UI Collective AI Design System Audit Workflow

Last updated: 29 August 2026

Systematically catch incorrect design token usage and auto-generate component documentation using Cursor + Figma MCP — without re-examining every element by hand.

// TL;DR

The UI Collective AI Design System Audit Workflow is a Cursor + Figma MCP method for catching incorrect or missing design token usage and generating first-draft component documentation — without manually inspecting every element. You teach Cursor your token logic once via a Project Rule, then invoke reusable Commands ('@check variables' and '@generate documentation') on any Figma link. Use it before developer handoff to audit variable usage across dashboards and components, or when you need structured documentation for buttons, variants, and modules. It treats AI as a design system reviewer, not a builder.

Framework

// When should you use the AI Design System Audit Workflow?

Use this skill whenever you need to audit a Figma design or component for incorrect or missing variable usage before developer handoff, or when you need to generate first-draft design system documentation for components, variants, or modules.

// What do you need before running this design system audit?

Figma File / Component Linkrequired
A Figma URL pointing to the specific page, component, or selection you want audited or documented.
Design Token Table (Figma)required
A Figma table listing token name, light mode value, dark mode value, and a plain-language description of when each token should be used.
Cursor (installed + signed in)required
The Cursor AI code editor, downloaded from cursor.com, used as the AI interface throughout this workflow.
Figma MCP Server (connected to Cursor)required
The Figma MCP integration that allows Cursor to read Figma file contents directly via a shared link.
Component Scope
A defined, simplified selection of components or variants to audit or document — not the entire design system at once.

// What core principles guide this AI design system workflow?

AI as Design System Assistant

Treat AI not as a builder of components or designs, but as a mini design system assistant — one that reads your tokens, understands their rules, and flags where they are applied incorrectly or missing entirely.

Rules Teach, Commands Execute

A Cursor Project Rule teaches the AI your design system's token logic once. A reusable Command then calls that knowledge on demand for any Figma link. Separate the teaching step from the doing step.

Document What Exists, Not What Could Exist

When generating documentation, instruct AI only to describe the provided component or token — not to introduce new components, new rules, or design opinions. Confirm assumptions before accepting them.

Simplify Before You Scale

Select a specific, simplified set of components or variants before running any AI command. Feeding AI an entire component library at once produces mistakes and noise. Start narrow, then expand.

Clarity Over Completeness

Generated documentation should use plain language and be short. Avoid internal jargon and over-explaining theory. Developers write developer content; designers write usage and accessibility guidelines.

Don't Trust 'Builds With Your Design System' Claims

Any tool claiming to build Figma designs using your actual design system components currently uses your styles but recreates elements as groups — not as real component instances with proper auto layout. You will spend more time fixing the output than building from scratch.

// How do you run the AI design system audit step by step?

1
Set up Cursor + Figma MCP connection
Install Cursor from cursor.com. Navigate 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 MCP server shows a connected badge and the switch is on. If it shows loading, delete and reconnect — connection should be instant.
2
Prepare your Design Token Table in Figma
Ensure you have a Figma table with four columns: token name, light mode value, dark mode value, and a plain-language description of when that token should be applied. This table is the source of truth AI will learn from. If you do not have one, create it before proceeding.
3
Generate a Cursor Project Rule from your token table
Copy the Figma link to your token table. In Cursor, open a new chat and paste the link with a prompt such as: 'Check the following Figma link and build me a Cursor project rule focused on the design variables / design tokens and when they should be applied.' Review the generated rule — it should list each token, its value, and its usage context. Optionally enrich descriptions if the rule feels too high-level. Delete any unrequested outputs (e.g. auto-generated CSS files).
4
Create the reusable 'Check Variables' command
In Cursor Settings > Rules and Commands, add a new Project Command named 'check variables' (no hashtag). Write the command with these steps: (1) Determine whether the shared Figma link is a page, a component, or something else. (2) Look at the UI or component as a whole — identify page color, all surfaces, all borders, all text colors, all icon colors, and any secondary or tertiary components. (3) Review variables in context — check surface variables against surface usage, border variables against border usage, text variables against text usage, icon variables against icon usage. (4) Call out what is wrong: one line per issue; if nothing is wrong, state 'All variables applied correctly.' Run the raw draft through an AI editor (e.g. ChatGPT) to clean up formatting before saving.
5
Run the 'Check Variables' audit on a design
In Figma, select the component, page section, or dashboard you want to audit and copy the link to that selection. In Cursor, type '@check variables' to invoke the command, then paste the Figma URL. The command uses the Project Rule to identify: wrong token type applied to an element (e.g. a border variable on text), missing variables (e.g. a hard-coded hex on a border instead of a border token), and the specific correct token that should be applied instead. Review issues line by line before developer handoff.
6
Create the reusable 'Generate Documentation' rule and command
In Cursor Settings > Rules, create a new Project Rule named 'design system documentation'. Include these directives: goal is to document what exists, not redesign or expand; only reference provided components or Figma links; use plain language describing what the component is, where it is used, and why it exists; do not introduce new components or rules; if assumptions are needed, confirm them rather than stating them as fact; do not over-explain theory; consider accessibility and usage guidelines. Then in Commands, create a 'generate documentation' command with these steps: (1) Identify what is being documented — component, variant, module, page. (2) Review it as a whole — what problem does it solve, where does it appear in a product, what makes it different from similar items. (3) Write documentation in this format: Name, Purpose, When to Use, When Not to Use, Properties, Accessibility Guidelines, Notes. (4) Keep it short — clarity over completeness; avoid internal jargon unless provided. Output: a markdown file, one section per item, no opinions, no assumptions, no new system rules.
7
Run the 'Generate Documentation' command on a component selection
In Figma, isolate a simplified, specific set of components or variants (not the entire library). Copy the link to that selection. In Cursor, type '@generate documentation' and paste the Figma URL. Review the returned markdown — it will cover variants, use cases, states, behaviors, props, and accessibility notes. Use this content as structured input for your documentation platform (e.g. ZeroHeight, Supernova, or an internal doc site). Dialogue with the AI to expand or tighten sections as needed. Do not hand the raw output to developers — treat it as a structured first draft.

