Design System Token Pass

---
name: Design System Token Pass
description: Systematic audit of component code for hard-coded values that should be design tokens, returning a refactor plan.
when_to_use: User pastes a component and asks for a token review, theme-readiness check, or design-system compliance pass.
---

# Design System Token Pass

## What this skill does
Walks component code through five fixed passes — color, spacing, typography, radius and shadow, motion and breakpoints — and returns a refactor plan naming every hard-coded value, the token it should become, and the code change. Also flags missing tokens that should be promoted into the system.

## When to load this skill
Load when the user pastes CSS, SCSS, Tailwind, styled-components, CSS-in-JS, or any component markup and asks: "is this using our tokens", "make this theme-ready", "dark-mode-proof this", "design-system audit", "clean up the magic numbers", or "why doesn't this look right in dark mode".

## The procedure

### Step 1 — Confirm the token system
Before auditing, ask one question: what token system is in use? CSS custom properties, Tailwind config, a JS theme object, Figma Tokens JSON, or none declared yet. If the user has a token file, request it or ask for the naming conventions. If they don't, say so clearly: this skill assumes a token system exists. Offer to generate a starter token list instead, but don't pretend you're doing a refactor against a system that isn't there.

### Step 2 — Pass one: color
Scan for every color value: hex, rgb, rgba, hsl, named colors, and Tailwind color utilities used with arbitrary values (`bg-[#2a2e35]`). For each, check if a matching token exists. If yes, propose the swap. If no, propose a token name following the user's convention (`color.surface.raised`, `--color-text-muted`, etc.) and note it in the "missing tokens" list. Flag any color used for both foreground and background somewhere — that's a dark-mode bug waiting to happen.

### Step 3 — Pass two: spacing
Scan for every padding, margin, gap, top, left, right, bottom, width, height value. Ignore layout constraints (100%, auto, 100vh) — those aren't spacing. Focus on fixed pixel, rem, or em values. Map each to a spacing scale token (`space.2`, `--space-md`). Values that fall outside the scale get flagged twice: once for the refactor, once for the question of whether the scale is wrong or the component is wrong. Never silently round to the nearest token — ask the designer.

### Step 4 — Pass three: typography
Scan for font-size, line-height, letter-spacing, font-weight, and font-family. Typography tokens are usually bundled (a `text-body` token carries size, line-height, and weight together). Propose the bundle swap, not individual value swaps. Call out any inline font-family — those almost always belong in a root token. Flag responsive font sizing (clamp, vw units) as in-scope: tokens should handle that, not individual components.

### Step 5 — Pass four: radius, shadow, border
Scan for border-radius, box-shadow, border-width, and border-color. These are the tokens most often missed in refactors because they're visually subtle. Check that every radius and shadow maps to a scale. Flag custom shadows ("0 2px 8px rgba(0,0,0,0.1)") — they almost always have a token equivalent, and if they don't, they should.

### Step 6 — Pass five: motion and breakpoints, then write the plan
Final pass: transition-duration, transition-timing-function, animation timings, and media-query breakpoints. Each should be a token. Then write the refactor plan: grouped by category, each entry showing original → token, with missing tokens listed separately. Close with a count ("23 values mapped to existing tokens, 4 new tokens proposed") and a one-line theme-readiness verdict. Hand off to [The Design Systems Zealot](/agents/soul-the-design-systems-zealot) for discussion, or [Color Contrast Fix](/agents/prompt-color-contrast-fix) if any proposed color swap risks failing contrast.

## A worked example

**User:** Review this card component against our tokens. We use CSS custom properties, naming is `--color-*`, `--space-*`, `--radius-*`, `--shadow-*`.

```css
.card {
  background: #ffffff;
  color: #1a1a1a;
  padding: 16px 20px;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0,0,0,0.08);
  font-size: 15px;
  line-height: 1.5;
  transition: all 200ms ease;
}
```

**Claude:** Five-pass token review. System confirmed: CSS custom properties, `--color-*`, `--space-*`, `--radius-*`, `--shadow-*`.

**Color (2 values):**
- `#ffffff` → `var(--color-surface-raised)`. Standard.
- `#1a1a1a` → `var(--color-text-primary)`. Standard.

**Spacing (2 values):**
- `padding: 16px 20px` → `var(--space-4) var(--space-5)`. Assuming a 4px base. Flag: asymmetric padding is unusual — confirm it's intentional, not a one-off patch.

**Typography (2 values):**
- `font-size: 15px` → not a standard scale value. Propose `var(--text-body-size)` which is likely 16px. Ask the designer: is 15px intentional, or drift?
- `line-height: 1.5` → `var(--text-body-line-height)`. Bundle these two into `var(--text-body)` if the system supports composite tokens.

**Radius / shadow (2 values):**
- `border-radius: 8px` → `var(--radius-md)`.
- `box-shadow: 0 2px 8px rgba(0,0,0,0.08)` → `var(--shadow-sm)`. Verify it matches — this is the shadow that most often has a "close but not quite" token.

**Motion (1 value):**
- `transition: all 200ms ease` → `transition: all var(--duration-fast) var(--ease-standard)`. Also: avoid `transition: all` — name the properties. It's a performance win and a common dark-mode flash fix.

**Refactored:**
```css
.card {
  background: var(--color-surface-raised);
  color: var(--color-text-primary);
  padding: var(--space-4) var(--space-5);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-sm);
  font: var(--text-body);
  transition: background var(--duration-fast) var(--ease-standard),
              box-shadow var(--duration-fast) var(--ease-standard);
}
```

**Missing or questioned tokens:** none new, but two questions for the designer: (1) is the 15px font-size drift or intentional? (2) is the asymmetric padding drift or intentional?

**Count:** 9 values reviewed, 9 mapped to tokens, 0 new tokens needed, 2 design questions flagged.

**Theme-readiness:** yes, once the swaps land. The `transition: all` change also prevents the dark-mode flash where text color animates visibly when the theme switches.

## What this skill will NOT do
- Will NOT run without a confirmed token system. No silent guessing at naming conventions.
- Will NOT round hard-coded values to the nearest token silently. Drift gets flagged as a design question, not auto-corrected.
- Will NOT refactor logic, structure, or accessibility — only token substitutions. Other concerns get flagged and handed off.
- Will NOT invent tokens the user didn't ask for. Missing tokens are proposed, not added.
- Will NOT guarantee visual fidelity post-refactor. A token pass can shift a component by a pixel or a shade — the skill says so and recommends a visual diff.