UI Design System

UI Design System

1. Design Token Generation

Token Format: W3C DTCG (2025.10)

Use the W3C Design Token Community Group format as the canonical interchange format for tokens:

{
  "color": {
    "brand": {
      "primary": {
        "$type": "color",
        "$value": "oklch(0.65 0.25 265)",
        "$description": "Primary brand color"
      }
    }
  }
}

Key conventions:

• $type declares the token type (color, dimension, fontFamily, fontWeight, etc.)
• $value holds the resolved value
• Group nesting replaces flat naming (e.g., color.brand.primary not color-brand-primary)
• Use Style Dictionary (v4+) to transform DTCG tokens into platform outputs (CSS, iOS, Android, Figma)

Semantic Token Naming (Four-Part Hierarchy)

Structure token names as: category.concept.property.modifier

Examples: color.brand.background.default, color.feedback.error.foreground, space.layout.gap.lg

Color System

From a single brand color, generate a full palette:

Wide-Gamut Color Spaces

Oklch is the preferred perceptually uniform color space for design tokens. It provides consistent lightness across hues, making palette generation predictable:

/* Oklch: lightness, chroma, hue */
--color-brand-500: oklch(0.65 0.25 265);
--color-brand-600: oklch(0.55 0.25 265);  /* Darken by reducing L */

/* Display P3 fallback for broader gamut */
--color-accent: color(display-p3 0.2 0.5 1.0);

• Use oklch() for new projects; it's supported in all modern browsers (2024+)
• Use color(display-p3 ...) for vivid colors beyond sRGB gamut
• Always provide an sRGB fallback with @supports or CSS color() fallback syntax

Typography Scale (1.25x Ratio)

Spacing (8pt Grid)

Base unit: 8px. Scale: 0, 4, 8, 12, 16, 24, 32, 48, 64.

Export Formats

# CSS custom properties
python scripts/design_token_generator.py "#0066CC" modern css > design-tokens.css

# SCSS variables
python scripts/design_token_generator.py "#0066CC" modern scss > _design-tokens.scss

# JSON (for Figma/tooling)
python scripts/design_token_generator.py "#0066CC" modern json > design-tokens.json

2. Component Architecture (Atomic Design)

Variant Patterns

Size:

sm: height 32px, paddingX 12px, fontSize 14px
md: height 40px, paddingX 16px, fontSize 16px
lg: height 48px, paddingX 20px, fontSize 18px

Color:

primary:   background primary-500, text white
secondary: background neutral-100, text neutral-900
ghost:     background transparent, text neutral-700

3. Responsive Design

Breakpoints

Fluid Typography

--fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
--fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
--fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);

4. WCAG Accessibility

Contrast Requirements

Checklist

• Color contrast meets WCAG AA
• Focus indicators visible on all interactive elements
• Touch targets ≥ 44×44px
• Semantic HTML elements used
• All images have alt text

5. Developer Handoff

Framework Integration

React + CSS Variables:

import './design-tokens.css';
<button className="btn btn-primary">Click</button>

Tailwind Config:

const tokens = require('./design-tokens.json');
module.exports = { theme: { colors: tokens.colors, fontFamily: tokens.typography.fontFamily } };

Handoff Checklist

• Token files added to project
• Theme imported in app entry point
• Component library uses tokens only (no hardcoded values)
• Documentation generated

Style Presets

Tooling Reference