Back to blog

Design system audit: a checklist for whether your library is ready for AI agents

A design system audit for AI agents: seven checks you run in your own repo, each with the search that finds the problem and the fix.

Modeinspect

Design system audit: a checklist for whether your library is ready for AI agents

A design system audit for AI agents applies one test from our design system guide to every component. Could someone new to your codebase pick it from its name, props, exports and one example? A coding agent opens your repo knowing nothing else. The seven checks below each come with a search you can run in your own repo and the fix for what it finds.

Most audits look at the system the way a user sees it. This one looks at it the way an agent reads it, which is as files. It works for any React library, and the searches assume Tailwind and TypeScript. Building the system is covered in the guide to building a design system in code, and most checks link the step they come from.

Key takeaways

  • Audit the code, not the screenshots. A coding agent picks components from names, types, exports and examples, and never opens the Figma library.
  • Each check is a search: duplicate names, variants typed as string, missing exports, missing "when not to use" lines, decoy directories, dark: color classes, behaviors with no example.
  • Fix in order of what an agent copies most: duplicates and decoys first, then types and exports, then the docs.
  • A search finds candidates. A person who knows the product still decides which of two components is the real one.

What a design system audit checks when agents write the UI

The classic design system audit is an inventory. Brad Frost defines the method as "a comprehensive collection of the bits and pieces that make up your user interface" (Atomic Design, chapter 4). You screenshot every button, put them on one page and count the styles. The checklists that rank for the term, such as Ramotion's and Awesomic's, add accessibility, typography and documentation. They stay with what the interface looks like.

The audits that mention AI look at the Figma side. Figma's own AI audit page promises an agent that "scans your files for detached components, styling drift, and token misuse" (Figma). Those are design files. A coding agent working on your product reads the repo instead, and copies whatever it finds there.

If you own the design system, or you are the designer who cares most about it on a team of ten engineers, you may have run the screenshot audit already. You may have written a rules file too. Then a pull request arrived with StatusPill where Badge belonged, and nothing on your audit page explained why.

The audit that explains it runs where the agent works. Each check below is a search, a place to look and a fix.

Seven checks, each one a search you can run in your own repo.

  1. Duplicate componentsrg --files -g '*.tsx' componentsKeep the most-used copy, migrate the call sites, delete the rest.
  2. Variants typed as stringsrg -n "(variant|size|tone|intent)\??: string" componentsOne prop per decision, typed as a union of fixed options.
  3. Compound parts not exportedrg -U "^export \{[^}]*\}" components/uiExport every part, with one example of the whole tree.
  4. No “when not to use”rg --files-without-match -i "when not to use|\bnot for\b" components/ui -g '*.tsx'One line in the doc comment that names the alternative.
  5. Decoy directories and dead exportsnpx knipDelete what is unused. Label live legacy code in CLAUDE.md.
  6. dark: color classesrg -o "dark:\S*(bg|text|border|ring)-(white|black|[a-z]+-[0-9]{2,3})\b" components app | wc -lSemantic tokens that switch per mode, such as bg-surface.
  7. Behaviors with no examplerg -n '\bmultiple\b|\scollapsible\b|modal=\{false\}' app componentsOne named example per behavior, with a line on when to use it.

Searches use ripgrep (rg) from the repo root. Adjust the folder names to your layout.

Before you start: count what is used

You need a checkout of the repo and a search tool. rg is ripgrep, and your editor's project search can run most of the patterns.

Take a usage baseline first, so you know which fixes matter. react-scanner "statically analyzes the given code (TypeScript supported) and extracts React components and props usage" (react-scanner). Run it over your app folders and you get how often each component is used, and with which props.

That count is also the plainest measure of design system adoption. Brevo's engineering team tracked "the ratio of Indigo components to old frontend component library components", Indigo being their system (Brevo engineering). For a quick version, compare rg -o "<button\b" app | wc -l with rg -o "<Button\b" app | wc -l. Each raw element is a candidate for a component nobody found.

Check 1: duplicate components

Two components for one job mean an agent picks one of two. Alice Moore wrote on Builder.io's blog about what decides the pick: "the agent will pick whichever one happens to be closest to the file it's editing" (Builder.io).

Find it. List every component file with rg --files -g '*.tsx' components, then read the list for pairs that do one job: Badge and StatusPill, Modal and Dialog, Dropdown and Select. Search features/ and app/ too, where one-screen copies hide. The usage counts from your baseline show which copy the product actually depends on.

Fix it. Keep the most-used copy, move the call sites over and delete the rest. The order is in subtract before you add, the guide's first step.

Check 2: variants typed as strings

