Skip to content

Component Usage Guide

UI Primitives (components/ui)

Button

Standardized button component supporting variants and sizes.

import { Button } from '@/components/ui/button';

// Primary
<Button>Click Me</Button>

// Secondary
<Button variant="secondary">Cancel</Button>

// Ghost (for icons)
<Button variant="ghost" size="icon">
  <Icon />
</Button>

// Pill (for chips)
<Button variant="pill">Category</Button>

// Full width
<Button className="w-full">Submit</Button>

Variants:

  • default: Primary blue action.
  • destructive: Red/Warning action.
  • outline: Bordered, transparent background.
  • secondary: Light gray background.
  • ghost: Transparent, hover effect only.
  • link: Underlined text.
  • pill: Rounded chip style (white with shadow).

Sizes:

  • default: Standard padding.
  • sm: Smaller padding.
  • lg: Larger padding.
  • icon: Square, for icon-only buttons.
  • pill: Optimized for chip usage.

Feature Components

ServiceCard

Displays a service with score, match reasons, and trust signals.

import ServiceCard from "@/components/services/ServiceCard"
;<ServiceCard service={service} score={result.score} matchReasons={result.matchReasons} />

TrustPanel (v14.0)

Displays data provenance, verification status, and last verified dates.

import { TrustPanel } from "@/components/services/TrustPanel"
;<TrustPanel service={service} />

SimplifiedServiceView (v14.0)

Renders plain-language summaries and "How-to-use" step-by-step guides for higher literacy accessibility.

import { SimplifiedServiceView } from "@/components/services/SimplifiedServiceView"
;<SimplifiedServiceView serviceId={service.id} />

FeedbackWidget (v14.0)

Privacy-preserving feedback collection tool at the bottom of detail pages.

import { FeedbackWidget } from "@/components/feedback/FeedbackWidget"
;<FeedbackWidget serviceId={service.id} />

Includes integrated voice search capability.

import SearchBar from "@/components/home/SearchBar"
;<SearchBar query={query} setQuery={setQuery} placeholder="Search..." />

Sub-components:

  • VoiceSearchButton: Manages microphone state and local Whisper transcription.

ChatAssistant

On-device “smart search” assistant.

  • Uses a local LLM to rewrite/expand the user’s query (not shown to the user).
  • Runs the normal local search pipeline and renders deterministic service links (no free-form AI answers).
  • Enforces a client-side crisis circuit breaker that blocks the LLM and shows the emergency modal.
import ChatAssistant from "@/components/ai/ChatAssistant"

// Must be wrapped in ClientOnly due to WebGPU/WASM
;<ClientOnly>
  <ChatAssistant />
</ClientOnly>

Homepage Discovery Layer

The resting homepage discovery layer is composed of HomeStats, CategoryBrowseGrid, and HowItWorks.

  • HomeStats renders the semantic service/category/language metrics rail.
  • CategoryBrowseGrid provides category shortcuts and must call the existing category setter/search flow rather than introducing a separate navigation path.
  • HowItWorks explains the private-search to direct-contact flow with concise localized copy and card details; avoid reintroducing a separate trust-strip row for privacy/offline/language claims unless the homepage information architecture is revisited.

About Page Surfaces

The About page uses a single editorial content rail with the hero, integrated trust overview, boundaries surface, context cards, and final CTA aligned to the same grid.

  • AboutTrustOverview owns the source review, privacy/accessibility trust items, and "does / doesn't do" boundaries content.
  • Avoid reintroducing homepage metrics, duplicated trust-strip content, or separate stacked governance sections on /about.
  • The primary About CTAs use about-gradient-border-button only as a scoped page helper for the solid #6366f1 fill and white text treatment; keep the underlying Button sizing/elevation consistent with neighboring outline buttons.
  • Keep /about focused on trust, boundaries, source context, and governance context rather than marketing-style feature cards.

ServiceCardSkeleton

Loading placeholder for ServiceCard.

import ServiceCardSkeleton from "@/components/services/ServiceCardSkeleton"
;<ServiceCardSkeleton />

ErrorBoundary

Catches React errors and displays a fallback UI with error ID for support.

import { ErrorBoundary } from "@/components/error/ErrorBoundary"
;<ErrorBoundary
  fallback={<CustomErrorUI />}
  onError={(error, errorInfo, errorId) => {
    // Optional error reporting
  }}
>
  <App />
</ErrorBoundary>

ServiceEditForm (Partner-Focused)

New multi-lingual-aware form for service editing (EN/FR fields). Located in components/partner/ServiceEditForm.tsx.

import { ServiceEditForm } from "@/components/partner/ServiceEditForm"
;<ServiceEditForm
  service={serviceData}
  onSave={async (data) => {
    // Save logic
  }}
/>

UpdateRequestModal (Partner-Focused, v14.0)

Structured workflow for partners to request listing updates with justifications.

import { UpdateRequestModal } from "@/components/services/UpdateRequestModal"
;<UpdateRequestModal service={service} isOpen={isOpen} onClose={() => setIsOpen(false)} />

PartnerServiceList

Data table for displaying an organization's services on the dashboard.

import { PartnerServiceList } from "@/components/partner/PartnerServiceList"
;<PartnerServiceList partnerId={user.id} />

AnalyticsCard (Advanced)

Visualizes a single metric with trend indicator. Supports glassmorphism styling.

import { AnalyticsCard } from "@/components/dashboard/AnalyticsCard"
;<AnalyticsCard title="Total Views" value={1200} change={5.2} loading={false} />

VoiceSearchButton

See SearchBar section.

Provider Components

AuthProvider

Provides authentication context throughout the app.

import { AuthProvider, useAuth } from "@/components/layout/AuthProvider"

// Wrap app
;<AuthProvider>
  <App />
</AuthProvider>

// Use in components
const { user, signOut } = useAuth()

BetaBanner

Displays a beta warning banner at the top of the app.

import BetaBanner from "@/components/layout/BetaBanner"
;<BetaBanner />

ThemeProvider

Manages light/dark mode state using next-themes.

import { ThemeProvider } from "@/components/layout/ThemeProvider"
;<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
  <App />
</ThemeProvider>

DashboardSidebar

Navigation sidebar for partner dashboard.

import DashboardSidebar from "@/components/dashboard/DashboardSidebar"
;<DashboardSidebar />

ServiceDetailPage

Dedicated public route for service information.

// Route: /service/[id]
import ServiceDetailPage from "@/app/[locale]/service/[id]/page.tsx"

Layout Components

Global shell components.

import { Header } from "@/components/layout/Header"
import { Footer } from "@/components/layout/Footer"
import { ThemeToggle } from "@/components/layout/ThemeToggle"

Tooltip

Accessible tooltip component.

import { Tooltip } from "@/components/Tooltip"
;<Tooltip content="Helpful info">
  <button>Hover me</button>
</Tooltip>

### FreshnessBadge

Visual indicator of when service data was last verified.

```tsx
import { FreshnessBadge } from "@/components/ui/FreshnessBadge"

;<FreshnessBadge lastVerified="2024-01-01T00:00:00Z" />

PrintButton

Optimized button for printing search results. Automatically hidden during print.

import { PrintButton } from "@/components/ui/PrintButton"
;<PrintButton />