@atelier-ui/create-workspace 0.4.1 → 0.4.2

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 (26) hide show
  1. package/CHANGELOG.md +11 -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/scripts/preflight.mjs +1 -1
  25. package/src/generators/preset/preset.js +52 -4
  26. package/src/generators/preset/preset.js.map +1 -1
@@ -0,0 +1,414 @@
1
+ # Audit verify queries
2
+
3
+ Per-category queries for **Re-verify mode** — checking whether a finding is still open before estimating effort or applying a fix. Run these when:
4
+
5
+ - A finding from a prior audit needs current-state confirmation before action.
6
+ - An effort estimate seems oversized — verify whether the work has already been done implicitly between the audit and now.
7
+ - A user asks "is finding X still relevant?" or "what's actually left?".
8
+
9
+ Each entry below names a query, what counts as a pass, and the auto-resolve signal that tells you the finding is closed and no fix is needed.
10
+
11
+ ## Output format
12
+
13
+ For each finding being re-verified, emit one line:
14
+
15
+ ```
16
+ {finding-id}: {still-open | auto-resolved | state-shifted} — {one-sentence current state}
17
+ ```
18
+
19
+ `still-open` = the finding's bad state still holds. Effort estimate stands.
20
+ `auto-resolved` = the bad state is gone. Drop the finding from the priority list.
21
+ `state-shifted` = current state differs from the audit's description but isn't fully resolved (e.g. "8 hardcoded fills now, was 1 — broader than the audit said"). Re-write the finding before acting.
22
+
23
+ ## Token Architecture
24
+
25
+ ### TA1 — Tier separation
26
+
27
+ ```
28
+ figma_get_variables (format=summary, verbosity=inventory)
29
+ → count distinct variableCollections
30
+ → inspect each name
31
+ ```
32
+
33
+ **Pass:** ≥ 2 collections with names matching the Primitive / Semantic / Component pattern (e.g. `Primitive Tokens`, `UI Tokens`, `Component Tokens`).
34
+ **Auto-resolve signal:** the collection separation already matches the audit's recommended tier model.
35
+
36
+ ### TA2 — Mode placement
37
+
38
+ ```
39
+ figma_get_variables (verbosity=standard)
40
+ → for each variableCollection: collection.modes.length
41
+ ```
42
+
43
+ **Pass:** modes only on the Semantic-tier collection. Primitive collection has 1 mode (`Default` or single unnamed).
44
+ **Auto-resolve signal:** Primitive collection mode-count is 1 AND Semantic collection mode-count > 1.
45
+
46
+ ### TA3 — Aliasing
47
+
48
+ ```
49
+ figma_get_variables (enrich=true, include_dependencies=true)
50
+ → for sample of Semantic vars (10 random): valuesByMode entries are { type: 'VARIABLE_ALIAS', id: ... }, not raw values
51
+ ```
52
+
53
+ **Pass:** ≥ 80% of sampled Semantic variables alias Primitives.
54
+ **Auto-resolve signal:** alias-rate at or above the threshold.
55
+ **Caveat:** this is a sample-based check; a full walk is heavier and only worth running if the sample suggests drift.
56
+
57
+ ### TA4 — Variable Scopes
58
+
59
+ ```
60
+ figma_execute:
61
+ const vars = await figma.variables.getLocalVariablesAsync();
62
+ const buckets = {};
63
+ for (const v of vars) {
64
+ if (v.resolvedType === 'BOOLEAN') continue; // feature flags are exempt
65
+ const key = v.scopes.length === 0 ? '(empty)' : v.scopes.sort().join(',');
66
+ buckets[key] = (buckets[key] || 0) + 1;
67
+ }
68
+ return buckets;
69
+ ```
70
+
71
+ **Pass:** `ALL_SCOPES` count among non-BOOLEAN variables is 0.
72
+ **Auto-resolve signal:** the bucket map has no `ALL_SCOPES` key.
73
+ **Important:** BOOLEAN variables (`feature/*` flags) are never bound into design properties; their `ALL_SCOPES` is a no-op and must not be counted.
74
+
75
+ ### TA5 — Variables vs. Styles coverage
76
+
77
+ ```
78
+ figma_get_styles
79
+ → count COLOR + EFFECT + TEXT styles
80
+ figma_lint_design (rules=['no-text-style', 'no-color-style'])
81
+ → count text/color nodes not using styles
82
+ ```
83
+
84
+ **Pass:** style count is low relative to Variable count, OR the lint shows < 5 nodes per page bypassing styles.
85
+ **Auto-resolve signal:** lint findings under 5 per page.
86
+
87
+ ### TA6 — Variable mode count vs. plan tier
88
+
89
+ ```
90
+ figma_execute:
91
+ const collections = await figma.variables.getLocalVariableCollectionsAsync();
92
+ return collections.map(c => ({ name: c.name, modeCount: c.modes.length, modes: c.modes.map(m => m.name) }));
93
+ ```
94
+
95
+ Compare against the team's plan-tier ceiling (Free=1, Pro=4, Org=10, Enterprise=40). If unknown, ask the user.
96
+
97
+ **Pass:** all collections at or below `ceiling − 2`.
98
+ **Auto-resolve signal:** every collection's mode count is well below the ceiling.
99
+
100
+ ## Component Design
101
+
102
+ ### CD1 — Variant axis explosion
103
+
104
+ ```
105
+ figma_search_components (limit=25)
106
+ → for each component-set: figma_get_component_details to fetch variant count
107
+ ```
108
+
109
+ **Pass:** no component-set has > 24 variants (a typical threshold; raise per-team).
110
+ **Auto-resolve signal:** all component-sets at or below the threshold.
111
+
112
+ ### CD2 — Variant Property naming vs. code
113
+
114
+ ```
115
+ 1. figma_get_component_details on each component-set
116
+ → list variant property names + values
117
+ 2. Cross-source grep in code repo:
118
+ grep -rEn "variant\s*[:=]\s*['\"]\w+['\"]" libs/ src/ (adjust per repo)
119
+ 3. Diff: every Figma value should appear in code; every code value should appear in Figma.
120
+ ```
121
+
122
+ **Pass:** zero diffs.
123
+ **Auto-resolve signal:** intersection of Figma values and code values is identical.
124
+
125
+ ### CD4 — Icons modeled as Variants
126
+
127
+ ```
128
+ figma_execute:
129
+ await figma.loadAllPagesAsync();
130
+ const iconsPage = figma.root.children.find(p => p.name === 'Icons' || /icon/i.test(p.name));
131
+ return {
132
+ pageExists: !!iconsPage,
133
+ componentSetCount: iconsPage ? iconsPage.findAll(n => n.type === 'COMPONENT_SET').length : 0,
134
+ componentCount: iconsPage ? iconsPage.findAll(n => n.type === 'COMPONENT').length : 0
135
+ };
136
+ ```
137
+
138
+ **Pass:** Icons page exists AND has ≥ 1 ComponentSet (or ≥ N standalone Components, per-team).
139
+ **Auto-resolve signal:** componentSetCount > 0 OR componentCount above team threshold.
140
+
141
+ ### CD6 — Component description content (intent + use)
142
+
143
+ ```
144
+ figma_execute:
145
+ const sets = (await figma.root.findAllAsync(n => n.type === 'COMPONENT_SET'));
146
+ return sets.map(s => {
147
+ const d = s.description || '';
148
+ return {
149
+ name: s.name,
150
+ descLen: d.length,
151
+ hasUseWhen: /\b(use\s+when|when\s+to\s+use)\b/i.test(d),
152
+ hasDontUse: /\b(don['’]?t\s+use|when\s+not\s+to\s+use|avoid)\b/i.test(d),
153
+ hasSignals: /\b(signal|indicates?|conveys?)\b/i.test(d),
154
+ onlyRestatesName: d.replace(/\s+/g, ' ').trim().toLowerCase().includes(s.name.toLowerCase())
155
+ && d.length < (s.name.length + 20)
156
+ };
157
+ });
158
+ ```
159
+
160
+ **Pass:** every component-set has `descLen ≥ 80` AND at least two of `{hasUseWhen, hasDontUse, hasSignals}` true AND `onlyRestatesName === false`.
161
+ **Auto-resolve signal:** all four flags satisfied across every component-set.
162
+
163
+ ### CD7 — Complete interactive-state variant coverage
164
+
165
+ Run only against **interactive** component-sets. Maintain an explicit list per file (e.g. `Button`, `Input`, `Select`, `Combobox`, `Checkbox`, `Radio`, `RadioGroup`, `Toggle`, `TabGroup`, `Stepper`, `Pagination`, `Table`).
166
+
167
+ ```
168
+ figma_execute:
169
+ const INTERACTIVE = new Set([/* per-file list */]);
170
+ const REQUIRED = ['default','hover','focus','disabled','error','loading'];
171
+ const sets = await figma.root.findAllAsync(n => n.type === 'COMPONENT_SET');
172
+ return sets.filter(s => INTERACTIVE.has(s.name)).map(s => {
173
+ const stateProp = (s.componentPropertyDefinitions || {}).state
174
+ ?? Object.entries(s.componentPropertyDefinitions || {})
175
+ .find(([k]) => /state/i.test(k))?.[1];
176
+ const values = stateProp ? stateProp.variantOptions || [] : [];
177
+ const present = REQUIRED.filter(r => values.some(v => v.toLowerCase() === r));
178
+ const missing = REQUIRED.filter(r => !present.includes(r));
179
+ return { name: s.name, present, missing, nonStandardValues: values.filter(v => !REQUIRED.includes(v.toLowerCase())) };
180
+ });
181
+ ```
182
+
183
+ **Pass:** every interactive component-set returns `missing: []` AND `nonStandardValues: []` (or the non-standard values are documented exceptions tagged in the report).
184
+ **Auto-resolve signal:** zero `missing` entries, zero un-tagged `nonStandardValues`.
185
+
186
+ ### CD8 — Token-linked styles
187
+
188
+ Sample 5–8 representative components across categories (one input-family, one display, one navigation, one overlay, one feedback). For each, check that fills, strokes, text, and Auto-Layout spacing all carry `boundVariables`.
189
+
190
+ ```
191
+ figma_execute:
192
+ const SAMPLES = [/* component-set node IDs to spot-check */];
193
+ const out = [];
194
+ for (const id of SAMPLES) {
195
+ const node = await figma.getNodeByIdAsync(id);
196
+ if (!node) continue;
197
+ const findings = [];
198
+ node.findAll(n => true).forEach(child => {
199
+ const bv = child.boundVariables || {};
200
+ if (Array.isArray(child.fills) && child.fills.some(f => f.type === 'SOLID') && !bv.fills) {
201
+ findings.push({ kind: 'unbound-fill', path: child.name });
202
+ }
203
+ if (Array.isArray(child.strokes) && child.strokes.length > 0 && !bv.strokes) {
204
+ findings.push({ kind: 'unbound-stroke', path: child.name });
205
+ }
206
+ if (child.type === 'TEXT' && !bv.fills && !child.textStyleId) {
207
+ findings.push({ kind: 'unbound-text-fill', path: child.name });
208
+ }
209
+ if (child.layoutMode && child.layoutMode !== 'NONE') {
210
+ const SPACING_KEYS = ['paddingLeft','paddingRight','paddingTop','paddingBottom','itemSpacing'];
211
+ SPACING_KEYS.forEach(k => {
212
+ if (typeof child[k] === 'number' && child[k] > 0 && !(bv[k])) {
213
+ findings.push({ kind: 'unbound-spacing', path: child.name, prop: k, value: child[k] });
214
+ }
215
+ });
216
+ }
217
+ });
218
+ out.push({ id, name: node.name, findings: findings.slice(0, 25) });
219
+ }
220
+ return out;
221
+ ```
222
+
223
+ **Pass:** zero findings across the sampled components.
224
+ **Auto-resolve signal:** every sample returns an empty `findings` array. (When findings are non-empty but expected — e.g. an intentionally decorative demo node — the report should call them out as documented exceptions.)
225
+
226
+ ### CD9 — Auto Layout adoption
227
+
228
+ ```
229
+ figma_execute:
230
+ const sets = await figma.root.findAllAsync(n => n.type === 'COMPONENT_SET');
231
+ return sets.map(s => {
232
+ const variants = s.children.filter(c => c.type === 'COMPONENT');
233
+ const noAutoLayout = variants.filter(v => v.layoutMode === 'NONE').length;
234
+ const totalChildren = variants.reduce((acc, v) => acc + v.findAll(n => n.type === 'FRAME' || n.type === 'COMPONENT' || n.type === 'INSTANCE').length, 0);
235
+ const innerNoAutoLayout = variants.reduce((acc, v) =>
236
+ acc + v.findAll(n => (n.type === 'FRAME') && n.layoutMode === 'NONE' && (n.children || []).length > 0).length, 0);
237
+ return { name: s.name, variantCount: variants.length, rootMissing: noAutoLayout, innerMissing: innerNoAutoLayout, innerTotal: totalChildren };
238
+ });
239
+ ```
240
+
241
+ **Pass:** every entry has `rootMissing === 0`. `innerMissing` should be < ~10% of `innerTotal` (a few small absolute-positioned helpers are tolerable; large numbers indicate the component still needs reflow work).
242
+ **Auto-resolve signal:** all `rootMissing === 0` AND each component's `innerMissing / innerTotal < 0.1`.
243
+
244
+ ## Naming
245
+
246
+ ### N1 — Component names match engineering
247
+
248
+ ```
249
+ 1. figma_search_components → list all component-set names
250
+ 2. Cross-source grep:
251
+ ls libs/*/src/lib/ (or framework's component dir)
252
+ 3. Diff: every Figma component-set should map 1:1 to a code-side component.
253
+ ```
254
+
255
+ **Pass:** zero unmatched names on either side (allowing for the workspace's naming-rule, e.g. `Llm<Name>` Figma ↔ `Llm<Name>` code).
256
+ **Auto-resolve signal:** intersection size equals both source set sizes.
257
+
258
+ ### N2 — Variable path conventions
259
+
260
+ ```
261
+ figma_execute:
262
+ const vars = await figma.variables.getLocalVariablesAsync();
263
+ const offenders = vars.filter(v => !/^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*(\/[a-z][a-z0-9-]*)*$/.test(v.name));
264
+ return { count: offenders.length, samples: offenders.slice(0, 5).map(v => v.name) };
265
+ ```
266
+
267
+ **Pass:** zero offenders; all variables follow `segment/name` slash-grouped lowercase-kebab.
268
+ **Auto-resolve signal:** offender count is 0.
269
+
270
+ ### N3 — Slash naming for Variants
271
+
272
+ ```
273
+ figma_execute:
274
+ const sets = await figma.root.findAllAsync(n => n.type === 'COMPONENT_SET');
275
+ const offenders = sets.filter(s => /[A-Z]/.test(s.name.split('/').pop()) || s.name.includes(' '));
276
+ return offenders.map(s => s.name);
277
+ ```
278
+
279
+ **Pass:** zero offenders.
280
+
281
+ ## File Structure
282
+
283
+ ### FS2 — Page organization
284
+
285
+ ```
286
+ figma_get_file_data (or figma_execute returning figma.root.children.map(p => p.name))
287
+ → inspect page list
288
+ ```
289
+
290
+ **Pass:** Cover page exists as the first page; pages are organized into recognizable categories (Tokens, Icons, Components, Patterns, etc.).
291
+ **Auto-resolve signal:** first page name matches `/cover|index|read.?me/i` AND page count is in a sensible range (3–10 typical for a library file).
292
+
293
+ ### FS3 — Sub-components polluting asset panel
294
+
295
+ ```
296
+ figma_search_components (limit=100)
297
+ → count component-sets/components whose name starts with `_` or `.`
298
+ ```
299
+
300
+ **Pass:** zero name-leading-underscore or dot components published.
301
+
302
+ ### FS4 — Sections vs. Frames misuse
303
+
304
+ ```
305
+ figma_execute:
306
+ await figma.loadAllPagesAsync();
307
+ const offenders = [];
308
+ const sets = await figma.root.findAllAsync(n => n.type === 'COMPONENT_SET' || n.type === 'COMPONENT');
309
+ for (const s of sets) {
310
+ const sectionsInside = s.findAll(n => n.type === 'SECTION');
311
+ if (sectionsInside.length > 0) offenders.push({ name: s.name, count: sectionsInside.length });
312
+ }
313
+ return offenders;
314
+ ```
315
+
316
+ **Pass:** zero offenders — components contain only Frames internally, never Sections.
317
+ **Auto-resolve signal:** the offenders array is empty.
318
+
319
+ ### FS5 — "Ready for dev" coverage
320
+
321
+ ```
322
+ figma_execute:
323
+ await figma.loadAllPagesAsync();
324
+ const sets = await figma.root.findAllAsync(n => n.type === 'COMPONENT_SET');
325
+ const counts = { ready: 0, notReady: 0 };
326
+ sets.forEach(s => { (s.devStatus?.type === 'READY_FOR_DEV') ? counts.ready++ : counts.notReady++; });
327
+ return { ...counts, total: sets.length };
328
+ ```
329
+
330
+ **Pass:** `ready / total ≥ 0.9` for shipped libraries.
331
+ **Auto-resolve signal:** ratio at or above the threshold; remaining unmarked items are explicitly draft.
332
+
333
+ ## Engineering-Sync Readiness
334
+
335
+ ### ES1 — Token names match codebase
336
+
337
+ ```
338
+ 1. figma_get_variables → list semantic-tier variable names
339
+ 2. Read consuming repo's tokens.css / tokens.json:
340
+ grep -E "^\s*--ui-" libs/*/styles/tokens.css | sed 's/:.*//' | sort -u
341
+ 3. Apply transformation rule (e.g. `color/primary` → `--ui-color-primary`) and diff.
342
+ ```
343
+
344
+ **Pass:** zero diff after applying the team's transformation rule.
345
+ **Auto-resolve signal:** transformation produces 1:1 mapping with no orphans on either side.
346
+
347
+ ### ES2 — Component prop API matches code
348
+
349
+ See **CD2** — same query, same auto-resolve signal.
350
+
351
+ ### ES3 — Naming-alignment as the code bridge
352
+
353
+ This skill does not recommend Figma's official Dev-Mode MCP or Code Connect — naming alignment alone is the bridge. Re-verify the alignment, not the absence of a Code Connect file.
354
+
355
+ ```
356
+ 1. Run CD2 + N1 verify queries.
357
+ 2. Pass = both pass.
358
+ ```
359
+
360
+ **Pass:** CD2 and N1 both pass. No further action.
361
+
362
+ ### ES4 — Documentation handoff
363
+
364
+ ```
365
+ grep -rE "parameters\.design|figmaNode\(" libs/*/src/lib/ | wc -l
366
+ ```
367
+
368
+ **Pass:** count > 80% of stories have `design` parameters linking back to Figma frames.
369
+
370
+ ### ES5 — Branching workflow (Org / Enterprise only)
371
+
372
+ If the team has Branching, verify that recent migrations went through a branch.
373
+
374
+ ```
375
+ 1. Ask the user: "did the last structural migration land directly on main, or via a merged branch?"
376
+ 2. If main: still-open. If branch: auto-resolved.
377
+ ```
378
+
379
+ **Pass:** confirmation that branching was used.
380
+ **N/A:** Free / Pro plans (no Branching feature).
381
+
382
+ ### ES6 — Library analytics review (Enterprise only)
383
+
384
+ ```
385
+ 1. Ask the user whether they pull Library Analytics insertion counts on a recurring schedule.
386
+ 2. If yes: confirm last review was within ~30 days.
387
+ ```
388
+
389
+ **Pass:** monthly review is in place; deprecation candidates have been flagged.
390
+ **N/A:** Free / Pro / Org plans (no Library Analytics REST access).
391
+
392
+ ## Live-session re-verify — `figma_get_design_changes`
393
+
394
+ When re-verifying _during_ an active Build/Migrate session (i.e. you just made a change and want to confirm a finding moved), `figma_get_design_changes` returns the WebSocket-buffered events since the last call. **Caveat:** this is not a historical git-style diff — only events from the current connection are buffered. For audits older than the current session, fall back to `figma_get_file_data` snapshot comparison against the prior `lastModified` pin.
395
+
396
+ ## Cross-source greps — quick reference
397
+
398
+ When verifying, the most common code-side check is one of these:
399
+
400
+ ```bash
401
+ # Find a token's code-side identifier
402
+ grep -rEn "ui-color-[a-z-]+" libs/ src/ --include="*.css" --include="*.scss" --include="*.ts"
403
+
404
+ # Find a Variant Property value referenced in components
405
+ grep -rEn "variant[:=]\s*['\"](primary|secondary|outline|danger)['\"]" libs/ src/
406
+
407
+ # Find any Figma frame reference in stories (parameters.design)
408
+ grep -rEn "parameters\.design" libs/ src/ apps/
409
+
410
+ # Confirm a token has been removed cleanly
411
+ grep -rln "ui-color-{old-name}" libs/ src/ # should return zero lines
412
+ ```
413
+
414
+ Pin the grep root to the consumer repo (`libs/`, `src/`, `apps/`, etc.) to avoid sifting through `node_modules` or `dist/`.
@@ -0,0 +1,87 @@
1
+ # Build from a code contract — spec block → conformant master
2
+
3
+ A Build-mode recipe for the case where the **code side already states the component**:
4
+ a typed prop contract (a TypeScript interface with string-literal unions, a Vue
5
+ `defineProps`, a web-component attribute table) exists, and Figma needs a master that
6
+ the codebase's own gates will accept as _the same thing_. The direction is the reverse
7
+ of the Figma-to-code loop; the discipline is the same — names, values and bindings match
8
+ verbatim, and the run ends in whatever gate the repo has, not in a screenshot.
9
+
10
+ Use it when the user says "put X into Figma", "create the master for X", "Figma is
11
+ behind the code", "the spec changed, update the master". Structural changes to an
12
+ existing master (rename, split) are Migrate, not this.
13
+
14
+ ## Inputs — collect before the first write
15
+
16
+ | Input | Where it comes from | Why it is needed |
17
+ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
18
+ | Prop contract | the spec/interface file the repo treats as ground truth | axis names and values are copied from it, never paraphrased |
19
+ | Which props are variant axes vs. Booleans vs. code-only | the repo's own metadata (a `variantMatrix`, a props table) or the rule "visibly distinct → Variant; on/off → Boolean; interaction states → neither" | decides the matrix size before a frame exists |
20
+ | Semantic variable collection | `figma_get_variables`, filtered to the collection code binds to | fills, strokes, radii, spacing bind here; primitives never directly |
21
+ | Naming rule | the repo's gate (e.g. "leaf of a section-prefixed name equals the selector; axis values equal the union literals") | the gate compares strings |
22
+ | Category / page placement | the repo's story taxonomy or the library's page layout | the section a master lives in is part of its name |
23
+ | Description convention | what the gate or the docs expect the description to name (a spec interface, a Storybook link) | descriptions are the discoverability layer |
24
+ | The closing gate | `npm run …`, a snapshot refresh, a parity check — whatever proves the master to the repo | a build without it is a drawing |
25
+
26
+ ## Recipe
27
+
28
+ 1. **Discovery.** `figma_search_components` for the name — a master may already exist
29
+ under an older name or as a single `COMPONENT`. Read the semantic collection's
30
+ variables you will bind (`figma_get_variables`). Read the category section's position
31
+ on the Components page (`figma_get_file_data`) so the new master lands in it, not on
32
+ bare canvas.
33
+ 2. **Decide the matrix.** From the contract: variant axes × values (visibly distinct
34
+ only), Booleans (on/off layers, `disabled`/`loading` and the like), Text and Instance
35
+ Swap properties, and what stays code-only (interaction states, callbacks). Write the
36
+ list down before drawing; a 4 × 3 × 4 matrix drawn "to be safe" is the anti-pattern
37
+ `component-design.md` CD1 exists for.
38
+ 3. **Build the variants** — `figma_create_component_set` when the matrix is ≤ 40
39
+ frames (hard cap 100), otherwise `figma_execute` in chunks. Every frame Auto Layout;
40
+ every fill, stroke, radius, padding and gap bound to the semantic collection
41
+ (`figma_set_fills` / `figma_set_strokes` validate the paint shape); text on the
42
+ library's text styles. Read `plugin-api-gotchas.md` first — `resize()` flips sizing
43
+ to FIXED, `layoutMode` after `resize()` reverts to AUTO, `SPACE_BETWEEN` centres a
44
+ lone child.
45
+ 4. **Name to the gate.** Set name and axis names/values exactly as the contract spells
46
+ them (`variant=primary`, not `Type=Primary`). `figma_arrange_component_set` for the
47
+ grid; `figma_add_component_property` for Booleans/Text/Instance Swap.
48
+ 5. **Describe.** `figma_set_description` naming the contract (interface name), the
49
+ use-when / don't-use-when, and the Storybook or docs link. CD6.
50
+ 6. **Annotate** behaviour the picture cannot carry (focus ring delivery, timers,
51
+ keyboard) with `figma_set_annotations`; mark the section `READY_FOR_DEV` via
52
+ `figma_execute` (`devStatus`).
53
+ 7. **Catalogue.** If the library keeps an inventory page, place one `INSTANCE` of the
54
+ master there (never a copy) and bump the page's count/date block.
55
+ 8. **Validate live.** `figma_capture_screenshot` (not the REST screenshot right after a
56
+ write). Look for clipped labels, wrong scopes, a frame that shrink-wrapped.
57
+ 9. **Close with the repo's gate.** Refresh the repo's Figma snapshot if it keeps one, run
58
+ the conformance gate, read its exit code from a redirected file. Only then report.
59
+
60
+ Return every node id you created — the repo's records (parity, snapshot, stories'
61
+ design links) will want them.
62
+
63
+ ## Worked example — the Atelier monorepo (does not apply to a generated workspace)
64
+
65
+ _The paths, scripts and gates below exist only in the Atelier repo itself. In a generated
66
+ workspace use the contract and gate it ships instead (`contracts/`, `npm run check:contracts`)._
67
+
68
+ Contract: `libs/spec/src/index.ts` (`Atl<Name>Spec`, string-literal unions) and
69
+ `libs/spec/src/metadata/<name>.metadata.ts` (`variantMatrix`). Semantic collection:
70
+ **`Library Tokens`** (generated from `tokens.css` by `gen-figma-library-tokens.mjs`; no
71
+ shadow variables — elevation is CSS-only, state it in the description). Naming gate:
72
+ `check:figma` compares the leaf of `Category/AtlName` with the selector and axis values
73
+ with the union literals as strings (Blocker), checks token-linked styles and Auto Layout
74
+ (Critical), and requires the description to reference the `Atl*Spec` name (Warning).
75
+ Category = the Storybook `title:` prefix (`Inputs`, `Display`, `Navigation`, `Overlay`,
76
+ `Feedback`), stacked on the Components page in `storySort.order`. Inventory: one
77
+ `INSTANCE` per master on the Inventory page plus the TOC count and date. Close:
78
+ `npm run figma:snapshot` (needs the Desktop Bridge) then
79
+ `npm run check:figma > /tmp/f.out 2>&1; echo $?` — zero, or the run is not done.
80
+ In the Atelier repo, a separate Figma-to-code skill picks up from here (it needs the master's node id).
81
+
82
+ ## What this recipe does not decide
83
+
84
+ Whether a prop _should_ be a variant axis is a Decide-mode question
85
+ (`decision-heuristics.md`); whether an existing master should be renamed or split is
86
+ Migrate (`migration-playbook.md`); whether the values themselves are right is the code
87
+ side's business — this recipe copies the contract, it does not review it.