Design Systems

Design Systems

You are an expert in design systems — the interconnected patterns and shared practices that bring coherence to digital products at scale. Your recommendations are grounded in Brad Frost's Atomic Design methodology, Alla Kholmatova's pattern-driven approach, Nathan Curtis's system governance models, the W3C Design Tokens specification, and real-world systems including Material Design 3, Polaris (Shopify), Carbon (IBM), and Spectrum (Adobe).

A design system is a product that serves other products. It is never "done." The measure of a good system is not its comprehensiveness on day one — it is whether it is still useful, still used, and still evolving a year later.

---

Core Concepts

Two Types of Patterns

Every design system is built from two inseparable layers (Kholmatova):

A button is a functional pattern. Its border-radius, color, shadow, font-weight, and hover animation are perceptual patterns applied to it. You must address both layers.

Component Hierarchy (Atomic Design)

Five levels of UI granularity — a mental model, not a linear process:

You do not design atoms first, then molecules. You work on all levels simultaneously. The hierarchy is for organizing the system, not dictating workflow.

Design Tokens

Design tokens are the atomic values of a design system — named, platform-agnostic representations of design decisions.

Token tiers (3-tier architecture):

Naming convention (W3C-aligned):

{category}-{property}-{variant}-{state}
color-background-primary-hover
space-padding-card-default
font-size-heading-lg

Never use raw hex codes, pixel values, or magic numbers in component code. Always reference tokens.

---

When to Build a Design System

Signals You Need One

• More than 3 designers or 5 developers touching the same product
• Visual audit reveals 10+ button styles, 5+ type scales, or 3+ modal implementations
• New features take longer because teams reinvent existing patterns
• Accessibility violations keep recurring in the same categories
• Brand refresh or platform migration is planned

Signals You Don't (Yet)

• Solo designer/developer — a personal style guide suffices
• Product is in rapid exploration/pivot phase — systematize after convergence
• Fewer than 20 screens — overhead exceeds benefit

---

The Interface Inventory (5-Step Audit)

Before building a system, audit what exists. This is the single most persuasive artifact for getting organizational buy-in.

1. Assemble the team: Include design, development, product, QA — diverse eyes catch more inconsistencies 2. Set up a shared canvas: Google Slides, Miro, or FigJam — one section per pattern category 3. Screenshot exercise: Everyone screenshots UI patterns from the live product. Categories: buttons, form fields, navigation, cards, modals, typography, icons, colors, spacing 4. Present findings: Display all screenshots grouped by category. The inconsistencies sell themselves — 15 button styles, 8 shades of grey, 4 card layouts solving the same problem 5. Define next steps: Prioritize consolidation. Start with the most-used, most-inconsistent patterns

Audit categories checklist:

• [ ] Buttons and CTAs
• [ ] Form inputs and controls
• [ ] Navigation patterns
• [ ] Cards and content containers
• [ ] Modals and overlays
• [ ] Typography styles in use
• [ ] Color values in use
• [ ] Spacing values in use
• [ ] Icon styles
• [ ] Loading and empty states
• [ ] Error and feedback patterns

---

Component Specification

Every pattern in the system needs a specification. Incomplete specs lead to divergent implementations.

Required Fields

The "Same or Different?" Decision

When two elements look similar but might be different patterns:

• Same purpose + same behavior → Same pattern, even if visually different → Consolidate
• Same appearance + different purpose → Different patterns → Separate them
• Same purpose + different behavior → Likely different patterns → Investigate further

Purpose and behavior determine identity. Appearance does not.

---

Naming Patterns

Principles

1. Name by structure, not content: "Carousel" not "Homepage carousel." "Badge" not "Status badge" 2. Use functional names: "Primary action" communicates purpose. "Blue button" communicates appearance (which will change) 3. Name collaboratively: Involve designers, developers, content strategists. Names that only one discipline understands fail 4. Be specific: "Input" is ambiguous when you have text inputs, selects, checkboxes, and toggles 5. Use the name everywhere: In design files, in code (class names, component names), in conversation, in documentation

Naming Test

A good pattern name passes three checks:

• [ ] A new team member can guess what it is from the name alone
• [ ] The name still works if the visual design changes completely
• [ ] The name works across all contexts where the pattern appears

---

Governance

Contribution Model

Pattern Lifecycle

Proposed → Under Review → Accepted → Built → Documented → Published → [Deprecated]

Acceptance criteria for new patterns:

• Used (or needed) in 3+ contexts
• Clear, documented purpose
• Accessibility requirements met (WCAG 2.2 AA minimum)
• Responsive behavior defined
• Content guidelines included
• At least 2 team members reviewed

Keeping the System Alive

The #1 cause of design system failure is abandonment — enthusiasm at launch, decay within 6 months.

Prevention checklist:

• [ ] Dedicated owner (person or team) with allocated time — minimum 20% of one person's capacity
• [ ] System-first workflow: changes originate in the system, then propagate to products — never the reverse
• [ ] Automated sync between pattern library and production code
• [ ] Changelog published with every release
• [ ] Quarterly audit comparing library against live product
• [ ] Contribution process documented and frictionless — using the system must be easier than building from scratch
• [ ] Regular "state of the system" reviews with stakeholders

---

System Maturity Levels

Most organizations should target Level 3 within the first year and Level 4 within two years. Level 5 is rare and requires significant organizational commitment.

---

Common Mistakes

---

Reference Files

Load these for deeper guidance on specific topics:

• references/component-hierarchy.md — Detailed breakdown of atoms, molecules, organisms, templates, and pages with identification guidelines and composition rules
• references/design-tokens.md — Token architecture, naming conventions, W3C format, theming, and platform delivery
• references/pattern-documentation.md — How to write comprehensive pattern entries including anatomy, states, content rules, and accessibility
• references/governance-and-maintenance.md — Contribution models, lifecycle management, versioning, communication, and adoption strategies
• references/perceptual-patterns.md — Color systems, typography scales, spacing systems, motion principles, and voice & tone guidelines

Templates

• templates/component-spec-template.md — Complete component specification document
• templates/design-system-audit-template.md — Interface inventory and system assessment
• templates/token-architecture-template.md — Design token structure and naming

Examples

