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	<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

9.1 CSS Custom Properties (Source of Truth)

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

9.2 Tailwind Config Extension

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

9.3 JavaScript/TypeScript Constants

// 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

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:

/**
 * 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