# Design System

# Design System Documentation

> **Project:** {{PROJECT_NAME}}
> **Version:** {{VERSION}}
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Draft | In Review | Approved
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |

---

## 1. Design Principles

<!-- GUIDANCE: Define 3-6 core principles that guide every design decision. These should be opinionated and actionable, not generic platitudes. -->

| Principle | Description |
|-----------|-------------|
| **Clarity first** | Every UI element must communicate its purpose without explanation |
| **Consistent over clever** | Prefer familiar patterns over novel interactions |
| **Accessible by default** | WCAG AA compliance is a baseline, not a feature |
| **Density-aware** | Support comfortable and compact density modes |
| **TODO: Add principle** | {{DESCRIPTION}} |

---

## 2. Color System

<!-- GUIDANCE: Define every color token. Use semantic naming (not color names like "blue-500") for usage tokens. -->

### 2.1 Primitive Palette (Raw Values)

```css
/* Brand primitives — do NOT use directly in components */
--color-brand-50:  {{#F0F9FF}};
--color-brand-100: {{#E0F2FE}};
--color-brand-500: {{#0EA5E9}};
--color-brand-600: {{#0284C7}};
--color-brand-900: {{#0C4A6E}};

--color-neutral-0:   #FFFFFF;
--color-neutral-50:  {{#F8FAFC}};
--color-neutral-100: {{#F1F5F9}};
--color-neutral-400: {{#94A3B8}};
--color-neutral-700: {{#334155}};
--color-neutral-900: {{#0F172A}};
--color-neutral-1000: #000000;
```

### 2.2 Semantic Tokens (Light Mode)

```css
/* Background */
--color-bg-primary:   var(--color-neutral-0);
--color-bg-secondary: var(--color-neutral-50);
--color-bg-elevated:  var(--color-neutral-0);

/* Text */
--color-text-primary:   var(--color-neutral-900);
--color-text-secondary: var(--color-neutral-700);
--color-text-disabled:  var(--color-neutral-400);
--color-text-inverse:   var(--color-neutral-0);

/* Interactive */
--color-interactive-primary:        var(--color-brand-500);
--color-interactive-primary-hover:  var(--color-brand-600);
--color-interactive-primary-active: var(--color-brand-700);

/* Semantic */
--color-success:  {{#10B981}};
--color-warning:  {{#F59E0B}};
--color-error:    {{#EF4444}};
--color-info:     {{#3B82F6}};
```

### 2.3 Semantic Tokens (Dark Mode)

```css
[data-theme="dark"] {
  --color-bg-primary:   var(--color-neutral-900);
  --color-bg-secondary: var(--color-neutral-800);
  --color-text-primary: var(--color-neutral-50);
  /* TODO: Complete dark mode token mapping */
}
```

### 2.4 Contrast Ratios (WCAG)

| Pair | Ratio | WCAG AA (4.5:1) | WCAG AAA (7:1) |
|------|-------|-----------------|----------------|
| Text primary on bg primary | {{X:1}} | {{Pass/Fail}} | {{Pass/Fail}} |
| Text secondary on bg primary | {{X:1}} | {{Pass/Fail}} | {{Pass/Fail}} |
| Interactive on bg primary | {{X:1}} | {{Pass/Fail}} | {{Pass/Fail}} |
| White on brand-500 | {{X:1}} | {{Pass/Fail}} | {{Pass/Fail}} |

**TODO:** Run contrast checks with `{{axe | Colour Contrast Analyser}}` and fill table.

---

## 3. Typography

<!-- GUIDANCE: Define all type properties as tokens. Every text style should be composable from these base tokens. -->

### 3.1 Font Families

| Token | Value | Usage |
|-------|-------|-------|
| `--font-heading` | `{{Inter, sans-serif}}` | H1–H4, display text |
| `--font-body` | `{{Inter, sans-serif}}` | Body copy, labels, UI |
| `--font-mono` | `{{JetBrains Mono, monospace}}` | Code, technical data |

### 3.2 Type Scale

| Token | Size | Weight | Line Height | Letter Spacing | Usage |
|-------|------|--------|-------------|----------------|-------|
| `--text-display` | 48px | 700 | 1.1 | -0.02em | Hero headings |
| `--text-h1` | 36px | 700 | 1.2 | -0.01em | Page titles |
| `--text-h2` | 28px | 600 | 1.25 | -0.01em | Section headings |
| `--text-h3` | 22px | 600 | 1.3 | 0 | Subsections |
| `--text-h4` | 18px | 600 | 1.4 | 0 | Card headings |
| `--text-body-lg` | 18px | 400 | 1.6 | 0 | Lead paragraphs |
| `--text-body` | 16px | 400 | 1.6 | 0 | Default body copy |
| `--text-body-sm` | 14px | 400 | 1.5 | 0 | Secondary text, captions |
| `--text-label` | 14px | 500 | 1.4 | 0.01em | Form labels, UI labels |
| `--text-caption` | 12px | 400 | 1.4 | 0.02em | Timestamps, meta |
| `--text-code` | 14px | 400 | 1.6 | 0 | Inline code |

