556f74b196
Approved proposals:
- Data Model v1: Consolidated schema with PHI/PII classification
- Authentication System: OAuth2/OIDC with RBAC & pseudonym support
- Design System: Unified components with WCAG 2.2 AA+ compliance
Applied to specs:
- openspec/specs/data-model.md (updated with full schema)
- openspec/specs/authentication.md (new)
- openspec/specs/design-system.md (new)
- openspec/specs/architecture.md (added infrastructure references)
All infrastructure proposals now approved and ready for implementation.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
173 lines
8 KiB
Markdown
173 lines
8 KiB
Markdown
# 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>`
|