Design
Design Token Drift Loop
Find hard-coded style values that should be tokens, replace one cluster per round, and stop only when token usage, component examples, and screenshots agree.
Use when
Product screens still ship hard-coded colors, spacing, type, or radii that ignore the token file, so the design system and the live UI disagree.
Intermediatedifficulty
Designcategory
Design Tokens Community Group (DTCG) + Style Dictionary / design-system token governance practice (adapted): treat tokens as the single source of truth and burn down hard-coded style drift with screenshot proofsource
Cadence
Weekly scheduled pass on the primary product UI package; also trigger after a design-system release or a large UI feature merge
Verification
After each change, (1) token lint or grep count of banned hard-coded color/spacing values in the scoped paths drops or stays flat with zero new hits, (2) component story/example pages render without console token errors, and (3) before/after screenshots for the same viewport show the intended visual with no unintended layout shift.
Structured loop spec
| Field | Value |
|---|---|
| Name | Design Token Drift Loop |
| Category | Design |
| Trigger | Weekly scheduled pass on the primary product UI package; also trigger after a design-system release or a large UI feature merge |
| Objective | Find hard-coded style values that should be tokens, replace one cluster per round, and stop only when token usage, component examples, and screenshots agree. |
| Allowed inputs | Relevant files, source notes, logs, tests, screenshots, metrics, or task state for this loop |
| Allowed actions | Lock scope: name the design-token source of truth (e.g. tokens.json / Style Dictionary build / CSS variables package), the UI package paths in scope, and the forbidden raw-value patterns (hex/rgb, raw px spacing outside allowed exceptions).; Baseline: run token build if required; capture grep/lint counts for hard-coded values in scope; screenshot 3–5 high-traffic components or routes at a fixed viewport into docs/loops/daily-2026-07-11-design-token-drift-loop/baseline/.; Rank one drift cluster only (e.g. primary button colors, card radii, type scale on settings). Do not boil the ocean across the whole app in one round.; Replace that cluster with existing tokens where possible; if a token is missing, add the smallest token entry + regenerate consumers, then map the UI to it. One reversible commit/PR per round.; Re-run the same lint/grep counts and re-screenshot the same fixtures. Record counts, screenshots, and decision (keep / adjust / revert) in docs/loops/daily-2026-07-11-design-token-drift-loop/progress.md and state.json.; If lint is green for the cluster but screenshots regress, revert the visual change and either fix the token mapping or stop for design approval. If two rounds produce zero net reduction in hard-coded hits, stop and report the remaining hotspots. |
| Verification | After each change, (1) token lint or grep count of banned hard-coded color/spacing values in the scoped paths drops or stays flat with zero new hits, (2) component story/example pages render without console token errors, and (3) before/after screenshots for the same viewport show the intended visual with no unintended layout shift. |
| Stop condition | Success: scoped hard-coded color/spacing hits are at zero (or only documented exceptions remain) and the same screenshot set matches design-system examples for two consecutive rounds. Stop earlier on: 3 rounds with no net lint/grep improvement, 45-minute budget exhausted, missing design-token source of truth, or any change that would alter brand palette, public marketing pages, or multi-brand themes without human approval. Honestly classify leftover exceptions (legacy, third-party, intentional one-offs) rather than claiming zero drift. |
| Budget | Max 3 rounds per run, 15 minutes per round (45 minutes total). At most one token schema addition and one UI package PR/commit set per run. No bulk restyles of more than one component family per round. |
| Approval boundary | Human approval required before: changing canonical brand/palette tokens used outside the scoped package, shipping token renames that break multi-brand or partner themes, editing production CDN design-system packages, or publishing visual changes to public marketing/docs sites. Local token remaps inside the scoped app package with screenshot proof may proceed; anything touching shared token packages or multi-app consumers is red. |
| Safe output | Draft, report, checklist, table, or approval-gated recommendation |
| Works with | Claude, ChatGPT, Gemini, any tool-using AI assistant |
Steps
- Lock scope: name the design-token source of truth (e.g. tokens.json / Style Dictionary build / CSS variables package), the UI package paths in scope, and the forbidden raw-value patterns (hex/rgb, raw px spacing outside allowed exceptions).
- Baseline: run token build if required; capture grep/lint counts for hard-coded values in scope; screenshot 3–5 high-traffic components or routes at a fixed viewport into docs/loops/daily-2026-07-11-design-token-drift-loop/baseline/.
- Rank one drift cluster only (e.g. primary button colors, card radii, type scale on settings). Do not boil the ocean across the whole app in one round.
- Replace that cluster with existing tokens where possible; if a token is missing, add the smallest token entry + regenerate consumers, then map the UI to it. One reversible commit/PR per round.
- Re-run the same lint/grep counts and re-screenshot the same fixtures. Record counts, screenshots, and decision (keep / adjust / revert) in docs/loops/daily-2026-07-11-design-token-drift-loop/progress.md and state.json.
- If lint is green for the cluster but screenshots regress, revert the visual change and either fix the token mapping or stop for design approval. If two rounds produce zero net reduction in hard-coded hits, stop and report the remaining hotspots.
Prompt
Run the Design Token Drift Loop for the scoped product UI. State file: docs/loops/daily-2026-07-11-design-token-drift-loop/state.json and progress.md. One change cluster per round only. Same verification every round: banned hard-coded color/spacing grep or token-lint count in scope, component examples with no token console errors, and before/after screenshots at the same viewport. Baseline counts and screenshots first, rank the worst drift cluster, map it to existing tokens (or add the smallest missing token then consume it), remeasure, and log keep/adjust/revert. Do not rewrite the whole design system. Stop when scoped hard-coded hits are zero (or only documented exceptions) with matching screenshots for two consecutive rounds, after 3 no-progress rounds, at the 45-minute budget, or when brand palette / shared token package / public marketing changes need human approval. Never invent tokens that contradict the design-token source of truth.Run in Claude Code
Paste this into Claude Code (or any tool-using agent) to run the loop bounded: one change per round, the same verification every round, durable state files, and explicit stop conditions.
Run the "Design Token Drift Loop" loop from AI Loop Library (https://ailooplibrary.com/loops/design-token-drift-loop/) as a bounded loop.
Goal: Find hard-coded style values that should be tokens, replace one cluster per round, and stop only when token usage, component examples, and screenshots agree.
Rules: one change per round; run the same verification every round (After each change, (1) token lint or grep count of banned hard-coded color/spacing values in the scoped paths drops or stays flat with zero new hits, (2) component story/example pages render without console token errors, and (3) before/after screenshots for the same viewport show the intended visual with no unintended layout shift.); append each round to docs/loops/design-token-drift-loop/progress.md and update docs/loops/design-token-drift-loop/state.json; stop on verifier pass, 8 rounds, 3 consecutive failed verifications, no progress, a blocker, or anything needing human approval (money, production, outbound, deletion). Finish with a proof report: rounds used, changes made, verification output, remaining risk, and the next human decision.