You open your Figma library and there are 600 variables. Some are used everywhere. Some haven’t been touched in months. A few have names that only the person who made them understands. Is this a design system, or a pile of tokens that grew without a plan?
Most audits check the tokens and stop there. That covers 1 dimension out of 6. Here’s the full playbook, in the order I run it, with a prompt you can copy at the end.
The 6 dimensions of a design system audit
Design tokens and variables
Start here, because everything else sits on top of it. Sort your variables into primitives, semantic tokens, and theme tokens. Check the naming convention is consistent. Confirm your modes are set up properly. Then find the dead and duplicate tokens, the ones with zero real usage, and remove them once you’ve verified nothing breaks. Most systems carry a surprising amount of weight nobody uses.
Component architecture in Figma
Now the components. Are your variants and props consistent across the set, or has every designer added their own? Look for duplicate components doing the same job. Check that components are built from your tokens, with no hardcoded values. And find the detached instances, the places where someone broke away from the system and never came back.
Accessibility audit
The dimension most audits skip. Check contrast ratios against WCAG AA. Check focus indicators are visible. Check target sizes are big enough to tap. Check every state is visible, including hover, focus, disabled, and error. Give each a clear pass or fail.
Design-to-code token parity
This is where you bring in your developer. The goal is simple: the names and values in your Figma file should match the tokens your developers ship, whether that’s a shadcn theme, Tailwind tokens, or your own setup. When design and code use different names for the same thing, every handoff turns into a translation job. One meeting and one shared token file usually closes most of the gap.
Design system documentation
The boring part, and the part that pays off later. Every token and every component should have a description and a when-to-use note. Do that, and a new designer or developer can pick up your system without booking time with you to explain it. This is the kind of repetitive writing an AI tool handles well, so it’s worth handing over.
Governance and publishing
The hardest dimension, and the one that keeps a system alive after launch. How do you version it? What’s published versus hidden? How is the library structured? How do you track adoption? What happens when you deprecate something, and who owns the whole thing? Most systems never get this far. The ones that do are the ones still standing in 2 years.
How to prioritize your design system audit
The reason audits stall is that people try to fix everything at once. 600 variables, no idea where to begin. Splitting the work into 6 dimensions solves that. You pick one, finish it, then move on. I start with tokens because every other dimension depends on them. You don’t need to complete all 6 in one sitting. You need to know which one you’re working on and why.
Why your audit should live in a single file
An audit that lives in a PDF is out of date the moment you close the file. Mine lives in a single HTML file I can open in a browser. It shows the status of all 6 dimensions, the findings, and a log of every decision with the reason behind it. Every session updates it, so future-me or the client can open it any time and see exactly where things stand, and never has to ask why a token was deleted 6 weeks ago. (That decisions log settles more arguments than anything else in the file.)
The AI prompt to audit your design system
Here’s the prompt I use. Copy it, give it your Figma file and your code’s token file, and run it in Claude Code or your AI tool of choice. It runs the 6 dimensions in order, verifies against your real files instead of guessing, only deletes what’s safe to delete, logs every decision, and builds you the same living dashboard.
You are my design system audit partner. We will audit my design system in Figma across 6 dimensions, one at a time, and keep a living record of every decision.
Context I will give you:
- My Figma library file, connected through Dev Mode and the Figma MCP, so you read the real variables and components instead of guessing.
- My code source of truth: the CSS or token file my developers actually ship (for example a shadcn or Tailwind theme file).
Rules you must follow:
1. Verify against the live Figma file and the real code. Never work from memory.
2. Audit one dimension at a time. Finish it before starting the next.
3. Only delete a token after you confirm zero usage everywhere (components, example files, and archived pages). If you cannot confirm zero usage, flag it for a decision instead of deleting.
4. Rename binding-safe. A rename must never break an existing binding. If it would, stop and tell me.
5. Log every decision with a one-line reason, so anyone can later see why we did it.
The 6 dimensions, in this order:
1. Tokens and variables: primitive vs semantic vs theme, naming, modes, dead and duplicate tokens, real usage.
2. Component architecture: variant and prop consistency, duplicate components, components built from tokens (no hardcoded values), detached instances, naming.
3. Accessibility: contrast ratios against WCAG AA, focus indicators, target sizes, state visibility. Give a measurable pass or fail per check.
4. Design and code parity: do my Figma names and values match the real tokens in my code file? List every mismatch, every code-only token, every Figma-only token.
5. Documentation: does each token and component have a description and a when-to-use note, so a new designer or developer can self-serve?
6. Governance and publishing: versioning, published vs hidden, library structure, adoption, a deprecation process, and ownership.
Output:
- For the dimension we are on, give me: findings with a severity (high, medium, low), a recommendation per finding, and the effort involved.
- Maintain one HTML dashboard file showing the status of all 6 dimensions, the findings, and the decisions log. After each session, update it and tell me what changed.
- When I say "resume the audit" in a new session, read the HTML dashboard first and tell me exactly where we are before doing anything.
Start with dimension 1. Ask me for my Figma file and my code file, then begin.
Split the work into 6 dimensions, write down every decision, and the audit stops being the job you keep putting off. You open the file and do the next one.