**TODO:** Verify scale against Figma — update values if mismatched.

---

## 4. Spacing & Layout

<!-- GUIDANCE: All spacing must derive from the base unit. No magic numbers in components. -->

### 4.1 Spacing Scale (4px Base Unit)

| Token | Value | Usage |
|-------|-------|-------|
| `--space-0` | 0px | |
| `--space-1` | 4px | Micro gaps, icon padding |
| `--space-2` | 8px | Tight inline spacing |
| `--space-3` | 12px | Compact form elements |
| `--space-4` | 16px | Default content spacing |
| `--space-5` | 20px | Card padding (compact) |
| `--space-6` | 24px | Card padding, section padding |
| `--space-8` | 32px | Large section gaps |
| `--space-10` | 40px | Feature section padding |
| `--space-12` | 48px | Section separation |
| `--space-16` | 64px | Page-level padding |
| `--space-20` | 80px | Hero sections |

### 4.2 Grid System

| Property | Value |
|----------|-------|
| Column count | 12 |
| Column gutter | 24px (mobile: 16px) |
| Container max-width | 1280px |
| Container side padding | 24px (mobile: 16px) |

### 4.3 Responsive Breakpoints

| Name | Min Width | Target Devices |
|------|-----------|----------------|
| `xs` | 0px | Small phones |
| `sm` | 480px | Large phones |
| `md` | 768px | Tablets |
| `lg` | 1024px | Small laptops |
| `xl` | 1280px | Desktops |
| `2xl` | 1536px | Large displays |

---

## 5. Component Library

<!-- GUIDANCE: Categorize all components. Each primitive/composite must have its own entry — reference the component-inventory.md for per-component detail. -->

### 5.1 Primitive Components (Atoms)

| Component | Status | Variants | Storybook |
|-----------|--------|----------|-----------|
| Button | `{{Done | WIP | Planned}}` | primary, secondary, ghost, danger, link | {{URL}} |
| Input | `{{Done | WIP | Planned}}` | default, error, disabled, with-icon | {{URL}} |
| Select | `{{Done | WIP | Planned}}` | single, multi, searchable | {{URL}} |
| Checkbox | `{{Done | WIP | Planned}}` | default, indeterminate, disabled | {{URL}} |
| Radio | `{{Done | WIP | Planned}}` | default, disabled | {{URL}} |
| Toggle/Switch | `{{Done | WIP | Planned}}` | default, disabled | {{URL}} |
| Textarea | `{{Done | WIP | Planned}}` | default, resizable, fixed | {{URL}} |
| Badge | `{{Done | WIP | Planned}}` | success, warning, error, info, neutral | {{URL}} |
| Avatar | `{{Done | WIP | Planned}}` | image, initials, icon | {{URL}} |
| Tooltip | `{{Done | WIP | Planned}}` | top, right, bottom, left | {{URL}} |
| Spinner | `{{Done | WIP | Planned}}` | sm, md, lg | {{URL}} |
| Divider | `{{Done | WIP | Planned}}` | horizontal, vertical | {{URL}} |

### 5.2 Composite Components (Molecules)

| Component | Status | Storybook |
|-----------|--------|-----------|
| Card | `{{Status}}` | {{URL}} |
| Modal / Dialog | `{{Status}}` | {{URL}} |
| Dropdown Menu | `{{Status}}` | {{URL}} |
| Table | `{{Status}}` | {{URL}} |
| Pagination | `{{Status}}` | {{URL}} |
| Toast / Notification | `{{Status}}` | {{URL}} |
| Form Field (label + input + error) | `{{Status}}` | {{URL}} |
| Search Bar | `{{Status}}` | {{URL}} |
| Breadcrumb | `{{Status}}` | {{URL}} |
| Tabs | `{{Status}}` | {{URL}} |
| Accordion | `{{Status}}` | {{URL}} |
| Date Picker | `{{Status}}` | {{URL}} |

### 5.3 Layout Components

| Component | Description |
|-----------|-------------|
| `Container` | Max-width wrapper with responsive padding |
| `Stack` | Vertical flex stack with configurable gap |
| `Inline` | Horizontal flex row with configurable gap/alignment |
| `Grid` | CSS grid layout wrapper |
| `PageLayout` | Full-page layout with sidebar/header/main/footer slots |
| `Section` | Content section with standard vertical rhythm |

