feat(mcp): bind a color variable to a fill/stroke paint

New bind_variable_to_paint tool closes the write-side gap that bind_variable_to_node
can't cover: Figma keeps fill/stroke colour bindings on the paint, not the node, so
node.setBoundVariable('fills', …) throws ("must be set on paints directly"). The new
tool uses figma.variables.setBoundVariableForPaint and writes the returned paint back
into a cloned array; supports fills/strokes, a paint index, and unbinding (variableId
null). bind_variable_to_node now redirects fills/strokes to it instead of surfacing
Figma's opaque error. This is the write half of token-driven colouring — the design-
system build path needs it to colour nodes by token instead of hard-coding hex.

Live-verified: bound a frame's fill to a White COLOR variable; get_node reads the
binding back via node.boundVariables.fills (so the existing reader already round-trips
it — no reader change needed).

Author: awdr74100

packages/mcp/src/tools/bind-variable-to-paint.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+import type { ToolSpec } from './spec.js';
+
+export const BIND_VARIABLE_TO_PAINT_TOOL_NAME = 'bind_variable_to_paint';
+
+export const bindVariableToPaintTool: ToolSpec = {
+  name: BIND_VARIABLE_TO_PAINT_TOOL_NAME,
+  description:
+    'Bind a COLOR variable to a SOLID fill or stroke paint (the design-token way to colour a node) ' +
+    '— or unbind by passing variableId: null. Figma stores fill/stroke colour bindings on the paint, ' +
+    'not the node, so this is separate from bind_variable_to_node (which covers scalar fields like ' +
+    'width / padding / radius). target is fills (default) or strokes; index selects which paint ' +
+    '(default 0). The paint at that index must be SOLID. Returns { ok, nodeId }.',
+  inputShape: {
+    nodeId: z.string().describe('Node whose fill/stroke paint to bind'),
+    target: z
+      .enum(['fills', 'strokes'])
+      .optional()
+      .describe('Which paint list to bind on (default fills)'),
+    index: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe('Index of the paint within the list (default 0)'),
+    variableId: z
+      .string()
+      .nullable()
+      .describe('COLOR variable id to bind, or null to remove the binding'),
+  },
+  kind: 'write',
+};

packages/mcp/src/tools/registry.ts

@@ -10,6 +10,7 @@ import { applyStyleToNodeTool } from './apply-style-to-node.js';
 import { batchRenameNodesTool } from './batch-rename-nodes.js';
 import { batchTool } from './batch.js';
 import { bindVariableToNodeTool } from './bind-variable-to-node.js';
+import { bindVariableToPaintTool } from './bind-variable-to-paint.js';
 import { cloneNodeTool } from './clone-node.js';
 import { combineAsVariantsTool } from './combine-as-variants.js';
 import { componentMapTool } from './component-map.js';
