How to Audit a Design System for Inconsistencies

Last updated: November 01, 2026

Quick Answer: A design system audit usually starts with 1 fixed inventory and ends with 1 ranked cleanup list. It is a structured check for where components, tokens, accessibility rules, and documentation no longer match each other. In How to Audit a Design System for Inconsistencies, the goal is to find those mismatches before they spread across apps.

Key takeaways

• Start with a fixed inventory, or the audit turns into opinions about screenshots.
• Compare real usage against the documented system, not against a hoped-for future state.
• The biggest wins often come from duplicate components, token drift, and missing guidance.
• Accessibility gaps often hide in variants, states, and content patterns, not only in the base component.
• An audit is only useful if it ends with a ranked cleanup list and an owner for each fix.

What a design system audit actually checks

A design system audit checks whether the system is still one system in practice. It looks for places where components have forked, tokens no longer map cleanly to the source of truth, accessibility rules are skipped, and documentation no longer tells the truth.

That matters because inconsistency usually arrives quietly. One team adds a new button variant for a campaign page. Another copies a card and changes the spacing by 4 px. A third updates the code but not the docs. By the time someone notices, there are five versions of the same pattern in production and no clear owner for the cleanup.

A useful audit is not a brand review and not a visual polish pass. It is a diagnostic. The goal is to answer three questions:

1. What exists?
2. What is duplicated, drifted, or missing?
3. What should be fixed first?

I would not use this process for a brand-new system that has only a handful of components and no production usage yet. In that case, you need creation work, not audit work. This method is for an existing design system with real product surfaces, usually across at least 2 codebases or product areas.

A design system audit also has a scope boundary. It should cover the system’s components, tokens, accessibility, and documentation. It should not try to solve atomic design theory or define how to build the system from scratch. If the audit starts turning into a rearchitecture project, it has gone too far.

For teams that need the operational side after this review, the next stop is the Design System Operations hub, which should sit beside the audit rather than inside it.

What do I need before I start the audit?

You need a complete inventory, a way to inspect the code and the UI, and one person who can decide what counts as the source of truth.

At minimum, gather these before you begin:

• The component library or design system repository
• A token file or token registry, if one exists
• Current documentation pages or Figma library pages
• A list of product surfaces using the system
• Access to a browser, the component catalog, and the codebase
• A working spreadsheet or issue tracker for findings

If there is a changelog, include it. If there is a release branch or package version, record that too. Even a simple audit benefits from a known snapshot date, such as “library version 3.8” or “docs last updated March 2026.” Without that anchor, findings drift as the system changes under you.

I also recommend setting the audit scope in plain language before you inspect anything. Example: “Review buttons, form fields, alerts, cards, and navigation across the main web app and the marketing site.” That sentence keeps the audit from ballooning into every edge case in the product.

The main trade-off is breadth versus depth. A wide audit covers more surface area but may only catch obvious inconsistencies. A narrow audit can go deep enough to expose token drift and accessibility problems, but it will miss patterns outside the chosen set. If the system is large, start with the top 10 to 15 components by usage, then expand.

One thing not to do: start with screenshots only. Screenshots are useful, but they hide structure. A component may look consistent in one state while using a different token set, different content rules, or a different accessibility label under the hood.

How do I audit the design system step by step?

You audit it by inventorying the system, comparing source-of-truth files to live usage, and logging each inconsistency in one place.

