@atelier-ui/create-workspace 0.4.0 → 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.
- package/CHANGELOG.md +27 -3
- 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/contracts/README.md +6 -6
- package/src/generators/preset/files/contracts/types.ts.template +9 -10
- package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/check-contracts.mjs +236 -223
- package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/figma-snapshot-contracts.mjs +107 -92
- package/src/generators/preset/files/tools/design-contracts/src/codespec.mjs +234 -0
- package/src/generators/preset/files/tools/design-contracts/src/config.mjs +63 -0
- package/src/generators/preset/files/tools/{scripts/lib → design-contracts/src}/docgen.mjs +78 -98
- package/src/generators/preset/files/tools/{scripts/lib/ts-eval.js → design-contracts/src/ts-eval.cjs} +3 -4
- package/src/generators/preset/files/tools/scripts/preflight.mjs +1 -1
- package/src/generators/preset/preset.js +79 -15
- package/src/generators/preset/preset.js.map +1 -1
|
@@ -0,0 +1,490 @@
|
|
|
1
|
+
# Inventory generation — `figma_execute` payloads
|
|
2
|
+
|
|
3
|
+
Ready-to-paste payload templates for the seven phases of the Inventory sub-mode. Adapt names and ids for the file at hand. The structure is fixed; the values come from the Section plan emitted in Phase 2 (see `inventory-generation.md`).
|
|
4
|
+
|
|
5
|
+
The shared constants below are inlined into every payload — there is no plugin-side state across calls.
|
|
6
|
+
|
|
7
|
+
```js
|
|
8
|
+
// Layout tokens
|
|
9
|
+
const GAP_SECTION = 80;
|
|
10
|
+
const GAP_GROUP = 48;
|
|
11
|
+
const GAP_CARD = 32;
|
|
12
|
+
const CARD_WIDTH = 320;
|
|
13
|
+
const CARD_PADDING = 24;
|
|
14
|
+
const CARD_ITEM_SPACING = 12;
|
|
15
|
+
const PREVIEW_PAD = 16;
|
|
16
|
+
const PREVIEW_MIN_H = 96; // floor for tiny components (Badge, Avatar, Skeleton)
|
|
17
|
+
const PREVIEW_MAX_H = 240; // ceiling for large compositions (Chat, Drawer, Table)
|
|
18
|
+
const PREVIEW_INNER_W = CARD_WIDTH - CARD_PADDING * 2 - PREVIEW_PAD * 2; // 240 by default
|
|
19
|
+
const BADGE_PAD = { x: 6, y: 4 };
|
|
20
|
+
|
|
21
|
+
// Palettes
|
|
22
|
+
const PALETTE = {
|
|
23
|
+
light: { surface: '#FFFFFF', preview: '#F4F4F5', fg: '#0A0A0A', muted: '#6B7280' },
|
|
24
|
+
dark: { surface: '#0A0A0A', preview: '#1F1F23', fg: '#FAFAFA', muted: '#9CA3AF' },
|
|
25
|
+
};
|
|
26
|
+
const STATUS = {
|
|
27
|
+
ready: { color: '#10B981', fg: '#FFFFFF', label: 'READY' },
|
|
28
|
+
beta: { color: '#F59E0B', fg: '#000000', label: 'BETA' },
|
|
29
|
+
wip: { color: '#6366F1', fg: '#FFFFFF', label: 'WIP' },
|
|
30
|
+
deprecated: { color: '#EF4444', fg: '#FFFFFF', label: 'DEPRECATED' },
|
|
31
|
+
unmarked: { color: '#9CA3AF', fg: '#FFFFFF', label: '—' },
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
// Hex → rgb in 0..1 (Figma colors are 0–1, not 0–255)
|
|
35
|
+
function hex(h) {
|
|
36
|
+
const v = h.replace('#', '');
|
|
37
|
+
return {
|
|
38
|
+
r: parseInt(v.slice(0, 2), 16) / 255,
|
|
39
|
+
g: parseInt(v.slice(2, 4), 16) / 255,
|
|
40
|
+
b: parseInt(v.slice(4, 6), 16) / 255,
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
function solid(h) {
|
|
44
|
+
return [{ type: 'SOLID', color: hex(h) }];
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Phase 1 — Discover
|
|
49
|
+
|
|
50
|
+
Read-only. Returns the light index. Heavy metadata is deferred to Phase 4.
|
|
51
|
+
|
|
52
|
+
```js
|
|
53
|
+
// figma_execute payload — Phase 1
|
|
54
|
+
// Inputs (inlined by the skill agent):
|
|
55
|
+
// skipNamespaces: string[] // top-level slash segments to drop, e.g. ['Icon']
|
|
56
|
+
// skipPages: string[] // page names to drop, e.g. ['Icons', '🔣 Icons']
|
|
57
|
+
|
|
58
|
+
await figma.loadAllPagesAsync();
|
|
59
|
+
figma.skipInvisibleInstanceChildren = true;
|
|
60
|
+
|
|
61
|
+
const all = await figma.root.findAllAsync((n) => n.type === 'COMPONENT' || n.type === 'COMPONENT_SET');
|
|
62
|
+
|
|
63
|
+
// Default skip lists — `Icon` namespace and common icon page names.
|
|
64
|
+
// Icons live on a dedicated `Icons` page (see naming-and-file-structure.md);
|
|
65
|
+
// dumping them into the component inventory drowns it in single-cell cards.
|
|
66
|
+
const defaultSkipNamespaces = new Set(skipNamespaces || ['Icon']);
|
|
67
|
+
const defaultSkipPages = new Set(skipPages || ['Icons', '🔣 Icons']);
|
|
68
|
+
|
|
69
|
+
const skipped = [];
|
|
70
|
+
const sources = all.filter((n) => {
|
|
71
|
+
if (n.type === 'COMPONENT' && n.parent?.type === 'COMPONENT_SET') return false;
|
|
72
|
+
const leaf = n.name.split('/').pop();
|
|
73
|
+
if (/^[_.]/.test(leaf)) {
|
|
74
|
+
skipped.push({ id: n.id, name: n.name, reason: 'private prefix' });
|
|
75
|
+
return false;
|
|
76
|
+
}
|
|
77
|
+
const top = n.name.split('/')[0];
|
|
78
|
+
if (defaultSkipNamespaces.has(top)) {
|
|
79
|
+
skipped.push({ id: n.id, name: n.name, reason: `namespace skip: ${top}` });
|
|
80
|
+
return false;
|
|
81
|
+
}
|
|
82
|
+
// Walk up to find the parent page
|
|
83
|
+
let cursor = n.parent;
|
|
84
|
+
while (cursor && cursor.type !== 'PAGE') cursor = cursor.parent;
|
|
85
|
+
if (cursor && defaultSkipPages.has(cursor.name)) {
|
|
86
|
+
skipped.push({ id: n.id, name: n.name, reason: `page skip: ${cursor.name}` });
|
|
87
|
+
return false;
|
|
88
|
+
}
|
|
89
|
+
return true;
|
|
90
|
+
});
|
|
91
|
+
|
|
92
|
+
return {
|
|
93
|
+
sources: sources.map((n) => ({ id: n.id, name: n.name, type: n.type })),
|
|
94
|
+
skipped,
|
|
95
|
+
};
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Phase 3 — Scaffold
|
|
99
|
+
|
|
100
|
+
Wipes any existing `📋 Inventory` page, recreates it, drops a Section + inner Frame per top-level category. The skill agent passes `sectionPlans` from Phase 2.
|
|
101
|
+
|
|
102
|
+
```js
|
|
103
|
+
// figma_execute payload — Phase 3
|
|
104
|
+
// Inputs (inlined by the skill agent):
|
|
105
|
+
// sectionPlans: Array<{ sectionName: string }>
|
|
106
|
+
|
|
107
|
+
const PAGE_NAME = '📋 Inventory';
|
|
108
|
+
const existing = figma.root.children.find((p) => p.name === PAGE_NAME);
|
|
109
|
+
if (existing) existing.remove();
|
|
110
|
+
|
|
111
|
+
const page = figma.createPage();
|
|
112
|
+
page.name = PAGE_NAME;
|
|
113
|
+
await figma.setCurrentPageAsync(page);
|
|
114
|
+
|
|
115
|
+
const sectionRefs = {};
|
|
116
|
+
let cursorX = 0;
|
|
117
|
+
|
|
118
|
+
for (const plan of sectionPlans) {
|
|
119
|
+
const section = figma.createSection();
|
|
120
|
+
section.name = `${plan.sectionName} — Inventory`;
|
|
121
|
+
section.x = cursorX;
|
|
122
|
+
section.y = 0;
|
|
123
|
+
|
|
124
|
+
const inner = figma.createFrame();
|
|
125
|
+
inner.name = `${plan.sectionName} · groups`;
|
|
126
|
+
inner.layoutMode = 'VERTICAL';
|
|
127
|
+
inner.layoutSizingHorizontal = 'HUG';
|
|
128
|
+
inner.layoutSizingVertical = 'HUG';
|
|
129
|
+
inner.itemSpacing = 48;
|
|
130
|
+
inner.paddingTop = inner.paddingBottom = 32;
|
|
131
|
+
inner.paddingLeft = inner.paddingRight = 32;
|
|
132
|
+
inner.fills = [];
|
|
133
|
+
section.appendChild(inner);
|
|
134
|
+
|
|
135
|
+
sectionRefs[plan.sectionName] = { sectionId: section.id, innerId: inner.id };
|
|
136
|
+
cursorX += 1600; // placeholder; reflowed at the end of Phase 4
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
return { sectionRefs };
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Phase 4 — Populate one Section (one call per Section)
|
|
143
|
+
|
|
144
|
+
The hot loop — one `figma_execute` call per top-level Section. Card builder helpers are inlined at the bottom.
|
|
145
|
+
|
|
146
|
+
```js
|
|
147
|
+
// figma_execute payload — Phase 4 (one Section)
|
|
148
|
+
// Inputs (inlined by the skill agent):
|
|
149
|
+
// innerId: string // Frame inside the Section, from Phase 3
|
|
150
|
+
// sectionName: string
|
|
151
|
+
// groups: Array<{ groupName: string; componentIds: string[] }>
|
|
152
|
+
|
|
153
|
+
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
|
154
|
+
await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
|
|
155
|
+
await figma.loadFontAsync({ family: 'Inter', style: 'Semi Bold' });
|
|
156
|
+
|
|
157
|
+
const inner = await figma.getNodeByIdAsync(innerId);
|
|
158
|
+
|
|
159
|
+
// — helpers —————————————————————————————————————————————————————————————
|
|
160
|
+
|
|
161
|
+
function makeText(content, { size = 12, weight = 'Regular', color = '#0A0A0A', uppercase = false } = {}) {
|
|
162
|
+
const t = figma.createText();
|
|
163
|
+
t.fontName = { family: 'Inter', style: weight };
|
|
164
|
+
t.characters = uppercase ? content.toUpperCase() : content;
|
|
165
|
+
t.fontSize = size;
|
|
166
|
+
t.fills = solid(color);
|
|
167
|
+
return t;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
function autoFrame({ name, mode = 'VERTICAL', pad = 0, gap = 0, fill, radius = 0, sizing = 'HUG' }) {
|
|
171
|
+
const f = figma.createFrame();
|
|
172
|
+
f.name = name;
|
|
173
|
+
f.layoutMode = mode;
|
|
174
|
+
f.itemSpacing = gap;
|
|
175
|
+
f.paddingTop = f.paddingBottom = typeof pad === 'object' ? pad.y : pad;
|
|
176
|
+
f.paddingLeft = f.paddingRight = typeof pad === 'object' ? pad.x : pad;
|
|
177
|
+
f.layoutSizingHorizontal = sizing === 'FILL' ? 'FILL' : 'HUG';
|
|
178
|
+
f.layoutSizingVertical = 'HUG';
|
|
179
|
+
if (radius) f.cornerRadius = radius;
|
|
180
|
+
f.fills = fill ? solid(fill) : [];
|
|
181
|
+
return f;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
function makeGroupFrame(groupName) {
|
|
185
|
+
const wrap = autoFrame({ name: `group · ${groupName}`, mode: 'VERTICAL', gap: 16, sizing: 'HUG' });
|
|
186
|
+
wrap.appendChild(makeText(groupName, { size: 16, weight: 'Semi Bold', color: '#0A0A0A' }));
|
|
187
|
+
return wrap;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
function makeCardsRow(cardCount) {
|
|
191
|
+
// Size the wrap row to the actual card count, capped at MAX_COLS.
|
|
192
|
+
// FIXED width is required for `layoutWrap = 'WRAP'` to know when to break
|
|
193
|
+
// a new row, but a hardcoded 1480 leaves single-card sections (1 card in
|
|
194
|
+
// a 1480-wide row) sitting in 1160px of phantom whitespace that propagates
|
|
195
|
+
// up through the parent group, inner Frame, and Section bounds.
|
|
196
|
+
const MAX_COLS = 4;
|
|
197
|
+
const cols = Math.min(cardCount, MAX_COLS);
|
|
198
|
+
const width = cols * CARD_WIDTH + Math.max(0, cols - 1) * GAP_CARD;
|
|
199
|
+
const row = figma.createFrame();
|
|
200
|
+
row.name = 'cards';
|
|
201
|
+
row.layoutMode = 'HORIZONTAL';
|
|
202
|
+
row.layoutWrap = 'WRAP';
|
|
203
|
+
row.itemSpacing = GAP_CARD;
|
|
204
|
+
row.counterAxisSpacing = GAP_CARD;
|
|
205
|
+
row.layoutSizingHorizontal = 'FIXED';
|
|
206
|
+
row.resize(width, 1);
|
|
207
|
+
row.layoutSizingVertical = 'HUG';
|
|
208
|
+
row.fills = [];
|
|
209
|
+
return row;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
function resolveStatus(node) {
|
|
213
|
+
const pd = node.getSharedPluginData('inventory', 'status');
|
|
214
|
+
if (pd) {
|
|
215
|
+
const v = pd.trim().toLowerCase();
|
|
216
|
+
if (['ready', 'beta', 'wip', 'deprecated'].includes(v)) return v;
|
|
217
|
+
}
|
|
218
|
+
if (node.devStatus?.type === 'READY_FOR_DEV') return 'ready';
|
|
219
|
+
const tag = (node.description || '').match(/\[(stable|ready|beta|wip|deprecated)\]/i);
|
|
220
|
+
if (tag) return tag[1].toLowerCase().replace('stable', 'ready');
|
|
221
|
+
return 'unmarked';
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
function detectContextualBg(node) {
|
|
225
|
+
// 1. Layer-name hint — explicit dark/inverse marker on any descendant flips to dark
|
|
226
|
+
const hint = node.findOne?.((n) => /(^|[\s/])(dark|inverse|on[\s\-_]?dark)([\s/]|$)/i.test(n.name));
|
|
227
|
+
if (hint) return 'dark';
|
|
228
|
+
// 2. Cached
|
|
229
|
+
const cached = node.getSharedPluginData('inventory', 'contextualBg');
|
|
230
|
+
if (cached === 'dark' || cached === 'light') return cached;
|
|
231
|
+
// 3. Walk UP — sample the first ancestor with a visible SOLID fill.
|
|
232
|
+
// The previewNode's own root fill is usually the component itself
|
|
233
|
+
// (Button = teal, Tooltip = dark, Toast = colored); that's not its
|
|
234
|
+
// contextual surface. The actual surface is the Section/Frame the
|
|
235
|
+
// component sits inside. Walk parents until one has a fill.
|
|
236
|
+
let cursor = node.parent;
|
|
237
|
+
while (cursor && cursor.type !== 'PAGE' && cursor.type !== 'DOCUMENT') {
|
|
238
|
+
const fill = (cursor.fills || []).find((f) => f.type === 'SOLID' && f.visible !== false);
|
|
239
|
+
if (fill) {
|
|
240
|
+
const { r, g, b } = fill.color;
|
|
241
|
+
const L = 0.2126 * r + 0.7152 * g + 0.0722 * b;
|
|
242
|
+
const result = L < 0.5 ? 'dark' : 'light';
|
|
243
|
+
node.setSharedPluginData('inventory', 'contextualBg', result);
|
|
244
|
+
return result;
|
|
245
|
+
}
|
|
246
|
+
cursor = cursor.parent;
|
|
247
|
+
}
|
|
248
|
+
// 4. Fallback — the component sits on the page background, which is
|
|
249
|
+
// light by Figma default. The layer-name hint above covers
|
|
250
|
+
// intentionally-dark components.
|
|
251
|
+
const fallback = 'light';
|
|
252
|
+
node.setSharedPluginData('inventory', 'contextualBg', fallback);
|
|
253
|
+
return fallback;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
function extractMetadata(node) {
|
|
257
|
+
const isSet = node.type === 'COMPONENT_SET';
|
|
258
|
+
const previewNode = isSet ? node.defaultVariant : node;
|
|
259
|
+
const properties = [];
|
|
260
|
+
if (isSet) {
|
|
261
|
+
for (const [key, def] of Object.entries(node.componentPropertyDefinitions || {})) {
|
|
262
|
+
properties.push({
|
|
263
|
+
key: key.split('#')[0],
|
|
264
|
+
type: def.type,
|
|
265
|
+
defaultValue: def.defaultValue,
|
|
266
|
+
variantOptions: def.variantOptions,
|
|
267
|
+
});
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
return {
|
|
271
|
+
description: node.description || '',
|
|
272
|
+
documentationLinks: (node.documentationLinks || []).map((d) => d.uri),
|
|
273
|
+
properties,
|
|
274
|
+
size: { width: previewNode.width, height: previewNode.height },
|
|
275
|
+
status: resolveStatus(node),
|
|
276
|
+
contextualBg: detectContextualBg(previewNode),
|
|
277
|
+
previewNode,
|
|
278
|
+
isSet,
|
|
279
|
+
};
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
async function buildCard(node) {
|
|
283
|
+
const meta = extractMetadata(node);
|
|
284
|
+
const bg = PALETTE[meta.contextualBg];
|
|
285
|
+
const status = STATUS[meta.status];
|
|
286
|
+
|
|
287
|
+
const card = autoFrame({
|
|
288
|
+
name: `card · ${node.name}`,
|
|
289
|
+
mode: 'VERTICAL',
|
|
290
|
+
pad: CARD_PADDING,
|
|
291
|
+
gap: CARD_ITEM_SPACING,
|
|
292
|
+
fill: bg.surface,
|
|
293
|
+
radius: 8,
|
|
294
|
+
sizing: 'HUG',
|
|
295
|
+
});
|
|
296
|
+
card.layoutSizingHorizontal = 'FIXED';
|
|
297
|
+
card.resize(CARD_WIDTH, 1);
|
|
298
|
+
card.layoutSizingVertical = 'HUG';
|
|
299
|
+
|
|
300
|
+
// — Header ——————————————————————————————————
|
|
301
|
+
const header = autoFrame({ name: 'header', mode: 'HORIZONTAL', gap: 8, sizing: 'FILL' });
|
|
302
|
+
header.primaryAxisAlignItems = 'SPACE_BETWEEN';
|
|
303
|
+
header.counterAxisAlignItems = 'CENTER';
|
|
304
|
+
header.appendChild(makeText(node.name.split('/').pop(), { size: 14, weight: 'Semi Bold', color: bg.fg }));
|
|
305
|
+
const badge = autoFrame({
|
|
306
|
+
name: 'status',
|
|
307
|
+
mode: 'HORIZONTAL',
|
|
308
|
+
pad: BADGE_PAD,
|
|
309
|
+
fill: status.color,
|
|
310
|
+
radius: 12,
|
|
311
|
+
sizing: 'HUG',
|
|
312
|
+
});
|
|
313
|
+
badge.appendChild(makeText(status.label, { size: 10, weight: 'Medium', color: status.fg, uppercase: true }));
|
|
314
|
+
header.appendChild(badge);
|
|
315
|
+
card.appendChild(header);
|
|
316
|
+
|
|
317
|
+
// — Preview ——————————————————————————————————
|
|
318
|
+
const preview = autoFrame({
|
|
319
|
+
name: 'preview',
|
|
320
|
+
mode: 'VERTICAL',
|
|
321
|
+
pad: PREVIEW_PAD,
|
|
322
|
+
fill: bg.preview,
|
|
323
|
+
radius: 6,
|
|
324
|
+
sizing: 'FILL',
|
|
325
|
+
});
|
|
326
|
+
preview.primaryAxisAlignItems = 'CENTER';
|
|
327
|
+
preview.counterAxisAlignItems = 'CENTER';
|
|
328
|
+
preview.minHeight = PREVIEW_MIN_H;
|
|
329
|
+
try {
|
|
330
|
+
const instance = meta.previewNode.createInstance();
|
|
331
|
+
preview.appendChild(instance);
|
|
332
|
+
// Scale-fit on BOTH axes — width-only clamp pancakes tall compositions
|
|
333
|
+
// (a 1080×720 chat preview scaled by width alone becomes 240×26 because
|
|
334
|
+
// the parent preview frame's minHeight clips the height after rescale).
|
|
335
|
+
const scale = Math.min(PREVIEW_INNER_W / instance.width, PREVIEW_MAX_H / instance.height, 1);
|
|
336
|
+
if (scale < 0.99) instance.rescale(scale);
|
|
337
|
+
} catch (e) {
|
|
338
|
+
preview.appendChild(makeText('(preview unavailable)', { size: 11, color: bg.muted }));
|
|
339
|
+
}
|
|
340
|
+
card.appendChild(preview);
|
|
341
|
+
|
|
342
|
+
// — Meta row ——————————————————————————————————
|
|
343
|
+
const metaRow = autoFrame({ name: 'meta', mode: 'HORIZONTAL', gap: 8, sizing: 'FILL' });
|
|
344
|
+
metaRow.appendChild(makeText(`${meta.isSet ? 'COMPONENT_SET' : 'COMPONENT'} · ${Math.round(meta.size.width)}×${Math.round(meta.size.height)}px`, { size: 11, color: bg.muted }));
|
|
345
|
+
card.appendChild(metaRow);
|
|
346
|
+
|
|
347
|
+
// — Property table ——————————————————————————————————
|
|
348
|
+
if (meta.properties.length) {
|
|
349
|
+
const table = autoFrame({ name: 'properties', mode: 'VERTICAL', gap: 4, sizing: 'FILL' });
|
|
350
|
+
for (const p of meta.properties) {
|
|
351
|
+
const row = autoFrame({ name: `prop · ${p.key}`, mode: 'HORIZONTAL', gap: 8, sizing: 'FILL' });
|
|
352
|
+
row.appendChild(makeText(p.key, { size: 12, weight: 'Medium', color: bg.fg }));
|
|
353
|
+
row.appendChild(makeText(p.type, { size: 11, color: bg.muted }));
|
|
354
|
+
row.appendChild(makeText(`default: ${p.defaultValue}`, { size: 11, color: bg.muted }));
|
|
355
|
+
table.appendChild(row);
|
|
356
|
+
}
|
|
357
|
+
card.appendChild(table);
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
// — Description footer ——————————————————————————————————
|
|
361
|
+
if (meta.description) {
|
|
362
|
+
card.appendChild(makeText(meta.description, { size: 12, color: bg.muted }));
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
return card;
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
// — main loop ——————————————————————————————————————————————————————————
|
|
369
|
+
|
|
370
|
+
const built = [];
|
|
371
|
+
for (const group of groups) {
|
|
372
|
+
const groupFrame = makeGroupFrame(group.groupName);
|
|
373
|
+
inner.appendChild(groupFrame);
|
|
374
|
+
|
|
375
|
+
const cardsRow = makeCardsRow(group.componentIds.length);
|
|
376
|
+
groupFrame.appendChild(cardsRow);
|
|
377
|
+
|
|
378
|
+
for (let i = 0; i < group.componentIds.length; i += 25) {
|
|
379
|
+
const slice = group.componentIds.slice(i, i + 25);
|
|
380
|
+
for (const id of slice) {
|
|
381
|
+
const node = await figma.getNodeByIdAsync(id);
|
|
382
|
+
if (!node) continue;
|
|
383
|
+
const card = await buildCard(node);
|
|
384
|
+
cardsRow.appendChild(card);
|
|
385
|
+
built.push({ componentId: id, cardId: card.id });
|
|
386
|
+
}
|
|
387
|
+
await new Promise((r) => setTimeout(r, 0)); // YIELD between chunks
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
return { sectionName, built };
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
### Splitting a Section that exceeds 150 components
|
|
395
|
+
|
|
396
|
+
For the second + third + … call against the same Section, the same payload is reused with two changes:
|
|
397
|
+
|
|
398
|
+
- `groups` is the **next contiguous slice** of the original group plan (the skill agent slices it up-front).
|
|
399
|
+
- The first call may need to _reuse_ a `groupFrame` instead of creating a new one. Pass an optional `appendIntoGroupId` and have the payload fetch and reuse it instead of calling `makeGroupFrame()`. Same logic; the payload conditionally creates vs. resolves.
|
|
400
|
+
|
|
401
|
+
## Phase 6 — Mark Ready + index
|
|
402
|
+
|
|
403
|
+
```js
|
|
404
|
+
// figma_execute payload — Phase 6
|
|
405
|
+
// Inputs:
|
|
406
|
+
// sectionRefs: Record<string, { sectionId: string }>
|
|
407
|
+
// counts: Record<string, number> // section name → component count
|
|
408
|
+
// inventoryPageId: string
|
|
409
|
+
|
|
410
|
+
await figma.setCurrentPageAsync(await figma.getNodeByIdAsync(inventoryPageId));
|
|
411
|
+
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
|
|
412
|
+
await figma.loadFontAsync({ family: 'Inter', style: 'Semi Bold' });
|
|
413
|
+
|
|
414
|
+
// 1. Mark each Section ready for dev
|
|
415
|
+
for (const name of Object.keys(sectionRefs)) {
|
|
416
|
+
const sec = await figma.getNodeByIdAsync(sectionRefs[name].sectionId);
|
|
417
|
+
sec.devStatus = { type: 'READY_FOR_DEV' };
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
// 2. Reflow Section X positions with GAP_SECTION = 80
|
|
421
|
+
let cursorX = 0;
|
|
422
|
+
for (const name of Object.keys(sectionRefs)) {
|
|
423
|
+
const sec = await figma.getNodeByIdAsync(sectionRefs[name].sectionId);
|
|
424
|
+
sec.x = cursorX;
|
|
425
|
+
sec.y = 200; // leaves room above for the TOC
|
|
426
|
+
cursorX += sec.width + 80;
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
// 3. TOC card
|
|
430
|
+
const toc = figma.createFrame();
|
|
431
|
+
toc.name = '📋 Inventory · TOC';
|
|
432
|
+
toc.x = 0;
|
|
433
|
+
toc.y = 0;
|
|
434
|
+
toc.layoutMode = 'VERTICAL';
|
|
435
|
+
toc.itemSpacing = 8;
|
|
436
|
+
toc.paddingTop = toc.paddingBottom = toc.paddingLeft = toc.paddingRight = 24;
|
|
437
|
+
toc.layoutSizingHorizontal = 'HUG';
|
|
438
|
+
toc.layoutSizingVertical = 'HUG';
|
|
439
|
+
toc.cornerRadius = 8;
|
|
440
|
+
toc.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
|
|
441
|
+
const heading = figma.createText();
|
|
442
|
+
heading.fontName = { family: 'Inter', style: 'Semi Bold' };
|
|
443
|
+
heading.characters = 'Inventory';
|
|
444
|
+
heading.fontSize = 18;
|
|
445
|
+
toc.appendChild(heading);
|
|
446
|
+
for (const [name, n] of Object.entries(counts)) {
|
|
447
|
+
const row = figma.createText();
|
|
448
|
+
row.fontName = { family: 'Inter', style: 'Regular' };
|
|
449
|
+
row.characters = `${name} — ${n}`;
|
|
450
|
+
row.fontSize = 12;
|
|
451
|
+
toc.appendChild(row);
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
return { ready: Object.keys(sectionRefs).length, tocId: toc.id };
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
## Phase 7 — Validate
|
|
458
|
+
|
|
459
|
+
Skill-orchestrated, not a single payload. Per top-level Section the agent calls:
|
|
460
|
+
|
|
461
|
+
```
|
|
462
|
+
figma_capture_screenshot // live, post-write — see tool-map.md:97
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
…with the section's bounding rect and returns the image to the user.
|
|
466
|
+
|
|
467
|
+
Coverage check is data-only:
|
|
468
|
+
|
|
469
|
+
```
|
|
470
|
+
expected = sources.length - skipped.length
|
|
471
|
+
actual = sum(built.length across all Phase-4 returns)
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
If `actual < expected`, render a `_Skipped` frame on the Inventory page listing the missing components with reasons.
|
|
475
|
+
|
|
476
|
+
## Re-run idempotency
|
|
477
|
+
|
|
478
|
+
Phase 3 wipes the existing `📋 Inventory` page before recreating it. Per-component `setSharedPluginData('inventory', 'contextualBg', …)` cache survives the wipe (it lives on the source component, not the inventory page) so re-runs are fast on unchanged components.
|
|
479
|
+
|
|
480
|
+
To force a fresh contextual-background recompute, the skill agent first runs:
|
|
481
|
+
|
|
482
|
+
```js
|
|
483
|
+
// figma_execute payload — clear contextualBg cache
|
|
484
|
+
await figma.loadAllPagesAsync();
|
|
485
|
+
const all = await figma.root.findAllAsync((n) => n.type === 'COMPONENT' || n.type === 'COMPONENT_SET');
|
|
486
|
+
for (const n of all) n.setSharedPluginData('inventory', 'contextualBg', '');
|
|
487
|
+
return { cleared: all.length };
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
This is opt-in only — the user must request it explicitly (trigger: _recompute backgrounds, refresh contextual backgrounds, full rebuild_).
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# Migration playbook
|
|
2
|
+
|
|
3
|
+
Between greenfield Build and a one-off Audit lies the case where the file already exists, the Audit produced a punch list, and now things need to _change_ without breaking the people downstream. This file is that path.
|
|
4
|
+
|
|
5
|
+
> The single biggest mistake in Figma migrations is making them all at once. Almost every operation in this file has a "do additively, then remove later" form. Use it.
|
|
6
|
+
|
|
7
|
+
## When to load this file
|
|
8
|
+
|
|
9
|
+
Load it when the user's intent is to **change an existing structure** — not to assess one (Audit) and not to create one from scratch (Build). Trigger phrases:
|
|
10
|
+
|
|
11
|
+
- "rename this Variable / Variant Property / Component"
|
|
12
|
+
- "split this Variant Set into…"
|
|
13
|
+
- "add a Mode"
|
|
14
|
+
- "split our library"
|
|
15
|
+
- "restructure these tokens"
|
|
16
|
+
- "we ran the audit, now fix the Critical findings"
|
|
17
|
+
|
|
18
|
+
If the user has already run the Audit and is now in fix-mode, you'll often arrive here from `audit-checklist.md`. The Audit categories map directly onto the operations below.
|
|
19
|
+
|
|
20
|
+
## Pre-flight — always
|
|
21
|
+
|
|
22
|
+
Run all five before touching anything:
|
|
23
|
+
|
|
24
|
+
1. **Re-run discovery.** `figma_get_file_data` (or `figma_get_variables` + `figma_get_styles` for large files). The state you remember from the last session may not be the current state.
|
|
25
|
+
2. **Snapshot.** Pin a screenshot or `figma_get_file_data` dump as "before". You will refer back to it.
|
|
26
|
+
3. **Identify the safety class** for each planned change (table below). A Breaking change in your set forces the coordination protocol; a list of all-Safe changes can run end-to-end without ceremony.
|
|
27
|
+
4. **Branch first (Org / Enterprise only).** If the file lives in a workspace with **Branching** enabled, do the migration work on a branch, not on main. Library publishing happens **only from main**, so the workflow is: branch → migrate → review → merge → publish. Never run a Breaking change directly on main when a branch is available — it removes the only review buffer you have.
|
|
28
|
+
5. **Tell the consumers.** Code (Style Dictionary export, Token Studio config, manually-maintained `tokens.css`), other Figma files using this as a library, and the design team. The cost of silence is debugging "the production app's primary color is wrong" three days later.
|
|
29
|
+
|
|
30
|
+
## Safety classes
|
|
31
|
+
|
|
32
|
+
The figma-console-mcp tool surface and the Figma Variables API are designed so that _most_ renames preserve aliases — the breakage shows up in code that references by name. Categorize before you act.
|
|
33
|
+
|
|
34
|
+
### Safe — references are preserved automatically
|
|
35
|
+
|
|
36
|
+
| Operation | What carries through |
|
|
37
|
+
| -------------------------------------- | ----------------------------------------------------------- |
|
|
38
|
+
| `figma_rename_variable` | Aliases pointing at the renamed Variable are auto-updated. |
|
|
39
|
+
| `figma_rename_mode` | Values per mode are preserved; the Mode keeps its `modeId`. |
|
|
40
|
+
| Renaming a Component Set | Instances follow. |
|
|
41
|
+
| Reordering Variants in a Component Set | No effect on instances or the Variant Property values. |
|
|
42
|
+
|
|
43
|
+
These still need a code-side update because most exporters key by _name_ — but the Figma file itself stays internally consistent.
|
|
44
|
+
|
|
45
|
+
### Mostly safe — additive, but verify after
|
|
46
|
+
|
|
47
|
+
| Operation | Verify |
|
|
48
|
+
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
49
|
+
| `figma_add_mode` | Existing Variables get the new mode seeded with their current value. Re-confirm scopes. |
|
|
50
|
+
| `figma_create_variable` / `figma_batch_create_variables` | New Variable doesn't collide with an existing name (case-sensitive). |
|
|
51
|
+
| Adding a Variant to an existing Component Set | The new Variant Property combination renders correctly; existing instances keep their mapping. |
|
|
52
|
+
| Adding a Component Property | Instances pick up the default value. Inspect a few. |
|
|
53
|
+
|
|
54
|
+
### Breaking — needs the coordination protocol
|
|
55
|
+
|
|
56
|
+
| Operation | What breaks |
|
|
57
|
+
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
58
|
+
| `figma_delete_variable` | Every aliased Variable showing the old name as a broken reference; every component fill bound to it. |
|
|
59
|
+
| `figma_delete_variable_collection` | Same as above, multiplied by the number of Variables in the collection. |
|
|
60
|
+
| Removing a Mode | All values for that mode are gone; bindings fall back to default. |
|
|
61
|
+
| Removing a Variant from a Component Set | Instances using that combination "stick" but no longer track upstream changes. |
|
|
62
|
+
| Renaming a Variant Property or its values | Existing instances reset to the property's default — every consumer rebuilds. |
|
|
63
|
+
| Splitting one Component into two | Old instances continue pointing at the original; downstream rebuild required. |
|
|
64
|
+
| Splitting a Library | Every consumer file's import breaks; needs a manual swap-instances pass. |
|
|
65
|
+
|
|
66
|
+
## Coordination protocol — for every Breaking change
|
|
67
|
+
|
|
68
|
+
The same five steps regardless of the operation:
|
|
69
|
+
|
|
70
|
+
1. **Announce.** What is changing, when, and what consumers need to do. A Slack message and an entry in the file's Cover page.
|
|
71
|
+
2. **Add the new shape alongside the old.** Both shapes exist for one cycle. Old is marked with `_deprecated` prefix or the description is updated.
|
|
72
|
+
3. **Migrate consumers.** Code (rename in `tokens.css` / Style Dictionary source / manually). Other Figma files (`Swap Instance`). One designer per consumer file is the unit of work.
|
|
73
|
+
4. **Wait.** Don't remove the old shape until the next design review or the next code-side release, whichever is later. This is the gap where "wait, we still use that" surfaces.
|
|
74
|
+
5. **Remove.** `figma_delete_variable` (or equivalent) on the old shape. Confirm via `figma_get_file_data` that no broken aliases remain. Update the Cover page note. **Removal verification gotcha:** after `Variable.remove()` the variable can still appear in `figma.variables.getVariableByIdAsync(id)` for a tick (returned object lacks a `removed: true` flag). The reliable check is to read the parent collection's `variableIds` array — the removed ID will be absent there. Don't rely on the by-ID lookup alone.
|
|
75
|
+
|
|
76
|
+
Skipping step 4 is the most common failure. If you find yourself wanting to skip it because "we checked, nobody uses it" — assume someone does.
|
|
77
|
+
|
|
78
|
+
## Recipes — common operations end-to-end
|
|
79
|
+
|
|
80
|
+
### Rename a Variable safely
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
1. figma_get_variables — confirm current name + ID + aliases
|
|
84
|
+
2. figma_rename_variable — Figma updates all aliases; instances follow
|
|
85
|
+
3. Re-export to code — codesync exporter writes the new name
|
|
86
|
+
4. CI runs — diff is "rename only"; reviewer confirms
|
|
87
|
+
5. Update Cover page note if the rename is user-facing
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The change is Safe inside Figma; the code-side rename is the only chance for drift. If the codesync exporter keys by ID instead of name (rare), step 3 is a no-op.
|
|
91
|
+
|
|
92
|
+
### Add a Mode without breaking existing components
|
|
93
|
+
|
|
94
|
+
```
|
|
95
|
+
1. figma_get_variables — count the Variables in target collection
|
|
96
|
+
2. figma_execute → collection.addMode('NewMode')
|
|
97
|
+
3. For each Variable, decide:
|
|
98
|
+
- alias to a primitive (most semantic tokens),
|
|
99
|
+
- inherit from the default mode (most spacing / radius),
|
|
100
|
+
- explicit value per Variable (rare; probably means the Variable should be renamed).
|
|
101
|
+
4. Use figma_batch_update_variables to seed the new mode in one call.
|
|
102
|
+
5. figma_take_screenshot a representative component in the new mode.
|
|
103
|
+
6. Update the codesync exporter's mode list.
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Mostly safe — but the Mode now exists across **N × M** Variables and every one of them needs an explicit value. Don't ship the Mode until the count is verified.
|
|
107
|
+
|
|
108
|
+
### Split a Variant Set into two Components
|
|
109
|
+
|
|
110
|
+
The hardest legitimate refactor. Use when the cardinality has exploded (e.g., a `Button` Component Set with 5 variants × 4 sizes × 5 states × 3 widths = 300 permutations) and the user has confirmed the split is the right answer (see `decision-heuristics.md`).
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
1. Audit which axis to split on. The right answer is usually the one that:
|
|
114
|
+
- Is least likely to be cross-referenced (a "primary vs. icon button" split is cleaner than a "primary vs. lg button").
|
|
115
|
+
- Has the smallest cardinality on the side becoming its own Component.
|
|
116
|
+
2. Build the new Component(s) in a parallel Component Set with a different name (e.g. `IconButton`).
|
|
117
|
+
3. Document the migration on the Cover page or in the Component description (`figma_set_description`):
|
|
118
|
+
"IconButton extracted from Button — was variant=icon-only. Migrate via Swap Instance."
|
|
119
|
+
4. Wait one design cycle (Step 4 of the coordination protocol).
|
|
120
|
+
5. Migrate consumer files via Swap Instance.
|
|
121
|
+
6. Remove the old Variant from the original Component Set.
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
The new Component does NOT inherit instance history. Every instance referencing the extracted Variant has to be re-bound manually. Without coordination this turns into a multi-week regression hunt.
|
|
125
|
+
|
|
126
|
+
### Promote a Primitive to a Semantic Token
|
|
127
|
+
|
|
128
|
+
When you discover a primitive is being used semantically across many places (e.g., `primitive/teal/600` is what every component means by "primary action"), retrofit a semantic Variable on top.
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
1. figma_create_variable → 'color/primary' aliased to 'primitive/teal/600' in every Mode.
|
|
132
|
+
2. Audit usages: find every component fill bound to 'primitive/teal/600' that should be 'color/primary'.
|
|
133
|
+
3. figma_execute → walk components, rebind those fills via setBoundVariableForPaint.
|
|
134
|
+
4. The primitive stays — it's still the leaf value. Components now go through the semantic.
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Safe operation. The primitive's name doesn't change; only the binding layer does. Downstream code that imports the primitive directly continues working; downstream code can adopt the semantic at its own pace.
|
|
138
|
+
|
|
139
|
+
### Restructure Variant Properties (e.g., split `state` into `interactive` + `disabled`)
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
1. Add the new properties in parallel (figma_execute on the Component Set).
|
|
143
|
+
2. Each existing variant gets a default value for the new properties.
|
|
144
|
+
3. Update consumers: each instance has to be inspected. Worst case is fully manual.
|
|
145
|
+
4. Once all instances migrated, remove the old property.
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
This is Breaking. There is no "alias" mechanism for Variant Properties. Always use the coordination protocol.
|
|
149
|
+
|
|
150
|
+
### Split a Library
|
|
151
|
+
|
|
152
|
+
The largest possible migration. Treat it like a code monorepo split: every consumer file is a separate work unit.
|
|
153
|
+
|
|
154
|
+
```
|
|
155
|
+
1. Plan the split first. What lives where, and why?
|
|
156
|
+
2. Create the new Library file (a fresh file with the same conventions; see naming-and-file-structure.md).
|
|
157
|
+
3. Copy the components and Variable Collections that belong in the new Library.
|
|
158
|
+
4. Publish both Libraries.
|
|
159
|
+
5. For each consumer file: Swap to new Library where appropriate. This is the slow step.
|
|
160
|
+
6. Wait one full design cycle.
|
|
161
|
+
7. Remove the moved-out content from the original Library.
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
A Library split is rarely the right answer compared to _organizing_ the existing Library better. Confirm with the user that they have actually outgrown the file (>100 components OR multiple distinct product surfaces) before recommending this.
|
|
165
|
+
|
|
166
|
+
## Post-flight — always
|
|
167
|
+
|
|
168
|
+
After every migration, regardless of size:
|
|
169
|
+
|
|
170
|
+
1. **Re-run the architectural Audit** (`audit-checklist.md`). The exact thing that triggered the migration should now read "Resolved" in the new audit.
|
|
171
|
+
2. **Diff with the snapshot.** What changed beyond the intended scope? Unexpected diffs are bugs.
|
|
172
|
+
3. **Update Component descriptions** with `figma_set_description` if the Component's API changed. The description is what designers see in the asset panel; an out-of-date description is a worse-than-no-doc state.
|
|
173
|
+
4. **Run the codesync exporter** (or have the engineering team run theirs) and verify the diff is exactly the intended change. See `code-sync.md` for the drift sources.
|
|
174
|
+
5. **Update the Cover page note** with what changed, the date, and the rationale. Future-you will thank you.
|
|
175
|
+
|
|
176
|
+
If a migration is large enough to span multiple sessions, treat each session as a self-contained step with its own pre-flight + post-flight. Do not leave the file in an in-between state at the end of a working day.
|
|
177
|
+
|
|
178
|
+
## Out-of-scope here
|
|
179
|
+
|
|
180
|
+
- Visual redesigns where the structure stays the same (just CSS / stroke / radius tweaks). Use Build mode with the existing structure as discovery input.
|
|
181
|
+
- Component implementation changes that don't affect the public Variant Property surface. Treat as a normal `figma_execute` edit, no migration ceremony.
|
|
182
|
+
- Library publishing / versioning workflow itself. That's Figma library mechanics, not architecture.
|