Skip to main content

Source: ocean/docs/adr/0011-comprehensive-design-system-enhancements.md | ✏️ Edit on GitHub

ADR-0011: Comprehensive Design System Enhancements

Date: 2025-01-29

Status​

Accepted

Context​

Our design system audit revealed several gaps and opportunities for improvement:

  1. Hardcoded values: Found hardcoded colors in chart components and error boundaries
  2. Missing design tokens: No typography, spacing, shadow, animation, or z-index tokens
  3. No type safety: Design tokens were just CSS variables without TypeScript support
  4. Manual token management: No automated build process or validation
  5. Limited Figma integration: No automated sync between design and code
  6. Token fragmentation: Multiple token files that could drift out of sync

Decision​

We have implemented a comprehensive set of design system enhancements:

1. Fixed Hardcoded Values​

  • Replaced hardcoded colors in chart.tsx with CSS overrides for Recharts
  • Changed bg-orange-500 to semantic bg-accent in error boundary

2. Comprehensive Design Tokens​

Added complete token categories:

  • Typography: Font sizes (xs to 9xl), line heights, font weights, letter spacing
  • Spacing: Full scale from 0 to 96 (matching Tailwind)
  • Shadows: Light and dark mode variants with proper opacity
  • Animations: Duration tokens (75ms to 1000ms) and timing functions
  • Z-index: Consistent layering scale (0, 10, 20, 30, 40, 50, auto)
  • Border radius: Complete set from sm to full

3. TypeScript Type Safety​

Created src/types/design-tokens.ts with:

  • Complete type definitions for all token categories
  • Type-safe token getter functions
  • Autocomplete support in IDEs
  • Runtime token value access

4. Enhanced Build Process​

Implemented Style Dictionary for:

  • Token transformation and validation
  • Multiple output formats (CSS, TypeScript, JSON)
  • Watch mode for development
  • Token validation with detailed error reporting

5. Figma Integration​

Set up GitHub Actions workflow for:

  • Scheduled weekly syncs
  • Manual trigger option
  • Automatic PR creation with changes
  • Token validation before merge

6. Developer Experience​

  • useTokens() hook for React components
  • Comprehensive documentation
  • npm scripts for all token operations
  • Validation and build tooling

Architecture​

design-tokens/
├── base-tokens.json          # Source tokens for Style Dictionary
├── figma-tokens.json         # Tokens from Figma (source of truth)
└── tokens.json               # Legacy tokens (to be migrated)

src/
├── styles/
│   └── tokens.css            # Generated CSS variables
├── types/
│   ├── design-tokens.ts      # TypeScript types
│   └── tokens.generated.ts   # Generated types
├── hooks/
│   └── use-tokens.ts         # React hook for tokens
└── constants/
    └── tokens.json           # Generated JSON tokens

tools/
├── build-tokens.js           # Enhanced build script
├── validate-tokens.js        # Token validation
└── sync-design-tokens.js     # Figma sync (future)

.github/workflows/
└── sync-figma-tokens.yml     # Automated sync workflow

Token Structure​

Color Tokens (Managed by Theme System)​

--background, --foreground
--primary, --primary-foreground
--secondary, --secondary-foreground
--accent, --accent-foreground
--muted, --muted-foreground
--destructive, --destructive-foreground
--card, --card-foreground
--popover, --popover-foreground
--border, --input, --ring
--chart-1 through --chart-5

Typography Tokens​

/* Font Sizes */
--font-size-xs: 0.75rem /* 12px */ --font-size-sm: 0.875rem /* 14px */ --font-size-base: 1rem
  /* 16px */ /* ... up to --font-size-9xl: 8rem */ /* Line Heights */ --line-height-none: 1
  --line-height-tight: 1.25 --line-height-normal: 1.5 /* ... */ /* Font Weights */
  --font-weight-normal: 400 --font-weight-medium: 500 --font-weight-bold: 700 /* ... */;

Spacing Tokens​

--spacing-0: 0 --spacing-1: 0.25rem /* 4px */ --spacing-2: 0.5rem /* 8px */ --spacing-4: 1rem
  /* 16px */ /* ... up to --spacing-96: 24rem */;

Usage Examples​

TypeScript with Type Safety​

import { token, useTokens } from '@/hooks/use-tokens'

// Direct token access
const styles = {
  padding: token('spacing', '4'),        // Autocomplete!
  fontSize: token('fontSize', 'lg'),
  fontWeight: token('fontWeight', 'bold')
}

// Hook usage in components
function MyComponent() {
  const tokens = useTokens()

  return (
    <div style={{
      padding: tokens.spacing[4],
      fontSize: tokens.fontSize.lg
    }}>
      Content
    </div>
  )
}

CSS Usage​

.my-component {
  padding: var(--spacing-4);
  font-size: var(--font-size-lg);
  font-weight: var(--font-weight-semibold);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-lg);
  transition-duration: var(--duration-200);
}

Consequences​

Positive​

  • Type safety: Reduced errors from typos or invalid token usage
  • Consistency: All spacing, typography, and other values follow the scale
  • Maintainability: Single source of truth for design decisions
  • Developer experience: Autocomplete and validation improve productivity
  • Future-proof: Easy to add new tokens or modify existing ones
  • Design-dev sync: Automated workflow keeps design and code aligned

Negative​

  • Build complexity: Additional build step for token generation
  • Learning curve: Developers need to learn the token system
  • Migration effort: Existing components may need updates over time

Neutral​

  • File size: Slightly larger CSS due to comprehensive tokens
  • Dependencies: Added Style Dictionary and validation tools

Migration Strategy​

  1. Phase 1 (Complete): Add comprehensive tokens without breaking changes
  2. Phase 2 (Current): Update components to use tokens where beneficial
  3. Phase 3 (Future): Migrate legacy token files to new system
  4. Phase 4 (Future): Implement full Figma sync automation

Notes​

  • All visual appearance remains unchanged - tokens are additive only
  • The build-tokens.mjs file is preserved but not enhanced to avoid conflicts
  • Color tokens remain dynamically managed by the theme system
  • Documentation created at docs/design-tokens.md for reference

References​