# kui-react v0.1.0 — Full component catalog

Generated 2026-07-10T16:33:24.767Z.

Machine-readable catalog of every component, theme, design token, and convention in the kui-react library. Consume this from an AI assistant to know what exists, where it lives, and how to use it.

## Layers
- **ui** — modules/ui/ — Primitive, locally-stateful components (atoms + molecules). No business logic. Every file starts with 'use client' and imports cn from @/libs/utils/cn.
- **app** — modules/app/ — Application-level patterns (organisms, page shells, forms, providers). May own local state and orchestrate ui-layer atoms.
- **domain** — modules/domains/<vertical>/ — Industry-vertical components that compose ui/ + app/. Each vertical exports a barrel index.ts and a types.ts with Zod schemas.
- **theme** — app/theme/<vertical>/ — Full multi-page demos wiring domain components into a realistic product experience. layout.tsx is client, page.tsx is server unless it owns state.
- **library** — External npm packages featured in the showcase (e.g. kui-viewer). filePath points to the showcase example, not first-party source; the `external` field carries homepage/npm/github links.

## Conventions
- **icons** — All icons MUST come from Font Awesome. Named imports only — never the whole set. Apply Tailwind classes via className (e.g. text-primary, w-4 h-4); never use the size prop with raw strings. aria-hidden="true" on decorative icons.
- **styling** — Tailwind CSS 4 with CSS-variable design tokens. Use cn() from @/libs/utils/cn for class composition — never raw template literals. Reference token names (bg-primary, text-text-secondary) — never hex.
- **types** — Define props inline with a local type. Domain layers use Zod schemas in types.ts. Components export named functions — never default exports (excluding next/dynamic wrappers).
- **accessibility** — Use semantic HTML. Apply aria-busy / aria-invalid / aria-describedby / aria-pressed / aria-expanded as relevant. ALWAYS include focus-visible:ring-2 focus-visible:ring-border-focus on interactive elements. Use disabled:opacity-50 disabled:cursor-not-allowed for disabled state.
- **fileNaming** — UI/Domain components: PascalCase .tsx. Showcase builders: kebab-case .showcase.tsx. Utilities: camelCase .ts. Domain directories: lowercase.
- **pathAlias** — @/ resolves to the project root. Import as: @/modules/ui/<Component>, @/modules/app/<Component>, @/modules/domains/<vertical>, @/libs/utils/cn.

## Design tokens
| Token | Light value | Purpose |
|---|---|---|
| `--primary` | `#3b82f6` | Primary actions |
| `--primary-hover` | `#2563eb` | Hover state |
| `--primary-active` | `#1d4ed8` | Active/pressed |
| `--primary-subtle` | `#eff6ff` | Tinted backgrounds |
| `--primary-fg` | `#ffffff` | Text on primary |
| `--secondary` | `#8b5cf6` | Secondary actions |
| `--surface-base` | `#ffffff` | Page background |
| `--surface-raised` | `#f9fafb` | Cards |
| `--surface-overlay` | `#f3f4f6` | Hover overlays |
| `--surface-sunken` | `#e5e7eb` | Inset areas |
| `--text-primary` | `#111827` | Body text |
| `--text-secondary` | `#6b7280` | Muted text |
| `--text-disabled` | `#9ca3af` | Disabled text |
| `--text-inverse` | `#ffffff` | Text on dark bg |
| `--border` | `#e5e7eb` | Default borders |
| `--border-strong` | `#d1d5db` | Emphasized borders |
| `--border-focus` | `#3b82f6` | Focus rings |
| `--success` | `#22c55e` | Success state |
| `--success-subtle` | `#f0fdf4` | Success background |
| `--success-fg` | `#14532d` | Text on success |
| `--warning` | `#f59e0b` | Warning state |
| `--warning-subtle` | `#fffbeb` | Warning background |
| `--error` | `#ef4444` | Error/danger state |
| `--error-subtle` | `#fef2f2` | Error background |
| `--info` | `#06b6d4` | Informational state |
| `--info-subtle` | `#ecfeff` | Info background |

## Components — app / App

### AppShell  (`app-shell`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/AppShell.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Full-screen layout wrapper with logo, sidebar and topbar slots. Sidebar renders as an aside on desktop and opens via a drawer on mobile.
- **Design tokens:** --border, --surface-base, --surface-raised

**Variants:**

*Sidebar + topbar + content*
```tsx
const [sidebarCollapsed, setSidebarCollapsed] = useState(false);

<AppShell
  logo={<span className="font-black text-primary">Acme</span>}
  compactLogo={<span className="font-black text-primary">A</span>}
  sidebarCollapsed={sidebarCollapsed}
  sidebar={
    <AppSidebar
      navGroups={navGroups}
      activeId={activeId}
      onSelect={setActiveId}
      collapsed={sidebarCollapsed}
      onCollapsedChange={setSidebarCollapsed}
      searchable
      footer={<Avatar name="Jane Doe" size="sm" status="online" />}
    />
  }
  topbar={
    <AppTopBar>
      <GlobalSearch onSearch={handleSearch} onSelect={handleSelect} className="flex-1 max-w-sm hidden sm:block" />
      <div className="ml-auto flex items-center gap-1">
        <Button variant="ghost" size="sm" iconOnly>🔔</Button>
        <UserMenu user={currentUser} />
      </div>
    </AppTopBar>
  }
>
  {/* page content */}
</AppShell>
```

*Sadece topbar (sidebar yok)*
```tsx
<AppShell
  topbar={
    <AppTopBar logo={<span className="font-bold text-primary">Acme</span>}>
      <div className="ml-auto flex items-center gap-2">
        <Button variant="primary" size="sm">New project</Button>
        <UserMenu user={currentUser} />
      </div>
    </AppTopBar>
  }
>
  {/* page content */}
</AppShell>
```

### AppSidebar  (`app-sidebar`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/AppSidebar.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Collapsible side navigation. Accepts navGroups or navItems with a built-in collapse toggle. The searchable prop adds an inline filter and a footer slot can host a user block or any content.
- **Design tokens:** --border, --border-focus, --primary, --primary-subtle, --secondary, --surface-overlay, --text-disabled, --text-primary, --text-secondary

**Variants:**

*Açık (grouped nav + footer)*
```tsx
<AppSidebar
  navGroups={[
    { label: 'Main',     items: mainItems },
    { label: 'Settings', items: settingsItems },
  ]}
  activeId={activeId}
  onSelect={setActiveId}
  footer={({ collapsed }) => (
    <div className={collapsed ? 'p-3 flex items-center justify-center' : 'p-3 flex items-center gap-2'}>
      <Avatar name="Jane Doe" size="sm" status="online" />
      {!collapsed && <p className="text-xs font-semibold">Jane Doe</p>}
    </div>
  )}
/>
```

*Arama filtreli*
```tsx
<AppSidebar
  navGroups={navGroups}
  activeId={activeId}
  onSelect={setActiveId}
  searchable
/>
```

*Daraltılmış (icon-only)*
```tsx
<AppSidebar
  navGroups={navGroups}
  activeId={activeId}
  onSelect={setActiveId}
  defaultCollapsed
/>
```

### AppTopBar  (`app-top-bar`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/AppTopBar.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Top bar wrapper passed into AppShell's header slot. The logo slot anchors the left side while children (GlobalSearch, UserMenu, Button, etc.) are arranged in a flex row.

**Variants:**

*Arama + actions + kullanıcı*
```tsx
<AppTopBar>
  <GlobalSearch
    onSearch={handleSearch}
    onSelect={handleSelect}
    className="flex-1 max-w-sm hidden sm:block"
  />
  <div className="ml-auto flex items-center gap-1">
    <Button variant="ghost" size="sm" iconOnly aria-label="Notifications">🔔</Button>
    <Button variant="ghost" size="sm" iconOnly aria-label="Settings">⚙️</Button>
    <UserMenu user={currentUser} />
  </div>
</AppTopBar>
```

*Logo + action + kullanıcı*
```tsx
<AppTopBar logo={<span className="font-black text-primary text-lg">Acme</span>}>
  <div className="ml-auto flex items-center gap-2">
    <Button variant="primary" size="sm">Upgrade</Button>
    <UserMenu user={currentUser} />
  </div>
</AppTopBar>
```

### AppNav  (`app-nav`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/AppNav.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Horizontal navigation bar. Renders inline links on desktop and a hamburger that opens a NavDrawer on mobile. Provides logo, navItems and actions slots.
- **Design tokens:** --border, --primary, --primary-subtle, --secondary, --surface-overlay, --surface-raised, --text-primary, --text-secondary

**Variants:**

*Marketing bar (logo + links + CTA)*
```tsx
<AppNav
  logo={<span className="font-bold text-primary">Acme</span>}
  navItems={[
    { label: 'Home',     href: '/', active: true },
    { label: 'Products', href: '/products' },
    { label: 'Pricing',  href: '/pricing' },
  ]}
>
  <Button variant="ghost" size="sm">Log in</Button>
  <Button variant="primary" size="sm">Sign up</Button>
</AppNav>
```

*App bar (links + UserMenu)*
```tsx
<AppNav
  logo={<span className="font-bold">Dashboard</span>}
  navItems={[
    { label: 'Overview', active: true },
    { label: 'Analytics' },
    { label: 'Reports' },
  ]}
>
  <UserMenu user={currentUser} />
</AppNav>
```

### NavDrawer  (`nav-drawer`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/NavDrawer.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Wrapper that wraps any trigger and children inside a drawer. Manages its own open/closed state. Used as AppNav's mobile menu and also works standalone.

**Variants:**

*Sol nav (standalone)*
```tsx
<NavDrawer
  title="Navigation"
  side="left"
  trigger={<Button variant="outline" iconLeft={<MenuIcon />}>Open menu</Button>}
  footer={<Button variant="ghost" size="sm" fullWidth>Sign out</Button>}
>
  <nav className="space-y-1 pt-1">
    <a href="/" className="block px-3 py-2.5 rounded-lg bg-primary-subtle text-primary text-sm">Home</a>
    <a href="/products" className="block px-3 py-2.5 rounded-lg text-text-primary hover:bg-surface-overlay text-sm">Products</a>
  </nav>
</NavDrawer>
```

*Sağ drawer (cart panel)*
```tsx
<NavDrawer
  title="Cart"
  side="right"
  trigger={<Button variant="outline">🛒 Cart (3)</Button>}
>
  {cartItems.map((item) => (
    <div key={item.id} className="flex justify-between text-sm py-2">
      <span>{item.name}</span><span>{item.price}</span>
    </div>
  ))}
  <Button variant="primary" fullWidth>Checkout</Button>
</NavDrawer>
```

### UserMenu  (`user-menu`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/UserMenu.tsx`
- **Status:** stable (since 2025-03)
- **Description:** User dropdown opened by a trigger showing avatar, name and role. Accepts a SafeUser prop; the dropdown header shows the name and email.
- **Design tokens:** --border, --border-focus, --primary, --secondary, --surface-overlay, --text-disabled, --text-primary, --text-secondary

**Variants:**

*Varsayılan (isim + e-posta + rol)*
```tsx
<UserMenu
  user={{
    userId: 'u1',
    email: 'jane@acme.com',
    userRole: 'Admin',
    userStatus: 'ACTIVE',
    userPreferences: null,
    userProfile: { name: 'Jane Doe', profilePicture: null },
  }}
/>
```

*Özel items*
```tsx
<UserMenu
  user={currentUser}
  items={[
    { label: 'View Profile',  icon: '👤', onClick: () => {} },
    { label: 'Billing',       icon: '💳', onClick: () => {} },
    { type: 'separator' },
    { label: 'Sign out',      icon: '↩️', danger: true, onClick: () => {} },
  ]}
/>
```

### GlobalSearch  (`global-search`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/GlobalSearch.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Command-palette-style global search field. Supports a categorised result list, keyboard navigation and result selection.

**Variants:**

*Interactive results*
```tsx
<GlobalSearch
  placeholder="Search pages and actions…"
  results={results}
  onSearch={handleSearch}
  onSelect={(result) => setSelected(result.label)}
/>
```

*Loading state*
```tsx
<GlobalSearch loading results={results} onSearch={handleSearch} onSelect={handleSelect} />
```

### AppCommandBar  (`app-command-bar`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/CommandPalette/index.tsx`
- **Status:** beta (since 2025-04)
- **Description:** Keyboard-first command palette. Opens with ⌘K; an items prop accepts custom commands while a default navigation/actions/recent set is included.

**Variants:**

*Varsayılan komutlar*
```tsx
<AppCommandBar onSelect={(item) => console.log(item.label)} />
```

*Özel items + trigger*
```tsx
<AppCommandBar
  items={customItems}
  trigger={<Button variant="ghost" size="sm" iconRight={<Badge variant="neutral" size="sm">⌘K</Badge>}>Search…</Button>}
  onSelect={handleSelect}
/>
```

*Fuzzy search + özel gruplar*
```tsx
// Try typing "kbd", "asgn" or "rls" to exercise the subsequence matcher.
const fuzzyItems = [
  { icon: '⌨️', label: 'Open Keyboard Shortcuts',  shortcut: '?',   category: 'Help',        keywords: ['kbd'] },
  { icon: '📚', label: 'Browse Documentation',     shortcut: 'G H', category: 'Help' },
  { icon: '🔔', label: 'Notification Preferences', shortcut: 'G N', category: 'Preferences' },
  { icon: '🛠️', label: 'Assign Reviewer to PR-42', shortcut: 'A R', category: 'Workflows',   keywords: ['asgn'] },
  { icon: '🚀', label: 'Release & Tag v1.4.0',     shortcut: 'R T', category: 'Workflows',   keywords: ['rls'] },
];

<AppCommandBar items={fuzzyItems} />
```

### SectionCard  (`section-card`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/SectionCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Titled content card with rounded-xl + border + bg-surface-raised + p-6. Header is separated by an underline; children slot accepts arbitrary content.

**Variants:**

*Tek bölüm*
```tsx
<SectionCard title="Preferences">
  <Input id="name" label="Display name" value={name} onChange={...} />
  <Toggle id="notify" label="Email notifications" checked={notify} onChange={setNotify} />
</SectionCard>
```

*Birden fazla bölüm*
```tsx
<SectionCard title="Profile">
  <UserProfileForm ... />
</SectionCard>
<SectionCard title="Security">
  <ChangePasswordForm ... />
</SectionCard>
```

### InlineAlert  (`inline-alert`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/InlineAlert.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Compact inline alert strip used next to form fields or inside cards. success / error / warning / info variants; icon + single-line message.

**Variants:**

*Tüm variantlar*
```tsx
<InlineAlert variant="success" message="Changes saved successfully." />
<InlineAlert variant="error"   message="Something went wrong." />
<InlineAlert variant="warning" message="Please review before saving." />
<InlineAlert variant="info"    message="This action cannot be undone." />
```

### StepShell  (`step-shell`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/StepShell.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Wrapper card for a single step in a multi-step flow. Border and number circle change based on active / done / inactive state; the done + onEdit combination shows an Edit button alongside the summary.

**Variants:**

*Active / Done / Pending*
```tsx
<StepShell number={1} title="Delivery address" active={false} done
  summary={<AddressCard address={address} />}
  onEdit={() => setStep('address')}
/>
<StepShell number={2} title="Payment method" active done={false}>
  <PaymentMethodSelector value={method} onChange={setMethod} />
  <Button onClick={() => setStep('details')}>Continue</Button>
</StepShell>
<StepShell number={3} title="Review &amp; pay" active={false} done={false} />
```

### Form  (`form`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/Form.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Form layout wrapper with title, description, error and actions slots. `columns` prop renders fields in a 1 or 2 column grid.
- **Design tokens:** --border, --primary, --secondary, --text-primary, --text-secondary

**Variants:**

*Single column*
```tsx
<Form
  title="Create project"
  description="Fill in the details to create a new project."
  onSubmit={handleSubmit}
  actions={
    <>
      <Button variant="outline" type="button" onClick={handleCancel}>Cancel</Button>
      <Button variant="primary" type="submit">Save project</Button>
    </>
  }
>
  <Input id="name" label="Project name" required value={name} onChange={...} error={nameError} />
  <Input id="email" label="Owner email" type="email" required value={email} onChange={...} />
  <Select id="visibility" label="Visibility" value={visibility} onChange={...} options={options} />
  <Toggle id="notify" label="Send notifications" checked={notify} onChange={setNotify} />
</Form>
```

*Two column*
```tsx
<Form title="Create project" columns={2} onSubmit={handleSubmit} actions={<Button type="submit">Save</Button>}>
  <Input id="name" label="Project name" required value={name} onChange={...} />
  <Input id="email" label="Owner email" type="email" value={email} onChange={...} />
  <Select id="visibility" label="Visibility" value={visibility} onChange={...} options={options} />
  <MultiSelect id="stack" label="Tech stack" value={stack} onChange={setStack} options={options} />
  <div className="sm:col-span-2">
    <Textarea id="description" label="Description" value={description} onChange={...} />
  </div>
</Form>
```

### FilterBar  (`filter-bar`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/FilterBar.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Select, multiselect, daterange and text-based filter panel. Supports URL-based filtering via GET form submit.

**Variants:**

*Full filter set*
```tsx
<FilterBar fields={fields} values={values} onChange={handleChange} onApply={handleApply} onReset={handleReset} />
```

*Compact filters*
```tsx
<FilterBar fields={fields.slice(0, 2)} values={values} onChange={handleChange} />
```

### FileUploadSection  (`file-upload-section`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/FileUploadSection/index.tsx`
- **Status:** stable (since 2026-05)
- **Description:** High-level upload organism: drop zone + file list + remove. M1 implements drag/drop, paste-from-clipboard, accept-pattern + maxSize + maxFiles validation. M2 will add image thumbnails + crop dialog; M3 chunked + resumable uploads. Pixel-identical EJS sibling at modules/app/FileUploadSection/FileUploadSection.ejs.

**Variants:**

*Basic drop zone*
```tsx
<FileUploadSection title="Project attachments" hint="PDF, images up to 5 MB each"
  multiple accept="image/*,.pdf" maxSizeBytes={5242880} />
```

*Paste from clipboard*
```tsx
<FileUploadSection title="Bug report screenshots" multiple enablePaste
  accept="image/*" maxFiles={5} maxSizeBytes={4 * 1024 * 1024}
  hint="Drop, browse, or paste (Cmd/Ctrl + V while focused)" />
```

### OnboardingWizard  (`onboarding-wizard`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/OnboardingWizard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Multi-step onboarding flow with dots/bar progress, optional skip, and page or modal presentation. Each step renders its own content slot.
- **Composes:** button, modal
- **Related to:** step-flow, step-shell
- **Design tokens:** --primary, --surface-sunken, --text-primary, --text-secondary, --border
- **A11y:** WCAG AA · ARIA: role="progressbar" · Keys: Enter / Click → Activate Next / Previous / Skip / Complete · Progress is announced via role="progressbar" with aria-valuenow updating on step change.

**Variants:**

*Dots indicator (page mode)*
```tsx
<OnboardingWizard
  steps={steps}
  indicator="dots"
  allowSkip
  onComplete={() => {}}
/>
```

*Progress bar indicator*
```tsx
<OnboardingWizard
  steps={steps}
  indicator="bar"
  allowSkip={false}
  onComplete={() => {}}
/>
```

### DetailHeader  (`detail-header`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/DetailHeader.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Page header for detail/record views: title, subtitle, status badge, action buttons, and optional tab navigation.

**Variants:**

*With actions, no tabs*
```tsx
<DetailHeader
  title="Invoice #1042"
  subtitle="Created 3 days ago by Jane Doe"
  status="Pending"
  statusVariant="warning"
>
  <Button variant="outline" size="sm">Edit</Button>
  <Button variant="primary" size="sm">Approve</Button>
</DetailHeader>
```

*With tabs*
```tsx
<DetailHeader
  title="Order #8821"
  subtitle="Last updated 2 hours ago"
  status="Shipped"
  statusVariant="success"
  tabs={[
    { value: 'overview', label: 'Overview' },
    { value: 'items',    label: 'Items'    },
    { value: 'history',  label: 'History'  },
    { value: 'notes',    label: 'Notes', disabled: true },
  ]}
  defaultTab="overview"
>
  <Button variant="ghost" size="sm">Print</Button>
  <Button variant="primary" size="sm">Track</Button>
</DetailHeader>
```

### ErrorState  (`error-state`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/EmptyErrorState.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Error state pairing an inline alert banner with a centered empty state. Optional retry action.

**Variants:**

*Default*
```tsx
<ErrorState
  title="Something went wrong"
  message="Failed to load user data. Please check your connection."
/>
```

*With retry*
```tsx
<ErrorState
  title="Database connection failed"
  message="Could not connect to the database. Please try again."
  onRetry={handleRetry}
  retryLabel="Try again"
/>
```

### NotFoundState  (`not-found-state`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/EmptyErrorState.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Not-found / empty record state with optional go-back action.

**Variants:**

*Default*
```tsx
<NotFoundState />
```

*With back link*
```tsx
<NotFoundState
  title="User not found"
  description="This user account doesn't exist or may have been deleted."
  onGoBack={() => router.back()}
  goBackLabel="Back to users"
/>
```

### LoadingState  (`loading-state`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/LoadingState.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Skeleton loading animations. Variants: spinner / table / cards / list / detail / form.

**Variants:**

*Spinner*
```tsx
<LoadingState variant="spinner" />
```

*Table skeleton*
```tsx
<LoadingState variant="table" rows={5} cols={4} />
```

*Cards skeleton*
```tsx
<LoadingState variant="cards" cards={3} />
```

*List skeleton*
```tsx
<LoadingState variant="list" rows={4} />
```

*Form skeleton*
```tsx
<LoadingState variant="form" rows={3} />
```

### SplashScreen  (`splash-screen`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/SplashScreen.tsx`
- **Status:** beta (since 2025-05)
- **Description:** Full-screen overlay shown during app initialisation. Accepts a logo slot, optional progress bar, and fades out when visible=false.
- **Design tokens:** --primary

**Variants:**

*Logo + message + progress*
```tsx
<SplashScreen
  visible={true}
  logo={<span className="text-4xl font-black text-primary">Acme</span>}
  message="Loading your workspace…"
  progress={65}
/>
```

*Spinner only (no logo)*
```tsx
<SplashScreen visible={true} message="Please wait…" />
```

*Interactive fade-out*
```tsx
const [visible, setVisible] = useState(true);

<SplashScreen
  visible={visible}
  logo={<span className="text-4xl font-black text-primary">Acme</span>}
  message="Starting up…"
/>
<Button onClick={() => setVisible(false)}>Dismiss</Button>
```

### MaintenancePage  (`maintenance-page`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/MaintenancePage.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Full-page maintenance screen. Optional ETA countdown badge and external status-page link. Use for planned downtime or unplanned outages.
- **Composes:** badge
- **Design tokens:** --warning, --primary, --surface-base, --text-primary, --text-secondary
- **A11y:** WCAG AA · ARIA: role="status", aria-live="polite" · Screen reader announces the maintenance state via the live region; countdown updates without re-announcing.

**Variants:**

*Plain (no ETA)*
```tsx
<MaintenancePage
  title="System Maintenance"
  description="We're performing a short maintenance."
/>
```

*With ETA + status link*
```tsx
<MaintenancePage
  title="System Maintenance"
  description="We're shipping new features."
  eta={new Date(Date.now() + 45 * 60 * 1000)}
  statusUrl="https://status.example.com"
  statusLabel="Status Page"
/>
```

### AppBreadcrumbs  (`app-breadcrumbs`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/AppBreadcrumbs.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Page header with breadcrumb trail, title, description, and optional status badge. Collapses to a Breadcrumb + dropdown menu on mobile for deep paths.

**Variants:**

*With title + badge*
```tsx
<AppBreadcrumbs
  title="Project Atlas"
  description="Internal tooling for the design system team"
  items={[
    { label: 'Workspace', href: '/' },
    { label: 'Projects',  href: '/projects' },
    { label: 'Atlas' },
  ]}
  badge={<Badge variant="info" size="sm">Beta</Badge>}
/>
```

*Deep path*
```tsx
<AppBreadcrumbs
  title="invoice-2026-05-001.pdf"
  items={[
    { label: 'Home',     href: '/' },
    { label: 'Accounts', href: '/accounts' },
    { label: 'Acme Inc', href: '/accounts/acme' },
    { label: 'Invoices', href: '/accounts/acme/invoices' },
    { label: '2026-05',  href: '/accounts/acme/invoices/2026-05' },
    { label: 'invoice-2026-05-001.pdf' },
  ]}
/>
```

### AppFooter  (`app-footer`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/AppFooter.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Two-row application footer with logo, navigation links, system status badge, version, copyright, and social slot.

**Variants:**

*Operational, with nav + version*
```tsx
<AppFooter
  logo={<><BrandLogo size="sm">K</BrandLogo><span>KUIreact</span></>}
  nav={<><a href="#">Docs</a><a href="#">Pricing</a><a href="#">Status</a></>}
  version="0.2.0"
  status="operational"
  copyright="© 2026 KUIreact"
/>
```

### ThemeSwitcher  (`theme-switcher`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/ThemeSwitcher.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Tri-state theme selector (light / dark / system). Persists the choice to localStorage and toggles the .dark class on <html>. Mounts safely on the server with a placeholder until hydrated.

**Variants:**

*Default*
```tsx
<ThemeSwitcher />
```

### ContextMenu  (`context-menu`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/ContextMenu.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Right-click context menu. Wraps any element as a trigger. Supports item groups, keyboard shortcuts, separators, danger items, and disabled items. Positions itself via viewport-aware boundary detection, auto-flips when near screen edges. Full keyboard navigation: ↑↓ arrows, Enter, Escape.

**Variants:**

*Text editor — clipboard + format actions*
```tsx
<ContextMenu items={[
  { label: 'Cut',      icon: <Icon />, shortcut: '⌘X' },
  { label: 'Copy',     icon: <Icon />, shortcut: '⌘C' },
  { label: 'Paste',    icon: <Icon />, shortcut: '⌘V' },
  { type: 'separator' },
  { label: 'Copy link',icon: <Icon />, shortcut: '⌘⇧C' },
  { type: 'separator' },
  { label: 'Rename',   icon: <Icon /> },
  { label: 'Delete',   icon: <Icon />, danger: true, shortcut: '⌫' },
]}>
  <div>Right-click anywhere in this area</div>
</ContextMenu>
```

*File manager — groups + shortcut hint*
```tsx
<ContextMenu items={[
  { type: 'group', label: 'Actions' },
  { label: 'Open',     icon: <Icon /> },
  { label: 'Download', icon: <Icon />, shortcut: '⌘D' },
  { label: 'Share',    icon: <Icon />, shortcut: '⌘⇧S' },
  { type: 'separator' },
  { type: 'group', label: 'Organise' },
  { label: 'Move to…', icon: <Icon /> },
  { label: 'Add tag',  icon: <Icon /> },
  { type: 'separator' },
  { label: 'Delete', icon: <Icon />, danger: true },
]}>
  <FileCard name="Report Q1.pdf" />
</ContextMenu>
```

*Code branch — some items disabled*
```tsx
<ContextMenu items={[
  { label: 'View diff',        icon: <Icon /> },
  { label: 'Copy branch name', icon: <Icon />, shortcut: '⌘C' },
  { type: 'separator' },
  { label: 'Merge into main',  icon: <Icon />, disabled: true },
  { label: 'Cherry-pick',                      disabled: true },
  { type: 'separator' },
  { label: 'Delete branch',    icon: <Icon />, danger: true },
]}>
  <BranchRow name="feature/context-menu" />
</ContextMenu>
```

### ShareDialog  (`share-dialog`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/ShareDialog.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Share modal: copyable link, email invitation with permission picker, and a list of current invitees with permission/remove controls.
- **Composes:** modal, avatar, button
- **Design tokens:** --primary, --surface-base, --surface-raised, --border, --text-primary, --text-secondary
- **A11y:** WCAG AA · ARIA: role="dialog", aria-modal="true", aria-labelledby, aria-describedby · Keys: Escape → Close dialog; Tab → Cycle focus among interactive controls

**Variants:**

*With invitees*
```tsx
<ShareDialog
  open
  onClose={() => {}}
  shareUrl="https://app.example.com/docs/x4y9"
  invitees={[
    { id: '1', name: 'Alice Brooks',  email: 'alice@example.com', permission: 'owner' },
    { id: '2', name: 'Marcus Reed',   email: 'marcus@example.com', permission: 'editor' },
  ]}
/>
```

*Empty / link only*
```tsx
<ShareDialog
  open
  onClose={() => {}}
  shareUrl="https://app.example.com/docs/x4y9"
  invitees={[]}
/>
```

### CommentThread  (`comment-thread`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/CommentThread.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Generic threaded comments with replies, like counts, delete-own actions, and a composer. Domain-agnostic — pass comments + handlers.
- **Composes:** avatar, button
- **Design tokens:** --surface-overlay, --surface-base, --border, --text-primary, --text-secondary, --text-disabled, --primary
- **A11y:** WCAG AA · ARIA: aria-label="Comments", aria-pressed (like), aria-expanded (reply)

**Variants:**

*With replies*
```tsx
<CommentThread comments={comments} currentUserId="me" onReply={addComment} onLike={toggle} onDelete={remove} />
```

*Empty state*
```tsx
<CommentThread comments={[]} onReply={addComment} />
```

### MentionPicker  (`mention-picker`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/MentionPicker.tsx`
- **Status:** stable (since 2026-05)
- **Description:** @-trigger autocomplete picker. Headless: takes users + query + position, fires onSelect. Keyboard nav (ArrowUp/Down, Enter/Tab, Escape).
- **Composes:** avatar
- **Design tokens:** --surface-raised, --surface-overlay, --border, --text-primary, --text-secondary, --text-disabled
- **A11y:** WCAG AA · ARIA: role="listbox", role="option", aria-selected · Keys: ArrowDown / ArrowUp → Move selection; Enter / Tab → Insert highlighted mention; Escape → Cancel picker

