Design system alignment

Token pipeline (design → build → runtime)

  [ Figma / library: semantic + primitive ]
        │
        ▼
  ┌─────────────┐     Style Dictionary / Tokens Studio / theme JSON
  │ Token build │── naming: color.text.default, space.3 (team dictionary)
  └─────────────┘
        │
        ▼
  ┌─────────────┐     CSS variables, Tailwind extend, component theme
  │ Runtime use │── no scattered hex; dark mode flips the same semantic keys
  └─────────────┘
        │
        ▼
  ┌─────────────┐     Story / docs site / PR screenshots vs design
  │ QA & docs   │── variant matrix + traceable node ID / link
  └─────────────┘

Design Token CSS Variable Definitions

/* Design Token: full CSS variable definitions (color / spacing / font / shadow) */
:root {
  /* Color - primitive tokens (do not consume directly) */
  --color-blue-50:  #eff6ff;
  --color-blue-500: #3b82f6;
  --color-blue-700: #1d4ed8;
  --color-gray-50:  #f9fafb;
  --color-gray-900: #111827;

  /* Color - semantic tokens (components consume this layer) */
  --color-bg-primary:      var(--color-gray-50);
  --color-bg-elevated:     #ffffff;
  --color-text-primary:    var(--color-gray-900);
  --color-text-muted:      #6b7280;
  --color-brand:           var(--color-blue-500);
  --color-brand-hover:     var(--color-blue-700);
  --color-border:          #e5e7eb;
  --color-focus-ring:      rgba(59, 130, 246, 0.35);

  /* Spacing - 4px grid system */
  --space-1: 0.25rem;   /* 4px  */
  --space-2: 0.5rem;    /* 8px  */
  --space-3: 0.75rem;   /* 12px */
  --space-4: 1rem;      /* 16px */
  --space-6: 1.5rem;    /* 24px */
  --space-8: 2rem;      /* 32px */

  /* Typography */
  --font-family-sans: 'Inter', system-ui, sans-serif;
  --font-family-mono: 'JetBrains Mono', ui-monospace, monospace;
  --font-size-sm:   0.875rem;  /* 14px */
  --font-size-base: 1rem;      /* 16px */
  --font-size-lg:   1.125rem;  /* 18px */
  --font-weight-medium: 500;
  --font-weight-bold:   700;
  --line-height-tight:  1.25;
  --line-height-normal: 1.5;

  /* Shadows */
  --shadow-sm: 0 1px 2px 0 rgba(0,0,0,0.05);
  --shadow-md: 0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -1px rgba(0,0,0,0.06);

  /* Radii */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;
}

/* Dark theme: override only semantic tokens; primitives remain unchanged */
[data-theme="dark"] {
  --color-bg-primary:   #111827;
  --color-bg-elevated:  #1f2937;
  --color-text-primary: #f9fafb;
  --color-text-muted:   #9ca3af;
  --color-border:       #374151;
}

The swatches below show how this page consumes global CSS variables (follows site light/dark theme).

Variant System Implementation

/* Button variant system: primary / secondary / ghost — maps to Figma component property */
.btn {
  display: inline-flex;
  align-items: center;
  gap: var(--space-2);
  padding: var(--space-2) var(--space-4);
  font-size: var(--font-size-sm);
  font-weight: var(--font-weight-medium);
  border-radius: var(--radius-md);
  border: 1.5px solid transparent;
  cursor: pointer;
  transition: background 0.15s, color 0.15s, border-color 0.15s;

  /* Focus ring: consistent across all variants */
  &:focus-visible {
    outline: 2px solid var(--color-focus-ring);
    outline-offset: 2px;
  }
}

.btn--primary {
  background: var(--color-brand);
  color: #fff;
  &:hover { background: var(--color-brand-hover); }
}

.btn--secondary {
  background: transparent;
  color: var(--color-brand);
  border-color: var(--color-brand);
  &:hover { background: rgba(59,130,246,0.08); }
}

.btn--ghost {
  background: transparent;
  color: var(--color-text-primary);
  &:hover { background: var(--color-border); }
}

/* Size variants */
.btn--sm { padding: var(--space-1) var(--space-2); font-size: 0.8rem; }
.btn--lg { padding: var(--space-3) var(--space-6); font-size: var(--font-size-base); }

• Variant axes map 1:1 to design properties (e.g. Button primary / ghost ↔ Figma component property).
• Attach a table or link in the SKILL so Agents do not invent variant names missing from the library.
• Change process: who approves new tokens, how docs and package versions stay in sync.

Style Dictionary Configuration: Figma-to-Code Token Pipeline

// Style Dictionary config: generate CSS variables from design JSON
// tokens/config.js
const StyleDictionary = require('style-dictionary');

module.exports = {
  source: ['tokens/**/*.json'],  // JSON exported from Tokens Studio or Figma
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'color',
      buildPath: 'src/styles/tokens/',
      files: [{ destination: 'tokens.css', format: 'css/variables' }],
    },
    js: {
      transformGroup: 'js',
      buildPath: 'src/styles/tokens/',
      files: [{ destination: 'tokens.js', format: 'javascript/es6' }],
    },
  },
};

// tokens/color.json (design tool export format)
{
  "color": {
    "brand": {
      "value": "#3b82f6",
      "type": "color",
      "description": "Primary brand color, maps to Figma: Brand/Primary"
    }
  }
}

// Generated output: CSS variable
// :root { --color-brand: #3b82f6; }

Dark mode, contrast, and focus rings should follow WCAG and in-repo tokens; check new semantics against the existing palette before shipping.

SKILL snippet example

---
name: design-system-alignment
description: Implement UI aligned to design tokens and variant mapping
---
# Token sources and no hardcoded values
1. Token source: CSS variables / Style Dictionary output / Tailwind theme — pick one and use it project-wide
2. No hardcoded values: color / spacing / font / radius values must not be written directly in component styles
3. Semantic layer consumption: components reference --color-brand, not --color-blue-500

# Variants and design property mapping
4. variant names map 1:1 to Figma component properties — attach link in SKILL
5. Size variants (sm/md/lg) map to Figma size property
6. Agents must not invent variant names that do not exist in the design library

# Token pipeline
7. Design tool exports JSON → Style Dictionary transforms → CSS variables / JS constants
8. Token changes require a PR review; changelog and version number update automatically
9. CI compares design export to code tokens; alert when drift exceeds threshold

# Theme and contrast
10. Dark mode overrides only the semantic token layer; primitive tokens are unchanged
11. Contrast: text vs background at least 4.5:1 (WCAG AA); large text 3:1
12. Focus ring: consistent style on all interactive elements; outline:none without replacement is forbidden

# Docs and acceptance
13. Story coverage: all variants × all sizes × light/dark theme
14. Visual regression testing: PR screenshots compared against design mockups
15. Change flow: new tokens must first be created in Figma, then submitted as a code PR

Site CSS variable quick copy