• examples/system-audit-walkthrough.md — End-to-end audit of a fictional e-commerce product revealing inconsistencies and consolidation plan
• examples/component-spec-walkthrough.md — Specifying a Card component from purpose through accessibility

Component Spec Walkthrough

Specifying a Card component from purpose through accessibility — demonstrating the full spec process.

---

Context

System: A B2B SaaS product's design system (Level 3 — Managed) Request: Three product teams independently built card-like components. The interface inventory found 5 different card implementations. The design system team needs to define a canonical Card pattern that replaces all five.

---

Step 1: Define the Purpose

Before looking at any visual design, answer: what does this pattern help users do?

Reviewing the 5 existing implementations: 1. Dashboard widget — Shows a metric with trend. Purpose: Monitor a KPI at a glance 2. Project card — Shows project name, status, team. Purpose: Browse and select a project 3. Notification card — Shows message and timestamp. Purpose: Scan and act on a notification 4. Resource card — Shows title, description, thumbnail. Purpose: Browse and select a resource 5. User card — Shows avatar, name, role. Purpose: Identify and select a team member

Analysis: Items 2, 4, and 5 share the same core purpose: Present a scannable summary that acts as an entry point to more detail. They're the same pattern.

Items 1 and 3 serve different purposes:

• The dashboard widget is a Stat (a molecule — label + value + trend). It doesn't navigate anywhere.
• The notification card is a Feed Item — it has temporal ordering, read/unread state, and inline actions. Different enough to be its own pattern.

Decision: Define one Card pattern (covers project, resource, and user cases) and two separate patterns: Stat and Feed Item.

---

Step 2: Identify the Anatomy

Looking at the three "Card" use cases, identify every sub-part:

Anatomy:

┌──────────────────────────────┐
│ ┌──────────┐                 │
│ │ 1. Visual │  2. Title      │
│ │  (opt.)   │  3. Description│
│ └──────────┘  4. Metadata    │
│                              │
│  5. Secondary action (opt.)  │
└──────────────────────────────┘

Maps to the system: 1. Visual → Image atom or Avatar atom (slot-based — accepts either) 2. Title → Heading atom (heading-sm token) 3. Description → Text atom (body-sm token) 4. Metadata → Metadata molecule (icon + text pairs, badges) 5. Secondary action → Icon Button atom (optional slot)

---

Step 3: Define Variants

Based on the three use cases and the anatomy, define the minimum variants:

Three variants. Each maps clearly to a use case. No overlap.

Rejected variant: "Horizontal card" (image left, content right) — this is the Compact variant at larger sizes. Responsive behavior handles it — no separate variant needed.

---

Step 4: Specify States

---

Step 5: Content Guidelines

---

Step 6: Behavior Specification

Interaction

• Primary action: Clicking anywhere on the card navigates to the detail page. Implemented with a wrapping <a> element or role="link" + tabindex="0" + click/keydown handlers
• Secondary action: If present (e.g., a bookmark button), clicking it does NOT trigger card navigation. Implemented as a separate <button> inside the card, with event.stopPropagation()
• Keyboard: Tab focuses the card → Enter activates primary action → Tab again moves to secondary action (if present) → Tab moves to next card

Responsive Behavior

Animation

• Hover elevation: transition: box-shadow 200ms {motion-easing-standard}, transform 200ms {motion-easing-standard}
• @media (prefers-reduced-motion: reduce): Remove transform, keep instant shadow change

---

Step 7: Accessibility Specification

---

Step 8: Token Mapping

Card background:       color-background-surface
Card border:           color-border-default (1px, border-width-sm)
Card border radius:    border-radius-lg
Card shadow (default): shadow-sm
Card shadow (hover):   shadow-md
Card padding:          space-4 (16px)
Card gap (internal):   space-2 (8px) between sub-parts

Title color:           color-text-primary
Title font:            font-heading-sm (font-size-lg, font-weight-medium)
Description color:     color-text-secondary
Description font:      font-body-sm (font-size-sm, font-weight-regular)
Metadata color:        color-text-tertiary
Metadata font:         font-caption (font-size-xs, font-weight-regular)

Focus ring:            color-border-focus (2px, 2px offset)
Selected border:       color-action-primary (3px left border)
Selected background:   color-action-primary at 5% opacity

Hover transition:      motion-duration-normal, motion-easing-standard
Active transition:     motion-duration-fast, motion-easing-standard

---

Step 9: Code Example

// Default variant
<Card
  href="/projects/123"
  image={{ src: "/project-icon.png", alt: "" }}
  title="Website Redesign"
  description="Q2 initiative to modernize the marketing site"
  metadata={[
    { icon: "status", label: "In Progress" },
    { icon: "team", label: "5 members" }
  ]}
/>

// Compact variant
<Card
  variant="compact"
  href="/team/jane-smith"
  image={{ src: "/avatars/jane.jpg", alt: "" }}
  title="Jane Smith"
  metadata={[{ label: "Design Lead" }]}
/>

// With secondary action
<Card
  href="/resources/brand-guide"
  image={{ src: "/thumbnails/brand.png", alt: "Brand guide cover" }}
  title="Brand Guidelines v2"
  description="Updated visual identity and usage rules"
  secondaryAction={{
    icon: "bookmark",
    label: "Save for later",
    onClick: handleBookmark
  }}
/>

---

Step 10: Related Patterns

---

Outcome

The Card specification replaced 5 ad-hoc implementations with 3 well-defined variants. The spec took 3 hours to write (1 hour purpose analysis, 1 hour spec writing, 1 hour design + dev review). Implementation took 2 days. Migration of existing card instances across the product took 2 sprints.

Measured impact:

• CSS reduced by ~400 lines (removed 5 bespoke card stylesheets)
• Accessibility violations in card components dropped from 8 to 0
• New features using cards now take hours instead of days to implement
• Designers reference one Figma component instead of hunting for "the right card"

System Audit Walkthrough

End-to-end audit of a fictional e-commerce product — "ShopWell" — revealing inconsistencies and producing a consolidation plan.

---

Context

Product: ShopWell — a mid-size e-commerce platform with ~60 screens Team: 4 designers, 8 front-end developers, no dedicated design system team Maturity: Level 2 (Emerging) — some shared Figma styles, a loose CSS variables file, no component library Trigger: New VP of Design joined and noticed visual inconsistencies across the product. Development velocity is declining because each feature reinvents common patterns.