**Variants:**

*Filtered list*
```tsx
<MentionPicker users={users} query="ay" onSelect={(u) => {}} onCancel={() => {}} />
```

*Empty results*
```tsx
<MentionPicker users={users} query="zzz" onSelect={(u) => {}} onCancel={() => {}} />
```

### RichTextEditor  (`rich-text-editor`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/RichTextEditor/index.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Quill 2.x WYSIWYG editor with token-tinted snow theme. Production features: controlled value, imperative ref API, onBlur, name+hidden-form-sync, drag-and-drop image upload with onImageUpload callback, paste sanitization (Word / GDocs cleanup), char + word counter with maxLength, autosave to localStorage, markdown shortcuts, color + highlight, sub/sup, indent/outdent, horizontal rule, tables, emoji picker, @-mentions, /-slash command menu, selection bubble menu, image resize/align overlay, fullscreen mode. Pixel-identical EJS sibling at modules/app/RichTextEditor.ejs.
- **Composes:** modal, input, button
- **Design tokens:** --surface-base, --surface-sunken, --surface-raised, --surface-overlay, --text-primary, --text-secondary, --text-disabled, --border, --border-focus, --primary, --primary-subtle, --error
- **Dependencies:** quill
- **A11y:** WCAG AA · ARIA: textbox, toolbar, dialog, listbox · Keys: Ctrl/Cmd + B → Bold selection; Ctrl/Cmd + I → Italic selection; Ctrl/Cmd + U → Underline selection; Ctrl/Cmd + Z → Undo; Ctrl/Cmd + Shift + Z → Redo; Tab / Shift+Tab → Indent / outdent in lists; @ → Open mention suggestions; / → Open slash-command menu (at line start); ** ** / * * / ` ` → Markdown bold / italic / code; # / ## / ### → Markdown headings; - / * / 1. → Markdown bullet / numbered list; >  → Markdown blockquote

**Variants:**

*Empty + counter*
```tsx
const [body, setBody] = useState('');
<RichTextEditor
  id="article-body"
  label="Article body"
  value={body}
  onChange={setBody}
  showCounter
  showWordCount
/>
```

*Pre-populated*
```tsx
<RichTextEditor
  id="release-notes"
  label="Release notes"
  defaultValue={initial}
  onChange={setBody}
/>
```

*Read-only*
```tsx
<RichTextEditor
  id="archived"
  defaultValue={savedHtml}
  readOnly
/>
```

*Max length (200 chars)*
```tsx
<RichTextEditor
  id="short-summary"
  maxLength={200}
  showCounter
/>
```

*Mentions + slash commands*
```tsx
<RichTextEditor
  id="comment"
  mentions={[
    { id: 'u1', label: 'Jane Doe', description: 'Designer' },
    { id: 'u2', label: 'John Smith', description: 'Engineer' },
  ]}
  slashItems={[
    { id: 'h1', label: 'Heading 1', action: (q) => q.format('header', 1, 'user') },
    { id: 'list', label: 'Bullet list', action: (q) => q.format('list', 'bullet', 'user') },
  ]}
/>
```

*Imperative ref API*
```tsx
const ref = useRef<RichTextEditorHandle>(null);
<RichTextEditor ref={ref} id="reply" />
ref.current?.focus();
ref.current?.clear();
ref.current?.insertHTML('<p>Hi!</p>');
const text = ref.current?.getText();
```

*Form integration*
```tsx
<form action="/api/post" method="post">
  <RichTextEditor id="post" name="body" defaultValue={savedHtml} />
  <button type="submit">Save</button>
</form>
```

*Autosave*
```tsx
<RichTextEditor
  id="draft"
  autosaveKey="my-draft"
  placeholder="Survives page refresh…"
/>
```

### KanbanBoard  (`kanban-board`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/KanbanBoard/index.tsx`
- **Status:** beta (since 2026-05)
- **Description:** Trello / Linear-style kanban board. M1 ships HTML5-native drag and drop between columns with an inline drop-position indicator (thin line between cards) and full optimistic-UI rewind on rejected onCardMove. Use the canMove hook to gate transitions client-side, or throw from onCardMove to revert. Future milestones: column reorder + collapse + WIP limits (M2), swimlanes + filters + search (M3), inline edit + bulk select + card detail panel (M4), keyboard nav + ARIA announcements (M5), virtualization + auto-archive + dependencies (M6). Pixel-identical EJS sibling at modules/app/KanbanBoard/KanbanBoard.ejs.
- **Composes:** badge, avatar
- **Design tokens:** --surface-base, --surface-raised, --surface-overlay, --text-primary, --text-secondary, --text-disabled, --border, --border-strong, --border-focus, --primary, --primary-subtle, --info-subtle, --warning-subtle, --error-subtle, --success-subtle
- **A11y:** WCAG AA · ARIA: region, list, listitem, application · Keys: Tab → Move focus across cards / columns; Drag (mouse) → Pick up a card and drop on any column slot · M1 uses HTML5 drag-and-drop; each column is role="region" with aria-label, the list is role="list", cards are role="listitem". aria-grabbed (deprecated but still announced by some screen readers) flips on the active card; aria-dropeffect="move" is set on all columns while a drag is in flight. Full keyboard parity ships in M5.

**Variants:**

*Three columns (basic)*
```tsx
const columns = [
  { id: 'todo',  title: 'To Do' },
  { id: 'doing', title: 'In Progress' },
  { id: 'done',  title: 'Done' },
];
const [cards, setCards] = useState(initialCards);
<KanbanBoard
  columns={columns}
  cards={cards}
  onCardMove={(card, from, to) =>
    setCards((prev) =>
      prev.map((c) => (c.id === card.id ? { ...c, columnId: to } : c)),
    )
  }
/>
```

*canMove validation (no exit from Done)*
```tsx
<KanbanBoard
  columns={columns}
  cards={cards}
  canMove={(card, from, to) => from !== 'done' || to === 'done'}
  onCardMove={persist}
/>
```

*Async onCardMove with rollback*
```tsx
<KanbanBoard
  columns={columns}
  cards={cards}
  onCardMove={async (card, from, to) => {
    const res = await fetch('/api/move', { method: 'POST', body: JSON.stringify({ card, to }) });
    // Throw to revert the optimistic update.
    if (!res.ok) throw new Error('Server rejected');
    setCards(next);
  }}
/>
```

### Calendar  (`calendar`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/Calendar/index.tsx`
- **Status:** beta (since 2026-05)
- **Description:** Month / week / day / agenda / resource calendar with view switcher, full keyboard nav (PageUp/Down + T + arrow keys for day-step), per-event color and icon, all-day bars + timed pills, TR/EN locales, full interactions (anchored popover, drag-move, edge-resize, drag-create), in-house RRULE expansion (FREQ/INTERVAL/COUNT/UNTIL/BYDAY + exceptions), multi-calendar overlay with per-calendar visibility legend, ResourceView lanes with O(n²) conflict highlighting, agenda list (search + date grouping) and a composable MiniCalendar sidebar. WAI-ARIA grid pattern with live-region nav announcements ("Showing May 2026") and event-count cell labels ("Tuesday May 12, 3 events"). Optional Intl.DateTimeFormat-based time formatting for locale-aware clocks.
- **Design tokens:** --primary, --primary-fg, --success, --success-fg, --warning, --error, --info, --secondary, --surface-base, --surface-raised, --surface-overlay, --border, --border-focus, --text-primary, --text-secondary, --text-disabled
- **A11y:** WCAG AA · ARIA: Grid (month), Tablist (view switcher), Region (week/day), Live region (nav announcements), Dialog (event popover) · Keys: Page Up → Previous period (month / week / day); Page Down → Next period (month / week / day); T → Jump to today; Arrow Left → Step back one day; Arrow Right → Step forward one day; Arrow Up → Step back one week; Arrow Down → Step forward one week; Escape → Close popover / cancel drag in progress; Tab → Focus the next interactive element (events, nav buttons, legend chips) · Month view uses role="grid" with role="gridcell" per day. Cells announce "Tuesday May 12, 3 events" via aria-label. View switcher uses role="tablist". Legend chips use role="switch". Nav changes push a polite live-region message ("Showing May 2026"). Drag is direct manipulation (no animated motion), so prefers-reduced-motion is a no-op for the calendar.

**Variants:**

*Month view — Türkçe*
```tsx
<Calendar
  events={events}
  view="month"
  defaultDate={new Date(2026, 4, 13)}
  onViewChange={setView}
  locale="tr"
/>
```

*Week view — working hours shading*
```tsx
<Calendar
  events={events}
  view="week"
  defaultDate={new Date(2026, 4, 13)}
  onViewChange={setView}
  locale="tr"
  workingHours={{ start: 9, end: 18, days: [1,2,3,4,5] }}
/>
```

*Day view — English*
```tsx
<Calendar
  events={events}
  view="day"
  defaultDate={new Date(2026, 4, 13)}
  onViewChange={setView}
  locale="en"
  workingHours={{ start: 9, end: 18, days: [1,2,3,4,5] }}
/>
```

*Recurring — RRULE expansion*
```tsx
// Lazy in-house RRULE expander — FREQ + INTERVAL + COUNT + UNTIL + BYDAY.
const events: Event[] = [
  {
    id: 'standup',
    title: 'Daily standup',
    start: new Date(2026, 4, 11, 9, 30),
    end:   new Date(2026, 4, 11, 9, 45),
    rrule: 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=20',
    exceptions: [new Date(2026, 4, 13)], // skip team off-site
  },
  {
    id: 'coffee',
    title: 'Coffee with Ada',
    start: new Date(2026, 4, 12, 8, 30),
    end:   new Date(2026, 4, 12, 9, 0),
    rrule: 'FREQ=WEEKLY;INTERVAL=2;BYDAY=TU;COUNT=5',
  },
];

<Calendar
  events={events}
  view="week"
  defaultDate={new Date(2026, 4, 13)}
  slotMinutes={15}
  workingHours={{ start: 9, end: 18, days: [1, 2, 3, 4, 5] }}
/>
```

*Interactive — drag, resize, popover*
```tsx
<Calendar
  events={events}
  view="week"
  defaultDate={new Date(2026, 4, 13)}
  slotMinutes={30}
  workingHours={{ start: 9, end: 18, days: [1, 2, 3, 4, 5] }}
  onEventCreate={({ start, end }) =>
    setEvents((prev) => [...prev, { id: `n${Date.now()}`, title: 'New event', start, end }])
  }
  onEventUpdate={(updated) =>
    setEvents((prev) => prev.map((e) => (e.id === updated.id ? updated : e)))
  }
  onEventDelete={(id) =>
    setEvents((prev) => prev.filter((e) => e.id !== id))
  }
/>
```

*Resource view — rooms with conflict highlight*
```tsx
const resources = [
  { id: 'room-a', name: 'Studio A',  color: 'primary' },
  { id: 'room-b', name: 'Studio B',  color: 'success' },
  { id: 'room-c', name: 'Boardroom', color: 'warning' },
];
const events = [
  { id: 'r1', title: 'Sprint planning',
    start: new Date(2026, 4, 13,  9, 0), end: new Date(2026, 4, 13, 11, 0),
    resourceId: 'room-a' },
  { id: 'r2', title: 'Design crit',  // overlaps r1 → ring-error
    start: new Date(2026, 4, 13, 10, 30), end: new Date(2026, 4, 13, 12, 0),
    resourceId: 'room-a' },
  // …
];

<Calendar
  events={events}
  view="resource"
  defaultDate={new Date(2026, 4, 13)}
  resources={resources}
  slotMinutes={15}
  workingHours={{ start: 9, end: 18, days: [1, 2, 3, 4, 5] }}
/>
```

*Multi-calendar overlay — toggle visibility*
```tsx
const calendars = [
  { id: 'work',     name: 'Work',     color: 'primary' },
  { id: 'personal', name: 'Personal', color: 'success' },
  { id: 'family',   name: 'Family',   color: 'warning' },
];
const events = [
  { id: 'm1', title: 'Design sync',     start: ..., end: ..., calendarId: 'work' },
  { id: 'm2', title: 'Yoga',            start: ..., end: ..., calendarId: 'personal' },
  { id: 'm3', title: 'Dinner — parents', start: ..., end: ..., calendarId: 'family' },
];

<Calendar
  events={events}
  view="week"
  calendars={calendars}
  onCalendarToggle={(id, visible) => console.log(id, visible)}
/>
```

*Agenda view — date-grouped + search*
```tsx
<Calendar
  events={events}
  view="agenda"
  defaultDate={new Date(2026, 4, 13)}
  onViewChange={setView}
  locale="en"
/>
```

*MiniCalendar sidebar — jumps the main view to picked date*
```tsx
import { Calendar, MiniCalendar } from '@/modules/app/Calendar';

const [date, setDate] = useState(new Date(2026, 4, 13));
const [view, setView] = useState<View>('week');

<div className="grid grid-cols-[15rem_1fr] gap-3">
  <MiniCalendar
    value={date}
    onChange={(d) => { setDate(d); setView('day'); }}
    locale="en"
  />
  <Calendar
    events={events}
    view={view}
    defaultDate={date}
    onViewChange={setView}
    onDateChange={setDate}
  />
</div>
```

### Gantt  (`gantt`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/Gantt/index.tsx`
- **Status:** beta (since 2026-05)
- **Description:** MS Project / GanttPRO / dhtmlxGantt-style project timeline. M1 ships the scale switcher (day / week / month / quarter / year), a vertical Today line, WBS tree with expand/collapse on the left panel, sticky timeline header with synchronised horizontal + vertical scroll, and absolutely-positioned task bars with a %-progress fill. M2 adds full interactivity: drag a bar to reschedule (snap to day), drag the left/right edges to resize, drag the white progress thumb to change %, and drag from the right-edge blue dot to another bar to draw an FS dependency. Dependencies render as orthogonal SVG arrows with a marker-end arrowhead; click an arrow then press Delete to remove it. M3 adds a Critical Path toggle in the toolbar — tasks on the longest dependency chain switch to var(--error) styling and their connecting arrows turn red, computed by a forward + backward longest-path pass on the dependency DAG. Hovering a bar after a short delay shows a tooltip with name, start/end, duration, owner, % complete, predecessors, and a Critical badge. M4 adds zero-duration milestones rendered as 14×14 diamonds, planned-vs-actual baseline ghost bars beneath the live bars, and weekend + holiday shading on the day + week scales. M5 adds a toolbar Export menu (PNG via SVG `<foreignObject>` round-trip, PDF via the browser print dialog, CSV via a pure-JS Blob download), drag snap that nudges drops forward to the next working day, and a resource-conflict detector that flags over-allocated owners in the WBS panel with a red triangle. M6 closes the loop with grid keyboard navigation (↑↓/Home/End/PageUp/PageDown between rows, +/− zoom, focused bar exposes a focus ring + `aria-activedescendant`), a `locale` prop that drives Intl-based month names and tooltip dates, `prefers-reduced-motion` honouring (plus a `reducedMotion` prop force-on), and automatic row virtualization above ~60 tasks. All mutations are optimistic and roll back automatically if `onTaskUpdate` / `onDependencyCreate` rejects. Internal state is owned by a per-instance Zustand store (`store.ts`).
- **Composes:** button
- **Design tokens:** --surface-base, --surface-raised, --surface-overlay, --text-primary, --text-secondary, --border, --border-focus, --primary, --primary-subtle, --primary-fg, --warning, --error, --error-subtle
- **A11y:** WCAG AA · ARIA: grid, row, columnheader, gridcell, tablist, tab · Keys: Tab → Move focus across scale tabs, collapse buttons, and dependency arrows; Space / Enter → Activate scale tab or expand/collapse a WBS group; Delete → Remove the currently selected dependency arrow; Escape → Cancel an in-flight drag or dependency draw · Root carries role="grid"; the timeline header row is role="row" with each cell role="columnheader". Task bars are role="gridcell" labelled with the task name, dates, and % complete. Resize handles and the progress thumb are <button> elements so they are reachable by assistive tech. Dependency arrows are role="button" with keyboard-activatable selection. Scale switcher is a role="tablist"/role="tab" pair.

**Variants:**

*Week scale (default)*
```tsx
<Gantt tasks={tasks} scale="week" ariaLabel="Product launch plan" />
```

*Month scale*
```tsx
<Gantt tasks={tasks} scale="month" ariaLabel="Long-range roadmap" />
```

*Collapsed group*
```tsx
// Seed any task with `collapsed: true` to hide its children at first paint.
const tasks = base.map((t) => t.id === 'impl' ? { ...t, collapsed: true } : t);
<Gantt tasks={tasks} scale="week" />
```

*Dependencies (FS + SS)*
```tsx
const dependencies = [
  { id: 'd-t1-t2', from: 't1', to: 't2', type: 'FS' }, // Finish-to-Start
  { id: 'd-t4-t5', from: 't4', to: 't5', type: 'SS' }, // Start-to-Start
];

<Gantt tasks={tasks} dependencies={dependencies} scale="week" />
```

*Critical path (CPM)*
```tsx
// Critical-path highlight uses a forward + backward longest-path pass
// over the dependency DAG. Tasks with zero float switch to error styling
// and their connecting arrows turn red. The toolbar toggle lets users
// switch it on / off; passing the prop sets the initial value.
<Gantt
  tasks={tasks}
  dependencies={dependencies}
  scale="week"
  criticalPath
/>
```

*Milestones + baselines + weekends*
```tsx
// Milestones (zero-duration tasks rendered as diamonds), planned-vs-actual
// baseline ghost bars, and weekend / holiday shading on the day + week scales.
const baselines: Baseline[] = [
  { taskId: 't2', start: new Date('2026-05-01'), end: new Date('2026-05-07') },
  { taskId: 't5', start: new Date('2026-05-10'), end: new Date('2026-05-20') },
];

<Gantt
  tasks={tasks}                // include some { isMilestone: true } entries
  dependencies={dependencies}
  baselines={baselines}
  workingDays={[1, 2, 3, 4, 5]} // Mon-Fri; Sat+Sun shaded
  holidays={[new Date('2026-05-05')]}
  scale="week"
/>
```

*Export + resource conflicts + working-day snap*
```tsx
// M5 wires three things at once:
//  1. exportFormats opens the toolbar Export menu (PNG / PDF / CSV).
//  2. Tasks sharing an owner that overlap in time get a red ⚠ in the WBS
//     owner column (resource over-allocation).
//  3. workingDays makes drag snap forward to the next working day, so a
//     drop on a weekend lands on Monday.
const tasks: Task[] = [
  { id: 'r1', name: 'Frontend rebuild', start: ..., end: ..., owner: 'Eve M.' },
  { id: 'r2', name: 'Auth migration',   start: ..., end: ..., owner: 'Eve M.' }, // overlaps r1
  { id: 'r3', name: 'Reporting',        start: ..., end: ..., owner: 'Eve M.' }, // overlaps r2
];

<Gantt
  tasks={tasks}
  workingDays={[1, 2, 3, 4, 5]}
  exportFormats={['png', 'pdf', 'csv']}
  scale="week"
/>
```

*Keyboard nav + locale + reduced motion*
```tsx
// M6 adds:
//  - Grid keyboard nav from the Gantt root: ↑↓ between rows, Home/End,
//    PageUp/PageDown (5 rows), and +/− to zoom in/out. Focused bar gets a
//    border-focus ring and is announced via aria-activedescendant.
//  - locale prop drives Intl.DateTimeFormat for month names in the header
//    and date formatting in the hover tooltip.
//  - reducedMotion={true} or the OS prefers-reduced-motion media query
//    suppresses every Tailwind transition/animation under the root.
//  - Row virtualization kicks in automatically above ~60 tasks — only the
//    visible ± buffer slice renders, so 1000+ rows stay smooth.
<Gantt
  tasks={tasks}
  dependencies={deps}
  locale="tr-TR"               // Turkish month names / tooltip dates
  reducedMotion                // optional — force motion off
  scale="week"
/>
```

*Interactive (drag + dependencies)*
```tsx
const [tasks, setTasks] = useState<Task[]>(initial);
const [deps,  setDeps]  = useState<Dependency[]>([]);

<Gantt
  tasks={tasks}
  dependencies={deps}
  scale="week"
  onTaskUpdate={(t) => setTasks((prev) => prev.map((p) => (p.id === t.id ? t : p)))}
  onDependencyCreate={(d) => setDeps((prev) => [...prev, d])}
  onDependencyDelete={(id) => setDeps((prev) => prev.filter((d) => d.id !== id))}
/>
```

### FormBuilder  (`form-builder`)

- **Layer:** app
- **Category:** App
- **File:** `modules/app/FormBuilder/index.tsx`
- **Status:** beta (since 2026-05)
- **Description:** Typeform / JotForm-style drag-to-build form designer. M1 ships the field palette (text / email / number / textarea / select / radio / checkbox / date / file — multiselect / signature / rating are palette stubs), a draggable canvas with reorder + duplicate + delete, a right-hand settings panel (label, name, placeholder, helper text, required, default value, options), JSON schema export / import, and a paired FormRenderer with required + email-format validation. Future milestones: full validation engine + custom validators (M2), conditional logic editor + runtime AST eval (M3), multi-page + save & resume (M4), schema I/O + webhooks + signature / rating (M5), full WAI-ARIA / keyboard parity + i18n + theming (M6). Pixel-identical EJS sibling at modules/app/FormBuilder/FormBuilder.ejs.
- **Composes:** button, input, checkbox, select, textarea
- **Design tokens:** --surface-base, --surface-raised, --surface-overlay, --text-primary, --text-secondary, --text-disabled, --border, --border-strong, --border-focus, --primary, --primary-hover, --primary-active, --primary-fg, --error, --error-subtle
- **A11y:** WCAG AA · ARIA: application, list, listitem, radiogroup, alert · Keys: Tab → Move focus across palette / canvas / settings; Enter / Space → Activate palette item to append a field; Drag (mouse) → Drag from palette → drop into canvas; reorder by dragging the grip handle · Builder root is role="application" with aria-label. Canvas list is role="list"; each draggable card is role="listitem" with aria-current when selected. FormRenderer adds aria-required + aria-invalid + aria-describedby per field, and surfaces validation messages with role="alert". Full keyboard reorder + LiveRegion announcements land in M6.

**Variants:**

*Builder (drag + edit)*
```tsx
const [schema, setSchema] = useState<FormSchema>(seed);
<FormBuilder schema={schema} onChange={setSchema} />
```

*Builder + live FormRenderer*
```tsx
const [schema, setSchema] = useState<FormSchema>(seed);
<>
  <FormBuilder schema={schema} onChange={setSchema} />
  <FormRenderer schema={schema} onSubmit={async (values) => persist(values)} />
</>
```

*Standalone renderer (required + email validation)*
```tsx
<FormRenderer
  schema={STARTER_SCHEMA}
  onSubmit={async (values) => persist(values)}
/>
```

## Components — app / Domain

### NotFoundPage  (`common-not-found-page`)

- **Layer:** app
- **Category:** Domain
- **File:** `modules/app/NotFoundPage.tsx`
- **Status:** stable (since 2025-05)
- **Description:** Full-page 404 screen with a gradient "404" heading, icon slot, title, description, and home/back action buttons.

**Variants:**

*Default (Turkish)*
```tsx
<NotFoundPage homeHref="/" />
```

*Custom copy*
```tsx
<NotFoundPage title="Resource Not Found" description="The item you are looking for has been removed." homeLabel="Go Home" backLabel="Go Back" homeHref="/" />
```

## Components — app / Organism

### ImageGallery  (`image-gallery`)

- **Layer:** app
- **Category:** Organism
- **File:** `modules/app/ImageGallery/index.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Responsive image grid with a full-screen lightbox, right-click context menu (open, copy URL, move to first/last, remove), and drag-to-reorder. Supports 2–4 columns, square / video / portrait / auto aspect ratios, optional captions, zoom toggle, thumbnail strip, and full keyboard navigation (← → Escape).

**Variants:**

*Reorderable — drag + right-click menu*
```tsx
<ImageGallery
  images={images}
  columns={3}
  aspect="square"
  gap="md"
  reorderable
  onReorder={(next) => setImages(next)}
  onRemove={(idx, img) => console.log('removed', img.alt)}
/>
```

*3-column grid — lightbox only*
```tsx
<ImageGallery
  images={images}
  columns={3}
  aspect="square"
  gap="md"
  lightbox
/>
```

*2-column with captions*
```tsx
<ImageGallery
  images={images}
  columns={2}
  aspect="video"
  gap="lg"
  showCaptions
  lightbox
/>
```

*4-column compact*
```tsx
<ImageGallery
  images={images}
  columns={4}
  aspect="square"
  gap="sm"
  lightbox
/>
```

## Components — domain / Domain

### LoginForm  (`common-login-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/auth/LoginForm.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Email + password sign-in form with inline validation, "Remember me" checkbox, and server-error banner.

**Variants:**

*Default*
```tsx
<LoginForm onSubmit={handleLogin} />
```

*Server error*
```tsx
<LoginForm onSubmit={handleLogin} error="Invalid email or password." />
```

### RegisterForm  (`common-register-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/auth/RegisterForm.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Registration form with email, password, and confirm-password fields. Real-time password match validation and server-error support.

**Variants:**

*Default*
```tsx
<RegisterForm onSubmit={handleRegister} />
```

*Server error*
```tsx
<RegisterForm onSubmit={handleRegister} error="This email is already in use." />
```

### OAuthButtons  (`common-oauth-buttons`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/auth/OAuthButtons.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Social sign-in buttons for Google, GitHub, Discord, and Microsoft. Accepts a providers prop to show only a subset.

**Variants:**

*All providers*
```tsx
<OAuthButtons onProvider={handleOAuth} />
```

*Selected providers*
```tsx
<OAuthButtons providers={['GOOGLE', 'GITHUB']} onProvider={handleOAuth} />
```

### UserAvatar  (`common-user-avatar`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/user/UserAvatar.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Avatar that consumes the SafeUser type. Falls back to initials when no profile picture is set; supports online/away/busy/offline status dots.

**Variants:**

*Sizes*
```tsx
<UserAvatar user={user} size="xs" />
<UserAvatar user={user} size="sm" />
<UserAvatar user={user} size="md" />
<UserAvatar user={user} size="lg" />
<UserAvatar user={user} size="xl" />
```

*Status indicators*
```tsx
<UserAvatar user={user} size="lg" status="online" />
<UserAvatar user={user} size="lg" status="away" />
<UserAvatar user={user} size="lg" status="busy" />
<UserAvatar user={user} size="lg" status="offline" />
```

### UserRoleBadge  (`common-user-role-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/user/UserRoleBadge.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Color-coded badge for ADMIN / AUTHOR / USER roles. ADMIN renders as error (red), AUTHOR as primary (blue), USER as neutral.

**Variants:**

*All roles*
```tsx
<UserRoleBadge role="ADMIN" />
<UserRoleBadge role="AUTHOR" />
<UserRoleBadge role="USER" />
```

*Sizes*
```tsx
<UserRoleBadge role="ADMIN" size="sm" />
<UserRoleBadge role="ADMIN" size="md" />
<UserRoleBadge role="ADMIN" size="lg" />
```

### UserStatusBadge  (`common-user-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/user/UserStatusBadge.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Color-coded badge for ACTIVE / INACTIVE / BANNED user statuses. Optional dot prop adds a leading status indicator.

**Variants:**

*All statuses*
```tsx
<UserStatusBadge status="ACTIVE" />
<UserStatusBadge status="INACTIVE" />
<UserStatusBadge status="BANNED" />
```

*With dot*
```tsx
<UserStatusBadge status="ACTIVE" dot />
<UserStatusBadge status="INACTIVE" dot />
<UserStatusBadge status="BANNED" dot />
```

### UserMenu  (`common-user-menu`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/user/UserMenu.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Avatar + name + role trigger. Dropdown with Profile, Settings, and Sign out items. Closes on outside click.

**Variants:**

*Admin user*
```tsx
<UserMenu user={{ userId: 'u1', email: 'admin@acme.com', userRole: 'ADMIN', userStatus: 'ACTIVE', userProfile: { name: 'Jane Doe', profilePicture: null } }} />
```

*Custom items*
```tsx
<UserMenu user={authorUser} items={[
  { type: 'item', label: 'My Posts', icon: '📝' },
  { type: 'separator' },
  { type: 'item', label: 'Sign Out', icon: '↩️', danger: true },
]} />
```

### PriceDisplay  (`common-price-display`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/money/PriceDisplay.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Currency formatter using Intl.NumberFormat. Supports any ISO 4217 code and locale. Strikethrough prop renders an original/crossed-out price.

**Variants:**

*Sizes*
```tsx
<PriceDisplay amount={1299.99} currency="USD" size="sm" />
<PriceDisplay amount={1299.99} currency="USD" size="md" />
<PriceDisplay amount={1299.99} currency="USD" size="lg" />
<PriceDisplay amount={1299.99} currency="USD" size="xl" />
```

*Multi-currency + strikethrough*
```tsx
<PriceDisplay amount={2499} currency="TRY" size="lg" />
<PriceDisplay amount={1799} currency="TRY" size="lg" strikethrough />
<PriceDisplay amount={89.99} currency="USD" locale="en-US" size="lg" />
<PriceDisplay amount={74.99} currency="EUR" locale="de-DE" size="lg" />
```

### PaymentStatusBadge  (`common-payment-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/payment/PaymentStatusBadge.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Color-coded badge for all PaymentStatus values: PENDING / AUTHORIZED / PAID / FAILED / CANCELLED / REFUNDED.