1. List every component, token set, and doc page in scope. Use a spreadsheet or issue tracker with 4 columns: item name, source, usage location, and status. When this works, you have a single map instead of scattered notes.
2. Compare the design files to the code implementation. Check whether the named component in Figma or the library matches the exported component in code, including props, states, and variants. When this works, each component has one clear counterpart rather than two almost-identical versions.
3. Open the product surfaces and sample each component in context. Inspect at least the default state, hover, focus, disabled, error, and empty state if those exist. When this works, you can see where the system breaks outside the component catalog.
4. Check tokens against what ships in the UI. Compare spacing, color, typography, radius, and elevation tokens to rendered values in the browser. When this works, repeated values line up with the token source instead of hard-coded one-offs.
5. Review accessibility against the same set of components. Check keyboard focus, visible focus indicators, contrast, labels, error messaging, and state announcements where relevant. When this works, the component is usable, not just styled correctly.
6. Read the documentation against the implementation. Look for missing usage notes, outdated screenshots, and examples that no longer match the code. When this works, a designer or developer can rely on the page without double-checking in Slack.
7. Rank each issue by impact and spread. Mark whether it affects one component, one product, or the whole system, and whether it blocks shipping or only creates noise. When this works, the team knows what to fix first instead of arguing over the loudest bug.

Keep the notes concrete. Write “button secondary variant uses 12 px padding in app A and 16 px in app B” rather than “inconsistent button spacing.” Specific notes are easier to route to the right owner and easier to verify later.

A good audit does not try to fix everything on the spot. It produces a repair list. That list usually includes quick wins, such as duplicate docs or broken examples, and deeper work, such as collapsing duplicated components into one API.

Where do duplicate components usually hide?

Duplicate components usually hide in copied variants, product-specific forks, and “temporary” fixes that never got removed.

The easiest way to find them is to compare names, props, and rendered output across the component catalog and the production app. If you have a button called PrimaryButton and another called CTAButton, inspect whether they differ in behavior or only in naming. If two components share the same visual job but accept different prop shapes, that is a likely fork.

Look closely at areas where teams move fast:

• Marketing pages that needed a special hero or CTA
• Form patterns adjusted for one business unit
• Legacy code that pre-dates the current library
• “One-off” components built for a deadline
• Components with names like NewCard, CardV2, or CardBeta

The cost of duplicates is not just visual inconsistency. Duplicates split maintenance, so fixes land in one place and miss the other. They also confuse adoption, because teams do not know which component is blessed. Over time, that creates shadow systems.

When a duplicate is found, do not delete it immediately unless you know every usage. First mark whether it is a true duplicate, a partial duplicate with one important behavior difference, or a separate pattern that should be named honestly. A quick merge can break real usage if the component still carries a hidden requirement, such as different content density or a special keyboard interaction.

The right move is often to consolidate under one base component and keep only the variant states that are genuinely different. If the difference is only visual and the code path is otherwise the same, the system is usually healthier with one component and a documented variant. If the difference is semantic or behavioral, it may need to remain separate.

A useful indicator: if the team cannot explain in one sentence why both components exist, the duplication probably needs cleanup.

How do you spot token drift?

You spot token drift by comparing the token source to what the browser actually renders and looking for values that have escaped the token system.

Token drift shows up when a token exists in the design file or token registry, but the UI uses a hard-coded value, an older token, or a local override. A card may use the correct color token but a rogue 6 px padding value. A text style may still look right while pulling from a deprecated font size. The system appears stable until the changes start compounding.

Check the common token families one by one:

• Color tokens: surfaces, text, borders, feedback states
• Spacing tokens: padding, margin, gaps, layout offsets
• Typography tokens: font family, size, line height, weight
• Radius and elevation tokens
• Motion tokens, if the system uses them

Use one simple test: open a component in the browser and compare the computed styles to the token names you expect. If the UI uses --space-200 in one place and a raw 14px in another, that is drift. If the design file says one token and the code references another, that is drift too.

A common mistake is to audit only the canonical component. Token drift often appears in variants, states, and wrappers. A button may be clean in its default mode but use a separate spacing value in its loading state. A form field may respect the border token until an error state swaps in a hard-coded red.

This part of the audit usually exposes the most boring but costly fixes. The work is not glamorous, but it reduces future inconsistency more than almost anything else. Once drift is found, the repair path is usually to remove local overrides, map old values to the current token set, and retire unused tokens only after confirming they are not still in production.

If the system has a token catalog, record which tokens are live, which are deprecated, and which are never used. Even a small count of stale values can explain a lot of visual noise.

