# Design System & Component Library

Status: approved
Owners: Design, Accessibility, Mobile, Web
Last updated: 2025-11-18
Related proposal: `openspec/changes/2025-11-17-design-system/proposal.md`

## Overview

Unified design system and component library for Android, iOS, and Web that ensures platform parity, accessibility (WCAG 2.2 AA+), and consistent brand identity.

## Design Tokens

### Colors

**Primary Palette**
- Primary: `#3B82F6` (blue, adjust for brand)
- Secondary: `#8B5CF6` (purple)
- Error: `#EF4444`
- Success: `#10B981`
- Warning: `#F59E0B`

**Background & Text**
- Light background: `#FFFFFF`
- Dark background: `#1F2937`
- Light text: `#111827`
- Dark text: `#F9FAFB`
- Border light: `#D1D5DB`
- Border dark: `#4B5563`

### Typography

**Font Family**
- iOS: SF Pro
- Android: Roboto
- Web: Inter / system-ui

**Font Sizes**
- 12px, 14px, 16px (base), 18px, 20px, 24px, 32px, 48px

**Font Weights**
- 400 (normal), 600 (semibold), 700 (bold)

**Line Heights**
- 1.5 (body), 1.25 (headings)

### Spacing

**Base Unit**: 4px

**Scale**
- 0 (0px), 1 (4px), 2 (8px), 3 (12px), 4 (16px), 5 (20px), 6 (24px), 8 (32px), 10 (40px), 12 (48px), 16 (64px), 20 (80px)

### Border Radius

- sm: 4px
- md: 8px
- lg: 12px
- full: 9999px (pills/circles)

### Shadows

- sm: `0 1px 2px rgba(0,0,0,0.05)`
- md: `0 4px 6px rgba(0,0,0,0.1)`
- lg: `0 10px 15px rgba(0,0,0,0.15)`

## Core Components

### Button
- Variants: primary, secondary, ghost, danger
- Sizes: sm, md, lg
- States: default, hover, active, disabled, loading
- Accessibility: role="button", aria-label if icon-only, keyboard enter/space
- Touch target: min 44x44pt

### Input
- Types: text, email, password, textarea, number
- States: default, focus, error, disabled
- Validation: inline error messages with icon
- Accessibility: visible or aria-label, aria-describedby for errors

### Card
- Variants: elevated (shadow), outlined (border), flat
- Structure: header (optional), body, footer (optional)
- Accessibility: semantic sectioning (article/section)

### Modal / Dialog
- Backdrop overlay with dialog container
- Close button with clear affordance
- Accessibility: role="dialog", aria-modal, focus trap, Esc to close
- Focus management: return focus on close

### Navigation
- **Mobile**: bottom tab bar, app bar (top), drawer (side)
- **Web**: top nav, sidebar (collapsible), breadcrumbs
- Accessibility: role="navigation", aria-current for active route

### Form
- Validation helpers
- Error state styling
- Field grouping
- Accessibility: associated labels, error announcements

### Additional Components
- Checkbox, Radio, Select/Dropdown
- Avatar, Badge, Chip/Tag
- Spinner/Loading, Progress bar
- Tabs, Accordion
- List (virtualized), Link
- Toast/Snackbar

## Accessibility (WCAG 2.2 AA+)

### Core Requirements
- **Keyboard navigation**: tab order, focus indicators, enter/space activation
- **Screen readers**: accessible names, roles, states via ARIA
- **Color contrast**: 4.5:1 for text, 3:1 for UI components
- **Dynamic type**: components scale with user font size
- **Reduced motion**: animations respect `prefers-reduced-motion`
- **Touch targets**: minimum 44x44pt (mobile), 44x44px (web)

### Theme Support
- **Light mode** (default)
- **Dark mode**
- **High contrast mode** (7:1+ contrast ratios)

### Platform-Specific
- **iOS**: VoiceOver support, SF Symbols, native haptics
- **Android**: TalkBack support, Material icons, ripple effects
- **Web**: semantic HTML, focus-visible CSS, responsive

## Platform Adapters

### Mobile (React Native)
- Shared design tokens in JavaScript/JSON
- Platform-specific implementations for iOS/Android
- Expo modules for advanced features
- E2E testing via Detox

### Web (Next.js/React)
- Design tokens in CSS custom properties
- Semantic HTML with ARIA
- Responsive design (mobile-first)
- Storybook for documentation

## Theming System

- Design tokens in single source of truth
- Light/dark/high-contrast variants
- Runtime theme switching
- CSS variables for web, object config for mobile
- Support for future brand customization

## Testing & Quality Assurance

### Automated Tests
- Unit tests: component prop variations, state changes
- Accessibility tests:
  - Web: axe, react-native-a11y linters (mobile)
  - Automated checks in CI
- Visual regression: screenshot tests for all variants (light/dark/high contrast)
- Cross-platform parity checks

### Manual Testing
- VoiceOver (iOS) / TalkBack (Android) / NVDA/JAWS (web)
- Keyboard-only navigation
- High contrast mode verification
- Touch interaction validation

## Documentation

- **Storybook** for web component showcase
- **Example app** for mobile components
- **Design specifications** for each component
- **Accessibility guidelines** per platform
- **Brand guidelines** and usage patterns

## Release & Versioning

- Semantic versioning (1.0.0)
- Changelog for breaking changes
- Migration guides for component updates
- Quarterly release cycle with patches as needed

## Rollout Plan

**Phase 1 (Core Components)**
- Design tokens + colors, typography, spacing
- Button, Input, Card, Modal
- Basic theming (light/dark)

**Phase 2 (Navigation & Forms)**
- Navigation components
- Form helpers
- List (virtualized)

**Phase 3 (Advanced Components)**
- Tabs, Accordion
- Complex interactions
- Advanced theming (high contrast)

## Integration with Features

- Forum MVP uses design system components
- All new features must use design system
- No custom component creation without approval
- Design review for component additions

## Open Questions

- Final brand colors and logo? (use placeholders initially)
- Icon library choice (SF Symbols, Material, custom SVG)?
- Animation library (Framer Motion for web, Reanimated for mobile)?