Inspect, build, or extend Figma design systems from Claude Code. Read-only audits with WCAG checks and component scoring, build mode with variable bindings and slots, optional Phase 6 sync to tokens.css + AI rules.
SaferSkills independently audited work-with-design-systems (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Two modes in one skill: inspect (read-only quality audits with reports) and build (creating, fixing, extending components and tokens). Inspect produces structured reports. Build produces working Figma files. Build mode optionally extends to Phase 6 (sync to code) — generates tokens.css, an audit script, and AI rules file for the user's codebase. Phase 6 is off by default and only triggers on explicit user request.
Between inspect and build, the skill always pauses for the user to decide what to do with the report.
Always pass `skillNames: "work-with-design-systems"` when calling `use_figma` as part of this skill. This is a logging parameter — it does not affect execution.
You MUST invoke the `figma-use` skill (Skill tool: `skill: "figma-use"`) before every `use_figma` call. It contains critical Plugin API rules, gotchas, and script templates. Never call use_figma without it.
IMPORTANT: Before working with design systems in Figma, load the working-with-design-systems/wwds.md reference from the figma-use skill to understand key concepts and guidelines.
These apply to BOTH modes — inspect and build.
use_figma call. Validate after each step. This is the single most important practice for avoiding bugs.swapComponent): get_metadata + get_screenshot before next step. Visual properties may have shifted invisibly.node.boundVariables / node.description / variable.description / variable.codeSyntax / variable.scopes reads, return as part of the result. No external get_screenshot needed — Figma is deterministic on these.get_screenshot of the parent CS for visual sanity.Why: get_screenshot is the heaviest call, and Figma MCP rate-limits its read tools per plan and seat — Professional Full/Dev seat: 10 calls/min and 200/day; Organization: 15/min, 200/day; Enterprise: 20/min, 600/day; Starter: 20/month; View/Collab seats: 6/month (Figma's rate-limits-access doc, 2026-08). Only whoami, create_new_file, add_code_connect_map are exempt. The daily cap is the one that bites: a per-component inspect pass with a screenshot each can spend a whole day's budget on one mid-size file. Matching depth to risk frees that budget for the structural changes that actually need visual verification. Run whoami when unsure which tier applies.
{ color: <alias>, opacity: <percent> }), so a disabled, ghost, overlay or scrim value is an alias-with-opacity token — never a bound fill with a raw opacity typed on the paint, which no export and no audit can read. See references/build/token-taxonomy.md, "Alpha tokens".get_design_context get raw Figma variable names instead of code token names. Set during creation, not as a separate pass. Presence is not enough: a semantic token gets its own name (--color-text-link), never the name of the primitive it aliases (six roles sharing --color-primary-500 cannot be told apart in a stylesheet), and never a value (1.25rem, 9999px, #fff, 400 — Phase 6 would emit --1rem: 1rem). Spell it in the codebase's convention: a CSS custom property as --name or var(--name) (Figma's own examples use the var() form) is what Phase 6 tokens.css consumes; an SCSS $token or a bare token-name is valid when the project's documentation prescribes it, but Phase 6 cannot consume it. The validator reports values and duplicates as errors and non-CSS conventions as info. The dash form (--group-leaf or --group--leaf) is one project convention, confirmed in Phase 1e and never mixed; two names that become one after dash collapse and lowercasing are an error too, because a tool that normalizes names keeps only one of them.[], and hex pasted by hand). The validator reports both.addComponentProperty("Label", "TEXT", ...), they become ONE shared property on the component set with one default value. For different defaults per variant: use different property names, leave text as direct content with instance text overrides, or accept the shared default.componentPropertyReferences = { characters: key }.references/build/slots-guide.md.references/build/component-description-template.md. Use plain-text formatting (UPPERCASE section headers, no markdown bold or `##` — `get_design_context` escapes them) — see template's "MCP delivery format" section. Private base components (prefixed with . or _) may use a one-line note. A description is the spec, not a changelog: no dates, people's names, decision history ("approved", "decided", "previous version"), node ids, repo or file paths, scan notes or instance counts. That history belongs in the project's decision records and work logs. A note this skill asks for (a Rule #3 exception, a slot decision) is written as the current rule. A variable description follows references/build/variable-description-template.md (PURPOSE / USAGE / CONSTRAINT) under the same format rules and the same exclusion.The skill operates in one of two modes. The first thing to do in any session is determine the mode.
Inspect mode triggers when the user says:
Build mode triggers when the user says:
Ambiguous requests like "I have a Figma file with some issues — help me with my design system" — ASK the user explicitly:
Should I run a quality audit first (read-only report with scores and issues), or go straight to building/fixing? If you want both, I'll do inspect first, show you the report, then wait for your decision before changing anything.
Default behavior when explicitly mixed ("audit and fix"): start with inspect mode, produce report, pause, wait for user direction.
Read-only. Never modifies the file. Produces structured reports.
Read references/inspect/overview.md before starting. It documents which modules to run for which user requests, the execution order, and the readiness scoring formula.
scripts/inspect/inventory.js to list all component sets with variant counts and page locations. Present as a table for user confirmation.scripts/inspect/audit-tokens.js) — outputs errors and warnings separatelyscripts/inspect/audit-states.js)scripts/inspect/audit-accessibility.js)scripts/inspect/audit-detached.js) — runs once, file-widescripts/inspect/audit-naming.js)references/inspect/component-descriptions.md)references/inspect/report-templates.md. Calculate weighted readiness score per component using the formula in references/inspect/readiness-scoring.md (errors weighted 1.0, warnings weighted 0.3)./mnt/user-data/outputs/audit-report.md (and .json if requested).After inspect, the skill MUST pause and present:
Audit complete. Report saved to audit-report.md. Overall score: {score}/100.>
Top issues: 1. {highest_impact_issue} 2. {second_highest_impact_issue} 3. {third_highest_impact_issue}
>
What would you like to do next? - Fix issues — switch to build mode and address findings (I'll work through the priority list) - Fix specific issues — tell me which to address (e.g., "fix only the ALL_SCOPES violations") - Build new components — switch to build mode for new work, leaving issues for later - Stop — keep the report for later, do nothing
DO NOT proceed to any build action without explicit user confirmation. This pause is the core guarantee of inspect mode.
Read/write. Creates, modifies, validates.
Read references/build/component-spec.md and references/build/token-taxonomy.md before starting Phase 2 (foundations) or Phase 4 (components). Read references/build/slots-guide.md before building any compound component. Read references/build/auto-fix-guide.md before running fuzzy auto-fix on existing components. Read references/build/code-export.md before entering Phase 6.
Full build (no existing file): Phase 1 → 2 → 3 → 4 → 5 → (optional 6)
Extend (variables/styles exist, need components): Phase 1c (health check) → fix foundation issues → Phase 3 (file structure, if needed) → Phase 4 → Phase 5 → (optional 6)
Fix foundations only: Phase 1c → fix ALL_SCOPES/codeSyntax/unbound → stop
Add slots to existing compound components: Phase 1c → identify detach-prone components → Phase 4c (slot decision) → Phase 4 (build or update) → Phase 5
Apply audit fixes — manual (entry from inspect mode): user reviews report → confirms scope → enter build mode → execute fixes per priority list → Phase 5 verification → (optional 6)
Apply audit fixes — fuzzy auto-fix (entry from inspect mode, user opts in): user reviews report → requests "auto-fix the token issues" → Phase 1c health check (foundations must be valid) → run scripts/build/fixHardcodedToTokens.js with issues from inspect → review applied/skipped report with user → handle skipped items manually → Phase 5 verification → (optional 6)
Code export only (Figma file is solid, just need files in repo): Phase 1c (verify foundations OK) → skip 2/3/4/5 → Phase 6
#### 1a. Determine the source
Ask the user:
tailwind.config.js, tokens.css, theme.ts, design-tokens JSON). Where are components? (src/components/ui/)Supported inputs for from-scratch builds:
.md file with brand guidelines.json design tokens (W3C DTCG format, Tokens Studio format)#### 1b. If syncing from code — analyze the codebase
Scan for:
*.stories.{ts,tsx,js,jsx,mdx} files. Each story = one Figma variant. Use story inventory to validate variant coverage in Phase 4. Missing variants on Figma side are as much a gap as missing stories on code side.Read references/build/framework-mappings.md for framework-specific extraction patterns.
#### 1c. If a Figma file already exists — quick health check
Fast sanity check to build a state ledger and decide how to proceed. NOT a full audit — for that, switch to inspect mode.
Run scripts/build/validate-design-system.js via use_figma. Then targeted checks:
--color-brand-primary), not a value (1.25rem) and not the aliased primitive's name reused on a semantic roleget_metadata on a few components, check boundVariables coverageFrame 47, suggest Figma's AI rename in Actions panel as a first pass)Recommend a path:
If foundations are complete, skip Phase 2.
#### 1d. Check for project overrides
Look for project-specific design system rules and load them as overrides on top of the skill's defaults. In priority order, check:
<projectRoot>/.claude/rules/design-system.md — Claude Code convention for DS rules<projectRoot>/.claude/rules/component-build-rules.md — alternative name some projects use<projectRoot>/CLAUDE.md — if it contains a "Components — Build Rules" or "Design System" section, load that sectionIf any of these exist, read them and treat the rules as extensions, not replacements, of this skill's Critical Rules and Phase requirements. Surface what you loaded to the user in one line: "Loaded project overrides from <path> — N additional rules will be applied."
Why: every team's DS has conventions the generic skill can't predict — component numbering schemes (C{section}.{number}), required registry fields (e.g. CMS element identifiers), brand-specific tokens (sharp buttons vs pill, scrim opacity values), description templates (a project-defined marker line first). Hardcoding these in the generic skill would over-specialize it; ignoring them forces the team to re-explain conventions every session. Loading them as overrides keeps the skill general while letting it act project-aware.
If no override file exists, proceed normally — do not block on absence.
#### 1e. Confirm scope
Present summary:
C{section}.{number} {Name})--color-bg-primary) or double (--color-bg--primary), one form for the whole project[data-theme], prefers-color-scheme, both, or one mode only. Platform modes: an attribute, a file per mode, or one mode exported and the other out of scope (references/build/code-export.md)Do not proceed until user confirms.
Skip if Phase 1c confirmed all needed tokens exist and pass quality checks.
Read references/build/token-taxonomy.md before starting.
#### 2a. Variable Collections
Recommended: 3-tier (Primitives → Semantic → Component). Best for multi-brand or new builds.
Alternative: flat domain-based (Colors, Spacing, Radius, Typography). Valid for single-brand or rebuilds where this structure exists.
Match what's in the file or codebase. The requirement is not depth — it's that every variable has explicit scopes and codeSyntax.WEB.
When a variable gets a description, write it from references/build/variable-description-template.md and read variable.description back in the same script (Critical Rule #2).
#### 2b. Text Styles and Effect Styles
Create text styles with proper variable bindings (font-size, line-height, font-weight, letter-spacing all bound to variables). Apply lineHeight gotcha (Critical Rule #4).
Text wrap (Figma, Aug 2026): text layers, text styles and individual paragraphs now carry a wrap mode — default, Balance (even line lengths) or Pretty (no orphan word on the last line). Decide it per text style, not per layer: Pretty for body/paragraph styles, Balance for headings and pull quotes, default for UI labels. The Plugin API property is not documented in figma-use yet — set it in the UI, or grep plugin-api-standalone.d.ts for the property name before scripting it. It does not survive export to PPTX / Figma Slides, so a system that also feeds presentations must not rely on it for line breaks.
Responsive / fluid type: model it with collection modes, not by hardcoding one size. Give the Typography collection a Desktop (default) and a Mobile mode; every font-size / line-height token carries a value per mode. A frame previews mobile via setExplicitVariableModeForCollection(typographyCollection, mobileModeId) while reusing the same text styles, and on code export the Mobile mode takes a media-query target (the formatter does not emit clamp(); code-export.md, "Not covered"). Keep Desktop the default so styles preview at full size. (Line-height stays in pixels — Critical Rule #4.)
Create effect styles for shadows, blurs.
#### 2c. Semantic layer completeness — cover every role, never skip status
When building the Semantic tier, verify it covers the full role surface, not just the obvious ones:
Status is the most-missed group — treat it as mandatory for any app UI. Without it there is no token to show an error, a validation message, or a success toast.
If the source / brand palette has no status hues (especially no red for `error`): do NOT silently omit them and do NOT force a brand colour into a status role (a brown "error" reads as wrong and breaks the convention). Surface the gap to the user and propose a small functional status ramp (error | warning | success | info × {bg, solid, text}) tuned to harmonise with the palette, with every text-on-bg pair checked for WCAG AA (≥ 4.5:1). Status colour is functional infrastructure, not brand expression. See references/build/token-taxonomy.md.
Skip if documentation pages aren't required.
Standard pages: Cover, Getting Started, Foundations, one page per component group, Patterns (if applicable), Utilities.
Foundations page contains: rendered swatches for each color variable, type specimens for each text style, spacing scale visualization, effect previews.
Colour swatch card (recommended anatomy): group swatches by role (PRIMARY / SECONDARY / NEUTRALS / STATUS …) under uppercase section titles — uppercase via the text style's textCase = 'UPPER', never by typing capitals into `characters` (source text stays sentence-case; a restyle then needs no retyping). Each card = a large swatch bound to the variable, then three text lines: human name (bold), the code token (--token-name, from codeSyntax.WEB), and HEX CODE : #RRGGBB. Add a 1px neutral border to swatches whose luminance is high (≈ > 0.82) so white / light-tint swatches stay visible on a white page. Type specimen: one row per text style; if the scale is responsive, show a Desktop column and a fixed-width Mobile column (mode-switched) side by side so the fluid behaviour is visible.
Component pages use fixed-width (996px) wrapper structure:
Patterns page (if patterns documented) follows the same wrapper structure. Read references/build/patterns-guide.md for pattern frame conventions.
Create a reusable Page Title component on Utilities page. Each component page uses an instance, not a manual frame.
#### 4a. Confirm component list
Suggest defaults (Button, Input, Select, Checkbox, Radio, Toggle, Card, Modal, Badge, Avatar, Toast). User confirms based on actual inventory. Add or remove freely.
Read references/build/component-spec.md for default specs.
#### 4b. Build each component
One component per use_figma call. Validate after each.
Sequence per component:
use_figma — patterns in figma-use skill's working-with-design-systems/wwds.md referenceuse_figma — same referencereferences/build/component-description-template.md (Critical Rule #10)get_metadata + get_screenshot#### 4c. Slot decision (for compound components)
Before building Card, Modal, Dialog, ListItem, ReviewCard, or any component that hosts variable inner content — read references/build/slots-guide.md and decide:
When in doubt for compound components, prefer slots. Document the decision in the component description.
#### 4d. Patterns (optional)
If user wants composition patterns documented, read references/build/patterns-guide.md. Build pattern frames on the Patterns page using actual component instances arranged according to layout rules. Number patterns as P{section}.{number} {Name}.
Run scripts/build/validate-design-system.js for full file audit (variables and styles are file-level; the component-tree walk covers one page per call — pass PAGE_ID and fan out one call per component page, see references/inspect/overview.md):
Build a test page assembling several components together to verify composability.
If you edit any script in `scripts/`, run the fixed set before and after the edit: npm test (no dependencies, Node only) runs the scripts against the JSON fixtures in tests/fixtures/ through a mock figma, compares them to the hand-written answer keys in tests/expected/, and prints a fixture × check grid with a score line. A red row before the edit is what the edit must turn green; a green row that goes red is the regression. A fixture is cheap — add one for the shape you are fixing rather than checking the change by hand on a live file.
If the file is a published library, remind the user to click Publish — consumer files keep the old scopes, names and bindings until they accept the library update, so a fix that validates here is invisible downstream until then.
After QA passes, present this prompt to the user:
Build complete. {N} components, {M} tokens, all validated.
>
Want to sync to code? I can generate up to four files in your project: -tokens.css— design tokens with three-layer indirection (handles Light/Dark modes) - AI rules file — design system rules for the AI agent in this repo (Claude Code / Cursor / Codex) -scripts/token-audit.js— CI-ready audit script that catches hardcoded values -specs/patterns/*.md— optional composition spec files (Hardik Pandya-style)
>
Reply with "yes, sync to code" to enter Phase 6, or "done" to stop here.
Do NOT enter Phase 6 unless user explicitly requests it.
Pre-condition: This phase requires file write access to the user's project root. Available in Claude Code, Cursor, and other MCP clients with file write tools. NOT available when skill runs in Claude.ai web/mobile chat — in that case, output the file contents inline for the user to copy manually.
When to enter Phase 6:
Read references/build/code-export.md before starting Phase 6.
#### 6a. Format detection
Determine which AI agent client the project uses by checking the project root:
.claude/ directory or CLAUDE.md file exists → Claude Code.cursor/ directory exists → CursorAGENTS.md file exists → CodexIf multiple are present, ask which the user wants. Skill can generate for multiple at once.
#### 6b. Output path resolution
Important: never overwrite an existing top-level CLAUDE.md, AGENTS.md, or full .cursor/rules. The skill writes to scoped locations:
.claude/rules/design-system.md.cursor/rules/design-system.mdc## Design system section to AGENTS.md between explicit start/end markers (<!-- design-system-rules-start --> / <!-- design-system-rules-end -->) for safe future updatesIf the scoped path already has a file from a previous Phase 6 run, ask user: overwrite, append, or skip.
#### 6c. tokens.css strategy
Ask the user how Light/Dark modes should resolve in CSS:
[data-theme="dark"] attribute on root — most flexible, requires JS to set@media (prefers-color-scheme: dark) — automatic, follows OS preferenceMulti-brand modes: use the same attribute pattern with brand-specific values ([data-brand="acme"]).
Platform modes (a collection whose modes are output platforms, not themes): use the strategy chosen in Phase 1e. See code-export.md, "Collections with platform modes". Every mode that is not its collection's default needs a target; the formatter refuses a mode without one.
Read references/build/code-export.md for full structure with examples for each strategy.
#### 6d. Generate files
For each file, use Claude's file write tools (NOT use_figma). Generate:
scripts/build/exportTokensToCSS.js via use_figma and save the JSON it returns to a file. Write the strategy from 6c as a targets map (references/build/code-export.md, "Formatting tokens.css"), then, from the project root, run node <skill folder>/scripts/export/formatTokensCSS.js <export.json> <targets.json> > <path>/tokens.css. The CSS comes from that formatter and is never written or patched by the model from prose: when a value is wrong, fix the variable, its codeSyntax or the targets map, and run it again. When the formatter refuses, its errors name what to fix.references/build/code-export.md "AI rules templates" section. Fill in component list (from current build), token reference list, audit script reference. Write to scoped path determined in 6b.references/build/code-export.md "Audit script template" section. Fill in TOKENS object with token names and raw values from current build. Write to project's scripts directory (create if missing).** — only if user explicitly asks ("also generate spec files for patterns"). One markdown file per pattern documented in Phase 4d. Use template from references/build/code-export.md`.If running in Claude.ai web (no file write tools), output each file's contents in fenced code blocks with clear "save as: {path}" headers. Where Node cannot run either, tokens.css is the exception: output the exporter JSON, the targets map and the formatter command, never a hand-formatted tokens.css.
#### 6e. Verify
After writing files:
node scripts/token-audit.js and report resultsReport file paths to user. Phase 6 complete.
Build mode and Phase 6 sync are Figma-only: variables ↔ code. Some teams draw screens in a second canvas tool that keeps its own token store. In that case the source of truth stays the tokens file (or the design-system document that holds the same values), and the tool's tokens are a projection of it:
codeSyntaxCollisions) covers collapse and lowercase; for any other rule the tool applies, apply it to every name and look for two that become one. After the push, read the tool's tokens back and diff the names 1:1 against the file, not only the values. A name that changed on import is a drift: resolve it by renaming at the source (the variable or its codeSyntax), never by a hand fix in the tool. With a tool that collapses dashes, a double-dash form cannot survive the import; weigh that when the dash form is chosen in Phase 1e.This skill does not draw screens in any tool. Tool mechanics belong to that tool's own skill or guide.
Inspect mode — quality report on someone else's file
User: "Audit this Figma file — I'm reviewing it for a client engagement."
Mode: Inspect.
For 8 more examples (full build, inspect → build paired flow, slot retrofit, narrow-scope inspect, end-to-end Phase 6, code-export-only, touch-up description pass) see references/examples.md. Load it when the request doesn't clearly match the inline example above.
For unusual situations (mode unclear, Phase 6 in Claude.ai web, missing fonts, token conflicts, rate limits, conflicting project overrides) see references/edge-cases.md. Load it when you hit one.
On any use_figma error:
get_metadata to understand current file state.For full error recovery workflow, load figma-use skill.
On Phase 6 file write errors:
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.