Design System Creator

Design System Creator

Design systems architect and CSS expert specializing in creating comprehensive, scalable design bibles.

When to Use This Skill

✅ Use for:

• Creating design tokens from scratch (colors, spacing, typography scales)
• Building CSS custom property architectures
• Documenting component libraries with usage guidelines
• Creating design bibles and style guides
• Establishing naming conventions (BEM, OOCSS, SMACSS)
• Auditing existing CSS for design system extraction
• Theming and dark mode token systems
• Multi-brand/white-label token structures

❌ Do NOT use for:

• Typography selection and pairing → typography-expert
• Color theory and palette generation → color-theory-palette-harmony-expert
• Brand identity and visual direction → web-design-expert
• Actual component implementation → web-design-expert or native-app-designer
• Icon design → web-design-expert
• Motion design principles → native-app-designer

Three-Tier Token Architecture

The foundation of scalable design systems:

:root {
  /* 1. PRIMITIVE - Raw values (ALWAYS use OKLCH for colors) */
  --color-blue-500: oklch(62.8% 0.195 252.5);
  --space-4: 1rem;

  /* 2. SEMANTIC - Purpose-driven */
  --color-primary: var(--color-blue-500);
  --space-component-padding: var(--space-4);

  /* 3. COMPONENT - Specific usage */
  --button-bg: var(--color-primary);
  --button-padding: var(--space-component-padding);
}

→ See references/token-architecture.md for dark mode, multi-brand, and complete examples.

OKLCH: The Modern Color Standard

⚠️ CRITICAL: Always use OKLCH for color tokens, not hex or HSL.

OKLCH is perceptually uniform - equal L values mean equal perceived lightness. This is essential for:

• Generating harmonious color scales
• Ensuring accessibility (L=50% is true middle gray)
• Theming (adjust L for dark mode, C for brand intensity)

:root {
  /* OKLCH format: oklch(Lightness% Chroma Hue) */

  /* Primary scale - same hue, varying lightness */
  --color-primary-100: oklch(95% 0.05 252);
  --color-primary-500: oklch(62% 0.19 252);
  --color-primary-900: oklch(30% 0.15 252);

  /* Dark mode: reduce L uniformly */
  --color-bg-light: oklch(98% 0.01 252);
  --color-bg-dark: oklch(15% 0.02 252);
}

Essential OKLCH Resources:

OKLCH Benefits for Design Systems:

• Perceptual uniformity: L=70% always looks 70% light
• Better contrast: APCA-ready lightness calculations
• Easier scaling: Math operations work predictably
• Native CSS: oklch() works in all modern browsers (2023+)

Design Bible Structure

1. Foundation

• Brand Identity, Design Principles
• Color System, Typography Scale
• Spacing Scale, Grid System

2. Components

For each component document:

• Purpose, Anatomy, Variants
• States (default, hover, active, disabled, focus)
• Responsive behavior
• Accessibility (ARIA, keyboard, screen readers)
• Code examples

3. Patterns

• Page Layouts, Navigation
• Forms, Data Display
• Feedback (alerts, toasts, modals)

4. Guidelines

• Writing (voice, tone)
• Imagery, Motion, Accessibility

→ See references/component-documentation.md for templates.

CSS Organization (ITCSS)

styles/
├── 0-settings/     # Tokens, custom properties
├── 1-tools/        # Mixins, functions
├── 2-generic/      # Reset, normalize
├── 3-elements/     # Typography, forms (unclassed)
├── 4-objects/      # Layout patterns
├── 5-components/   # UI components
├── 6-utilities/    # Helpers, overrides
└── main.css        # Import all

→ See references/css-organization.md for BEM naming and full structure.

Anti-Patterns to Avoid

1. Token Explosion

What it looks like: 500+ tokens with overlapping purposes Why it's wrong: Defeats constraints; developers can't choose Fix: Limit to 6-8 spacing tokens. If you need more, fix the scale.

2. Missing Semantic Layer

What it looks like: Components reference primitives directly Why it's wrong: Can't theme, can't change brand without touching every component Fix: Three-tier tokens: Primitive → Semantic → Component

3. Documentation Drift

What it looks like: Design bible says one thing, CSS does another Why it's wrong: Developers stop trusting documentation Fix: Generate docs from CSS comments, or use Storybook

4. Utility Class Overload

What it looks like: class="p-4 m-2 bg-blue-500 text-white..." Why it's wrong: HTML unreadable, design intent lost Fix: Use utilities sparingly; most styles in semantic component classes

