# OSHUN Design System

Component reference for the OSHUN web app design system.

## Components

### Button

Interactive button with multiple variants, sizes, and states.

| Prop           | Type                                                               | Default     | Description                     |
| -------------- | ------------------------------------------------------------------ | ----------- | ------------------------------- |
| `variant`      | `'primary' \| 'secondary' \| 'ghost' \| 'destructive' \| 'domain'` | `'primary'` | Visual variant                  |
| `size`         | `'sm' \| 'md' \| 'lg'`                                             | `'md'`      | Size variant                    |
| `loading`      | `boolean`                                                          | `false`     | Shows spinner, sets `aria-busy` |
| `leadingIcon`  | `ReactNode`                                                        | —           | Icon before label               |
| `trailingIcon` | `ReactNode`                                                        | —           | Icon after label                |
| `fullWidth`    | `boolean`                                                          | `false`     | Stretch to container width      |
| `disabled`     | `boolean`                                                          | `false`     | Disable interaction             |

**When to use:** Primary actions (submit, save, confirm), secondary actions
(cancel, back), destructive actions (delete, remove).

---

### IconButton

Icon-only button with built-in tooltip and aria-label.

| Prop          | Type                   | Default   | Description                       |
| ------------- | ---------------------- | --------- | --------------------------------- |
| `icon`        | `ReactNode`            | required  | The icon element                  |
| `label`       | `string`               | required  | Accessible label and tooltip text |
| `size`        | `'sm' \| 'md' \| 'lg'` | `'md'`    | Size variant                      |
| `variant`     | `'ghost' \| 'outline'` | `'ghost'` | Visual variant                    |
| `showTooltip` | `boolean`              | `true`    | Show tooltip on hover             |
| `disabled`    | `boolean`              | `false`   | Disable interaction               |

**When to use:** Toolbar actions, compact controls where icon meaning is clear
(close, settings, notifications).

---

### Tabs

Accessible tab interface with roving tabindex and animated indicator.

| Prop        | Type                      | Default  | Description             |
| ----------- | ------------------------- | -------- | ----------------------- |
| `tabs`      | `TabItem[]`               | required | Tab definitions         |
| `activeTab` | `string`                  | required | Currently active tab ID |
| `onChange`  | `(tabId: string) => void` | required | Tab change handler      |
| `domain`    | `DomainName`              | —        | Domain accent color     |
| `size`      | `'sm' \| 'md'`            | `'md'`   | Size variant            |

**ARIA:** Uses `role="tablist"`, `role="tab"`, `aria-selected`, `aria-controls`,
and roving `tabIndex`.

**Keyboard:** ArrowLeft/Right to navigate, Home/End for first/last tab.

---

### Dropdown

Menu dropdown with keyboard navigation and proper ARIA.

| Prop       | Type                   | Default   | Description       |
| ---------- | ---------------------- | --------- | ----------------- |
| `trigger`  | `ReactNode`            | required  | Trigger element   |
| `items`    | `DropdownItem[]`       | required  | Menu items        |
| `onSelect` | `(id: string) => void` | required  | Selection handler |
| `align`    | `'start' \| 'end'`     | `'start'` | Menu alignment    |

**ARIA:** `aria-haspopup="menu"`, `aria-expanded`, `role="menu"`,
`role="menuitem"`, `aria-activedescendant`.

**Keyboard:** Enter/Space/ArrowDown to open, Arrow keys to navigate, Enter/Space
to select, Escape to close, Home/End for first/last item.

---

### SearchInput

Search input with clear button, loading state, and shortcut hint.

| Prop            | Type                      | Default       | Description                             |
| --------------- | ------------------------- | ------------- | --------------------------------------- |
| `value`         | `string`                  | required      | Controlled value                        |
| `onValueChange` | `(value: string) => void` | required      | Change handler                          |
| `loading`       | `boolean`                 | `false`       | Show loading spinner                    |
| `shortcutHint`  | `string`                  | —             | Keyboard shortcut hint (e.g., "Ctrl+K") |
| `size`          | `'sm' \| 'md'`            | `'md'`        | Size variant                            |
| `placeholder`   | `string`                  | `'Search...'` | Placeholder text                        |

**Accessibility:** `type="search"`, auto-derives `aria-label` from placeholder,
clear button has `aria-label="Clear search"`.

---

### OverlaySheet