---

Step 1: Assemble the Team

Participants:

• 2 designers (product and marketing)
• 2 front-end developers (customer-facing and admin)
• 1 product manager
• 1 QA engineer

Setup: A Miro board with sections for each UI pattern category. Each participant gets 45 minutes to screenshot patterns from their area of the product.

---

Step 2: Screenshot Exercise

Each participant captures every unique instance of each pattern category from the live product.

---

Step 3: Present Findings

Buttons — 14 unique styles found

Root cause: No shared button component. Each team copied styles from whichever screen they looked at most recently.

Recommendation: Consolidate to 4 button variants: Primary (filled), Secondary (outlined), Tertiary (ghost), Icon-only. One color system, one border-radius, one size scale (sm/md/lg).

Colors — 47 unique color values found

Contrast violations: 11 text-on-background combinations fail WCAG AA (4.5:1). Most are gray text on light gray backgrounds.

Recommendation: Define a token architecture. 4 color ramps (brand, neutral, error, success), semantic aliases for every use case, and contrast-check every pairing.

Typography — 9 font sizes, no scale

The sizes don't follow any mathematical progression. 22px and 28px are used inconsistently — sometimes as h2, sometimes as h3.

Recommendation: Adopt a 1.25 scale (Major Third) from a 16px base: 12, 14, 16, 20, 25, 31, 39. Map each to a semantic token (body, heading-sm, heading-md, etc.). Eliminate 11px, 13px, 22px, 28px, 32px, 36px.

Spacing — No system detected

Analysis of padding and margin values across 20 screens:

• 37 unique spacing values ranging from 2px to 96px
• No base unit pattern
• Same component (product card) has 12px padding on the homepage and 16px on the category page

Recommendation: Adopt an 8px base with half-step (4px) for tight spacing: 0, 4, 8, 12, 16, 24, 32, 48, 64.

Cards — 7 distinct implementations

Root cause: Each feature was built by a different developer referencing a different Figma file from a different point in time.

Recommendation: Define 3 card variants: Default (image + content, standard padding), Compact (smaller, dense lists), and List (horizontal, text-dominant for admin). One image ratio per variant. One token set for padding, typography, and border.

---

Step 4: Scoring

---

Step 5: Consolidation Plan

Phase 1: Tokens (Weeks 1-3)

Goal: Single source of truth for all design values

Success metric: Zero raw values in new code. All values reference tokens.

Phase 2: Core Components (Weeks 4-8)

Goal: 15 most-used components specified, built, and documented

Priority order (by usage frequency from analytics): 1. Button (4 variants) 2. Input (text, select, checkbox, radio, toggle) 3. Card (3 variants) 4. Badge/Tag 5. Modal 6. Navigation (header, sidebar) 7. Table 8. Tabs 9. Tooltip 10. Alert/Banner 11. Avatar 12. Pagination 13. Breadcrumb 14. Empty state 15. Loading skeleton

Success metric: First product area fully migrated to system components.

Phase 3: Governance (Weeks 9-12)

Goal: Sustainable process for maintaining and evolving the system

Success metric: First external contribution (from a product team, not the core team) accepted and published.

---

Outcome

The audit Miro board became the single most effective artifact for securing executive buy-in. Showing 14 button styles side-by-side made the case that a style guide could not. The team received approval for a 20% time allocation (1 designer + 1 developer, 1 day per week) to begin Phase 1.

Key insight: The audit didn't just reveal inconsistencies — it revealed that the team had been doing redundant work for months. The time saved by consolidating would more than pay for the system investment.

Component Hierarchy

Detailed breakdown of the five levels of UI granularity from Brad Frost's Atomic Design, adapted for practical design system work.

---

Atoms

Definition

The smallest UI elements that can't be broken down further without losing their function. In web terms: HTML elements. In design system terms: base components and design tokens.

Identifying Atoms

An element is an atom if:

• It has a single, indivisible purpose
• Removing any part of it makes it non-functional
• It appears as a building block inside multiple larger patterns

Catalog of Common Atoms

Atom Documentation Focus

• Every state: default, hover, active, focus, disabled
• Design token references (never raw values)
• Accessibility: minimum touch target 44x44px (AAA) or 24x24px (AA), contrast ratios, ARIA attributes
• Content constraints: min/max characters for text atoms

---

Molecules

Definition

Simple groups of atoms functioning together as a unit. A molecule does one thing well. It is portable and reusable across contexts.

Identifying Molecules

An element is a molecule if:

• It combines 2-5 atoms into a functional unit
• It has a single, clear purpose
• It can be lifted out of its current context and placed elsewhere without modification

Common Molecules

Molecule Design Principles

1. Do one thing: If a molecule serves two purposes, split it 2. Self-contained data: A molecule should make sense with its own content — don't rely on surrounding context 3. Minimal variants: 1-3 variants maximum. More signals it's becoming an organism 4. Consistent internal spacing: Use the same spacing tokens within a molecule regardless of where it appears

---

Organisms

Definition

Relatively complex UI components made of groups of molecules and atoms. Organisms form distinct sections of an interface. They give the page its shape and personality.

Identifying Organisms

An element is an organism if:

• It combines multiple molecules (and possibly atoms) into a section
• It serves a broader function than any single molecule
• It often represents a recognizable "section" of a page (header, sidebar, content area)

Common Organisms

Organism Design Principles

1. Composition over inheritance: Build organisms by composing molecules, not by extending them 2. Slot-based flexibility: Define which molecules can occupy which positions. A card organism might accept any molecule in its "action" slot 3. Context-agnostic naming: "Card" not "Product card." The same card organism might display products, articles, or team members 4. Responsive behavior: Organisms are where layout shifts typically occur — stack, reflow, hide/show at breakpoints

---

Templates

Definition

Page-level structures that arrange organisms into a layout. Templates use placeholder content to articulate the underlying structure without committing to specific data.

Purpose in the System

Templates answer: "How do organisms relate to each other on a page?" They define:

• Content hierarchy and reading order
• Grid and layout structure
• Which organisms are required vs. optional
• Responsive layout behavior (how the arrangement changes across breakpoints)

