Insights
A design system audit checklist for messy component libraries: trace components through tokens, Figma, code and product use, then decide what to fix or keep. To audit a design system, pick one or two component families that teams keep working around, then trace each through tokens, Figma, code, documentation, release a
To audit a design system, pick one or two component families that teams keep working around, then trace each through tokens, Figma, code, documentation, release and the running product. Record where they diverge, why, and who owns the fix. An inventory tells you what exists; the trace tells you whether the system is actually used.
Last reviewed September 29, 2026.
Audit guides often start as inventories: collect every button, color and text style, group them, and flag the duplicates. That work is useful, and in a messy library you will need some of it. But an inventory describes the library. It does not tell you why the product team copied the date picker last quarter, or whether that copy was a mistake or the only sensible option. This guide covers both halves, with a checklist you can run yourself and the questions to ask if you bring someone in.
Start from a repeated cost, not the whole library
Brad Frost's interface inventory (2013) is a widely cited way to see everything a product contains: screenshot each distinct treatment of each component and lay them side by side. When nobody knows what exists, start there.
For a library that already exists but is messy, our judgment is that a whole-product inventory is usually the wrong first move. It is slow, and it tends to end in a long list of inconsistencies with no ranking, because a mismatched border radius and a missing permission state look equally like "inconsistency" on a slide. A tighter start:
- Name the repeated cost. Which component family causes arguments in review, gets rebuilt, or generates support questions? Tables, form fields, filters, status badges and navigation are typical candidates to check.
- Choose the sample. One or two families, plus at least two product areas that use them. One product path shows you a finding; a second tells you whether it recurs.
- Inventory that family only. Every variant in Figma, every coded implementation (shared and copied), and every place it appears in the running product.
- Write down what the audit will not cover. A sample-based audit can say what is true of the families it traced. It cannot say how common the problem is across the whole portfolio.
Design system audit checklist
Work through each layer for the families in your sample. The right-hand column is what should make you look harder, not an automatic verdict.
| Layer | What to check | Evidence to collect | Warning sign |
|---|---|---|---|
| Scope and ownership | Which products consume the system; who owns shared decisions; who approves exceptions | A list of consuming products, owners and the path a change request takes | No named owner, or requests that wait with nobody assigned |
| Tokens and foundations | Whether color, spacing and type are referenced through named tokens or typed in as raw values; whether token names carry meaning | Token files, Figma variables, and lint output from rules such as Stylelint's `color-no-hex` and `declaration-property-value-disallowed-list` | The same raw value doing different jobs, or local values that are easier to use than the token |
| Component contract | The states, variants, properties and content limits each component supports: default, hover, focus, disabled, loading, error, empty, overflow | Figma component properties, Storybook stories, the coded component's props | A state that exists in design but not code, or the reverse |
| Design and code agreement | Whether the Figma component and the coded component describe the same thing, state by state | A side-by-side comparison for each state in the sample | Two sources of truth and no agreed rule for which one governs |
| Accessibility in the product | Text contrast of at least 4.5:1, 3:1 for component boundaries and states, visible focus that is not entirely hidden by other content, targets of at least 24 by 24 CSS pixels, and a programmatic name, role and value (WCAG 2.2); keyboard behavior against the WAI-ARIA Authoring Practices patterns | Automated results plus manual keyboard and screen reader checks in the running product | Passes in isolation and fails once composed into a real screen |
| Documentation | Usage guidance, when not to use a component, examples, known exceptions, last update | The documentation site and its change history | Docs describe the intended system, not the one that ships |
| Contribution and release | How a request becomes a shared change; versioning; changelog; migration notes | Request history, changelog, package versions in each consuming product | Products stuck on old versions, or copies made while a request waited |
| Product use | Where teams import, copy, override or detach the shared component, and why | Figma detach data, a code scan, two real product surfaces, and a conversation with the teams | One family with a high rate of copies or overrides |
The last row is the one many checklists leave out, and it is the one that tells you whether the system is doing its job.
How to read a messy library
A detached instance, a copied component or a local override is an observation, not a diagnosis. In Figma, detaching an instance turns it into a plain frame that no longer receives updates from the main component, so a detach does mean that screen has left the system. It does not tell you why.
Some local work is supposed to exist. Brad Frost distinguishes shared components from recipes and snowflakes: product-specific compositions of system parts, and one-off components that are not reused beyond their first use. Treating every one of those as drift would push product-specific decisions into a shared library that should not own them.
For each divergence in your sample, separate what you saw from what caused it:
| What you see | Possible causes | Check before deciding |
|---|---|---|
| A product team copied a shared component | A missing state or behavior; an old version; a slow request path; a genuinely product-specific need | What the team asked for, and what stopped the shared route from meeting it |
| Figma and code disagree | One side is out of date; an agreed implementation adaptation; nobody decided which governs | Which definition is current, and whether the difference was intentional |
| Code matches Figma, but the product differs | The product runs an older version; local overrides; different content, theme or permissions | Which version the product actually imports, and under what conditions you observed it |
| Many near-duplicate components | Contributions that never merged back; unclear naming; missing variants | Whether the duplicates carry different meanings or the same meaning built twice |
| Accessibility fails in the product only | Composition, content or focus order introduced by the screen, not the component | Whether the fix belongs in the component, its guidance, or the product screen |
Each finding should end in one decision: fix the shared component, bring the product back in line, document the variation, migrate consumers to a newer version, retire the duplicate, change who owns it, or deliberately keep it local. Give each decision an owner and a way to confirm it worked. A single missing permission state in a table used across the product can matter more than dozens of small naming differences, so rank by consequence, not by count.
What usage numbers can and cannot tell you
Numbers help you choose where to look. None of them, on its own, tells you whether the system is healthy.
- Figma library analytics report component inserts, detaches and instances across teams and files, keep up to one year of history, and are available on Figma's Organization and Enterprise plans. A high detach count on one family is a good place to start interviewing.
- Code scans. Productboard described tracking component instances, deprecated usage and prop usage with the open-source react-scanner, and flagging off-system typography with custom lint rules. The same team found visual coverage hard to quantify, because a screen hardly ever used only system components, though still useful for spotting areas to improve.
- Rendered coverage. Mews marks elements rendered by system components and measures their share of all elements in production, partly because counting imports proved inaccurate when components were extended and re-exported internally. That is a strong signal of reach. It still cannot tell you whether a team copied a component because the shared one was missing a state.
- Automated accessibility checks. Storybook's accessibility addon is built on axe-core, and its documentation cites Deque's figure that automated checks catch up to 57% of issues. That figure comes from Deque's own 2021 analysis of its audit data, measured by volume of issues found. Read it as a vendor's best case: the rest needs manual keyboard and screen reader testing.
The pattern across all four: numbers find the hotspot, and the trace and a conversation with the team explain it.
What should you ask a design system audit provider?
Specialist design system consultancies, product design studios, UX audit agencies and tooling vendors all sell something called a design system audit, and the scope varies widely. Some review Figma files only and deliver a written report. Others add a code check and governance. Some score you against a maturity framework. None of these is wrong, but they answer different questions, so ask before you commission one:
- Will you look at code and a running product, or design files only? A files-only audit can find inventory problems. It cannot tell you whether the system is used.
- How will you choose the sample, and will you state what it does not cover?
- Will each finding name a cause and an owner, or only describe an inconsistency?
- How will you tell legitimate local variation from drift?
- Is accessibility checked in the implementation, by hand as well as automatically?
- What exactly do we receive? A score, a report, a ranked list of decisions, a migration sequence? Can our own team act on it without you?
- What do you need from us? Access to design files, code or Storybook, documentation, release history, product surfaces and the people who contribute.
What drives the size of an audit is mostly scope: how many component families, how many consuming products, whether code is in scope, and how quickly access to the sources and people can be arranged.
Tcules offers a Design System Audit built around the trace described here. It follows a repeated table, form, navigation or status problem through token meaning, Figma properties, coded behavior, documentation, release state and actual product use. It asks for Figma libraries, coded components or Storybook, documentation and release history, two representative product surfaces, and time with system and product contributors. It leaves a map of where shared decisions live, findings tied to product consequences, an ordered list of decisions and a sequence for rolling changes out, written so your system team can carry them out without Tcules. It does not center on a maturity score.
Where this work sits
If you want to run a single trace before involving anyone, the Design System Drift Checker walks you through recording one component's differences across design, code and product. The underlying condition has a name, design system drift, and most of the fixes it calls for are questions of design system governance: who owns shared decisions, and how a product team's need gets back into the system.
If the problem turns out to be less about the system and more about how the product works for its users, a UX product audit is the better starting point.