A variant typed as string accepts anything. The agent writes variant="brand", the build passes, and the button renders with none of the variant styles. The TypeScript handbook describes what a union of literals buys instead: "functions that only accept a certain set of known values" (TypeScript handbook).

Typed as a string, an invented variant compiles. Typed as a union, it fails the type check.

components/ui/button.tsx
type ButtonProps = {
variant?: string
}
app/settings/page.tsx
+<Button variant="primary">Save</Button>
+<Button variant="brand">Buy</Button>
+<Button variant="outline">Back</Button>
  1. Compiles. The button renders with none of the variant styles, so only a screenshot shows the mistake.
  2. Compiles too, and renders as unstyled as the line above.

Example. The two flagged lines are variants an agent made up. Switch the prop type to see which check catches them.

Find it. rg -n "(variant|size|tone|intent)\??: string" components lists the loose ones. Then look for booleans that combine, such as primary, ghost and danger on one Button. Two of them set at once is a state the design never had.

Fix it. Type every design decision as one prop with fixed options. If you style variants with cva, the cva docs say "cva offers the VariantProps helper to extract variant types" (cva), so the type and the styles cannot drift apart. Naming components so an agent can pick them is the other half of component API design.

Check 3: compound components with parts missing

Compound components only work as a set. In the patterns.dev definition, the pattern "allows you to create components that all work together to perform a task" (patterns.dev). An Accordion needs its Root, Item, Header, Trigger and Panel (Content in Radix and shadcn/ui). If your wrapper exports the Trigger and forgets the Panel, an agent cannot build the accordion from your library, so it builds its own.

Find it. Compare what each wrapper exports with the parts of the primitive it wraps. rg -U "^export \{[^}]*\}" components/ui prints each file's export block, including the multi-line ones. Radix and Base UI both list the parts in an Anatomy section on each component page. A wrapper may fold one part into another, as shadcn/ui's AccordionTrigger includes the Header. What matters is that every part a screen needs can be imported. Check Accordion, Dialog, Tabs, Select and Popover first.

Fix it. Export every part, and keep one example that shows the whole tree.

Check 4: no "when not to use"

Props say how to use a component. Only a sentence says when to use something else. The GOV.UK Design System gives it a heading on its component pages. Its details page says: "Do not use the details component to hide information that the majority of your users will need" (GOV.UK Design System).

Find it. rg --files-without-match -i "when not to use|\bnot for\b" components/ui -g '*.tsx' lists every component file without such a line.

Fix it. Add one line to each component's doc comment that names the alternative. For example: "Not for site navigation: use NavigationMenu." Putting instructions next to the code shows where that line lives. Writing the rest is its own job: documentation that people and agents both read.

Check 5: decoy directories and dead exports

A folder name reads as an instruction. To an agent searching for a component, a legacy/ folder that still compiles looks like the system. So does a design-system/ folder holding one old file, or an index that still exports OldModal.

An agent searching this repo for a modal finds four candidates. One of them is the system.

  • components/
  • ui/the system
  • dialog.tsx
  • index.tsstill exports OldModal
  • design-system/one file, from 2023
  • modal.tsx
  • legacy/still imported by two pages
  • Modal.jsx
  1. A dead export. knip lists it, and every import from components/ui offers it until it goes.
  2. A folder named after the system reads as the system. Move the file or delete the folder.
  3. Live legacy code. Keep it, and say in CLAUDE.md that new code must not copy it.

Example repo. knip lists the dead export. The two folders need a look by name.

Find it. knip "finds and fixes unused dependencies, exports and files" (knip), so npx knip lists the dead ones. Live decoys need a look by name: rg --files | rg -i "(^|/)(legacy|old|deprecated|design-?system)/" shows the files under folders that look retired, or that carry the system's name without being the system. Any of them may still be imported.

Fix it. Check each file knip reports, then delete it. For legacy code that has to stay, say so where the agent reads it. Anthropic's example rules file has the line: "src/legacy/ is still live but don't copy its patterns into new code" (Claude Code docs).

Check 6: dark: color classes in components

A dark: class is a pair someone has to remember. Tailwind's docs describe the variant as a way "to style your site differently when dark mode is enabled" (Tailwind CSS). That works one element at a time. An agent that sees bg-white dark:bg-zinc-900 in a component copies the pair, or forgets half of it.

Find it. rg -o "dark:\S*(bg|text|border|ring)-(white|black|[a-z]+-[0-9]{2,3})\b" components app | wc -l counts the ones set to a raw palette color, including stacked ones such as dark:hover:bg-zinc-800. Leave off | wc -l to see each one. shadcn/ui's own components use a few dark: classes on tokens, such as dark:bg-input/30, and the pattern skips those.

