morethanadiagnosis-hub/openspec/changes/2025-11-17-design-system/proposal.md

Proposal: Design System & Component Library

Status: approved Authors: Design Team, Accessibility Team Owners: Design Lead, Accessibility Lead, Mobile Lead, Web Lead Created: 2025-11-17 Scope: spec Related: openspec/specs/architecture.md, openspec/specs/accessibility.md

Summary

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

Motivation

• Accelerate feature development with reusable, accessible components.
• Ensure consistent UX and visual language across all platforms.
• Embed accessibility best practices at the component level.
• Support theming for future customization (light/dark mode, high contrast).

Goals / Non-Goals

• Goals: component library (buttons, inputs, cards, modals, navigation), design tokens (colors, typography, spacing), accessibility built-in, platform adapters, documentation/Storybook, versioning.
• Non-Goals: final brand identity (can be iterated); advanced animations (keep simple initially); custom illustrations (use placeholders).

User Stories

• As a developer, I can import pre-built, accessible components to build features quickly.
• As a user with low vision, I can enable high contrast mode and components adapt automatically.
• As a user, I experience consistent visual design whether I'm on mobile or web.
• As a designer, I have a single source of truth for design tokens and component specs.

Requirements

Functional

• Core components: Button, Input (text, email, password, textarea), Checkbox, Radio, Select/Dropdown, Card, Modal/Dialog, Toast/Snackbar, Tabs, Accordion, Navigation (app bar, bottom nav, sidebar), List (virtualized), Avatar, Badge, Chip/Tag, Spinner/Loading, Progress bar, Form (validation helpers), Link.
• Platform implementations: React Native components (mobile), Next.js/React components (web), with shared design tokens.
• Theming: light mode (default), dark mode, high contrast mode.
• Design tokens: colors (primary, secondary, background, text, error, success, etc.), typography (font families, sizes, weights, line heights), spacing (4px grid), border radius, shadows.

Accessibility (WCAG 2.2 AA+)

• All components support:
  • Keyboard navigation (tab order, focus indicators, enter/space activation).
  • Screen reader labels (accessible names, roles, states).
  • Color contrast: minimum 4.5:1 for text, 3:1 for UI components.
  • Dynamic type: components scale with user font size preferences.
  • Reduced motion: animations respect prefers-reduced-motion.
  • Touch targets: minimum 44x44pt (mobile), 44x44px (web).
• High contrast mode: boost contrast ratios to 7:1+.
• Focus management: modals trap focus, dismissible with Esc, return focus on close.

Design Tokens

Colors

• Primary: #3B82F6 (blue, adjust for brand)
• Secondary: #8B5CF6 (purple)
• Background: #FFFFFF (light), #1F2937 (dark)
• Text: #111827 (light mode), #F9FAFB (dark mode)
• Error: #EF4444
• Success: #10B981
• Warning: #F59E0B
• Border: #D1D5DB (light), #4B5563 (dark)

Typography

• Font family: system fonts (SF Pro for iOS, Roboto for Android, Inter/system-ui for web)
• 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)

Component Specifications

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, focus ring
• Touch target: min 44x44

Input

• Types: text, email, password, textarea, number
• States: default, focus, error, disabled
• Accessibility: label (visible or aria-label), aria-describedby for errors, role="textbox" for textarea
• Validation: inline error messages with icon, clear error state styling

Card

• Variants: elevated (shadow), outlined (border), flat
• Structure: header (optional), body, footer (optional)
• Accessibility: semantic sectioning (article/section), focus ring if interactive

Modal

• Structure: overlay (backdrop), dialog container, close button
• Accessibility: role="dialog", aria-modal="true", trap focus, Esc to close, return focus on close, aria-labelledby for title
• Animations: respect prefers-reduced-motion

Navigation

• Mobile: bottom tab bar, app bar (top), drawer (side)
• Web: top nav, sidebar (collapsible), breadcrumbs
• Accessibility: role="navigation", aria-current for active route, keyboard nav (arrow keys for tabs)

Platform-Specific Considerations

• iOS: use SF Symbols for icons, native haptics for interactions, iOS navigation patterns (back swipe).
• Android: use Material icons, ripple effects, Android navigation patterns (drawer, bottom nav).
• Web: use accessible HTML (semantic tags), focus-visible CSS, responsive breakpoints.

Observability & Telemetry

• Component usage analytics (opt-in): track which components are most used to prioritize improvements.
• Accessibility metrics: track high contrast mode adoption, screen reader usage (if detectable).

Test Plan

• Unit tests: component prop variations, state changes, event handlers.
• Accessibility tests:
  • Automated: axe (web), react-native-a11y linters (mobile).
  • Manual: VoiceOver (iOS), TalkBack (Android), NVDA/JAWS (web), keyboard-only nav.
• Visual regression: screenshot tests for all component variants (light/dark/high contrast).
• Cross-platform parity: ensure components look consistent on Android, iOS, Web.

Migration / Rollout Plan

• Phase 1: Design tokens + core components (Button, Input, Card, Modal).
• Phase 2: Navigation, Form helpers, List.
• Phase 3: Advanced components (Tabs, Accordion, etc.).
• Versioning: semantic versioning (1.0.0), changelog for breaking changes.
• Migration guide for existing components (if any from early development).

Risks & Mitigations

• Platform drift → enforce design review for all component changes; automated visual regression tests.
• Accessibility regressions → CI gates for a11y linters; manual audits per release.
• Over-engineering → start with MVP components; add complexity only when needed.

Alternatives Considered

• Custom vs existing design system (Material, Chakra, Ant Design) → choosing custom for brand control and accessibility customization, but borrowing patterns from established systems.
• Shared components vs platform-specific → choosing shared design tokens with platform-specific implementations for best native UX.

Work Breakdown

1. Define design tokens (colors, typography, spacing) in config files
2. Build core components: Button, Input, Card, Modal
3. Platform adapters: React Native (mobile), Next.js/React (web)
4. Accessibility audit and fixes
5. Documentation: Storybook (web), example app (mobile)
6. Visual regression test setup
7. Versioning and release process
8. Design review and feedback iteration
9. Theming implementation (light/dark/high contrast)
10. Rollout to first feature (e.g., Forum MVP)

Acceptance Criteria

• Core components implemented and documented.
• All components pass WCAG 2.2 AA automated checks (axe).
• Manual accessibility audit completed with VoiceOver, TalkBack, NVDA.
• Visual regression tests passing for all variants.
• Design tokens consistent across mobile and web.
• Documentation (Storybook/example app) published.
• At least one feature (e.g., Forum MVP) uses design system components.

Open Questions

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

Slash Commands

• /review areas=mobile,web,accessibility,design
• /apply spec=openspec/specs/architecture.md
• /archive link=<PR>