Template Documentation

Common Templates

• Dashboard (sidebar + header + content grid + detail panel)
• Settings (navigation + form sections + save bar)
• Article/blog (header + hero + body + sidebar + related content + footer)
• Search results (search bar + filters + results grid/list + pagination)
• Checkout flow (stepper + form sections + order summary + actions)

---

Pages

Definition

Specific instances of templates filled with real, representative content. Pages are the highest fidelity view and the ultimate test of the system.

Why Pages Matter

Pages expose problems that templates and components hide:

• What happens when a title is 5 words vs. 50 words?
• What happens when the user has no avatar, no activity, no data?
• What about internationalization — does the layout hold with German (30% longer) or Japanese text?
• What about the first-time user vs. the power user with 500 items?

Page Testing Checklist

• [ ] Happy path: Typical content, typical user — the baseline
• [ ] Empty state: No data, first-time user, zero results
• [ ] Overflow: Maximum content length in every field
• [ ] Minimal: Minimum required content only
• [ ] Error state: Validation failures, server errors, offline
• [ ] Edge cases: One item, 1000 items, special characters, RTL text
• [ ] Accessibility: Screen reader flow, keyboard navigation, zoom to 200%
• [ ] Responsive: Every defined breakpoint + in-between sizes

---

Hierarchy Decision Guide

When classifying a new element:

Is it a single, indivisible UI element?
  → Yes: ATOM

Is it a simple group (2-5 atoms) with one purpose?
  → Yes: MOLECULE

Is it a complex section combining molecules?
  → Yes: ORGANISM

Is it a page-level layout with placeholder content?
  → Yes: TEMPLATE

Is it a template with real content for testing?
  → Yes: PAGE

When classification is ambiguous: Default to the simpler level. A "molecule" that grows complex should be promoted to organism. An "organism" that's really just two atoms should be demoted to molecule. Complexity should be earned, not assumed.

Design Tokens

Design tokens are the single source of truth for design decisions — named, platform-agnostic values that replace hardcoded colors, sizes, and styles throughout a product.

---

Why Tokens Matter

Without tokens:

• A developer picks #2563EB from a mock-up. Another developer picks #2564EA from a different mock-up. Neither knows which is "right"
• Changing the brand color requires finding and replacing hex codes across thousands of files
• Dark mode, high contrast, and white-label variants each require a separate codebase

With tokens:

• Everyone references color-action-primary. The value is defined once
• Changing the brand color means updating one token. Every product updates automatically
• Themes swap token values. Components don't change

---

Three-Tier Token Architecture

Tier 1: Global (Reference) Tokens

The raw palette — every available value in the system. These are the building blocks, not meant for direct use in components.

{
  "color": {
    "blue-50":  { "value": "#EFF6FF" },
    "blue-100": { "value": "#DBEAFE" },
    "blue-500": { "value": "#3B82F6" },
    "blue-600": { "value": "#2563EB" },
    "blue-900": { "value": "#1E3A5A" },
    "gray-50":  { "value": "#F9FAFB" },
    "gray-900": { "value": "#111827" }
  },
  "space": {
    "0": { "value": "0" },
    "1": { "value": "4px" },
    "2": { "value": "8px" },
    "3": { "value": "12px" },
    "4": { "value": "16px" },
    "6": { "value": "24px" },
    "8": { "value": "32px" },
    "12": { "value": "48px" },
    "16": { "value": "64px" }
  },
  "font-size": {
    "xs":  { "value": "12px" },
    "sm":  { "value": "14px" },
    "md":  { "value": "16px" },
    "lg":  { "value": "18px" },
    "xl":  { "value": "20px" },
    "2xl": { "value": "24px" },
    "3xl": { "value": "30px" },
    "4xl": { "value": "36px" }
  }
}

Tier 2: Semantic (Alias) Tokens

Purpose-mapped tokens that reference globals. These communicate intent, not value.

{
  "color-action-primary":     { "value": "{color.blue-600}" },
  "color-action-primary-hover": { "value": "{color.blue-500}" },
  "color-background-default": { "value": "{color.gray-50}" },
  "color-background-surface":  { "value": "#FFFFFF" },
  "color-text-primary":       { "value": "{color.gray-900}" },
  "color-text-secondary":     { "value": "{color.gray-600}" },
  "color-text-on-action":     { "value": "#FFFFFF" },
  "color-border-default":     { "value": "{color.gray-200}" },
  "color-feedback-error":     { "value": "{color.red-600}" },
  "color-feedback-success":   { "value": "{color.green-600}" },
  "color-feedback-warning":   { "value": "{color.yellow-500}" },
  "space-inline-sm":          { "value": "{space.2}" },
  "space-inline-md":          { "value": "{space.4}" },
  "space-stack-sm":           { "value": "{space.2}" },
  "space-stack-md":           { "value": "{space.4}" },
  "space-stack-lg":           { "value": "{space.8}" },
  "font-size-body":           { "value": "{font-size.md}" },
  "font-size-heading":        { "value": "{font-size.2xl}" }
}

Tier 3: Component Tokens

Component-specific tokens referencing semantic tokens. These are optional — use them when a component needs to deviate from semantic defaults or when theming complexity justifies the indirection.

{
  "button-bg-primary":        { "value": "{color-action-primary}" },
  "button-bg-primary-hover":  { "value": "{color-action-primary-hover}" },
  "button-text-primary":      { "value": "{color-text-on-action}" },
  "button-padding-x":         { "value": "{space-inline-md}" },
  "button-padding-y":         { "value": "{space-inline-sm}" },
  "button-border-radius":     { "value": "{border-radius.md}" },
  "card-bg":                  { "value": "{color-background-surface}" },
  "card-padding":             { "value": "{space-stack-md}" },
  "card-border":              { "value": "{color-border-default}" },
  "card-border-radius":       { "value": "{border-radius.lg}" }
}

---

Naming Convention

Structure

{category}-{property}-{element}-{variant}-{state}

Not every segment is required. Use only what's needed:

Naming Rules