5. Breaking the Scale

What it looks like: padding: 13px; (why 13?) Why it's wrong: Every exception erodes the system Fix: If the scale doesn't work, fix the scale

6. No Version Control

What it looks like: "Which button is correct?" Why it's wrong: Multiple sources of truth Fix: Single source of truth with version numbers, deprecation warnings

Working Process

1. Audit: Review existing patterns and inconsistencies 2. Define: Establish tokens and foundational system 3. Build: Create component library with documentation 4. Document: Write comprehensive design bible 5. Test: Validate accessibility and responsiveness 6. Deliver: Package with examples and starter templates

MCP Integrations

Output Deliverables

• Design Bible Document: Complete markdown/HTML with visual examples
• CSS Codebase: Well-commented, modular, production-ready
• Component Library: Interactive examples with all variants
• Quick Start Guide: Getting started, customization, common recipes

References

→ references/token-architecture.md - Three-tier tokens, dark mode, multi-brand → references/css-organization.md - ITCSS, BEM, component file structure → references/component-documentation.md - Doc templates, quick reference cards

Integrates With

• typography-expert - Typography scale and font selection
• color-theory-palette-harmony-expert - Color palette generation
• web-design-expert - Brand identity and visual direction
• adhd-design-expert - ADHD-friendly design tokens

---

Remember: A design system is a living product that serves products.

Changelog

All notable changes to the design-system-creator skill will be documented in this file.

[2.0.0] - 2024-12-14

Changed

• BREAKING: Restructured skill following progressive disclosure pattern
• Reduced SKILL.md from 359 lines to ~175 lines for faster loading
• Extracted detailed content to reference files

Added

• references/token-architecture.md - Three-tier token system, dark mode, multi-brand
• references/css-organization.md - ITCSS, BEM, component file structure
• references/component-documentation.md - Component doc templates, quick reference cards

Improved

• Clearer activation triggers and boundary definitions
• Expanded anti-patterns section (5 → 6 items)
• Better MCP integration documentation
• Streamlined working process description

[1.1.0] - 2025-11-26

Added

• Complete "When to Use This Skill" section with ✅/❌ checklists
• "When NOT to Use" with redirects to appropriate skills
• NOT clause in description for precise activation
• Activation keywords in description
• 5 common anti-patterns with detailed explanations:
• Token Explosion
• Missing Semantic Layer
• Documentation Drift
• Utility Class Overload
• Breaking the Scale
• MCP Integrations section with:
• Storybook MCP options (mcpland, freema, stefanoamorelli)
• Figma MCP for design token sync
• 21st.dev MCP guidance
• Integration with Other Skills section

Changed

• Converted frontmatter from custom YAML format to standard allowed-tools format
• Expanded from 270 lines to 359 lines
• Improved description with clear activation triggers and exclusions

Removed

• Custom frontmatter fields (triggers, integrates_with, outputs, official_mcps) - moved to documentation sections

[1.0.0] - 2024-12-01

Added

• Initial skill creation
• Design system architecture guidance
• CSS mastery section
• Design token systems
• Design Bible structure template
• CSS organization patterns
• Working process workflow
• Output deliverables list
• Best practices sections
• Example button component documentation

Component Documentation Template

Standard format for documenting design system components.

---

Component Documentation Structure

# Button

## Purpose
Primary interactive element for user actions. Use for submitting forms,
triggering actions, and navigating when styled as a link.

## Anatomy

┌─────────────────────────────────────┐
│  [icon]  Label Text  [icon]         │
└─────────────────────────────────────┘
    ↑          ↑           ↑
 Leading    Label      Trailing
  Icon    (required)     Icon

**Parts:**
1. Container (background, border, padding)
2. Label (required, text content)
3. Leading icon (optional)
4. Trailing icon (optional)

## Variants

| Variant   | Use Case                        | Visual                |
|-----------|--------------------------------|----------------------|
| Primary   | Main CTA, form submit          | Solid brand color    |
| Secondary | Supporting actions             | Outlined             |
| Tertiary  | Low-emphasis actions           | Text only            |
| Danger    | Destructive actions            | Red tones            |
| Ghost     | Minimal UI, icon buttons       | Transparent          |

## Sizes

| Size | Height | Padding      | Font Size | Use Case           |
|------|--------|--------------|-----------|-------------------|
| sm   | 32px   | 8px 12px     | 14px      | Dense UIs, tables |
| md   | 40px   | 10px 16px    | 16px      | Default           |
| lg   | 48px   | 12px 24px    | 18px      | Hero CTAs         |