@@ -158,6 +159,7 @@ export const ALL_TOOL_SPECS: readonly ToolSpec[] = [
   createVariableTool,
   setVariableValueTool,
   bindVariableToNodeTool,
+  bindVariableToPaintTool,
   renameVariableTool,
   deleteVariableTool,
   groupNodesTool,

packages/plugin/src/handlers/bind-variable-to-node.ts

@@ -13,6 +13,13 @@ export const createBindVariableToNodeHandler =
     if (p.variableId !== null && typeof p.variableId !== 'string') {
       throw new TypeError('bind_variable_to_node: variableId must be a string or null');
     }
+    // Fill/stroke colour bindings live on the paint, not the node — setBoundVariable rejects them.
+    // Point the caller at the right tool instead of surfacing Figma's opaque error.
+    if (p.field === 'fills' || p.field === 'strokes') {
+      throw new Error(
+        `bind_variable_to_node: "${p.field}" is a paint-level colour binding — use bind_variable_to_paint instead`,
+      );
+    }
 
     const node = await figmaCtx.getNodeByIdAsync(p.nodeId);
     if (node === null) throw new Error(`bind_variable_to_node: node ${p.nodeId} not found`);

packages/plugin/src/handlers/bind-variable-to-paint.ts

@@ -0,0 +1,60 @@
+import type { MutateResult } from '@figwright/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+/**
+ * Bind (or unbind) a COLOR variable on a node's fill/stroke paint. Figma keeps fill/stroke colour
+ * bindings on the paint — not in node.boundVariables — so `node.setBoundVariable('fills', …)`
+ * throws; the only path is `figma.variables.setBoundVariableForPaint`, which returns a NEW paint
+ * that must be written back into a cloned array (paints are read-only).
+ */
+export const createBindVariableToPaintHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as {
+      nodeId?: unknown;
+      target?: unknown;
+      index?: unknown;
+      variableId?: unknown;
+    };
+    if (typeof p.nodeId !== 'string')
+      throw new TypeError('bind_variable_to_paint: nodeId must be a string');
+    const target: 'fills' | 'strokes' = p.target === 'strokes' ? 'strokes' : 'fills';
+    const index = typeof p.index === 'number' ? p.index : 0;
+    if (p.variableId !== null && typeof p.variableId !== 'string') {
+      throw new TypeError('bind_variable_to_paint: variableId must be a string or null');
+    }
+
+    const node = await figmaCtx.getNodeByIdAsync(p.nodeId);
+    if (node === null || !(target in node)) {
+      throw new Error(`bind_variable_to_paint: node ${p.nodeId} not found or has no ${target}`);
+    }
+    const paints = (node as unknown as Record<string, unknown>)[target];
+    if (!Array.isArray(paints)) {
+      throw new Error(`bind_variable_to_paint: ${target} on ${p.nodeId} is mixed or unreadable`);
+    }
+    const paint = paints[index] as Paint | undefined;
+    if (paint === undefined) {
+      throw new Error(`bind_variable_to_paint: no paint at ${target}[${index}] on ${p.nodeId}`);
+    }
+    if (paint.type !== 'SOLID') {
+      throw new Error(
+        `bind_variable_to_paint: ${target}[${index}] is ${paint.type}; only SOLID paints bind a colour variable`,
+      );
+    }
+
+    let variable: Variable | null = null;
+    if (typeof p.variableId === 'string') {
+      variable = await figmaCtx.variables.getVariableByIdAsync(p.variableId);
+      if (variable === null)
+        throw new Error(`bind_variable_to_paint: variable ${p.variableId} not found`);
+    }
+
+    const bound = figmaCtx.variables.setBoundVariableForPaint(paint, 'color', variable);
+    const next = [...(paints as Paint[])];
+    next[index] = bound;
+    (node as unknown as Record<string, unknown>)[target] = next;
+
+    const result: MutateResult = { ok: true, nodeId: node.id };
+    return result;
+  };

packages/plugin/src/handlers/registry.ts

@@ -6,6 +6,7 @@ import { createApplyStyleToNodeHandler } from './apply-style-to-node.js';
 import { createBatchRenameNodesHandler } from './batch-rename-nodes.js';
 import { createBatchHandler } from './batch.js';
 import { createBindVariableToNodeHandler } from './bind-variable-to-node.js';
+import { createBindVariableToPaintHandler } from './bind-variable-to-paint.js';
 import { createCloneNodeHandler } from './clone-node.js';
 import { createCombineAsVariantsHandler } from './combine-as-variants.js';
 import { createCreateComponentHandler } from './create-component.js';
@@ -129,6 +130,7 @@ export const createSandboxHandlers = (figmaCtx: typeof figma): SandboxHandlers =
     create_variable: createCreateVariableHandler(figmaCtx),
     set_variable_value: createSetVariableValueHandler(figmaCtx),
     bind_variable_to_node: createBindVariableToNodeHandler(figmaCtx),
+    bind_variable_to_paint: createBindVariableToPaintHandler(figmaCtx),
     rename_variable: createRenameVariableHandler(figmaCtx),
     delete_variable: createDeleteVariableHandler(figmaCtx),
     // Structure + bulk text

packages/plugin/test/handlers/bind-variable-to-node.test.ts

@@ -44,6 +44,16 @@ describe('bind_variable_to_node handler', () => {
     expect(result).toEqual({ ok: true, nodeId: '1:1' });
   });
 
