Work With Design Systems

Work with design systems in Figma

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.

Prerequisites

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.

Critical rules

These apply to BOTH modes — inspect and build.

1. Work incrementally. One component (or one variant set) per use_figma call. Validate after each step. This is the single most important practice for avoiding bugs.
2. Never build on unvalidated work — match validation depth to change type.

• Structural change (new variant, restructured auto-layout, new property, swapComponent): get_metadata + get_screenshot before next step. Visual properties may have shifted invisibly.
• Binding / description / codeSyntax / scope / rename change: verify INSIDE the same script via node.boundVariables / node.description / variable.codeSyntax / variable.scopes reads, return as part of the result. No external get_screenshot needed — Figma is deterministic on these.
• End of batch: one get_screenshot of the parent CS for visual sanity.

Why: get_screenshot is the heaviest call and Figma MCP has a ~15 calls/min rate limit. Matching depth to risk frees that budget for the structural changes that actually need visual verification, and stops you hitting the rate limit on a binding pass that doesn't need it.

1. Bind visual properties to variables when a scale value exists. Fills, strokes, padding, itemSpacing, corner radius. For component-specific dimensions that don't match any scale value (e.g., 3px internal padding on a toggle track, 1px divider offset), hardcoded values are acceptable — document these exceptions in the component description.
2. lineHeight variables must store pixel values, not percentages. Figma variables are unitless. When bound to lineHeight, the value is interpreted as pixels. If your DS defines line heights as percentages (e.g., 150%), convert before storing: fontSize × (percentage / 100). Text styles can store {unit: "PERCENT", value: 150} — variables cannot.
3. Set codeSyntax.WEB on every variable. Without it, agents using get_design_context get raw Figma variable names instead of CSS token names. Set during creation, not as a separate pass.
4. Set explicit variable scopes. Never leave ALLSCOPES. Background colors get FRAMEFILL + SHAPEFILL. Text colors get TEXTFILL. Spacing gets GAP + WIDTHHEIGHT. Radius gets CORNERRADIUS. Font size gets FONT_SIZE.
5. TEXT properties with the same name merge across variants. If two variants both define 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.
6. TEXT component properties on every customizable text node. Without them, label overrides ("Label" → "Submit") revert on component update. Every customizable text node needs componentPropertyReferences = { characters: key }.
7. Use slots for compound components. Compound components (Card, Modal, Dialog, ListItem, ReviewCard) that contain variable inner content MUST use named slots instead of detach patterns or text-only props. Without slots, agents and users detach the component to edit inner content, which breaks maintenance and the agent's ability to reason about composition. Slots are available in Figma as of March 2026. See references/build/slots-guide.md.
8. Every public component MUST have a structured description. Figma MCP reads component descriptions and passes them to agents as context. Missing descriptions force the agent to guess purpose, behavior, and composition. Use the template in 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.
9. Never detach a component. If you need to vary inner content, use: variant, boolean property, instance swap, or named slot. Detaching breaks the design-to-code bridge — the detached frame becomes structurally invisible to agents and to inspect mode.

---

Mode selection

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:

• "audit my design system" / "check component quality" / "review my DS"
• "find detached instances" / "check WCAG" / "score my components"
• "generate handoff docs" / "export component specs"
• "is this design system ready" / "what's broken in my file"
• Any request that asks for a report or evaluation without explicit "build" or "fix"

Build mode triggers when the user says:

• "create design system" / "build DS in Figma" / "generate component library"
• "set up tokens" / "add components" / "sync from code"
• "fix ALL_SCOPES" / "add codeSyntax" / "rebuild Variables"
• "add slots to my components" / "write descriptions"
• "export tokens.css" / "generate CLAUDE.md" / "sync to code" (these enter build mode and proceed directly to Phase 6 if rest of system is in good shape)
• Any request that asks for changes to the file or codebase

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.

---

Inspect mode

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.

Inspect workflow

1. Scope. Ask the user: full file or specific components? Which audit modules? Default is all six. Export format — markdown (default), JSON, both, or AI prompt.
2. Inventory. Run scripts/inspect/inventory.js to list all component sets with variant counts and page locations. Present as a table for user confirmation.
3. Run modules for each component set in this order:

• Module 1 — Token compliance (scripts/inspect/audit-tokens.js) — outputs errors and warnings separately
• Module 2 — Interactive states (scripts/inspect/audit-states.js)
• Module 3 — Accessibility (scripts/inspect/audit-accessibility.js)
• Module 4 — Detached instances (scripts/inspect/audit-detached.js) — runs once, file-wide
• Module 5 — Naming quality (scripts/inspect/audit-naming.js)
• Module 6 — Component descriptions (no script — uses Claude reasoning, read references/inspect/component-descriptions.md)

1. Compile report using templates from 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).
2. Export report to /mnt/user-data/outputs/audit-report.md (and .json if requested).
3. STOP. Present report summary. Wait for user decision.

Inspect → build handoff

After inspect, the skill MUST pause and present:

> Audit complete. Report saved to audit-report.md. Overall score: {score}/100. > > Top issues: > 1. {highestimpactissue} > 2. {secondhighestimpactissue} > 3. {thirdhighestimpactissue} > > 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.

---

Build 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.

Build workflow paths

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

Phase 1: Discovery

1a. Determine the source

Ask the user:

• From scratch: What's the product? Brand colors, typography, spacing? Reference (Figma file, website, brand guidelines)?
• From codebase: Where are tokens defined? (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)
• Screenshots or URLs as visual references
• Verbal description of brand, colors, typography

1b. If syncing from code — analyze the codebase

Scan for:

• Token files: CSS variables, Tailwind config, JSON token files, styled-components theme
• Component inventory: list all UI components, their props/variants, file paths
• Naming conventions: PascalCase vs kebab-case, variant naming patterns
• Framework: React, Vue, Svelte, Angular, or other
• Storybook stories (if present): Read *.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:

• Variable scopes (flag ALL_SCOPES violations)
• codeSyntax coverage (list variables missing codeSyntax.WEB)
• Duplicate variables
• Bindings sample via get_metadata on a few components, check boundVariables coverage
• Generic layer names (if >20% of layers in components are auto-named like Frame 47, suggest Figma's AI rename in Actions panel as a first pass)
• Detach patterns in compound components (flag for Phase 4c slot decision)

Recommend a path:

• Build in place — file has solid variables, components need fixes
• New file, old as reference — no variables, naming chaos, start fresh
• Hybrid — foundations solid, components need rebuild
• Switch to inspect mode — if user wants comprehensive audit before deciding
• Code export only — if Figma is solid and user just wants Phase 6 outputs

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:

1. /.claude/rules/design-system.md — Claude Code convention for DS rules
2. /.claude/rules/component-build-rules.md — alternative name some projects use
3. /CLAUDE.md — if it contains a "Components — Build Rules" or "Design System" section, load that section

If 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 `` — 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:

• Token categories (colors, spacing, radius, typography, shadows)
• Number of modes (Light/Dark, brands)
• Component list (prioritized — core first)
• Naming convention
• Component numbering convention (C{section}.{number} {Name})
• CSS token naming for codeSyntax.WEB

Do not proceed until user confirms.

Phase 2: Foundations

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.

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).

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 `setExplicitV

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: natdexterra
• Source: natdexterra/work-with-design-systems
• License: MIT

Install and usage instructions live in the source repository linked above.