**Variants:**

*All statuses*
```tsx
<PaymentStatusBadge status="PENDING" />
<PaymentStatusBadge status="AUTHORIZED" />
<PaymentStatusBadge status="PAID" />
<PaymentStatusBadge status="FAILED" />
<PaymentStatusBadge status="CANCELLED" />
<PaymentStatusBadge status="REFUNDED" />
```

*With dot, large*
```tsx
<PaymentStatusBadge status="PENDING" dot size="lg" />
<PaymentStatusBadge status="PAID" dot size="lg" />
<PaymentStatusBadge status="FAILED" dot size="lg" />
```

### AddressForm  (`common-address-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/address/AddressForm.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Full address form with full name, phone, address lines, city, state/district, postal code, and country. Pre-fillable via the initial prop.

**Variants:**

*Empty*
```tsx
<AddressForm onSubmit={handleSave} />
```

*Pre-filled*
```tsx
<AddressForm initial={existingAddress} submitLabel="Update" onCancel={handleCancel} onSubmit={handleUpdate} />
```

### AddressCard  (`common-address-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/address/AddressCard.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Read-only address display card with full name, phone, address lines, city, state, postal code, and country. Supports selected state and optional Edit/Delete actions.

**Variants:**

*Default*
```tsx
<AddressCard address={address} onEdit={handleEdit} onDelete={handleDelete} />
```

*Selectable list*
```tsx
<AddressCard address={address} selected={selected === idx} onEdit={() => setSelected(idx)} />
```

### OrderTotalsCard  (`common-order-totals-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/money/OrderTotalsCard.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Order summary card showing subtotal, discount, tax, service fee, shipping, and an emphasized total. Zero-value lines are hidden automatically.

**Variants:**

*No extras*
```tsx
<OrderTotalsCard currency="USD" totals={{ subtotal: 89.99, total: 89.99 }} />
```

*With discount, tax & shipping*
```tsx
<OrderTotalsCard currency="USD" totals={{ subtotal: 149.99, discountTotal: 20, taxTotal: 11.99, shippingTotal: 9.99, total: 153.96 }} />
```

### PublishStatusBadge  (`common-publish-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/status/PublishStatusBadge.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Badge for DRAFT / PUBLISHED / ARCHIVED content states with contextual Font Awesome icons. Icon can be hidden via showIcon={false}.

**Variants:**

*All statuses*
```tsx
<PublishStatusBadge status="DRAFT" />
<PublishStatusBadge status="PUBLISHED" />
<PublishStatusBadge status="ARCHIVED" />
```

*Without icon, small*
```tsx
<PublishStatusBadge status="DRAFT" showIcon={false} size="sm" />
<PublishStatusBadge status="PUBLISHED" showIcon={false} size="sm" />
```

### VisibilityBadge  (`common-visibility-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/status/VisibilityBadge.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Badge for PUBLIC / PRIVATE / UNLISTED visibility states with eye/lock icons. PUBLIC is green, PRIVATE is red, UNLISTED is neutral.

**Variants:**

*All states*
```tsx
<VisibilityBadge visibility="PUBLIC" />
<VisibilityBadge visibility="PRIVATE" />
<VisibilityBadge visibility="UNLISTED" />
```

*Sizes*
```tsx
<VisibilityBadge visibility="PUBLIC" size="sm" />
<VisibilityBadge visibility="PUBLIC" size="md" />
<VisibilityBadge visibility="PUBLIC" size="lg" />
```

### LanguageSwitcher  (`common-language-switcher`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/i18n/LanguageSwitcher.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Dropdown language selector using AppLanguage, LANG_NAMES and LANG_FLAGS from I18nTypes. RTL direction is applied per-option automatically.

**Variants:**

*Default*
```tsx
<LanguageSwitcher value={lang} onChange={setLang} languages={['en', 'tr', 'de', 'fr']} />
```

*RTL selected*
```tsx
<LanguageSwitcher value="ar" onChange={setLang} languages={['en', 'tr', 'de', 'fr', 'ar']} />
```

### ChangePasswordForm  (`common-change-password-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/auth/ChangePasswordForm.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Current password + new password + confirm fields with match validation and server-error banner.

**Variants:**

*Default*
```tsx
<ChangePasswordForm onSubmit={handleSubmit} />
```

*Server error*
```tsx
<ChangePasswordForm onSubmit={handleSubmit} error="Current password is incorrect." />
```

### UserProfileCard  (`common-user-profile-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/user/UserProfileCard.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Profile card with cover banner, avatar, display name, username, bio, role and status badges, and an optional actions slot.

**Variants:**

*Full profile*
```tsx
<UserProfileCard user={user} actions={<Button variant="outline" size="sm">Edit</Button>} />
```

*No profile data*
```tsx
<UserProfileCard user={user} />
```

### UserProfileForm  (`common-user-profile-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/user/UserProfileForm.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Controlled form for editing display name, username, bio, and profile picture URL. Username validation: 3–32 chars, lowercase alphanumeric + underscore.

**Variants:**

*Empty*
```tsx
<UserProfileForm onSubmit={handleSave} />
```

*Pre-filled*
```tsx
<UserProfileForm initial={{ name: 'Jane Doe', username: 'janedoe', biography: '...' }} onSubmit={handleSave} />
```

### UserPreferencesForm  (`common-user-preferences-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/user/UserPreferencesForm.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Preferences form with theme and language selects plus email/push notification and newsletter toggles.

**Variants:**

*Defaults*
```tsx
<UserPreferencesForm onSubmit={handleSave} />
```

*Pre-filled*
```tsx
<UserPreferencesForm initial={{ theme: 'DARK', language: 'tr', emailNotifications: false }} onSubmit={handleSave} />
```

### CouponInput  (`common-coupon-input`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/discount/CouponInput.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Coupon code input with apply/remove flow. Calls onApply which returns success/error; shows applied state once a valid code is accepted.

**Variants:**

*Default (try SAVE20)*
```tsx
<CouponInput onApply={async (code) => validateCoupon(code)} />
```

*Applied state*
```tsx
<CouponInput appliedCode="SAVE20" onApply={handleApply} onRemove={handleRemove} />
```

### DiscountBadge  (`common-discount-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/discount/DiscountBadge.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Formats and displays a discount: percentage (e.g. "20% off"), fixed amount with currency, or free shipping.

**Variants:**

*All types*
```tsx
<DiscountBadge discountType="PERCENTAGE" discountValue={20} />
<DiscountBadge discountType="FIXED" discountValue={50} currency="TRY" />
<DiscountBadge discountType="FREE_SHIPPING" discountValue={0} />
```

*Sizes*
```tsx
<DiscountBadge discountType="PERCENTAGE" discountValue={10} size="sm" />
<DiscountBadge discountType="PERCENTAGE" discountValue={10} size="md" />
<DiscountBadge discountType="PERCENTAGE" discountValue={10} size="lg" />
```

### PaymentMethodSelector  (`common-payment-method-selector`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/payment/PaymentMethodSelector.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Radio-group style card selector for payment methods. Shows icon, label, and description. Default set: credit card, debit card, bank transfer, wallet.

**Variants:**

*Default (4 methods)*
```tsx
<PaymentMethodSelector value={method} onChange={setMethod} />
```

### PaymentSummaryCard  (`common-payment-summary-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/payment/PaymentSummaryCard.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Read-only payment summary card: amount, method, provider, provider reference, and status badge.

**Variants:**

*Paid via Stripe*
```tsx
<PaymentSummaryCard payment={{ provider: 'Stripe', method: 'CREDIT_CARD', status: 'PAID', amount: 153.96, currency: 'USD', ... }} />
```

*Pending bank transfer*
```tsx
<PaymentSummaryCard payment={{ provider: 'Iyzico', method: 'BANK_TRANSFER', status: 'PENDING', amount: 2499, currency: 'TRY', ... }} />
```

### ForgotPasswordForm  (`common-forgot-password-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/auth/ForgotPasswordForm.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Email input that triggers a password reset link. Shows an inline success state after submission instead of a redirect.

**Variants:**

*Default*
```tsx
<ForgotPasswordForm onSubmit={async (email) => sendResetLink(email)} />
```

*Sent state*
```tsx
// After successful onSubmit, form renders a success message automatically
```

### SessionExpiredBanner  (`common-session-expired-banner`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/auth/SessionExpiredBanner.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Warning banner shown when the user session has expired. Includes a "Sign in again" action button.

**Variants:**

*With action*
```tsx
<SessionExpiredBanner onSignIn={() => router.push('/login')} />
```

*Custom message*
```tsx
<SessionExpiredBanner message="You've been signed out due to inactivity." onSignIn={handleSignIn} />
```

### SeoForm  (`common-seo-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/seo/SeoForm.tsx`
- **Status:** stable (since 2025-04)
- **Description:** SEO metadata form: title (60 char limit), meta description (160 char limit), and keyword tag input with character counters.

**Variants:**

*Empty*
```tsx
<SeoForm onSubmit={handleSave} />
```

*Pre-filled*
```tsx
<SeoForm initial={{ seoTitle: 'My Page', seoDescription: 'Short desc', keywords: ['next', 'react'] }} onSubmit={handleSave} onCancel={handleCancel} />
```

### SeoPreview  (`common-seo-preview`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/seo/SeoPreview.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Google search result preview card. Shows title, URL, and description with character count indicators. Empty fields render placeholder text.

**Variants:**

*Filled*
```tsx
<SeoPreview seo={{ seoTitle: 'My Page Title', seoDescription: 'A clear meta description.', keywords: ['next', 'react'] }} url="https://example.com/page" />
```

*Empty (placeholders)*
```tsx
<SeoPreview seo={{}} url="https://example.com/page" />
```

### AddressSelector  (`common-address-selector`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/address/AddressSelector.tsx`
- **Status:** beta (since 2025-04)
- **Description:** Selectable list of saved addresses built on AddressCard. Supports add, edit, and delete callbacks.

**Variants:**

*Multiple addresses*
```tsx
<AddressSelector addresses={addresses} onSelect={handleSelect} onAdd={handleAdd} />
```

*Empty state*
```tsx
<AddressSelector addresses={[]} onSelect={handleSelect} onAdd={() => setShowForm(true)} />
```

### LocationPicker  (`common-location-picker`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/location/LocationPicker.tsx`
- **Status:** beta (since 2025-04)
- **Description:** Location form with country selector (countries-list), city, state, postal code, and optional lat/lng. 2-column grid layout.

**Variants:**

*Empty*
```tsx
<LocationPicker onSubmit={handleSave} />
```

*Pre-filled*
```tsx
<LocationPicker initial={{ city: 'Istanbul', countryCode: 'TR', postalCode: '34000' }} onSubmit={handleSave} onCancel={handleCancel} />
```

### GeoPointDisplay  (`common-geo-point-display`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/location/GeoPointDisplay.tsx`
- **Status:** beta (since 2025-04)
- **Description:** Displays latitude/longitude coordinates with a Google Maps link. Configurable precision and optional label.

**Variants:**

*With label*
```tsx
<GeoPointDisplay point={{ latitude: 41.0082, longitude: 28.9784 }} label="Istanbul" />
```

*Coordinates only*
```tsx
<GeoPointDisplay point={{ latitude: 48.8566, longitude: 2.3522 }} showMapLink={false} />
```

### ProcessingStatusIndicator  (`common-processing-status-indicator`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/status/ProcessingStatusIndicator.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Animated status indicator for UPLOADING / PROCESSING / READY / FAILED states. Optional progress bar with percentage.

**Variants:**

*All states*
```tsx
<ProcessingStatusIndicator status="UPLOADING" progress={30} />
<ProcessingStatusIndicator status="PROCESSING" progress={65} />
<ProcessingStatusIndicator status="READY" progress={100} />
<ProcessingStatusIndicator status="FAILED" />
```

*Custom label + sizes*
```tsx
<ProcessingStatusIndicator status="PROCESSING" label="Encoding…" progress={45} size="sm" />
<ProcessingStatusIndicator status="PROCESSING" label="Encoding…" progress={45} size="md" />
<ProcessingStatusIndicator status="PROCESSING" label="Encoding…" progress={45} size="lg" />
```

### CurrencySelector  (`common-currency-selector`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/money/CurrencySelector.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Currency dropdown built from countries-list. Deduped, alphabetically sorted ISO 4217 currency codes.

**Variants:**

*Default*
```tsx
<CurrencySelector value={currency} onChange={setCurrency} />
```

*No label*
```tsx
<CurrencySelector value="USD" onChange={setCurrency} label="" />
```

### CountrySelector  (`common-country-selector`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/location/CountrySelector.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Country dropdown built from countries-list. Shows flag + full name + ISO2 code. Supports search by name or code, error/hint states.

**Variants:**

*Default*
```tsx
<CountrySelector value={country} onChange={setCountry} />
```

*With hint & error*
```tsx
<CountrySelector value="" onChange={setCountry} hint="Used for shipping address." />
<CountrySelector value="" onChange={setCountry} error="Please select a country." required />
```

*No label*
```tsx
<CountrySelector value="US" onChange={setCountry} label="" />
```

### DirectionProvider  (`common-direction-provider`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/i18n/DirectionProvider.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Context provider that sets dir="rtl"/"ltr" on a wrapper div based on the active language. useDirection() hook exposes lang, dir, isRTL.

**Variants:**

*RTL (Arabic)*
```tsx
<DirectionProvider lang="ar">
  <p className="text-right">مرحبا بالعالم — Hello World</p>
</DirectionProvider>
```

*LTR (English)*
```tsx
<DirectionProvider lang="en">
  <p>Hello World — مرحبا بالعالم</p>
</DirectionProvider>
```

### CreditCardVisual  (`common-credit-card-visual`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/payment/CreditCardVisual.tsx`
- **Status:** beta (since 2025-05)
- **Description:** Animated 3-D flip credit card. Front shows number, name, expiry; back shows CVV strip. Supports VISA, Mastercard, AMEX, Discover.

**Variants:**

*Brands*
```tsx
<CreditCardVisual brand="VISA" cardNumber="4111111111111111" cardholderName="JANE DOE" expiryMonth="08" expiryYear="28" />
<CreditCardVisual brand="MASTERCARD" cardNumber="5500005555555559" cardholderName="JOHN SMITH" expiryMonth="12" expiryYear="27" />
```

*Flipped (CVV)*
```tsx
<CreditCardVisual brand="AMEX" cardNumber="378282246310005" cardholderName="JANE DOE" expiryMonth="03" expiryYear="26" cvv="1234" flipped />
```

### CreditCardForm  (`common-credit-card-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/payment/CreditCardForm.tsx`
- **Status:** beta (since 2025-05)
- **Description:** Full credit card entry form with live card visual preview. Auto-detects brand, formats number, flips card on CVV focus, validates expiry.

**Variants:**

*Default*
```tsx
<CreditCardForm onSubmit={async (card) => saveCard(card)} onCancel={handleCancel} />
```

*Server error*
```tsx
<CreditCardForm onSubmit={handleSave} error="Card declined. Please try a different card." />
```

### SavedCardSelector  (`common-saved-card-selector`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/payment/SavedCardSelector.tsx`
- **Status:** beta (since 2025-05)
- **Description:** Radio-group list of saved payment cards. Shows brand badge, masked number, expiry, and default indicator. Supports remove and add-new callbacks.

**Variants:**

*Multiple cards*
```tsx
<SavedCardSelector cards={cards} selectedCardId={selected} onSelect={handleSelect} onRemove={handleRemove} onAddNew={() => setShowForm(true)} />
```

*Empty state*
```tsx
<SavedCardSelector cards={[]} onSelect={handleSelect} onAddNew={() => setShowForm(true)} />
```

### ChatBox  (`common-chat-box`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/chat/ChatBox.tsx`
- **Status:** beta (since 2025-05)
- **Description:** Floating chat widget that anchors to the bottom-right of the screen. Includes a FAB toggle, collapsible panel, scrollable message list with typing indicator, and an auto-growing textarea input.

**Variants:**

*With initial messages*
```tsx
<ChatBox
  title="Support Chat"
  subtitle="We typically reply in a few minutes"
  initialMessages={[
    { id: 'm1', role: 'agent', text: 'Hi there! How can I help you today?' },
    { id: 'm2', role: 'user', text: 'I have a question about my order.' },
  ]}
/>
```

*Empty / initial state*
```tsx
<ChatBox title="Sales Chat" subtitle="Ask us anything" />
```

### NotificationMenu  (`common-notification-menu`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/notification/NotificationMenu.tsx`
- **Status:** stable (since 2025-05)
- **Description:** Bell icon button with unread count badge. Opens a dropdown panel showing notification items grouped by read/unread state with variant color dots, timestamps, and mark-all-read / view-all actions.

**Variants:**

*With unread notifications*
```tsx
<NotificationMenu
  items={[
    { id: 'n1', title: 'New comment on your post', description: 'Jane replied to your article.', timestamp: '2 min ago', read: false, variant: 'info' },
    { id: 'n2', title: 'Payment received', description: 'Invoice #1042 paid ($153.96).', timestamp: '1 hr ago', read: false, variant: 'success' },
    { id: 'n3', title: 'Storage limit at 90%', timestamp: '3 hr ago', read: false, variant: 'warning' },
    { id: 'n4', title: 'Deployment complete', timestamp: 'Yesterday', read: true, variant: 'success' },
  ]}
  onMarkAllRead={handleMarkAllRead}
  onViewAll={() => router.push('/notifications')}
/>
```

*Empty state*
```tsx
<NotificationMenu items={[]} onViewAll={() => router.push('/notifications')} />
```

### SubscriptionPlanCard  (`common-subscription-plan-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/subscription/SubscriptionPlanCard.tsx`
- **Status:** stable (since 2025-05)
- **Description:** Subscription plan card displaying name, price with currency formatting, billing interval, and feature list with checkmarks. Highlights the popular and current plans. Accepts onSelect callback for plan switching.

**Variants:**

*Plan grid*
```tsx
<div className="grid grid-cols-3 gap-4">
  <SubscriptionPlanCard plan={freePlan} onSelect={handleSelect} />
  <SubscriptionPlanCard plan={proPlan} isCurrent onSelect={handleSelect} />
  <SubscriptionPlanCard plan={enterprisePlan} onSelect={handleSelect} />
</div>
```

*Single card states*
```tsx
<SubscriptionPlanCard plan={plan} isCurrent />
<SubscriptionPlanCard plan={{ ...plan, isPopular: true }} onSelect={handleSelect} />
```

### Charts  (`common-charts`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/charts/Charts.tsx`
- **Status:** beta (since 2025-05)
- **Description:** react-chartjs-2 chart components wrapped in Cards: Bar, Line, Doughnut, Radar, and Polar Area.

**Variants:**

*Bar — Revenue vs Expenses*
```tsx
<RevenueBarChart />
```

*Line — User Activity*
```tsx
<UserActivityLineChart />
```

*Doughnut — Sales by Category*
```tsx
<SalesByCategoryDoughnut />
```

*Radar — Product Comparison*
```tsx
<ProductComparisonRadar />
```

*Polar Area — Regional Sales*
```tsx
<RegionalSalesPolar />
```

### CheckoutSuccessState  (`common-checkout-success-state`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/common/payment/CheckoutSuccessState.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Success screen shown after checkout completion; includes a confirmation icon, payment summary, and optional delivery address.

**Variants:**

*Başarı ekranı*
```tsx
<CheckoutSuccessState
  payment={payment}
  address={deliveryAddress}
  onReset={() => window.location.reload()}
/>
```

### PostStatusBadge  (`blog-post-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/post/PostStatusBadge.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Color-coded dot-badge for blog post status. PUBLISHED (green), DRAFT (amber), SCHEDULED (blue), ARCHIVED (neutral). Extends common/PublishStatusBadge by adding the SCHEDULED value.

**Variants:**

*All statuses*
```tsx
<PostStatusBadge status="PUBLISHED" />
<PostStatusBadge status="DRAFT" />
<PostStatusBadge status="SCHEDULED" />
<PostStatusBadge status="ARCHIVED" />
```

*Sizes*
```tsx
<PostStatusBadge status="PUBLISHED" size="sm" />
<PostStatusBadge status="PUBLISHED" size="md" />
<PostStatusBadge status="PUBLISHED" size="lg" />
```

### CategoryBadge  (`blog-category-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/category/CategoryBadge.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Renders a category name as a small primary-colored pill. Accepts Pick<Category, "title" | "slug"> — the full Category object is not required.

**Variants:**

*Categories*
```tsx
<CategoryBadge category={{ title: 'Technology', slug: 'technology' }} />
<CategoryBadge category={{ title: 'Design', slug: 'design' }} />
<CategoryBadge category={{ title: 'Career', slug: 'career' }} />
```

*Sizes*
```tsx
<CategoryBadge category={category} size="sm" />
<CategoryBadge category={category} size="md" />
<CategoryBadge category={category} size="lg" />
```

### PostMeta  (`blog-post-meta`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/post/PostMeta.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Inline row showing author avatar, name, publish date, estimated read time, and view count. Read time is calculated by stripping HTML tags and dividing word count by 200.

**Variants:**

*With avatar*
```tsx
<PostMeta post={post} showAvatar />
```

*Without avatar*
```tsx
<PostMeta post={post} showAvatar={false} />
```

### PostContent  (`blog-post-content`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/post/PostContent.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Renders HTML blog content with token-based typography styles. Separate styles are defined for h1–h3, p, a, ul/ol, blockquote, code, pre, img, hr, and table.

**Variants:**

*Rich content*
```tsx
<PostContent content={htmlContent} />
```

*Simple paragraphs*
```tsx
<PostContent content="<p>First paragraph.</p><p>Second paragraph.</p>" />
```

### PostCard  (`blog-post-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/post/PostCard.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Listing card consuming PostWithData. Composed of cover image, category badge, title, description, and a PostMeta row. href renders an <a>, onClick a <button>, neither a plain <div>.

**Variants:**

*Default*
```tsx
<PostCard post={post} href={`/blog/${post.slug}`} />
```

*With status badge*
```tsx
<PostCard post={post} showStatus />
<PostCard post={draftPost} showStatus />
```

### CommentForm  (`blog-comment-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/comment/CommentForm.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Name, email, and content comment form with inline validation. Providing parentId switches it to reply mode; onCancel shows a Cancel button.

**Variants:**

*New comment*
```tsx
<CommentForm postId={post.postId} onSubmit={handleSubmit} />
```

*Reply mode*
```tsx
<CommentForm postId={post.postId} parentId={comment.commentId} onSubmit={handleSubmit} onCancel={handleCancel} />
```

### CommentItem  (`blog-comment-item`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/comment/CommentItem.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Single comment with initials-fallback avatar, name, date, content, and a Reply button. At depth < 1, clicking Reply opens an inline CommentForm; nested replies are indented with a left border.

**Variants:**

*Single comment*
```tsx
<CommentItem comment={comment} />
```

*With replies*
```tsx
<CommentItem comment={comment} replies={replies} onSubmitReply={handleReply} />
```

### CommentList  (`blog-comment-list`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/comment/CommentList.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Filters to PUBLISHED comments, groups them 2 levels deep by parentId, and appends a new-comment form. Shows an encouraging empty state when there are no comments.

**Variants:**

*With comments*
```tsx
<CommentList comments={comments} postId={post.postId} onSubmitComment={handleSubmit} />
```

*Empty state*
```tsx
<CommentList comments={[]} postId={post.postId} onSubmitComment={handleSubmit} />
```

### AuthorBioCard  (`blog-author-bio-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/author/AuthorBioCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Author profile header with avatar, bio, role/verified badges, and social links.

**Variants:**

*Verified author with socials*
```tsx
<AuthorBioCard name="John Nolan" verified role="Senior Editor" socials={{ twitter, linkedin, github }} />
```

*Minimal author with follow*
```tsx
<AuthorBioCard name="Oscar Reed" username="oscarreed" onFollow={…} />
```

### TopicCloud  (`blog-topic-cloud`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/author/TopicCloud.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Weighted tag cloud where each topic is sized by its post count.

**Variants:**

*Mixed counts*
```tsx
<TopicCloud topics={topics} />
```

*Compact range*
```tsx
<TopicCloud topics={topics} minSize={0.85} maxSize={1.1} />
```

### AuthorStatsRow  (`blog-author-stats-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/blog/author/AuthorStatsRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Horizontal stat strip for an author profile — posts, views, comments, likes, followers.

**Variants:**

*All stats*
```tsx
<AuthorStatsRow stats={{ posts, views, comments, likes, followers }} />
```

*Posts + followers*
```tsx
<AuthorStatsRow stats={{ posts: 12, followers: 480 }} />
```

### EventStatusBadge  (`event-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/EventStatusBadge.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Etkinlik durumunu (PUBLISHED, SOLD_OUT, CANCELLED…) renkli badge ile gösterir.

**Variants:**

*Tüm durumlar*
```tsx
<EventStatusBadge status="DRAFT" />
<EventStatusBadge status="PUBLISHED" />
<EventStatusBadge status="SOLD_OUT" />
```

*Boyutlar*
```tsx
<EventStatusBadge status="CANCELLED" size="sm" />
<EventStatusBadge status="CANCELLED" size="md" />
<EventStatusBadge status="CANCELLED" size="lg" />
```

### EventFormatBadge  (`event-format-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/EventFormatBadge.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Etkinlik formatını (PHYSICAL / ONLINE / HYBRID) emoji + etiket ile gösterir.

**Variants:**

*Tüm formatlar*
```tsx
<EventFormatBadge format="PHYSICAL" />
<EventFormatBadge format="ONLINE" />
<EventFormatBadge format="HYBRID" />
```

### EventCategoryBadge  (`event-category-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/EventCategoryBadge.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Etkinlik kategorisini chip olarak gösterir; href verilirse tıklanabilir bağlantıya dönüşür.

**Variants:**

*Badge ve link*
```tsx
<EventCategoryBadge category={category} />
<EventCategoryBadge category={category} href="/events?category=muzik" />
```

### EventCard  (`event-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/EventCard.tsx`
- **Status:** stable (since 2025-03)
- **Description:** 16:9 görsel, fiyat pill, kategori/durum/format badge ve organizatör bilgisi içeren tam etkinlik kartı.

**Variants:**

*Yayında*
```tsx
<EventCard event={event} />
```

*Satışı Bitti*
```tsx
<EventCard event={soldOutEvent} />
```

### OrganizerCard  (`organizer-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/OrganizerCard.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Organizatör logo/baş harfleri, isim, doğrulanmış rozetleri ve iletişim bağlantılarını gösterir.

**Variants:**

*Doğrulanmış organizatör*
```tsx
<OrganizerCard organizer={organizer} />
```

*Logosuz*
```tsx
<OrganizerCard organizer={{ ...organizer, verified: false }} />
```

### SectionPricingCard  (`section-pricing-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/SectionPricingCard.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Bilet kategorisi seçim kartı; −/+ adet kontrolü, kapasite uyarısı ve seçili durumu içerir.

**Variants:**

*Seçili*
```tsx
<SectionPricingCard pricing={pricing} quantity={2} onQuantityChange={setQty} selected />
```

*Son koltuk uyarısı*
```tsx
// soldCount yakın olduğunda "Son X koltuk" uyarısı gösterilir
<SectionPricingCard pricing={pricing} quantity={0} onQuantityChange={setQty} />
```

### TicketCard  (`ticket-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/TicketCard.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Kesik çizgili ayırıcı ve SVG QR koduyla tam bilet görseli.

**Variants:**

*Yatay bilet (varsayılan)*
```tsx
<TicketCard
  ticket={ticket}
  event={{ title, startAt, venueName, venueCity }}
  section={{ sectionName: 'Genel Giriş' }}
/>
```

*Dikey bilet*
```tsx
<TicketCard
  ticket={ticket}
  event={{ title, startAt, venueName, venueCity }}
  section={{ sectionName: 'Genel Giriş', seatLabel: 'B-14' }}
  orientation="vertical"
  className="w-72"
/>
```

*İptal bilet (dikey)*
```tsx
<TicketCard
  ticket={{ ...ticket, status: 'CANCELLED' }}
  event={{ title, startAt, venueName, venueCity }}
  orientation="vertical"
  className="w-72"
/>
```

### EventInfoGrid  (`event-info-grid`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/EventInfoGrid.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Etkinlik detay sayfası için tarih/saat, mekan, format ve doluluk oranı bilgilerini düzenli bir kart içinde gösterir.

**Variants:**

*Tüm alanlar*
```tsx
<EventInfoGrid event={event} venue={venue} />
```

*Online etkinlik (mekan yok)*
```tsx
<EventInfoGrid event={{ ...event, format: 'ONLINE' }} venue={null} />
```

### TicketSidebarBox  (`ticket-sidebar-box`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/TicketSidebarBox.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Etkinlik detay sayfasının yapışkan sağ kenar çubuğu: fiyat başlığı, fiyatlandırma listesi, satın al butonu ve harita.

**Variants:**

*Satın alınabilir*
```tsx
<TicketSidebarBox
  priceLabel="₺1.500 – ₺8.500"
  pricings={pricings}
  canBuy={true}
  isSoldOut={false}
  isCancelled={false}
  eventSlug={event.slug}
  remainingCapacity={800}
  venue={venue}
/>
```

*Satışı bitti*
```tsx
<TicketSidebarBox canBuy={false} isSoldOut={true} ... />
```

### StepIndicator  (`step-indicator`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/StepIndicator.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Ödeme akışı (Biletler → Bilgiler → Ödeme → Onay) için 4 adımlı ilerleme göstergesi.

**Variants:**

*Tüm adım durumları*
```tsx
<StepIndicator current="tickets" />
<StepIndicator current="buyer" />
<StepIndicator current="payment" />
<StepIndicator current="confirm" />
```