1. Use kebab-case: color-text-primary, not colorTextPrimary (token names are platform-agnostic; case conversion happens at build time) 2. Describe purpose, not value: color-feedback-error, not color-red-600 3. Be predictable: Anyone should be able to guess a token name. If color-action-primary exists, color-action-secondary should too 4. Avoid abbreviations: background not bg, typography not typo — clarity over brevity in token names (code aliases can abbreviate) 5. Match scales consistently: If spacing uses t-shirt sizes (sm, md, lg), typography should too — don't mix t-shirt sizes with numbers

---

W3C Design Tokens Format

The W3C Design Tokens Community Group is standardizing token format. Key aspects:

File Structure

{
  "$name": "My Design System",
  "$description": "Design tokens for...",
  "color": {
    "primary": {
      "$type": "color",
      "$value": "#2563EB",
      "$description": "Primary brand color"
    }
  }
}

Supported Types

• color — CSS color values
• dimension — Sizes with units (px, rem, em)
• fontFamily — Font stack
• fontWeight — Numeric weight (100-900)
• duration — Time values (ms, s)
• cubicBezier — Easing curves [x1, y1, x2, y2]
• number — Unitless numbers (line-height, opacity)
• shadow — Box shadow definitions
• border — Border shorthand
• transition — Combined duration + delay + easing
• gradient — Color gradients
• typography — Composite type (family + size + weight + line-height + letter-spacing)

Aliases

{
  "action-primary": {
    "$type": "color",
    "$value": "{color.primary}"
  }
}

Curly braces {} denote references to other tokens — this is the standard alias syntax.

---

Theming with Tokens

Themes work by swapping token values at the semantic tier while keeping component code identical.

Light/Dark Example

// light.tokens.json
{
  "color-background-default": { "value": "#FFFFFF" },
  "color-text-primary":       { "value": "#111827" },
  "color-border-default":     { "value": "#E5E7EB" }
}

// dark.tokens.json
{
  "color-background-default": { "value": "#1F2937" },
  "color-text-primary":       { "value": "#F9FAFB" },
  "color-border-default":     { "value": "#374151" }
}

Components reference color-background-default. They never know which theme is active.

Theme Checklist

• [ ] Contrast ratios meet WCAG AA (4.5:1 for text, 3:1 for large text/UI) in every theme
• [ ] Semantic colors (error, success, warning) are distinguishable in every theme
• [ ] Shadows and elevation are visible in every theme (dark mode may need reduced or inverted shadows)
• [ ] Images and illustrations adapt or remain legible across themes
• [ ] Focus indicators are visible against every background color in every theme
• [ ] No information conveyed by color alone (WCAG 1.4.1)

---

Platform Delivery

Tokens are authored once and transformed for each platform:

Build Pipeline

tokens.json (source of truth)
    ↓ Style Dictionary / token transformer
    ├── css/variables.css
    ├── js/tokens.js
    ├── ios/Colors.swift
    ├── android/colors.xml
    └── figma/ (via Tokens Studio sync)

Critical rule: The token JSON file is the single source of truth. All platform outputs are generated artifacts. Never edit generated files directly.

---

Token Audit Checklist

When reviewing an existing token system:

• [ ] Every raw value in component code traces back to a token
• [ ] No orphaned tokens (defined but never used)
• [ ] No duplicate semantic tokens pointing to the same value (consolidate)
• [ ] Naming is consistent and predictable across all categories
• [ ] Every color token meets contrast requirements in all themes
• [ ] Spacing scale is consistent (base unit × multiplier, no arbitrary gaps)
• [ ] Typography scale follows a mathematical progression (1.25x, 1.333x, or 1.5x ratio)
• [ ] Token deprecation process exists for removing old tokens
• [ ] Token documentation includes purpose, not just value

Governance and Maintenance

A design system without governance decays within 6 months. This reference covers contribution models, lifecycle management, versioning, communication, and adoption strategies.

---

Contribution Models

Centralized

A dedicated design system team owns everything. Product teams consume the system and request changes through a formal process.

Structure:

• 3-8 person core team (designers + developers + documentation lead)
• Product teams submit requests via issue tracker
• Core team prioritizes, builds, and publishes

Strengths:

• Maximum consistency
• Deep expertise in system architecture
• Clear accountability

Weaknesses:

• Bottleneck: core team becomes a blocker when demand exceeds capacity
• Disconnected from product reality if team doesn't rotate in product work
• Slow to address product-specific needs

Best for: Large organizations (50+ designers/developers), strict brand requirements, regulated industries

Federated (Distributed)

Product teams contribute patterns back to the system. Ownership is shared.

Structure:

• Small core team (1-3 people) sets standards and reviews contributions
• Product teams build patterns and submit them for inclusion
• "Design system guild" or working group meets regularly

Strengths:

• Faster innovation — patterns come from real product needs
• Broader ownership and buy-in
• Scales with the organization

Weaknesses:

• Consistency requires active review and enforcement
• Contribution quality varies — need clear standards
• Coordination overhead increases with team count

Best for: Mid-size organizations, fast-moving products, distributed teams

Hybrid (Recommended Default)

Core team owns foundations (tokens, core components, documentation standards). Product teams own domain-specific patterns and contribute candidates back.

Structure:

• Core team: 2-5 people maintaining tokens, core components, tooling, documentation
• Product teams: build on foundations, propose new patterns when used in 3+ contexts
• Contribution guidelines define the handoff process

Strengths:

• Balances consistency with speed
• Core team isn't a bottleneck for product-specific patterns
• Natural path for patterns to graduate from product-level to system-level

Best for: Most organizations

---

Pattern Lifecycle

Stages

1. PROPOSED    → Someone identifies a need for a new pattern
2. UNDER REVIEW → Core team evaluates against acceptance criteria
3. ACCEPTED    → Pattern approved for building
4. BUILT       → Implementation complete in code and design tools
5. DOCUMENTED  → Full documentation published in pattern library
6. PUBLISHED   → Available for general use (Stable)
7. DEPRECATED  → Marked for removal with migration path
8. REMOVED     → Deleted from the system after deprecation period

Acceptance Criteria for New Patterns

A proposed pattern should meet all of these before being accepted:

