Design Token Pipeline

Quick Start

No Claude Code? Run the scripts manually—each phase works standalone.

Prerequisites

Required: Node.js 18+, this repository cloned.
Optional: Claude Code for orchestration, Figma MCP for live data.

Phase 1: Environment Check

The demo verifies your setup before running. If anything's missing, you'll get clear instructions.

Checking environment...

[ok] Project directory: foxtrot
[ok] tokens/ directory exists
[ok] scripts/detect-drift.js
[ok] scripts/transform-tokens.js
[ok] scripts/analyze-impact.js
[warn] Figma MCP not configured — using sample tokens

[ok] Environment ready

Phase 2: Read Tokens

In production, this reads live from Figma via MCP. For the demo, sample data simulates three token changes.

Reading tokens from Figma...

[ok] Loaded 16 tokens from figma-source.json

  colors/accent-default: #ff6b35 ← CHANGED
  spacing/section-md: 120px ← CHANGED
  typography/size-base: 20px ← CHANGED

Phase 3: Drift Detection

Before syncing, scan the codebase for hardcoded values that should already be tokens. This reveals design debt that accumulates silently.

DESIGN DRIFT REPORT

HARDCODED VALUES FOUND: 112

src/components/CursorGlow.astro:21
│ rgba(255, 255, 255, 0.03)
└→ Use: var(--color-glow)

src/pages/index.astro:247
│ 1.5rem
└→ Use: var(--gutter)

... (109 more)

─────────────────────────────────────
PARITY SCORE: 77%
368 token usages found, 112 should be converted

Most teams don't know their parity score. They sync tokens but never measure adoption. This metric makes design debt visible and trackable.

Phase 4: Transform

Convert Figma tokens to CSS via Style Dictionary. The pipeline outputs Tailwind CSS 4 @theme format.

@theme {
  --colors-surface-deep: #0a0a0a;
  --colors-accent-default: #ff6b35;
  --spacing-section-md: 120px;
  --typography-size-base: 20px;
  ...
}

Output files: tokens/figma-source.json (raw), tokens/tokens.json (W3C DTCG), tokens/generated-theme.css (Tailwind @theme)

Phase 5: Impact Analysis

Before applying changes, analyze what breaks. WCAG contrast checks for colors, layout impact for spacing, reflow warnings for typography.

IMPACT ANALYSIS

TOKEN: --color-accent
CHANGE: #e5e5e5 → #ff6b35

[!] WCAG FAILURES (1)

src/styles/global.css:145
│ background usage
│ Contrast: 2.6:1 (needs 4.5:1)
└→ Text on this background may be hard to read

[ok] SAFE USAGES (5)
• decorative contexts only

─────────────────────────────────────

TOKEN: --space-section-md
CHANGE: 5.5rem → 7.5rem (36% change)
[ok] LAYOUT CHECK PASSED

TOKEN: --font-size-base
CHANGE: 1.125rem → 1.25rem (11% change)
[ok] TYPOGRAPHY CHECK PASSED

Phase 6: PR Simulation

See what an automated PR would look like: files changed, diff preview, impact summary, and simulated notifications.

Phase 7: Apply Changes

The final step asks for confirmation before modifying your codebase. Changes are applied to global.css with inline comments.

Changes Applied

BEFORE → AFTER

--color-accent:     #e5e5e5 → #ff6b35
--space-section-md: 5.5rem  → 7.5rem
--font-size-base:   1.125rem → 1.25rem

Files modified:
• src/styles/global.css — 3 token values changed

Run with --dry-run to preview changes without applying.

Next Steps

1. Configure Figma MCP — Connect to live Figma data instead of sample files. Get Figma MCP →

2. Fix the WCAG issue — The orange accent (#ff6b35) needs a darker shade or lighter text to meet AA contrast.

3. Improve parity score — Run drift detection and systematically replace hardcoded values. Target 95%+.

4. Add to CI/CD — Run drift detection on every PR. Block merges below a parity threshold.

Troubleshooting