### CheckoutSuccess  (`checkout-success`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/CheckoutSuccess.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Başarılı ödeme sonrası gösterilen onay ekranı: QR bilet, sipariş özeti, yazdır/geri dön butonları.

**Variants:**

*Başarı ekranı*
```tsx
<CheckoutSuccess
  orderId="ORD-XY9Z12"
  ticketId="TKT-A1B2C3"
  buyerName="Ahmet Yılmaz"
  buyerEmail="ahmet@example.com"
  event={event}
  venue={venue}
  cartItems={cartItems}
  total={total}
/>
```

### SeatMapPicker  (`seat-map-picker`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/SeatMapPicker/index.tsx`
- **Status:** beta (since 2025-04)
- **Description:** Görsel koltuk seçim haritası: section/subsection sekme desteği, sıra-koltuk grid, renk kodlu durum, erişilebilirlik göstergesi.

**Variants:**

*Section + subsection + koltuk seçimi*
```tsx
const sections = buildSectionTree(allSections, seatInfos, pricings);

<SeatMapPicker
  sections={sections}
  selectedSeatIds={selected}
  onSeatToggle={(id) => toggleSeat(id)}
  maxSelectable={4}
  showStage
/>
```

*SVG Salon Haritası — tıkla → koltuk seç*
```tsx
import type { SectionMapShape } from '@/modules/domains/event/SeatMapPicker';

const mapShapes: SectionMapShape[] = [
  { sectionId: 'parket',     points: '170,93 510,93 558,290 122,290',                labelX: 340, labelY: 185 },
  { sectionId: 'sol-yan',   points: '32,93 170,93 122,290 18,248',                  labelX: 95,  labelY: 185 },
  { sectionId: 'sag-yan',   points: '510,93 648,93 662,248 558,290',                labelX: 585, labelY: 185 },
  { sectionId: 'ust-balkon', points: '18,248 122,290 558,290 662,248 674,438 6,438', labelX: 340, labelY: 360 },
];

<SeatMapPicker
  sections={sections}
  selectedSeatIds={selected}
  onSeatToggle={(id) => toggleSeat(id)}
  maxSelectable={6}
  mapShapes={mapShapes}
  mapViewBox="0 0 680 460"
  stagePoints="225,18 455,18 455,88 225,88"
  stageLabel="SAHNE"
  stageLabelX={340}
  stageLabelY={53}
/>
```

### HeroSlide  (`hero-slide`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/HeroSlide.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Slider içinde kullanılan tam ekran hero slayt: çift gradyan katmanı, badge'ler, fiyat, CTA butonları.

**Variants:**

*Tek slayt önizleme*
```tsx
<HeroSlide event={event} />
```

### NavDropdown  (`event-nav-dropdown`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/NavDropdown.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Event koyu nav barı için dropdown bileşen ailesi: NavDropdown kapsayıcı, NavDropdownHeader başlık, NavTriggerButton tetikleyici. useNavPopover hook'u ile kullanılır.

**Variants:**

*Dropdown açık/kapalı*
```tsx
const { open, setOpen, ref } = useNavPopover();

<div ref={ref} className="relative">
  <NavTriggerButton onClick={() => setOpen(p => !p)} expanded={open}>
    Options
  </NavTriggerButton>
  {open && (
    <NavDropdown>
      <NavDropdownHeader>Choose one</NavDropdownHeader>
      <ul>{...}</ul>
    </NavDropdown>
  )}
</div>
```

### CityPicker  (`event-city-picker`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/CityPicker.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Event nav barı için şehir seçici dropdown; varsayılan Türkiye şehirleri, props ile özelleştirilebilir.

**Variants:**

*Varsayılan*
```tsx
<CityPicker />
```

*Özel şehir listesi*
```tsx
<CityPicker cities={customCities} allCitiesHref="/cities" />
```

### NavLanguageSwitcher  (`event-nav-language-switcher`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/NavLanguageSwitcher.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Event koyu nav barına özel dil seçici; bayrak emojileri ve seçili işareti. Mevcut LanguageSwitcher'dan bağımsız koyu tema variant'ı.

**Variants:**

*Nav içinde*
```tsx
<NavLanguageSwitcher />
```

### NavThemeSwitcher  (`event-nav-theme-switcher`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/NavThemeSwitcher.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Event koyu nav barına özel tema değiştirici (Açık / Koyu / Sistem); localStorage'a yazar ve html.dark class'ını yönetir.

**Variants:**

*Nav içinde*
```tsx
<NavThemeSwitcher />
```

*Birlikte kullanım*
```tsx
// Tipik event nav bar üst çubuğu:
<NavThemeSwitcher />
<TopBarDivider />
<NavLanguageSwitcher />
<TopBarDivider />
<CityPicker />
```

### EventOrderStatusBadge  (`event-order-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/EventOrderStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Sipariş durumu rozeti; PAID / REFUNDED / CANCELLED renk şeması, iki boyut seçeneği.

**Variants:**

*All statuses — sm*
```tsx
<EventOrderStatusBadge status="PAID" />
<EventOrderStatusBadge status="REFUNDED" />
<EventOrderStatusBadge status="CANCELLED" />
```

*Size md (detail view)*
```tsx
<EventOrderStatusBadge status="PAID"      size="md" />
<EventOrderStatusBadge status="REFUNDED"  size="md" />
<EventOrderStatusBadge status="CANCELLED" size="md" />
```

### TicketRowMeta + TicketRowActions  (`event-ticket-row-meta`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/event/TicketRowMeta.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Bilet listesi satırı başlığı: etkinlik küçük resmi, durum rozeti (TicketRowMeta) ve yazdır / paylaş butonları (TicketRowActions).

**Variants:**

*Default*
```tsx
<div className="flex items-center justify-between px-1">
  <TicketRowMeta   entry={entry} />
  <TicketRowActions entry={entry} />
</div>
```

*Compact (vertical layout)*
```tsx
<TicketRowMeta   entry={entry} compact />
<TicketRowActions entry={entry} compact />
```

### StatusCodeBadge  (`api-doc-status-code-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/StatusCodeBadge.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Displays an HTTP status code with a semantic color and an optional human-readable label.

**Variants:**

*All status families*
```tsx
<StatusCodeBadge code={200} />
<StatusCodeBadge code={201} />
<StatusCodeBadge code={204} />
<StatusCodeBadge code={301} />
<StatusCodeBadge code={400} />
<StatusCodeBadge code={404} />
<StatusCodeBadge code={500} />
```

*Without label*
```tsx
<StatusCodeBadge code={200} showLabel={false} />
<StatusCodeBadge code={404} showLabel={false} />
<StatusCodeBadge code={500} showLabel={false} />
```

### HttpMethodBadge  (`api-doc-http-method-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/HttpMethodBadge.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Color-coded badge for HTTP methods — GET, POST, PUT, PATCH, DELETE, and more.

**Variants:**

*All methods — medium (default)*
```tsx
{(['GET','POST','PUT','PATCH','DELETE','HEAD','OPTIONS','TRACE'] as const).map((m) => (
  <HttpMethodBadge key={m} method={m} />
))}
```

*Sizes*
```tsx
<HttpMethodBadge method="GET" size="sm" />
<HttpMethodBadge method="GET" size="md" />
<HttpMethodBadge method="GET" size="lg" />
```

### SecurityBadge  (`api-doc-security-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/SecurityBadge.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Inline badge representing an API security scheme type with a matching icon and color.

**Variants:**

*All scheme types*
```tsx
<SecurityBadge type="apiKey" />
<SecurityBadge type="http" />
<SecurityBadge type="oauth2" />
<SecurityBadge type="openIdConnect" />
<SecurityBadge type="mutualTLS" />
```

*Custom names*
```tsx
<SecurityBadge type="apiKey" name="X-API-Key" />
<SecurityBadge type="oauth2" name="OAuth 2.0 (PKCE)" />
<SecurityBadge type="http" name="Bearer JWT" />
```

### SecuritySchemeBadge  (`api-doc-security-scheme-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/SecuritySchemeBadge.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Badge variant of SecurityBadge that uses the design-system Badge component for consistent styling.

**Variants:**

*All scheme types*
```tsx
<SecuritySchemeBadge type="apiKey" />
<SecuritySchemeBadge type="http" />
<SecuritySchemeBadge type="oauth2" />
<SecuritySchemeBadge type="openIdConnect" />
<SecuritySchemeBadge type="mutualTLS" />
```

*Small size with custom names*
```tsx
<SecuritySchemeBadge type="apiKey" name="X-API-Key" size="sm" />
<SecuritySchemeBadge type="http" name="Bearer JWT" size="sm" />
<SecuritySchemeBadge type="oauth2" name="Google OAuth" size="sm" />
```

### SchemaViewer  (`api-doc-schema-viewer`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/SchemaViewer.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Interactive JSON Schema tree viewer with type coloring, constraint display, and collapsible nodes.

**Variants:**

*Object schema*
```tsx
const userSchema = {
  type: 'object',
  required: ['id', 'email', 'name'],
  properties: {
    id: { type: 'string', format: 'uuid', readOnly: true },
    email: { type: 'string', format: 'email' },
    name: { type: 'string', minLength: 1, maxLength: 100 },
    role: { type: 'string', enum: ['admin', 'editor', 'viewer'] },
    active: { type: 'boolean', default: true },
  },
};

<SchemaViewer schema={userSchema} title="User" />
```

*Nested / array schema*
```tsx
const listSchema = {
  type: 'object',
  properties: {
    data: { type: 'array', items: userSchema },
    total: { type: 'integer', description: 'Total items' },
    page: { type: 'integer' },
    pageSize: { type: 'integer' },
  },
};

<SchemaViewer schema={listSchema} title="PaginatedUsers" />
```

### ParameterTable  (`api-doc-parameter-table`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/ParameterTable.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Table displaying API parameters with location (path/query/header/cookie), type, required flag, and description.

**Variants:**

*Mixed parameter locations*
```tsx
<ParameterTable parameters={[
  { parameterId: 'p1', name: 'userId', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } },
  { parameterId: 'p2', name: 'page', in: 'query', schema: { type: 'integer', default: 1 } },
  { parameterId: 'p3', name: 'Authorization', in: 'header', required: true, schema: { type: 'string' } },
  { parameterId: 'p4', name: 'role', in: 'query', schema: { type: 'string', enum: ['admin','editor','viewer'] }, deprecated: true },
]} />
```

*Path params only*
```tsx
<ParameterTable parameters={[
  { parameterId: 'pp1', name: 'orgId', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } },
  { parameterId: 'pp2', name: 'projectId', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } },
]} />
```

### ResponseCard  (`api-doc-response-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/ResponseCard.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Collapsible card for a single API response showing the status code, description, and response body schema.

**Variants:**

*Success response (expanded)*
```tsx
<ResponseCard
  response={{
    statusCode: '200',
    description: 'Successful response',
    content: { 'application/json': { schema: userSchema } },
  }}
  defaultOpen
/>
```

*Multiple response cards*
```tsx
{responses.map((r) => (
  <ResponseCard key={r.responseId} response={r} defaultOpen={r.statusCode.startsWith('2')} />
))}
```

### CodeSamplePanel  (`api-doc-code-sample-panel`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/CodeSamplePanel.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Dark-themed panel showing code samples in multiple languages with tab switching and a one-click copy button.

**Variants:**

*Multi-language sample*
```tsx
<CodeSamplePanel samples={[
  { lang: 'curl', label: 'cURL', source: `curl -X GET 'https://api.example.com/v1/users'` },
  { lang: 'javascript', label: 'JavaScript', source: `const res = await fetch('/users');` },
  { lang: 'python', label: 'Python', source: `import requests\nr = requests.get('/users')` },
]} />
```

*Single language*
```tsx
<CodeSamplePanel samples={[{ lang: 'bash', label: 'Shell', source: '...' }]} />
```

### EndpointRow  (`api-doc-endpoint-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/EndpointRow.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Collapsible row representing a single API endpoint — shows the method badge, path, summary, and expands to an OperationPanel.

**Variants:**

*GET endpoint (expanded)*
```tsx
<EndpointRow
  path="/users"
  operation={{ method: 'GET', summary: 'List users', ... }}
  defaultOpen
/>
```

*Multiple endpoints*
```tsx
<EndpointRow path="/users" operation={getOp} />
<EndpointRow path="/users" operation={postOp} />
<EndpointRow path="/users/{userId}" operation={deleteOp} />
```

### ServerSelector  (`api-doc-server-selector`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/ServerSelector.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Dropdown for selecting the active API server, with environment badges (production, staging, development, sandbox).

**Variants:**

*Multi-environment servers*
```tsx
<ServerSelector servers={[
  { serverId: 'srv1', url: 'https://api.example.com/v1', environment: 'production' },
  { serverId: 'srv2', url: 'https://staging-api.example.com/v1', environment: 'staging' },
  { serverId: 'srv3', url: 'http://localhost:3000/v1', environment: 'development' },
]} />
```

*Single server*
```tsx
<ServerSelector servers={[
  { serverId: 'srv1', url: 'https://api.example.com/v1', environment: 'production' },
]} />
```

### ApiTagSection  (`api-doc-api-tag-section`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/ApiTagSection.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Collapsible section grouping endpoints under a named tag — the primary navigation unit in API documentation.

**Variants:**

*Users tag (expanded)*
```tsx
<ApiTagSection
  tag={{ tagId: 'tag-users', name: 'Users', description: 'User management endpoints' }}
  paths={[
    { pathItem: { path: '/users', operations: [getOp, postOp] } },
    { pathItem: { path: '/users/{userId}', operations: [deleteOp] } },
  ]}
  defaultOpen
/>
```

*Collapsed by default*
```tsx
<ApiTagSection
  tag={{ name: 'Auth', description: 'Authentication endpoints' }}
  paths={[{ pathItem: { path: '/auth/token', operations: [postOp] } }]}
  defaultOpen={false}
/>
```

### OperationPanel  (`api-doc-operation-panel`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/OperationPanel.tsx`
- **Status:** stable (since 2025-04)
- **Description:** Tabbed panel showing all details of an API operation — parameters, request body, responses, and code samples.

**Variants:**

*GET with parameters and code samples*
```tsx
<OperationPanel operation={{
  method: 'GET',
  summary: 'List users',
  parameters: [...],
  responses: [...],
  codeSamples: [...],
}} />
```

*POST with request body*
```tsx
<OperationPanel operation={{
  method: 'POST',
  summary: 'Create user',
  requestBody: { required: true, content: { 'application/json': { schema: userSchema } } },
  responses: [...],
}} />
```

### AuthSchemeCard  (`api-doc-auth-scheme-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/AuthSchemeCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Selectable card describing a single auth scheme (apiKey, http, oauth2, openIdConnect, mutualTLS).

**Variants:**

*OAuth recommended*
```tsx
<AuthSchemeCard name="OAuth 2.0" type="oauth2" recommended description="…" href="/auth/oauth2" />
```

*API key*
```tsx
<AuthSchemeCard name="X-API-Key" type="apiKey" description="…" />
```

### OAuthFlowDiagram  (`api-doc-oauth-flow-diagram`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/OAuthFlowDiagram.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Visual walkthrough of an OAuth 2.0 flow with actors, numbered steps, endpoints, and scopes.

**Variants:**

*Authorization Code*
```tsx
<OAuthFlowDiagram flow="authorizationCode" tokenUrl="…" authorizationUrl="…" scopes={[…]} />
```

*Client Credentials (server-to-server)*
```tsx
<OAuthFlowDiagram flow="clientCredentials" tokenUrl="…" />
```

### ApiKeyTokenCard  (`api-doc-api-key-token-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/api-doc/ApiKeyTokenCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Card for a single API key — reveal/hide, copy-to-clipboard, env badge, last-used metadata.

**Variants:**

*Production key*
```tsx
<ApiKeyTokenCard name="Production key" token="sk_live_…" environment="production" scopes={[…]} />
```

*Staging key with revoke*
```tsx
<ApiKeyTokenCard name="Staging key" token="sk_test_…" environment="staging" onRevoke={…} />
```

### HeroSection  (`landing-hero-section`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/hero/HeroSection.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Full-width landing hero with eyebrow label, headline, subheadline, dual CTAs, and an optional right-column image. Gradient blobs are applied in-component.

**Variants:**

*With image*
```tsx
<HeroSection hero={{ headline: 'Ship better products, faster.', primaryCta: { label: 'Start for free', href: '#' }, image: '/hero.png' }} />
```

*Text only*
```tsx
<HeroSection hero={{ eyebrow: 'New feature', headline: 'The fastest way to go from idea to production.', primaryCta: { label: 'Get started', href: '#' } }} />
```

### FeatureCard  (`landing-feature-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/feature/FeatureCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Single feature item with Font Awesome icon, title, and description. layout="card" renders a raised card with hover border; layout="inline" renders a compact horizontal row.

**Variants:**

*Card layout*
```tsx
<FeatureCard feature={{ featureId: 'f1', icon: 'bolt', title: 'Fast deploys', description: 'Push in under 60s.' }} />
```

*Inline layout*
```tsx
<FeatureCard feature={feature} layout="inline" />
```

### FeatureGrid  (`landing-feature-grid`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/feature/FeatureGrid.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Section wrapper that renders a heading block and a responsive grid of FeatureCard components. columns prop controls breakpoints; layout prop is passed down to each card.

**Variants:**

*3-column cards*
```tsx
<FeatureGrid title="Built for teams" features={features} columns={3} />
```

*2-column inline*
```tsx
<FeatureGrid title="Core capabilities" features={features} layout="inline" columns={2} />
```

### PricingPlanCard  (`landing-pricing-plan-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/pricing/PricingPlanCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Marketing-oriented pricing card with formatted price, interval label, feature checklist, and a CTA link. isPopular adds a "Most Popular" badge and primary border highlight.

**Variants:**

*Popular plan*
```tsx
<PricingPlanCard plan={{ ...plan, isPopular: true }} />
```

*All plans*
```tsx
<PricingPlanCard plan={freePlan} />
<PricingPlanCard plan={{ ...proPlan, isPopular: true }} />
<PricingPlanCard plan={scalePlan} />
```

### PricingGrid  (`landing-pricing-grid`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/pricing/PricingGrid.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Pricing section that wraps PricingPlanCard in a responsive grid. showIntervalToggle renders a Monthly/Yearly switch and filters plans by the selected interval.

**Variants:**

*Monthly only*
```tsx
<PricingGrid title="Pricing" plans={monthlyPlans} showIntervalToggle={false} />
```

*With interval toggle*
```tsx
<PricingGrid title="Pricing" plans={[...monthlyPlans, ...yearlyPlans]} showIntervalToggle />
```

### TestimonialCard  (`landing-testimonial-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/testimonial/TestimonialCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Customer quote card with optional star rating, author initials fallback avatar, name, title, company, and company logo. All fields except quote and authorName are optional.

**Variants:**

*With rating & company*
```tsx
<TestimonialCard testimonial={{ ...testimonial, rating: 5 }} />
```

*Minimal*
```tsx
<TestimonialCard testimonial={{ testimonialId: 't1', quote: '...', authorName: 'Marcus Webb' }} />
```

### TestimonialGrid  (`landing-testimonial-grid`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/testimonial/TestimonialGrid.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Masonry columns grid of TestimonialCard components with a centred heading block. Uses CSS columns for the masonry effect — cards automatically balance across columns.

**Variants:**

*Masonry grid*
```tsx
<TestimonialGrid title="What teams say" testimonials={testimonials} />
```

### FaqAccordion  (`landing-faq-accordion`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/faq/FaqAccordion.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Accessible accordion for FAQ items using aria-expanded + aria-controls. By default only one item is open at a time; allowMultiple enables concurrent open items. First item is pre-opened.

**Variants:**

*Single open*
```tsx
<FaqAccordion eyebrow="FAQ" title="Common questions" items={faqItems} />
```

*Allow multiple open*
```tsx
<FaqAccordion title="Common questions" items={faqItems} allowMultiple />
```

### StatsBar  (`landing-stats-bar`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/stat/StatsBar.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Social proof stats display in two variants. band renders a full-width <dl> grid with dividers; cards renders a grid of bordered stat cards.

**Variants:**

*Band variant*
```tsx
<StatsBar stats={stats} variant="band" />
```

*Cards variant*
```tsx
<StatsBar stats={stats} variant="cards" />
```

### TeamMemberCard  (`landing-team-member-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/team/TeamMemberCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Centered team card showing avatar (or initials fallback), name, role, optional bio, and social link icons for LinkedIn, X (Twitter), and GitHub.

**Variants:**

*Two cards*
```tsx
<TeamMemberCard member={member} />
```

*Four-column grid*
```tsx
{team.map((m) => <TeamMemberCard key={m.memberId} member={m} />)}
```

### PartnerLogosStrip  (`landing-partner-logos-strip`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/partner/PartnerLogosStrip.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Horizontal strip of grayscale partner logos. On hover the logo transitions to full colour. Logos with a url prop are wrapped in an accessible <a>.

**Variants:**

*With label*
```tsx
<PartnerLogosStrip label="Trusted by teams at" partners={partners} />
```

*Without label*
```tsx
<PartnerLogosStrip partners={partners} />
```

### HowItWorksSection  (`landing-how-it-works`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/how-it-works/HowItWorksSection.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Process steps section in two layouts. horizontal shows numbered/icon circles in a row connected by a dashed line. vertical stacks them with a timeline connector.

**Variants:**

*Horizontal layout*
```tsx
<HowItWorksSection title="3 simple steps" steps={steps} layout="horizontal" />
```

*Vertical timeline*
```tsx
<HowItWorksSection title="How it works" steps={steps} layout="vertical" />
```

### AnnouncementBar  (`landing-announcement-bar`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/nav/AnnouncementBar.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Dismissible top-of-page banner for promotions and announcements. Supports an optional icon, rich message content, a CTA link, and a dismiss button. Renders null once dismissed.

**Variants:**

*Default (dismissible)*
```tsx
<AnnouncementBar icon={faBullhorn} message={<><span className="font-semibold">Velox 2.0 is here</span> — faster builds, smarter previews.</>} cta={{ label: 'Read the announcement', href: '#' }} />
```

*Non-dismissible promo*
```tsx
<AnnouncementBar message="Black Friday — 40% off all plans." cta={{ label: 'Claim offer', href: '#' }} dismissible={false} />
```

### MegaMenu  (`landing-mega-menu`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/landing/nav/MegaMenu.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Compound component for hover-activated mega menus. Composed of MegaMenu.Root, Trigger, Panel, Section, Item, Footer, and FeaturedCard sub-components. Use useMegaMenu() to share open/close state across multiple menus. Includes an invisible hover bridge that prevents the gap between the trigger and panel from closing the menu.

**Variants:**

*Product menu (with FeaturedCard)*
```tsx
<MegaMenu.Root id="product" openId={openId} onOpen={open} onScheduleClose={scheduleClose}>
  <MegaMenu.Trigger label="Product" isOpen={openId === 'product'} />
  {openId === 'product' && (
    <MegaMenu.Panel id="product" onOpen={open} onScheduleClose={scheduleClose} width="w-[560px]">
      ...
    </MegaMenu.Panel>
  )}
</MegaMenu.Root>
```

*Resources menu (2-column grid)*
```tsx
<MegaMenu.Section label="Resources">
  <div className="grid grid-cols-2 gap-0.5">
    {items.map((item) => <MegaMenu.Item key={item.label} {...item} iconVariant="neutral" />)}
  </div>
</MegaMenu.Section>
```

### JobStatusBadge  (`jobs-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/jobs/job/JobStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Displays job listing status with semantic colour coding.

**Variants:**

*All statuses*
```tsx
{(['DRAFT', 'PUBLISHED', 'PAUSED', 'CLOSED', 'ARCHIVED'] as const).map((s) => (
  <JobStatusBadge key={s} status={s} />
))}
```

*Sizes*
```tsx
<JobStatusBadge status="PUBLISHED" size="sm" />
<JobStatusBadge status="PUBLISHED" size="md" />
<JobStatusBadge status="PUBLISHED" size="lg" />
```

### JobTypeBadge  (`jobs-type-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/jobs/job/JobTypeBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Colour-coded badge for employment type (full-time, contract, etc.).

**Variants:**

*All types*
```tsx
{(['FULL_TIME', 'PART_TIME', 'CONTRACT', 'FREELANCE', 'INTERNSHIP'] as const).map((t) => (
  <JobTypeBadge key={t} type={t} />
))}
```

### JobWorkModeBadge  (`jobs-work-mode-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/jobs/job/JobWorkModeBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Icon + label badge for work location mode (remote, hybrid, on-site).

**Variants:**

*All modes*
```tsx
{(['REMOTE', 'HYBRID', 'ONSITE'] as const).map((m) => (
  <JobWorkModeBadge key={m} workMode={m} />
))}
```

### JobExperienceBadge  (`jobs-experience-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/jobs/job/JobExperienceBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Experience level badge mapping seniority to a semantic colour.

**Variants:**

*All levels*
```tsx
{(['JUNIOR', 'MID', 'SENIOR', 'LEAD', 'DIRECTOR'] as const).map((l) => (
  <JobExperienceBadge key={l} level={l} />
))}
```

### ApplicationStatusBadge  (`jobs-application-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/jobs/application/ApplicationStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Tracks an application's lifecycle from Pending through Offered or Rejected.

**Variants:**

*All statuses*
```tsx
{(['PENDING', 'REVIEWING', 'SHORTLISTED', 'INTERVIEW', 'OFFERED', 'REJECTED', 'WITHDRAWN'] as const).map((s) => (
  <ApplicationStatusBadge key={s} status={s} />
))}
```

### JobMeta  (`jobs-job-meta`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/jobs/job/JobMeta.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Inline metadata row: location, salary range, open positions, and posted date.

**Variants:**

*With salary*
```tsx
<JobMeta job={job} />
```

*Salary hidden*
```tsx
<JobMeta job={{ ...job, salaryVisible: false }} />
```

### JobCard  (`jobs-job-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/jobs/job/JobCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Summarises a job posting with company logo, title, badges, tags, and meta.

**Variants:**

*With link*
```tsx
<JobCard job={job} href="/jobs/slug" />
```

*No badges*
```tsx
<JobCard job={job} showBadges={false} />
```

### CompanyCard  (`jobs-company-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/jobs/company/CompanyCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Company profile card showing logo, name, industry, location, and open job count.

**Variants:**

*Verified with job count*
```tsx
<CompanyCard company={company} jobCount={3} href="/companies/slug" />
```

*Unverified, no count*
```tsx
<CompanyCard company={{ ...company, verified: false }} />
```

### WalletStatusBadge  (`fintech-wallet-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/wallet/WalletStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Displays wallet status with semantic colour coding: ACTIVE, FROZEN, CLOSED.

**Variants:**

*All statuses*
```tsx
{(['ACTIVE', 'FROZEN', 'CLOSED'] as const).map((s) => (
  <WalletStatusBadge key={s} status={s} />
))}
```

*Sizes*
```tsx
<WalletStatusBadge status="ACTIVE" size="sm" />
<WalletStatusBadge status="ACTIVE" size="md" />
```

### CurrencyBadge  (`fintech-currency-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/wallet/CurrencyBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Currency code badge with distinct colour per currency: TRY, USD, EUR, GBP, BTC, ETH.

**Variants:**

*All currencies*
```tsx
{(['TRY', 'USD', 'EUR', 'GBP', 'BTC', 'ETH'] as const).map((c) => (
  <CurrencyBadge key={c} currency={c} />
))}
```

*Small size*
```tsx
<CurrencyBadge currency="TRY" size="sm" />
<CurrencyBadge currency="USD" size="sm" />
<CurrencyBadge currency="EUR" size="sm" />
```

### TransactionTypeBadge  (`fintech-transaction-type-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/transaction/TransactionTypeBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Colour-coded badge for transaction type: DEPOSIT, WITHDRAW, TRANSFER, PAYMENT, REFUND, FX, FEE.

**Variants:**

*All types*
```tsx
{(['DEPOSIT', 'WITHDRAW', 'TRANSFER', 'PAYMENT', 'REFUND', 'FX', 'FEE'] as const).map((t) => (
  <TransactionTypeBadge key={t} type={t} />
))}
```

*Small size*
```tsx
<TransactionTypeBadge type="DEPOSIT" size="sm" />
<TransactionTypeBadge type="PAYMENT" size="sm" />
<TransactionTypeBadge type="REFUND" size="sm" />
```

### TransactionStatusBadge  (`fintech-transaction-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/transaction/TransactionStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Status badge tracking a transaction lifecycle: PENDING, COMPLETED, FAILED, CANCELLED.

**Variants:**

*All statuses*
```tsx
{(['PENDING', 'COMPLETED', 'FAILED', 'CANCELLED'] as const).map((s) => (
  <TransactionStatusBadge key={s} status={s} />
))}
```

*Small size*
```tsx
<TransactionStatusBadge status="COMPLETED" size="sm" />
<TransactionStatusBadge status="PENDING" size="sm" />
<TransactionStatusBadge status="FAILED" size="sm" />
```

### WalletCard  (`fintech-wallet-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/wallet/WalletCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Wallet card displaying balance, currency, status, and account reference with a premium gradient look.

**Variants:**

*Active primary (TRY)*
```tsx
<WalletCard wallet={wallet} />
```

*Frozen wallet (EUR)*
```tsx
<WalletCard wallet={{ ...wallet, status: 'FROZEN' }} />
```

*USD wallet*
```tsx
<WalletCard wallet={usdWallet} />
```

### TransactionRow  (`fintech-transaction-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/transaction/TransactionRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Transaction list row with icon, description, date, amount (coloured by direction), and status badge.

**Variants:**