---

## 6. Iconography Guidelines

<!-- GUIDANCE: Define the icon library, sizing standards, and usage rules. -->

| Item | Standard |
|------|----------|
| Library | `{{Lucide React | Heroicons | Phosphor}}` |
| Delivery | Inline SVG via component (no sprite, no icon font) |
| Sizes | 16px (sm), 20px (md, default), 24px (lg), 32px (xl) |
| Stroke width | 1.5px at 24px, scaled proportionally |
| Color | Inherits `currentColor` — never hardcoded |
| Interactive icons | Must have visible focus ring + 44×44px touch target |
| Custom icons | SVG optimized via SVGO, placed in `src/components/icons/` |

**Accessibility rule:** Icons conveying meaning must have `aria-label`. Decorative icons: `aria-hidden="true"`.

---

## 7. Motion & Animation Standards

<!-- GUIDANCE: Define animation tokens and rules for when/how motion should be used. -->

### 7.1 Duration Tokens

| Token | Value | Usage |
|-------|-------|-------|
| `--duration-instant` | 50ms | Micro-feedback (checkbox check) |
| `--duration-fast` | 100ms | Button states, hover |
| `--duration-normal` | 200ms | Modals, dropdowns |
| `--duration-slow` | 300ms | Page transitions, large panels |
| `--duration-slower` | 500ms | Onboarding, loading states |

### 7.2 Easing Tokens

| Token | Value | Usage |
|-------|-------|-------|
| `--ease-default` | `cubic-bezier(0.4, 0, 0.2, 1)` | General UI |
| `--ease-enter` | `cubic-bezier(0, 0, 0.2, 1)` | Elements entering |
| `--ease-exit` | `cubic-bezier(0.4, 0, 1, 1)` | Elements leaving |
| `--ease-spring` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | Playful, emphasis |

### 7.3 Reduced Motion

```css
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

**Rule:** Every animated component MUST respect `prefers-reduced-motion`.

---

## 8. Accessibility Requirements Per Component

<!-- GUIDANCE: This is a summary — full audit detail is in accessibility-audit.md. Each component family must meet these baseline requirements. -->

| Requirement | Buttons | Inputs | Modals | Tables | Navigation |
|-------------|---------|--------|--------|--------|------------|
| Keyboard accessible | ✓ | ✓ | ✓ | ✓ | ✓ |
| Focus visible | ✓ | ✓ | Focus trap | ✓ | ✓ |
| ARIA role | `button` | `textbox`/`combobox` | `dialog` | `table`/`grid` | `nav` |
| Screen reader label | aria-label or visible text | `<label>` associated | `aria-labelledby` | Caption + headers | `aria-label` |
| Error state | `aria-describedby` error msg | `aria-invalid` | — | — | — |
| Touch target | 44×44px min | 44px height | — | Row: 44px min | 44×44px |

---

## 9. Design Token Format

<!-- GUIDANCE: Define how tokens are exported and consumed. Choose ONE canonical format. -->

### 9.1 CSS Custom Properties (Source of Truth)

```css
/* tokens/colors.css */
:root {
  --color-brand-500: #0EA5E9;
  /* ... */
}
```

### 9.2 Tailwind Config Extension

```js
// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        brand: {
          500: 'var(--color-brand-500)',
          // ...
        }
      }
    }
  }
}
```

### 9.3 JavaScript/TypeScript Constants

```ts
// tokens/colors.ts — for use in charting libraries, canvas, etc.
export const colors = {
  brand500: '#0EA5E9',
  // ...
} as const;
```

**Token update process:** Figma → `Style Dictionary` export → CSS/JS/Tailwind files → PR review.

---

## 10. Component Documentation Standard

<!-- GUIDANCE: Every component in the library must follow this documentation format in Storybook. -->

Each component story must include:
1. **Default** story — basic render with minimal props
2. **All Variants** story — every visual variant displayed
3. **All States** story — hover, focus, disabled, error, loading
4. **Responsive** story — behavior at each breakpoint
5. **Accessibility story** — keyboard navigation, screen reader notes

Component JSDoc minimum:

```tsx
/**
 * Button component for primary user actions.
 *
 * @example
 * <Button variant="primary" onClick={handleSubmit}>Save Changes</Button>
 */
```

**Props table:** Every prop must have: type, default, required flag, description.

---

## Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Lead Designer | | | |
| Frontend Lead | | | |
| Accessibility Reviewer | | | |