• [ ] Used (or needed) in 3+ distinct contexts — if it's used in only one place, it's a product component, not a system pattern
• [ ] Purpose is clearly stated in one sentence
• [ ] Does not duplicate an existing pattern — explain why existing patterns don't work
• [ ] Accessibility requirements meet WCAG 2.2 AA minimum
• [ ] Responsive behavior defined for all breakpoints
• [ ] Content guidelines included
• [ ] Reviewed by at least 2 team members from different disciplines

Deprecation Process

Deprecation must be gradual and communicated. Never remove a pattern without warning.

Timeline: 1. Announce deprecation — Add "Deprecated" badge to pattern library entry. State the replacement pattern and migration path 2. Migration period — Minimum 2 sprints (for small systems) or 1 quarter (for large systems). Add console warnings or linter rules flagging usage 3. Usage audit — Before removal, verify zero active usage. If usage remains, extend the period or provide migration support 4. Remove — Delete pattern from library and codebase. Update changelog

Deprecation notice template:

⚠️ DEPRECATED as of [version]
Replacement: [New Pattern Name]
Migration guide: [link]
Removal planned: [date or version]
Reason: [brief explanation]

---

Versioning

Semantic Versioning for Design Systems

Apply semver to the design system as a product:

Versioning Rules

1. Never introduce breaking changes in a minor release 2. Group breaking changes into major releases — one painful migration is better than five small ones 3. Provide migration guides for every major release 4. Maintain the previous major version for at least one quarter after a new major release 5. Communicate breaking changes at least 2 sprints before the release

---

Communication

Channels

Changelog Format

## [2.3.0] - 2026-03-15

### Added
- Compact variant for Card component
- `color-feedback-info` semantic token
- Date Picker pattern (Beta)

### Changed
- Button focus ring increased from 1px to 2px for accessibility
- Modal backdrop opacity reduced from 60% to 50%

### Deprecated
- `Banner` pattern — use `Alert` instead. Removal in v3.0.0.

### Fixed
- Tooltip positioning overflow on small viewports
- Select dropdown z-index conflict with Modal

What to Communicate

• New patterns: What, why, when to use, link to docs
• Changes to existing patterns: What changed, why, impact on consumers
• Deprecations: What's deprecated, replacement, migration timeline
• Roadmap updates: What's coming, what's been reprioritized, why
• Adoption wins: "Team X reduced their build time by 30% using the new Form components"

---

Adoption Strategy

Measuring Adoption

Driving Adoption

Make it the path of least resistance:

• Using the system should be faster than building from scratch
• Provide starter templates, code generators, and Figma libraries
• Integrate with the team's existing toolchain (npm package, Figma plugin, IDE snippets)

Remove friction:

• Zero-config setup: npm install @company/design-system and go
• Comprehensive documentation with copy-paste code examples
• Responsive, accessible defaults — consumers shouldn't have to add accessibility themselves

Create advocates:

• Identify power users on product teams and empower them as "system champions"
• Run office hours where anyone can get help
• Pair with product teams during their sprints to show how the system accelerates work

Show value:

• Track and publish time savings: "Average feature delivery is 2 days faster using system components"
• Celebrate contributions publicly
• Report accessibility improvements: "WCAG violations down 60% since system adoption"

Anti-patterns in Adoption

---

Team Health Checks

Run these quarterly with the core team and key consumers:

For the core team

• [ ] Is the backlog manageable? (Under 30 open issues)
• [ ] Are we shipping on a regular cadence? (At least 1 release per month)
• [ ] Is documentation keeping up with implementation?
• [ ] Are deprecated patterns being migrated on schedule?
• [ ] Do we have visibility into how the system is being used?

For consumers

• [ ] Can you find what you need in the pattern library within 2 minutes?
• [ ] Does the system cover 80%+ of your UI needs?
• [ ] Do you know how to propose a new pattern?
• [ ] Do you receive timely updates about changes?
• [ ] Is the system making your work faster?

A "no" on any item is a priority item for the next quarter's roadmap.

Pattern Documentation

How to write comprehensive pattern library entries that serve designers, developers, content strategists, and product managers.

---

Anatomy of a Pattern Entry

Every pattern in the library should include these sections. Incomplete documentation leads to inconsistent implementation.

1. Header

Name:        [Context-agnostic name]
Purpose:     [One sentence: what user need does this serve?]
Status:      [Draft | Beta | Stable | Deprecated]
Version:     [Semantic version: 1.0.0]
Last updated: [Date]
Owner:       [Person or team responsible]

2. Description

2-3 sentences explaining:

• What the pattern is
• When to use it
• What makes it distinct from similar patterns

Example:

A Card is a contained unit of content that acts as an entry point to more detailed information. Use Cards when presenting a collection of related items that users browse and select from. Cards differ from List Items in that they emphasize visual content and support richer layouts.

3. Visual Example

Show the rendered component in its default state. Include:

• Live, interactive instance (not a static screenshot — screenshots go stale)
• Light and dark theme variants
• Responsive breakpoints (mobile, tablet, desktop)

4. Anatomy Diagram

Name every sub-part of the component. Use numbered callouts:

┌──────────────────────────┐
│ ┌──────────────────────┐ │
│ │    1. Image           │ │
│ └──────────────────────┘ │
│  2. Category tag          │
│  3. Title                 │
│  4. Description           │
│  5. Metadata (date, read  │
│     time, author)         │
│  ┌─────────┐             │
│  │ 6. CTA  │             │
│  └─────────┘             │
└──────────────────────────┘

Every sub-part should reference which atom or molecule it corresponds to in the system.

5. Variants

Document each legitimate variant:

Maximum 5 variants. If you need more, the pattern likely needs to be split into distinct patterns with different purposes.

6. States

Document every possible state:

7. Content Guidelines

8. Behavior

Interaction rules:

• Entire card is clickable (not just the CTA) — use <a> wrapping or role="link"
• If card contains multiple actions, only the primary action activates on card click
• Secondary actions (bookmark, share) are scoped — clicking them does NOT trigger card navigation
• Hover animation: 200ms ease-out elevation transition
• Keyboard: Tab to focus → Enter to activate → Tab to next card

Responsive behavior:

• Desktop (>1024px): 3-4 column grid, 24px gap
• Tablet (768-1024px): 2 column grid, 16px gap
• Mobile (<768px): Single column, full width, 12px gap
• Card aspect ratio remains fixed. Content reflows within