## States

### Interactive States
- **Default**: Resting state
- **Hover**: Mouse over (desktop)
- **Active**: Being pressed
- **Focus**: Keyboard navigation (visible focus ring)

### Semantic States
- **Disabled**: Cannot be interacted with
- **Loading**: Action in progress (show spinner)

## Responsive Behavior

- **Mobile**: Full-width in forms, fixed bottom for primary CTAs
- **Tablet+**: Inline, min-width based on content
- **Touch targets**: Minimum 44×44px

## Accessibility

### Requirements
- Minimum 4.5:1 contrast for text
- 3:1 contrast for non-text (borders, backgrounds)
- Focus indicator visible (2px outline, 2px offset)
- Disabled state announced to screen readers

### ARIA
- Use `<button>` element (not `<div>`)
- `aria-disabled="true"` for disabled (keep focusable)
- `aria-busy="true"` when loading
- `aria-label` for icon-only buttons

### Keyboard
- `Enter` or `Space` to activate
- Tab to focus

## Code Examples

### HTML

<!-- Primary button --&gt; <button class="btn btn--primary"> Submit Form </button>

<!-- With icon --&gt; <button class="btn btn--primary"> <svg class="btn__icon" aria-hidden="true">...</svg> Download </button>

<!-- Icon only --&gt; <button class="btn btn--ghost btn--icon" aria-label="Close"> <svg aria-hidden="true">...</svg> </button>

<!-- Loading --&gt; <button class="btn btn--primary" aria-busy="true" disabled> <svg class="btn__spinner" aria-hidden="true">...</svg> Saving... </button>

<!-- Disabled --&gt; <button class="btn btn--primary" aria-disabled="true"> Unavailable </button>

### React

interface ButtonProps { variant?: 'primary' | 'secondary' | 'tertiary' | 'danger' | 'ghost'; size?: 'sm' | 'md' | 'lg'; isLoading?: boolean; isDisabled?: boolean; leftIcon?: React.ReactNode; rightIcon?: React.ReactNode; children: React.ReactNode; }

## Do's and Don'ts

### ✅ Do
- Use verb-led labels ("Submit", "Save", "Delete")
- Keep labels short (1-3 words)
- Use one primary button per view
- Provide feedback for async actions

### ❌ Don't
- Don't use for navigation (use links)
- Don't disable without explanation
- Don't stack more than 2 buttons horizontally
- Don't use all caps (harder to read)

## Related Components
- **Link**: For navigation
- **IconButton**: Icon-only variant
- **ButtonGroup**: Multiple related actions
- **SplitButton**: Primary + dropdown

## Changelog
- v2.0: Added loading state, updated focus styles
- v1.1: Added ghost variant
- v1.0: Initial release

---

Quick Reference Card Format

For at-a-glance reference:

┌─────────────────────────────────────────────────────────────┐
│ BUTTON                                              v2.0    │
├─────────────────────────────────────────────────────────────┤
│ VARIANTS: primary | secondary | tertiary | danger | ghost   │
│ SIZES: sm (32px) | md (40px) | lg (48px)                    │
│ STATES: default | hover | active | focus | disabled         │
├─────────────────────────────────────────────────────────────┤
│ TOKENS                                                      │
│ --button-bg, --button-text, --button-border                 │
│ --button-padding-x, --button-padding-y                      │
│ --button-radius, --button-font-size                         │
├─────────────────────────────────────────────────────────────┤
│ A11Y: 4.5:1 contrast | 44px touch | focus ring | `<button>` │
├─────────────────────────────────────────────────────────────┤
│ ✅ Verb labels | Short | One primary per view               │
│ ❌ Navigation | All caps | Stacking 3+                      │
└─────────────────────────────────────────────────────────────┘

---

Visual Documentation

Include visual examples for each state:

┌─────────────────────────────────────────────────────────────┐
│                     BUTTON STATES                           │
├──────────────┬──────────────┬──────────────┬───────────────┤
│   Default    │    Hover     │    Active    │    Focus      │
│  ┌────────┐  │  ┌────────┐  │  ┌────────┐  │  ╔════════╗   │
│  │ Button │  │  │ Button │  │  │ Button │  │  ║ Button ║   │
│  └────────┘  │  └────────┘  │  └────────┘  │  ╚════════╝   │
│   #3b82f6    │   #2563eb    │   #1d4ed8    │  +focus ring  │
├──────────────┴──────────────┴──────────────┴───────────────┤
│                       DISABLED                              │
│               ┌─ ─ ─ ─ ─ ─ ─┐                              │
│               │   Button    │  opacity: 0.5                │
│               └─ ─ ─ ─ ─ ─ ─┘  cursor: not-allowed         │
└─────────────────────────────────────────────────────────────┘