*Completed deposit*
```tsx
<TransactionRow transaction={depositTransaction} />
```

*Mixed statuses*
```tsx
<TransactionRow transaction={depositTx} />
<TransactionRow transaction={paymentTx} />
<TransactionRow transaction={failedTx} />
```

### PortfolioHoldingRow  (`fintech-portfolio-holding-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/portfolio/PortfolioHoldingRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Portfolio table row: currency badge, name, holding amount, USD value, 24h delta, P&L.

**Variants:**

*Profit / loss rows*
```tsx
<PortfolioHoldingRow symbol="BTC" amount={0.05} currency="BTC" usdValue={3421} costBasis={2980} dayChangePct={2.34} />
```

*No cost basis (no P&L)*
```tsx
<PortfolioHoldingRow symbol="USD" amount={3420} currency="USD" usdValue={3420} />
```

### AssetAllocationCard  (`fintech-asset-allocation-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/portfolio/AssetAllocationCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Donut chart + total / change header. Self-contained portfolio summary tile.

**Variants:**

*Positive change*
```tsx
<AssetAllocationCard assets={[...]} changePct={4.2} changeAbsUsd={552} />
```

*Negative change*
```tsx
<AssetAllocationCard assets={[...]} changePct={-2.8} changeAbsUsd={-72} />
```

### PerformanceSparkline  (`fintech-performance-sparkline`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/portfolio/PerformanceSparkline.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Inline sparkline + percent change label. Auto-colors green / red based on net change.

**Variants:**

*Trending up*
```tsx
<PerformanceSparkline series={[10840, ..., 11516]} />
```

*Trending down*
```tsx
<PerformanceSparkline series={[12500, ..., 11450]} />
```

### PaymentCardTile  (`fintech-payment-card-tile`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/card/PaymentCardTile.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Skeuomorphic payment card tile with scheme brand, kind icon (virtual / physical), and status badge.

**Variants:**

*Three states*
```tsx
<PaymentCardTile nickname="…" scheme="visa" kind="physical" status="active" last4="4291" expiry="11/28" />
```

*Virtual card*
```tsx
<PaymentCardTile scheme="mastercard" kind="virtual" status="active" />
```

### CardLimitMeter  (`fintech-card-limit-meter`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/card/CardLimitMeter.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Progress bar showing spend vs. limit. Color shifts at warning + over-limit thresholds.

**Variants:**

*Three thresholds*
```tsx
<CardLimitMeter spent={920} limit={3000} currency="USD" />
```

### CardActionMenu  (`fintech-card-action-menu`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/fintech/card/CardActionMenu.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Three-dot menu with status-aware actions (freeze / unfreeze / show / limits / delete).

**Variants:**

*Active card menu*
```tsx
<CardActionMenu status="active" onFreeze={...} onShowDetails={...} onUpdateLimits={...} onDelete={...} />
```

*Frozen card menu*
```tsx
<CardActionMenu status="frozen" onUnfreeze={...} onShowDetails={...} />
```

### ProductStatusBadge  (`commerce-product-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/commerce/product/ProductStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Displays product lifecycle status with semantic colour coding.

**Variants:**

*All statuses*
```tsx
{(['DRAFT', 'PUBLISHED', 'ARCHIVED', 'OUT_OF_STOCK'] as const).map((s) => (
  <ProductStatusBadge key={s} status={s} />
))}
```

*Sizes*
```tsx
<ProductStatusBadge status="PUBLISHED" size="sm" />
<ProductStatusBadge status="PUBLISHED" size="md" />
```

### ProductTypeBadge  (`commerce-product-type-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/commerce/product/ProductTypeBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Colour-coded badge for product type: Physical, Digital, or Service.

**Variants:**

*All types*
```tsx
{(['PHYSICAL', 'DIGITAL', 'SERVICE'] as const).map((t) => (
  <ProductTypeBadge key={t} type={t} />
))}
```

*Small size*
```tsx
{(['PHYSICAL', 'DIGITAL', 'SERVICE'] as const).map((t) => (
  <ProductTypeBadge key={t} type={t} size="sm" />
))}
```

### StockStatusBadge  (`commerce-stock-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/commerce/product/StockStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Inventory status badge mapping stock levels to semantic colours.

**Variants:**

*All stock statuses*
```tsx
{(['IN_STOCK', 'LOW_STOCK', 'OUT_OF_STOCK', 'BACKORDER'] as const).map((s) => (
  <StockStatusBadge key={s} status={s} />
))}
```

*Small size*
```tsx
{(['IN_STOCK', 'LOW_STOCK', 'OUT_OF_STOCK', 'BACKORDER'] as const).map((s) => (
  <StockStatusBadge key={s} status={s} size="sm" />
))}
```

### OrderStatusBadge  (`commerce-order-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/commerce/order/OrderStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Tracks an order through its full lifecycle from Pending to Delivered or Refunded.

**Variants:**

*All statuses*
```tsx
{(['PENDING', 'CONFIRMED', 'PAID', 'PROCESSING', 'SHIPPED', 'DELIVERED', 'CANCELLED', 'REFUNDED'] as const).map((s) => (
  <OrderStatusBadge key={s} status={s} />
))}
```

*Small size*
```tsx
{(['PENDING', 'SHIPPED', 'DELIVERED', 'CANCELLED'] as const).map((s) => (
  <OrderStatusBadge key={s} status={s} size="sm" />
))}
```

### ProductCard  (`commerce-product-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/commerce/product/ProductCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Product card with image, price, type and stock badges, and tags.

**Variants:**

*Physical product with link*
```tsx
<ProductCard product={product} href="/products/slug" />
```

*Digital product with sale price*
```tsx
<ProductCard product={{ ...product, salePrice: 199 }} href="/products/slug" />
```

### OrderCard  (`commerce-order-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/commerce/order/OrderCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Compact order row showing order number, status badge, item count, and total.

**Variants:**

*Delivered order with link*
```tsx
<OrderCard order={order} href="/orders/id" />
```

*Pending order (no link)*
```tsx
<OrderCard order={order} />
```

### CartItem  (`commerce-cart-item`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/commerce/cart/CartItem.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Cart line item row with product image, name, quantity, unit price, and remove action.

**Variants:**

*Single item with remove*
```tsx
<CartItem item={item} onRemove={() => removeItem(item.productId)} />
```

*Multi-quantity item*
```tsx
<CartItem item={{ ...item, quantity: 2 }} />
```

### WishlistItemCard  (`commerce-wishlist-item-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/commerce/wishlist/WishlistItemCard.tsx`
- **Status:** stable
- **Description:** Wishlist row card: product image, current price, sale strikethrough, price-drop badge, move-to-cart and remove actions.

**Variants:**

*On sale with price drop*
```tsx
<WishlistItemCard item={{ …, salePrice: 279, priceWhenAdded: 349 }} onMoveToCart={…} onRemove={…} />
```

*Out of stock*
```tsx
<WishlistItemCard item={{ …, stockStatus: 'OUT_OF_STOCK' }} onMoveToCart={…} onRemove={…} />
```

### EmptyWishlistState  (`commerce-empty-wishlist-state`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/commerce/wishlist/EmptyWishlistState.tsx`
- **Status:** stable
- **Description:** Empty state for an empty wishlist with an optional recommendations grid.

**Variants:**

*With recommendations*
```tsx
<EmptyWishlistState recommendations={[…]} />
```

*Minimal*
```tsx
<EmptyWishlistState browseHref="/products" />
```

### ProductImageGallery  (`commerce-product-image-gallery`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/commerce/product/ProductImageGallery.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Product image viewer: large main image with a thumbnail strip below. Hovering a thumbnail instantly swaps the main image via crossfade. When the image count exceeds thumbsVisible (default 5), the strip grows left/right arrows and becomes a slider.

**Variants:**

*4 görsel — thumbnail strip*
```tsx
<ProductImageGallery
  images={[
    { src: '/front.jpg',   alt: 'Front view' },
    { src: '/side.jpg',    alt: 'Side view' },
    { src: '/on-desk.jpg', alt: 'On desk' },
    { src: '/profile.jpg', alt: 'Profile' },
  ]}
  thumbsVisible={5}
/>
```

*8 görsel — slider aktif*
```tsx
// 8 images, thumbsVisible=5 → arrows appear automatically
<ProductImageGallery
  images={productImages}
  thumbsVisible={5}
/>
```

*Video aspect ratio*
```tsx
<ProductImageGallery
  images={productImages}
  aspect="video"
  thumbsVisible={5}
/>
```

### VideoStatusBadge  (`media-video-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/media/video/VideoStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Displays video lifecycle status with semantic colour coding.

**Variants:**

*All statuses*
```tsx
{(['DRAFT', 'PROCESSING', 'PUBLISHED', 'PRIVATE', 'UNLISTED', 'BLOCKED', 'DELETED'] as const).map((s) => (
  <VideoStatusBadge key={s} status={s} />
))}
```

*Sizes*
```tsx
<VideoStatusBadge status="PUBLISHED" size="sm" />
<VideoStatusBadge status="PUBLISHED" size="md" />
```

### VideoCard  (`media-video-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/media/video/VideoCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Thumbnail card for a video: 16:9 image, duration overlay, title, channel, and view count.

**Variants:**

*Published with thumbnail*
```tsx
<VideoCard video={video} href="/videos/slug" />
```

*Draft, no thumbnail*
```tsx
<VideoCard video={{ ...video, status: 'DRAFT', thumbnailUrl: undefined }} />
```

### ChannelCard  (`media-channel-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/media/channel/ChannelCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Channel profile card: avatar, name, verified badge, subscriber count, and subscribe button.

**Variants:**

*Verified channel*
```tsx
<ChannelCard channel={channel} href="/channels" />
```

*Unverified channel*
```tsx
<ChannelCard channel={{ ...channel, verified: false }} />
```

### VideoMeta  (`media-video-meta`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/media/video/VideoMeta.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Inline metadata strip: view count, like count, duration, and relative publish date.

**Variants:**

*Full meta*
```tsx
<VideoMeta video={{ viewCount: 128400, likeCount: 5320, publishedAt: date, duration: 3842 }} />
```

*Views and date only*
```tsx
<VideoMeta video={{ viewCount: 2340000, publishedAt: date }} />
```

### ChannelStatsCard  (`media-channel-stats-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/media/channel/ChannelStatsCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Creator dashboard tile: 4 KPI metrics with deltas (subscribers, views, watch time, videos).

**Variants:**

*All four KPIs*
```tsx
<ChannelStatsCard channelName="CodeWithAlex" stats={[...]} />
```

*Negative deltas*
```tsx
<ChannelStatsCard channelName="WanderFar" period="Last 7 days" stats={[{ metric: 'subscribers', value: 728000, deltaPct: -0.6 }, { metric: 'views', value: 184000, deltaPct: -8.2 }]} />
```

### VideoPerformanceRow  (`media-video-performance-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/media/video/VideoPerformanceRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Dashboard row for a single video: thumbnail, title + status, views, watch time, CTR delta.

**Variants:**

*Trending up*
```tsx
<VideoPerformanceRow title="..." views={128400} watchTimeHours={12420} ctrPct={8.4} deltaPct={12.3} />
```

*Trending down*
```tsx
<VideoPerformanceRow title="..." views={84200} ctrPct={6.1} deltaPct={-3.4} />
```

### WatchTimeChart  (`media-watch-time-chart`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/media/chart/WatchTimeChart.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Smooth area chart showing daily watch hours over a period. Used in Creator Studio.

**Variants:**

*8-day window*
```tsx
<WatchTimeChart data={[{ date: 'Apr 20', hours: 4120 }, ...]} />
```

*Custom title*
```tsx
<WatchTimeChart title="Subscriber growth" subtitle="..." data={[...]} />
```

### PlaylistHeaderCard  (`media-playlist-header-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/media/playlist/PlaylistHeaderCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Playlist hero: cover image, visibility badge, total duration, owner channel, play / shuffle.

**Variants:**

*Public playlist*
```tsx
<PlaylistHeaderCard title="..." videoCount={3} totalDurationSeconds={12012} channel={{ name, handle, verified: true }} />
```

*Unlisted, no cover*
```tsx
<PlaylistHeaderCard title="..." visibility="UNLISTED" videoCount={3} totalDurationSeconds={6370} channel={{ name, handle }} />
```

### PlaylistVideoRow  (`media-playlist-video-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/media/playlist/PlaylistVideoRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Numbered playlist row: position, thumbnail with duration, title, channel, now-playing state.

**Variants:**

*Now playing + idle*
```tsx
<PlaylistVideoRow position={1} title="..." channelName="..." duration={3842} isPlaying />
```

*Draggable (reorderable)*
```tsx
<PlaylistVideoRow position={1} title="..." channelName="..." draggable />
```

### TopicStatusBadge  (`forum-topic-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/forum/topic/TopicStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Displays forum topic status with semantic colour coding — open, locked, pinned, archived, or deleted.

**Variants:**

*All statuses*
```tsx
{(['OPEN', 'LOCKED', 'PINNED', 'ARCHIVED', 'DELETED'] as const).map((s) => (
  <TopicStatusBadge key={s} status={s} />
))}
```

*Sizes*
```tsx
<TopicStatusBadge status="OPEN" size="sm" />
<TopicStatusBadge status="OPEN" size="md" />
```

### PostStatusBadge  (`forum-post-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/forum/post/PostStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Indicates the moderation state of a forum post: published, pending review, hidden, deleted, or spam.

**Variants:**

*All statuses*
```tsx
{(['PUBLISHED', 'PENDING_REVIEW', 'HIDDEN', 'DELETED', 'SPAM'] as const).map((s) => (
  <PostStatusBadge key={s} status={s} />
))}
```

*Sizes*
```tsx
<PostStatusBadge status="PUBLISHED" size="sm" />
<PostStatusBadge status="PUBLISHED" size="md" />
```

### ReactionTypeBadge  (`forum-reaction-type-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/forum/reaction/ReactionTypeBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Pill badge with icon and optional count for each forum reaction type: like, dislike, thanks, laugh, and confused.

**Variants:**

*All reaction types with counts*
```tsx
<ReactionTypeBadge type="LIKE"     count={88} />
<ReactionTypeBadge type="THANKS"   count={34} />
<ReactionTypeBadge type="LAUGH"    count={12} />
<ReactionTypeBadge type="CONFUSED" count={5} />
<ReactionTypeBadge type="DISLIKE"  count={2} />
```

*Sizes*
```tsx
<ReactionTypeBadge type="LIKE" count={42} size="sm" />
<ReactionTypeBadge type="LIKE" count={42} size="md" />
```

### ForumCategoryCard  (`forum-category-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/forum/category/ForumCategoryCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Hoverable card displaying a forum category with icon, description, topic/post stats, and last activity timestamp.

**Variants:**

*With stats and activity*
```tsx
<ForumCategoryCard category={category} href="/forum/tech-help" />
```

*Minimal (no stats)*
```tsx
<ForumCategoryCard category={{ categoryId, title, slug }} />
```

### TopicRow  (`forum-topic-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/forum/topic/TopicRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Horizontal list row for a forum topic showing title, status badges, pin/lock indicators, author, and reply/view counts.

**Variants:**

*Open topic*
```tsx
<TopicRow topic={topic} href="/forum/topics/slug" />
```

*Pinned and locked variants*
```tsx
<TopicRow topic={{ ...topic, status: 'PINNED', isPinned: true }} href="#" />
<TopicRow topic={{ ...topic, status: 'LOCKED', isLocked: true }} href="#" />
```

### ForumUserCard  (`forum-user-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/forum/user/ForumUserCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Profile card for a forum user: avatar with online dot, role badge, joined / posts / reputation.

**Variants:**

*Moderator, online*
```tsx
<ForumUserCard user={{ username: 'mod_jane', role: 'moderator', online: true, postCount: 892, reputation: 4280 }} />
```

*Regular member, offline*
```tsx
<ForumUserCard user={{ username: 'rustacean99', role: 'member', online: false }} />
```

### ReputationBar  (`forum-reputation-bar`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/forum/user/ReputationBar.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Progress bar with tiered milestones showing the user's reputation and distance to the next tier.

**Variants:**

*Mid-tier (Veteran)*
```tsx
<ReputationBar reputation={4280} />
```

*Max tier reached*
```tsx
<ReputationBar reputation={9200} />
```

### BadgeShelf  (`forum-badge-shelf`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/forum/user/BadgeShelf.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Grid of tiered forum badges (bronze / silver / gold) with optional earned counts.

**Variants:**

*Six earned badges*
```tsx
<BadgeShelf badges={[{ badgeId, name, tier: 'gold', icon: 'verified' }]} />
```

*Empty state*
```tsx
<BadgeShelf badges={[]} />
```

### UserActivityRow  (`forum-user-activity-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/forum/user/UserActivityRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Single activity entry in a user feed: kind icon, action verb, topic link, excerpt, time-ago.

**Variants:**

*All four kinds*
```tsx
<UserActivityRow kind="reply" topicTitle="…" topicHref="…" excerpt="…" createdAt={date} />
```

### PostComposer  (`forum-post-composer`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/forum/post/PostComposer.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Topic creation form: title + category + write/preview tabs + tag input. Composes UI primitives.

**Variants:**

*Default composer*
```tsx
<PostComposer categories={[{ value: 'tech-help', label: 'Tech Help' }]} />
```

*Pre-filled draft*
```tsx
<PostComposer initialTitle="…" initialBody="…" initialTags={['nextjs', 'devops']} />
```

### PropertyStatusBadge  (`real-estate-property-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/real-estate/property/PropertyStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Displays property listing status with semantic colour coding.

**Variants:**

*All statuses*
```tsx
{(['DRAFT', 'ACTIVE', 'PUBLISHED', 'SOLD', 'RENTED', 'ARCHIVED'] as const).map((s) => (
  <PropertyStatusBadge key={s} status={s} />
))}
```

*Sizes*
```tsx
<PropertyStatusBadge status="PUBLISHED" size="sm" />
<PropertyStatusBadge status="PUBLISHED" size="md" />
```

### PropertyTypeBadge  (`real-estate-property-type-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/real-estate/property/PropertyTypeBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Colour-coded badge for property type (Apartment, House, Villa, etc.).

**Variants:**

*All types*
```tsx
{(['APARTMENT', 'HOUSE', 'VILLA', 'LAND', 'COMMERCIAL', 'OFFICE'] as const).map((t) => (
  <PropertyTypeBadge key={t} type={t} />
))}
```

*Small size*
```tsx
<PropertyTypeBadge type="APARTMENT" size="sm" />
```

### ListingTypeBadge  (`real-estate-listing-type-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/real-estate/listing/ListingTypeBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Badge indicating listing intent: For Sale, For Rent, or Short-term.

**Variants:**

*All listing types*
```tsx
{(['SALE', 'RENT', 'SHORT_TERM'] as const).map((t) => (
  <ListingTypeBadge key={t} type={t} />
))}
```

*Small size*
```tsx
<ListingTypeBadge type="SALE" size="sm" />
<ListingTypeBadge type="RENT" size="sm" />
```

### PropertyCard  (`real-estate-property-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/real-estate/property/PropertyCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Summarises a property listing with image, price, type badges, specs, and location.

**Variants:**

*For sale with image*
```tsx
<PropertyCard property={property} href="/properties/slug" />
```

*Rental — no image (gradient placeholder)*
```tsx
<PropertyCard property={{ ...property, imageUrl: null }} />
```

*Short-term villa*
```tsx
<PropertyCard property={villa} href="/properties/slug" />
```

### AgentCard  (`real-estate-agent-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/real-estate/agent/AgentCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Real estate agent profile card with avatar, contact info, bio, and listing count.

**Variants:**

*Full profile*
```tsx
<AgentCard agent={agent} />
```

*Minimal (no bio, no phone)*
```tsx
<AgentCard agent={{ agentId, name, email }} />
```

### RestaurantStatusBadge  (`food-restaurant-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/restaurant/RestaurantStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Displays restaurant operational status with semantic colour coding.

**Variants:**

*All statuses*
```tsx
{(['ACTIVE', 'INACTIVE', 'CLOSED'] as const).map((s) => (
  <RestaurantStatusBadge key={s} status={s} />
))}
```

*Sizes*
```tsx
<RestaurantStatusBadge status="ACTIVE" size="sm" />
<RestaurantStatusBadge status="ACTIVE" size="md" />
```

### OrderStatusBadge  (`food-order-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/order/OrderStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Tracks a food order through its full lifecycle with semantic colours.

**Variants:**

*All statuses*
```tsx
{(['PENDING', 'ACCEPTED', 'PREPARING', 'READY', 'PICKED_UP', 'ON_THE_WAY', 'DELIVERED', 'CANCELLED', 'REFUNDED'] as const).map((s) => (
  <OrderStatusBadge key={s} status={s} />
))}
```

*Key states*
```tsx
<OrderStatusBadge status="PREPARING" size="sm" />
<OrderStatusBadge status="DELIVERED" size="sm" />
<OrderStatusBadge status="CANCELLED" size="sm" />
```

### DeliveryStatusBadge  (`food-delivery-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/order/DeliveryStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Shows courier delivery progress from assignment through completion.

**Variants:**

*All statuses*
```tsx
{(['PENDING', 'ASSIGNED', 'PICKED_UP', 'ON_THE_WAY', 'DELIVERED', 'FAILED'] as const).map((s) => (
  <DeliveryStatusBadge key={s} status={s} />
))}
```

*Sizes*
```tsx
<DeliveryStatusBadge status="ON_THE_WAY" size="sm" />
<DeliveryStatusBadge status="ON_THE_WAY" size="md" />
```

### RestaurantCard  (`food-restaurant-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/restaurant/RestaurantCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Hoverable restaurant summary card with gradient image placeholder, cuisine tags, star rating, and delivery estimate.

**Variants:**

*Active with link*
```tsx
<RestaurantCard restaurant={restaurant} href="/restaurants/slug" />
```

*Closed restaurant*
```tsx
<RestaurantCard restaurant={{ ...restaurant, status: 'CLOSED' }} />
```

### MenuItemCard  (`food-menu-item-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/menu/MenuItemCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Horizontal menu item card showing name, description, dietary badges, calories, price, and an add-to-cart button.

**Variants:**

*Vegetarian with add to cart*
```tsx
<MenuItemCard item={item} onAddToCart={() => addToCart(item)} />
```

*Vegan item*
```tsx
<MenuItemCard item={{ ...item, isVegan: true }} onAddToCart={() => addToCart(item)} />
```

*Out of stock*
```tsx
<MenuItemCard item={{ ...item, status: 'OUT_OF_STOCK' }} />
```

### OrderTrackingTimeline  (`food-order-tracking-timeline`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/order/OrderTrackingTimeline.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Vertical timeline of order milestones (placed → preparing → on the way → delivered) with timestamps.

**Variants:**

*In progress*
```tsx
<OrderTrackingTimeline steps={[{ key: 'PLACED', ... }, { key: 'ON_THE_WAY', isCurrent: true }, { key: 'DELIVERED' }]} />
```

*Cancelled*
```tsx
<OrderTrackingTimeline steps={[{ key: 'PLACED', ... }, { key: 'CANCELLED', occurredAt: date }]} />
```

### CourierCard  (`food-courier-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/order/CourierCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Delivery courier summary: avatar with online dot, vehicle, rating, and call / message actions.

**Variants:**

*Scooter, online*
```tsx
<CourierCard courier={{ name, vehicle: 'scooter', rating: 4.9, online: true }} onCall={...} />
```

*Bike, no actions*
```tsx
<CourierCard courier={{ name, vehicle: 'bike', rating: 4.78, online: false }} />
```

### EtaCountdownCard  (`food-eta-countdown-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/order/EtaCountdownCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Live ETA tile: shows minutes remaining and arrival clock time. Auto-refreshes every 30s.

**Variants:**

*Default*
```tsx
<EtaCountdownCard estimatedArrival={isoString} destinationLabel="..." />
```

*Urgent (≤ 5 min)*
```tsx
<EtaCountdownCard estimatedArrival={near} variant="urgent" />
```

### CuisineHeroBanner  (`food-cuisine-hero-banner`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/cuisine/CuisineHeroBanner.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Hero banner for a cuisine landing page: icon, headline, description, key stats over a tinted image.

**Variants:**

*Italian*
```tsx
<CuisineHeroBanner cuisine="Italian" icon="pizza" description="..." restaurantCount={12} averageRating={4.7} averageDeliveryMin={32} />
```

*No image, gradient fallback*
```tsx
<CuisineHeroBanner cuisine="Japanese" icon="bowl" description="…" />
```

### CuisineTagChip  (`food-cuisine-tag-chip`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/cuisine/CuisineTagChip.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Pill button for cuisine filtering. Supports selected state and an optional result count badge.

**Variants:**

*Selected + neutral*
```tsx
<CuisineTagChip label="Italian" selected count={12} />
```

*Without counts*
```tsx
<CuisineTagChip label="Healthy" selected />
```

### FeaturedDishCard  (`food-featured-dish-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/food/menu/FeaturedDishCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Featured/promoted dish tile: large image, restaurant attribution, rating, prep time, optional badges.

**Variants:**

*Chef pick*
```tsx
<FeaturedDishCard name="Margherita Pizza" restaurantName="Bella Napoli" price={14.5} currency="USD" badge="Chef pick" />
```

*Hot, no badge*
```tsx
<FeaturedDishCard name="Spicy Tonkotsu Ramen" restaurantName="Sakura Bento" price={15.5} currency="USD" hot />
```

### BookingStatusBadge  (`travel-booking-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/travel/booking/BookingStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Displays travel booking lifecycle status with semantic colour coding.

**Variants:**

*All statuses*
```tsx
{(['DRAFT', 'PENDING', 'CONFIRMED', 'PAID', 'CANCELLED', 'REFUNDED', 'COMPLETED'] as const).map((s) => (
  <BookingStatusBadge key={s} status={s} />
))}
```

*Sizes*
```tsx
<BookingStatusBadge status="PAID" size="sm" />
<BookingStatusBadge status="PAID" size="md" />
```

### FlightCabinBadge  (`travel-flight-cabin-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/travel/flight/FlightCabinBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Colour-coded badge for flight cabin class (Economy through First).

**Variants:**

*All cabins*
```tsx
{(['ECONOMY', 'PREMIUM_ECONOMY', 'BUSINESS', 'FIRST'] as const).map((c) => (
  <FlightCabinBadge key={c} cabin={c} />
))}
```

*Small size*
```tsx
{(['ECONOMY', 'PREMIUM_ECONOMY', 'BUSINESS', 'FIRST'] as const).map((c) => (
  <FlightCabinBadge key={c} cabin={c} size="sm" />
))}
```

### FlightSegmentStatusBadge  (`travel-flight-segment-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/travel/flight/FlightSegmentStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Real-time flight segment status badge (Scheduled, Delayed, Departed, etc.).

**Variants:**

*All statuses*
```tsx
{(['SCHEDULED', 'DELAYED', 'CANCELLED', 'DEPARTED', 'ARRIVED'] as const).map((s) => (
  <FlightSegmentStatusBadge key={s} status={s} />
))}
```

*Small size*
```tsx
{(['SCHEDULED', 'DELAYED', 'ARRIVED'] as const).map((s) => (
  <FlightSegmentStatusBadge key={s} status={s} size="sm" />
))}
```

### FlightCard  (`travel-flight-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/travel/flight/FlightCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Flight summary card with route, airline, cabin class, status, and price.

**Variants:**

*Economy — scheduled*
```tsx
<FlightCard flight={flight} href="/theme/travel/flights/tk-123" />
```

*Business — delayed*
```tsx
<FlightCard flight={flight} />
```

### HotelCard  (`travel-hotel-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/travel/hotel/HotelCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Hotel summary card with image, star rating, guest score, location, and price per night.

**Variants:**

*With image*
```tsx
<HotelCard hotel={hotel} href="/theme/travel/hotels/grand-pera-palace" />
```

*No image (gradient placeholder)*
```tsx
<HotelCard hotel={{ ...hotel, imageUrl: null }} />
```

### ModelProviderBadge  (`ai-model-provider-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/ai/model/ModelProviderBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Colour-coded badge that maps an AI provider name to a semantic variant.

**Variants:**

*All providers*
```tsx
{(['OPENAI', 'ANTHROPIC', 'GOOGLE', 'XAI', 'DEEPSEEK', 'AZURE_OPENAI', 'CUSTOM'] as const).map((p) => (
  <ModelProviderBadge key={p} provider={p} />
))}
```

*Small size*
```tsx
<ModelProviderBadge provider="OPENAI" size="sm" />
```

### ModelTypeBadge  (`ai-model-type-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/ai/model/ModelTypeBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Badge indicating the modality of an AI model (Text, Image, Embedding, etc.).

**Variants:**

*All types*
```tsx
{(['TEXT', 'IMAGE', 'EMBEDDING', 'AUDIO', 'VIDEO'] as const).map((t) => (
  <ModelTypeBadge key={t} type={t} />
))}
```

*Small size*
```tsx
<ModelTypeBadge type="TEXT" size="sm" />
```

### ModelCard  (`ai-model-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/ai/model/ModelCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Card summarising an AI model with provider, type badges, context window, and pricing.

**Variants:**

*Active text model with link*
```tsx
<ModelCard model={model} href="/models/gpt-4o" />
```

*Inactive image model*
```tsx
<ModelCard model={model} />
```

### AIJobStatusBadge  (`ai-job-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/ai/job/AIJobStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Dot + label badge tracking the lifecycle of an async AI job.

**Variants:**

*All statuses*
```tsx
{(['PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CANCELLED'] as const).map((s) => (
  <AIJobStatusBadge key={s} status={s} />
))}
```

*Small size*
```tsx
<AIJobStatusBadge status="COMPLETED" size="sm" />
```

