Design System
Overview
A design system is the single source of truth for an organization's UI — combining design tokens, component libraries, documentation, and tooling into a cohesive ecosystem. It ensures consistency, accelerates development, and bridges the gap between design and engineering.
Architecture Layers
┌─────────────────────────────────────────────────┐
│ Design (Figma) │
│ Variables, components, styles, auto-layout │
├─────────────────────────────────────────────────┤
│ Tokens (W3C DTCG / Style Dictionary) │
│ Color, typography, spacing, elevation, motion │
├─────────────────────────────────────────────────┤
│ Components (React, Vue, Angular, Web Comp.) │
│ Buttons, inputs, modals, cards, layouts │
├─────────────────────────────────────────────────┤
│ Documentation (Storybook) │
│ Stories, usage guidelines, interaction tests │
└─────────────────────────────────────────────────┘
Design-to-Code Pipeline
Figma Variables ──► W3C DTCG JSON ──► Style Dictionary ──► CSS / SCSS / iOS / Android
│
Figma Components ──► Code Connect / Mitosis ──────────────► React / Vue / Angular / Svelte
│
▼
Storybook
(catalog + interaction tests)
Token Architecture
Design tokens are the atomic values of a design system — colors, spacing, typography, elevation, motion. They flow through three tiers:
| Tier |
Example |
Purpose |
| Global |
blue-500: #3b82f6 |
Raw palette values |
| Alias / Semantic |
color-primary: {blue-500} |
Intent-based references |
| Component |
button-bg: {color-primary} |
Scoped to a specific component |
Component Strategy
Single-Framework
Build components in one framework (e.g., React) and use Storybook for documentation and testing.
Multi-Framework
Use an intermediary format to target multiple frameworks from a single source:
- Mitosis — JSX subset that compiles to React, Vue, Angular, Svelte, Solid, etc.
- Web Components — Framework-agnostic custom elements usable everywhere
- Stencil — Web Component compiler with lazy loading and SSR
Key Tools
| Tool |
Role |
| Figma |
Visual design, variables, prototyping, Dev Mode |
| W3C Design Tokens |
Vendor-neutral token format (DTCG spec) |
| Style Dictionary |
Transform tokens into platform-specific outputs |
| Storybook |
Component catalog, docs, visual/interaction testing |
| Mitosis |
Write-once component compiler for multiple frameworks |
| Tokens Studio |
Figma plugin for managing tokens in DTCG format |
| Chromatic |
Visual regression testing for Storybook stories |
File Structure
design-system/
tokens/
global/
colors.tokens.json # W3C DTCG format
typography.tokens.json
spacing.tokens.json
semantic/
theme-light.tokens.json
theme-dark.tokens.json
style-dictionary.config.mjs # Token build pipeline
src/
components/
Button/
Button.tsx # Component implementation
Button.stories.tsx # Storybook stories
Button.test.tsx # Unit / interaction tests
.storybook/
main.ts
preview.ts
Best Practices
- Define tokens in W3C DTCG format for vendor neutrality — avoid locking into a single tool's proprietary format.
- Use three-tier token architecture (global → semantic → component) so themes only override the semantic layer.
- Use Style Dictionary to transform tokens into every platform your products target (CSS, SCSS, iOS, Android, Compose).
- Catalog every component in Storybook with args, docs, and play-function interaction tests.
- Use Figma Variables synced to your token files — Tokens Studio or Code Connect bridges the gap.
- For multi-framework orgs, evaluate Mitosis or Web Components before duplicating component code per framework.
- Automate visual regression testing with Chromatic or Percy in CI.
- Version your design system as a package — consumers should pin to semver releases.
1---2name: design-system3description: |4 Use when building or maintaining a design system — the coordinated set of design tokens, component libraries, documentation, and tooling that ensures visual and behavioral consistency across products.5 USE FOR: design system architecture, choosing token formats vs component frameworks, connecting Figma to code, design-to-development workflows, multi-platform consistency6 DO NOT USE FOR: specific token authoring (use design-tokens), Figma workflows (use figma), component cataloging (use storybook), token transformation (use style-dictionary), cross-framework components (use mitosis)7license: MIT8metadata:9 displayName: "Design System"10 author: "Tyler-R-Kendrick"11compatibility: claude, copilot, cursor12references:13 - title: "W3C Design Tokens Community Group"14 url: "https://www.w3.org/community/design-tokens/"15 - title: "Design Tokens Specification"16 url: "https://www.designtokens.org/"17---1819# Design System2021## Overview22A design system is the single source of truth for an organization's UI — combining design tokens, component libraries, documentation, and tooling into a cohesive ecosystem. It ensures consistency, accelerates development, and bridges the gap between design and engineering.2324## Architecture Layers25```26┌─────────────────────────────────────────────────┐27│ Design (Figma) │28│ Variables, components, styles, auto-layout │29├─────────────────────────────────────────────────┤30│ Tokens (W3C DTCG / Style Dictionary) │31│ Color, typography, spacing, elevation, motion │32├─────────────────────────────────────────────────┤33│ Components (React, Vue, Angular, Web Comp.) │34│ Buttons, inputs, modals, cards, layouts │35├─────────────────────────────────────────────────┤36│ Documentation (Storybook) │37│ Stories, usage guidelines, interaction tests │38└─────────────────────────────────────────────────┘39```4041## Design-to-Code Pipeline42```43Figma Variables ──► W3C DTCG JSON ──► Style Dictionary ──► CSS / SCSS / iOS / Android44 │45Figma Components ──► Code Connect / Mitosis ──────────────► React / Vue / Angular / Svelte46 │47 ▼48 Storybook49 (catalog + interaction tests)50```5152## Token Architecture53Design tokens are the atomic values of a design system — colors, spacing, typography, elevation, motion. They flow through three tiers:5455| Tier | Example | Purpose |56|------|---------|---------|57| **Global** | `blue-500: #3b82f6` | Raw palette values |58| **Alias / Semantic** | `color-primary: {blue-500}` | Intent-based references |59| **Component** | `button-bg: {color-primary}` | Scoped to a specific component |6061## Component Strategy6263### Single-Framework64Build components in one framework (e.g., React) and use Storybook for documentation and testing.6566### Multi-Framework67Use an intermediary format to target multiple frameworks from a single source:68- **Mitosis** — JSX subset that compiles to React, Vue, Angular, Svelte, Solid, etc.69- **Web Components** — Framework-agnostic custom elements usable everywhere70- **Stencil** — Web Component compiler with lazy loading and SSR7172## Key Tools73| Tool | Role |74|------|------|75| **Figma** | Visual design, variables, prototyping, Dev Mode |76| **W3C Design Tokens** | Vendor-neutral token format (DTCG spec) |77| **Style Dictionary** | Transform tokens into platform-specific outputs |78| **Storybook** | Component catalog, docs, visual/interaction testing |79| **Mitosis** | Write-once component compiler for multiple frameworks |80| **Tokens Studio** | Figma plugin for managing tokens in DTCG format |81| **Chromatic** | Visual regression testing for Storybook stories |8283## File Structure84```85design-system/86 tokens/87 global/88 colors.tokens.json # W3C DTCG format89 typography.tokens.json90 spacing.tokens.json91 semantic/92 theme-light.tokens.json93 theme-dark.tokens.json94 style-dictionary.config.mjs # Token build pipeline95 src/96 components/97 Button/98 Button.tsx # Component implementation99 Button.stories.tsx # Storybook stories100 Button.test.tsx # Unit / interaction tests101 .storybook/102 main.ts103 preview.ts104```105106## Best Practices107- Define tokens in W3C DTCG format for vendor neutrality — avoid locking into a single tool's proprietary format.108- Use three-tier token architecture (global → semantic → component) so themes only override the semantic layer.109- Use Style Dictionary to transform tokens into every platform your products target (CSS, SCSS, iOS, Android, Compose).110- Catalog every component in Storybook with args, docs, and play-function interaction tests.111- Use Figma Variables synced to your token files — Tokens Studio or Code Connect bridges the gap.112- For multi-framework orgs, evaluate Mitosis or Web Components before duplicating component code per framework.113- Automate visual regression testing with Chromatic or Percy in CI.114- Version your design system as a package — consumers should pin to semver releases.
Tyler-R-Kendrick