What is the work-with-design-systems skill?
The work-with-design-systems skill gives your AI coding agent two modes for Figma design systems. Inspect mode runs read-only audits with WCAG checks and component scoring. Build mode creates components with variable bindings and slots, and an optional Phase 6 syncs tokens.css to your code.
This skill gives your AI coding agent two modes for Figma design systems. Inspect mode runs read-only audits with WCAG checks, component scoring and handoff docs. Build mode creates components, fixes foundations, adds slots and writes descriptions.
The skill detects the mode from your request, or asks when it is unclear. After an inspect run it pauses with the report and waits for your decision before any change is made.
Six audit modules
- Token compliance. Variable binding coverage, with unbound fills, strokes, padding, gaps and corner radii as errors.
- Interactive states. Variants are compared against the expected state matrix for each component type.
- Accessibility. Computed WCAG 2.1 AA checks for color contrast, touch target size, font size and focus indicators.
- Detached instances. Frames that match component names but are not instances, reported with page, parent path and node ID.
- Naming quality. Generic Figma auto-names such as Frame 47 or Rectangle 3 inside components.
- Component descriptions. Structured documentation per component: PURPOSE, BEHAVIOR, COMPOSITION, USAGE and CODE NOTES.
Build mode and Phase 6
Build mode runs six phases: discovery, foundations, file structure, components, QA and an optional sync to code. The skill pauses between phases so you can review the work before it moves on.
Phase 6 is off by default and triggers only on an explicit request. It generates tokens.css with three-layer indirection, a CI-ready audit script and an AI rules file for Claude Code, Cursor or Codex.
Where it fits
Best for
- Auditing a Figma file and getting a weighted readiness score from 0 to 100 for each component.
- Adding slots to compound components such as Card, Modal and Dialog in place of detach patterns.
- Generating component documentation for developer handoff as a markdown and JSON bundle.
- Exporting
tokens.cssand an AI rules file from a Figma design system that is already solid.
Not for
- Auditing a rendered page with Lighthouse and the accessibility tree, then fixing source code against WCAG 2.2, which the web accessibility skill covers.
- Building Tailwind CSS v4 design systems with CSS-first theme tokens, OKLCH semantic colors and CVA components, which the tailwind design system skill covers.
- Scoring a front end on three grades for design, AI slop and accessibility from static HTML and CSS, which the design auditor skill covers.
- Scoring a screenshot for color, layout and type, which the design critique MCP covers.
How to install Work With Design Systems Skill: Audit and Build in Figma
git clone https://github.com/natdexterra/work-with-design-systems.git .claude/skills/work-with-design-systemsClone into your project
Run the command above in a project to put the skill at
.claude/skills/work-with-design-systems. Copying the folder to~/.claude/skills/work-with-design-systems/makes it available across all projects.Use another client
For Cursor, copy the folder to
.cursor/skills/work-with-design-systems/. For Codex, copy it toskills/work-with-design-systems/.Connect the prerequisites
Connect the Figma MCP server, with the remote server recommended, and install the
figma-useskill. A Full or Dev seat is required.Invoke the skill
Type
/work-with-design-systemsin Claude Code chat and describe what you want, such as auditing your design system file.
Check that it loaded
Run /work-with-design-systems and ask it to audit your design system file. Expect it to inventory the file, run the six modules, produce a report and stop to wait for your decision.
Key features
- Two modes in one skillInspect mode is read-only. Build mode creates components, fixes foundations, adds slots and writes descriptions. The mode is detected from your request.
- Mandatory pauseAfter inspect, the skill presents the report and waits for your explicit decision before any build action.
- Six audit modulesToken compliance, interactive states, accessibility, detached instances, naming quality and component descriptions each run on the components you scope.
- Weighted readiness scoreEach component is scored from 0 to 100. State gaps weigh x3, token errors x2, accessibility x1 and naming x0.5, with token warnings at x0.6.
- WCAG checksContrast is checked at 4.5:1 for normal text and 3:1 for large text, with a 44 by 44 pixel touch target minimum and font size warnings below 12px.
- Slots for compound componentsCard, Modal and Dialog get named slots in place of detach patterns, and existing instances continue to work when slots are added.
- Structured descriptionsEvery public component gets a structured description, because Figma MCP passes component descriptions to agents as context.
- Variable hygieneThe skill sets
codeSyntax.WEBon every variable and explicit variable scopes, and leaves no variable on ALL_SCOPES. - Optional sync to codePhase 6 writes
tokens.css,scripts/token-audit.jsand an AI rules file, and runs only when you ask for it. - Three export formatsAudit output comes as markdown, JSON or an AI prompt for code generation.
Frequently asked questions
What is the work-with-design-systems skill?
It is a skill that gives your AI coding agent two modes for Figma design systems. Inspect mode runs read-only audits with WCAG checks, component scoring and handoff docs. Build mode creates components, fixes foundations, adds slots and writes descriptions, and it can optionally sync tokens.css and AI rules to your codebase.
How do I install the work-with-design-systems skill?
Clone the repository into .claude/skills/work-with-design-systems inside your project with the git clone command shown above, or copy the folder into your global Claude Code skills directory. Then invoke it with /work-with-design-systems in Claude Code chat. Cursor and Codex use their own skills folders for the same copy.
What does inspect mode check?
Inspect mode runs up to six audit modules: token compliance, interactive states, WCAG accessibility, detached instances, naming quality and component descriptions. You can narrow the scope to certain components or modules, for example only the accessibility checks on Button and Input, and choose markdown, JSON or an AI prompt as the output.
Does the skill change my Figma file during an audit?
No. Inspect mode is read-only and leaves the file unchanged. After the audit it presents the report with the top issues and waits for your decision. You can fix everything, fix specific issues, build new components or stop, and no build action starts without your explicit confirmation.
What does Phase 6 produce?
Phase 6 is optional and off by default. It generates tokens.css with three-layer indirection, a CI-ready audit script at scripts/token-audit.js that exits with code 1 on hardcoded values, and an AI rules file. The rules file is .claude/rules/design-system.md for Claude Code, .cursor/rules/design-system.mdc for Cursor, or a section in AGENTS.md for Codex.
What do I need before I use the skill?
You need the Figma MCP server connected, with the remote server recommended, the figma-use skill installed, and a Full or Dev seat. Figma rate-limits MCP read tools per plan: Professional allows 10 calls per minute and 200 per day, Organization 15 and 200, and Enterprise 20 and 600. Scope inspect runs to the component sets you need.
How does the skill score components?
Each component gets a weighted readiness score from 0 to 100. State coverage weighs the most at x3 because missing states cause the most downstream breakage in generated code. Token errors weigh x2, accessibility x1 and naming x0.5, and token warnings count x0.6, which is less than errors but not zero.
Why does build mode use slots instead of detaching components?
Detached frames are structurally invisible to agents and to inspect mode. Slots give explicit dropzones for variable content while keeping the component intact. Compound components such as Card, Modal and Dialog get named slots, and slots are available in Figma as of March 2026.