---

Storybook-Style Categories

Organize documentation by:

1. Overview - Purpose, when to use 2. Playground - Interactive demo with controls 3. Variants - All visual variations 4. Sizes - All size options 5. States - All interactive/semantic states 6. Composition - With icons, in groups 7. Accessibility - Testing checklist 8. Code - Implementation examples

CSS Organization Patterns

Proven patterns for organizing design system stylesheets.

---

ITCSS (Inverted Triangle CSS)

Most widely adopted pattern. Organizes by specificity:

styles/
├── 0-settings/           # Variables, tokens (no CSS output)
│   ├── tokens.css
│   ├── breakpoints.css
│   └── custom-properties.css
│
├── 1-tools/              # Mixins, functions (no CSS output)
│   ├── mixins.css
│   └── functions.css
│
├── 2-generic/            # Reset, normalize (low specificity)
│   ├── reset.css
│   ├── normalize.css
│   └── box-sizing.css
│
├── 3-elements/           # Bare HTML elements (type selectors)
│   ├── typography.css
│   ├── forms.css
│   ├── tables.css
│   └── links.css
│
├── 4-objects/            # Layout patterns (class selectors)
│   ├── container.css
│   ├── grid.css
│   ├── stack.css
│   └── cluster.css
│
├── 5-components/         # UI components (class selectors)
│   ├── button.css
│   ├── card.css
│   ├── modal.css
│   ├── nav.css
│   └── form-controls.css
│
├── 6-utilities/          # Helper classes (high specificity)
│   ├── display.css
│   ├── spacing.css
│   └── visibility.css
│
└── main.css              # Import order matters!

main.css Import Order

/* Settings & Tools */
@import '0-settings/tokens.css';
@import '0-settings/custom-properties.css';

/* Generic */
@import '2-generic/reset.css';
@import '2-generic/box-sizing.css';

/* Elements */
@import '3-elements/typography.css';
@import '3-elements/forms.css';

/* Objects */
@import '4-objects/container.css';
@import '4-objects/grid.css';

/* Components */
@import '5-components/button.css';
@import '5-components/card.css';

/* Utilities (last - highest specificity) */
@import '6-utilities/spacing.css';
@import '6-utilities/display.css';

---

BEM Naming Convention

Block__Element--Modifier

/* Block: standalone component */
.card { }

/* Element: part of a block */
.card__header { }
.card__body { }
.card__footer { }
.card__title { }
.card__image { }

/* Modifier: variant or state */
.card--featured { }
.card--compact { }
.card__title--large { }

BEM in HTML

<article class="card card--featured">
  <header class="card__header">
    <h2 class="card__title card__title--large">Title</h2>
  </header>
  <div class="card__body">Content</div>
  <footer class="card__footer">
    <button class="btn btn--primary">Action</button>
  </footer>
</article>

---

Component File Structure

Each component gets its own file with consistent structure:

/* ==========================================================================
   Button Component
   ========================================================================== */

/**
 * 1. Base button styles
 * 2. Variants (primary, secondary, ghost)
 * 3. Sizes (sm, md, lg)
 * 4. States (hover, active, disabled, focus)
 * 5. Icon buttons
 */

/* -----------------------------------------------------------------------------
   1. Base
   -------------------------------------------------------------------------- */

.btn {
  /* Layout */
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: var(--button-icon-gap, 0.5rem);

  /* Sizing */
  padding: var(--button-padding-y) var(--button-padding-x);
  min-height: var(--button-min-height);

  /* Typography */
  font-family: var(--button-font-family);
  font-size: var(--button-font-size);
  font-weight: var(--button-font-weight);
  line-height: 1;

  /* Visual */
  border: var(--button-border-width) solid transparent;
  border-radius: var(--button-radius);

  /* Interaction */
  cursor: pointer;
  transition: var(--button-transition);
}

/* -----------------------------------------------------------------------------
   2. Variants
   -------------------------------------------------------------------------- */

.btn--primary {
  background: var(--button-primary-bg);
  color: var(--button-primary-text);
  border-color: var(--button-primary-border);
}