Fix it. Give each color a semantic token that switches per mode. In the shadcn/ui setup, "Dark mode works by overriding the same tokens inside a .dark selector" (shadcn/ui). Components then use bg-surface and never mention the mode. The three layers are in theming in tokens, never in components, and the tokens behind them are semantic tokens that switch per mode.

Check 7: behavioral variants with no example

A behavioral variant looks identical at rest. An accordion that allows several open panels, a dialog that is not modal and a collapsible sidebar look like their defaults. An agent learns them only from words and examples. Kyle Gach wrote on the Storybook blog: "Agents don't know anything about your components so they make up slop that doesn't match your coding standards" (Storybook).

Find it. Wrappers such as shadcn/ui's pass the primitive's props straight through, so the behavioral props may not appear in your files by name. Take them from the primitive's API reference, then search where they are set: rg -n '\bmultiple\b|\scollapsible\b|modal=\{false\}' app components. Expect a few hits from file inputs and plain text. A value the app sets but no story shows has no example.

Fix it. One named example per behavior, each with a one-line "use when", as in documenting behavior, not only looks. Storybook can also test the behavior. "Play functions are small snippets of code executed after the story renders" (Storybook docs). A story can open two panels and assert both stay open.

Examples have to render the real component, or they become decoys of their own. We hear the same thing on our calls with customers: most of the drift comes from Storybook components that no longer match what runs in production.

What to do with the results

Fix in the order an agent copies. Duplicates and decoys come first, because every new screen inherits them. Types come next, because each fix turns a class of mistakes into a type error. Exports follow, because every missing part is a component the agent rebuilds. Docs and examples come last, since they only help once the component they describe is the only one.

A search finds candidates, not verdicts. A Badge renamed StatusPill matches no pattern, and only someone who knows the product can say which of two dropdowns is current. No script can tell you whether a "when not to use" line is right, either.

Whatever keeps coming back belongs in lint, not in the next audit. How to turn a check into a rule that fails the build is in enforcing design system rules on AI-generated code. Who may change card.tsx once the library is clean is a separate decision, part of governing a design system when agents write the UI.

Tools that work on the codebase pick from the same exports and props. Modeinspect, for Next.js React codebases that use Tailwind, finds a team's React components after setup, and designers edit their props on the canvas. Its design panel offers your Tailwind theme's tokens without enforcing them.

Start with the two counts that take a minute: dark: color classes, and raw <button> elements against <Button>. Write both numbers in the description of your first fix's pull request. Then run the same two searches a month later.

Frequently asked questions

What is a design system audit?

A design system audit is a review of what a design system contains and how well it is used. The classic version is an interface inventory: a collection of every button, form field and color in the product, sorted to find duplicates. For a team whose UI is partly written by coding agents, the audit also checks the code: names, typed props, exports, examples and folders an agent can copy from.

How do you audit an existing design system?

Start with a usage count, so you know which components the product depends on. Then run one check at a time. Look for duplicates, loosely typed variants, compound components with missing exports and components with no "when not to use" line. Then check decoy directories, dark: color classes and behaviors without an example. Fix duplicates and decoys first.

What should a design system audit checklist cover?

For a library that coding agents use, cover the seven checks in this post. Start with duplicates, variants typed as strings, compound parts not exported and missing "when not to use" guidance. Then cover decoy directories and dead exports, dark: color classes, and behavioral variants with no example. Add accessibility and visual consistency if you also audit what users see.

How often should you audit a design system?

Run the full checklist once, then turn what keeps coming back into lint rules so the build catches it. After that, a short pass each quarter, or after a large migration, catches new duplicates and decoys. The two quickest counts (dark: color classes, and raw <button> elements against <Button>) are worth running monthly.

What is an AI-powered design system?

The phrase usually means a design system that AI tools can read and use well, or one maintained with AI help. In practice it means components an agent can import, a theme that offers only the system's tokens, and checks that reject off-system code. The audit in this post is how you find out how far a library is from that. The enforcement side is covered in AI and design systems.

What are compound components?

Compound components are sets of parts that work together as one component, such as an Accordion made of Root, Item, Header, Trigger and Panel. The parent holds the shared state, and each part renders one piece. In a design system, every part has to be exported, or anyone building with the library, agent or person, cannot assemble the whole.

How do you measure design system adoption?

Count how often the product uses system components compared with custom components or raw HTML elements. react-scanner reports component and prop usage across a codebase, and Omlet "tracks design system adoption across all your projects". A quick version is comparing how many raw <button> elements and how many <Button> components your app folders contain.

What is component API design?

Component API design is choosing the names, props and parts a component exposes. For a design system that agents use, it starts with a name that says what the component is and one typed prop per design decision. Every part of a compound component is exported, and one example shows the parts together.