figma-mcp-console 0.5.4 → 0.7.0
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/README.md +4 -0
- package/bin/darwin-amd64/figma-mcp +0 -0
- package/bin/darwin-arm64/figma-mcp +0 -0
- package/bin/linux-amd64/figma-mcp +0 -0
- package/bin/linux-arm64/figma-mcp +0 -0
- package/bin/plugin/code.js +1087 -143
- package/bin/plugin/manifest.json +1 -0
- package/bin/plugin/ui.html +298 -177
- package/bin/windows-amd64/figma-mcp.exe +0 -0
- package/bin/windows-arm64/figma-mcp.exe +0 -0
- package/package.json +2 -2
package/bin/plugin/code.js
CHANGED
|
@@ -2,15 +2,15 @@
|
|
|
2
2
|
// Receives {id, command, params} from the Go bridge (relayed through ui.html),
|
|
3
3
|
// executes it against the Figma Plugin API, and replies {id, result|error}.
|
|
4
4
|
|
|
5
|
-
figma.showUI(__html__, { width:
|
|
5
|
+
figma.showUI(__html__, { width: 280, height: 104 });
|
|
6
6
|
|
|
7
7
|
// Tell the UI which file this plugin window runs in; the UI forwards it to
|
|
8
8
|
// the bridge on every (re)connect so calls can be routed per file when
|
|
9
|
-
// several files run the plugin at once. figma.fileKey
|
|
10
|
-
//
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
});
|
|
9
|
+
// several files run the plugin at once. figma.fileKey needs
|
|
10
|
+
// enablePrivatePluginApi in the manifest, so the file name stays the fallback.
|
|
11
|
+
// readOnly rides along so AI sees it in list_files before it plans an edit.
|
|
12
|
+
const register = () =>
|
|
13
|
+
figma.ui.postMessage({ register: { key: figma.fileKey || undefined, name: figma.root.name, read_only: readOnly } });
|
|
14
14
|
|
|
15
15
|
// ---------- helpers ----------
|
|
16
16
|
|
|
@@ -27,11 +27,92 @@ async function node(id) {
|
|
|
27
27
|
return n;
|
|
28
28
|
}
|
|
29
29
|
|
|
30
|
+
// Pages are addressed by id or name. With documentAccess "dynamic-page" a
|
|
31
|
+
// page's children are unreachable until it is loaded, so load it here.
|
|
32
|
+
async function resolvePage(ref) {
|
|
33
|
+
const want = String(ref);
|
|
34
|
+
const lower = want.toLowerCase();
|
|
35
|
+
const pages = figma.root.children;
|
|
36
|
+
let p = pages.find((x) => x.id === want) || pages.find((x) => x.name.toLowerCase() === lower);
|
|
37
|
+
if (!p) {
|
|
38
|
+
const partial = pages.filter((x) => x.name.toLowerCase().indexOf(lower) !== -1);
|
|
39
|
+
if (partial.length > 1) {
|
|
40
|
+
throw new Error("page " + ref + " is ambiguous: " + partial.map((x) => x.name).join(", "));
|
|
41
|
+
}
|
|
42
|
+
p = partial[0];
|
|
43
|
+
}
|
|
44
|
+
if (!p) throw new Error("page not found: " + ref + " (see list_pages)");
|
|
45
|
+
await p.loadAsync();
|
|
46
|
+
return p;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
// Figma stacks newly combined variants on top of each other and never grows
|
|
50
|
+
// the set to fit them, so the extras are invisible and clipped. Lay them out.
|
|
51
|
+
function arrangeVariants(set) {
|
|
52
|
+
if (set.layoutMode && set.layoutMode !== "NONE") return;
|
|
53
|
+
const gap = 32;
|
|
54
|
+
let y = 0;
|
|
55
|
+
let w = 0;
|
|
56
|
+
for (const v of set.children) {
|
|
57
|
+
v.x = 0;
|
|
58
|
+
v.y = y;
|
|
59
|
+
y += v.height + gap;
|
|
60
|
+
w = Math.max(w, v.width);
|
|
61
|
+
}
|
|
62
|
+
if (y > 0) set.resize(Math.max(w, 1), Math.max(y - gap, 1));
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
// Mutating commands accept one node_id or many node_ids so a bulk edit costs
|
|
66
|
+
// one call instead of one per node.
|
|
67
|
+
async function targets(params) {
|
|
68
|
+
const ids = params.node_ids && params.node_ids.length
|
|
69
|
+
? params.node_ids
|
|
70
|
+
: params.node_id ? [params.node_id] : [];
|
|
71
|
+
if (!ids.length) throw new Error("node_id or node_ids is required");
|
|
72
|
+
const out = [];
|
|
73
|
+
for (const id of ids) out.push(await node(id));
|
|
74
|
+
return out;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// Result of a mutating command. Echoing a full summary per node drowns the
|
|
78
|
+
// caller's context on a 50-node batch, so default to ids and let the caller
|
|
79
|
+
// ask for the rest with verbose.
|
|
80
|
+
function done(params, nodes, extra) {
|
|
81
|
+
const list = Array.isArray(nodes) ? nodes : [nodes];
|
|
82
|
+
const out = params.verbose
|
|
83
|
+
? { nodes: list.map(summarize) }
|
|
84
|
+
: { ok: true, ids: list.map((n) => n.id) };
|
|
85
|
+
return Object.assign(out, extra || {});
|
|
86
|
+
}
|
|
87
|
+
|
|
30
88
|
// Mixed values (figma.mixed) are Symbols, which postMessage cannot clone.
|
|
31
89
|
function val(x) {
|
|
32
90
|
return x === figma.mixed ? "mixed" : x;
|
|
33
91
|
}
|
|
34
92
|
|
|
93
|
+
function rgbToHex(c) {
|
|
94
|
+
const h = (v) => ("0" + Math.round(v * 255).toString(16)).slice(-2);
|
|
95
|
+
return "#" + h(c.r) + h(c.g) + h(c.b);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
// A full PaintObject is ~20 lines of JSON (17-digit float channels, complete
|
|
99
|
+
// gradientTransform); compact callers only ever need the color.
|
|
100
|
+
function paintBrief(p) {
|
|
101
|
+
if (p.visible === false) return "hidden";
|
|
102
|
+
if (p.type !== "SOLID") return p.type;
|
|
103
|
+
const hex = rgbToHex(p.color);
|
|
104
|
+
return p.opacity === undefined || p.opacity === 1 ? hex : hex + "@" + p.opacity;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
// First visible solid fill as hex, for find_nodes' fill filter.
|
|
108
|
+
function solidFillHex(n) {
|
|
109
|
+
if (!("fills" in n) || !Array.isArray(n.fills)) return null;
|
|
110
|
+
for (const p of n.fills) {
|
|
111
|
+
if (p.type === "SOLID" && p.visible !== false) return rgbToHex(p.color);
|
|
112
|
+
}
|
|
113
|
+
return null;
|
|
114
|
+
}
|
|
115
|
+
|
|
35
116
|
function summarize(n) {
|
|
36
117
|
const s = { id: n.id, name: n.name, type: n.type };
|
|
37
118
|
if (n.parent) s.parentId = n.parent.id;
|
|
@@ -41,22 +122,9 @@ function summarize(n) {
|
|
|
41
122
|
return s;
|
|
42
123
|
}
|
|
43
124
|
|
|
44
|
-
// The file key needed to build share links.
|
|
45
|
-
// figma.fileKey
|
|
46
|
-
|
|
47
|
-
// the file via pluginData so it survives reopening.
|
|
48
|
-
const FILE_KEY_DATA = "figma-mcp-file-key";
|
|
49
|
-
let fileKey = figma.fileKey || "";
|
|
50
|
-
try {
|
|
51
|
-
if (!fileKey) fileKey = figma.root.getPluginData(FILE_KEY_DATA) || "";
|
|
52
|
-
} catch (e) {}
|
|
53
|
-
|
|
54
|
-
function setFileKey(key) {
|
|
55
|
-
fileKey = key || "";
|
|
56
|
-
try {
|
|
57
|
-
figma.root.setPluginData(FILE_KEY_DATA, fileKey);
|
|
58
|
-
} catch (e) {}
|
|
59
|
-
}
|
|
125
|
+
// The file key needed to build share links. Development plugins only get
|
|
126
|
+
// figma.fileKey because the manifest sets enablePrivatePluginApi.
|
|
127
|
+
const fileKey = figma.fileKey || "";
|
|
60
128
|
|
|
61
129
|
// nodeLink builds a shareable figma.com URL that jumps straight to a node (the
|
|
62
130
|
// same link as Figma's "Copy link to selection"). Returns null when no file
|
|
@@ -73,16 +141,29 @@ function nodeLink(id) {
|
|
|
73
141
|
);
|
|
74
142
|
}
|
|
75
143
|
|
|
76
|
-
|
|
144
|
+
// compact drops defaults (visible, full opacity, empty fills) and renders
|
|
145
|
+
// paints as hex: depth 1 on a 27-child frame is ~15k tokens otherwise.
|
|
146
|
+
// visibleOnly drops hidden layers (and their subtrees): QC scripts would
|
|
147
|
+
// otherwise report them as missing on the web.
|
|
148
|
+
function serialize(n, depth, compact, visibleOnly) {
|
|
77
149
|
const s = summarize(n);
|
|
78
|
-
if (
|
|
79
|
-
|
|
80
|
-
|
|
150
|
+
if (compact) {
|
|
151
|
+
for (const k of ["x", "y", "width", "height"]) {
|
|
152
|
+
if (typeof s[k] === "number") s[k] = Math.round(s[k] * 100) / 100;
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
if ("visible" in n && (!compact || !n.visible)) s.visible = n.visible;
|
|
156
|
+
if ("opacity" in n && (!compact || n.opacity !== 1)) s.opacity = n.opacity;
|
|
157
|
+
if ("fills" in n && Array.isArray(n.fills) && (!compact || n.fills.length)) {
|
|
158
|
+
s.fills = compact ? n.fills.map(paintBrief) : n.fills;
|
|
159
|
+
}
|
|
81
160
|
if ("strokes" in n && n.strokes.length) {
|
|
82
|
-
s.strokes = n.strokes;
|
|
83
|
-
s.strokeWeight = val(n.strokeWeight);
|
|
161
|
+
s.strokes = compact ? n.strokes.map(paintBrief) : n.strokes;
|
|
162
|
+
if (!compact || val(n.strokeWeight) !== 1) s.strokeWeight = val(n.strokeWeight);
|
|
163
|
+
}
|
|
164
|
+
if ("effects" in n && n.effects.length) {
|
|
165
|
+
s.effects = compact ? n.effects.map((e) => e.type) : n.effects;
|
|
84
166
|
}
|
|
85
|
-
if ("effects" in n && n.effects.length) s.effects = n.effects;
|
|
86
167
|
if ("cornerRadius" in n && n.cornerRadius !== 0) s.cornerRadius = val(n.cornerRadius);
|
|
87
168
|
if (n.type === "TEXT") {
|
|
88
169
|
s.fontSize = val(n.fontSize);
|
|
@@ -98,13 +179,109 @@ function serialize(n, depth) {
|
|
|
98
179
|
s.primaryAxisAlignItems = n.primaryAxisAlignItems;
|
|
99
180
|
s.counterAxisAlignItems = n.counterAxisAlignItems;
|
|
100
181
|
}
|
|
182
|
+
// Sizes auto layout computes (fill, hug) and layers pinned outside the flow,
|
|
183
|
+
// so diff_design reports only what the designer set. FIXED is the default, left out.
|
|
184
|
+
try {
|
|
185
|
+
if (n.layoutSizingHorizontal && n.layoutSizingHorizontal !== "FIXED") s.layoutSizingHorizontal = n.layoutSizingHorizontal;
|
|
186
|
+
if (n.layoutSizingVertical && n.layoutSizingVertical !== "FIXED") s.layoutSizingVertical = n.layoutSizingVertical;
|
|
187
|
+
if (n.layoutPositioning === "ABSOLUTE") s.layoutPositioning = "ABSOLUTE";
|
|
188
|
+
} catch (e) {}
|
|
189
|
+
// Designer notes and variant values; each getter can throw on node types or
|
|
190
|
+
// plans that lack it, which must not sink the whole tree.
|
|
191
|
+
try {
|
|
192
|
+
if ("annotations" in n && n.annotations.length) {
|
|
193
|
+
s.annotations = n.annotations.map((a) => ({
|
|
194
|
+
label: a.labelMarkdown || a.label || "",
|
|
195
|
+
properties: (a.properties || []).map((p) => p.type),
|
|
196
|
+
}));
|
|
197
|
+
}
|
|
198
|
+
} catch (e) {}
|
|
199
|
+
try {
|
|
200
|
+
if ((n.type === "INSTANCE" || n.type === "COMPONENT") && n.variantProperties) {
|
|
201
|
+
s.variant = n.variantProperties;
|
|
202
|
+
}
|
|
203
|
+
} catch (e) {}
|
|
204
|
+
if (n.type === "COMPONENT_SET") {
|
|
205
|
+
const opts = variantOptions(n);
|
|
206
|
+
if (opts) s.variantOptions = opts;
|
|
207
|
+
}
|
|
208
|
+
// Dashed vs solid borders, and the tokens/styles behind the raw values: ids
|
|
209
|
+
// here, swapped for names by resolveRefs once the (sync) walk is done.
|
|
210
|
+
if ("dashPattern" in n && n.dashPattern.length) s.dashPattern = n.dashPattern;
|
|
211
|
+
try {
|
|
212
|
+
if (n.boundVariables && Object.keys(n.boundVariables).length) s.boundVariables = Object.assign({}, n.boundVariables); // a copy: resolveRefs rewrites it
|
|
213
|
+
} catch (e) {}
|
|
214
|
+
for (const k of STYLE_KEYS) {
|
|
215
|
+
if (k in n && typeof n[k] === "string" && n[k]) s[k] = n[k];
|
|
216
|
+
}
|
|
217
|
+
// Text mixing fonts, sizes or colors (one bold word, a red asterisk) reads
|
|
218
|
+
// as "mixed" above; list the runs so nothing hides behind it.
|
|
219
|
+
if (n.type === "TEXT" && [n.fontName, n.fontSize, n.fills, n.textDecoration].includes(figma.mixed)) {
|
|
220
|
+
try {
|
|
221
|
+
s.segments = n.getStyledTextSegments(["fontName", "fontSize", "fills", "textDecoration"]).map((g) => {
|
|
222
|
+
const seg = { text: g.characters, font: g.fontName.family + " " + g.fontName.style, size: g.fontSize, fill: g.fills.map(paintBrief).join(", ") };
|
|
223
|
+
if (g.textDecoration !== "NONE") seg.decoration = g.textDecoration;
|
|
224
|
+
return seg;
|
|
225
|
+
});
|
|
226
|
+
} catch (e) {}
|
|
227
|
+
}
|
|
101
228
|
if ("children" in n) {
|
|
102
|
-
|
|
103
|
-
if (
|
|
229
|
+
const kids = visibleOnly ? n.children.filter((c) => c.visible !== false) : n.children;
|
|
230
|
+
if (!compact || kids.length) {
|
|
231
|
+
s.childCount = kids.length;
|
|
232
|
+
if (depth > 0) s.children = kids.map((c) => serialize(c, depth - 1, compact, visibleOnly));
|
|
233
|
+
}
|
|
104
234
|
}
|
|
105
235
|
return s;
|
|
106
236
|
}
|
|
107
237
|
|
|
238
|
+
const STYLE_KEYS = ["fillStyleId", "strokeStyleId", "textStyleId", "effectStyleId"];
|
|
239
|
+
|
|
240
|
+
// Replace variable and style ids in a serialized tree with their names
|
|
241
|
+
// ("color/primary/500", "Heading/H1"), so a reader can match them to tokens.
|
|
242
|
+
async function resolveRefs(root) {
|
|
243
|
+
const cache = new Map();
|
|
244
|
+
const name = async (id, style) => {
|
|
245
|
+
if (!cache.has(id)) {
|
|
246
|
+
let x = null;
|
|
247
|
+
try {
|
|
248
|
+
x = style ? await figma.getStyleByIdAsync(id) : await figma.variables.getVariableByIdAsync(id);
|
|
249
|
+
} catch (e) {}
|
|
250
|
+
cache.set(id, x ? x.name : id);
|
|
251
|
+
}
|
|
252
|
+
return cache.get(id);
|
|
253
|
+
};
|
|
254
|
+
const alias = async (v) =>
|
|
255
|
+
Array.isArray(v) ? Promise.all(v.map(alias)) : v && v.type === "VARIABLE_ALIAS" ? name(v.id) : v;
|
|
256
|
+
const walk = async (s) => {
|
|
257
|
+
if (s.boundVariables) {
|
|
258
|
+
for (const k of Object.keys(s.boundVariables)) s.boundVariables[k] = await alias(s.boundVariables[k]);
|
|
259
|
+
}
|
|
260
|
+
for (const k of STYLE_KEYS) {
|
|
261
|
+
if (s[k]) {
|
|
262
|
+
s[k.slice(0, -2)] = await name(s[k], true); // fillStyleId -> fillStyle
|
|
263
|
+
delete s[k];
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
if (s.children) for (const c of s.children) await walk(c);
|
|
267
|
+
};
|
|
268
|
+
await walk(root);
|
|
269
|
+
return root;
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
// {property: [values]} for a component set's variant properties, or null.
|
|
273
|
+
function variantOptions(set) {
|
|
274
|
+
try {
|
|
275
|
+
const out = {};
|
|
276
|
+
for (const [k, d] of Object.entries(set.componentPropertyDefinitions)) {
|
|
277
|
+
if (d.type === "VARIANT") out[k.replace(/#.*$/, "")] = d.variantOptions || [];
|
|
278
|
+
}
|
|
279
|
+
return Object.keys(out).length ? out : null;
|
|
280
|
+
} catch (e) {
|
|
281
|
+
return null;
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
|
|
108
285
|
async function parentOf(params) {
|
|
109
286
|
if (params.parent_id) {
|
|
110
287
|
const p = await node(params.parent_id);
|
|
@@ -171,11 +348,249 @@ function buildEffects(list) {
|
|
|
171
348
|
}
|
|
172
349
|
|
|
173
350
|
function applyShapeParams(n, params) {
|
|
174
|
-
n.x = params.x;
|
|
175
|
-
n.y = params.y;
|
|
351
|
+
n.x = params.x || 0;
|
|
352
|
+
n.y = params.y || 0;
|
|
176
353
|
if (params.width > 0 && params.height > 0) n.resize(params.width, params.height);
|
|
177
354
|
if (params.name) n.name = params.name;
|
|
178
|
-
if (params.fill_color
|
|
355
|
+
if (params.fill_color && params.fill_color !== "none") {
|
|
356
|
+
n.fills = [{ type: "SOLID", color: hexToRGB(params.fill_color) }];
|
|
357
|
+
}
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
// Optional extras find_nodes can attach per node, so callers can filter on
|
|
361
|
+
// style without a get_design_context round-trip per hit.
|
|
362
|
+
const FIELD_GETTERS = {
|
|
363
|
+
fills: (n) => ("fills" in n && Array.isArray(n.fills) ? n.fills.map(paintBrief) : undefined),
|
|
364
|
+
strokes: (n) => ("strokes" in n && Array.isArray(n.strokes) && n.strokes.length ? n.strokes.map(paintBrief) : undefined),
|
|
365
|
+
fontSize: (n) => (n.type === "TEXT" ? val(n.fontSize) : undefined),
|
|
366
|
+
fontName: (n) => (n.type === "TEXT" ? val(n.fontName) : undefined),
|
|
367
|
+
cornerRadius: (n) => ("cornerRadius" in n ? val(n.cornerRadius) : undefined),
|
|
368
|
+
effects: (n) => ("effects" in n && n.effects.length ? n.effects.map((e) => e.type) : undefined),
|
|
369
|
+
opacity: (n) => ("opacity" in n ? n.opacity : undefined),
|
|
370
|
+
characters: (n) => (n.type === "TEXT" ? n.characters : undefined),
|
|
371
|
+
};
|
|
372
|
+
|
|
373
|
+
// ---------- prototyping ----------
|
|
374
|
+
|
|
375
|
+
const TRIGGERS = ["ON_CLICK", "ON_HOVER", "ON_PRESS", "ON_DRAG"];
|
|
376
|
+
const NAVIGATIONS = ["NAVIGATE", "SWAP", "OVERLAY", "BACK", "CLOSE"];
|
|
377
|
+
// Directional transitions carry a direction; the rest only easing/duration.
|
|
378
|
+
const DIRECTIONAL_TRANSITIONS = ["MOVE_IN", "MOVE_OUT", "PUSH", "SLIDE_IN", "SLIDE_OUT"];
|
|
379
|
+
const SIMPLE_TRANSITIONS = ["DISSOLVE", "SMART_ANIMATE", "SCROLL_ANIMATE"];
|
|
380
|
+
|
|
381
|
+
function buildTransition(item) {
|
|
382
|
+
const type = (item.transition || "").toUpperCase();
|
|
383
|
+
if (!type || type === "NONE" || type === "INSTANT") return null;
|
|
384
|
+
const directional = DIRECTIONAL_TRANSITIONS.indexOf(type) !== -1;
|
|
385
|
+
if (!directional && SIMPLE_TRANSITIONS.indexOf(type) === -1) {
|
|
386
|
+
throw new Error(
|
|
387
|
+
"unsupported transition: " + type + " (use " +
|
|
388
|
+
SIMPLE_TRANSITIONS.concat(DIRECTIONAL_TRANSITIONS).join(", ") + ")",
|
|
389
|
+
);
|
|
390
|
+
}
|
|
391
|
+
const t = {
|
|
392
|
+
type,
|
|
393
|
+
easing: { type: (item.easing || "EASE_OUT").toUpperCase() },
|
|
394
|
+
duration: item.duration === undefined || item.duration === null ? 0.3 : item.duration,
|
|
395
|
+
};
|
|
396
|
+
if (directional) {
|
|
397
|
+
t.direction = (item.direction || "LEFT").toUpperCase();
|
|
398
|
+
t.matchLayers = false;
|
|
399
|
+
}
|
|
400
|
+
return t;
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
async function buildReaction(item) {
|
|
404
|
+
const trigger = (item.trigger || "ON_CLICK").toUpperCase();
|
|
405
|
+
if (TRIGGERS.indexOf(trigger) === -1) {
|
|
406
|
+
throw new Error("unsupported trigger: " + trigger + " (use " + TRIGGERS.join(", ") + ")");
|
|
407
|
+
}
|
|
408
|
+
const navigation = (item.navigation || "NAVIGATE").toUpperCase();
|
|
409
|
+
if (NAVIGATIONS.indexOf(navigation) === -1) {
|
|
410
|
+
throw new Error("unsupported navigation: " + navigation + " (use " + NAVIGATIONS.join(", ") + ")");
|
|
411
|
+
}
|
|
412
|
+
const needsDestination = navigation !== "BACK" && navigation !== "CLOSE";
|
|
413
|
+
if (needsDestination && !item.destination_id) {
|
|
414
|
+
throw new Error("destination_id is required for " + navigation + "; only BACK and CLOSE take none");
|
|
415
|
+
}
|
|
416
|
+
// BACK and CLOSE are action types of their own, not navigations of a NODE
|
|
417
|
+
// action; sending them as a navigation fails validation.
|
|
418
|
+
if (!needsDestination) {
|
|
419
|
+
return { trigger: { type: trigger }, actions: [{ type: navigation }] };
|
|
420
|
+
}
|
|
421
|
+
// Resolve the destination here so a stale id fails by name, not as an
|
|
422
|
+
// opaque setReactionsAsync rejection.
|
|
423
|
+
await node(item.destination_id);
|
|
424
|
+
return {
|
|
425
|
+
trigger: { type: trigger },
|
|
426
|
+
actions: [{
|
|
427
|
+
type: "NODE",
|
|
428
|
+
destinationId: item.destination_id,
|
|
429
|
+
navigation,
|
|
430
|
+
transition: buildTransition(item),
|
|
431
|
+
preserveScrollPosition: false,
|
|
432
|
+
}],
|
|
433
|
+
};
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
// The page owning a node; flowStartingPoints lives on the page, which is not
|
|
437
|
+
// necessarily the open one.
|
|
438
|
+
function pageOf(n) {
|
|
439
|
+
while (n && n.type !== "PAGE") n = n.parent;
|
|
440
|
+
if (!n) throw new Error("node is not on a page");
|
|
441
|
+
return n;
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
|
|
445
|
+
// Right of everything already on the page, top-aligned with it.
|
|
446
|
+
function placeInFreeSpace(n, page) {
|
|
447
|
+
const others = page.children.filter((c) => c !== n && "width" in c);
|
|
448
|
+
if (!others.length) return;
|
|
449
|
+
n.x = Math.max.apply(null, others.map((c) => c.x + c.width)) + 100;
|
|
450
|
+
n.y = Math.min.apply(null, others.map((c) => c.y));
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
// ---------- design audit ----------
|
|
454
|
+
|
|
455
|
+
const EPS = 1; // sub-pixel noise from auto layout, rotation and vector bounds: never visible
|
|
456
|
+
|
|
457
|
+
function intersect(a, b) {
|
|
458
|
+
const x = Math.max(a.x, b.x), y = Math.max(a.y, b.y);
|
|
459
|
+
const r = Math.min(a.x + a.width, b.x + b.width), bt = Math.min(a.y + a.height, b.y + b.height);
|
|
460
|
+
return { x, y, width: Math.max(0, r - x), height: Math.max(0, bt - y) };
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
// How far box a sticks out of box b, per side; null when it does not.
|
|
464
|
+
function spill(a, b) {
|
|
465
|
+
const o = {
|
|
466
|
+
left: b.x - a.x, top: b.y - a.y,
|
|
467
|
+
right: a.x + a.width - (b.x + b.width), bottom: a.y + a.height - (b.y + b.height),
|
|
468
|
+
};
|
|
469
|
+
const out = {};
|
|
470
|
+
for (const k in o) if (o[k] > EPS) out[k] = Math.round(o[k] * 10) / 10;
|
|
471
|
+
return Object.keys(out).length ? out : null;
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
// Topmost visible paint: an {r,g,b} color when it is an opaque solid, "unknown"
|
|
475
|
+
// for images, gradients and translucent fills (no single color to measure
|
|
476
|
+
// against), null when the node paints nothing.
|
|
477
|
+
function topFill(n) {
|
|
478
|
+
if (!("fills" in n) || !Array.isArray(n.fills)) return null;
|
|
479
|
+
for (let i = n.fills.length - 1; i >= 0; i--) {
|
|
480
|
+
const p = n.fills[i];
|
|
481
|
+
if (p.visible === false) continue;
|
|
482
|
+
if (p.type !== "SOLID" || (p.opacity !== undefined && p.opacity < 1) || ("opacity" in n && n.opacity < 1)) return "unknown";
|
|
483
|
+
return p.color;
|
|
484
|
+
}
|
|
485
|
+
return null;
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
// What a text layer is drawn on: the nearest thing behind it that paints,
|
|
489
|
+
// either a sibling lower in the stack that covers it (the hand-drawn
|
|
490
|
+
// "rectangle as background") or an ancestor's own fill.
|
|
491
|
+
function backgroundOf(t) {
|
|
492
|
+
const box = t.absoluteBoundingBox;
|
|
493
|
+
for (let n = t; n.parent && n.parent.type !== "DOCUMENT"; n = n.parent) {
|
|
494
|
+
const sibs = n.parent.children || [];
|
|
495
|
+
for (let i = sibs.indexOf(n) - 1; i >= 0; i--) {
|
|
496
|
+
const s = sibs[i];
|
|
497
|
+
if (s.visible === false || !s.absoluteBoundingBox || spill(box, s.absoluteBoundingBox)) continue;
|
|
498
|
+
const f = topFill(s);
|
|
499
|
+
if (f) return f;
|
|
500
|
+
}
|
|
501
|
+
const f = n.parent.type === "PAGE" ? null : topFill(n.parent);
|
|
502
|
+
if (f) return f;
|
|
503
|
+
}
|
|
504
|
+
return "unknown";
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
// WCAG 2.x relative luminance and contrast ratio.
|
|
508
|
+
function luminance(c) {
|
|
509
|
+
const f = (v) => (v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
|
|
510
|
+
return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b);
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
function contrastRatio(a, b) {
|
|
514
|
+
const la = luminance(a), lb = luminance(b);
|
|
515
|
+
return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
// WCAG exempts inactive controls from contrast: text inside an instance whose
|
|
519
|
+
// variant says Disabled (State=Disabled, Disabled=true, ...) is not measured.
|
|
520
|
+
function inDisabledControl(n) {
|
|
521
|
+
for (let p = n.parent; p && p.type !== "PAGE"; p = p.parent) {
|
|
522
|
+
if (p.type !== "INSTANCE") continue;
|
|
523
|
+
let v = null;
|
|
524
|
+
try {
|
|
525
|
+
v = p.variantProperties;
|
|
526
|
+
} catch (e) {}
|
|
527
|
+
for (const k in v || {}) {
|
|
528
|
+
if (/^(disabled?|inactive)$/i.test(v[k]) || (/disabled/i.test(k) && /^(true|yes|on)$/i.test(v[k]))) return true;
|
|
529
|
+
}
|
|
530
|
+
}
|
|
531
|
+
return false;
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
// Layers a finger is expected to hit: anything wired in the prototype, or
|
|
535
|
+
// named like a control.
|
|
536
|
+
const CONTROL_NAME = /\b(button|btn|link|tab|chip|checkbox|radio|switch|toggle|icon[-_ ]?button)\b/i;
|
|
537
|
+
|
|
538
|
+
function isControl(n) {
|
|
539
|
+
if ("reactions" in n && n.reactions && n.reactions.length) return true;
|
|
540
|
+
return (n.type === "INSTANCE" || n.type === "FRAME" || n.type === "COMPONENT") && CONTROL_NAME.test(n.name);
|
|
541
|
+
}
|
|
542
|
+
|
|
543
|
+
// "$2" in a batch op's params stands for the id of the node op 2 produced,
|
|
544
|
+
// so a frame and its children can be created in one call.
|
|
545
|
+
function resolveBatchRefs(v, results) {
|
|
546
|
+
if (Array.isArray(v)) return v.map((x) => resolveBatchRefs(x, results));
|
|
547
|
+
if (v && typeof v === "object") {
|
|
548
|
+
const out = {};
|
|
549
|
+
for (const k in v) out[k] = resolveBatchRefs(v[k], results);
|
|
550
|
+
return out;
|
|
551
|
+
}
|
|
552
|
+
const m = typeof v === "string" ? /^\$(\d+)$/.exec(v) : null;
|
|
553
|
+
if (!m) return v;
|
|
554
|
+
const r = results[+m[1]];
|
|
555
|
+
if (!r) throw new Error(v + " refers to an op that has not run yet; refs only point backwards");
|
|
556
|
+
const res = r.result || {};
|
|
557
|
+
const id = res.id || (res.ids && res.ids[0]) || (res.nodes && res.nodes[0] && res.nodes[0].id);
|
|
558
|
+
if (!id) throw new Error(v + " has no node id: op " + m[1] + (r.error ? " failed" : " did not return a node"));
|
|
559
|
+
return id;
|
|
560
|
+
}
|
|
561
|
+
|
|
562
|
+
// These carry megabytes of base64 or need the server's filesystem/network, so
|
|
563
|
+
// they only work as their own tool call.
|
|
564
|
+
const NOT_BATCHABLE = ["batch", "download_assets", "import_image", "get_screenshot"];
|
|
565
|
+
|
|
566
|
+
// An SVG becomes editable vector layers (createImage takes only PNG, JPG and
|
|
567
|
+
// GIF), scaled as a whole so stroke widths keep their proportion, the way a
|
|
568
|
+
// designer scales an icon.
|
|
569
|
+
async function importSvg(params) {
|
|
570
|
+
if (params.node_id) {
|
|
571
|
+
throw new Error("an SVG becomes layers, not a fill: omit node_id, and pass parent_id to place it inside a node");
|
|
572
|
+
}
|
|
573
|
+
const n = figma.createNodeFromSvg(params.svg);
|
|
574
|
+
n.fills = []; // the wrapper frame; the SVG's own shapes are its children
|
|
575
|
+
if (params.name) n.name = params.name;
|
|
576
|
+
if (params.color) {
|
|
577
|
+
const c = hexToRGB(params.color);
|
|
578
|
+
// Icons draw with fills or strokes (lucide uses strokes); recolor every
|
|
579
|
+
// solid paint and keep its opacity.
|
|
580
|
+
const recolor = (paints) => paints.map((p) => (p.type === "SOLID" ? Object.assign({}, p, { color: c }) : p));
|
|
581
|
+
for (const d of n.findAll(() => true)) {
|
|
582
|
+
if ("fills" in d && Array.isArray(d.fills) && d.fills.length) d.fills = recolor(d.fills);
|
|
583
|
+
if ("strokes" in d && Array.isArray(d.strokes) && d.strokes.length) d.strokes = recolor(d.strokes);
|
|
584
|
+
}
|
|
585
|
+
}
|
|
586
|
+
const w = params.width > 0 ? params.width / n.width : 0;
|
|
587
|
+
const h = params.height > 0 ? params.height / n.height : 0;
|
|
588
|
+
const scale = w && h ? Math.min(w, h) : w || h;
|
|
589
|
+
if (scale && Math.abs(scale - 1) > 1e-6) n.rescale(scale);
|
|
590
|
+
n.x = params.x || 0;
|
|
591
|
+
n.y = params.y || 0;
|
|
592
|
+
(await parentOf(params)).appendChild(n);
|
|
593
|
+
return summarize(n);
|
|
179
594
|
}
|
|
180
595
|
|
|
181
596
|
// ---------- command handlers (names match MCP tool names) ----------
|
|
@@ -189,6 +604,23 @@ const handlers = {
|
|
|
189
604
|
};
|
|
190
605
|
},
|
|
191
606
|
|
|
607
|
+
async list_pages() {
|
|
608
|
+
return {
|
|
609
|
+
currentPage: figma.currentPage.name,
|
|
610
|
+
pages: figma.root.children.map((p) => ({
|
|
611
|
+
id: p.id,
|
|
612
|
+
name: p.name,
|
|
613
|
+
current: p.id === figma.currentPage.id,
|
|
614
|
+
})),
|
|
615
|
+
};
|
|
616
|
+
},
|
|
617
|
+
|
|
618
|
+
async set_current_page(params) {
|
|
619
|
+
const p = await resolvePage(params.page);
|
|
620
|
+
await figma.setCurrentPageAsync(p);
|
|
621
|
+
return { id: p.id, name: p.name, childCount: p.children.length };
|
|
622
|
+
},
|
|
623
|
+
|
|
192
624
|
async get_selection() {
|
|
193
625
|
return figma.currentPage.selection.map((n) => {
|
|
194
626
|
const s = summarize(n);
|
|
@@ -200,16 +632,219 @@ const handlers = {
|
|
|
200
632
|
|
|
201
633
|
async get_design_context(params) {
|
|
202
634
|
const depth = params.depth === undefined ? 2 : params.depth;
|
|
203
|
-
return serialize(await node(params.node_id), depth);
|
|
635
|
+
return resolveRefs(serialize(await node(params.node_id), depth, !!params.compact, !!params.visible_only));
|
|
636
|
+
},
|
|
637
|
+
|
|
638
|
+
// Every component used under node_id, grouped by component (set), with all
|
|
639
|
+
// the states its set defines and the state each instance is in, so testers
|
|
640
|
+
// can write a case per state. Library components resolve too when Figma
|
|
641
|
+
// has their set loaded.
|
|
642
|
+
async get_component_states(params) {
|
|
643
|
+
const root = await node(params.node_id);
|
|
644
|
+
const instances = "findAllWithCriteria" in root ? root.findAllWithCriteria({ types: ["INSTANCE"] }) : [];
|
|
645
|
+
if (root.type === "INSTANCE") instances.unshift(root);
|
|
646
|
+
const groups = new Map();
|
|
647
|
+
for (const inst of instances) {
|
|
648
|
+
if (!inst.visible) continue;
|
|
649
|
+
const main = await inst.getMainComponentAsync();
|
|
650
|
+
if (!main) continue;
|
|
651
|
+
const set = main.parent && main.parent.type === "COMPONENT_SET" ? main.parent : null;
|
|
652
|
+
const owner = set || main;
|
|
653
|
+
let g = groups.get(owner.id);
|
|
654
|
+
if (!g) {
|
|
655
|
+
g = { component: owner.name, id: owner.id, library: !!main.remote, count: 0, used: [] };
|
|
656
|
+
if (set) {
|
|
657
|
+
const opts = variantOptions(set);
|
|
658
|
+
if (opts) g.states = opts;
|
|
659
|
+
else g.statesError = "variant list not readable";
|
|
660
|
+
}
|
|
661
|
+
groups.set(owner.id, g);
|
|
662
|
+
}
|
|
663
|
+
g.count++;
|
|
664
|
+
let state = null;
|
|
665
|
+
try {
|
|
666
|
+
state = inst.variantProperties;
|
|
667
|
+
} catch (e) {}
|
|
668
|
+
if (state) {
|
|
669
|
+
g.usedStates = g.usedStates || {};
|
|
670
|
+
for (const [k, v] of Object.entries(state)) {
|
|
671
|
+
const vals = (g.usedStates[k] = g.usedStates[k] || []);
|
|
672
|
+
if (!vals.includes(v)) vals.push(v);
|
|
673
|
+
}
|
|
674
|
+
}
|
|
675
|
+
if (g.used.length < 10) {
|
|
676
|
+
const u = { id: inst.id, name: inst.name };
|
|
677
|
+
if (state) u.state = state;
|
|
678
|
+
g.used.push(u);
|
|
679
|
+
}
|
|
680
|
+
// Hand edits on top of the component (a "Disabled" button recolored by
|
|
681
|
+
// hand) are what testers miss; list which layer and which fields.
|
|
682
|
+
let ovs = [];
|
|
683
|
+
try {
|
|
684
|
+
ovs = inst.overrides || [];
|
|
685
|
+
} catch (e) {}
|
|
686
|
+
if (ovs.length) {
|
|
687
|
+
g.overridden = (g.overridden || 0) + 1;
|
|
688
|
+
g.overrides = g.overrides || [];
|
|
689
|
+
if (g.overrides.length < 10) {
|
|
690
|
+
const layers = [];
|
|
691
|
+
for (const o of ovs) {
|
|
692
|
+
const n = o.id === inst.id ? inst : await figma.getNodeByIdAsync(o.id);
|
|
693
|
+
layers.push({ layer: n ? n.name : o.id, fields: o.overriddenFields });
|
|
694
|
+
}
|
|
695
|
+
g.overrides.push({ id: inst.id, name: inst.name, layers });
|
|
696
|
+
}
|
|
697
|
+
}
|
|
698
|
+
}
|
|
699
|
+
return [...groups.values()].sort((a, b) => b.count - a.count);
|
|
204
700
|
},
|
|
205
701
|
|
|
206
702
|
async create_frame(params) {
|
|
207
703
|
const f = figma.createFrame();
|
|
704
|
+
const parent = await parentOf(params);
|
|
705
|
+
const topLevel = parent.type === "PAGE" || parent.type === "SECTION";
|
|
706
|
+
// A frame inside another is almost always a layout wrapper, and Figma's
|
|
707
|
+
// white default turns every wrapper into a white slab over the design.
|
|
708
|
+
// Top-level frames are screens and keep it.
|
|
709
|
+
if (params.fill_color === "none" || (!params.fill_color && !topLevel)) f.fills = [];
|
|
208
710
|
applyShapeParams(f, params);
|
|
209
|
-
|
|
711
|
+
parent.appendChild(f);
|
|
712
|
+
// A screen created without a position goes beside the existing work
|
|
713
|
+
// instead of on top of it at 0,0.
|
|
714
|
+
if (parent.type === "PAGE" && params.x == null && params.y == null) placeInFreeSpace(f, parent);
|
|
210
715
|
return summarize(f);
|
|
211
716
|
},
|
|
212
717
|
|
|
718
|
+
// Findings only: what a screenshot shows but a model reading it tends to
|
|
719
|
+
// miss. Reads the rendered geometry, never changes the document.
|
|
720
|
+
async audit_design(params) {
|
|
721
|
+
const root = await node(params.node_id);
|
|
722
|
+
if (!root.absoluteBoundingBox) throw new Error("node " + root.id + " is " + root.type + " and has no box to audit; pass a frame, section or component");
|
|
723
|
+
const want = params.checks && params.checks.length ? params.checks : ["layout", "contrast"];
|
|
724
|
+
for (const c of want) {
|
|
725
|
+
if (["layout", "contrast"].indexOf(c) === -1) throw new Error("unknown check: " + c + " (use layout, contrast)");
|
|
726
|
+
}
|
|
727
|
+
const layout = want.indexOf("layout") !== -1, contrast = want.indexOf("contrast") !== -1;
|
|
728
|
+
const minTouch = params.min_touch > 0 ? params.min_touch : 0;
|
|
729
|
+
const max = params.max_results || 100;
|
|
730
|
+
const issues = [], summary = {};
|
|
731
|
+
let checked = 0, contrastUnknown = 0, disabledSkipped = 0;
|
|
732
|
+
const report = (n, issue, detail) => {
|
|
733
|
+
summary[issue] = (summary[issue] || 0) + 1;
|
|
734
|
+
if (issues.length < max) issues.push(Object.assign({ id: n.id, name: n.name, issue }, detail));
|
|
735
|
+
};
|
|
736
|
+
let insideInstances = 0;
|
|
737
|
+
// clip: the visible window left by every clipping ancestor, or null.
|
|
738
|
+
// inInstance: geometry inside an instance belongs to its component and
|
|
739
|
+
// cannot be fixed on this screen (an icon's vector parts poking out of its
|
|
740
|
+
// own frame), so only contrast and touch size are checked there.
|
|
741
|
+
const walk = (n, clip, parentCut, inInstance) => {
|
|
742
|
+
if (n.visible === false) return;
|
|
743
|
+
const box = n.absoluteBoundingBox;
|
|
744
|
+
if (!box) return;
|
|
745
|
+
checked++;
|
|
746
|
+
let cut = parentCut;
|
|
747
|
+
if (inInstance) insideInstances++;
|
|
748
|
+
if (layout && n !== root && !inInstance) {
|
|
749
|
+
const seen = clip ? intersect(box, clip) : box;
|
|
750
|
+
if (clip && !parentCut && (seen.width <= EPS || seen.height <= EPS)) {
|
|
751
|
+
// Nothing of it shows, so nothing inside it is worth reporting.
|
|
752
|
+
report(n, "hidden_by_clip", { clippedBy: clip.id });
|
|
753
|
+
return;
|
|
754
|
+
}
|
|
755
|
+
const over = clip && !parentCut ? spill(box, clip) : null;
|
|
756
|
+
if (over) {
|
|
757
|
+
report(n, "clipped", { clippedBy: clip.id, cutOff: over });
|
|
758
|
+
cut = true;
|
|
759
|
+
} else if (n.parent && n.parent.absoluteBoundingBox && n.parent.type !== "GROUP" && !parentCut) {
|
|
760
|
+
const out = spill(box, n.parent.absoluteBoundingBox);
|
|
761
|
+
if (out) report(n, "overflows_parent", { parent: n.parent.id, by: out });
|
|
762
|
+
}
|
|
763
|
+
}
|
|
764
|
+
if (n.type === "TEXT") {
|
|
765
|
+
if (layout && !inInstance) {
|
|
766
|
+
// A fixed-size text box does not grow with its content: the glyphs
|
|
767
|
+
// either spill out of it or are cut with an ellipsis.
|
|
768
|
+
const rb = n.absoluteRenderBounds;
|
|
769
|
+
const fixed = n.textAutoResize === "NONE" || n.textAutoResize === "TRUNCATE";
|
|
770
|
+
const out = fixed && rb ? spill(rb, box) : null;
|
|
771
|
+
if (out && (out.right || out.bottom)) report(n, "text_overflows_box", { by: out });
|
|
772
|
+
const size = typeof n.fontSize === "number" ? n.fontSize : 14;
|
|
773
|
+
const lines = n.maxLines > 0 ? n.maxLines : Math.max(1, Math.floor(box.height / (size * 1.2)));
|
|
774
|
+
// shortcut: half the font size per character is a lower bound on
|
|
775
|
+
// width, so this only catches clear cases; measuring needs a clone,
|
|
776
|
+
// and an audit must not touch the document.
|
|
777
|
+
if ((n.textTruncation === "ENDING" || n.textAutoResize === "TRUNCATE") &&
|
|
778
|
+
(n.characters || "").length * size * 0.5 > box.width * lines) {
|
|
779
|
+
report(n, "text_truncated", { text: n.characters.slice(0, 60) });
|
|
780
|
+
}
|
|
781
|
+
}
|
|
782
|
+
if (contrast && (n.characters || "").trim()) {
|
|
783
|
+
const fg = topFill(n), bg = fg && fg !== "unknown" ? backgroundOf(n) : "unknown";
|
|
784
|
+
if (!fg || inDisabledControl(n)) {
|
|
785
|
+
// paints nothing, or a disabled control's label: exempt
|
|
786
|
+
if (fg) disabledSkipped++;
|
|
787
|
+
} else if (fg === "unknown" || bg === "unknown") {
|
|
788
|
+
contrastUnknown++;
|
|
789
|
+
} else {
|
|
790
|
+
const size = typeof n.fontSize === "number" ? n.fontSize : 0;
|
|
791
|
+
const bold = n.fontName && n.fontName !== figma.mixed && /bold|black|heavy/i.test(n.fontName.style || "");
|
|
792
|
+
// WCAG AA: 3:1 for large text (24px, or 18.66px bold), else 4.5:1.
|
|
793
|
+
const need = size >= 24 || (bold && size >= 18.66) ? 3 : 4.5;
|
|
794
|
+
const ratio = contrastRatio(fg, bg);
|
|
795
|
+
if (ratio < need) {
|
|
796
|
+
report(n, "low_contrast", { ratio: Math.round(ratio * 100) / 100, required: need, text: rgbToHex(fg), background: rgbToHex(bg) });
|
|
797
|
+
}
|
|
798
|
+
}
|
|
799
|
+
}
|
|
800
|
+
}
|
|
801
|
+
if (minTouch && isControl(n) && (box.width < minTouch - EPS || box.height < minTouch - EPS)) {
|
|
802
|
+
report(n, "small_touch_target", { width: Math.round(box.width), height: Math.round(box.height), required: minTouch });
|
|
803
|
+
}
|
|
804
|
+
if (!("children" in n) || n.type === "BOOLEAN_OPERATION") return;
|
|
805
|
+
let inner = clip;
|
|
806
|
+
if (n.clipsContent) {
|
|
807
|
+
inner = clip ? intersect(box, clip) : { x: box.x, y: box.y, width: box.width, height: box.height };
|
|
808
|
+
inner.id = n.id;
|
|
809
|
+
}
|
|
810
|
+
for (const c of n.children) walk(c, inner, cut, inInstance || n.type === "INSTANCE");
|
|
811
|
+
};
|
|
812
|
+
walk(root, null, false, root.type === "INSTANCE");
|
|
813
|
+
const total = Object.keys(summary).reduce((a, k) => a + summary[k], 0);
|
|
814
|
+
const out = { scope: root.name, checks: want.concat(minTouch ? ["touch"] : []), nodesChecked: checked, total, summary, issues };
|
|
815
|
+
if (total > issues.length) out.truncated = true;
|
|
816
|
+
if (layout && insideInstances) out.layoutNotChecked = insideInstances + " layers inside instances; audit their main component to check those";
|
|
817
|
+
if (disabledSkipped) out.contrastSkippedDisabled = disabledSkipped + " text layers in disabled controls (WCAG exempts them)";
|
|
818
|
+
if (contrastUnknown) out.contrastNotMeasured = contrastUnknown + " text layers sit on an image, gradient or translucent fill; check those by screenshot";
|
|
819
|
+
return out;
|
|
820
|
+
},
|
|
821
|
+
|
|
822
|
+
// Several commands in one round-trip. A failed op is reported in place and
|
|
823
|
+
// the rest still run: what already landed in the document stays there.
|
|
824
|
+
async batch(params) {
|
|
825
|
+
const ops = params.ops || [];
|
|
826
|
+
if (!ops.length) throw new Error("ops is required");
|
|
827
|
+
const results = [];
|
|
828
|
+
let failed = 0;
|
|
829
|
+
for (let i = 0; i < ops.length; i++) {
|
|
830
|
+
const op = ops[i] || {};
|
|
831
|
+
try {
|
|
832
|
+
if (NOT_BATCHABLE.indexOf(op.command) !== -1) throw new Error(op.command + " cannot run inside batch; call it as its own tool");
|
|
833
|
+
const h = handlers[op.command];
|
|
834
|
+
if (!h) throw new Error("unknown command: " + op.command + " (batch runs the same commands as the other tools, by tool name)");
|
|
835
|
+
const r = await h(resolveBatchRefs(op.params || {}, results));
|
|
836
|
+
results.push({ result: r === undefined ? null : r });
|
|
837
|
+
} catch (e) {
|
|
838
|
+
failed++;
|
|
839
|
+
results.push({ error: String((e && e.message) || e) });
|
|
840
|
+
if (params.stop_on_error) break;
|
|
841
|
+
}
|
|
842
|
+
}
|
|
843
|
+
const out = { ok: failed === 0, ran: results.length, failed, results };
|
|
844
|
+
if (results.length < ops.length) out.skipped = ops.length - results.length;
|
|
845
|
+
return out;
|
|
846
|
+
},
|
|
847
|
+
|
|
213
848
|
async create_rectangle(params) {
|
|
214
849
|
const r = figma.createRectangle();
|
|
215
850
|
applyShapeParams(r, params);
|
|
@@ -238,6 +873,7 @@ const handlers = {
|
|
|
238
873
|
},
|
|
239
874
|
|
|
240
875
|
async import_image(params) {
|
|
876
|
+
if (params.svg !== undefined) return importSvg(params);
|
|
241
877
|
const image = figma.createImage(figma.base64Decode(params.data));
|
|
242
878
|
const paint = { type: "IMAGE", imageHash: image.hash, scaleMode: params.scale_mode || "FILL" };
|
|
243
879
|
let n;
|
|
@@ -283,32 +919,39 @@ const handlers = {
|
|
|
283
919
|
},
|
|
284
920
|
|
|
285
921
|
async set_characters(params) {
|
|
286
|
-
const
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
922
|
+
const nodes = await targets(params);
|
|
923
|
+
for (const t of nodes) {
|
|
924
|
+
if (t.type !== "TEXT") throw new Error("node " + t.id + " is " + t.type + ", not TEXT");
|
|
925
|
+
if (t.characters.length > 0) {
|
|
926
|
+
const fonts = t.getRangeAllFontNames(0, t.characters.length);
|
|
927
|
+
await Promise.all(fonts.map(figma.loadFontAsync));
|
|
928
|
+
} else {
|
|
929
|
+
await figma.loadFontAsync(t.fontName);
|
|
930
|
+
}
|
|
931
|
+
t.characters = params.text;
|
|
293
932
|
}
|
|
294
|
-
|
|
295
|
-
return summarize(t);
|
|
933
|
+
return done(params, nodes);
|
|
296
934
|
},
|
|
297
935
|
|
|
298
936
|
async set_fills(params) {
|
|
299
|
-
const
|
|
300
|
-
|
|
301
|
-
let paint;
|
|
302
|
-
if (
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
937
|
+
const nodes = await targets(params);
|
|
938
|
+
const clear = params.color === "none" || params.color === null;
|
|
939
|
+
let paint = null;
|
|
940
|
+
if (!clear) {
|
|
941
|
+
if (params.gradient) {
|
|
942
|
+
paint = buildGradient(params.gradient);
|
|
943
|
+
} else if (params.color) {
|
|
944
|
+
paint = { type: "SOLID", color: hexToRGB(params.color) };
|
|
945
|
+
} else {
|
|
946
|
+
throw new Error('set_fills needs color, gradient, or color: "none" to clear');
|
|
947
|
+
}
|
|
948
|
+
if (params.opacity !== undefined && params.opacity !== null) paint.opacity = params.opacity;
|
|
308
949
|
}
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
950
|
+
for (const n of nodes) {
|
|
951
|
+
if (!("fills" in n)) throw new Error("node " + n.id + " has no fills");
|
|
952
|
+
n.fills = clear ? [] : [paint];
|
|
953
|
+
}
|
|
954
|
+
return done(params, nodes);
|
|
312
955
|
},
|
|
313
956
|
|
|
314
957
|
async move_nodes(params) {
|
|
@@ -318,9 +961,9 @@ const handlers = {
|
|
|
318
961
|
if (!("x" in n)) throw new Error("node " + item.node_id + " cannot be moved");
|
|
319
962
|
n.x = item.x;
|
|
320
963
|
n.y = item.y;
|
|
321
|
-
out.push(
|
|
964
|
+
out.push(n);
|
|
322
965
|
}
|
|
323
|
-
return out;
|
|
966
|
+
return done(params, out);
|
|
324
967
|
},
|
|
325
968
|
|
|
326
969
|
async resize_nodes(params) {
|
|
@@ -329,16 +972,16 @@ const handlers = {
|
|
|
329
972
|
const n = await node(item.node_id);
|
|
330
973
|
if (!("resize" in n)) throw new Error("node " + item.node_id + " cannot be resized");
|
|
331
974
|
n.resize(item.width, item.height);
|
|
332
|
-
out.push(
|
|
975
|
+
out.push(n);
|
|
333
976
|
}
|
|
334
|
-
return out;
|
|
977
|
+
return done(params, out);
|
|
335
978
|
},
|
|
336
979
|
|
|
337
980
|
async remove_nodes(params) {
|
|
338
981
|
const deleted = [];
|
|
339
982
|
for (const id of params.node_ids) {
|
|
340
983
|
const n = await node(id);
|
|
341
|
-
deleted.push(
|
|
984
|
+
deleted.push({ id: n.id, name: n.name, type: n.type });
|
|
342
985
|
n.remove();
|
|
343
986
|
}
|
|
344
987
|
return { deleted };
|
|
@@ -348,7 +991,7 @@ const handlers = {
|
|
|
348
991
|
const n = await node(params.node_id);
|
|
349
992
|
if (!("layoutMode" in n)) throw new Error("node " + params.node_id + " does not support auto-layout");
|
|
350
993
|
n.layoutMode = params.layout_mode;
|
|
351
|
-
if (params.layout_mode === "NONE") return
|
|
994
|
+
if (params.layout_mode === "NONE") return done(params, n);
|
|
352
995
|
if (params.item_spacing !== undefined) n.itemSpacing = params.item_spacing;
|
|
353
996
|
if (params.padding !== undefined) {
|
|
354
997
|
n.paddingTop = n.paddingRight = n.paddingBottom = n.paddingLeft = params.padding;
|
|
@@ -361,46 +1004,97 @@ const handlers = {
|
|
|
361
1004
|
if (params.counter_axis_align) n.counterAxisAlignItems = params.counter_axis_align;
|
|
362
1005
|
if (params.primary_axis_sizing) n.primaryAxisSizingMode = params.primary_axis_sizing;
|
|
363
1006
|
if (params.counter_axis_sizing) n.counterAxisSizingMode = params.counter_axis_sizing;
|
|
364
|
-
return
|
|
1007
|
+
return done(params, n);
|
|
365
1008
|
},
|
|
366
1009
|
|
|
367
1010
|
async set_corner_radius(params) {
|
|
368
|
-
const
|
|
369
|
-
|
|
370
|
-
if (
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
if (
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
1011
|
+
const nodes = await targets(params);
|
|
1012
|
+
for (const n of nodes) {
|
|
1013
|
+
if (params.radius !== undefined) {
|
|
1014
|
+
if (!("cornerRadius" in n)) throw new Error("node " + n.id + " has no corner radius");
|
|
1015
|
+
n.cornerRadius = params.radius;
|
|
1016
|
+
}
|
|
1017
|
+
if (!("topLeftRadius" in n)) {
|
|
1018
|
+
if (params.radius === undefined) throw new Error("node " + n.id + " has no per-corner radius");
|
|
1019
|
+
continue;
|
|
1020
|
+
}
|
|
1021
|
+
if (params.top_left !== undefined) n.topLeftRadius = params.top_left;
|
|
1022
|
+
if (params.top_right !== undefined) n.topRightRadius = params.top_right;
|
|
1023
|
+
if (params.bottom_right !== undefined) n.bottomRightRadius = params.bottom_right;
|
|
1024
|
+
if (params.bottom_left !== undefined) n.bottomLeftRadius = params.bottom_left;
|
|
1025
|
+
}
|
|
1026
|
+
return done(params, nodes);
|
|
382
1027
|
},
|
|
383
1028
|
|
|
384
1029
|
async set_strokes(params) {
|
|
385
|
-
const
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
1030
|
+
const nodes = await targets(params);
|
|
1031
|
+
for (const n of nodes) {
|
|
1032
|
+
if (!("strokes" in n)) throw new Error("node " + n.id + " has no strokes");
|
|
1033
|
+
if (params.color && params.color !== "none") {
|
|
1034
|
+
const paint = { type: "SOLID", color: hexToRGB(params.color) };
|
|
1035
|
+
if (params.opacity !== undefined && params.opacity !== null) paint.opacity = params.opacity;
|
|
1036
|
+
n.strokes = [paint];
|
|
1037
|
+
} else {
|
|
1038
|
+
n.strokes = [];
|
|
1039
|
+
}
|
|
1040
|
+
if (params.weight !== undefined && "strokeWeight" in n) n.strokeWeight = params.weight;
|
|
1041
|
+
if (params.align && "strokeAlign" in n) n.strokeAlign = params.align;
|
|
393
1042
|
}
|
|
394
|
-
|
|
395
|
-
if (params.align && "strokeAlign" in n) n.strokeAlign = params.align;
|
|
396
|
-
return summarize(n);
|
|
1043
|
+
return done(params, nodes);
|
|
397
1044
|
},
|
|
398
1045
|
|
|
399
1046
|
async set_effects(params) {
|
|
400
|
-
const
|
|
401
|
-
|
|
402
|
-
n
|
|
403
|
-
|
|
1047
|
+
const nodes = await targets(params);
|
|
1048
|
+
const effects = buildEffects(params.effects);
|
|
1049
|
+
for (const n of nodes) {
|
|
1050
|
+
if (!("effects" in n)) throw new Error("node " + n.id + " has no effects");
|
|
1051
|
+
n.effects = effects;
|
|
1052
|
+
}
|
|
1053
|
+
return done(params, nodes);
|
|
1054
|
+
},
|
|
1055
|
+
|
|
1056
|
+
async rename_nodes(params) {
|
|
1057
|
+
const renamed = [];
|
|
1058
|
+
for (const item of params.items) {
|
|
1059
|
+
const n = await node(item.node_id);
|
|
1060
|
+
n.name = item.name;
|
|
1061
|
+
renamed.push(n);
|
|
1062
|
+
}
|
|
1063
|
+
return done(params, renamed);
|
|
1064
|
+
},
|
|
1065
|
+
|
|
1066
|
+
// Restyle text in place. create_text sets the font once; variants (Bold vs
|
|
1067
|
+
// Regular of the same label) need this.
|
|
1068
|
+
async set_text_properties(params) {
|
|
1069
|
+
const nodes = await targets(params);
|
|
1070
|
+
for (const n of nodes) {
|
|
1071
|
+
if (n.type !== "TEXT") throw new Error("node " + n.id + " is " + n.type + ", not TEXT");
|
|
1072
|
+
// Every font already in the node must be loaded before any edit, and
|
|
1073
|
+
// the new one before it can be applied.
|
|
1074
|
+
const current = n.characters.length
|
|
1075
|
+
? n.getRangeAllFontNames(0, n.characters.length)
|
|
1076
|
+
: [n.fontName];
|
|
1077
|
+
await Promise.all(current.filter((f) => f !== figma.mixed).map(figma.loadFontAsync));
|
|
1078
|
+
if (params.font_family || params.font_style) {
|
|
1079
|
+
const base = current[0] === figma.mixed ? { family: "Inter", style: "Regular" } : current[0];
|
|
1080
|
+
const font = {
|
|
1081
|
+
family: params.font_family || base.family,
|
|
1082
|
+
style: params.font_style || base.style,
|
|
1083
|
+
};
|
|
1084
|
+
await figma.loadFontAsync(font);
|
|
1085
|
+
n.fontName = font;
|
|
1086
|
+
}
|
|
1087
|
+
if (params.font_size) n.fontSize = params.font_size;
|
|
1088
|
+
if (params.line_height !== undefined && params.line_height !== null) {
|
|
1089
|
+
n.lineHeight = { value: params.line_height, unit: "PIXELS" };
|
|
1090
|
+
}
|
|
1091
|
+
if (params.letter_spacing !== undefined && params.letter_spacing !== null) {
|
|
1092
|
+
n.letterSpacing = { value: params.letter_spacing, unit: "PIXELS" };
|
|
1093
|
+
}
|
|
1094
|
+
if (params.text_align) n.textAlignHorizontal = params.text_align;
|
|
1095
|
+
if (params.fill_color) n.fills = [{ type: "SOLID", color: hexToRGB(params.fill_color) }];
|
|
1096
|
+
}
|
|
1097
|
+
return done(params, nodes);
|
|
404
1098
|
},
|
|
405
1099
|
|
|
406
1100
|
async download_assets(params) {
|
|
@@ -419,6 +1113,7 @@ const handlers = {
|
|
|
419
1113
|
let scale = item.scale || 1;
|
|
420
1114
|
scale = Math.max(0.5, Math.min(scale, 4));
|
|
421
1115
|
settings = { format, constraint: { type: "SCALE", value: scale } };
|
|
1116
|
+
if (item.exact) settings.useAbsoluteBounds = true;
|
|
422
1117
|
} else {
|
|
423
1118
|
throw new Error("unsupported format: " + format + " (use PNG, JPG or SVG)");
|
|
424
1119
|
}
|
|
@@ -445,22 +1140,57 @@ const handlers = {
|
|
|
445
1140
|
},
|
|
446
1141
|
|
|
447
1142
|
async find_nodes(params) {
|
|
448
|
-
|
|
1143
|
+
let scope;
|
|
1144
|
+
if (params.node_id) scope = await node(params.node_id);
|
|
1145
|
+
else if (params.page) scope = await resolvePage(params.page);
|
|
1146
|
+
else scope = figma.currentPage;
|
|
449
1147
|
if (!("findAll" in scope)) throw new Error("node " + scope.id + " has no children to search");
|
|
450
1148
|
const name = params.name ? params.name.toLowerCase() : null;
|
|
451
1149
|
const text = params.text ? params.text.toLowerCase() : null;
|
|
452
1150
|
const types = params.types && params.types.length ? params.types : null;
|
|
1151
|
+
// Style filters let callers target "every white card" directly instead of
|
|
1152
|
+
// guessing a node's role from its size.
|
|
1153
|
+
const fill = params.fill ? ("#" + params.fill.replace(/^#/, "")).toLowerCase() : null;
|
|
1154
|
+
const fontSize = params.font_size;
|
|
1155
|
+
const fontStyle = params.font_style ? params.font_style.toLowerCase() : null;
|
|
453
1156
|
const matches = scope.findAll((n) => {
|
|
454
1157
|
if (types && types.indexOf(n.type) === -1) return false;
|
|
455
1158
|
if (name && n.name.toLowerCase().indexOf(name) === -1) return false;
|
|
456
1159
|
if (text && (n.type !== "TEXT" || n.characters.toLowerCase().indexOf(text) === -1)) return false;
|
|
1160
|
+
if (fill) {
|
|
1161
|
+
const hex = solidFillHex(n);
|
|
1162
|
+
if (!hex || hex.toLowerCase() !== fill) return false;
|
|
1163
|
+
}
|
|
1164
|
+
if (fontSize !== undefined && fontSize !== null) {
|
|
1165
|
+
if (n.type !== "TEXT" || val(n.fontSize) !== fontSize) return false;
|
|
1166
|
+
}
|
|
1167
|
+
if (fontStyle) {
|
|
1168
|
+
if (n.type !== "TEXT") return false;
|
|
1169
|
+
const f = val(n.fontName);
|
|
1170
|
+
if (f === "mixed" || f.style.toLowerCase() !== fontStyle) return false;
|
|
1171
|
+
}
|
|
457
1172
|
return true;
|
|
458
1173
|
});
|
|
459
1174
|
const max = params.max_results || 50;
|
|
1175
|
+
const fields = params.fields && params.fields.length ? params.fields : null;
|
|
1176
|
+
// Name the scope: with no node_id or page this searches whatever page the
|
|
1177
|
+
// user happens to have open, which silently changes under a long session.
|
|
1178
|
+
const page = (function (n) {
|
|
1179
|
+
while (n && n.type !== "PAGE") n = n.parent;
|
|
1180
|
+
return n ? n.name : undefined;
|
|
1181
|
+
})(scope);
|
|
460
1182
|
return {
|
|
1183
|
+
scope: scope.type === "PAGE" ? "page " + scope.name : scope.name + " (page " + page + ")",
|
|
461
1184
|
total: matches.length,
|
|
462
1185
|
truncated: matches.length > max,
|
|
463
|
-
nodes: matches.slice(0, max).map(
|
|
1186
|
+
nodes: matches.slice(0, max).map((n) => {
|
|
1187
|
+
const s = summarize(n);
|
|
1188
|
+
for (const f of fields || []) {
|
|
1189
|
+
const v = FIELD_GETTERS[f] ? FIELD_GETTERS[f](n) : undefined;
|
|
1190
|
+
if (v !== undefined) s[f] = v;
|
|
1191
|
+
}
|
|
1192
|
+
return s;
|
|
1193
|
+
}),
|
|
464
1194
|
};
|
|
465
1195
|
},
|
|
466
1196
|
|
|
@@ -486,18 +1216,27 @@ const handlers = {
|
|
|
486
1216
|
async append_children(params) {
|
|
487
1217
|
const parent = await node(params.parent_id);
|
|
488
1218
|
if (!("appendChild" in parent)) throw new Error("node " + params.parent_id + " cannot have children");
|
|
489
|
-
const
|
|
1219
|
+
const moved = [];
|
|
1220
|
+
const warnings = [];
|
|
490
1221
|
let index = params.index;
|
|
491
1222
|
for (const id of params.node_ids) {
|
|
492
1223
|
const n = await node(id);
|
|
1224
|
+
// Figma silently pulls a variant out of its set and renames it
|
|
1225
|
+
// "<Set>/<Variant>" — easy to miss until the variants stop working.
|
|
1226
|
+
if (n.type === "COMPONENT" && n.parent && n.parent.type === "COMPONENT_SET") {
|
|
1227
|
+
warnings.push(
|
|
1228
|
+
"node " + n.id + " (" + n.name + ") left component set " + n.parent.name +
|
|
1229
|
+
"; Figma renames detached variants to <Set>/<Variant>",
|
|
1230
|
+
);
|
|
1231
|
+
}
|
|
493
1232
|
if (index === undefined || index === null) {
|
|
494
1233
|
parent.appendChild(n);
|
|
495
1234
|
} else {
|
|
496
1235
|
parent.insertChild(index++, n);
|
|
497
1236
|
}
|
|
498
|
-
|
|
1237
|
+
moved.push(n);
|
|
499
1238
|
}
|
|
500
|
-
return
|
|
1239
|
+
return done(params, moved, warnings.length ? { warnings } : null);
|
|
501
1240
|
},
|
|
502
1241
|
|
|
503
1242
|
async clone_node(params) {
|
|
@@ -567,6 +1306,57 @@ const handlers = {
|
|
|
567
1306
|
return summarize(inst);
|
|
568
1307
|
},
|
|
569
1308
|
|
|
1309
|
+
async combine_as_variants(params) {
|
|
1310
|
+
if (!params.node_ids || !params.node_ids.length) throw new Error("node_ids is required");
|
|
1311
|
+
const nodes = await Promise.all(params.node_ids.map((id) => node(id)));
|
|
1312
|
+
for (const n of nodes) {
|
|
1313
|
+
if (n.type !== "COMPONENT") throw new Error("node " + n.id + " is " + n.type + ", not a COMPONENT");
|
|
1314
|
+
}
|
|
1315
|
+
const parent = params.parent_id ? await node(params.parent_id) : nodes[0].parent;
|
|
1316
|
+
const set = figma.combineAsVariants(nodes, parent);
|
|
1317
|
+
if (params.name) set.name = params.name;
|
|
1318
|
+
arrangeVariants(set);
|
|
1319
|
+
return summarize(set);
|
|
1320
|
+
},
|
|
1321
|
+
|
|
1322
|
+
// Component properties live on the component (or set); binding the property
|
|
1323
|
+
// to a child layer is what makes it editable from the instance panel, so do
|
|
1324
|
+
// both in one call.
|
|
1325
|
+
async add_component_property(params) {
|
|
1326
|
+
const c = await node(params.component_id);
|
|
1327
|
+
if (c.type !== "COMPONENT" && c.type !== "COMPONENT_SET") {
|
|
1328
|
+
throw new Error("node " + c.id + " is " + c.type + ", not a COMPONENT or COMPONENT_SET");
|
|
1329
|
+
}
|
|
1330
|
+
const type = (params.type || "TEXT").toUpperCase();
|
|
1331
|
+
// Figma requires a default of the matching kind; pick the empty one
|
|
1332
|
+
// rather than failing a call that only omitted it.
|
|
1333
|
+
let def = params.default_value;
|
|
1334
|
+
if (def === undefined || def === null) def = type === "BOOLEAN" ? false : "";
|
|
1335
|
+
const t = params.bind_node_id ? await node(params.bind_node_id) : null;
|
|
1336
|
+
const key = c.addComponentProperty(params.name, type, def);
|
|
1337
|
+
if (t) {
|
|
1338
|
+
const field = type === "TEXT" ? "characters" : type === "BOOLEAN" ? "visible" : "mainComponent";
|
|
1339
|
+
const refs = {};
|
|
1340
|
+
for (const k in t.componentPropertyReferences || {}) refs[k] = t.componentPropertyReferences[k];
|
|
1341
|
+
refs[field] = key;
|
|
1342
|
+
t.componentPropertyReferences = refs;
|
|
1343
|
+
}
|
|
1344
|
+
return { key, name: params.name, type, boundTo: params.bind_node_id || null };
|
|
1345
|
+
},
|
|
1346
|
+
|
|
1347
|
+
async set_instance_properties(params) {
|
|
1348
|
+
const inst = await node(params.instance_id);
|
|
1349
|
+
if (inst.type !== "INSTANCE") throw new Error("node " + params.instance_id + " is " + inst.type + ", not an INSTANCE");
|
|
1350
|
+
const known = Object.keys(inst.componentProperties || {});
|
|
1351
|
+
for (const k in params.properties) {
|
|
1352
|
+
if (known.indexOf(k) === -1) {
|
|
1353
|
+
throw new Error("unknown property " + k + "; this instance accepts: " + (known.join(", ") || "(none)"));
|
|
1354
|
+
}
|
|
1355
|
+
}
|
|
1356
|
+
inst.setProperties(params.properties);
|
|
1357
|
+
return { id: inst.id, properties: inst.componentProperties };
|
|
1358
|
+
},
|
|
1359
|
+
|
|
570
1360
|
async swap_component(params) {
|
|
571
1361
|
const inst = await node(params.instance_id);
|
|
572
1362
|
if (inst.type !== "INSTANCE") throw new Error("node " + params.instance_id + " is " + inst.type + ", not an INSTANCE");
|
|
@@ -627,27 +1417,29 @@ const handlers = {
|
|
|
627
1417
|
},
|
|
628
1418
|
|
|
629
1419
|
async apply_style(params) {
|
|
630
|
-
const
|
|
1420
|
+
const nodes = await targets(params);
|
|
631
1421
|
const style = await figma.getStyleByIdAsync(params.style_id);
|
|
632
1422
|
if (!style) throw new Error("style not found: " + params.style_id);
|
|
633
|
-
if (style.type === "
|
|
634
|
-
|
|
635
|
-
|
|
1423
|
+
if (style.type === "TEXT") await figma.loadFontAsync(style.fontName);
|
|
1424
|
+
for (const n of nodes) {
|
|
1425
|
+
if (style.type === "PAINT") {
|
|
1426
|
+
if (params.target === "stroke") {
|
|
1427
|
+
await n.setStrokeStyleIdAsync(style.id);
|
|
1428
|
+
} else {
|
|
1429
|
+
await n.setFillStyleIdAsync(style.id);
|
|
1430
|
+
}
|
|
1431
|
+
} else if (style.type === "TEXT") {
|
|
1432
|
+
if (n.type !== "TEXT") throw new Error("node " + n.id + " is " + n.type + ", not TEXT");
|
|
1433
|
+
await n.setTextStyleIdAsync(style.id);
|
|
1434
|
+
} else if (style.type === "EFFECT") {
|
|
1435
|
+
await n.setEffectStyleIdAsync(style.id);
|
|
1436
|
+
} else if (style.type === "GRID") {
|
|
1437
|
+
await n.setGridStyleIdAsync(style.id);
|
|
636
1438
|
} else {
|
|
637
|
-
|
|
638
|
-
}
|
|
639
|
-
} else if (style.type === "TEXT") {
|
|
640
|
-
if (n.type !== "TEXT") throw new Error("node " + params.node_id + " is " + n.type + ", not TEXT");
|
|
641
|
-
await figma.loadFontAsync(style.fontName);
|
|
642
|
-
await n.setTextStyleIdAsync(style.id);
|
|
643
|
-
} else if (style.type === "EFFECT") {
|
|
644
|
-
await n.setEffectStyleIdAsync(style.id);
|
|
645
|
-
} else if (style.type === "GRID") {
|
|
646
|
-
await n.setGridStyleIdAsync(style.id);
|
|
647
|
-
} else {
|
|
648
|
-
throw new Error("unsupported style type: " + style.type);
|
|
1439
|
+
throw new Error("unsupported style type: " + style.type);
|
|
1440
|
+
}
|
|
649
1441
|
}
|
|
650
|
-
return
|
|
1442
|
+
return done(params, nodes);
|
|
651
1443
|
},
|
|
652
1444
|
|
|
653
1445
|
// ---------- variables (design tokens) ----------
|
|
@@ -674,6 +1466,28 @@ const handlers = {
|
|
|
674
1466
|
};
|
|
675
1467
|
},
|
|
676
1468
|
|
|
1469
|
+
// Removing a variable detaches it from every node bound to it; those nodes
|
|
1470
|
+
// keep the value they showed.
|
|
1471
|
+
async remove_variables(params) {
|
|
1472
|
+
const removed = [];
|
|
1473
|
+
for (const id of params.variable_ids || []) {
|
|
1474
|
+
const v = await figma.variables.getVariableByIdAsync(id);
|
|
1475
|
+
if (!v) throw new Error("variable not found: " + id + " (see get_variable_defs)");
|
|
1476
|
+
removed.push({ id: v.id, name: v.name });
|
|
1477
|
+
v.remove();
|
|
1478
|
+
}
|
|
1479
|
+
if (!removed.length) throw new Error("variable_ids is required");
|
|
1480
|
+
return { removed };
|
|
1481
|
+
},
|
|
1482
|
+
|
|
1483
|
+
async remove_variable_collection(params) {
|
|
1484
|
+
const c = await figma.variables.getVariableCollectionByIdAsync(params.collection_id);
|
|
1485
|
+
if (!c) throw new Error("variable collection not found: " + params.collection_id + " (see get_variable_defs)");
|
|
1486
|
+
const out = { removed: { id: c.id, name: c.name, variables: c.variableIds.length } };
|
|
1487
|
+
c.remove();
|
|
1488
|
+
return out;
|
|
1489
|
+
},
|
|
1490
|
+
|
|
677
1491
|
async create_variable_collection(params) {
|
|
678
1492
|
const c = figma.variables.createVariableCollection(params.name);
|
|
679
1493
|
if (params.mode_name) c.renameMode(c.defaultModeId, params.mode_name);
|
|
@@ -712,18 +1526,107 @@ const handlers = {
|
|
|
712
1526
|
},
|
|
713
1527
|
|
|
714
1528
|
async set_bound_variable(params) {
|
|
715
|
-
const
|
|
1529
|
+
const nodes = await targets(params);
|
|
716
1530
|
const v = await figma.variables.getVariableByIdAsync(params.variable_id);
|
|
717
1531
|
if (!v) throw new Error("variable not found: " + params.variable_id);
|
|
718
1532
|
const field = params.field;
|
|
719
|
-
|
|
720
|
-
if (
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
1533
|
+
for (const n of nodes) {
|
|
1534
|
+
if (field === "fills" || field === "strokes") {
|
|
1535
|
+
if (!(field in n)) throw new Error("node " + n.id + " has no " + field);
|
|
1536
|
+
const paints = n[field].length ? n[field] : [{ type: "SOLID", color: { r: 0, g: 0, b: 0 } }];
|
|
1537
|
+
n[field] = [figma.variables.setBoundVariableForPaint(paints[0], "color", v)].concat(paints.slice(1));
|
|
1538
|
+
} else {
|
|
1539
|
+
n.setBoundVariable(field, v);
|
|
1540
|
+
}
|
|
725
1541
|
}
|
|
726
|
-
return
|
|
1542
|
+
return done(params, nodes);
|
|
1543
|
+
},
|
|
1544
|
+
|
|
1545
|
+
// ---------- prototyping ----------
|
|
1546
|
+
|
|
1547
|
+
// setReactionsAsync replaces a node's reactions wholesale, so items for the
|
|
1548
|
+
// same node are grouped and written once instead of overwriting each other.
|
|
1549
|
+
async set_prototype_links(params) {
|
|
1550
|
+
const items = params.items || [];
|
|
1551
|
+
if (!items.length) throw new Error("items is required");
|
|
1552
|
+
const order = [];
|
|
1553
|
+
const groups = {};
|
|
1554
|
+
for (const item of items) {
|
|
1555
|
+
if (!item.node_id) throw new Error("node_id is required for every item");
|
|
1556
|
+
if (!groups[item.node_id]) {
|
|
1557
|
+
groups[item.node_id] = [];
|
|
1558
|
+
order.push(item.node_id);
|
|
1559
|
+
}
|
|
1560
|
+
groups[item.node_id].push(await buildReaction(item));
|
|
1561
|
+
}
|
|
1562
|
+
const out = [];
|
|
1563
|
+
for (const id of order) {
|
|
1564
|
+
const n = await node(id);
|
|
1565
|
+
if (!("setReactionsAsync" in n)) {
|
|
1566
|
+
throw new Error("node " + id + " is " + n.type + " and cannot carry prototype reactions");
|
|
1567
|
+
}
|
|
1568
|
+
await n.setReactionsAsync(groups[id]);
|
|
1569
|
+
out.push(n);
|
|
1570
|
+
}
|
|
1571
|
+
return done(params, out);
|
|
1572
|
+
},
|
|
1573
|
+
|
|
1574
|
+
async get_prototype_links(params) {
|
|
1575
|
+
const scope = params.node_id ? await node(params.node_id) : figma.currentPage;
|
|
1576
|
+
const withReactions = [];
|
|
1577
|
+
const has = (n) => "reactions" in n && n.reactions && n.reactions.length;
|
|
1578
|
+
if (has(scope)) withReactions.push(scope);
|
|
1579
|
+
if ("findAll" in scope) withReactions.push(...scope.findAll(has));
|
|
1580
|
+
const names = {};
|
|
1581
|
+
const nameOf = async (id) => {
|
|
1582
|
+
if (!(id in names)) {
|
|
1583
|
+
const d = await figma.getNodeByIdAsync(id);
|
|
1584
|
+
names[id] = d ? d.name : null;
|
|
1585
|
+
}
|
|
1586
|
+
return names[id];
|
|
1587
|
+
};
|
|
1588
|
+
const links = [];
|
|
1589
|
+
for (const n of withReactions) {
|
|
1590
|
+
for (const r of n.reactions) {
|
|
1591
|
+
for (const a of r.actions || []) {
|
|
1592
|
+
const link = { id: n.id, name: n.name, trigger: r.trigger ? r.trigger.type : null, action: a.type };
|
|
1593
|
+
if (a.navigation) link.navigation = a.navigation;
|
|
1594
|
+
if (a.url) link.url = a.url;
|
|
1595
|
+
if (a.destinationId) {
|
|
1596
|
+
link.destinationId = a.destinationId;
|
|
1597
|
+
const dn = await nameOf(a.destinationId);
|
|
1598
|
+
if (dn) link.destinationName = dn;
|
|
1599
|
+
}
|
|
1600
|
+
if (a.transition) link.transition = a.transition.type;
|
|
1601
|
+
links.push(link);
|
|
1602
|
+
}
|
|
1603
|
+
}
|
|
1604
|
+
}
|
|
1605
|
+
return {
|
|
1606
|
+
scope: scope.type === "PAGE" ? "page " + scope.name : scope.name,
|
|
1607
|
+
total: links.length,
|
|
1608
|
+
links,
|
|
1609
|
+
};
|
|
1610
|
+
},
|
|
1611
|
+
|
|
1612
|
+
// flowStartingPoints is a page-level array, so read-modify-write it.
|
|
1613
|
+
async set_flow_starting_point(params) {
|
|
1614
|
+
const n = await node(params.node_id);
|
|
1615
|
+
const page = pageOf(n);
|
|
1616
|
+
const kept = page.flowStartingPoints.filter((p) => p.nodeId !== n.id);
|
|
1617
|
+
const changed = params.remove
|
|
1618
|
+
? kept.length !== page.flowStartingPoints.length
|
|
1619
|
+
: true;
|
|
1620
|
+
page.flowStartingPoints = params.remove
|
|
1621
|
+
? kept
|
|
1622
|
+
: kept.concat([{ nodeId: n.id, name: params.name || n.name }]);
|
|
1623
|
+
return {
|
|
1624
|
+
ok: true,
|
|
1625
|
+
id: n.id,
|
|
1626
|
+
page: page.name,
|
|
1627
|
+
changed,
|
|
1628
|
+
flowStartingPoints: page.flowStartingPoints.map((p) => ({ nodeId: p.nodeId, name: p.name })),
|
|
1629
|
+
};
|
|
727
1630
|
},
|
|
728
1631
|
|
|
729
1632
|
async get_screenshot(params) {
|
|
@@ -736,17 +1639,27 @@ const handlers = {
|
|
|
736
1639
|
target = figma.currentPage;
|
|
737
1640
|
}
|
|
738
1641
|
if (!("exportAsync" in target)) throw new Error("node " + target.id + " cannot be exported");
|
|
739
|
-
|
|
740
|
-
|
|
1642
|
+
// With dynamic-page access a node can be reachable before its page is
|
|
1643
|
+
// loaded, and exporting then yields a blank image with no error.
|
|
1644
|
+
let owner = target;
|
|
1645
|
+
while (owner && owner.type !== "PAGE") owner = owner.parent;
|
|
1646
|
+
if (owner && typeof owner.loadAsync === "function") await owner.loadAsync();
|
|
1647
|
+
const requested = Math.max(0.5, Math.min(params.scale || 1, 4));
|
|
1648
|
+
let scale = requested;
|
|
741
1649
|
// Cap the output size: huge pages at high scale produce multi-MB base64
|
|
742
1650
|
// payloads that are slow to ship and waste the AI's context.
|
|
1651
|
+
const cap = params.max_dimension > 0 ? Math.min(params.max_dimension, 4096) : 2000;
|
|
743
1652
|
const maxDim = Math.max("width" in target ? target.width : 0, "height" in target ? target.height : 0);
|
|
744
|
-
|
|
1653
|
+
const clamped = maxDim * scale > cap;
|
|
1654
|
+
if (clamped) scale = cap / maxDim;
|
|
745
1655
|
const bytes = await target.exportAsync({ format: "PNG", constraint: { type: "SCALE", value: scale } });
|
|
746
1656
|
return {
|
|
747
1657
|
data: figma.base64Encode(bytes),
|
|
748
1658
|
width: ("width" in target ? target.width : 0) * scale,
|
|
749
1659
|
height: ("height" in target ? target.height : 0) * scale,
|
|
1660
|
+
scale,
|
|
1661
|
+
clamped,
|
|
1662
|
+
sourceHeight: "height" in target ? target.height : 0,
|
|
750
1663
|
};
|
|
751
1664
|
},
|
|
752
1665
|
};
|
|
@@ -764,7 +1677,7 @@ async function postSelection() {
|
|
|
764
1677
|
const sel = figma.currentPage.selection;
|
|
765
1678
|
const items = [];
|
|
766
1679
|
for (const n of sel) {
|
|
767
|
-
const item = { name: n.name, type: n.type, link: nodeLink(n.id) };
|
|
1680
|
+
const item = { id: n.id, name: n.name, type: n.type, link: nodeLink(n.id) };
|
|
768
1681
|
// Frames are copied as links; every other element (vectors, instances, …)
|
|
769
1682
|
// is copied as SVG, so pre-export it now to keep the UI copy synchronous
|
|
770
1683
|
// (clipboard writes must happen inside the click gesture). Skip huge
|
|
@@ -779,37 +1692,68 @@ async function postSelection() {
|
|
|
779
1692
|
}
|
|
780
1693
|
items.push(item);
|
|
781
1694
|
}
|
|
782
|
-
|
|
783
|
-
figma.ui.postMessage({ selection: items, hasKey: !!fileKey });
|
|
784
|
-
// Room for: base card + filter bar (30) + optional Copy-all header (22) +
|
|
785
|
-
// the paste-URL prompt when a frame needs a key (64) + up to 6 visible rows
|
|
786
|
-
// (the list scrolls beyond that).
|
|
787
|
-
const rows = Math.min(items.length, 6);
|
|
788
|
-
const h = items.length
|
|
789
|
-
? 162 + (items.length > 1 ? 22 : 0) + (needsKey ? 64 : 0) + rows * 30
|
|
790
|
-
: 132;
|
|
791
|
-
figma.ui.resize(300, h);
|
|
1695
|
+
figma.ui.postMessage({ selection: items });
|
|
792
1696
|
}
|
|
793
1697
|
figma.on("selectionchange", postSelection);
|
|
794
1698
|
postSelection();
|
|
795
1699
|
|
|
1700
|
+
// ---------- activity log clicks ----------
|
|
1701
|
+
|
|
1702
|
+
async function uiAction(msg) {
|
|
1703
|
+
if (msg.uiAction !== "select") throw new Error("unknown action: " + msg.uiAction);
|
|
1704
|
+
const n = await node(msg.nodeId);
|
|
1705
|
+
figma.currentPage.selection = [n];
|
|
1706
|
+
figma.viewport.scrollAndZoomIntoView([n]);
|
|
1707
|
+
return null;
|
|
1708
|
+
}
|
|
1709
|
+
|
|
1710
|
+
// ---------- read-only switch ----------
|
|
1711
|
+
// Commands that leave the document as it is (selection and the open page are
|
|
1712
|
+
// view state). With the switch on, everything else is refused, so a tester can
|
|
1713
|
+
// let AI read a file it must not change. On at every start and never
|
|
1714
|
+
// remembered, so AI edits only while the user has this window unlocked.
|
|
1715
|
+
const READ_COMMANDS = /^(get_|list_|find_|audit_|download_assets$|set_selection$|set_current_page$)/;
|
|
1716
|
+
let readOnly = true;
|
|
1717
|
+
register();
|
|
1718
|
+
// Checkpoint buttons are for people who can edit this file. Dev Mode and
|
|
1719
|
+
// view-only windows (should the plugin ever run there) do not get them.
|
|
1720
|
+
figma.ui.postMessage({ canEdit: figma.editorType === "figma" && figma.mode !== "inspect" });
|
|
1721
|
+
|
|
796
1722
|
// ---------- dispatch ----------
|
|
797
1723
|
|
|
798
1724
|
figma.ui.onmessage = async (msg) => {
|
|
799
1725
|
if (!msg) return;
|
|
800
|
-
//
|
|
801
|
-
if (
|
|
802
|
-
|
|
803
|
-
|
|
1726
|
+
// The window measures its content after every render.
|
|
1727
|
+
if (msg.resize) {
|
|
1728
|
+
figma.ui.resize(280, Math.max(104, Math.min(600, Math.round(msg.resize))));
|
|
1729
|
+
return;
|
|
1730
|
+
}
|
|
1731
|
+
if (msg.uiAction) {
|
|
1732
|
+
// A log row whose layer was deleted since: nothing to select.
|
|
1733
|
+
await uiAction(msg).catch(() => {});
|
|
1734
|
+
return;
|
|
1735
|
+
}
|
|
1736
|
+
if (msg.setReadOnly !== undefined) {
|
|
1737
|
+
readOnly = !!msg.setReadOnly;
|
|
1738
|
+
register();
|
|
804
1739
|
return;
|
|
805
1740
|
}
|
|
806
1741
|
if (!msg.id || !msg.command) return;
|
|
807
1742
|
const h = handlers[msg.command];
|
|
1743
|
+
const p = msg.params || {};
|
|
1744
|
+
const act = { command: msg.command, write: !READ_COMMANDS.test(msg.command), node: p.node_id || (p.node_ids && p.node_ids[0]) || null };
|
|
808
1745
|
try {
|
|
809
1746
|
if (!h) throw new Error("unknown command: " + msg.command);
|
|
810
|
-
|
|
1747
|
+
if (readOnly && act.write) {
|
|
1748
|
+
figma.notify("AI tried to edit this file (" + msg.command + ") and was blocked. Untick Read-only in Figma MCP Console to allow edits.", { timeout: 8000 });
|
|
1749
|
+
throw new Error(msg.command + " was blocked: read-only mode is on in this file's Figma MCP Console window. " +
|
|
1750
|
+
"Tell the user; they can turn it off there if the edit is intended.");
|
|
1751
|
+
}
|
|
1752
|
+
const result = await h(p);
|
|
811
1753
|
figma.ui.postMessage({ id: msg.id, result: result === undefined ? null : result });
|
|
812
1754
|
} catch (e) {
|
|
813
|
-
|
|
1755
|
+
act.error = String((e && e.message) || e);
|
|
1756
|
+
figma.ui.postMessage({ id: msg.id, error: act.error });
|
|
814
1757
|
}
|
|
1758
|
+
figma.ui.postMessage({ activity: act });
|
|
815
1759
|
};
|