How to Audit Design Tokens Before Dev Handoff
For Product designers preparing developer handoff · Based on UI Collective AI Design System Audit Workflow
// TL;DR
If you're a product designer prepping a Figma file for engineering, this workflow lets you audit every design token — surfaces, borders, text, icons — with one Cursor command instead of clicking through each element. You teach Cursor your token rules once via a Project Rule, then run '@check variables' on any frame or component. It returns a line-by-line list of wrong token types, hard-coded hex values, and the correct token to apply. Use it right before handoff to ship clean, consistent designs and eliminate token-related back-and-forth with developers.
Why do token errors slip through before handoff?
On a real SaaS dashboard with 20+ components across three surface layers, manually verifying every element's token usage is exhausting and unreliable. It's easy to miss a card subtitle using a border token instead of `text-secondary`, or a footer background hard-coded to `#F4F4F4` instead of `surface-default`. These slip through into developer handoff, where they become bug tickets, inconsistent implementations, and rework. The UI Collective AI Design System Audit Workflow catches these before they leave your hands.
How does the audit actually work?
The workflow treats AI as a Design System Assistant — not a builder, but an analytical reviewer that reads your token rules and flags misapplications. You start by connecting the Figma MCP server to Cursor, which lets the AI read your file's component structures and variable assignments directly. Then you generate a Cursor Project Rule from your Design Token Table — a Figma table with token name, light value, dark value, and a usage description. This teaches the AI your token logic once.
Next you build a reusable `@check variables` command. It's structured to determine whether the link is a page or component, examine the whole UI (page color, surfaces, borders, text colors, icon colors, and crucially secondary and tertiary components), review each variable against its actual usage context, and output one line per issue — or confirm 'All variables applied correctly.'
What does a real audit return?
When you select your dashboard frame in Figma, copy the link, type `@check variables` in Cursor, and paste the URL, you get results like:
- Card subtitle text is using a border-subtle token — should use text-secondary.
- Footer background is a hard-coded hex #F4F4F4 — should use surface-default.
You resolve each flagged issue, re-run the command, and confirm a clean audit before handoff. The line-by-line format means no guesswork — the AI names both the problem and the correct replacement token.
How do I avoid noisy or inaccurate results?
Follow Simplify Before You Scale: don't feed the AI your entire library at once. Scope to a specific frame, component, or dashboard section. Make sure your command explicitly lists secondary and tertiary components — nested helper text, badges, and status indicators are where token errors hide most often. And remember you need foundational knowledge of design tokens yourself: the AI checks against rules you define, so you must recognize whether its flags are correct.
What should I never rely on AI to do here?
Don't use tools claiming to 'build designs with your actual design system components.' They recreate elements as groups using your styles, not real component instances with auto layout — you'll rebuild from scratch anyway. Keep AI in its lane as a reviewer. The value is in the audit, not the build.
Next step
Create your Design Token Table in Figma if you don't have one, install Cursor, connect the Figma MCP server, and generate your first Project Rule. Then build the `@check variables` command and run it on a single dashboard frame. Once you trust the output on a narrow scope, make it a standard pre-handoff step for every screen.
// FREQUENTLY ASKED QUESTIONS
Will this catch hard-coded hex values, not just wrong tokens?
Yes — the '@check variables' command identifies both wrong token types applied to elements (like a border variable on text) and missing variables such as a hard-coded hex on a border instead of a border token. It also names the specific correct token that should be applied, so you can fix each issue directly.
How long does an audit take on a large dashboard?
Once your Project Rule and command are set up, an audit is a single command invocation — you paste the Figma link and get a line-by-line issues list back. The setup takes longer the first time, but every subsequent audit on any frame is fast, replacing manual element-by-element inspection entirely.
Do I need to re-run the audit after fixing issues?
Yes — resolve each flagged issue, then re-run '@check variables' to confirm a clean result before handoff. The command will state 'All variables applied correctly' when nothing is wrong, giving you a verified checkpoint before passing the design to engineering.