// What does this workflow look like in real projects?

A designer has built a dashboard screen for a SaaS product and needs to confirm all design tokens are correctly applied before engineering handoff. The dashboard has 20+ components across three surface layers.

Rather than clicking through each element manually, the designer copies the Figma link to the dashboard frame, invokes '@check variables' in Cursor, and receives a line-by-line issues list: e.g. '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.' The designer resolves each flagged issue, re-runs the command, and confirms a clean audit before handoff.

A design systems team has an existing button component with six variants but no written documentation. They need usage guidelines for a new ZeroHeight documentation site.

The team selects the primary and secondary button variants in Figma (not all six at once), copies the link, and invokes '@generate documentation'. Cursor returns a markdown file with Name, Purpose, When to Use (e.g. 'Primary button for the single highest-priority action per view'), When Not to Use (e.g. 'Do not use alongside another primary button'), Properties (size, icon slot, state), Accessibility Guidelines (contrast ratio, focus ring requirement), and Notes. The team copies the markdown into ZeroHeight and supplements it with annotated screenshots.

// What mistakes should you avoid with AI design system audits?

Do not use any AI tool that claims to 'build designs using your actual design system components' — they recreate elements using styles and groups, not real component instances, and do not apply your actual variables. You will rebuild everything from scratch anyway.
Do not attempt to build a variable library entirely from scratch with AI without foundational knowledge of design tokens and Figma variables — it requires considerable iteration and high-level input to get anything accurate.
Do not feed AI your entire component library or all variants at once when generating documentation — scope to a specific, simplified selection first to reduce errors and noise.
Do not accept AI-generated documentation assumptions as fact — instruct the AI in your rule to confirm assumptions before stating them, then audit the output before using it.
Do not skip auditing existing documentation even if you already have some — use the 'Generate Documentation' command to check for missing elements, incorrect usage guidelines, or gaps.
Do not copy generated markdown documentation directly to developers without review — it is a structured first draft, not a finished handoff document.
Do not use Figma Make or similar tools to build production Figma files from a design system — variables and text styles are not properly applied when the design is pasted into a real Figma file, and auto layout is replaced with fixed-width frames and arbitrary padding values.
If the MCP server shows a loading state instead of a connected badge, delete and reconnect — it should connect instantly, and a loading state indicates a failed connection.

// What key terms should you know for this workflow?

