Phase 1: Design System Foundation - Task Breakdown

Overview

Phase 1 establishes the foundation for the entire design system. These tasks can be worked on in parallel to maximize efficiency.

Timeline: 1-2 weeks Dependencies: None (all tasks can start immediately) Deliverables: Enhanced design tokens, theme provider, updated Tailwind config, Inter font integration

Parallel Task Groups

Group A: Design Tokens Enhancement

Can be done independently - no blockers

Task 1.1: Update Color Palette

File: /packages/design-tokens/src/colors.ts Effort: 4-6 hours Priority: High

Subtasks:

Research and define healthcare color palette
- Primary: Calming medical blue (#0066CC family)
- Secondary: Calming green (#00A67E family)
- Neutral: Soft grays (no pure black)
- Semantic: Success, error, warning, info
Create light mode color scales (50-950 for each)
- Use tools like https://uicolors.app or https://palettte.app
- Ensure 9 shades per color family
Create dark mode color scales
- Adjust luminance for dark backgrounds
- Maintain same color relationships
Define semantic tokens
- background-primary, background-secondary, etc.
- text-primary, text-secondary, text-muted, etc.
- border-default, border-focus, etc.
Verify WCAG contrast ratios
- Use WebAIM Contrast Checker
- Document contrast ratios in comments
- Ensure AA compliance (4.5:1 text, 3:1 UI)

Output:

Updated colors.ts with light and dark variants
Color documentation with contrast ratios
Usage guidelines

Task 1.2: Update Typography System

File: /packages/design-tokens/src/typography.ts Effort: 2-3 hours Priority: High

Subtasks:

Define Inter font family stack

fontFamily: {
  sans: ['Inter', 'system-ui', '-apple-system', ...],
  mono: ['JetBrains Mono', 'Menlo', ...]
}

Create type scale with line heights
- xs through 7xl
- Use rem units
- Include line-height for readability
Define font weights
- Map semantic names: light, normal, medium, semibold, bold
- Use variable font weights (300-700)
Create typography presets for components
- heading1 through heading6
- body, bodySmall, bodyLarge
- caption, overline, button

Output:

Updated typography.ts
Typography documentation
Component typography presets

Task 1.3: Create Component Variant Tokens

New File: /packages/design-tokens/src/components.ts Effort: 3-4 hours Priority: Medium

Subtasks:

Define button variants
- Sizes: sm, md, lg
- Variants: primary, secondary, outline, ghost, danger
- States: default, hover, active, disabled
Define card tokens
- Padding scales
- Shadow levels
- Border radius
Define input tokens
- Heights for different sizes
- Padding
- Border styles
Define spacing tokens for components
- Component-specific spacing
- Layout spacing

Output:

New components.ts file
Component variant documentation

Group B: Theme Infrastructure

Can be done independently - no blockers

Task 1.4: Create Theme Provider

New Files:

/packages/ui/src/providers/ThemeProvider.tsx
/packages/ui/src/providers/ThemeContext.tsx
/packages/ui/src/providers/index.ts

Effort: 4-5 hours Priority: High

Subtasks:

Create ThemeContext

interface ThemeContextValue {
  theme: "light" | "dark" | "system";
  resolvedTheme: "light" | "dark";
  setTheme: (theme: "light" | "dark" | "system") => void;
  toggleTheme: () => void;
}

Create ThemeProvider component
- Manage theme state
- Sync with localStorage
- Support system preference detection
- Apply theme to document root

Create useTheme hook

export function useTheme(): ThemeContextValue;

Add theme transition support
- Smooth color transitions when switching
- Prevent flash of wrong theme
Write tests
- Test theme switching
- Test localStorage persistence
- Test system preference detection

Output:

ThemeProvider component
useTheme hook
Tests for theme functionality

Task 1.5: Create CSS Variables Bridge

New File: /packages/ui/src/styles/theme-variables.css Effort: 3-4 hours Priority: High

Subtasks:

Generate CSS custom properties from design tokens

:root {
  --color-primary-50: ...;
  --color-primary-500: ...;
  --spacing-1: ...;
  --font-size-base: ...;
}

Create dark mode overrides

[data-theme="dark"] {
  --color-primary-50: ...;
  /* Override colors for dark mode */
}

Create semantic tokens

:root {
  --color-background: var(--color-neutral-50);
  --color-text: var(--color-neutral-900);
}

[data-theme="dark"] {
  --color-background: var(--color-neutral-900);
  --color-text: var(--color-neutral-50);
}

Add transition support

* {
  transition:
    background-color 0.2s,
    color 0.2s,
    border-color 0.2s;
}

Output:

CSS variables file
Import in global styles
Documentation on usage

Group C: Integration

Depends on Groups A & B being complete

Task 1.6: Update Tailwind Config

File: /packages/config/tailwind.js Effort: 2-3 hours Priority: High Depends on: Tasks 1.1, 1.2, 1.3

Subtasks:

Import design tokens

const { colors } = require("@voiceassist/design-tokens");
const { typography } = require("@voiceassist/design-tokens");

Configure dark mode

darkMode: 'class', // or ['class', '[data-theme="dark"]']

Extend theme with tokens

theme: {
  extend: {
    colors,
    fontFamily: typography.fontFamily,
    fontSize: typography.fontSize,
    // ...
  }
}

Add custom variants if needed
Configure content paths (ensure all apps/packages included)

Output:

Updated Tailwind config
Documentation on Tailwind usage

Task 1.7: Add Inter Font to Applications

Files:

/apps/web-app/index.html
/apps/admin-panel/index.html

Effort: 1-2 hours Priority: Medium Depends on: Task 1.2

Subtasks:

Add Google Fonts link to both apps

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet" />

Alternative: Self-host fonts
- Download Inter font files
- Add to /packages/ui/src/assets/fonts/
- Create @font-face declarations
Update global styles to use Inter

Output:

Inter font loaded in both apps
Font performance optimized (preconnect, display=swap)

Task 1.8: Update Global Styles

Files:

/apps/web-app/src/styles.css
/apps/admin-panel/src/styles.css

Effort: 2-3 hours Priority: High Depends on: Tasks 1.5, 1.6, 1.7

Subtasks:

Import theme variables

@import "@voiceassist/ui/styles/theme-variables.css";

Apply Tailwind directives

@tailwind base;
@tailwind components;
@tailwind utilities;

Add base styles

@layer base {
  body {
    @apply bg-background text-text font-sans;
  }
}

Add custom utility classes if needed
Ensure accessibility styles are maintained
- Focus indicators
- Reduced motion support
- High contrast mode

Output:

Updated global styles in both apps
Theme applied correctly

Task 1.9: Integrate Theme Provider in Apps

Files:

/apps/web-app/src/App.tsx
/apps/admin-panel/src/App.tsx

Effort: 1-2 hours Priority: High Depends on: Task 1.4

Subtasks:

Import ThemeProvider

import { ThemeProvider } from "@voiceassist/ui/providers";

Wrap app in ThemeProvider

<ThemeProvider>
  <BrowserRouter>{/* existing app */}</BrowserRouter>
</ThemeProvider>

Test theme switching (if implementing toggle now)
Verify no visual regressions

Output:

Theme provider integrated
Apps running with new theme system

Testing & Validation

Testing Checklist

After completing all tasks:

Recommended Execution Order

Week 1:

Day 1-2: Parallel execution

Task 1.1: Update color palette (4-6 hours)
Task 1.2: Update typography (2-3 hours)
Task 1.4: Create theme provider (4-5 hours)

Day 3: Parallel execution

Task 1.3: Component variant tokens (3-4 hours)
Task 1.5: CSS variables bridge (3-4 hours)

Day 4: Sequential execution (dependencies)

Task 1.6: Update Tailwind config (depends on 1.1, 1.2, 1.3)
Task 1.7: Add Inter font (depends on 1.2)

Day 5: Integration & testing

Task 1.8: Update global styles (depends on 1.5, 1.6, 1.7)
Task 1.9: Integrate theme provider (depends on 1.4)
Full testing and validation

Success Criteria

Phase 1 is complete when:

✅ All design tokens are defined (colors, typography, spacing, components)
✅ Both light and dark mode tokens exist
✅ Theme provider is implemented and tested
✅ CSS variables bridge is created
✅ Tailwind config uses design tokens
✅ Inter font is loaded in both apps
✅ Global styles are updated
✅ All tests pass
✅ Build succeeds with no errors
✅ No visual regressions
✅ Documentation is complete
✅ Stakeholder review completed (Week 2 feedback session)

Deliverables

Code:
- Updated design tokens package
- Theme provider in UI package
- Updated Tailwind config
- Updated global styles
Documentation:
- Color palette documentation
- Typography documentation
- Theme provider usage guide
- Migration notes (if any)
Testing:
- Unit tests for theme provider
- Visual regression baselines
- Build validation
Stakeholder Review:
- Design token presentation
- Color palette approval
- Typography approval

Next Steps After Phase 1

Once Phase 1 is complete:

Commit and push all changes
Create PR for review
Schedule stakeholder feedback session (Week 2-3)
Begin Phase 2: Shared Component Library
Start building components using the new design system

Phase 1 Breakdown

Phase 1: Design System Foundation - Task Breakdown

Overview

Parallel Task Groups

Group A: Design Tokens Enhancement

Task 1.1: Update Color Palette

Task 1.2: Update Typography System

Task 1.3: Create Component Variant Tokens

Group B: Theme Infrastructure

Task 1.4: Create Theme Provider

Task 1.5: Create CSS Variables Bridge

Group C: Integration

Task 1.6: Update Tailwind Config

Task 1.7: Add Inter Font to Applications

Task 1.8: Update Global Styles

Task 1.9: Integrate Theme Provider in Apps

Testing & Validation

Testing Checklist

Recommended Execution Order

Success Criteria

Deliverables

Next Steps After Phase 1