All writing

Design systems

Design system audit: the checklist I use, and how I run one

A design system audit answers one question: can the people building your product, and now the AI agents helping them, trust the system to give them the right answer? This is the checklist I use to find out. You can run most of it yourself.

Written by
Gideon Awolesi
Published
Reading time
8 min read

1. Inventory: what exists, and where

Start by listing every component in Figma and every component in the code, then match them up. The ones that only exist on one side, and the variants that don't match, are usually where most of the drift lives. Look in feature folders too, because that's where one-off components get written when nobody can find the right one.

2. Tokens and naming

Count how many colour and spacing values in the code don't come from a token. Then read the token names out loud and mark every one you can't place without context. Check that there's a semantic layer, so components use names like color.text.error and never reach straight for a raw palette value.

3. Accessibility of the components themselves

If accessibility is fixed in the components, every screen built from them gets it for free. If it isn't, every team fixes it separately, and some don't. Check contrast on the token pairs you actually use, visible focus states, touch target sizes, and that form components have real labels and error messages.

4. The connection between design and code

Check that designers can see what actually ships, and developers can find the source in one click. At Syndigo, I wrote the Code Connect and component files for all 200 components, and set up Storybook so you could see the design and the coded component side by side. That link is what keeps a library honest after launch.

5. Documentation and ownership

Look for two things. First, documentation people actually read: when to use a component, when not to, and an example. Second, a named owner and a clear way to contribute, so changes don't just happen in whichever file someone had open. A system without an owner slowly drifts, because keeping the file and the code in step isn't anyone's job.

6. Is it ready for AI coding agents?

This is the newest part of the checklist, and the one I see missing most often. When you ask your coding agent to build a screen, it reads your components and your docs to decide what to build. Check that component names are clear, the docs are in the repository where the agent can read them, and there's a short instruction file telling it to use the system. Otherwise, the agent writes new components, and every one of them is drift.

How to score it

I score each of the six sections from 0 to 3, so the total is out of 18. The number itself matters less than the list of findings behind it, but it gives the team something to measure against when they run the check again in six months.

AI-Ready Design System Audit

Want a second pair of eyes on your product?

I run this audit on your system in three weeks, from €4,500, and you get a scored report and a fix plan your team can work through. If you'd rather start small, send me one AI flow for a free review.