@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.
- package/CHANGELOG.md +22 -0
- package/package.json +1 -1
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/SKILL.md +194 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/assets/audit-report-template.md +181 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-checklist.md +462 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-verify-queries.md +414 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-from-code-contract.md +87 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-workflow.md +260 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-sync.md +218 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-verify.md +152 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/component-design.md +198 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/decision-heuristics.md +262 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/iconography.md +150 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-generation.md +433 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-payload.md +490 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/migration-playbook.md +182 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/naming-and-file-structure.md +161 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/plugin-api-gotchas.md +79 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/scaffold-payload.md +279 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/sync-workflow.md +98 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/token-architecture.md +177 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/tool-map.md +398 -0
- package/src/generators/preset/files/claude/skills/uianatomy-mcp/SKILL.md +160 -0
- package/src/generators/preset/files/tools/design-contracts/bin/check-contracts.mjs +7 -2
- package/src/generators/preset/files/tools/scripts/preflight.mjs +1 -1
- package/src/generators/preset/preset.js +52 -4
- 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.
|