@atelier-ui/create-workspace 0.4.1 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/package.json +1 -1
  3. package/src/generators/preset/files/claude/skills/figma-workspace-architect/SKILL.md +194 -0
  4. package/src/generators/preset/files/claude/skills/figma-workspace-architect/assets/audit-report-template.md +181 -0
  5. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-checklist.md +462 -0
  6. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-verify-queries.md +414 -0
  7. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-from-code-contract.md +87 -0
  8. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-workflow.md +260 -0
  9. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-sync.md +218 -0
  10. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-verify.md +152 -0
  11. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/component-design.md +198 -0
  12. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/decision-heuristics.md +262 -0
  13. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/iconography.md +150 -0
  14. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-generation.md +433 -0
  15. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-payload.md +490 -0
  16. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/migration-playbook.md +182 -0
  17. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/naming-and-file-structure.md +161 -0
  18. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/plugin-api-gotchas.md +79 -0
  19. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/scaffold-payload.md +279 -0
  20. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/sync-workflow.md +98 -0
  21. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/token-architecture.md +177 -0
  22. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/tool-map.md +398 -0
  23. package/src/generators/preset/files/claude/skills/uianatomy-mcp/SKILL.md +160 -0
  24. package/src/generators/preset/files/tools/design-contracts/bin/check-contracts.mjs +7 -2
  25. package/src/generators/preset/files/tools/scripts/preflight.mjs +1 -1
  26. package/src/generators/preset/preset.js +52 -4
  27. package/src/generators/preset/preset.js.map +1 -1
