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 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 2.1 Primitive Palette (Raw Values) /* 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) /* 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) [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 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 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 5.1 Primitive Components (Atoms) Component Status Variants Storybook Button `{{Done WIP Planned}}` Input `{{Done WIP Planned}}` Select `{{Done WIP Planned}}` Checkbox `{{Done WIP Planned}}` Radio `{{Done WIP Planned}}` Toggle/Switch `{{Done WIP Planned}}` Textarea `{{Done WIP Planned}}` Badge `{{Done WIP Planned}}` Avatar `{{Done WIP Planned}}` Tooltip `{{Done WIP Planned}}` Spinner `{{Done WIP Planned}}` Divider `{{Done WIP Planned}}` 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 Item Standard Library `{{Lucide React 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 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 @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 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