Sweep Hardcoded Values to Design Tokens with Evidence

Tier: Core · Workflow area: Design-to-code & design systems

This playbook turns "we should really tokenize this" from a quarter-long chore into one afternoon of mechanical inventory, one agent-built mapping table, and one focused review session.

Prerequisites

• •
  The token source of truth in the repo: a tokens.json consumed by style-dictionary, a Tailwind @theme block, or a theme.ts / CSS-variables file.
• •
  A coding agent with repo access (Claude Code, Cursor agent mode).
• •
  Some visual gate — Storybook, a Playwright screenshot script, or Chromatic — to prove "zero visual change" batches actually changed nothing.

The recipe

1. 1.

   Size the problem mechanically before involving a model. Counting is a job for ripgrep, not tokens:

   Copy

   rg -n --no-heading \
     -e '#[0-9a-fA-F]{3,8}\b' \
     -e 'rgba?\(' \
     -e '\b\d+px\b' \
     src/ --glob '!**/tokens/**' --glob '!**/*.test.*' | wc -l
   

   Record the number. It is your progress metric and your PR-slicing guide — 900 hits means several batched PRs, not one.

2. 2.

   Load the token vocabulary into the agent. The single biggest failure mode is an agent that invents plausible-sounding tokens. Anchor it:

   Copy

   Read src/design-tokens/tokens.json (style-dictionary format). Build a
   lookup of every color, spacing, radius, and typography token with its
   RESOLVED value (follow aliases like {color.brand.600}). Output the
   lookup as a table. Do not modify any files yet.
   

   Spot-check five rows against the file. If an alias resolved wrong here, every mapping downstream is wrong.

3. 3.

   Demand a mapping table with evidence — not edits. This is the heart of the playbook:

   Copy

   For every hardcoded color, spacing, radius, and font-size value under
   src/features/billing/, produce a table with columns:
   file:line | code excerpt | current value | proposed token |
   token's resolved value | delta | confidence (exact/near/none).
   "exact" = resolved values identical. "near" = within 2% lightness or
   one spacing step. "none" = no token within that range — propose
   nothing, flag for design. Never round silently. Do not edit files.
   

   Sample of what a healthy table looks like:

   file:line	current	proposed token	resolves to	delta	confidence
   InvoiceCard.tsx:41	#2563eb	color.brand.600	#2563eb	none	exact
   InvoiceCard.tsx:78	padding: 18px	space.400	16px	−2px	near
   StatusPill.tsx:12	#e8fff1	—	—	—	none

4. 4.

   Approve per mapping, not per file. Three verdicts, three speeds. Exact rows: skim and approve in bulk. Near rows: these are design decisions in disguise — an 18px padding becoming 16px moves pixels; get a designer's yes, row by row. None rows: send the list to the design-system owner; they either mint a new token or declare the value a bug.

5. 5.

   Apply in confidence-ordered batches, gated visually. Have the agent apply only approved exact rows first, then run your screenshot diff:

   Copy

   Apply only the rows marked APPROVED-EXACT in mapping.md. One commit
   per component directory. Touch nothing outside those rows.
   

   The exact batch must produce a pixel-identical diff — if it does not, a "resolved value" was wrong, and you stop and re-audit step 2. Near batches land next, each with its expected visual delta named in the PR description.

6. 6.

   Lock the door behind you. A sweep without a gate decays in a month. Add stylelint-declaration-strict-value (or an ESLint rule for CSS-in-JS) so raw hex and px literals fail CI, with an explicit /* token-exempt: reason */ escape hatch for the genuinely intentional cases.

Tool variations

• Claude Code: strongest for the multi-file table-then-apply loop; keep mapping.md in the repo so approvals survive across sessions.
• Cursor: run the inventory prompt per feature directory in agent mode; its inline diff view makes the near-batch review fast.
• style-dictionary shops: point the agent at the built platform output too (build/css/variables.css) so it maps to the names your code actually imports.
• Tailwind projects: the sweep targets arbitrary values (bg-[#2563eb], p-[18px]) and maps them to theme utilities (bg-brand-600, p-4); the same table format applies.
• Mobile: identical recipe against Compose (Color(0xFF2563EB) → MaterialTheme.colorScheme) or SwiftUI (Color(red:green:blue:) → asset-catalog / token extension values).

Quality check

• Traceabilityevery changed line maps to an approved row in the table; nothing was edited "while in there."
• Exact batch proofthe exact-confidence PR shipped with a zero-diff screenshot run attached.
• Near-batch sign-offeach visual delta was named in the PR and approved by design, not discovered by design.
• Residual countthe step-1 ripgrep number dropped to your target, and the remainder are tagged token-exempt with reasons.
• Regression gatethe lint rule is merged, so the number cannot silently climb back.