← Agent Skills / figma-workspace-architect

figma-workspace-architect

A Claude Code skill for designing, building, auditing, and migrating Figma workspaces via the figma-console-mcp server. Sets the bar at "a workspace where a designer can find what they need without asking" — correct Variable scopes, Variants matching the engineering prop API, Modes carrying theming instead of duplicate components, predictable naming.

v0.2.0 4 modes · 3 sub-modes · 13 references · 8 test scenarios

What it does

The skill activates when a user asks about Figma file architecture, design tokens, components, or a workspace decision. It picks one of four modes based on the user's intent, then loads only the references it needs — references are scoped, not bundled. Sub-modes handle the narrower cases that benefit from a more focused recipe.

Build

triggers on: create, set up, bootstrap, scaffold, build, generate, add, refactor

Discovery → Decide → Map tools → Execute → Validate → Document. Never write to Figma without first reading what is there.

↳ Scaffold sub-mode

One-shot starter: Cover + Tokens + Components pages with placeholder content. For when the user wants a working skeleton in one turn.

Audit

triggers on: audit, review, check, assess, what's wrong with, how good is

Two layers: Design System Dashboard (breadth: A11y, Coverage) followed by the architectural deep-audit (depth: 5 categories with severity tags). Pre-flight pins the snapshot (git SHA + Figma lastModified) and runs cross-source greps so findings are grounded in current state.

↳ Re-verify sub-mode

Re-checks an existing audit report by running only the per-category verify queries. Emits still-open / auto-resolved / state-shifted per finding so stale findings drop off the priority list automatically.

Decide

triggers on: either/or questions, "should I…?", "is it better to…?"

Single-pass recommendation with reasoning in 1–2 sentences plus the alternative path with its trade-off. No essays.

Migrate

triggers on: rename, split, restructure, refactor, deprecate, retire, replace

The additive coordination protocol for breaking changes (add new alongside old → wait one cycle → migrate consumers → remove old). Recipes for variable renames, mode adds, variant set splits, primitive→semantic promotions, library splits.

↳ Code-verify sub-mode

Post-flight Storybook + browser-automation recipe to confirm Figma↔code parity in Light + Dark after a token or variant change. Catches the bug class where Figma and code each look correct but their handoff is broken.

Install

Claude Code skills live as directories under ~/.claude/skills/ (user-global) or .claude/skills/ (project-local). Both options below land the skill in the canonical layout — Claude Code auto-discovers it on the next session.

From the published zip

# Download the runtime payload (SKILL.md + references/ + assets/)
curl -sL "https://atelier.pieper.io/.well-known/agent-skills/figma-workspace-architect.zip" \
  -o /tmp/figma-workspace-architect.zip
unzip -o /tmp/figma-workspace-architect.zip -d ~/.claude/skills/

From a repo clone

# Or install from a clone of the repo
git clone https://github.com/DominikPieper/atelier-ui.git
cp -r atelier-ui/skills/figma-workspace-architect ~/.claude/skills/

The skill needs figma-console-mcp configured to do anything useful — it is the underlying MCP server the skill drives. See the Figma Setup page for the connection guide.

When the skill loads

The skill's description field is tuned so Claude Code picks it up on architectural / audit / build prompts about Figma — even when the user only says "Figma" without naming the file or library. It explicitly does not trigger on Figma → code translation requests, which are out of scope.

# Triggering examples — any of these will load the skill

"audit our Figma library"
"set up token tiers in Figma"
"should I use a Variant or a Component Property here?"
"rename color/primary to color/brand-primary safely"
"check Figma against the spec"

References

Loaded on demand by the active mode. Every reference is self-contained — opening one does not pull the others into context.

File	Summary
token-architecture.md	Three-tier model (Primitive / Semantic / Component), Modes, Variable Scopes, anti-patterns.
component-design.md	Variants vs. Component Properties vs. Instance Swap, atomic composition, slot patterns.
naming-and-file-structure.md	Slash naming, page taxonomy, _ and . prefixes for sub-components, library boundaries.
tool-map.md	figma-console-mcp tools grouped by purpose with ready-to-use figma_execute payloads.
build-workflow.md	Build mode in depth: discovery checklist, decide gates, validation, documentation requirements.
audit-checklist.md	Five architectural categories with severity tags. Pre-flight: snapshot pin + cross-source grep.
audit-verify-queries.md	Re-verify sub-mode. One verify query per audit category with auto-resolve signals.
decision-heuristics.md	Decision trees for the recurring forks (Variant vs. Property, Token tier, Mode vs. Collection).
migration-playbook.md	Refactoring an existing file safely. Coordination protocol, recipes, removal-tombstone gotcha.
code-verify.md	Code-side visual verification recipe. Storybook flow for Figma↔code parity in Light + Dark.
code-sync.md	Keeping Figma Variables in lockstep with code-side tokens. Drift sources and mode-mapping pitfalls.
iconography.md	Icon-system architecture: size stops, color binding, library-split signals.
scaffold-payload.md	Scaffold sub-mode of Build. Three-call recipe producing Cover + Tokens + Components pages.

Test scenarios

Each scenario has an input.md (the user prompt) and an expected.md (the mode + references + first tool call + regressions to flag). Scenarios are well-formedness tested in CI; behavioural grading is manual or LLM-judged.

Scenario	Mode	Summary
`audit-existing-system`	Audit	Two-year-old library, prioritised audit report.
`build-bootstrap-tokens`	Build	Bootstrap a fresh token system end-to-end.
`build-scaffold-starter`	Build (Scaffold)	One-shot starter file with three-call recipe.
`decide-variant-vs-property`	Decide	Variant vs. Component Property fork.
`migrate-rename-variable`	Migrate	Variable rename with code-side coordination.
`re-verify-stale-audit`	Audit (Re-verify)	Re-check a 3-day-old audit before acting.
`code-verify-token-rename`	Migrate (post-flight)	Browser confirmation after token consolidation.
`out-of-scope-code-gen`	Out-of-scope	Figma → code translation request — agent declines and points elsewhere.

Source

SKILL.md: https://atelier.pieper.io/.well-known/agent-skills/figma-workspace-architect/SKILL.md
Repository: https://github.com/DominikPieper/atelier-ui/tree/main/skills/figma-workspace-architect
Discovery index: /.well-known/agent-skills/index.json
License: Same as the repository (MIT). The skill is private: true on npm — distribution is via the discovery URL only.