What causes design drift?

Deadlines, copy-pasted snippets, missing tokens for values teams need, and increasingly AI coding assistants, which write literal values unless they are given the design system as context.

How do you detect design drift?

Scan the code for values and components that bypass the design system, ignoring literals that are correct (icons, email templates, tests, layout math). Buoy does this from a GitHub URL at buoy.design/scan or with `npx @buoy-design/cli drift check`.

How do you prevent design drift?

Check new code where it arrives: pull request reviews that flag only added lines and suggest the existing token, a pre-commit check on staged lines, and giving AI coding assistants the tokens through an MCP server.

What is design drift?

Updated 2026-10-26 · Buoy

Short answer

Design drift is the growing gap between a design system and the code that ships: literal colors and spacing where tokens belong, near-duplicate components, and tokens swapped for their raw values. It is detected by scanning code for values that bypass the system, and prevented by checking new code in pull requests.

What it looks like

Hardcoded values. color: #2563eb where var(--color-primary) exists, or p-[13px] between p-3 and p-4.
Token regressions. A pull request replaces var(--space-4) with 16px. It renders identically today and stops following the scale tomorrow.
Near-duplicate components. PrimaryButton, ButtonPrimary and CTAButton, each edited separately.
Repeated one-offs. The same gray in forty files, which is a missing token rather than forty mistakes.

It is common in good codebases. Across 20 well-known open-source projects, Buoy found 2,685 hardcoded-value findings in 35,458 components (reports).

Why it happens

Deadlines. A literal is faster than finding the token.
Missing tokens. If the scale has no value between 12px and 16px, someone writes 14px.
Copy-paste from other files, Stack Overflow and design tool exports.
AI coding assistants. They write working code with literal values unless they are given the tokens.

Why it matters

Each instance is small. The cost appears at the next rebrand, dark mode or accessibility fix, when a change that should touch one token touches hundreds of files, and some are missed.

What is not drift

Not every literal is a problem. SVG icons, email templates, tests, layout math such as calc(), and deliberate choices a comment explains are correct as they are. Flagging them is how drift tools lose the team's trust.

Detect and prevent it

Measure it: scan a repository or run npx @buoy-design/cli show health.
Fix the cheap wins: literals that exactly match an existing token.
Stop new drift at the pull request, in a pre-commit hook, and in AI assistants via npx @buoy-design/cli mcp install.

More: how to audit a design system and how design system health is measured.

Scan a repository now

Paste a public GitHub URL and get a design health report in under a minute: score, the hardcoded values to fix first, and the path to 100.

Frequently asked questions

What is design drift?: Design drift is the gap that grows between a design system and the code that ships: hardcoded colors and spacing instead of tokens, near-duplicate components, and tokens replaced by their raw values. Each change looks harmless; together they make the product inconsistent and expensive to rebrand.
What causes design drift?: Deadlines, copy-pasted snippets, missing tokens for values teams need, and increasingly AI coding assistants, which write literal values unless they are given the design system as context.
How do you detect design drift?: Scan the code for values and components that bypass the design system, ignoring literals that are correct (icons, email templates, tests, layout math). Buoy does this from a GitHub URL at buoy.design/scan or with `npx @buoy-design/cli drift check`.
How do you prevent design drift?: Check new code where it arrives: pull request reviews that flag only added lines and suggest the existing token, a pre-commit check on staged lines, and giving AI coding assistants the tokens through an MCP server.