Frequently Asked Questions About UI Collective AI Design System Audit Workflow
21 answers covering everything from basics to advanced usage.
// Basics
What exactly does the 'check variables' command look for?
The command first determines whether the link is a page or component, then examines the UI as a whole — page color, all surfaces, borders, text colors, icon colors, and secondary or tertiary components. It cross-references surface variables against surfaces, border variables against borders, and so on. It then outputs one line per issue identifying wrong token types, missing variables, and the correct token to apply.
What is the Design Token Table and how should I structure it?
The Design Token Table is a Figma table with four columns: token name, light mode value, dark mode value, and a plain-language description of when each token should be applied. It's the source of truth from which Cursor generates its Project Rule. Without it, the AI has no rules to check against, so create one before starting the workflow.
Why does the workflow treat AI as an assistant instead of a builder?
Because AI reliably reads token rules and flags misapplications, but fails at building real component instances. Tools that claim to build with your design system recreate elements as groups, not true instances with auto layout, forcing you to rebuild from scratch. Framing AI as a 'Design System Assistant' — an analytical reviewer — plays to its actual strengths and avoids wasted rework.
What foundational knowledge do I need before starting?
You need a working understanding of design tokens and Figma variables — what surface, border, text, and icon tokens are and when each applies. The AI checks against rules you define, so you must recognize correct usage to write good rules and validate output. Without this foundation, you can't tell whether the AI's flags are right.
// How To
How do I set up the Figma MCP connection in Cursor?
Install Cursor from cursor.com, go to the Figma MCP catalog, hit 'Add MCP to Cursor', open Cursor when prompted, install the MCP server, then hit Connect > Agree > Allow Access. Confirm the server shows a connected badge and the switch is on. If it shows a loading state, delete and reconnect — connection should be instant.
How do I generate a Cursor Project Rule from my token table?
Copy the Figma link to your token table, open a new Cursor chat, and paste the link with a prompt like: 'Check the following Figma link and build me a Cursor project rule focused on the design variables and when they should be applied.' Review the generated rule — it should list each token, its value, and usage context. Enrich descriptions if too high-level and delete any unrequested outputs like auto-generated CSS.
How do I write the 'check variables' command properly?
In Cursor Settings > Rules and Commands, add a Project Command named 'check variables'. Structure it in steps: determine if the link is a page or component; examine the whole UI including surfaces, borders, text, icons, and secondary components; review variables in context against their usage; then call out issues one line each, or state 'All variables applied correctly.' Run the draft through an AI editor to clean formatting before saving.
How do I invoke a command on a specific Figma selection?
In Figma, select the exact component, page section, or dashboard you want, then copy the link to that selection specifically. In Cursor, type '@check variables' or '@generate documentation' to invoke the command, then paste the Figma URL. The command uses your Project Rule to analyze that scoped selection and return results.
// Troubleshooting
My MCP server shows a loading state instead of connected — what do I do?
Delete and reconnect the MCP server. A proper connection is instant, so a persistent loading state indicates a failed connection. Repeat the setup: Add MCP to Cursor, install, then Connect > Agree > Allow Access, and confirm the connected badge appears and the switch is on before proceeding.
The AI generated CSS files I didn't ask for — is that normal?
Yes, Cursor sometimes produces unrequested outputs like auto-generated CSS when building a Project Rule. Delete anything you didn't ask for and keep only the rule listing tokens, values, and usage contexts. Review the rule to ensure it's focused strictly on variable logic and enrich descriptions if they feel too high-level.
The documentation output includes assumptions stated as fact — how do I fix that?
Update your 'design system documentation' Project Rule to explicitly instruct the AI to confirm assumptions rather than state them as fact. Then always audit the output before using it. If the AI needs to assume something about a component's purpose or usage, it should flag it for confirmation instead of presenting it as verified.
The audit missed token errors in nested helper text and badges — why?
The AI likely over-focused on primary elements. Ensure your 'check variables' command explicitly lists secondary and tertiary components — helper text, badges, status indicators nested within cards — as items to review. This directive prevents the AI from ignoring supporting components where token errors commonly hide.
// Comparisons
How does this compare to manually checking every element in Figma?
Manual checking on a 20+ component dashboard across three surface layers is slow and error-prone, especially for nested elements. This workflow returns a line-by-line issues list in one command — flagging wrong token types, hard-coded hexes, and the correct replacement tokens. You resolve flagged issues and re-run for a clean audit, dramatically reducing handoff prep time.
How does this compare to Figma Make or similar design-building tools?
Figma Make and similar tools attempt to build production Figma files but fail to properly apply variables and text styles, and replace auto layout with fixed-width frames and arbitrary padding. This workflow doesn't build anything — it audits existing designs and documents them. It plays to AI's analytical strengths rather than its unreliable building capabilities.
Is this better than building a token library from scratch with AI?
Yes, for this use case. Building a variable library entirely from scratch with AI requires foundational token knowledge, considerable iteration, and high-level input to get anything accurate. This workflow assumes you already have a token table and uses AI to enforce and document it — a far more reliable application of AI in design systems.
// Advanced
How do I feed generated documentation into ZeroHeight or Supernova?
Run '@generate documentation' on a scoped selection, review the returned markdown covering variants, states, props, and accessibility, then use it as structured input in your documentation platform. Supplement with annotated screenshots and dialogue with the AI to expand or tighten sections. Treat it as a first draft you refine, not a finished paste-in.
Can I audit existing documentation for gaps with this workflow?
Yes — even if you already have documentation, run the 'Generate Documentation' command to check for missing elements, incorrect usage guidelines, or gaps. Compare the AI's structured output against your current docs to surface omissions in states, accessibility notes, or when-not-to-use guidance that manual writing often skips.
How narrow should my component scope be for the documentation command?
Very narrow — start with one or two related variants rather than all of them. For a button with six variants, select just the primary and secondary variants first. Feeding the entire set at once produces errors and noise. Once you validate output quality on a small scope, expand incrementally following the 'Simplify Before You Scale' principle.
What sections should generated component documentation include?
The 'generate documentation' command produces: Name, Purpose, When to Use, When Not to Use, Properties, Accessibility Guidelines, and Notes. It documents what exists using plain language, avoids internal jargon unless provided, doesn't introduce new components or rules, and stays short — clarity over completeness. One markdown section per item, no opinions or unconfirmed assumptions.
Why should documentation prioritize clarity over completeness?
Because over-explaining theory and internal jargon slows down the developers and designers who consume the docs. The principle 'Clarity Over Completeness' means keeping documentation short and plain-language. Developers write developer content; designers write usage and accessibility guidelines. The AI first draft should be concise and role-appropriate, not an exhaustive theory dump.
Can I reuse these rules and commands across multiple projects?
Project Rules and Commands live in Cursor and are reusable — that's the point of separating teaching from doing. Once you've built a token rule and 'check variables' command, you invoke them on any Figma link. For a new design system with different tokens, regenerate the Project Rule from that system's token table while keeping the command structure.