.btn--secondary {
  background: var(--button-secondary-bg);
  color: var(--button-secondary-text);
  border-color: var(--button-secondary-border);
}

.btn--ghost {
  background: transparent;
  color: var(--button-ghost-text);
}

/* -----------------------------------------------------------------------------
   3. Sizes
   -------------------------------------------------------------------------- */

.btn--sm {
  --button-padding-x: var(--space-3);
  --button-padding-y: var(--space-1);
  --button-font-size: var(--font-size-sm);
}

.btn--lg {
  --button-padding-x: var(--space-6);
  --button-padding-y: var(--space-3);
  --button-font-size: var(--font-size-lg);
}

/* -----------------------------------------------------------------------------
   4. States
   -------------------------------------------------------------------------- */

.btn:hover:not(:disabled) {
  background: var(--button-primary-bg-hover);
}

.btn:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

.btn:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

---

Layout Objects

Reusable layout primitives (from Every Layout):

/* Stack: vertical rhythm */
.stack {
  display: flex;
  flex-direction: column;
}

.stack > * + * {
  margin-block-start: var(--stack-space, 1rem);
}

/* Cluster: horizontal grouping */
.cluster {
  display: flex;
  flex-wrap: wrap;
  gap: var(--cluster-space, 1rem);
}

/* Sidebar: content + sidebar */
.with-sidebar {
  display: flex;
  flex-wrap: wrap;
  gap: var(--sidebar-gap, 1rem);
}

.with-sidebar > :first-child {
  flex-basis: var(--sidebar-width, 20rem);
  flex-grow: 1;
}

.with-sidebar > :last-child {
  flex-basis: 0;
  flex-grow: 999;
  min-inline-size: 50%;
}

/* Center: constrained width + centered */
.center {
  box-sizing: content-box;
  max-inline-size: var(--center-width, 60ch);
  margin-inline: auto;
  padding-inline: var(--center-padding, 1rem);
}

/* Grid: auto-fill responsive grid */
.grid {
  display: grid;
  grid-template-columns: repeat(
    auto-fill,
    minmax(min(var(--grid-min, 250px), 100%), 1fr)
  );
  gap: var(--grid-gap, 1rem);
}

---

Utility Classes (Sparingly)

/* Display */
.d-none { display: none; }
.d-block { display: block; }
.d-flex { display: flex; }
.d-grid { display: grid; }

/* Spacing (use tokens) */
.mt-0 { margin-top: 0; }
.mt-4 { margin-top: var(--space-4); }
.mb-4 { margin-bottom: var(--space-4); }
.p-4 { padding: var(--space-4); }

/* Text */
.text-center { text-align: center; }
.text-muted { color: var(--color-text-muted); }
.font-bold { font-weight: 700; }

/* Visibility */
.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

---

Performance Considerations

/* Containment for complex components */
.card {
  contain: layout style;
}

/* Will-change for animations (use sparingly) */
.modal {
  will-change: transform, opacity;
}

/* Content-visibility for long lists */
.list-item {
  content-visibility: auto;
  contain-intrinsic-size: 0 100px;
}

/* Prefer transform over layout properties */
.slide-in {
  transform: translateX(0);
  transition: transform 300ms ease;
}

/* Layer hints for paint optimization */
.sticky-header {
  position: sticky;
  top: 0;
  z-index: 100;
  will-change: transform;  /* Creates new layer */
}

Design Token Architecture

Complete guide to building scalable, maintainable token systems.

---

Three-Tier Token System

The gold standard for scalable design tokens:

/* TIER 1: Primitive Tokens (raw values) */
:root {
  /* Colors */
  --color-blue-50: #eff6ff;
  --color-blue-100: #dbeafe;
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;
  --color-blue-900: #1e3a8a;

  /* Spacing (4px base unit) */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --space-8: 2rem;
  --space-12: 3rem;
  --space-16: 4rem;

  /* Typography */
  --font-size-xs: 0.75rem;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
  --font-size-2xl: 1.5rem;
  --font-size-3xl: 1.875rem;

  /* Radii */
  --radius-sm: 0.125rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-xl: 0.75rem;
  --radius-full: 9999px;
}

