Design Drift
I find where the UI has quietly diverged from its own design system and pull it back — consolidating one-off values into tokens, collapsing duplicate component variants, and promoting recurring exceptions into the system before they calcify into debt.
This is not a taste audit. design-audit asks "does this look good?" I ask "is this consistent with the system that already exists, and what should be normalized or promoted?" Drift is a refactor problem, not an aesthetics problem.
Core Principle
Every visual value in the codebase is one of three things:
- On-system — references a token (
var(--space-4), theme.colors.primary). Leave it.
- Drift to normalize — a hardcoded value that is close to an existing token (
padding: 15px next to a 16px scale, #3b82f7 vs the brand #3b82f6). Snap it back to the token.
- Drift to promote — a hardcoded value that recurs deliberately and has no token (
#0a0a0a used in 14 places). It's a real system value that was never named. Add it to the system, then reference it.
The skill is deciding which bucket each value falls in — never blindly find-and-replacing.
Evidence First — No Guessing
I report only drift I can point to. Every finding cites file:line and a count. If I can't locate the design system's source of truth, I stop and ask rather than inventing tokens.
- Locate the system. Find the token source:
tailwind.config.*, theme.ts, :root custom properties, tokens.json, a DESIGN_SYSTEM.md, Style Dictionary, etc. This is ground truth. If there is no system, this skill doesn't apply yet — recommend interface-design or high-end-visual-design to establish one first.
- Scan for raw values. Grep the styling surface (CSS/SCSS, styled-components, Tailwind arbitrary values
[...], inline style=, RN StyleSheet) for:
- Color: hex,
rgb(, hsl(, named colors outside the token layer
- Spacing: raw
px/rem in padding/margin/gap not drawn from the scale
- Type:
font-size / font-weight / line-height literals off the type scale
- Radii & shadows:
border-radius and box-shadow literals
- Z-index: bare integers (a classic drift hotspot)
- Breakpoints: media queries with literal widths
- Cluster by proximity. Group near-identical values (
#fafafa, #fbfbfb, #f9f9f9 → one cluster). The cluster size is the signal: how many shades of gray actually ship?
- Find duplicate components. Look for
Button2, CardNew, PrimaryButtonV2, copy-pasted variants, and components that reimplement an existing primitive with slightly different values.
Classification
For each cluster, decide and justify:
| Bucket |
Test |
Action |
| Normalize |
Within rounding distance of an existing token, or a clear typo/near-dupe |
Replace with the token |
| Promote |
Recurs ≥3× intentionally, no token exists, semantically distinct |
Add a named token, then reference it |
| Leave |
Genuinely one-off and intentional (e.g. a marketing hero) |
Document why; don't touch |
State the count and the decision for every cluster. "14 hardcoded grays collapse to 4 existing tokens + 1 new --surface-sunken" is the deliverable, not "cleaned up colors."
Deliverable
Present a drift report before changing anything:
- Token source of truth — what the system is and where it lives.
- Drift inventory — clustered findings with counts, file:line evidence, and the Normalize/Promote/Leave decision per cluster. Order by blast radius (most occurrences first).
- Proposed token additions — any new named values, with rationale for the name and where they slot into the scale.
- Consolidation plan — phased like a refactor: high-confidence mechanical swaps first (typos, exact near-dupes), judgment calls last.
Wait for approval. The user reorders, cuts, or rejects promotions. Execute only what's approved, one phase at a time, presenting a diff after each.
Guardrails
- Never introduce a new visual value while fixing drift — that is drift. Promotions go through the token layer, named and reviewed.
- Pixel-faithful by default. Normalizing should not visibly change the UI unless the user opts into "snap to nearest." If a swap shifts a value by more than a rounding margin, flag it as a visual change, not a silent fix.
- One axis at a time when the surface is large — colors, then spacing, then type. Mixing axes makes diffs unreviewable.
- Touch styling only. Logic, state, props, and behavior are out of scope. Flag functional coupling (e.g. a component that can't be deduped without a prop change) for the build agent.
- Re-drift prevention. After consolidating, recommend the cheap guardrail: a lint rule (
stylelint declaration-property-value-allowed-list, ESLint no-restricted-syntax for arbitrary Tailwind values) or a token-only convention note, so the same drift can't silently return.
Scope Boundaries
I touch: hardcoded visual values, duplicate component variants, token definitions, references to tokens.
I don't touch: application logic, new features, visual taste decisions (use design-audit), establishing a system from scratch (use interface-design / high-end-visual-design).
1---2name: design-drift3description: Detect and fix design drift — the ad-hoc colors, spacing, type sizes, shadows, and duplicate component variants that accumulate outside the design system and harden into debt. Use when the user mentions "design drift", "inconsistent UI", "one-off styles", "magic numbers in CSS", "consolidate styles", "design tokens are a mess", "too many shades of gray", or wants to align an existing codebase back to its design system before patterns calcify.4---56# Design Drift78I find where the UI has quietly diverged from its own design system and pull it back — consolidating one-off values into tokens, collapsing duplicate component variants, and promoting recurring exceptions into the system *before* they calcify into debt.910This is not a taste audit. `design-audit` asks "does this look good?" I ask "is this **consistent with the system that already exists**, and what should be normalized or promoted?" Drift is a refactor problem, not an aesthetics problem.1112## Core Principle1314Every visual value in the codebase is one of three things:151. **On-system** — references a token (`var(--space-4)`, `theme.colors.primary`). Leave it.162. **Drift to normalize** — a hardcoded value that is *close to* an existing token (`padding: 15px` next to a `16px` scale, `#3b82f7` vs the brand `#3b82f6`). Snap it back to the token.173. **Drift to promote** — a hardcoded value that recurs deliberately and has no token (`#0a0a0a` used in 14 places). It's a real system value that was never named. Add it to the system, then reference it.1819The skill is deciding which bucket each value falls in — never blindly find-and-replacing.2021## Evidence First — No Guessing2223I report only drift I can point to. Every finding cites file:line and a count. If I can't locate the design system's source of truth, I stop and ask rather than inventing tokens.24251. **Locate the system.** Find the token source: `tailwind.config.*`, `theme.ts`, `:root` custom properties, `tokens.json`, a `DESIGN_SYSTEM.md`, Style Dictionary, etc. This is ground truth. If there is no system, this skill doesn't apply yet — recommend `interface-design` or `high-end-visual-design` to establish one first.262. **Scan for raw values.** Grep the styling surface (CSS/SCSS, styled-components, Tailwind arbitrary values `[...]`, inline `style=`, RN `StyleSheet`) for:27 - **Color**: hex, `rgb(`, `hsl(`, named colors outside the token layer28 - **Spacing**: raw `px`/`rem` in padding/margin/gap not drawn from the scale29 - **Type**: `font-size` / `font-weight` / `line-height` literals off the type scale30 - **Radii & shadows**: `border-radius` and `box-shadow` literals31 - **Z-index**: bare integers (a classic drift hotspot)32 - **Breakpoints**: media queries with literal widths333. **Cluster by proximity.** Group near-identical values (`#fafafa`, `#fbfbfb`, `#f9f9f9` → one cluster). The cluster size is the signal: how many shades of gray actually ship?344. **Find duplicate components.** Look for `Button2`, `CardNew`, `PrimaryButtonV2`, copy-pasted variants, and components that reimplement an existing primitive with slightly different values.3536## Classification3738For each cluster, decide and justify:3940| Bucket | Test | Action |41|--------|------|--------|42| Normalize | Within rounding distance of an existing token, or a clear typo/near-dupe | Replace with the token |43| Promote | Recurs ≥3× intentionally, no token exists, semantically distinct | Add a named token, then reference it |44| Leave | Genuinely one-off and intentional (e.g. a marketing hero) | Document why; don't touch |4546State the count and the decision for every cluster. "14 hardcoded grays collapse to 4 existing tokens + 1 new `--surface-sunken`" is the deliverable, not "cleaned up colors."4748## Deliverable4950Present a **drift report** before changing anything:51521. **Token source of truth** — what the system is and where it lives.532. **Drift inventory** — clustered findings with counts, file:line evidence, and the Normalize/Promote/Leave decision per cluster. Order by blast radius (most occurrences first).543. **Proposed token additions** — any new named values, with rationale for the name and where they slot into the scale.554. **Consolidation plan** — phased like a refactor: high-confidence mechanical swaps first (typos, exact near-dupes), judgment calls last.5657Wait for approval. The user reorders, cuts, or rejects promotions. Execute only what's approved, one phase at a time, presenting a diff after each.5859## Guardrails6061- **Never** introduce a new visual value while fixing drift — that *is* drift. Promotions go through the token layer, named and reviewed.62- **Pixel-faithful by default.** Normalizing should not visibly change the UI unless the user opts into "snap to nearest." If a swap shifts a value by more than a rounding margin, flag it as a visual change, not a silent fix.63- **One axis at a time** when the surface is large — colors, then spacing, then type. Mixing axes makes diffs unreviewable.64- **Touch styling only.** Logic, state, props, and behavior are out of scope. Flag functional coupling (e.g. a component that can't be deduped without a prop change) for the build agent.65- **Re-drift prevention.** After consolidating, recommend the cheap guardrail: a lint rule (`stylelint` `declaration-property-value-allowed-list`, ESLint `no-restricted-syntax` for arbitrary Tailwind values) or a token-only convention note, so the same drift can't silently return.6667## Scope Boundaries6869**I touch:** hardcoded visual values, duplicate component variants, token definitions, references to tokens.7071**I don't touch:** application logic, new features, visual taste decisions (use `design-audit`), establishing a system from scratch (use `interface-design` / `high-end-visual-design`).
ariadoss