### ChatMessage  (`ai-chat-message`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/ai/chat/ChatMessage.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Chat bubble for AI conversations — USER bubbles are right-aligned (primary bg), ASSISTANT bubbles are left-aligned (surface-raised).

**Variants:**

*User message*
```tsx
<ChatMessage message={{ role: 'USER', content: '...' }} />
```

*Assistant message*
```tsx
<ChatMessage message={{ role: 'ASSISTANT', content: '...' }} />
```

### FeatureCheckCell  (`ai-feature-check-cell`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/ai/compare/FeatureCheckCell.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Pill-style indicator for feature-support cells in comparison tables (yes/no/partial/preview).

**Variants:**

*All states*
```tsx
<FeatureCheckCell value="yes" />
<FeatureCheckCell value="no" />
<FeatureCheckCell value="partial" />
<FeatureCheckCell value="preview" />
```

*Custom labels*
```tsx
<FeatureCheckCell value="yes" label="Supported" />
```

### ModelScoreSparkline  (`ai-model-score-sparkline`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/ai/compare/ModelScoreSparkline.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Compact inline sparkline for AI model benchmark scores over time.

**Variants:**

*Upward trend*
```tsx
<ModelScoreSparkline scores={[62, 68, 71, 78, 81, 84, 86, 88]} label="MMLU" />
```

*Wider canvas*
```tsx
<ModelScoreSparkline scores={[…]} width={220} height={48} label="GSM8K" />
```

### ModelComparisonTable  (`ai-model-comparison-table`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/ai/compare/ModelComparisonTable.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Side-by-side table comparing AI models across price, context, benchmarks, and feature support.

**Variants:**

*Three models compared*
```tsx
<ModelComparisonTable rows={rows} featureKeys={featureKeys} />
```

*Two models only*
```tsx
<ModelComparisonTable rows={rows.slice(0, 2)} featureKeys={featureKeys} />
```

### UsageStatsCard  (`ai-usage-stats-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/ai/usage/UsageStatsCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Card displaying prompt tokens, completion tokens, and cost for a single AI usage record.

**Variants:**

*GPT-4o usage*
```tsx
<UsageStatsCard usage={usage} />
```

*Low-cost model*
```tsx
<UsageStatsCard usage={cheapUsage} />
```

### PostStatusBadge  (`social-post-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/social/post/PostStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Displays the publication status of a social post — published, draft, archived, or deleted.

**Variants:**

*All statuses*
```tsx
{(['PUBLISHED', 'DRAFT', 'ARCHIVED', 'DELETED'] as const).map((s) => (
  <PostStatusBadge key={s} status={s} />
))}
```

*Small size*
```tsx
<PostStatusBadge status="PUBLISHED" size="sm" />
<PostStatusBadge status="DRAFT" size="sm" />
```

### PostPrivacyBadge  (`social-post-privacy-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/social/post/PostPrivacyBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Compact icon (+ optional label) showing post visibility — public, friends only, or private.

**Variants:**

*Icon + label*
```tsx
<PostPrivacyBadge privacy="PUBLIC"  showLabel />
<PostPrivacyBadge privacy="FRIENDS" showLabel />
<PostPrivacyBadge privacy="PRIVATE" showLabel />
```

*Icon only*
```tsx
<PostPrivacyBadge privacy="PUBLIC" />
<PostPrivacyBadge privacy="FRIENDS" />
<PostPrivacyBadge privacy="PRIVATE" />
```

### PostCard  (`social-post-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/social/post/PostCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Social media post card with author info, text content, optional media grid, and like / comment / share / bookmark actions.

**Variants:**

*Text post (liked)*
```tsx
<PostCard post={{
  postId: 'post-01',
  content: 'Just shipped a new open-source design system…',
  privacy: 'PUBLIC',
  likeCount: 248, commentCount: 34, shareCount: 71,
  isLiked: true, isBookmarked: false,
  author: { name: 'Lena Fischer', username: 'lena_design', isVerified: true, ... },
}} />
```

*Image post (friends only)*
```tsx
<PostCard post={{
  postId: 'post-02',
  content: 'Morning vibes from the home office ☕',
  privacy: 'FRIENDS',
  mediaUrls: ['https://picsum.photos/seed/office1/600/400', ...],
  likeCount: 92, commentCount: 8, shareCount: 3,
  isBookmarked: true,
  author: { name: 'Marco Rossi', username: 'marco_dev', ... },
}} />
```

### SocialProfileCard  (`social-profile-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/social/profile/SocialProfileCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** User profile card with cover image, avatar, bio, location, website, follower / following stats, and follow / message actions.

**Variants:**

*Full profile — other user*
```tsx
<SocialProfileCard user={{
  userId: 'user-01',
  name: 'Lena Fischer',
  username: 'lena_design',
  bio: 'Product designer & creative coder.',
  location: 'Berlin, Germany',
  website: 'https://lena.design',
  followerCount: 12400, followingCount: 320, postCount: 284,
  isVerified: true, isFollowing: false,
}} />
```

*Own profile (edit button)*
```tsx
<SocialProfileCard user={user} isOwnProfile />
```

### SocialNotificationItem  (`social-notification-item`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/social/notification/SocialNotificationItem.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Notification list item showing actor avatar, type icon overlay, message and timestamp. Unread items have a distinct background and dot indicator.

**Variants:**

*Unread (like) + Read (follow)*
```tsx
<div className="border border-border rounded-xl overflow-hidden divide-y divide-border">
  <SocialNotificationItem notification={{ type: 'LIKE',   isRead: false, actor: user, message: 'liked your post', ... }} />
  <SocialNotificationItem notification={{ type: 'FOLLOW', isRead: true,  actor: user, message: 'started following you', ... }} />
</div>
```

*All notification types*
```tsx
{(['LIKE', 'COMMENT', 'FOLLOW', 'MENTION', 'SHARE'] as const).map((type) => (
  <SocialNotificationItem key={type} notification={{ type, isRead: false, actor: user, ... }} />
))}
```

### MarketplaceListingCard  (`social-marketplace-listing-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/social/marketplace/MarketplaceListingCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Compact listing card for the peer-to-peer marketplace: thumbnail, price, condition badge, location, and seller info.

**Variants:**

*Two listings side by side*
```tsx
<div className="grid grid-cols-2 gap-3">
  <MarketplaceListingCard listing={listing1} />
  <MarketplaceListingCard listing={listing2} />
</div>
```

*Single card*
```tsx
<MarketplaceListingCard listing={listing} href="/marketplace/listing-01" />
```

### DeviceStatusBadge  (`iot-device-status-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/device/DeviceStatusBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Displays device connectivity state — Online, Offline, Error, or Maintenance.

**Variants:**

*All states*
```tsx
<DeviceStatusBadge status="ONLINE" />
<DeviceStatusBadge status="OFFLINE" />
<DeviceStatusBadge status="ERROR" />
<DeviceStatusBadge status="MAINTENANCE" />
```

*Small size*
```tsx
<DeviceStatusBadge status="ONLINE" size="sm" />
<DeviceStatusBadge status="ERROR" size="sm" />
```

### DeviceTypeBadge  (`iot-device-type-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/device/DeviceTypeBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Indicates device origin — Internal first-party hardware, third-party Integration, or External feed.

**Variants:**

*All types*
```tsx
<DeviceTypeBadge type="INTERNAL" />
<DeviceTypeBadge type="INTEGRATION" />
<DeviceTypeBadge type="EXTERNAL" />
```

*Small size*
```tsx
<DeviceTypeBadge type="INTERNAL" size="sm" />
<DeviceTypeBadge type="INTEGRATION" size="sm" />
```

### AlertSeverityBadge  (`iot-alert-severity-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/alert/AlertSeverityBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Alert severity indicator — Info, Warning, or Critical.

**Variants:**

*All severities*
```tsx
<AlertSeverityBadge severity="INFO" />
<AlertSeverityBadge severity="WARNING" />
<AlertSeverityBadge severity="CRITICAL" />
```

*Small*
```tsx
<AlertSeverityBadge severity="WARNING" size="sm" />
<AlertSeverityBadge severity="CRITICAL" size="sm" />
```

### DeviceCard  (`iot-device-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/device/DeviceCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Compact device summary card showing status, type, location, last-seen time and tags.

**Variants:**

*Online device*
```tsx
<DeviceCard device={device} />
```

*Error + Gateway*
```tsx
<DeviceCard device={errorDevice} />
<DeviceCard device={gatewayDevice} />
```

### CloudWorkspaceCard  (`iot-cloud-workspace-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/workspace/CloudWorkspaceCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Cloud workspace overview card — status, plan, device counts with online progress bar.

**Variants:**

*Active workspace*
```tsx
<CloudWorkspaceCard workspace={workspace} />
```

*Suspended workspace*
```tsx
<CloudWorkspaceCard workspace={suspendedWorkspace} />
```

### RulesetEditor  (`iot-ruleset-editor`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/ruleset/RulesetEditor/index.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Drag-and-drop visual rule chain editor — build telemetry pipelines with Trigger, Filter, Switch, Transform, and Action nodes.

**Variants:**

*With pre-loaded chain*
```tsx
<RulesetEditor
  initialNodes={nodes}
  initialEdges={edges}
/>
```

*Empty canvas (editable)*
```tsx
<RulesetEditor />
```

### MetricSparklineCard  (`iot-metric-sparkline-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/telemetry/MetricSparklineCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** KPI tile with current value, unit, delta-vs-prev, and an inline SVG sparkline. No deps.

**Variants:**

*Four KPIs*
```tsx
<MetricSparklineCard label="CPU" value={36} unit="%" series={[...]} deltaPct={5.2} goodWhen="down" />
```

*No delta*
```tsx
<MetricSparklineCard label="Idle metric" value="—" series={[1,1,1,1]} />
```

### TelemetryTimeSeriesChart  (`iot-telemetry-time-series-chart`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/telemetry/TelemetryTimeSeriesChart.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Multi-line time-series chart built on chart.js. Supports any number of series with custom colors.

**Variants:**

*Vibration / Temp / RPM*
```tsx
<TelemetryTimeSeriesChart title="..." labels={[...]} series={[{ label, color, data }, ...]} />
```

### LogStreamRow  (`iot-log-stream-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/telemetry/LogStreamRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Monospace log entry: timestamp, level tag (DBG/INF/WRN/ERR/FTL), source, and message body.

**Variants:**

*All five levels*
```tsx
<LogStreamRow timestamp={date} level="warn" source="..." message="..." />
```

### AlertDetailHeader  (`iot-alert-detail-header`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/alert/AlertDetailHeader.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Header for an alert detail page: severity + status badges, device link, opened timestamp, action buttons.

**Variants:**

*Critical / open*
```tsx
<AlertDetailHeader title="…" severity="CRITICAL" status="OPEN" deviceName="…" openedAt={date} />
```

*Warning / acknowledged*
```tsx
<AlertDetailHeader severity="WARNING" status="ACKNOWLEDGED" />
```

### AlertEventTimeline  (`iot-alert-event-timeline`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/iot/alert/AlertEventTimeline.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Chronological event log for an alert: opened → acknowledged → resolved, with operator notes.

**Variants:**

*Five event kinds*
```tsx
<AlertEventTimeline events={[{ kind: 'opened', ... }, { kind: 'resolved', ... }]} />
```

### RarityBadge  (`nft-rarity-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/asset/RarityBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Tier-coloured badge — Common, Uncommon, Rare, Epic, Legendary, Mythic.

**Variants:**

*All tiers*
```tsx
<RarityBadge tier="COMMON" />
<RarityBadge tier="MYTHIC" />
```

*With rank*
```tsx
<RarityBadge tier="LEGENDARY" rank={12} />
<RarityBadge tier="MYTHIC" rank={1} size="sm" />
```

### BlockchainBadge  (`nft-blockchain-badge`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/wallet/BlockchainBadge.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Chain pill — Ethereum, Polygon, Solana, Base, Arbitrum.

**Variants:**

*All chains*
```tsx
<BlockchainBadge chain="ETHEREUM" />
<BlockchainBadge chain="POLYGON" />
```

*Icon-only*
```tsx
<BlockchainBadge chain="ETHEREUM" iconOnly />
```

### PriceTag  (`nft-price-tag`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/asset/PriceTag.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Dual ETH / USD price display with optional last-sale delta arrow.

**Variants:**

*Listed with delta*
```tsx
<PriceTag label="Current price" priceEth={0.85} priceUsd={2635} lastSalePriceEth={0.72} size="lg" />
```

*Sizes*
```tsx
<PriceTag label="Md" priceEth={0.42} priceUsd={1300} size="md" />
```

### TraitTag  (`nft-trait-tag`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/asset/TraitTag.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Single trait chip — type, value, and rarity percentage.

**Variants:**

*Trait grid*
```tsx
<TraitTag trait={{ traitType: 'Form', value: 'Crystalline', rarityPercent: 0.3 }} />
```

*Without rarity*
```tsx
<TraitTag trait={{ traitType: 'Ring', value: 'Triple' }} />
```

### NftCard  (`nft-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/asset/NftCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Image-forward NFT tile — thumbnail, name, price, like + view counters, status pill.

**Variants:**

*Listed*
```tsx
<NftCard asset={asset} href="/theme/nft/assets/abc" />
```

*Live auction*
```tsx
<NftCard asset={auctionAsset} />
```

### NftDetailHeader  (`nft-detail-header`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/asset/NftDetailHeader.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Asset page header — collection link, name, token id, owner, share / like actions.

**Variants:**

*Full header*
```tsx
<NftDetailHeader asset={asset} collectionName="Glyph Genesis" collectionSlug="glyph-genesis" />
```

### CollectionCard  (`nft-collection-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/collection/CollectionCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Collection tile — banner + avatar, floor, 24h volume, chain badge.

**Variants:**

*Verified collection*
```tsx
<CollectionCard collection={collection} href="/theme/nft/collections/glyph-genesis" />
```

*Falling floor*
```tsx
<CollectionCard collection={{ ...c, volumeChange24hPct: -8.4 }} />
```

### CollectionStatsBar  (`nft-collection-stats-bar`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/collection/CollectionStatsBar.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Horizontal stat strip — floor, volume, items, owners, listed %.

**Variants:**

*Default*
```tsx
<CollectionStatsBar collection={collection} />
```

### FloorPriceChart  (`nft-floor-price-chart`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/collection/FloorPriceChart.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Time-series chart of collection floor price over a configurable window.

**Variants:**

*14-day window*
```tsx
<FloorPriceChart points={floorHistory} height={200} />
```

### CreatorProfileCard  (`nft-creator-profile-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/creator/CreatorProfileCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Creator block — avatar, handle, verified, wallet, follower count, social links.

**Variants:**

*Not following*
```tsx
<CreatorProfileCard creator={creator} onFollowToggle={fn} />
```

*Following*
```tsx
<CreatorProfileCard creator={creator} following onFollowToggle={fn} />
```

### CreatorLeaderboardRow  (`nft-creator-leaderboard-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/creator/CreatorLeaderboardRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Ranked row — rank chip, avatar, handle, volume, 24h change.

**Variants:**

*Top 3 leaderboard*
```tsx
<CreatorLeaderboardRow rank={1} creator={creator} changePct={12.4} />
```

### ActivityFeedRow  (`nft-activity-feed-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/activity/ActivityFeedRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Single activity event — kind icon, asset thumb, parties, price, chain, time.

**Variants:**

*Sale event*
```tsx
<ActivityFeedRow event={event} />
```

*Mixed feed*
```tsx
<ActivityFeedRow event={event} />
```

### AuctionCountdown  (`nft-auction-countdown`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/auction/AuctionCountdown.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Live ticking countdown to an auction end — days, hours, minutes, seconds.

**Variants:**

*Ticking auction*
```tsx
<AuctionCountdown endsAt={auction.endsAt} size="md" />
```

*Ended state*
```tsx
<AuctionCountdown endsAt={pastDate} />
```

### BidHistoryRow  (`nft-bid-history-row`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/auction/BidHistoryRow.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Bid row — bidder avatar + handle, amount, time, winning indicator.

**Variants:**

*With winning highlight*
```tsx
<BidHistoryRow bid={bid} winning />
```

### WalletConnectButton  (`nft-wallet-connect-button`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/wallet/WalletConnectButton.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Two-state wallet connector — disconnected (provider picker) or connected (address + balance menu).

**Variants:**

*Disconnected*
```tsx
<WalletConnectButton wallet={null} onConnect={fn} />
```

*Connected*
```tsx
<WalletConnectButton wallet={connectedWallet} onDisconnect={fn} />
```

### MintProgressBar  (`nft-mint-progress-bar`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/nft/mint/MintProgressBar.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Mint progress strip — "X / Y minted" with percentage, mint price, and hot/sold-out state colour.

**Variants:**

*In progress*
```tsx
<MintProgressBar mintedCount={1247} totalSupply={5000} mintPriceEth={0.08} />
```

*Hot (≥80%)*
```tsx
<MintProgressBar mintedCount={4812} totalSupply={5000} mintPriceEth={0.08} />
```

*Sold out*
```tsx
<MintProgressBar mintedCount={5000} totalSupply={5000} mintPriceEth={0.08} />
```

### RatingDistribution  (`reviews-rating-distribution`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/reviews/RatingDistribution.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Horizontal bar chart of 1–5 star buckets. SVG-free, accessible via per-row progressbar roles.
- **Used by:** reviews-review-summary-card
- **Design tokens:** --warning, --surface-sunken, --text-secondary

**Variants:**

*Typical (4-star skew)*
```tsx
<RatingDistribution
  distribution={{ 1: 6, 2: 12, 3: 24, 4: 86, 5: 120 }}
  total={248}
/>
```

*Low-rated, counts hidden*
```tsx
<RatingDistribution
  distribution={low.distribution}
  total={low.total}
  showCounts={false}
/>
```

### ReviewCard  (`reviews-review-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/reviews/ReviewCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Single user review with avatar, star rating, optional verified badge, body, and an optimistic helpful counter.
- **Composes:** avatar, badge, star-rating

**Variants:**

*Verified · 5 stars · with title*
```tsx
<ReviewCard review={review} />
```

*Anonymous · 3 stars · no title*
```tsx
<ReviewCard review={review} />
```

### ReviewSummaryCard  (`reviews-review-summary-card`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/reviews/ReviewSummaryCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Aggregated rating summary. Combines the average score, a big star strip, and the per-bucket distribution into a single card.
- **Composes:** star-rating, reviews-rating-distribution

**Variants:**

*Default — restaurant*
```tsx
<ReviewSummaryCard summary={summary} />
```

*Custom title — hotel guest ratings*
```tsx
<ReviewSummaryCard
  summary={summary}
  title="Guest ratings"
  reviewNoun="stay"
/>
```

### ReviewSubmitForm  (`reviews-review-submit-form`)

- **Layer:** domain
- **Category:** Domain
- **File:** `modules/domains/reviews/ReviewSubmitForm.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Composable submit form: interactive StarRating, optional title input, textarea with min-length validation, submit button.
- **Composes:** star-rating, input, textarea, button

**Variants:**

*Default*
```tsx
<ReviewSubmitForm onSubmit={(d) => save(d)} />
```

*Custom labels — hotel review*
```tsx
<ReviewSubmitForm
  title="Share your stay"
  submitLabel="Post review"
/>
```

## Components — library / Library

### KUIViewer  (`lib-kui-viewer`)

- **Layer:** library
- **Category:** Library
- **File:** `modules/showcase/data/sections/lib-kui-viewer.showcase.tsx`
- **Status:** beta (since 2026-05)
- **Description:** Browser-based IFC/BIM 3D viewer built on Three.js, web-ifc and @thatopen/fragments. Ships a vanilla TypeScript core plus an optional React subpath (`kui-viewer/react`) exposing the `<KUIViewer />` component, a `ViewerProvider`, and a Zustand-backed `useViewerStore` hook for selection, federation and spatial-tree state. In-viewport widgets — an interactive NavCube, a pill toolbar (`viewer.toolbar`) and a dolly ZoomSlider — mount as children of `<KUIViewer />` and wire themselves to the live camera via `useViewer`.
- **When to use:** When you need to render IFC/BIM models in the browser — viewing, navigating and inspecting AEC scenes — and want a framework-agnostic core with an optional React wrapper.
- **When not to use:** For lightweight, non-BIM 3D scenes — prefer a thinner Three.js wrapper or react-three-fiber. KUIViewer pulls in web-ifc WASM and @thatopen/fragments and is sized for AEC workloads.
- **Dependencies:** @kuraykaraaslan/kui-viewer, three, web-ifc, @thatopen/fragments, zustand

**Variants:**

## Components — ui / App

### CodeEditor  (`code-editor`)

- **Layer:** ui
- **Category:** App
- **File:** `modules/ui/CodeEditor/index.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Engine-agnostic code editor primitive. M1 ships a lightweight CodeMirror-style fallback engine (textarea + line-number gutter + active-line + theme + readonly + placeholder) so the public API is stable today. Future milestones: Monaco (VSCode) lazy engine, find/replace, multi-cursor, diagnostics (markers), custom autocomplete + hover, minimap, code folding, vim/emacs keymap. Pixel-identical EJS sibling at modules/ui/CodeEditor/CodeEditor.ejs. Used by RulesetEditor M3 + RichTextEditor code-block insert (planned).
- **Design tokens:** --surface-base, --surface-raised, --surface-overlay, --surface-sunken, --text-primary, --text-secondary, --text-disabled, --border, --border-strong, --border-focus, --error
- **A11y:** WCAG AA · ARIA: textbox · Keys: Tab → Move focus into / out of the editor; Arrow keys → Move caret + sync active line gutter; Ctrl/Cmd + Z → Browser-native undo (M1 textarea fallback)

**Variants:**

*JavaScript readonly*
```tsx
<CodeEditor
  id="example"
  label="example.js"
  language="js"
  theme="light"
  value={source}
  readonly
  showLineNumbers
/>
```

*Markdown editable*
```tsx
const [src, setSrc] = useState('# Hello');
<CodeEditor
  id="readme"
  name="readme"
  label="README.md"
  language="markdown"
  theme="dark"
  value={src}
  onChange={setSrc}
  placeholder="Start typing markdown…"
/>
```

## Components — ui / Atom

### Button  (`button`)

- **Layer:** ui
- **Category:** Atom
- **File:** `modules/ui/Button.tsx`
- **Status:** stable (since 2025-01)
- **Description:** Core interactive element. Supports 5 visual styles (variants) and 5 sizes. disabled, loading and selected states are built-in.
- **Used by:** color-picker, comment-thread, form-builder, gantt, onboarding-wizard, reviews-review-submit-form, rich-text-editor, share-dialog
- **Design tokens:** --border, --border-focus, --error, --primary, --primary-fg, --primary-hover, --secondary, --surface-overlay, --text-inverse, --text-primary

**Variants:**

*Primary*
```tsx
<Button variant="primary">Primary</Button>
```

*Secondary*
```tsx
<Button variant="secondary">Secondary</Button>
```

*Ghost*
```tsx
<Button variant="ghost">Ghost</Button>
```

*Danger*
```tsx
<Button variant="danger">Danger</Button>
```

*Outline*
```tsx
<Button variant="outline">Outline</Button>
```

*Disabled*
```tsx
<Button variant="primary" disabled>Disabled</Button>
```

*Sizes*
```tsx
<Button size="xs">XS</Button>
<Button size="sm">SM</Button>
<Button size="md">MD</Button>
<Button size="lg">LG</Button>
<Button size="xl">XL</Button>
```

*Icon left / right*
```tsx
<Button iconLeft="⬇">Download</Button>
<Button variant="outline" iconRight="→">Next</Button>
```

*Icon only*
```tsx
<Button iconOnly aria-label="Delete item">✕</Button>
```

*Full width*
```tsx
<Button fullWidth>Full-width</Button>
```

*Selected / active state*
```tsx
<Button variant="outline" selected>Selected</Button>
```

*Loading state*
```tsx
<Button variant="primary" loading>Saving…</Button>
```

### Badge  (`badge`)

- **Layer:** ui
- **Category:** Atom
- **File:** `modules/ui/Badge.tsx`
- **Status:** stable (since 2025-01)
- **Description:** Status, category or label indicator. 6 semantic variants, 3 sizes, dot and dismissible support.
- **Used by:** kanban-board, maintenance-page, reviews-review-card
- **Design tokens:** --error, --error-subtle, --info, --info-subtle, --primary, --primary-subtle, --secondary, --success, --success-fg, --success-subtle, --surface-sunken, --text-secondary, --warning, --warning-subtle

**Variants:**

*Success*
```tsx
<Badge variant="success">Active</Badge>
```

*Error*
```tsx
<Badge variant="error">Inactive</Badge>
```

*Warning*
```tsx
<Badge variant="warning">Pending</Badge>
```

*Info*
```tsx
<Badge variant="info">New</Badge>
```

*Neutral*
```tsx
<Badge variant="neutral">Design</Badge>
```

*Primary*
```tsx
<Badge variant="primary">Frontend</Badge>
```

*Sizes*
```tsx
<Badge size="sm">Small</Badge>
<Badge size="md">Medium</Badge>
<Badge size="lg">Large</Badge>
```

*Dot badge*
```tsx
<Badge variant="success" dot>Online</Badge>
<Badge variant="warning" dot>Away</Badge>
```

*Dismissible*
```tsx
<Badge variant="primary" dismissible onDismiss={() => remove(tag)}>React</Badge>
```

### Avatar  (`avatar`)

- **Layer:** ui
- **Category:** Atom
- **File:** `modules/ui/Avatar.tsx`
- **Status:** stable (since 2025-01)
- **Description:** User profile photo or initials indicator. 5 sizes with optional status dot. When no image is provided, initials render on a bg-primary-subtle / text-primary tile.
- **Used by:** comment-thread, kanban-board, mention-picker, reviews-review-card, share-dialog
- **Design tokens:** --border, --primary, --primary-subtle

**Variants:**

*Initials (sizes)*
```tsx
<Avatar name="Jane Doe" size="xs" />
<Avatar name="Jane Doe" size="sm" />
<Avatar name="Jane Doe" size="md" />
<Avatar name="Jane Doe" size="lg" />
<Avatar name="Jane Doe" size="xl" />
```

*With label*
```tsx
<div className="flex items-center gap-3">
  <Avatar name="John Smith" size="md" />
  <div>
    <p className="text-sm font-medium text-text-primary">John Smith</p>
    <p className="text-xs text-text-secondary">john@example.com</p>
  </div>
</div>
```

*Image source*
```tsx
<Avatar src="/avatar.jpg" name="Jane Doe" />
```

*Status dot*
```tsx
<Avatar name="Alice" status="online" />
<Avatar name="Bob" status="away" />
<Avatar name="Carol" status="busy" />
<Avatar name="Dave" status="offline" />
```

*AvatarGroup*
```tsx
<AvatarGroup
  avatars={[{ name: 'Alice' }, { name: 'Bob' }, ...]}
  max={4}
/>
```

### Spinner  (`spinner`)

- **Layer:** ui
- **Category:** Atom
- **File:** `modules/ui/Spinner.tsx`
- **Status:** stable (since 2025-01)
- **Description:** CSS border-based loading indicator. Does not require FontAwesome. 5 sizes, border-border / border-t-primary colour system.
- **Design tokens:** --border

**Variants:**

*Sizes*
```tsx
<Spinner size="xs" />
<Spinner size="sm" />
<Spinner size="md" />
<Spinner size="lg" />
<Spinner size="xl" />
```

*In a Button*
```tsx
<Button variant="primary" loading>Loading…</Button>
```

### Skeleton  (`skeleton`)

- **Layer:** ui
- **Category:** Atom
- **File:** `modules/ui/Skeleton.tsx`
- **Status:** stable (since 2025-01)
- **Description:** Animated placeholder shown before content loads. Uses animate-pulse bg-surface-sunken. aria-busy="true" ensures accessibility.
- **Design tokens:** --border, --surface-raised, --surface-sunken

**Variants:**

*Lines*
```tsx
<SkeletonLine width="w-full" />
<SkeletonLine width="w-3/4" />
<SkeletonLine width="w-1/2" />
```

*Text block*
```tsx
<SkeletonText lines={4} />
```

*Card*
```tsx
<SkeletonCard />
```

*Table rows*
```tsx
<table className="w-full"><tbody><SkeletonTableRow cols={4} /></tbody></table>
```

*Dashboard layout*
```tsx
// Stat cards + table skeleton
<div className="space-y-4">
  <div className="grid grid-cols-3 gap-3">
    {[...Array(3)].map((_, i) => (
      <div key={i} className="border rounded-lg p-4 space-y-2">
        <SkeletonLine width="w-1/2" />
        <SkeletonLine width="w-3/4" className="h-5" />
        <SkeletonLine width="w-1/3" />
      </div>
    ))}
  </div>
  <table><tbody><SkeletonTableRow cols={4} /></tbody></table>
</div>
```

*Article layout*
```tsx
// Blog post / article skeleton
<div className="space-y-4">
  <SkeletonLine width="w-1/4" />        {/* category */}
  <SkeletonLine width="w-full" className="h-6" /> {/* title row 1 */}
  <SkeletonLine width="w-3/4" className="h-6" />  {/* title row 2 */}
  <div className="flex items-center gap-3">
    <SkeletonAvatar size="sm" />
    <SkeletonLine width="w-24" />
  </div>
  <div className="h-40 animate-pulse bg-surface-sunken rounded-xl" /> {/* hero */}
  <SkeletonText lines={4} />
</div>
```

### SkipLink + LiveRegion  (`skip-link`)

- **Layer:** ui
- **Category:** Atom
- **File:** `modules/ui/SkipLink.tsx`
- **Status:** stable (since 2025-01)
- **Description:** SkipLink is visually hidden until focused, enabling keyboard users to bypass navigation. LiveRegion announces dynamic content to screen readers.

