# Design System Architecture

> Token hierarchy, theming strategy, and cross-platform consistency

- Skill: `dtsong/design-system-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dtsong/design-system-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dtsong/design-system-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: dtsong (https://skillmd.com/u/dtsong)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/dtsong/design-system-architecture

---


# Design System Architecture

## Purpose

Design a token-based design system architecture, including primitive → semantic → component token hierarchy, theming strategy (dark/light mode), and cross-platform implementation plan.

## Inputs

- Existing styling approach (Tailwind, CSS modules, styled-components, etc.)
- Target platforms (web, iOS, Android, cross-platform)
- Brand guidelines or existing color palette
- Current component inventory
- Theming requirements (dark mode, high contrast, brand variations)

## Process

### Step 1: Audit Current State

Review the existing styling approach:
- How are colors, spacing, and typography defined today?
- Are there hardcoded values scattered across components?
- Is there an existing design system or component library?
- What CSS methodology is used (utility-first, BEM, CSS-in-JS)?

### Step 2: Define Primitive Tokens

Establish the raw values that form the foundation:
- **Color primitives:** Named palette (blue-50 through blue-900, gray scale, semantic colors)
- **Spacing scale:** 4px base unit → 0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64
- **Type scale:** Size ramp with corresponding line heights and letter spacing
- **Border radius:** Small (4px), medium (8px), large (16px), full (9999px)
- **Shadow/elevation:** Subtle, medium, prominent
- **Duration:** Fast (100ms), normal (200ms), slow (300ms)

### Step 3: Define Semantic Tokens

Map primitives to semantic meaning:
- **Surface:** surface-primary, surface-secondary, surface-elevated
- **Text:** text-primary, text-secondary, text-muted, text-inverse
- **Border:** border-default, border-strong, border-focus
- **Interactive:** interactive-primary, interactive-hover, interactive-pressed
- **Status:** status-success, status-warning, status-error, status-info
- **Spacing:** space-xs, space-sm, space-md, space-lg, space-xl

### Step 4: Define Component Tokens

Map semantic tokens to component-specific values:
- **Button:** button-bg, button-text, button-border, button-radius
- **Input:** input-bg, input-border, input-focus-ring, input-text
- **Card:** card-bg, card-border, card-shadow, card-radius, card-padding

### Step 5: Design Theme Architecture

Define how themes override token values:
- **Light theme:** Default token assignments
- **Dark theme:** Which semantic tokens change, which stay the same
- **High contrast:** Increased border widths, higher contrast ratios
- **Implementation:** CSS custom properties, Tailwind config, or platform-specific theming

### Step 6: Cross-Platform Strategy

If multiple platforms:
- **Token format:** Use Style Dictionary or similar to generate platform-specific output
- **Web:** CSS custom properties or Tailwind theme config
- **iOS:** Swift color/spacing constants or asset catalogs
- **Android:** XML resources or Compose theme
- **Shared source of truth:** JSON or YAML token definitions

## Output Format

```markdown
# Design System Architecture

## Token Hierarchy

### Primitive Tokens
| Category | Token | Value |
|----------|-------|-------|
| Color | blue-500 | #3B82F6 |
| Spacing | space-4 | 16px |
| Type | text-base | 16px/24px |

### Semantic Tokens
| Token | Light | Dark | Usage |
|-------|-------|------|-------|
| surface-primary | white | gray-900 | Main background |
| text-primary | gray-900 | gray-50 | Body text |
| interactive-primary | blue-500 | blue-400 | Buttons, links |

### Component Tokens
| Component | Token | Maps To |
|-----------|-------|---------|
| Button (primary) | button-bg | interactive-primary |
| Button (primary) | button-text | text-inverse |

## Theme Switching
[Implementation approach — CSS class, media query, user preference]

## File Structure
```
tokens/
  primitives.json
  semantic-light.json
  semantic-dark.json
  components.json
```

## Migration Plan
[Steps to migrate from current approach to token-based system]
```

## Quality Checks

- [ ] All existing hardcoded values can be mapped to tokens
- [ ] Semantic tokens cover all current UI needs without gaps
- [ ] Dark mode token overrides maintain WCAG AA contrast
- [ ] Token naming is consistent and predictable
- [ ] The migration path doesn't require a big-bang rewrite
- [ ] Cross-platform strategy has a single source of truth

## Evolution Notes
<!-- Observations appended after each use -->