morethanadiagnosis-hub/openspec/specs/design-system.md

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