Modal bottom sheet with focus trap, scroll lock, and restore.

| Prop                   | Type         | Default  | Description                  |
| ---------------------- | ------------ | -------- | ---------------------------- |
| `open`                 | `boolean`    | required | Open state                   |
| `onClose`              | `() => void` | required | Close handler                |
| `title`                | `string`     | —        | Header title                 |
| `description`          | `string`     | —        | Header description           |
| `footer`               | `ReactNode`  | —        | Sticky footer content        |
| `maxWidth`             | `number`     | `540`    | Maximum sheet width          |
| `disableBackdropClose` | `boolean`    | `false`  | Disable backdrop click close |

**Accessibility:** `role="dialog"`, `aria-modal="true"`, focus trap with Tab
cycling, Escape to close, focus restoration on close, body scroll lock.

---

### Toast / ToastProvider

Toast notification system with auto-dismiss and screen reader support.

**Provider:** Wrap app in `<ToastProvider>`. Access via `useToast()` hook.

**Toast variants:** `success`, `error`, `warning`, `info`.

| ToastMessage Prop | Type                 | Default  | Description                 |
| ----------------- | -------------------- | -------- | --------------------------- |
| `variant`         | `ToastVariant`       | required | Visual variant              |
| `title`           | `string`             | required | Toast title                 |
| `description`     | `string`             | —        | Description text            |
| `duration`        | `number`             | `5000`   | Auto-dismiss ms (0 = never) |
| `action`          | `{ label, onClick }` | —        | Action button               |

**Accessibility:** `role="alert"`, `aria-live="assertive"`, dismiss button with
`aria-label="Dismiss notification"`.

---

### Skeleton

Loading placeholder with animated shimmer effect.

| Prop     | Type               | Default           | Description           |
| -------- | ------------------ | ----------------- | --------------------- |
| `width`  | `string \| number` | `'100%'`          | Width                 |
| `height` | `number`           | `16`              | Height in px          |
| `radius` | `string \| number` | `tokens.radii.md` | Border radius         |
| `lines`  | `number`           | `1`               | Number of lines       |
| `gap`    | `number`           | `8`               | Gap between lines     |
| `circle` | `boolean`          | `false`           | Circle shape (avatar) |

**Presets:** `KpiGridSkeleton`, `HeroBannerSkeleton`, `SplitGridSkeleton`,
`DomainCardGridSkeleton`, `DomainSurfaceSkeleton`, `ActivityListSkeleton`,
`ExploreSkeleton`.

---

### VirtualList

Virtualized list for long content (sessions, articles, observations).

| Prop                  | Type                                | Default  | Description                      |
| --------------------- | ----------------------------------- | -------- | -------------------------------- |
| `items`               | `T[]`                               | required | Items array                      |
| `estimatedItemHeight` | `number`                            | required | Estimated row height             |
| `renderItem`          | `(item, index) => ReactNode`        | required | Render function                  |
| `overscan`            | `number`                            | `5`      | Extra items above/below viewport |
| `getKey`              | `(item, index) => string \| number` | —        | Key extractor                    |

---

## Design Tokens

All components use semantic tokens from `@/design-system/tokens`:

- **Colors:** `tokens.semantic.text.*`, `tokens.semantic.surface.*`,
  `tokens.semantic.accent.*`, `tokens.semantic.status.*`
- **Typography:** `tokens.typeScale.*`, `tokens.fontWeights.*`,
  `tokens.fontFamilies.*`
- **Spacing:** `tokens.spacing.*` (4px grid)
- **Radii:** `tokens.radii.*` (xs=4, sm=6, md=8, lg=12, xl=16, 2xl=20,
  full=9999)
- **Shadows:** `tokens.shadows.*` (sm, md, lg, xl)
- **Motion:** `tokens.motion.duration.*`, `tokens.motion.easing.*`
- **Z-index:** `tokens.zIndex.*` (dropdown, modal, toast, etc.)

## Usage Guidelines

1. **Use semantic tokens** — never hardcode colors, use `tokens.semantic.*`
2. **Use design system components** — don't create custom buttons, inputs, etc.
3. **Follow heading hierarchy** — h1 > h2 > h3, no skipping levels
4. **Add aria-labels** to icon-only buttons
5. **Use role="switch" with aria-checked** for toggle buttons
6. **Test with keyboard** — every interactive element must be keyboard
   accessible