What accessibility checks belong in the audit?

Accessibility checks belong in the audit because inconsistent components often break keyboard use, labels, or contrast before anyone notices a visual problem.

I would check every audited component for the same baseline set: keyboard focus, visible focus state, color contrast, label association, error text, and state communication. If the component has menus, dialogs, tabs, or form controls, verify the expected interaction model as well. The relevant standard to align with is WCAG 2.2, not as a branding badge, but as a practical checklist for visible and operable behavior.

Start with focus. If you tab through the component in the browser and cannot see where focus moved, the component is not audit-ready. Then check whether the interaction still works without a mouse. A dropdown that opens only on click but not via keyboard is a system defect, not an isolated UI annoyance.

The audit should also check states, because accessibility problems often hide there. Disabled states need to communicate status clearly. Error states need text, not color alone. Icon-only buttons need names that screen readers can announce. If the documentation says a pattern supports assistive tech but the implementation leaves the accessible name blank, note the mismatch directly.

Do not stop at the component shell. Inspect the content inside it. Long labels, truncation, helper text, and validation messages can make an otherwise correct component unusable. If a form field looks fine at one line but breaks when the label wraps to two lines, the audit should catch that.

This is one area where I would not recommend guessing. If the team is uncertain how a specific ARIA pattern should behave, the audit should record the uncertainty and route it to someone who knows the pattern well. Accessibility mistakes can become persistent if they are normalized in the system.

Where do documentation gaps matter most?

Documentation gaps matter most where people choose between two similar components, need state behavior, or need to know what not to do.

The docs are failing if a designer or developer has to ask in chat whether a component supports icons, how it behaves in error mode, or which prop controls density. The system may still work, but adoption slows because people do not trust the page.

Look for five common gaps:

• Missing examples of real usage
• Screenshots that no longer match the component
• No guidance on when to use one variant over another
• No note about accessibility behavior or requirements
• No mention of deprecated props, tokens, or patterns

A good documentation check compares the page to the live component, not just to another page in the library. If the code changed in the last release but the example still shows the old prop name, the docs are lying by omission. If a component has three variants and the docs show only one, users will invent the rest.

The cost of bad documentation is broader than annoyance. It creates inconsistency downstream because teams improvise. They copy a similar component, guess at usage, or build a local workaround. That is how a system gains duplicates even when the base library is technically available.

The fix is usually not a long rewrite. Often it is a set of targeted repairs: update the prop table, replace stale screenshots, add “use this when / do not use this when,” and note any accessibility constraints. If a component has been deprecated, the docs should say so plainly and point to the replacement.

A practical audit output is a three-part list: what to fix in code, what to fix in design files, and what to fix in documentation. That separation keeps the cleanup work from getting stuck in one team’s queue.

How should I turn audit findings into cleanup work?

You should turn audit findings into cleanup work by grouping issues by impact, assigning owners, and setting the order of repairs before the list gets longer.

A useful final pass is to sort findings into three buckets:

1. System-wide issues, such as token drift or a broken core component
2. Component-level issues, such as a duplicated button or missing state
3. Documentation issues, such as outdated examples or unclear guidance

Then assign each item to one owner and one release window. A finding without an owner tends to stay open. A finding without a timeline tends to slip behind new work. If you have 20 findings and no ranking, the audit has created noise instead of progress.

It also helps to label each fix as quick, medium, or large. A quick fix might take less than a day. A medium fix may need coordinated design and code changes. A large fix may require a migration plan. Those labels make the cleanup list easier to schedule.

If possible, include a short “done” definition for each issue. For example: “Button variants use one token source, one prop API, and one doc page.” That sentence gives the team a finish line and makes it easier to verify the repair later.

The audit is complete when the team can answer three questions without hesitation: what is inconsistent, what should be fixed first, and who owns the next step. At that point, the system is no longer being guessed at.

Drafted with AI; not yet reviewed by a person.