/* TIER 2: Semantic Tokens (intent) */
:root {
  /* Colors */
  --color-primary: var(--color-blue-500);
  --color-primary-hover: var(--color-blue-600);
  --color-background: var(--color-white);
  --color-surface: var(--color-gray-50);
  --color-text: var(--color-gray-900);
  --color-text-muted: var(--color-gray-600);
  --color-border: var(--color-gray-200);

  /* Spacing */
  --space-component-padding: var(--space-4);
  --space-component-gap: var(--space-3);
  --space-section-gap: var(--space-8);
  --space-page-margin: var(--space-6);

  /* Typography */
  --font-size-body: var(--font-size-base);
  --font-size-heading: var(--font-size-2xl);
  --font-size-caption: var(--font-size-sm);
}

/* TIER 3: Component Tokens (specific) */
:root {
  /* Button */
  --button-bg: var(--color-primary);
  --button-bg-hover: var(--color-primary-hover);
  --button-text: var(--color-white);
  --button-padding-x: var(--space-4);
  --button-padding-y: var(--space-2);
  --button-radius: var(--radius-md);

  /* Card */
  --card-bg: var(--color-surface);
  --card-border: var(--color-border);
  --card-padding: var(--space-component-padding);
  --card-radius: var(--radius-lg);

  /* Input */
  --input-border: var(--color-border);
  --input-border-focus: var(--color-primary);
  --input-padding: var(--space-3);
  --input-radius: var(--radius-md);
}

---

Dark Mode with Semantic Tokens

/* Light theme (default) */
:root {
  --color-background: #ffffff;
  --color-surface: #f8fafc;
  --color-text: #0f172a;
  --color-text-muted: #64748b;
  --color-border: #e2e8f0;
  --color-primary: #3b82f6;
}

/* Dark theme */
[data-theme="dark"] {
  --color-background: #0f172a;
  --color-surface: #1e293b;
  --color-text: #f8fafc;
  --color-text-muted: #94a3b8;
  --color-border: #334155;
  --color-primary: #60a5fa;  /* Lighter for dark bg */
}

/* Components just work */
.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  color: var(--color-text);
}

---

Spacing Scale Philosophy

4px base unit is the industry standard:

8-point grid: Only use multiples of 8px for major layout. 4px increments for fine-tuning.

---

Typography Scale

Use modular scale (1.25 ratio is common):

:root {
  --type-scale-ratio: 1.25;  /* Major third */

  --font-size-xs: 0.64rem;    /* 10.24px */
  --font-size-sm: 0.8rem;     /* 12.8px */
  --font-size-base: 1rem;     /* 16px */
  --font-size-lg: 1.25rem;    /* 20px */
  --font-size-xl: 1.563rem;   /* 25px */
  --font-size-2xl: 1.953rem;  /* 31.25px */
  --font-size-3xl: 2.441rem;  /* 39px */
  --font-size-4xl: 3.052rem;  /* 48.8px */
}

---

Multi-Brand / White-Label

/* Base tokens (shared) */
:root {
  --space-4: 1rem;
  --radius-md: 0.375rem;
  --font-family-sans: system-ui, sans-serif;
}

/* Brand A tokens */
[data-brand="brand-a"] {
  --color-primary: #ff6b35;
  --color-secondary: #004e89;
  --font-family-brand: 'Montserrat', sans-serif;
}

/* Brand B tokens */
[data-brand="brand-b"] {
  --color-primary: #7c3aed;
  --color-secondary: #10b981;
  --font-family-brand: 'Inter', sans-serif;
}

/* Usage - same component works for both brands */
.button-primary {
  background: var(--color-primary);
  font-family: var(--font-family-brand);
  padding: var(--space-4);
  border-radius: var(--radius-md);
}

---

Token Naming Conventions

Good Names (Semantic)

--color-primary
--color-text-muted
--space-component-padding
--button-bg-hover
--input-border-focus

Bad Names (Presentational)

--blue-button           /* What if brand changes? */
--margin-20             /* Magic number */
--large-text            /* Relative to what? */
--red-error             /* Color in name */

Naming Pattern

--{category}-{property}-{variant}

Examples:
--color-primary-hover
--space-component-gap
--font-size-heading
--button-bg-disabled

---

Token Documentation Format

## --color-primary

**Value**: `#3b82f6`
**Category**: Color / Brand
**Dark theme**: `#60a5fa`

**Description**: Primary brand color used for CTAs and interactive elements.

**Usage**:
- Primary buttons
- Links
- Active states
- Focus rings

**Do**:
- Use for main call-to-action
- Ensure 4.5:1 contrast with text

**Don't**:
- Use for large background areas
- Use for decorative elements
- Combine with other saturated colors

**Related tokens**:
- `--color-primary-hover`
- `--color-primary-active`
- `--button-bg`