**Variants:**

*SkipLink (focus to reveal)*
```tsx
// Place at top of layout:
<SkipLink href="#main-content" />

// Linked target:
<main id="main-content">...</main>
```

*LiveRegion*
```tsx
function Demo() {
  const [msg, setMsg] = useState('');
  return (
    <>
      <button onClick={() => setMsg('Action completed')}>Act</button>
      <LiveRegion message={msg} />
    </>
  );
}
```

### BrandLogo  (`brand-logo`)

- **Layer:** ui
- **Category:** Atom
- **File:** `modules/ui/BrandLogo.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Square brand mark with rounded corners. Renders a single letter or short token on a primary-coloured tile. 5 sizes (sm → 2xl).
- **Design tokens:** --primary, --primary-fg

**Variants:**

*Default sizes*
```tsx
<BrandLogo size="sm">A</BrandLogo>
<BrandLogo size="md">B</BrandLogo>
<BrandLogo size="lg">C</BrandLogo>
<BrandLogo size="xl">D</BrandLogo>
<BrandLogo size="2xl">E</BrandLogo>
```

*Custom content*
```tsx
<BrandLogo size="lg">KU</BrandLogo>
<BrandLogo size="lg" className="bg-secondary">N</BrandLogo>
<BrandLogo size="lg" className="bg-success">✓</BrandLogo>
```

### StarRating  (`star-rating`)

- **Layer:** ui
- **Category:** Atom
- **File:** `modules/ui/StarRating.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Five-star rating indicator. Read-only by default with decimal/half-star rendering; pass `readonly={false}` + `onChange` for interactive whole-star selection.
- **When to use:** Surface a 0–5 star score (e.g. product / hotel / restaurant ratings) or let users submit a new rating.
- **When not to use:** For non-star scales (e.g. NPS, percentages) use ContentScoreBar or a custom indicator instead.
- **Used by:** reviews-review-card, reviews-review-submit-form, reviews-review-summary-card
- **Design tokens:** --warning, --text-disabled, --border-focus
- **A11y:** WCAG AA · ARIA: role="img" (readonly), role="radiogroup" / role="radio" (interactive)

**Variants:**

*Readonly with decimals*
```tsx
<StarRating value={4.7} size="sm" caption="(312 reviews)" />
<StarRating value={3.5} size="md" />
<StarRating value={2.2} size="lg" />
```

*Interactive*
```tsx
const [value, setValue] = useState(0);
<StarRating
  value={value}
  readonly={false}
  onChange={setValue}
  aria-label="Pick a rating"
/>
```

## Components — ui / Molecule

### ButtonGroup  (`button-group`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/ButtonGroup.tsx`
- **Status:** stable (since 2025-01)
- **Description:** Segmented button group for mutually-exclusive options. Supports 4 variants, 4 sizes and disabled items.
- **Design tokens:** --border, --surface-base, --surface-overlay

**Variants:**

*Outline (default)*
```tsx
function Demo() {
  const [v, setV] = useState('week');
  return (
    <ButtonGroup value={v} onChange={setV}
      items={[{ value: 'day', label: 'Day' }, { value: 'week', label: 'Week' }, { value: 'month', label: 'Month' }]}
    />
  );
}
```

*Sizes*
```tsx
<ButtonGroup size="sm" value="a" onChange={setV} items={[...]} />
<ButtonGroup size="md" value="a" onChange={setV} items={[...]} />
```

*Primary / secondary / ghost*
```tsx
<ButtonGroup variant="primary" value="week" onChange={setV} items={[...]} />
<ButtonGroup variant="secondary" value="week" onChange={setV} items={[...]} />
<ButtonGroup variant="ghost" value="week" onChange={setV} items={[...]} />
```

*With disabled item*
```tsx
<ButtonGroup value="week" onChange={setV}
  items={[
    { value: 'day',   label: 'Day' },
    { value: 'week',  label: 'Week' },
    { value: 'month', label: 'Month', disabled: true },
  ]}
/>
```

*Icon-style labels*
```tsx
// Use single-char labels as icon proxies:
<ButtonGroup value="grid" onChange={setV}
  items={[
    { value: 'list', label: '☰' },
    { value: 'grid', label: '⊞' },
    { value: 'map',  label: '◫' },
  ]}
/>
```

### Input  (`input`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/Input.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Text input field with label, hint, error, prefix icon, password toggle, and 3 size variants.
- **Used by:** form-builder, reviews-review-submit-form, rich-text-editor
- **Design tokens:** --border, --border-focus, --error, --error-subtle, --primary, --secondary, --surface-base, --surface-sunken, --text-disabled, --text-primary, --text-secondary

**Variants:**

*Default*
```tsx
<Input id="email" label="Email" type="email" placeholder="you@example.com" hint="We'll never share your email." />
```

*Error*
```tsx
<Input id="email" label="Email" type="email" error="A valid email address is required." required />
```

*Disabled*
```tsx
<Input id="email" label="Email" type="email" placeholder="you@example.com" disabled />
```

*Prefix / suffix icon*
```tsx
<Input id="search" label="Search" prefixIcon={<SearchIcon />} placeholder="Search…" />
<Input id="amount" label="Amount" suffixIcon={<span>$</span>} type="number" />
```

*Clearable*
```tsx
function Demo() {
  const [v, setV] = useState('');
  return <Input id="clr" label="Label" value={v} onChange={(e) => setV(e.target.value)}
    clearable onClear={() => setV('')} />;
}
```

*Success state*
```tsx
<Input id="username" label="Username" value="johndoe" success="Username is available!" />
```

*Read only*
```tsx
<Input id="api-key" label="API Key" value="sk-abc123xyz" readOnly />
```

*Character counter*
```tsx
<Input id="bio" label="Bio" value={v} onChange={(e) => setV(e.target.value)} maxLength={50} showCount />
```

*Password with eye toggle*
```tsx
<Input id="password" label="Password" type="password" value={v} onChange={setV} />
```

*Number stepper*
```tsx
<Input id="qty" label="Quantity" type="number" value={v} onChange={setV} min={0} max={99} />
```

*Prefix / suffix text*
```tsx
<Input id="website" label="Website"
  prefixIcon={<span className="text-text-secondary text-xs font-mono">https://</span>}
  placeholder="yoursite.com" />

<Input id="handle" label="Twitter handle"
  prefixIcon={<span className="text-text-secondary">@</span>}
  placeholder="username" />

<Input id="price" label="Price"
  suffixIcon={<span className="text-text-secondary">USD</span>}
  type="number" />
```

*Loading state*
```tsx
<Input id="username" label="Username" value={v} onChange={setV}
  suffixIcon={<Spinner size="xs" />}
  hint="Checking availability…" />
```

### Textarea  (`textarea`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/Textarea.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Label + textarea + hint + error anatomy. Vertical resizing is enabled via resize-y and the parts are linked through aria-describedby.
- **Used by:** form-builder, reviews-review-submit-form
- **Design tokens:** --border, --border-focus, --error, --error-subtle, --primary, --secondary, --surface-base, --surface-sunken, --text-disabled, --text-primary, --text-secondary

**Variants:**

*Default*
```tsx
<Textarea id="message" label="Message" placeholder="Write your message…" hint="Max 500 characters." />
```

*Error*
```tsx
<Textarea id="message" label="Message" error="Message is required." required />
```

*Disabled*
```tsx
<Textarea id="message" label="Message" placeholder="Not editable" disabled />
```

*Character counter*
```tsx
function Demo() {
  const MAX = 200;
  const [v, setV] = useState('');
  return (
    <div className="space-y-1">
      <Textarea id="bio" label="Bio" value={v} maxLength={MAX} rows={3}
        onChange={(e) => setV(e.target.value)} />
      <p className={`text-xs text-right ${MAX - v.length < 20 ? 'text-error' : 'text-text-secondary'}`}>
        {MAX - v.length} characters remaining
      </p>
    </div>
  );
}
```

### SearchBar  (`search-bar`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/SearchBar.tsx`
- **Status:** stable (since 2025-02)
- **Description:** role="searchbox" with search icon and clear button. Works in controlled and uncontrolled modes.
- **Design tokens:** --border, --border-focus, --primary, --surface-base, --text-disabled, --text-primary

**Variants:**

*Default*
```tsx
<SearchBar placeholder="Search components…" />
```

*With value*
```tsx
<SearchBar value="Button" onChange={(v) => console.log(v)} />
```

*Loading state*
```tsx
function Demo() {
  const [q, setQ] = useState('');
  const [loading, setLoading] = useState(false);
  return (
    <div className="space-y-2">
      <SearchBar value={q} onChange={(v) => { setQ(v); setLoading(true); }} />
      {loading
        ? <p className="flex items-center gap-1.5"><Spinner size="xs" /> Searching…</p>
        : q && <p>{q} — 24 results</p>}
    </div>
  );
}
```

*With results count*
```tsx
function Demo() {
  const items = ['Button', 'Badge', 'Card', ...];
  const [q, setQ] = useState('');
  const filtered = q ? items.filter(n => n.toLowerCase().includes(q.toLowerCase())) : items;
  return (
    <div className="space-y-2">
      <SearchBar value={q} onChange={setQ} />
      <p className="text-xs text-text-secondary">{filtered.length} of {items.length} results</p>
      <ul>{filtered.map(name => <li key={name}>{name}</li>)}</ul>
    </div>
  );
}
```

### Checkbox  (`checkbox`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/Checkbox.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Label + checkbox + optional hint / error message. aria-describedby is wired up and border-error is applied on the error state.
- **Used by:** form-builder
- **Design tokens:** --border, --border-focus, --error, --primary, --secondary, --text-disabled, --text-primary, --text-secondary

**Variants:**

*Default*
```tsx
<Checkbox id="accept" label="I agree to the Terms of Service" />
```

*With hint*
```tsx
<Checkbox id="newsletter" label="Subscribe to newsletter" hint="We send weekly updates, no spam." />
```

*Error*
```tsx
<Checkbox id="accept" label="I agree to the Terms of Service" error="You must accept the terms." />
```

*Disabled*
```tsx
<Checkbox id="accept" label="Checked and disabled" defaultChecked disabled />
```

*Indeterminate (select all)*
```tsx
// Set indeterminate prop to show mixed state:
<Checkbox id="all" label="Select all" checked={allChecked} indeterminate={someChecked} onChange={toggleAll} />
```

### RadioGroup  (`radio-group`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/RadioGroup.tsx`
- **Status:** stable (since 2025-02)
- **Description:** fieldset + legend based radio group. WCAG-compliant keyboard navigation with an optional card-style variant.
- **Design tokens:** --border, --border-focus, --error, --primary, --secondary, --text-primary, --text-secondary

**Variants:**

*Default*
```tsx
<RadioGroup
  name="notify"
  legend="Notification preference"
  options={[
    { value: 'email', label: 'Email' },
    { value: 'sms', label: 'SMS' },
    { value: 'none', label: 'None' },
  ]}
/>
```

*Disabled*
```tsx
<RadioGroup name="notify" legend="Notification preference" options={[...]} value="email" disabled />
```

*Card style*
```tsx
function Demo() {
  const [v, setV] = useState('pro');
  const plans = [
    { value: 'free', label: 'Free',  hint: '$0/mo · 3 projects' },
    { value: 'pro',  label: 'Pro',   hint: '$12/mo · Unlimited' },
    { value: 'team', label: 'Team',  hint: '$49/mo · 10 seats'  },
  ];
  return (
    <fieldset className="space-y-2">
      <legend>Choose plan</legend>
      {plans.map(plan => (
        <label key={plan.value} className={cn(
          'flex items-start gap-3 rounded-lg border px-4 py-3 cursor-pointer',
          v === plan.value ? 'border-primary bg-primary-subtle' : 'border-border hover:bg-surface-overlay'
        )}>
          <input type="radio" name="plan" value={plan.value}
            checked={v === plan.value} onChange={() => setV(plan.value)} />
          <div>
            <span className={v === plan.value ? 'text-primary font-medium' : ''}>{plan.label}</span>
            <p className="text-xs text-text-secondary">{plan.hint}</p>
          </div>
        </label>
      ))}
    </fieldset>
  );
}
```

### Toggle  (`toggle`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/Toggle.tsx`
- **Status:** stable (since 2025-02)
- **Description:** role="switch" toggle/switch with three sizes, description slot, and disabled support. Fully accessible via CSS transform without a native input.
- **Design tokens:** --border, --primary, --secondary, --surface-sunken, --text-primary, --text-secondary

**Variants:**

*Sizes*
```tsx
<Toggle id="notifications" label="Enable notifications" checked={enabled} onChange={setEnabled} size="md" />
```

*With description*
```tsx
<Toggle id="marketing" label="Marketing emails" description="Receive weekly updates." checked={value} onChange={setValue} />
```

*Disabled*
```tsx
<Toggle id="toggle" label="Disabled" checked disabled onChange={() => {}} />
```

*Settings list (controlled)*
```tsx
function Demo() {
  const [s, setS] = useState({ notifications: true, marketing: false });
  return (
    <div className="divide-y border rounded-lg">
      {[{ key: 'notifications', label: 'Push notifications', desc: 'Alerts for new activity' }, ...].map(({ key, label, desc }) => (
        <div key={key} className="flex items-center justify-between px-4 py-3">
          <div>
            <p className="text-sm font-medium">{label}</p>
            <p className="text-xs text-text-secondary">{desc}</p>
          </div>
          <Toggle id={key} label="" checked={s[key]} onChange={() => setS(p => ({ ...p, [key]: !p[key] }))} />
        </div>
      ))}
    </div>
  );
}
```

### CheckboxGroup  (`checkbox-group`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/CheckboxGroup.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Chip-style multi-select group. Selected chips use bg-primary-subtle / border-primary tokens. Keyboard accessible.
- **Design tokens:** --border, --border-focus, --error, --primary, --primary-subtle, --surface-base, --surface-overlay, --text-primary

**Variants:**

*Default*
```tsx
const [selected, setSelected] = useState(['react', 'typescript']);
<CheckboxGroup
  legend="Tech stack"
  options={[
    { value: 'react', label: 'React' },
    { value: 'vue', label: 'Vue' },
    { value: 'typescript', label: 'TypeScript' },
  ]}
  selected={selected}
  onChange={setSelected}
/>
```

*Disabled*
```tsx
<CheckboxGroup
  legend="Permissions"
  options={[
    { value: 'read', label: 'Read' },
    { value: 'write', label: 'Write' },
    { value: 'delete', label: 'Delete' },
  ]}
  selected={['read']}
  onChange={() => {}}
  disabled
/>
```

### Select  (`select`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/Select.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Label + select + hint + error anatomy. appearance-none overrides the native dropdown style and renders a chevron icon.
- **Used by:** form-builder
- **Design tokens:** --border, --border-focus, --error, --error-subtle, --primary, --secondary, --surface-base, --surface-sunken, --text-primary, --text-secondary

**Variants:**

*Controlled*
```tsx
const ROLES = [
  { value: 'admin', label: 'Admin' },
  { value: 'editor', label: 'Editor' },
  { value: 'viewer', label: 'Viewer' },
];

const [role, setRole] = useState('editor');
<Select id="role" label="Role" options={ROLES} value={role}
  onChange={(e) => setRole(e.target.value)} />
```

*With icons*
```tsx
const STATUSES = [
  { value: 'active',   label: 'Active',   icon: <span className="text-success">●</span> },
  { value: 'inactive', label: 'Inactive', icon: <span className="text-text-disabled">●</span> },
  { value: 'pending',  label: 'Pending',  icon: <span className="text-warning">●</span> },
];

<Select id="status" label="Status" options={STATUSES} value={status} onChange={setStatus} />
```

*Validation states*
```tsx
<Select id="plan" label="Plan" placeholder="Select a plan" required
  error="Please select a plan." options={[...]} />

<Select id="plan" label="Plan" disabled options={[...]} value="pro" />
```

*With countries*
```tsx
import { countries, getEmojiFlag } from 'countries-list';

const COUNTRY_OPTIONS = Object.entries(countries)
  .map(([code, data]) => ({ value: code, label: `${getEmojiFlag(code)} ${data.name}` }))
  .sort((a, b) => a.label.localeCompare(b.label));

<Select id="country" label="Country" placeholder="Select a country…"
  options={COUNTRY_OPTIONS} hint="Powered by countries-list." />
```

*Searchable*
```tsx
<Select id="country" label="Country" placeholder="Select a country…" searchable
  options={COUNTRY_OPTIONS} value={val} onChange={(e) => setVal(e.target.value)}
  hint="Type to filter the list." />
```

### TagInput  (`tag-input`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/TagInput.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Free-text input that creates chips. Add tags with Enter or comma, double-click to edit, Backspace to delete. Duplicates are ignored.
- **Design tokens:** --border, --border-focus, --error, --primary, --primary-subtle, --surface-base, --surface-sunken, --text-disabled, --text-primary

**Variants:**

*Default*
```tsx
const [tags, setTags] = useState(['next.js', 'react']);
<TagInput id="tags" label="Tags" value={tags} onChange={setTags} hint="Press Enter or comma to add." />
```

*Empty / Error*
```tsx
<TagInput id="tags" label="Required tags" value={[]} onChange={setTags} error="At least one tag is required." />
```

### MultiSelect  (`multi-select`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/MultiSelect.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Chip-based multi-select popover with searchable filter, keyboard navigation, and disabled-option support.

**Variants:**

*Controlled*
```tsx
function Demo() {
  const [v, setV] = useState([]);
  return (
    <MultiSelect id="ms" label="Frameworks"
      options={[{ value: 'react', label: 'React' }, ...]}
      value={v} onChange={setV}
    />
  );
}
```

*With error*
```tsx
<MultiSelect id="ms" label="Tags" options={[...]} error="Please select at least one tag." />
```

*With countries*
```tsx
import { countries, getEmojiFlag } from 'countries-list';

const COUNTRY_OPTIONS = Object.entries(countries)
  .map(([code, data]) => ({ value: code, label: `${getEmojiFlag(code)} ${data.name}` }))
  .sort((a, b) => a.label.localeCompare(b.label));

function Demo() {
  const [v, setV] = useState([]);
  return (
    <MultiSelect id="ms-countries" label="Countries"
      options={COUNTRY_OPTIONS} placeholder="Select countries…"
      value={v} onChange={setV} hint="Select one or more countries." />
  );
}
```

*Searchable*
```tsx
<MultiSelect id="countries" label="Countries" searchable
  options={COUNTRY_OPTIONS} placeholder="Search and select…"
  value={v} onChange={setV} hint="Type to filter the list." />
```

### ComboBox  (`combo-box`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/ComboBox/index.tsx`
- **Status:** beta (since 2025-03)
- **Description:** Searchable autocomplete single-select with keyboard navigation, described options, and a clearable button.

**Variants:**

*Controlled selection*
```tsx
function Demo() {
  const [value, setValue] = useState('nextjs');
  return (
    <ComboBox
      id="framework"
      label="Framework"
      options={COMBO_OPTIONS}
      value={value}
      onChange={setValue}
    />
  );
}
```

*Async search*
```tsx
<ComboBox id="search" label="Async search" options={COMBO_OPTIONS} onSearch={search} value={value} onChange={setValue} />
```

*Debounced async suggestions*
```tsx
async function suggest(query, signal) {
  const res = await fetch('/api/suggest?q=' + encodeURIComponent(query), { signal });
  return res.json();
}

<ComboBox
  id="cb-async-debounced"
  label="Debounced suggestions"
  options={[]}
  value={value}
  onChange={setValue}
  onSearch={suggest}      // signature: (q, signal) => Promise<Option[]>
  debounceMs={300}        // useAsync debounces & cancels in-flight
  placeholder="Type to search…"
/>
```

### DatePicker  (`date-picker`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/DatePicker/index.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Popover-based date picker with a locale-aware calendar grid (TR / EN), quick month / year jump from the header, min / max / disabledDates support, and full keyboard navigation (Arrow / PageUp/Down / Shift+Page / Home / End / Enter / Esc). Pixel-identical EJS sibling at modules/ui/DatePicker/DatePicker.ejs.

**Variants:**

*Default*
```tsx
const [date, setDate] = useState<Date | null>(null);
<DatePicker id="date" label="Appointment date" hint="Select a future date." value={date} onChange={setDate} />
```

*With value*
```tsx
<DatePicker id="start" label="Start date" value={new Date('2026-06-15')} onChange={setDate} />
```

*Error / Disabled*
```tsx
<DatePicker id="due" label="Due date" error="Please select a date." required />
<DatePicker id="locked" label="Locked date" value={date} disabled />
```

*Locale: Türkçe + custom messages*
```tsx
<DatePicker
  locale="tr"
  value={date}
  onChange={setDate}
  messages={{ today: 'Bugün seç', clear: 'Temizle' }}
/>
```

### DateRangePicker  (`date-range-picker`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/DatePicker/index.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Two-month popover for picking a start → end date range. Shares the same Calendar core as DatePicker; locale-aware, fully keyboard navigable, with min/max/disabledDates. Pixel-identical EJS sibling at modules/ui/DatePicker/DateRangePicker.ejs.

**Variants:**

*Date range*
```tsx
function Demo() {
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
  return <DateRangePicker id="dr" label="Date range" value={range} onChange={setRange} />;
}
```

*With value (EN locale)*
```tsx
<DateRangePicker id="dr" label="Booking window"
  value={{ start: new Date('2026-06-01'), end: new Date('2026-06-15') }}
  onChange={setRange} locale="en" />
```

*Time picker*
```tsx
function Demo() {
  const [t, setT] = useState('09:00');
  return <TimePicker id="tp" label="Meeting time" value={t} onChange={setT} />;
}
```

### FileInput  (`file-input`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/FileInput/index.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Drag-and-drop file upload with validation, file list, and individual remove actions. M1 adds paste-from-clipboard, `accept` MIME-pattern + extension validation, and `maxFiles` enforcement with i18n messages. Pixel-identical EJS sibling at modules/ui/FileInput/FileInput.ejs.

**Variants:**

*Single file*
```tsx
<FileInput id="photo" label="Profile photo" hint="PNG or JPG, max 2 MB"
  accept="image/*" maxSizeBytes={2097152} />
```

*Multiple files*
```tsx
<FileInput id="attachments" label="Attachments" multiple hint="Up to 5 MB each" maxSizeBytes={5242880} />
```

*With upload action*
```tsx
<FileInput id="attachments" label="Project attachments" multiple maxSizeBytes={5242880}
  onUpload={uploadFiles} uploadLabel="Upload" />
```

*Paste from clipboard*
```tsx
<FileInput id="screenshots" label="Screenshot drop" multiple enablePaste
  accept="image/*" maxFiles={4} maxSizeBytes={4 * 1024 * 1024}
  hint="Drop, browse, or paste a screenshot (Cmd/Ctrl + V)." />
```

*Disabled*
```tsx
<FileInput id="upload" label="Disabled upload" disabled />
```

### ColorPicker  (`color-picker`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/ColorPicker/index.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Color selection control with a 32-swatch preset palette plus optional hex input and native browser color picker for unlimited colors. M1 adds a HEX / RGBA / HSLA / HWB / OKLCH format-switcher with per-format input + copy. Pixel-identical EJS sibling at modules/ui/ColorPicker/ColorPicker.ejs. Used by RichTextEditor for text + highlight colors.
- **Composes:** button
- **Design tokens:** --surface-base, --surface-raised, --surface-overlay, --surface-sunken, --text-primary, --text-secondary, --text-disabled, --border, --border-focus
- **A11y:** WCAG AA · ARIA: button, dialog · Keys: Enter / Space → Open / close the picker; Tab → Move between swatches; Enter (in hex) → Commit hex value; Escape → Close picker

**Variants:**

*Default*
```tsx
const [c, setC] = useState<string | null>('#3b82f6');
<ColorPicker label="Brand color" value={c} onChange={setC} showNoColor />
```

*Compact (swatches only)*
```tsx
<ColorPicker
  value={c}
  onChange={setC}
  showHexInput={false}
  showNativePicker={false}
/>
```

*Hex + native picker only (no swatches)*
```tsx
<ColorPicker
  label="Background"
  value={c}
  onChange={setC}
  swatches={[]}
  showHexInput
  showNativePicker
  showNoColor
/>
```

*Format switcher — HEX / RGBA / HSLA / HWB / OKLCH (M1)*
```tsx
<ColorPicker
  label="Theme color"
  value={c}
  onChange={setC}
  showFormatSwitcher
  defaultFormat="hex"
  showHexInput={false}
  showNativePicker
/>

// onChange receives the value formatted in the active format:
//   '#3b82f6'                              (HEX)
//   'rgb(59, 130, 246)'                    (RGBA)
//   'hsl(217.2, 91.2%, 59.8%)'             (HSLA)
//   'hwb(217.2 23.1% 3.5%)'                (HWB)
//   'oklch(0.6228 0.1808 257.84)'          (OKLCH)
//
// Each tab has its own validated text input + a Copy button (faCopy → faCheck).
```

### DiffViewer  (`diff-viewer`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/DiffViewer/index.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Line-based text diff viewer with unified (GitHub-style) and split (yan yana) modes. M1 ships a zero-dep LCS algorithm, hunk headers in `@@ -old,n +new,n @@` form, old/new line-number gutters, configurable context window, and optional collapsible unchanged regions. Pixel-identical EJS sibling at modules/ui/DiffViewer/DiffViewer.ejs.
- **Design tokens:** --surface-base, --surface-overlay, --surface-sunken, --text-primary, --text-secondary, --text-disabled, --border, --border-focus, --success, --success-subtle, --error, --error-subtle
- **A11y:** WCAG AA · ARIA: region, separator · Keys: Tab → Move focus into the diff region; Enter → Expand a collapsed unchanged run (when collapsible=true) · TODO M5: J/K next/prev change, N/P next/prev file, full roving tabindex + screen-reader line announcements.

**Variants:**

*Unified (default)*
```tsx
<DiffViewer oldText={oldSrc} newText={newSrc} />
```

*Split (yan yana)*
```tsx
<DiffViewer oldText={oldSrc} newText={newSrc} mode="split" />
```

*With context=1*
```tsx
<DiffViewer oldText={oldSrc} newText={newSrc} context={1} />
```

*Collapsible unchanged context*
```tsx
<DiffViewer
  oldText={oldSrc}
  newText={newSrc}
  context={3}
  collapsible
/>
```

### Chart  (`chart`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/Chart/index.ts`
- **Status:** beta (since 2026-05)
- **Description:** Token-aware primitive chart library at @/modules/ui/Chart. M1 ships seven SVG-based charts (Line, Bar, Area, Pie, Donut, Scatter, SparkLine) that consume a unified `Series` data shape. Colors auto-resolve from --primary / --secondary / --success / --warning / --error / --info, so dark mode and theme swaps work without any extra work. Pixel-identical EJS sibling at modules/ui/Chart/Chart.ejs. M3+ stubs (BubbleChart, HeatmapChart, TreemapChart, RadarChart, FunnelChart, SankeyChart, CandlestickChart, GaugeChart) are exported but render null until implemented; see PLANS/38-Charts.md.
- **Design tokens:** --primary, --secondary, --success, --warning, --error, --info, --surface-raised, --border, --text-primary, --text-secondary
- **A11y:** WCAG AA · ARIA: img · Each chart SVG uses role="img" + aria-label. M5 will add a visually hidden data table for screen-reader parity and keyboard navigation between data points.

**Variants:**

*LineChart*
```tsx
<LineChart
  series={[
    { id: 'active',  name: 'Active users', data: [{ x: 'Mon', y: 1200 }, /* … */] },
    { id: 'signups', name: 'New signups',  data: [{ x: 'Mon', y: 300 },  /* … */] },
  ]}
  height={220}
/>
```

*BarChart*
```tsx
<BarChart
  series={[
    { id: 'revenue',  name: 'Revenue',  data: [{ x: 'Jan', y: 4200 }, /* … */] },
    { id: 'expenses', name: 'Expenses', data: [{ x: 'Jan', y: 2800 }, /* … */] },
  ]}
  radius={4}
/>
```

*AreaChart*
```tsx
<AreaChart series={series} smooth fillOpacity={0.18} />
```

*PieChart*
```tsx
<PieChart
  series={[{
    id: 'share', name: 'Category share',
    data: [
      { x: 'Electronics', y: 35 },
      { x: 'Clothing',    y: 25 },
      { x: 'Food',        y: 20 },
      { x: 'Books',       y: 12 },
      { x: 'Other',       y: 8 },
    ],
  }]}
/>
```

*DonutChart*
```tsx
<DonutChart series={pieSeries} innerRadius={0.62} />
```

*SparkLine*
```tsx
<SparkLine values={[12, 14, 11, 17, 19, 16, 22]} width={120} height={28} filled />
<SparkLine values={[5, 7, 6, 9, 8, 11]} width={120} height={28} />
```

### Slider  (`slider`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/Slider/index.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Accessible carousel. Includes role="region" + aria-roledescription="carousel" and per-slide aria labels. Supports autoplay, arrow keys, and dot navigation.

**Variants:**

*Default*
```tsx
<Slider
  slides={[
    <HeroSlide title="Slide 1" />,
    <HeroSlide title="Slide 2" />,
    <HeroSlide title="Slide 3" />,
  ]}
/>
```

*Auto-play*
```tsx
<Slider slides={slides} autoPlay autoPlayInterval={2000} />
```

*Touch swipe + momentum*
```tsx
<Slider
  slides={slides}
  loop={false}
  dragThreshold={50}
  // Drag past 50 px = 1 slide.
  // Flick > 0.5 px/ms = +1 extra slide per 0.5 px/ms of release velocity.
  // Edge resistance (×0.4) keeps you on the rails when loop is off.
/>
```