package/CHANGELOG.md CHANGED
@@ -1,3 +1,25 @@
1
+ ## 0.4.3 (2026-10-12)
2
+
3
+ ### 🩹 Fixes
4
+
5
+ - clean up the participant's first-hour output (R-183..R-187) ([53f38aae](https://github.com/DominikPieper/atelier-ui/commit/53f38aae))
6
+
7
+ ### ❤️ Thank You
8
+
9
+ - Claude Opus 5.5
10
+ - Dominik Pieper @DominikPieper
11
+
12
+ ## 0.4.2 (2026-10-10)
13
+
14
+ ### 🚀 Features
15
+
16
+ - **create-workspace:** ship uianatomy-mcp and figma-workspace-architect skills (ADR-0167) ([b6ef45d2](https://github.com/DominikPieper/atelier-ui/commit/b6ef45d2))
17
+
18
+ ### ❤️ Thank You
19
+
20
+ - Claude Opus 5.5
21
+ - Dominik Pieper @DominikPieper
22
+
1
23
  ## 0.4.1 (2026-10-09)
2
24
 
3
25
  ### 🚀 Features
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atelier-ui/create-workspace",
3
- "version": "0.4.1",
3
+ "version": "0.4.3",
4
4
  "description": "Nx preset for Atelier workshop workspaces",
5
5
  "keywords": [
6
6
  "nx",
@@ -0,0 +1,194 @@
1
+ ---
2
+ name: figma-workspace-architect
3
+ description: Designs, builds, audits, and improves Figma workspaces and component libraries via figma-console-mcp so they use the right Figma primitives (Variables with proper scopes, Variants, Component Properties, Auto Layout, slash naming, Modes) and stay maintainable for both designers and downstream code generation. Use this skill whenever the user asks to set up, bootstrap, structure, build, refactor, audit, review, or assess a Figma file, library, design system, token system, component set, or workspace — even if they only mention "tokens", "variables", "components", "variants", "modes", or "design system" without saying "workspace". Also trigger on the bare keyword "Figma" when it is paired with a structural/architectural/audit verb ("fix in Figma", "set up in Figma", "audit Figma", "check Figma", "update Figma to match X"); this catches the common case where the user names the surface ("Figma") rather than the artifact ("the Figma file"). Also use it before running any larger figma_execute, figma_setup_design_tokens, figma_create_variable*, or figma_arrange_component_set call so the agent makes architectural decisions before mutating Figma. Do NOT use this skill for translating Figma designs into code in a repo — that is a code-generation task. Do NOT use it as a substitute for Plugin API mechanics — the agent uses its own knowledge of the Figma Plugin API for `figma_execute` payloads.
4
+ ---
5
+
6
+ # Figma Workspace Architect
7
+
8
+ A skill for using **figma-console-mcp** ([southleft/figma-console-mcp](https://github.com/southleft/figma-console-mcp)) to build, audit, and evolve Figma workspaces that use the right Figma primitives — not just files that _look_ right.
9
+
10
+ The bar this skill sets: a workspace where a designer can find what they need without asking, where Variables have correct scopes, where Variants match the engineering prop API, where Modes carry theming instead of duplicate components, and where naming/page structure is predictable enough that any agent (or human) can navigate it cold.
11
+
12
+ ## When to load this skill
13
+
14
+ Load this skill when the user is about to:
15
+
16
+ - **Build** anything structural in Figma — a token collection, a component set, a library scaffold, an icon set, a theme/mode setup
17
+ - **Audit / review** an existing Figma file or library and ask what's wrong with it
18
+ - **Decide** between architectural options — Variant vs. Component Property, Primitive vs. Semantic Token, separate Components vs. one Variant set, new Mode vs. new Collection
19
+
20
+ Also load it **before** any of these `figma-console-mcp` write tools, because each one bakes architectural choices into the file:
21
+
22
+ - `figma_execute` — when the JS payload creates frames, components, or variables
23
+ - `figma_setup_design_tokens` — bootstraps an entire token system in one call
24
+ - `figma_create_variable_collection`, `figma_create_variable`, `figma_batch_create_variables`
25
+ - `figma_add_mode`, `figma_rename_mode`
26
+ - `figma_arrange_component_set`
27
+ - `figma_set_description` (for components — descriptions are the discoverability layer)
28
+
29
+ ## What this skill is NOT
30
+
31
+ To keep scope sharp, this skill **does not** cover:
32
+
33
+ - **Plugin API mechanics for `figma_execute`** — colors as 0–1, `await figma.loadFontAsync`, `appendChild` ordering, etc. Use general Plugin API knowledge for the payload itself. The exception is `references/plugin-api-gotchas.md`: the sizing, section, text and instance traps that general knowledge gets wrong and that cost this library real sessions — read it before any payload that creates, resizes, re-parents or edits text.
34
+ - **Figma → code translation** — generating React/Vue/Swift from a design. That is downstream of this skill.
35
+ - **Code Connect or Figma's official Dev-Mode MCP server.** Explicit user constraint: the toolchain is figma-console-mcp only. The bridge to code in this skill is **naming alignment** alone — Component names, Variant Property names/values, and Variable names matching the codebase exactly. If the user asks about Code Connect / Dev-Mode MCP, say it's out of scope here and don't pretend either is being recommended.
36
+ - **FigJam boards and Figma Slides decks.** The MCP exposes `figjam_*` and `figma_*_slide` tools; this skill targets Figma Design files only.
37
+ - **Console / plugin debugging** (`figma_get_console_logs`, `figma_watch_console`, `figma_reload_plugin`, `figma_reconnect`). Unrelated workflows.
38
+ - **Accessibility and visual-coverage auditing** — the figma-console-mcp built-in _Design System Dashboard_ MCP App already scores Naming, Tokens, Components, Accessibility, Consistency, and Coverage. This skill defers A11y and Coverage to that dashboard and focuses on **architectural** depth the dashboard does not reach.
39
+
40
+ When the user asks something out-of-scope, say so briefly and either point them at the right tool (the dashboard, code-gen workflows) or proceed with general knowledge — do not pretend this skill covers it.
41
+
42
+ ## Five modes — pick one based on the user's intent
43
+
44
+ ### Build mode
45
+
46
+ Triggered by verbs like _create, set up, bootstrap, scaffold, build, generate, add, refactor_.
47
+
48
+ Never start writing to Figma directly. Run this loop:
49
+
50
+ 1. **Discovery.** Call `figma_get_file_data` (or `figma_get_design_system_kit` for a one-call full snapshot, or `figma_get_variables` + `figma_get_styles` if the file is large) to see what already exists. Read the existing structure before adding to it. Skipping this is the #1 cause of duplicate or conflicting tokens.
51
+ 2. **Decide.** Resolve every architectural question before any write tool. Use `references/decision-heuristics.md` for the common ones (Variant vs. Property, Token tier, Mode vs. Collection, Section vs. Frame, etc.). If a decision genuinely cannot be made without the user, ask — don't guess.
52
+ 3. **Map tools.** Pick the right tool for each step using `references/tool-map.md`. Prefer `figma_setup_design_tokens` and `figma_batch_*` over loops of single calls; they are 10–50× faster and atomic. For single-property mutations, prefer targeted node-write tools over `figma_execute`.
53
+ 4. **Execute.** Run the writes. Return all created/mutated node IDs from any `figma_execute` payload — subsequent calls reference them.
54
+ 5. **Validate.** Call `figma_capture_screenshot` (live, post-write) — `figma_take_screenshot` (REST) can be cache-stale right after a mutation. Look for cropped text, wrong scopes (e.g. a color variable showing up in spacing pickers), missing descriptions. Fix issues with targeted follow-ups, not a rebuild.
55
+ 6. **Document.** Use `figma_set_description` on every Component, Component Set, and shared Style. The description is what designers see in the asset panel and what Dev Mode surfaces — undocumented components are invisible.
56
+ 7. **Annotate.** `figma_set_annotations` for the surgical implementation details that don't belong in the description — focus-ring delivery, animation easing, A11y exceptions, tap-target extensions. Annotations surface in the Dev-Mode Inspect panel.
57
+ 8. **Mark Ready for Dev.** Set `devStatus = { type: 'READY_FOR_DEV' }` on the containing Section / Frame / Component via `figma_execute`. Without this, downstream Dev-Mode UI and consuming agents treat the artifact as work-in-progress and skip it.
58
+
59
+ The detailed Build playbook is in `references/build-workflow.md`, including the pre-publish checklist.
60
+
61
+ #### Scaffold sub-mode — one-shot starter file
62
+
63
+ Triggered by _scaffold, template, starter, quickstart, bootstrap a new file_ (when the user wants a working skeleton in one turn, not an iterative dialogue).
64
+
65
+ Skip the full Discovery → Decide loop and run a fixed three-call recipe that produces Cover + Tokens + Components pages with placeholder content. The output is a _skeleton_ the user is expected to replace, not a finished system. See `references/scaffold-payload.md` for the recipe and the after-scaffold checklist that the agent must hand back to the user.
66
+
67
+ Use the regular Build loop (not Scaffold) when:
68
+
69
+ - The user already has a file and wants additions — Discovery first.
70
+ - The user has specific values to seed — use those, not the placeholder palette.
71
+ - The user wants something polished — Scaffold ships placeholders intentionally.
72
+
73
+ #### Inventory sub-mode — visual library catalog
74
+
75
+ Triggered by _generate inventory, build gallery, library catalog, stickersheet, library overview_ — when the user wants a one-page visual reference of every published Component / Component Set in the file.
76
+
77
+ The output is a dedicated `📋 Inventory` page: one Section per top-level slash category, one card per component, each card carrying a header + status badge + default-variant preview + meta row + property table + optional description footer. Cards adopt a light or dark surface based on contextual background detection so the preview reads correctly.
78
+
79
+ Run it after the regular Build loop's **Validate** step (so half-shipped components don't pollute the gallery) — or stand-alone against an existing library when the user wants a fresh visual reference. See `references/inventory-generation.md` for the seven-phase pipeline and `references/inventory-payload.md` for the ready-to-paste `figma_execute` snippets.
80
+
81
+ Build the gallery **section by section** — one `figma_execute` per top-level Section, components chunked in groups of 25 with `setTimeout(0)` yields between chunks. A 500-component library otherwise blows the plugin host or saturates the figma_execute size cap. Sections beyond ~150 components get split across multiple calls.
82
+
83
+ ### Audit mode
84
+
85
+ Triggered by _audit, review, check, assess, what's wrong with, how good is_.
86
+
87
+ Two layers, run in this order:
88
+
89
+ 1. **Run the built-in Design System Dashboard MCP App** first if the client supports MCP Apps (Claude Desktop with `ENABLE_MCP_APPS=true`). Ask the user something like "audit the design system" — this gives an immediate Lighthouse-style score across Naming, Tokens, Components, A11y, Consistency, and Coverage. Without MCP Apps, `figma_audit_design_system_report` returns the same six-category scoring as plain JSON (weights: Naming 25 %, Tokens 20 %, Components 20 %, Consistency 15 %, A11y 10 %, Coverage 10 %; five-minute cache). Use either as the **breadth** layer; do not duplicate it.
90
+ 2. **Run the architectural deep-audit** in `references/audit-checklist.md`. This is the **depth** layer: five categories (Token Architecture, Component Design, Naming, File Structure, Engineering-Sync Readiness), each finding tagged with a severity (Blocker / Critical / Warning / Suggestion) and a concrete fix.
91
+
92
+ The Component Design category enforces four hard requirements every library has to meet — see _Required principles_ in `references/component-design.md`:
93
+
94
+ - **CD6** Component descriptions surface intent (use-when, don't-use-when, signals).
95
+ - **CD7** Every interactive component covers all six states (default, hover, focus, disabled, error, loading).
96
+ - **CD8** Fills, strokes, text, and spacing bind to Variables, never hardcoded values.
97
+ - **CD9** Components built with Auto Layout, not fixed frames.
98
+
99
+ These are the drift-sources an agent-driven workflow notices first. Treat any Critical finding under them as a real fix, not a cosmetic one.
100
+
101
+ Two rules for the _fix_ column of every finding, learned from an audit that called a collection "dead, zero risk to delete" without having read the second file that consumed it: a fix that **deletes, renames or rebinds** a Variable, Collection, Mode or Variant is a Migrate operation and carries the playbook's safety class (Breaking → additive coordination protocol), never "just remove it"; and a Token Architecture finding may say **"unused" or "duplicate" only after enumerating every collection's consumers** — the docs-site collection, a second library file, `codeSyntax` bindings — with the tool call that proved it named in the finding.
102
+
103
+ Before writing the report, do the two pre-flight passes called out in the checklist's _Inputs_ section: **pin the snapshot** (git SHA + Figma `lastModified`) and **cross-source-grep** any Variable / Variant value you're about to flag. Both are cheap and prevent the most common audit failure mode — findings that were already true at audit time but stale by the time someone acts on them, or findings that look bad in Figma but are actually load-bearing in code with subtly different semantics.
104
+
105
+ Output the result using `assets/audit-report-template.md`. Always lead with the priority list — Blockers and Criticals at the top, with effort estimates. Do not bury the punchline in a category-by-category walk-through.
106
+
107
+ #### Re-verify sub-mode — re-check an existing audit
108
+
109
+ Triggered when an audit report already exists and the user asks "is X still relevant?", "what's actually left?", "re-check this audit", "re-verify before I act", or hands you an audit `.md` more than a few hours old.
110
+
111
+ Don't redo the full deep-audit. Open `references/audit-verify-queries.md` and run _only_ the verify query for each open finding. Emit a `still-open / auto-resolved / state-shifted` line per finding. Update the report's "Re-verify" table with the result (template field at the bottom of `assets/audit-report-template.md`) — drop `auto-resolved` rows from the priority list, and rewrite `state-shifted` rows before acting.
112
+
113
+ This catches the most common audit failure mode: a stale `.md` directing fixes for findings that have already been resolved or have shifted in shape since audit time.
114
+
115
+ **Auto-prompt re-verify when the audit looks old.** When the user references
116
+ an audit `.md` more than ~1 hour stale (check the file `mtime` or the
117
+ `Generated against` git SHA against current `HEAD`), don't wait for them to
118
+ ask — say something like _"this audit is from N hours ago; let me re-verify
119
+ open findings before we act on them"_ and run the Re-verify sub-mode. One
120
+ read of `references/audit-verify-queries.md` plus one verify-pass per open
121
+ finding is far cheaper than fixing items that already auto-resolved.
122
+
123
+ ### Decide mode
124
+
125
+ Triggered by either/or questions or "should I…" framings. The user is at a fork.
126
+
127
+ Go straight to `references/decision-heuristics.md`, find the matching decision, give the recommendation **with the reasoning in one or two sentences**, and offer the alternative path with the trade-off. Don't write a treatise — the user is trying to move on.
128
+
129
+ ### Migrate mode
130
+
131
+ Triggered by _rename, split, restructure, refactor, deprecate, retire, replace_ — when the user wants to **change** an existing structure without breaking downstream consumers (designers, code, libraries that depend on this file).
132
+
133
+ Never run a Breaking operation alone. Open `references/migration-playbook.md` and:
134
+
135
+ 1. Pre-flight: re-discover, snapshot, classify each planned change as Safe / Mostly safe / Breaking.
136
+ 2. For Breaking changes: enforce the additive coordination protocol (add new shape alongside old → wait one cycle → migrate consumers → remove old). Skipping this is the source of "the design system broke prod" stories.
137
+ 3. Use the recipes in the playbook for the common patterns: Variable rename, Mode addition, Variant Set split, Primitive→Semantic promotion, Library split.
138
+ 4. Post-flight: re-audit, diff against the snapshot, update Component descriptions, run the codesync exporter, log the change on the Cover page. **If the change has a downstream visual effect in the consuming code repo** (mode-aware token, contrast-relevant fix, variant rename), run the recipe in `references/code-verify.md` to confirm Figma and code render the same thing in both Light and Dark — Figma alone won't catch decorator wiring or stale CSS-variable bindings.
139
+
140
+ If the migration is large enough to span sessions, finish each session in a self-contained state — never leave the file mid-restructure overnight.
141
+
142
+ ### Sync mode
143
+
144
+ Triggered when one side moved and the other must catch up. Trigger phrases: _"propagate to Figma"_, _"sync the lib tokens"_, _"keep Figma and code in lockstep"_, _"make Figma match the new spec"_. Different from Migrate: Migrate plans a coordinated structural change; Sync handles value drift after one side has already moved.
145
+
146
+ Open `references/sync-workflow.md` and run the four steps: direction → diff → batch-or-script → validate. Output a Sync summary (see "Output expectations" below).
147
+
148
+ If the diff turns out to include adds / removes / renames rather than only value updates, stop and switch to Migrate — Sync's batch-and-script approach won't apply the additive coordination protocol downstream consumers need.
149
+
150
+ ## Mode routing — quick reference
151
+
152
+ | User says… | Mode | First action |
153
+ | --------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------ |
154
+ | "create / build / set up / bootstrap…" | Build | `figma_get_file_data` for discovery |
155
+ | "scaffold / starter / template / quickstart a new file…" | Build (Scaffold sub-mode) | Open `references/scaffold-payload.md`, run the three-call recipe |
156
+ | "generate inventory / build gallery / library catalog / stickersheet…" | Build (Inventory sub-mode) | Open `references/inventory-generation.md`; run the seven-phase pipeline section-by-section |
157
+ | "audit / review / check / assess / how good is…" | Audit | Try Design System Dashboard MCP App; then deep-audit |
158
+ | "is finding X still relevant?", "re-verify this audit…" | Audit (Re-verify sub-mode) | Open `references/audit-verify-queries.md`; run only the verify queries for open findings |
159
+ | "should I use a Variant or…?", "is it better to…?" | Decide | Open `references/decision-heuristics.md` |
160
+ | "rename / split / restructure / deprecate / migrate…" | Migrate | Open `references/migration-playbook.md`; run pre-flight |
161
+ | "verify in code", "check the rendered result", "does dark mode look right…" | Migrate (post-flight) | Open `references/code-verify.md`; run the Storybook recipe |
162
+ | "propagate to Figma / sync the tokens / make Figma match…" | Sync | `figma_get_variables` → diff → batch update; see `references/code-sync.md` |
163
+ | "fix this issue…" (specific, after an audit) | Migrate | Use the playbook's recipe for the matching operation |
164
+ | "translate this Figma component into code…" | (none) | This is out of scope — point at code-gen workflow |
165
+
166
+ ## References — load on demand
167
+
168
+ Each file is self-contained and loaded only when relevant. Don't load everything up front.
169
+
170
+ - **`references/tool-map.md`** — figma-console-mcp tools grouped by purpose (read, create-tokens, create-components, validate, document). Read first time the agent isn't sure which tool to use. Includes ready-to-use `figma_execute` and `figma_setup_design_tokens` payloads.
171
+ - **`references/plugin-api-gotchas.md`** — the `figma_execute` traps that bit this repo: `resize()` flips sizing to FIXED, `layoutMode` after `resize()` reverts to AUTO, `SPACE_BETWEEN` centres a lone child, sections leave their children behind, text needs `textAutoResize='HEIGHT'` to wrap, instance text edits fail silently, REST 403s, batch caps. Load before any frame-creating or text-editing payload.
172
+ - **`references/token-architecture.md`** — three-tier token model (Primitive / Semantic / Component), Modes, Variable Scopes (this is where most setups go wrong), naming, anti-patterns.
173
+ - **`references/component-design.md`** — Variants vs. Component Properties vs. Instance Swap, atomic composition, slot patterns, Variant Property naming that matches engineering props.
174
+ - **`references/naming-and-file-structure.md`** — slash naming, page layout (Cover / Tokens / Icons / Components / Patterns), `_` and `.` prefixes for unpublished sub-components, library splitting heuristics.
175
+ - **`references/build-workflow.md`** — Build mode in depth: discovery checklist, decide gates, validation steps, documentation requirements.
176
+ - **`references/build-from-code-contract.md`** — Build mode when the code already states the component: prop contract → matrix decision → bound variants → names the gate accepts → description, annotations, ready-for-dev, inventory → the repo's own closing gate. Generic recipe; its closing worked example is the Atelier monorepo's own setup and does not apply to a generated workspace.
177
+ - **`references/audit-checklist.md`** — five architectural categories, severity definitions, per-finding fix template. Includes pre-flight steps for snapshot pinning and cross-source grep.
178
+ - **`references/audit-verify-queries.md`** — Re-verify sub-mode. One verify query per audit category with auto-resolve signals; output format for `still-open / auto-resolved / state-shifted` per finding.
179
+ - **`references/code-verify.md`** — code-side visual verification recipe. Storybook + browser-automation flow to confirm Figma↔code parity in Light + Dark after token/variant changes. Common traps (stale theme decorators, web-component selectors, HMR caching).
180
+ - **`references/decision-heuristics.md`** — decision trees for the recurring forks.
181
+ - **`references/code-sync.md`** — keeping Figma Variables in lockstep with code-side tokens (CSS / JSON / framework libraries). Direction-of-truth, sync approaches, mode-mapping pitfalls, drift sources.
182
+ - **`references/migration-playbook.md`** — refactoring an existing file safely. Safety classes per operation, the additive coordination protocol, recipes for Variable renames, Mode adds, Variant-Set splits, semantic-tier promotions, and Library splits.
183
+ - **`references/iconography.md`** — icon-system architecture. Size stops, internal boxed-model layout, Component-vs-vector heuristic, color-binding (never hardcode fills), naming categories, library-split signals, audit checklist.
184
+ - **`references/scaffold-payload.md`** — Scaffold sub-mode recipe. Three-call sequence (`figma_setup_design_tokens` + `figma_execute` + `figma_arrange_component_set`) producing Cover + Tokens + Components pages with placeholder content; after-scaffold checklist for the user.
185
+ - **`references/inventory-generation.md`** — Inventory sub-mode. Seven-phase pipeline (Discover → Group → Scaffold → Populate → Card builder → Mark Ready → Validate) for generating a visual library catalog. Layout token contract, internal grouping schema, batching contract (one Section per `figma_execute`, chunks of 25 with yields, 150-component split rule).
186
+ - **`references/inventory-payload.md`** — Ready-to-paste `figma_execute` snippets for the Inventory sub-mode: discover, scaffold, populate-one-section (with all card-builder helpers), mark-ready + TOC, and the optional contextual-background cache clear.
187
+ - **`references/sync-workflow.md`** — Sync mode in depth: direction-of-truth, diff classification (value-update / dimension-change / structural-bailout-to-Migrate), batch-or-script execution, audit + parity-check validation, and the escalate-to-Migrate signals.
188
+
189
+ ## Output expectations
190
+
191
+ - **Audit report** — always use `assets/audit-report-template.md`. Priority list first, then findings by category. Severity tags on every finding. Each finding has a one-line fix.
192
+ - **Build summary** — after a build, return what was created (counts: collections, modes, variables, components), what was validated (screenshots taken, descriptions set), and what is left undone (e.g. "Code Connect mappings — out of scope here, see [TODO]").
193
+ - **Decision answer** — recommendation in the first sentence, reasoning in the second, the alternative and its trade-off in the third. Stop there.
194
+ - **Sync summary** — after a code↔Figma sync run, return: direction (code→Figma or Figma→code), counts (Variables updated, frames resized, components touched), audit deltas (which scores moved up/down/held), known false-positives encountered (so the user doesn't re-fix them), and anything left undone. One small table beats prose here.
@@ -0,0 +1,181 @@
1
+ # Figma Workspace Audit — {file name or library name}
2
+
3
+ **File:** `{Figma file URL or key}`
4
+ **Audited:** {ISO date}
5
+ **Generated against:** `{git short SHA in the consuming repo, if applicable}` · Figma file last-edited `{ISO date from figma_get_file_data.lastModified, if available}`
6
+ **Mode availability for audit:** {Local + Bridge / Remote SSE only}
7
+
8
+ > **Audit freshness:** This is a snapshot. Before acting on a finding more than a few hours old, re-verify the underlying state — Figma edits or code commits between audit time and now can have already resolved or shifted findings. The "Generated against" line above is the pin point.
9
+
10
+ ## Overall
11
+
12
+ > **Architectural verdict:** {one sentence — e.g. "Solid foundation but missing a Semantic layer; dark mode is currently impossible."}
13
+
14
+ | Severity | Count |
15
+ | ---------- | ----- |
16
+ | Blocker | {n} |
17
+ | Critical | {n} |
18
+ | Warning | {n} |
19
+ | Suggestion | {n} |
20
+
21
+ If the figma-console-mcp Design System Dashboard MCP App was run as part of this audit, include its overall score and category scores here. Use it as the breadth view; this report covers depth.
22
+
23
+ | Dashboard category | Score | Notes |
24
+ | ------------------ | ------ | ------- |
25
+ | Naming | {/100} | {brief} |
26
+ | Tokens | {/100} | {brief} |
27
+ | Components | {/100} | {brief} |
28
+ | Accessibility | {/100} | {brief} |
29
+ | Consistency | {/100} | {brief} |
30
+ | Coverage | {/100} | {brief} |
31
+
32
+ ## Priority list
33
+
34
+ Top items to fix, ordered: Blockers first, then Criticals by ascending effort.
35
+
36
+ | # | Severity | Finding ID | What | Effort | Fix |
37
+ | --- | -------- | ---------- | ---------------------------------------------- | ------ | -------------------------------------------- |
38
+ | 1 | Blocker | TA2 | No Semantic tier; dark mode impossible | L | Add Semantic collection, alias from existing |
39
+ | 2 | Critical | TA4 | All variables use `ALL_SCOPES` | M | Set scopes per type via `figma_execute` |
40
+ | 3 | Critical | CD2 | Variant values `Small` mismatch code `sm` | S | Rename Variant values to match code |
41
+ | 4 | Critical | N1 | 8 components named `BTN_*`, code uses `Button` | S | Rename components |
42
+ | ... | ... | ... | ... | ... | ... |
43
+
44
+ Effort key: **S** = single tool call. **M** = a few coordinated calls. **L** = multi-day refactor.
45
+
46
+ ## Findings by category
47
+
48
+ ### 1 — Token Architecture
49
+
50
+ #### TA1 — Tier separation
51
+
52
+ - **State:** {what was found}
53
+ - **Severity:** {Blocker / Critical / Warning / Suggestion / Pass}
54
+ - **Fix:** {one-line actionable}
55
+ - **Effort:** {S/M/L}
56
+ - **Verified at:** {ISO timestamp — set when re-verify mode confirms the State is still current; omit on first audit}
57
+
58
+ #### TA2 — Mode placement
59
+
60
+ - **State:** ...
61
+ - **Severity:** ...
62
+ - **Fix:** ...
63
+ - **Effort:** ...
64
+
65
+ #### TA3 — Aliasing
66
+
67
+ ...
68
+
69
+ #### TA4 — Variable Scopes
70
+
71
+ ...
72
+
73
+ #### TA5 — Variables vs. Styles coverage
74
+
75
+ ...
76
+
77
+ ### 2 — Component Design
78
+
79
+ #### CD1 — Variant axis explosion
80
+
81
+ ...
82
+
83
+ #### CD2 — Variant Property naming vs. code
84
+
85
+ ...
86
+
87
+ #### CD3 — Show/hide encoded as Variants
88
+
89
+ ...
90
+
91
+ #### CD4 — Icons modeled as Variants
92
+
93
+ ...
94
+
95
+ #### CD5 — Composition / atomic structure
96
+
97
+ ...
98
+
99
+ #### CD6 — Component descriptions
100
+
101
+ ...
102
+
103
+ ### 3 — Naming
104
+
105
+ #### N1 — Component names match engineering
106
+
107
+ ...
108
+
109
+ #### N2 — Variable path conventions
110
+
111
+ ...
112
+
113
+ #### N3 — Slash naming for Variants
114
+
115
+ ...
116
+
117
+ ### 4 — File Structure
118
+
119
+ #### FS1 — Working designs in the library file
120
+
121
+ ...
122
+
123
+ #### FS2 — Page organization
124
+
125
+ ...
126
+
127
+ #### FS3 — Sub-components polluting the asset panel
128
+
129
+ ...
130
+
131
+ ### 5 — Engineering-Sync Readiness
132
+
133
+ #### ES1 — Token names match codebase
134
+
135
+ ...
136
+
137
+ #### ES2 — Component prop API matches code
138
+
139
+ ...
140
+
141
+ #### ES3 — Code Connect / mapping setup
142
+
143
+ ...
144
+
145
+ #### ES4 — Documentation handoff
146
+
147
+ ...
148
+
149
+ ## What's healthy
150
+
151
+ A short list of things the workspace gets right. Don't skip this — auditors who only list problems leave the team with no sense of what's working.
152
+
153
+ - {e.g. "Primitives are well-organized in a dedicated collection."}
154
+ - {e.g. "Component naming uses slash hierarchy consistently."}
155
+
156
+ ## Recommended next steps
157
+
158
+ A short numbered list, in order. Aim for 3–7 items. Group related fixes when they can be tackled together.
159
+
160
+ 1. {Step 1 — typically a Blocker fix or a Critical that unblocks multiple others.}
161
+ 2. {Step 2}
162
+ 3. {Step 3}
163
+
164
+ ## Re-verify (optional, generated only after a re-verify pass)
165
+
166
+ If this audit has been re-verified against current state since the original pass, list the result per finding:
167
+
168
+ | Finding ID | Status | Current state | Verified at |
169
+ | ---------- | ------------- | --------------------------------------------------------------------------------- | --------------- |
170
+ | TA4 | auto-resolved | 0 non-BOOLEAN ALL_SCOPES variables remain (was 72) | {ISO timestamp} |
171
+ | HC | state-shifted | Inputs section is now `#f2f7ff`; 8 other section titles still hardcoded `#000000` | {ISO timestamp} |
172
+ | A11y-OL | still-open | outline + secondary md loading spinner unchanged | {ISO timestamp} |
173
+
174
+ Drop `auto-resolved` rows from the active priority list. Rewrite the `state-shifted` rows before acting. Treat the timestamp as the new pin point for that finding.
175
+
176
+ ## Notes
177
+
178
+ Anything the user should know that didn't fit above:
179
+
180
+ - {e.g. "Dashboard categories scoring below 60 are out of this skill's scope and are addressed by figma-console-mcp's built-in checks."}
181
+ - {e.g. "Code Connect is not part of figma-console-mcp; if the team wants it, recommend Figma's official Dev Mode MCP alongside."}