+  it('redirects fills/strokes to bind_variable_to_paint (paint-level colour binding)', async () => {
+    for (const field of ['fills', 'strokes']) {
+      await expect(
+        createBindVariableToNodeHandler(
+          fakeFigma({ id: '1:1', setBoundVariable() {} }, { id: 'V:0' }),
+        )({ nodeId: '1:1', field, variableId: 'V:0' }),
+      ).rejects.toThrow(/use bind_variable_to_paint instead/);
+    }
+  });
+
   it('throws on missing node, missing variable, or non-bindable node', async () => {
     await expect(
       createBindVariableToNodeHandler(fakeFigma(null, { id: 'V:0' }))({

packages/plugin/test/handlers/bind-variable-to-paint.test.ts

@@ -0,0 +1,117 @@
+import type { MutateResult } from '@figwright/shared';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createBindVariableToPaintHandler } from '../../src/handlers/bind-variable-to-paint.js';
+
+const solid = () => ({ type: 'SOLID', color: { r: 1, g: 1, b: 1 } });
+
+// setBoundVariableForPaint returns a NEW paint (the binding marker) — the handler must write it back.
+const fakeFigma = (node: unknown, variable: unknown, bound: unknown) =>
+  ({
+    getNodeByIdAsync: async () => node,
+    variables: {
+      getVariableByIdAsync: async () => variable,
+      setBoundVariableForPaint: vi.fn<() => unknown>(() => bound),
+    },
+  }) as unknown as typeof figma & {
+    variables: { setBoundVariableForPaint: ReturnType<typeof vi.fn> };
+  };
+
+describe('bind_variable_to_paint handler', () => {
+  it('binds a colour variable to fills[0] and writes back a new paint array', async () => {
+    const node = { id: '1:1', fills: [solid()] };
+    const variable = { id: 'V:white' };
+    const boundPaint = {
+      type: 'SOLID',
+      color: { r: 1, g: 1, b: 1 },
+      boundVariables: { color: variable },
+    };
+    const ctx = fakeFigma(node, variable, boundPaint);
+
+    const result = (await createBindVariableToPaintHandler(ctx)({
+      nodeId: '1:1',
+      variableId: 'V:white',
+    })) as MutateResult;
+
+    expect(ctx.variables.setBoundVariableForPaint).toHaveBeenCalledWith(
+      expect.objectContaining({ type: 'SOLID' }),
+      'color',
+      variable,
+    );
+    // a NEW array with the returned paint at the index (not a mutation of the read-only original)
+    expect(node.fills).toEqual([boundPaint]);
+    expect(result).toEqual({ ok: true, nodeId: '1:1' });
+  });
+
+  it('targets strokes and the given index', async () => {
+    const node = { id: '2:2', strokes: [solid(), solid()] };
+    const variable = { id: 'V:grey' };
+    const bound = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } };
+    const ctx = fakeFigma(node, variable, bound);
+
+    await createBindVariableToPaintHandler(ctx)({
+      nodeId: '2:2',
+      target: 'strokes',
+      index: 1,
+      variableId: 'V:grey',
+    });
+
+    expect(node.strokes[1]).toBe(bound);
+    expect(node.strokes[0]).toEqual(solid()); // untouched
+  });
+
+  it('unbinds with variableId null, never looking up a variable', async () => {
+    const getVariableByIdAsync = vi.fn<() => Promise<unknown>>();
+    const node = { id: '3:3', fills: [solid()] };
+    const bound = solid();
+    const ctx = {
+      getNodeByIdAsync: async () => node,
+      variables: {
+        getVariableByIdAsync,
+        setBoundVariableForPaint: vi.fn<() => unknown>(() => bound),
+      },
+    } as unknown as typeof figma;
+
+    const result = (await createBindVariableToPaintHandler(ctx)({
+      nodeId: '3:3',
+      variableId: null,
+    })) as MutateResult;
+
+    expect(getVariableByIdAsync).not.toHaveBeenCalled();
+    expect(result).toEqual({ ok: true, nodeId: '3:3' });
+  });
+
+  it('rejects a non-SOLID paint at the target index', async () => {
+    const node = { id: '4:4', fills: [{ type: 'GRADIENT_LINEAR' }] };
+    await expect(
+      createBindVariableToPaintHandler(fakeFigma(node, { id: 'V:0' }, {}))({
+        nodeId: '4:4',
+        variableId: 'V:0',
+      }),
+    ).rejects.toThrow(/only SOLID paints/);
+  });
+
+  it('throws on missing node, missing paint index, or missing variable', async () => {
+    await expect(
+      createBindVariableToPaintHandler(fakeFigma(null, { id: 'V:0' }, {}))({
+        nodeId: '9:9',
+        variableId: 'V:0',
+      }),
+    ).rejects.toThrow(/not found or has no fills/);
+
+    await expect(
+      createBindVariableToPaintHandler(fakeFigma({ id: '1:1', fills: [] }, { id: 'V:0' }, {}))({
+        nodeId: '1:1',
+        index: 0,
+        variableId: 'V:0',
+      }),
+    ).rejects.toThrow(/no paint at fills\[0\]/);
+
+    await expect(
+      createBindVariableToPaintHandler(fakeFigma({ id: '1:1', fills: [solid()] }, null, {}))({
+        nodeId: '1:1',
+        variableId: 'V:missing',
+      }),
+    ).rejects.toThrow(/variable .* not found/);
+  });
+});