design-token-lock

Design Token Lock — Single Source of Truth

Purpose

Solve the #1 recurring pain point in Figma-to-code: style drift. This skill extracts every design value from Figma, writes a versioned lockfile (design-tokens.lock.json), and generates Tailwind config + CSS custom properties from it. The lockfile becomes the single source of truth — tests assert against it, components reference it, and the verify-tokens script enforces it.

When to Use

• Phase 2 of the /build-from-figma pipeline (after figma-intake)
• Any time you need to extract or refresh design tokens from Figma
• When regenerating Tailwind config from a Figma file

Inputs

• Required: Figma file key (from build-spec.json or URL)
• Optional: .claude/plans/build-spec.json (for component-specific token scoping)

Process

Step 1: Extract Tokens from Figma

Call Figma MCP to get all design values:

1. get_variable_defs(fileKey)
   → Color variables, typography variables, spacing variables
   → Variable collections and modes (light/dark)

2. get_design_context(fileKey, nodeId) — for each top-level frame
   → Computed styles on actual elements
   → Auto-layout padding, gap, corner radius values
   → Text styles with exact font-family, size, weight, lineHeight

3. get_screenshot(fileKey, nodeId) — for color reference verification
   → Visual reference to cross-check extracted values

Step 2: Build Token Structure

Organize extracted values into a normalized structure. Every value must trace back to Figma.

Color tokens:

• Extract from Figma variables first (most accurate)
• Fall back to computed styles on elements if no variables defined
• Record: hex, rgb, hsl, and suggested Tailwind class name
• Group: primitives (raw values), semantic (roles), component-specific

Typography tokens:

• Font family with full fallback stack
• Size scale in px and rem (assuming 16px base)
• Weight values (numeric, not named)
• Line height as unitless ratio
• Letter spacing in em