How to audit a design system in code

Updated · Buoy

Short answer

Inventory the tokens and components, find where code bypasses them with hardcoded values, fix the ones that exactly match an existing token first, and check every pull request so the drift does not come back. A scanner does the first three in under a minute; you can run one on any public GitHub repository at buoy.design/scan.

A design system audit answers one question: does the code actually use the design system? Design files and Storybook show what the system is supposed to be. The codebase shows what shipped. The gap between them is design drift, and it grows quietly with every deadline, copy-pasted snippet and AI-generated component.

1. Inventory the tokens

Start with what the system provides. Tokens live in more places than people expect:

  • CSS custom properties, usually in a :root block in tokens.css, theme.css or globals.css
  • A Tailwind theme: tailwind.config.js in v3, or an @theme block in CSS in v4
  • Design token JSON (tokens.json, Style Dictionary, Tokens Studio exports)
  • Sass variables such as $brand in _variables.scss or theme.scss
  • A component library theme (MUI, Chakra, Mantine)

Count them by category: colors, spacing, typography, radius, shadow. A system with 12 colors and no spacing scale will show up later as dozens of hand-picked margins.

2. Inventory the components

List the UI components and look for near-duplicates: three buttons with slightly different padding usually means one button that needed a variant. Duplicates are where drift multiplies, because each copy is edited separately.

3. Find where the code bypasses the system

This is the core of the audit: colors, spacing, font sizes, radii and shadows written as literals where a token belongs. color: #2563eb in a repository that defines --color-primary: #2563eb works today and drifts the day the brand color changes.

Just as important is what not to count. A useful audit skips values that are correct as literals:

  • Icons, logos and illustrations: SVG paint is artwork, not theming
  • Email templates: most email clients do not support CSS variables
  • Open Graph and social images, tests, stories and fixtures
  • Layout math: calc(), 100dvh, grid templates, 1px hairlines
  • Deliberate choices: a 2–3px optical nudge, or a value with a comment explaining why it differs

Skipping these is not leniency. An audit that flags a brand logo's fill color teaches the team to ignore the audit. Across the 20 open-source codebases in Buoy's public reports, 307 values were left alone because the code marked them as deliberate.

4. Rank the fixes by payoff

  1. Exact token matches. A literal that equals an existing token is a one-line, zero-risk swap.
  2. Repeated values. The same literal in five files is a missing token. Add it once and replace all five.
  3. One-offs. A single unusual value may be deliberate. Check before changing it.

5. Score it, so progress is visible

A single number makes an audit repeatable. Buoy's design health score weighs hardcoded values per component most heavily, then token health, naming consistency and critical issues such as color contrast. Across the public reports the median is 90/100, and 14 of 20 codebases score 80 or more.

6. Keep it fixed

An audit you run once decays. Put the check where new code arrives:

  • On pull requests, flagging only lines the PR adds, with a committable fix when a token exists
  • In a pre-commit hook that checks staged lines: npx @buoy-design/cli drift check --staged
  • In AI coding assistants, which write literals unless they are given the tokens: npx @buoy-design/cli mcp install

Run the audit

On any public GitHub repository, use buoy.design/scan. In a private checkout:

npx @buoy-design/cli show health     # score, pillars and the path to 100
npx @buoy-design/cli drift check     # every finding, with the token to use
npx @buoy-design/cli show tokens     # the token inventory

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

How do I scan a design system in a codebase?
Paste a public GitHub URL into buoy.design/scan, or run `npx @buoy-design/cli show health` in the repository. Both find the design tokens and components, list the hardcoded colors, spacing and font sizes that bypass them, and give a 0–100 health score with the changes that would raise it.
What should a design system audit check?
Four things: which tokens and components exist, where code bypasses them with literal values, whether the tokens are actually used, and accessibility problems such as low color contrast. It should skip values that are correct as literals: icons and logos, email templates, Open Graph images, tests, layout math like calc() and 100dvh, and deliberate optical nudges.
How long does a design system audit take?
An automated scan takes seconds to a few minutes: the 20 open-source codebases in Buoy's public reports took about half a minute each at the median. Fixing what it finds is the real work, which is why ranking by payoff matters: swapping a literal for an existing token is a one-line change.
Can I audit a private repository?
Yes, with the CLI. Run `npx @buoy-design/cli show health` inside a checkout; nothing leaves your machine. The web scanner at buoy.design/scan only reads public GitHub repositories.

More guides