*No arrows / no loop*
```tsx
<Slider slides={slides} showArrows={false} loop={false} />
```

### VideoPlayer  (`video-player`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/VideoPlayer/index.tsx`
- **Status:** beta (since 2025-04)
- **Description:** Custom HTML5 video player. Quality, subtitle, audio track, and playback rate selection; custom WebVTT subtitle overlay; auto-hiding controls; programmatic API. Keyboard shortcuts: Space/K=play, ←→=±10s, ↑↓=volume, M=mute, F=fullscreen.

**Variants:**

*Full featured (kalite + altyazı + dil)*
```tsx
<VideoPlayer
  src="video.mp4"
  poster="poster.jpg"
  title="Video Title"
  qualities={[
    { label: '1080p HD', value: '1080' },
    { label: '720p',     value: '720'  },
    { label: 'Auto',     value: 'auto' },
  ]}
  subtitles={[
    { label: 'English', srclang: 'en', src: 'en.vtt' },
    { label: 'Türkçe',  srclang: 'tr', src: 'tr.vtt' },
  ]}
  audioTracks={[
    { label: 'English', language: 'en' },
    { label: 'Türkçe',  language: 'tr' },
  ]}
  onQualityChange={(v) => console.log(v)}
  onAudioTrackChange={(i) => console.log(i)}
/>
```

*Subtitle + Font Boyutu*
```tsx
<VideoPlayer
  src="video.mp4"
  poster="poster.jpg"
  title="Elephants Dream"
  subtitles={[
    { label: 'English', srclang: 'en', src: 'en.vtt' },
    { label: 'Türkçe',  srclang: 'tr', src: 'tr.vtt' },
  ]}
/>
```

*Minimal (sadece oynatma hızı)*
```tsx
<VideoPlayer src="video.mp4" poster="poster.jpg" />
```

### MapView  (`map-view`)

- **Layer:** ui
- **Category:** Molecule
- **File:** `modules/ui/MapView/index.tsx`
- **Status:** beta (since 2025-04)
- **Description:** Leaflet-based interactive map. Tooltip-enabled markers, predefined zones (polygon), route lines (polyline), and click-to-add marker mode.

**Variants:**

*Tam özellik — işaretçi + zone + rota*
```tsx
<MapView
  center={[41.015, 28.979]}
  zoom={6}
  markers={CITIES}
  zones={ZONES}
  routes={ROUTES}
  onMarkerClick={(id) => console.log(id)}
  height={420}
/>
```

*Tıkla-ekle işaretçi modu*
```tsx
<MapView
  center={[39.5, 35.0]}
  zoom={5}
  markers={markers}
  onMarkerAdd={(pos) => setMarkers(prev => [
    ...prev,
    { id: String(Date.now()), position: pos, variant: 'warning' },
  ])}
  height={380}
/>
```

*Yalnız zone ve rota*
```tsx
<MapView
  center={[39.5, 35.0]}
  zoom={5}
  zones={ZONES}
  routes={ROUTES}
  height={380}
/>
```

## Components — ui / Organism

### Card  (`card`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Card.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Content container with raised / flat / outline variants. Supports title, subtitle, headerRight, footer slots and loading skeleton state.
- **Design tokens:** --border, --primary, --secondary, --surface-base, --surface-raised, --text-primary, --text-secondary

**Variants:**

*Raised*
```tsx
<Card title="User profile" subtitle="Manage your account" headerRight={<Badge variant="success">Active</Badge>}>
  <p>Card body content goes here.</p>
</Card>
```

*With footer*
```tsx
<Card title="Confirm deletion" footer={<><Button variant="outline" size="sm">Cancel</Button><Button variant="danger" size="sm">Delete</Button></>}>
  <p>This action is irreversible.</p>
</Card>
```

*Flat*
```tsx
<Card variant="flat" title="Flat card">
  <p>No shadow, uses page background color.</p>
</Card>
```

*Outline*
```tsx
<Card variant="outline" title="Outline card">
  <p>Transparent background, border only.</p>
</Card>
```

*Clickable / hoverable*
```tsx
<Card title="Clickable" onClick={() => navigate('/detail')}>...</Card>
<Card title="Hoverable" hoverable>...</Card>
```

*Loading skeleton*
```tsx
<Card loading />
```

### PageHeader  (`page-header`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/PageHeader.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Page title + subtitle + optional badge + action buttons. Supports 5 button variants (primary/secondary/outline/danger/ghost); rendered as a link with href or as a button.
- **Design tokens:** --border, --border-focus, --error, --primary, --primary-fg, --primary-hover, --secondary, --surface-overlay, --text-inverse, --text-primary, --text-secondary

**Variants:**

*With actions*
```tsx
<PageHeader
  title="Users"
  subtitle="Manage your team members."
  badge={<Badge variant="info">48 members</Badge>}
  actions={[
    { label: 'Export', variant: 'outline' },
    { label: '+ Invite user', variant: 'primary' },
  ]}
/>
```

*Danger action*
```tsx
<PageHeader
  title="Danger Zone"
  subtitle="Irreversible actions."
  actions={[
    { label: 'Archive', variant: 'outline' },
    { label: 'Delete project', variant: 'danger' },
  ]}
/>
```

*Minimal*
```tsx
<PageHeader title="Settings" subtitle="Configure your workspace preferences." />
```

### StatCard  (`stat-card`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/StatCard.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Compact metric display card with value, label, and optional accent color.
- **Design tokens:** --error, --success

**Variants:**

*Variants*
```tsx
<StatCard label="Total Users" value={1284} />
<StatCard label="Active"      value={947}  accent="text-success" />
<StatCard label="Transferred" value={38}   accent="text-info" />
<StatCard label="Cancelled"   value={12}   accent="text-error" />
```

### AlertBanner  (`alert-banner`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/AlertBanner.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Page-level info, success, warning or error message. Announced via role="alert" for screen readers with optional dismissible and action support.
- **Design tokens:** --border, --border-focus, --error, --error-subtle, --info, --info-subtle, --success, --success-fg, --success-subtle, --warning, --warning-subtle

**Variants:**

*Info*
```tsx
<AlertBanner variant="info" title="System update" message="A new version is available." dismissible />
```

*Success*
```tsx
<AlertBanner variant="success" message="Profile updated successfully." dismissible />
```

*Warning*
```tsx
<AlertBanner variant="warning" title="Maintenance window" message="The service will be unavailable from 2–4 AM UTC." />
```

*Error*
```tsx
<AlertBanner variant="error" title="Something went wrong" message="Unable to load the resource. Please try again." />
```

*With CTA action*
```tsx
<AlertBanner variant="warning" title="Your plan is expiring" message="Upgrade before your trial ends."
  action={{ label: 'Upgrade now', onClick: handleUpgrade }} dismissible />
```

*Link CTA (action.href)*
```tsx
<AlertBanner variant="info" title="Documentation updated" message="New guides are available."
  action={{ label: 'Read docs', href: '/docs/api' }} />
```

*Custom icon*
```tsx
<AlertBanner variant="info" message="Custom icon override." icon={<RocketIcon />} />
```

### Toast  (`toast`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Toast/index.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Notification system with success/warning/error/info/loading variants. Hover-to-freeze, progress bar, title, actions, and promise support.

**Variants:**

*Variants*
```tsx
toast.success('Kaydedildi.');
toast.info('Güncelleme mevcut.');
toast.warning('Oturum sona eriyor.');
toast.error('Sunucu hatası.'); // persistent
```

*Title + Message*
```tsx
toast.success('Dosya yüklendi.', { title: 'Yükleme tamamlandı' });
toast.error('Sunucuya bağlanılamadı.', { title: 'Bağlantı hatası' });
```

*Actions*
```tsx
toast.info('Öğe silindi.', {
  title: 'Silindi',
  actions: [
    { label: 'Geri Al', onClick: (dismiss) => { undo(); dismiss(); } },
    { label: 'Kalıcı sil', onClick: (d) => { purge(); d(); }, variant: 'danger' },
  ],
});
```

*Loading & Promise*
```tsx
// Loading state (persistent until updated)
toast.loading('İşleniyor...');

// Promise: auto-transitions loading → success/error
toast.promise(fetchData(), {
  loading: 'Yükleniyor...',
  success: (data) => `${data.name} hazır.`,
  error: 'Yüklenemedi.',
});
```

*toast.promise() API*
```tsx
// Single call drives one toast through loading → success | error.
// Strings or value-aware functions are accepted for success/error.
toast.promise(fetchUser(), {
  loading: 'Kullanıcı yükleniyor...',
  success: (u) => `${u.name} (#${u.id}) yüklendi.`,
  error:   (e) => `Hata: ${(e as Error).message}`,
});

// Error path resolves to an assertive role="alert" toast.
toast.promise(fetchBroken(), {
  loading: 'İstek gönderiliyor...',
  success: 'Tamamlandı!',
  error:   (e) => `Başarısız: ${(e as Error).message}`,
});
```

### EmptyState  (`empty-state`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/EmptyState.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Empty-state message shown when there is no data. Supports icon, title, description, and action slots.
- **Design tokens:** --primary, --secondary, --surface-sunken, --text-disabled, --text-primary, --text-secondary

**Variants:**

*With action*
```tsx
<EmptyState icon="📁" title="No projects yet" description="Create your first project to get started." action={<Button variant="primary" size="sm">New project</Button>} />
```

*Minimal*
```tsx
<EmptyState title="No results found" description="Try adjusting your search or filters." />
```

### Pagination  (`pagination`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Pagination.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Page navigation control. Collapses large page counts with ellipsis; accessible via aria-label and aria-current="page".

**Variants:**

*Default*
```tsx
const [page, setPage] = useState(1);
<Pagination page={page} totalPages={10} onPageChange={setPage} />
```

*Sizes*
```tsx
<Pagination page={page} totalPages={10} onPageChange={setPage} size="sm" />
<Pagination page={page} totalPages={10} onPageChange={setPage} size="lg" />
```

*First / Last + Jump to page*
```tsx
<Pagination page={page} totalPages={20} onPageChange={setPage} showFirstLast showJumpTo />
```

### TabGroup  (`tab-group`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/TabGroup.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Accessible tab navigation following the role="tablist" / role="tab" / role="tabpanel" ARIA pattern. Arrow-key navigation; tabIndex=-1 on inactive tabs.
- **Design tokens:** --border, --border-focus, --primary, --secondary, --text-primary, --text-secondary

**Variants:**

*Default*
```tsx
<TabGroup
  label="Account settings"
  tabs={[
    { id: 'profile', label: 'Profile', content: <ProfileSettings /> },
    { id: 'security', label: 'Security', content: <SecuritySettings /> },
    { id: 'billing', label: 'Billing', content: <BillingSettings /> },
  ]}
/>
```

*Icons + badge + disabled*
```tsx
<TabGroup tabs={[
  { id: 'overview', label: 'Overview', icon: <BarChart2 />, content: ... },
  { id: 'analytics', label: 'Analytics', icon: <TrendingUp />, badge: <Badge>New</Badge>, content: ... },
  { id: 'settings', label: 'Settings', disabled: true, content: ... },
]} />
```

*Lazy panels*
```tsx
// With lazy=true, panel content is only rendered when first activated:
<TabGroup lazy tabs={[
  { id: 'heavy', label: 'Heavy', content: <HeavyComponent /> },
]} />
```

### Breadcrumb  (`breadcrumb`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Breadcrumb.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Hierarchical navigation trail wrapped in nav aria-label="Breadcrumb". Last item marked with aria-current="page" and aria-hidden separators.
- **Design tokens:** --border, --border-focus, --primary, --secondary, --text-disabled, --text-primary, --text-secondary

**Variants:**

*Default*
```tsx
<Breadcrumb items={[
  { label: 'Home', href: '/' },
  { label: 'Components', href: '/components' },
  { label: 'Breadcrumb' },
]} />
```

*Long path*
```tsx
<Breadcrumb items={[
  { label: 'Dashboard', href: '/' },
  { label: 'Users', href: '/users' },
  { label: 'Settings', href: '/users/settings' },
  { label: 'Permissions' },
]} />
```

*Custom separator*
```tsx
<Breadcrumb items={[...]} separator={<span>/</span>} />
```

*Overflow / ellipsis*
```tsx
<Breadcrumb items={[/* 6 items */]} maxItems={3} />
```

### Stepper  (`stepper`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Stepper.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Multi-step progress indicator with complete, active, error, and pending states. Supports horizontal and vertical orientations.

**Variants:**

*Horizontal*
```tsx
<Stepper steps={[
  { label: 'Account', state: 'complete' },
  { label: 'Billing', state: 'active' },
  { label: 'Review', state: 'pending' },
  { label: 'Confirm', state: 'pending' },
]} />
```

*Vertical*
```tsx
<Stepper orientation="vertical" steps={[
  { label: 'Create account', state: 'complete' },
  { label: 'Verify email', state: 'error' },
  { label: 'Set up profile', state: 'pending' },
]} />
```

### TreeView  (`tree-view`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/TreeView/index.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Collapsible tree with keyboard navigation, selection, and aria-tree roles.

**Variants:**

*File tree*
```tsx
function Demo() {
  const [sel, setSel] = useState();
  return (
    <TreeView selectedId={sel} onSelect={setSel} label="Files"
      nodes={[
        { id: 'src', label: 'src', children: [
          { id: 'Button', label: 'Button.tsx' },
        ]},
      ]}
    />
  );
}
```

*Navigation menu*
```tsx
function Demo() {
  const [sel, setSel] = useState();
  return (
    <TreeView label="Settings navigation" selectedId={sel} onSelect={setSel}
      nodes={[
        { id: 'account', label: 'Account', children: [
          { id: 'profile', label: 'Profile' },
          { id: 'password', label: 'Password' },
        ]},
        { id: 'workspace', label: 'Workspace', children: [
          { id: 'general', label: 'General' },
          { id: 'billing', label: 'Billing' },
        ]},
        { id: 'integrations', label: 'Integrations' },
      ]}
    />
  );
}
```

*Flat list*
```tsx
function Demo() {
  const [sel, setSel] = useState('ts');
  return (
    <TreeView label="Language selector" selectedId={sel} onSelect={setSel}
      nodes={[
        { id: 'ts', label: 'TypeScript' },
        { id: 'js', label: 'JavaScript' },
        { id: 'py', label: 'Python' },
        { id: 'go', label: 'Go' },
      ]}
    />
  );
}
```

*Multi-select + type-ahead*
```tsx
function Demo() {
  const [ids, setIds] = useState<string[]>(['Card']);
  return (
    <TreeView
      label="Project files"
      selectionMode="multi"
      selectedIds={ids}
      onSelectionChange={setIds}
      nodes={[
        { id: 'docs', label: 'Documents', children: [
          { id: 'spec', label: 'spec.md' },
          { id: 'roadmap', label: 'roadmap.md' },
        ]},
        { id: 'src', label: 'src', children: [
          { id: 'Button', label: 'Button.tsx' },
          { id: 'Card', label: 'Card.tsx' },
          { id: 'Drawer', label: 'Drawer.tsx' },
          { id: 'TreeView', label: 'TreeView.tsx' },
        ]},
      ]}
    />
  );
}

// Try it:
//  - Cmd/Ctrl-click       → toggle individual rows
//  - Shift-click          → range-select between anchor and clicked row
//  - Type "tre"           → focus jumps to "TreeView.tsx"
//  - Cmd/Ctrl+A           → select all visible rows
//  - Arrow keys / Home/End / Space / Enter — full keyboard nav.
```

### TabButton  (`tab-button`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/TabButton.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Pill-style tab button with active/inactive coloring and an optional count badge.

**Variants:**

*Interactive*
```tsx
const [tab, setTab] = useState('all');

<TabButton active={tab === 'all'}      onClick={() => setTab('all')}      count={42}>All</TabButton>
<TabButton active={tab === 'active'}   onClick={() => setTab('active')}   count={18}>Active</TabButton>
<TabButton active={tab === 'archived'} onClick={() => setTab('archived')} count={24}>Archived</TabButton>
```

*Without count*
```tsx
<TabButton active onClick={...}>Selected</TabButton>
<TabButton active={false} onClick={...}>Default</TabButton>
```

### ViewToggle  (`view-toggle`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/ViewToggle.tsx`
- **Status:** stable (since 2026-05)
- **Description:** Horizontal / vertical view toggle control; two-state icon selector. Emits a viewtoggle:change CustomEvent.

**Variants:**

*Default (EN labels)*
```tsx
<ViewToggle value={view} onChange={setView} />
```

*Custom labels*
```tsx
<ViewToggle value={view} onChange={setView} labels={{ horizontal: 'Yatay', vertical: 'Dikey' }} />
```

### Modal  (`modal`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Overlays/Modal/index.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Focus-trapped dialog. Closes on Escape and backdrop click. Requires role="dialog" + aria-modal + aria-labelledby; supports sm/md/lg sizes. Uses the shared Overlays focus-trap, scroll-lock and presence hooks; nested modals are layer-aware so Escape only dismisses the topmost panel.
- **Used by:** onboarding-wizard, rich-text-editor, share-dialog
- **Design tokens:** --border, --border-focus, --primary, --surface-raised, --text-disabled, --text-primary

**Variants:**

*Confirmation dialog*
```tsx
const [open, setOpen] = useState(false);
<Button variant="primary" onClick={() => setOpen(true)}>Open Modal</Button>
<Modal open={open} onClose={() => setOpen(false)} title="Confirm action"
  description="Are you sure you want to proceed?"
  footer={<><Button variant="outline">Cancel</Button><Button variant="danger">Delete</Button></>}>
  <p>This will permanently delete all selected items.</p>
</Modal>
```

*Sizes (sm / md / lg)*
```tsx
<Modal open={open} onClose={onClose} title="Small" size="sm">...</Modal>
<Modal open={open} onClose={onClose} title="Medium" size="md">...</Modal>
<Modal open={open} onClose={onClose} title="Large" size="lg">...</Modal>
```

*Scrollable body*
```tsx
<Modal open={open} onClose={onClose} title="Long Content" scrollable
  footer={<Button>OK</Button>}>
  {/* long content scrolls inside */}
</Modal>
```

*Fullscreen*
```tsx
<Modal open={open} onClose={onClose} title="Fullscreen Dialog" fullscreen>...</Modal>
```

*Nested modals (layer-aware Escape)*
```tsx
// Opens a second modal on top — Escape only dismisses the inner one.
const [outer, setOuter] = useState(false);
const [inner, setInner] = useState(false);
<Modal open={outer} onClose={() => setOuter(false)} title="Outer">
  <Button onClick={() => setInner(true)}>Open Nested</Button>
</Modal>
<Modal open={inner} onClose={() => setInner(false)} title="Nested" size="sm">
  ...
</Modal>
```

### Drawer  (`drawer`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Overlays/Drawer/index.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Side panel sliding in from the screen edge. Left / right placement with focus management and Escape close. Body scroll is locked while open via the shared Overlays useScrollLock hook (iOS rubber-band safe). Accepts closeOnRouteChange (M6 stub).
- **Design tokens:** --border, --border-focus, --primary, --surface-raised, --text-disabled, --text-primary

**Variants:**

*Right drawer*
```tsx
const [open, setOpen] = useState(false);
<Button variant="outline" onClick={() => setOpen(true)}>Open Drawer</Button>
<Drawer open={open} onClose={() => setOpen(false)} title="Settings" side="right"
  footer={<><Button variant="outline">Cancel</Button><Button variant="primary">Save</Button></>}>
  <p>Drawer content goes here.</p>
</Drawer>
```

*Left drawer*
```tsx
<Drawer open={open} onClose={() => setOpen(false)} title="Navigation" side="left">...</Drawer>
```

*Route-aware close (M6 stub)*
```tsx
// closeOnRouteChange is accepted in M1 and reserved for M6 router-events integration.
<Drawer
  open={open}
  onClose={() => setOpen(false)}
  title="Route-aware drawer"
  side="right"
  closeOnRouteChange
>
  ...
</Drawer>
```

### Tooltip  (`tooltip`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Tooltip.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Short hint shown on hover and focus. Accessible via role="tooltip" + aria-describedby. Supports 4 placements, 3 themes, optional arrow, and configurable delay.
- **Design tokens:** --border, --primary, --surface-overlay, --text-primary

**Variants:**

*Placements*
```tsx
<Tooltip content="Help text" placement="top">
  <Button variant="outline" size="sm">Hover me</Button>
</Tooltip>
```

*Themes*
```tsx
<Tooltip content="Dark theme" theme="dark"><Button>Dark</Button></Tooltip>
```

*Arrow + Delay*
```tsx
<Tooltip content="With arrow" arrow placement="top">
  <Button>Arrow</Button>
</Tooltip>
<Tooltip content="500ms delay" delay={500}>
  <Button>Delayed</Button>
</Tooltip>
```

### DropdownMenu  (`dropdown-menu`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/DropdownMenu.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Accessible dropdown using role="menu" + role="menuitem". Closes on Escape and outside click. Supports left/right alignment, icons, separators, danger and disabled items, and arrow-key navigation.
- **Design tokens:** --border, --error, --error-subtle, --primary, --surface-overlay, --surface-raised, --text-primary

**Variants:**

*Default*
```tsx
<DropdownMenu
  trigger={<Button variant="outline" size="sm">Actions ▾</Button>}
  items={[
    { label: 'Edit', icon: '✏' },
    { label: 'Duplicate', icon: '⧉' },
    { type: 'separator' },
    { label: 'Delete', icon: '🗑', danger: true },
  ]}
/>
```

*Right-aligned*
```tsx
<DropdownMenu align="right"
  trigger={<Button variant="ghost" size="sm">⋮</Button>}
  items={[{ label: 'View details' }, { label: 'Remove', danger: true }]}
/>
```

### Popover  (`popover`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Overlays/Popover/index.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Anchor-based contextual panel. Closes on outside click (capture-phase pointerdown) and Escape, layered with sibling overlays. Supports top/bottom/left/right placement. Built-in focus trap (focusTrap prop) keeps Tab cycling inside the panel.

**Variants:**

*Bottom (default)*
```tsx
<Popover trigger={<Button variant="outline">Open</Button>} placement="bottom">
  <div className="p-4">
    <p className="text-sm font-semibold">Title</p>
    <p className="text-xs text-text-secondary">Content goes here.</p>
  </div>
</Popover>
```

*Placements*
```tsx
<Popover placement="top" trigger={<Button>Top</Button>}><div>...</div></Popover>
<Popover placement="right" trigger={<Button>Right</Button>}><div>...</div></Popover>
```

*Focus trap inside Popover*
```tsx
<Popover focusTrap placement="bottom" trigger={<Button>Quick edit</Button>}>
  <form onSubmit={(e) => e.preventDefault()} className="p-4 space-y-3 w-64">
    <input type="text" placeholder="Title" />
    <input type="text" placeholder="Tag" />
    <Button type="submit">Save</Button>
  </form>
</Popover>
```

### Table  (`table`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Table/Table.tsx`
- **Status:** stable (since 2025-02)
- **Description:** Responsive table. scope="col" headers, hover row highlight, empty-state message, and custom cell render support.
- **Design tokens:** --border, --primary, --secondary, --surface-base, --surface-overlay, --surface-sunken, --text-primary, --text-secondary

**Variants:**

*With data*
```tsx
<Table
  columns={[
    { key: 'name', header: 'Name' },
    { key: 'email', header: 'Email' },
    { key: 'status', header: 'Status', render: (row) => <Badge variant={row.status === 'Active' ? 'success' : 'neutral'}>{row.status}</Badge> },
  ]}
  rows={[{ name: 'Jane Doe', email: 'jane@example.com', status: 'Active' }]}
/>
```

*Empty state*
```tsx
<Table columns={[...]} rows={[]} emptyMessage="No users found." />
```

*Sortable columns*
```tsx
<Table
  columns={[
    { key: 'name', header: 'Name', sortable: true },
    { key: 'role', header: 'Role', sortable: true },
  ]}
  rows={rows}
/>
```

### DataTable  (`data-table`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Table/DataTable.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Unified table with `mode="static" | "paginated" | "server"`. Multi-column sort (Shift+click), global search, per-column filter (text + select), pagination, and unified loading/empty/error state.
- **Design tokens:** --border, --secondary, --surface-base, --text-secondary

**Variants:**

*Full example*
```tsx
<DataTable
  caption="Users"
  searchPlaceholder="Search users…"
  pageSize={5}
  rows={users}
  columns={[
    { key: 'name',   header: 'Name' },
    { key: 'email',  header: 'Email' },
    { key: 'role',   header: 'Role' },
    { key: 'status', header: 'Status', render: (r) => <Badge variant={...}>{r.status}</Badge> },
    { key: 'joined', header: 'Joined' },
  ]}
/>
```

*Sortable columns*
```tsx
<DataTable
  rows={products}
  columns={[
    { key: 'name',  header: 'Product',  sortable: true },
    { key: 'price', header: 'Price',    sortable: true, align: 'right' },
  ]}
/>
```

*Server mode (mode="server")*
```tsx
// Unified server-side data flow — the component owns sort/filter/pagination state
// and calls `fetchPage` whenever it changes.
<DataTable<User>
  mode="server"
  fetchPage={async ({ page, pageSize, sort, search, filters }) => {
    const res = await fetch(buildUrl({ page, pageSize, sort, search, filters }));
    const { rows, total } = await res.json();
    return { rows, total };
  }}
  pageSize={5}
  searchPlaceholder="Search users…"
  columns={[
    { key: 'name',  header: 'Name',  sortable: true },
    { key: 'email', header: 'Email', sortable: true, filter: { kind: 'text' } },
    { key: 'team',  header: 'Team',  sortable: true, filter: { kind: 'select', options: [
      { label: 'Platform', value: 'platform' },
      { label: 'Growth',   value: 'growth' },
    ] } },
  ]}
/>
```

### AdvancedDataTable  (`advanced-data-table`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/Table/index.tsx`
- **Status:** beta (since 2025-03)
- **Description:** Enhanced table with row selection (with indeterminate header), expandable rows, and optional sticky header.

**Variants:**

*Selectable + Expandable*
```tsx
<AdvancedDataTable
  columns={[{ key: 'name', header: 'Name' }, ...]}
  rows={rows}
  selectable
/>
```

*Sticky Header*
```tsx
<AdvancedDataTable columns={columns} rows={rows} stickyHeader />
```

### ContentScoreBar  (`content-score-bar`)

- **Layer:** ui
- **Category:** Organism
- **File:** `modules/ui/ContentScoreBar.tsx`
- **Status:** stable (since 2025-03)
- **Description:** Rule-based content quality score with Good ≥70 / Fair ≥40 / Poor <40 tier system. Each rule shown as a chip with passed/total count. role="progressbar" + aria-valuenow.
- **Design tokens:** --border, --error, --error-subtle, --secondary, --success, --success-fg, --success-subtle, --surface-sunken, --text-disabled, --text-secondary, --warning, --warning-subtle

**Variants:**

*Live evaluation*
```tsx
const rules = [
  { label: 'Min 20 chars', check: (v) => v.length >= 20, points: 20 },
  { label: 'Has keyword',  check: (v) => /react/i.test(v), points: 20, hint: 'Include "React"' },
  // ...
];
<ContentScoreBar value={content} rules={rules} label="Quality score" />
```

*All tiers*
```tsx
// Good tier  (score ≥ 70)
<ContentScoreBar value="" rules={allPassRules} label="Good (100%)" />

// Fair tier  (40 ≤ score < 70)
<ContentScoreBar value="" rules={halfPassRules} label="Fair (60%)" />

// Poor tier  (score < 40)
<ContentScoreBar value="" rules={onePassRules}  label="Poor (20%)" />
```

*Password strength*
```tsx
const rules = [
  { label: 'Min 8 chars',  check: (v) => v.length >= 8,          points: 25 },
  { label: 'Uppercase',    check: (v) => /[A-Z]/.test(v),        points: 25 },
  { label: 'Number',       check: (v) => /\d/.test(v),            points: 25 },
  { label: 'Special char', check: (v) => /[^A-Za-z0-9]/.test(v), points: 25 },
];
<ContentScoreBar value={password} rules={rules} label="Password strength" />
```

## Themes
| ID | Title | Route | Status | Since |
|---|---|---|---|---|
| `common` | Common Theme | `/theme/common` | stable | 2025-04 |
| `blog` | Blog Theme | `/theme/blog` | stable | 2025-04 |
| `event` | Event Theme | `/theme/event` | stable | 2025-04 |
| `api-doc` | API Doc Theme | `/theme/api-doc` | stable | 2025-05 |
| `landing` | Landing Theme | `/theme/landing` | stable | 2026-05 |
| `jobs` | Jobs Theme | `/theme/jobs` | stable | 2026-05 |
| `fintech` | Fintech Theme | `/theme/fintech` | stable | 2026-05 |
| `media` | Media Theme | `/theme/media` | stable | 2026-05 |
| `forum` | Forum Theme | `/theme/forum` | stable | 2026-05 |
| `commerce` | Commerce Theme | `/theme/commerce` | stable | 2026-05 |
| `real-estate` | Real Estate Theme | `/theme/real-estate` | stable | 2026-05 |
| `food` | Food Theme | `/theme/food` | stable | 2026-05 |
| `travel` | Travel Theme | `/theme/travel` | stable | 2026-05 |
| `ai` | AI Theme | `/theme/ai` | stable | 2026-05 |
| `social` | Social Theme | `/theme/social` | stable | 2026-05 |
| `iot` | IoT Theme | `/theme/iot` | stable | 2026-05 |
| `nft` | NFT Theme | `/theme/nft` | stable | 2026-05 |
| `promozone` | Personalise Theme | `/theme/promozone` | stable | 2026-07 |