9. Accessibility Requirements

10. Design Tokens Used

List every token the component references:

Background:    color-background-surface
Border:        color-border-default
Title:         color-text-primary, font-size-heading-sm, font-weight-semibold
Description:   color-text-secondary, font-size-body
Padding:       space-stack-md (vertical), space-inline-md (horizontal)
Border radius: border-radius-lg
Shadow:        shadow-sm (default), shadow-md (hover)
Transition:    motion-duration-fast, motion-easing-standard

11. Code Examples

Provide implementation in the project's primary framework:

// React example
<Card
  image={{ src: "/photo.jpg", alt: "Description" }}
  category="Design"
  title="Card Title"
  description="Brief description of the content."
  href="/article/123"
  metadata={{ date: "Mar 15", readTime: "5 min" }}
/>

Include:

• Default usage
• Each variant
• With and without optional props
• Accessibility-specific props (aria-label, role overrides)

12. Related Patterns

---

Documentation Quality Checklist

Before publishing a pattern entry:

• [ ] Purpose is stated in one sentence
• [ ] Anatomy diagram with named sub-parts
• [ ] All states documented (minimum: default, hover, focus, disabled, loading, empty, error)
• [ ] Content guidelines with specific character limits
• [ ] Responsive behavior at all defined breakpoints
• [ ] Accessibility requirements with WCAG references
• [ ] Design tokens listed (no raw values in component code)
• [ ] Code example for primary framework
• [ ] At least 2 related patterns listed
• [ ] Reviewed by at least one designer AND one developer

---

Writing Style for Documentation

Principles

1. Show, then tell: Lead with the visual example, then explain in text 2. Be prescriptive: "Use X" not "Consider X." "Maximum 60 characters" not "Keep it short" 3. Include the negative: "When NOT to use" is as valuable as "When to use" 4. Write for scanning: Tables > paragraphs. Bullets > prose. Headers every 3-5 lines 5. Cross-disciplinary: Avoid jargon from only one discipline. If you must use technical terms, define them

Anti-patterns

• Screenshot-only documentation (goes stale in weeks)
• "See Figma" as a substitute for written specs (not everyone has Figma access)
• Documenting only the happy path (edge cases cause the most bugs)
• Writing documentation after launch (write it while building — it surfaces gaps)

Perceptual Patterns

The aesthetic and experiential properties that make a product feel like itself. Perceptual patterns express brand personality through color, typography, spacing, motion, and voice.

---

Color Systems

Building a Color Palette

A complete color system has four layers:

1. Brand colors (1-3) The signature colors that define the brand. Typically a primary and 1-2 secondary accent colors.

2. Neutral palette (7-11 shades) The workhorse palette for backgrounds, text, borders, and surfaces. Build from a base gray:

3. Semantic colors (4-6)

Each semantic color needs: base, light (backgrounds), dark (text), and border variants.

4. Extended palette (per-color ramps) 10-shade ramps (50-900) for each brand and semantic color. Generate mathematically — don't eyeball intermediate shades.

Color Usage Rules

• 60-30-10 rule: 60% neutral, 30% secondary, 10% accent — as a starting point, not a rigid law
• One accent color per screen area: Multiple competing accents create visual noise
• Never use color as the only way to convey meaning (WCAG 1.4.1): Always pair color with text, icons, or patterns
• Contrast requirements:
• Body text: 4.5:1 minimum (AA), 7:1 (AAA)
• Large text (>=18px or >=14px bold): 3:1 minimum (AA), 4.5:1 (AAA)
• UI components and graphical objects: 3:1 minimum (AA)
• Focus indicators: 3:1 against adjacent colors

---

Typography Scales

Mathematical Scales

Choose a ratio and base size. Every size in the system is derived from base × ratio^n:

Practical Type Scale (base 16px, 1.25 ratio)

Typography Rules

1. Maximum 2 font families: One for headings, one for body — or a single family with sufficient weight range 2. Minimum body size 16px on web, 14px on mobile: Below this, readability drops sharply 3. Line height decreases as size increases: 1.5 for body → 1.1 for display — large text needs less leading 4. Measure (line length): 45-75 characters for body text. 66 characters is optimal (Bringhurst) 5. Weight range: Use at minimum Regular (400), Medium (500), and Bold (700). Don't use more than 4 weights 6. Letter spacing: Slightly increase (+0.01-0.02em) for all-caps text. Slightly decrease (-0.01em) for display sizes (>36px)

---

Spacing Systems

Base Unit Approach

Choose a base unit and build all spacing from multipliers of it:

Common base units:

• 4px: Fine-grained control. Good for dense UIs (dashboards, data apps)
• 8px: Most common. Balances flexibility and simplicity
• Hybrid 4/8px: 4px for internal component spacing, 8px for layout spacing

Spacing Scale (8px base)

Spacing Application Rules

Two dimensions of spacing:

Gestalt principles in spacing:

• Proximity: Related elements have less space between them than unrelated elements. A form label should be closer to its input (4-8px) than to the previous form field (16-24px)
• Consistency: All cards in a grid use the same gap. All section dividers use the same margin
• Density intention: More space = premium, editorial feel. Less space = efficient, data-dense feel

---

Motion Principles

Purpose of Motion

Motion in UI serves four functions:

Duration Guidelines

Motion Rules

1. Faster = more responsive: Feedback animations under 200ms. Never exceed 400ms for direct interactions 2. Enter slower, exit faster: Open a modal in 250ms, close it in 150ms — arrival is celebrated, departure is swift 3. Match distance: Larger movements take longer. A dropdown appearing directly below a button (short distance) is faster than a side panel sliding in from off-screen (long distance) 4. Respect `prefers-reduced-motion`: Always provide a reduced-motion alternative. Minimum: remove movement, keep opacity fades. Ideal: instant state changes with no animation 5. Consistent easing: Use a maximum of 3 easing curves system-wide — standard (ease-out), enter (ease-out), exit (ease-in) 6. No gratuitous animation: If removing an animation doesn't reduce usability or brand expression, remove it

Motion Tokens

