design-system

# 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.