Design System Assistant: The role AI plays in this workflow — not a builder of components or layouts, but an analytical reviewer that reads your token rules and flags where they are applied incorrectly or missing in a given Figma design.
Cursor Project Rule: A persistent instruction file inside Cursor that teaches the AI your design system's token logic — what each token is, when it should be used, and what contexts it covers. Rules are referenced automatically whenever a related command is invoked.
Cursor Project Command: A saved, reusable prompt shortcut inside Cursor (invoked with '@command-name') that executes a defined multi-step workflow — such as auditing variable usage or generating documentation — whenever a Figma URL is provided.
Figma MCP: A Model Context Protocol server integration that connects Cursor to a Figma file, allowing the AI to read component structures, variable assignments, text styles, and design tokens directly from a shared Figma link.
Check Variables (command): The reusable Cursor command that analyzes a provided Figma page or component, cross-references all identified surfaces, borders, text colors, and icon colors against the Design Token Rule, and returns a line-by-line list of incorrect or missing variable applications.
Generate Documentation (command): The reusable Cursor command that reads a provided Figma component or variant selection and produces structured markdown documentation covering Name, Purpose, When to Use, When Not to Use, Properties, Accessibility Guidelines, and Notes — without introducing opinions or new system rules.
Design Token Table: A Figma table containing four columns — token name, light mode value, dark mode value, and usage description — that serves as the source of truth from which the Cursor Project Rule is generated.
Secondary or Tertiary Components: Non-primary UI elements (e.g. helper text, badges, status indicators nested within a card) that are explicitly called out in the Check Variables command to prevent the AI from over-focusing on primary elements and missing token errors in supporting components.

// FREQUENTLY ASKED QUESTIONS

What is the UI Collective AI Design System Audit Workflow?

It's a workflow that uses Cursor and the Figma MCP server to automatically check whether design tokens are applied correctly in a Figma design and to generate first-draft component documentation. You teach Cursor your token rules once, then run reusable commands like '@check variables' on any Figma link to get a line-by-line list of incorrect or missing variables.

What is a Figma MCP server and why do I need it?

Figma MCP is a Model Context Protocol integration that connects Cursor to your Figma files, letting the AI read component structures, variable assignments, text styles, and tokens directly from a shared link. You need it because it's how Cursor actually 'sees' your design — without it, the AI can't cross-reference elements against your token rules to flag errors.

How do I audit design tokens in Figma using AI?

Set up Cursor with the Figma MCP server, then generate a Cursor Project Rule from your design token table so the AI learns your token logic. Create a '@check variables' command, select the component or page in Figma, copy its link, invoke the command in Cursor, and paste the URL. You'll get a line-by-line list of wrong or missing variables to fix before handoff.

How do I generate design system documentation with Cursor?

Create a 'design system documentation' Project Rule in Cursor that instructs the AI to document only what exists, then a '@generate documentation' command. Select a simplified set of components in Figma, copy the link, invoke the command, and paste the URL. Cursor returns structured markdown covering Name, Purpose, When to Use, When Not to Use, Properties, Accessibility, and Notes as a first draft.

How does this compare to AI tools that claim to build Figma designs with your design system?

This workflow uses AI as an analytical reviewer, not a builder — which is the key difference. Tools claiming to 'build with your design system' actually recreate elements as groups using your styles, not real component instances with proper auto layout. You end up rebuilding from scratch. This audit workflow instead reads existing designs and flags token errors, which AI does reliably.

When should I use this workflow?

Use it whenever you need to audit a Figma design or component for incorrect or missing variable usage before developer handoff, or when you need first-draft documentation for components, variants, or modules. It's most valuable on complex screens like dashboards with 20+ components across multiple surface layers, where manual token checking is slow and error-prone.

What results can I expect from using this workflow?

Expect a line-by-line issues list identifying wrong token types (e.g. a border variable on text), missing variables (hard-coded hex instead of a token), and the specific correct token to apply. For documentation, you get structured markdown drafts covering purpose, usage, states, props, and accessibility. It replaces manual element-by-element inspection and produces cleaner handoffs and faster documentation.

Do I need coding knowledge to use Cursor for design audits?

No coding knowledge is required to run the audit and documentation workflow, since you interact through natural-language prompts and reusable commands. However, you do need foundational understanding of design tokens and Figma variables — the AI reviews against rules you define, so knowing what correct token usage looks like is essential to write good rules and validate output.

What is a Cursor Project Rule versus a Cursor Command?

A Project Rule teaches the AI your design system's token logic once — what each token is and when to use it — and is referenced automatically. A Command is a reusable prompt shortcut invoked with '@command-name' that executes a defined multi-step workflow on demand. The principle is 'Rules Teach, Commands Execute' — separate the teaching step from the doing step.

Can I audit my entire design system at once with this workflow?

No — feeding AI your entire component library or all variants at once produces mistakes and noise. The 'Simplify Before You Scale' principle says to select a specific, simplified set of components or variants first, run the command, then expand. Start narrow with something like a single frame or two button variants for accurate results.

Can I hand AI-generated documentation directly to developers?

No — treat generated markdown as a structured first draft, not a finished handoff document. Review it line by line, confirm any AI assumptions, and use it as input for your documentation platform like ZeroHeight or Supernova. Developers write developer content; designers refine usage and accessibility guidelines. Always audit before publishing.

// GET THIS SKILL — FREE