motion-duration-instant:  0ms
motion-duration-fast:     100ms
motion-duration-normal:   200ms
motion-duration-slow:     300ms
motion-duration-slower:   400ms
motion-easing-standard:   cubic-bezier(0.2, 0, 0, 1)
motion-easing-enter:      cubic-bezier(0, 0, 0.2, 1)
motion-easing-exit:       cubic-bezier(0.4, 0, 1, 1)

---

Voice and Tone

Voice (Constant)

Voice is the product's personality — it doesn't change. Define 3-4 voice attributes:

Template:

We are [attribute 1] but not [opposite extreme].

We are [attribute 2] but not [opposite extreme].

We are [attribute 3] but not [opposite extreme].

Example:

We are confident but not arrogant.

We are helpful but not patronizing.

We are clear but not dumbed-down.

We are friendly but not frivolous.

Tone (Varies by Context)

Tone adapts to the situation while voice stays the same:

Writing Rules for UI

1. Lead with the action: "Save changes" not "Do you want to save?" 2. Use sentence case: "Create new project" not "Create New Project" (title case is for marketing, not UI) 3. Be specific: "Delete 3 items" not "Delete items" — specificity builds trust 4. No jargon: "Something went wrong" not "Error 500: Internal server exception" 5. No blame: "We couldn't find that page" not "You entered an invalid URL" 6. Active voice: "We saved your draft" not "Your draft has been saved"

---

Signature Moments

Signature moments are the distinctive, memorable interactions that express brand personality at key emotional points.

Where to Place Them

• First impression: Onboarding, welcome screen, first successful action
• Achievement: Completing a workflow, reaching a milestone, shipping something
• Recovery: Coming back after an error, resuming after time away
• Delight: Unexpected pleasant touches during routine tasks

Rules for Signature Moments

1. Earn the moment: Only at genuine emotional peaks — not on every button click 2. Brief: 300-600ms. Never block the user's flow 3. Skippable: Power users should be able to bypass them without friction 4. Accessible: Work without motion (static illustration + text), without sound (visual feedback), and without color 5. Consistent: The same moment should trigger the same expression every time — surprise is good, inconsistency isn't

Examples from Real Products

• Slack's loading messages (warm, human)
• Mailchimp's high-five after sending a campaign (celebration)
• Linear's smooth, precise transitions (craftsmanship)
• Stripe's documentation animations (clarity through motion)

Component Specification: [Component Name]

Header

---

Description

[2-3 sentences: What is this component? When should it be used? What makes it distinct from similar patterns?]

---

Anatomy

[Numbered diagram or description of sub-parts]

┌─────────────────────────┐
│  1. [Sub-part name]     │
│  2. [Sub-part name]     │
│  3. [Sub-part name]     │
│  4. [Sub-part name]     │
└─────────────────────────┘

---

Variants

Maximum 5 variants. If more are needed, consider splitting into separate patterns.

---

States

---

Content Guidelines

---

Behavior

Interaction Rules

• [What happens on click/tap]
• [What happens on keyboard interaction (Enter, Space, Escape, Arrow keys)]
• [Animation details: duration, easing, what moves]

Responsive Behavior

---

Accessibility

---

Design Tokens

[Category]:    [token-name]
[Category]:    [token-name]
[Category]:    [token-name]
[Category]:    [token-name]

No raw hex codes, pixel values, or magic numbers. Every value must reference a token.

---

Code Example

// Default usage
<[ComponentName]
  [prop]="[value]"
  [prop]="[value]"
/>

// With optional props
<[ComponentName]
  [prop]="[value]"
  [optionalProp]="[value]"
  [optionalProp]="[value]"
/>

---

Related Patterns

---

Changelog

Design System Audit: [Product Name]

Date: [Date] Auditor(s): [Names and roles] Scope: [Which product/pages/screens are included]

---

1. Current State Assessment

System Maturity Level

Team Context

---

2. Interface Inventory

Color Audit

Contrast violations found: [Count and details]

Typography Audit

Does a mathematical scale exist? [Yes/No — ratio if yes]

Spacing Audit

Base unit identified? [Yes/No — value if yes]

Component Inventory

For each component category, count unique implementations:

---

3. Consistency Score

Rate each area on a 1-5 scale:

Scale:

• 1: Chaotic — no discernible pattern
• 2: Emerging — some patterns, many exceptions
• 3: Partial — patterns exist but aren't universally applied
• 4: Consistent — clear system with minor deviations
• 5: Systematic — fully governed, deviations are intentional and documented

---

4. Accessibility Snapshot

---

5. Findings Summary

Top Inconsistencies (Ranked by Impact)

Quick Wins (High Impact, Low Effort)

1. [Action item] 2. [Action item] 3. [Action item]

Foundational Investments (High Impact, High Effort)

1. [Action item] 2. [Action item] 3. [Action item]

---

6. Recommended Roadmap

Phase 1: Foundation (Weeks 1-4)

• [ ] Define design tokens (colors, typography, spacing)
• [ ] Document top 10 most-used components
• [ ] Establish naming conventions
• [ ] Set up pattern library tooling

Phase 2: Core System (Weeks 5-12)

• [ ] Build and publish core component library
• [ ] Migrate first product area to use system components
• [ ] Establish governance and contribution process
• [ ] Create onboarding guide for consumers

Phase 3: Scale (Weeks 13+)

• [ ] Expand component coverage to 80%+
• [ ] Add theming support (dark mode, brand variants)
• [ ] Measure and publish adoption metrics
• [ ] Establish quarterly audit cadence

---

7. Appendix

Screenshots

[Include grouped screenshots from the interface inventory — organize by component category]

Participants

Token Architecture: [System Name]

Version: [1.0.0] Last updated: [Date] Owner: [Person or team]

---

Token Tiers

This system uses a three-tier token architecture:

---

Naming Convention

{category}-{property}-{element}-{variant}-{state}

---

Color Tokens

Global Colors

Semantic Color Tokens

---

Typography Tokens

Scale

Base size: [16px] Scale ratio: [1.25 — Major Third]

Font Families

Font Weights

Semantic Typography Tokens

---

Spacing Tokens

Base unit: [8px]

---

Border Tokens

---

Shadow Tokens

---

Motion Tokens

---

Theme Overrides

Light Theme (Default)

[All semantic tokens above define the light theme]

Dark Theme

---

Delivery