How to run a design system audit, from inventory to roadmap
Five audits in one pass, from interface inventory to adoption, scored with a rubric that turns findings into next quarter's work.
Most design system roadmaps are written from memory: whoever complains loudest about the date picker gets the date picker. An audit replaces that with counts, such as how many button styles ship in production, how often each Figma component gets detached, and how many hex values bypass your tokens.
A design system audit is a structured review of how your system is actually used across design files and code. You run five checks (interface, code, tokens, accessibility, documentation and adoption), score each on the same scale, and turn the lowest scores into the roadmap.
Key takeaways
- An interface inventory shows what users see; a code census shows what engineers actually import, and the gap between them is your duplication.
- Static analysis tools such as react-scanner count every component instance and prop in a React codebase.
- Figma's library analytics report insertions and detachments per component, which is the design-side half of adoption.
- Score every audit area on the same 1 to 5 rubric, so findings compete for roadmap space on equal terms.
Start with an interface inventory
Brad Frost described the interface inventory in 2013 as "a comprehensive collection of the bits and pieces that make up your interface." The method is still the right first step. Screenshot every distinct variation of each component, not every instance, and group them by category: buttons, inputs, cards, modals, tables, menus, typography, color, icons.
Do it as a group. A designer, a front-end engineer, and a product manager will each spot variants the others normalize. Keep the output numeric: 14 button styles, 6 modal layouts, 4 date pickers. Counts make the case later; screenshots make it vivid.
How do you count component usage in code?
The inventory shows what the product looks like. The code census shows what it's built from, and that is where duplication hides. Two tools cover most React codebases:
- react-scanner statically analyzes JavaScript and TypeScript, finds every rendered component with its import source and props, and outputs JSON. Its built-in processors count components, count components and props, or emit the raw per-instance report.
- Omlet pairs a CLI and VS Code extension with a dashboard that tracks design system adoption over time and shows which non-system components developers use most.
From either, compute an adoption ratio for each category: system component instances divided by system plus local look-alikes. A Button imported from your package 900 times next to 300 local PrimaryBtn instances gives 75%. Prop counts matter too. A prop no one passes is a candidate for removal, and a className override on half of all instances is a missing variant.
The design-side census
Figma's library analytics show insertions and detachments for components, styles, and variables, broken down by team, over the last 30, 60, or 90 days or a rolling year. It's available on Organization and Enterprise plans, among others. A high detach rate is the clearest signal in the whole audit: designers wanted the component but couldn't make it fit.
Run a token and style audit
Tokens fail quietly. Search stylesheets and component files for raw hex values, rgb() calls, and pixel spacing that should be tokens, then express the result as coverage: the share of color, spacing, and radius declarations that reference a token.
In Figma, Check designs flags hard-coded colors, spacing, radius, and type that could use variables or styles, plus components detached from their library. Figma's help center says it does not use LLMs or generative AI, and it's available on Organization, Enterprise, and some other plans. Run it on your highest-traffic files and record the counts, not just the fixes.
Also check the token layer itself. Look for semantic tokens that resolve to the same value, primitives used directly in components, and a dark mode, if you have one, that's missing values.
Audit accessibility at the component level
Accessibility problems repeat because components repeat. WebAIM's 2026 analysis of the top million home pages found low-contrast text on 83.9% of them, and fixing a single text token can clear that failure across a whole product. Audit each component, not each page:
- Run axe-core against every component story or rendered state.
- Tab through each interactive component without a mouse, checking that focus is visible and returns to a sensible place.
- Check names, roles, and states with a screen reader on interactive components.
- Record a pass, partial, or fail per component, with the WCAG criterion that failed.
Check documentation and adoption
A component no one can find doesn't exist. For each component, check whether documentation covers usage guidance, props or properties, variants, accessibility notes, and a live example. Then talk to the people using it: a ten-question survey, a review of the last quarter's support questions, and a look at which teams appear in library analytics at all. Teams missing from the data are an adoption finding in themselves.
How do you score a design system audit?
Score every area from 1 to 5 using the same definitions, so a token problem and a documentation problem can be compared directly.
| Area | 1: ad hoc | 3: partial | 5: systematic | Evidence |
|---|---|---|---|---|
| Interface consistency | Many variants per category | Two or three per category | One per documented use | Inventory counts |
| Code adoption | Under 40% system instances | 40% to 80% | Over 80% | react-scanner or Omlet |
| Design adoption | Frequent detaches | Detaches in a few components | Rare, explained detaches | Library analytics |
| Token coverage | Raw values common | Color tokenized, spacing not | Nearly all values tokenized | Search and Check designs |
| Accessibility | Untested | Automated checks only | Automated and manual, per component | axe and keyboard log |
| Documentation | Names only | Props, no guidance | Usage, props, accessibility, examples | Docs review |
The thresholds are a starting point; tune them to your product. Then turn scores into work:
- Multiply each gap (5 minus score) by reach, meaning the number of teams or screens affected.
- Rank areas by that product and take the top three into next quarter.
- Write each as an outcome with a metric, such as "raise code adoption for forms from 55% to 80%."
- Re-run the same scripts and analytics next quarter, so the audit becomes a trend line.
An audit you can't re-run is an opinion with screenshots.
Keep every script, query, and export in a repository. An audit you can't re-run is an opinion with screenshots.
Where Pegasus fits
An audit often ends in one of two places: consolidate what you have, or adopt a system that already has the structure you're missing. Pegasus is built for the second case. Its Figma library and React code share component names, variant structure, and tokens, so a code census and a Figma census count the same things under the same names.
The library has 1,540 components and 470 tokens as Figma variables in light and dark modes, and one token source themes both the Figma variables and the code's theme object, so token coverage has one place to measure. Each component is documented with anatomy, properties, and layout and spacing, and built to WCAG 2.1 AA with keyboard paths, focus states, and contrast documented per component. Pegasus Lite, a free subset, lets you compare a few categories against your inventory before deciding.
FAQ
How long does a design system audit take?
It depends on product size, but plan the first audit as a short project rather than a background task. The interface inventory and code census are the slowest parts, because they set up scripts and categories. The second audit is much faster, since you rerun the same scripts, analytics exports, and rubric. Most teams get more from a quarterly rhythm than from one exhaustive audit.
What tools measure design system adoption?
In code, react-scanner counts component and prop usage in React projects, and Omlet tracks adoption over time in a dashboard. In design, Figma's library analytics report insertions and detachments per component, style, and variable, and Check designs flags hard-coded values. For accessibility, axe-core runs automated checks. Combine them so design and code adoption are measured side by side.
What should a design system audit produce?
A scored rubric, a ranked list of gaps, and three to five roadmap items with metrics. The scores show where the system is weakest, ranking by reach shows what matters most, and the metrics let you prove progress when you re-run the audit. Screenshots and counts from the inventory are supporting evidence for stakeholders, not the deliverable itself.
Sources
- Interface inventory, Brad Frost (2013)
- react-scanner, GitHub
- Omlet: React component usage analytics, Omlet
- View and explore library analytics, Figma Help Center
- Check designs in Figma, Figma Help Center
- The WebAIM Million 2026, WebAIM (2026)
- axe-core, Deque Systems on GitHub
One system. In Figma and in code.
Pegasus ships 1,540 components, 470 tokens, matching React code, Storybook, and a local MCP server. $149, one-time.
Get the full system