feat(m2): add 8 style + 6 variable write tools (34/52)

Styles: set_effects, create/update_paint_style, create_text/effect/grid_style,
apply_style_to_node (field=fill/stroke/effect/grid/text), delete_style.
Variables: create_variable_collection, add_variable_mode, create_variable,
set_variable_value (per-mode, alias/color), bind_variable_to_node, delete_variable.

New handlers/convert.ts inverts the read-side serializer (toFigmaEffect /
toFigmaLayoutGrid / toFigmaLineHeight / toFigmaVariableValue), pairing with the
existing toFigmaPaint so write handlers stop hand-rolling Figma objects.
shared/writes.ts gains StyleResult / CollectionResult / ModeResult /
VariableResult. All wrapped with idempotent() and registered in WRITE_TOOLS.

365 tests pass (+29); typecheck / oxlint / plugin+server build all green.
Styles/variables verified by unit tests only — real-Figma smoke deferred to the
end-of-M2 one-shot pass. PLAN.md M2 section synced.

Author: awdr74100

packages/plugin/src/code.ts

@@ -2,11 +2,22 @@ import { createPluginContextEvent, SELECTION_DETAIL_LIMIT } from '@figma-mcp-rel
 
 import { dispatchSandboxMessage, type SandboxHandlers } from './dispatcher.js';
 import { createIdempotencyCache, idempotent } from './idempotency.js';
+import { createAddVariableModeHandler } from './handlers/add-variable-mode.js';
+import { createApplyStyleToNodeHandler } from './handlers/apply-style-to-node.js';
+import { createBindVariableToNodeHandler } from './handlers/bind-variable-to-node.js';
 import { createCloneNodeHandler } from './handlers/clone-node.js';
+import { createCreateEffectStyleHandler } from './handlers/create-effect-style.js';
 import { createCreateFrameHandler } from './handlers/create-frame.js';
+import { createCreateGridStyleHandler } from './handlers/create-grid-style.js';
+import { createCreatePaintStyleHandler } from './handlers/create-paint-style.js';
 import { createCreateRectangleHandler } from './handlers/create-rectangle.js';
 import { createCreateTextHandler } from './handlers/create-text.js';
+import { createCreateTextStyleHandler } from './handlers/create-text-style.js';
+import { createCreateVariableHandler } from './handlers/create-variable.js';
+import { createCreateVariableCollectionHandler } from './handlers/create-variable-collection.js';
 import { createDeleteNodesHandler } from './handlers/delete-nodes.js';
+import { createDeleteStyleHandler } from './handlers/delete-style.js';
+import { createDeleteVariableHandler } from './handlers/delete-variable.js';
 import { createGetAnnotationsHandler } from './handlers/get-annotations.js';
 import { createGetDesignContextHandler } from './handlers/get-design-context.js';
 import { createGetDocumentHandler } from './handlers/get-document.js';
@@ -36,11 +47,14 @@ import { createSetAutoLayoutHandler } from './handlers/set-auto-layout.js';
 import { createSetBlendModeHandler } from './handlers/set-blend-mode.js';
 import { createSetConstraintsHandler } from './handlers/set-constraints.js';
 import { createSetCornerRadiusHandler } from './handlers/set-corner-radius.js';
+import { createSetEffectsHandler } from './handlers/set-effects.js';
 import { createSetFillsHandler } from './handlers/set-fills.js';
 import { createSetOpacityHandler } from './handlers/set-opacity.js';
 import { createSetStrokesHandler } from './handlers/set-strokes.js';
 import { createSetTextHandler } from './handlers/set-text.js';
+import { createSetVariableValueHandler } from './handlers/set-variable-value.js';
 import { createSetVisibleHandler } from './handlers/set-visible.js';
+import { createUpdatePaintStyleHandler } from './handlers/update-paint-style.js';
 
 figma.showUI(__html__, { width: 320, height: 400, themeColors: true });
 
@@ -114,6 +128,22 @@ const handlers: SandboxHandlers = {
   lock_nodes: idempotent(idempotencyCache, createSetLockedHandler(figma, true)),
   unlock_nodes: idempotent(idempotencyCache, createSetLockedHandler(figma, false)),
   clone_node: idempotent(idempotencyCache, createCloneNodeHandler(figma)),
+  // Styles
+  set_effects: idempotent(idempotencyCache, createSetEffectsHandler(figma)),
+  create_paint_style: idempotent(idempotencyCache, createCreatePaintStyleHandler(figma)),
+  create_text_style: idempotent(idempotencyCache, createCreateTextStyleHandler(figma)),
+  create_effect_style: idempotent(idempotencyCache, createCreateEffectStyleHandler(figma)),
+  create_grid_style: idempotent(idempotencyCache, createCreateGridStyleHandler(figma)),
+  update_paint_style: idempotent(idempotencyCache, createUpdatePaintStyleHandler(figma)),
+  apply_style_to_node: idempotent(idempotencyCache, createApplyStyleToNodeHandler(figma)),
+  delete_style: idempotent(idempotencyCache, createDeleteStyleHandler(figma)),
+  // Variables
+  create_variable_collection: idempotent(idempotencyCache, createCreateVariableCollectionHandler(figma)),
+  add_variable_mode: idempotent(idempotencyCache, createAddVariableModeHandler(figma)),
+  create_variable: idempotent(idempotencyCache, createCreateVariableHandler(figma)),
+  set_variable_value: idempotent(idempotencyCache, createSetVariableValueHandler(figma)),
+  bind_variable_to_node: idempotent(idempotencyCache, createBindVariableToNodeHandler(figma)),
+  delete_variable: idempotent(idempotencyCache, createDeleteVariableHandler(figma)),
 };
 
 figma.ui.onmessage = (raw: unknown) => {

packages/plugin/src/handlers/add-variable-mode.ts

@@ -0,0 +1,22 @@
+import type { ModeResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+export const createAddVariableModeHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { collectionId?: unknown; name?: unknown };
+    if (typeof p.collectionId !== 'string') {
+      throw new TypeError('add_variable_mode: collectionId must be a string');
+    }
+    if (typeof p.name !== 'string') throw new TypeError('add_variable_mode: name must be a string');
+
+    const collection = await figmaCtx.variables.getVariableCollectionByIdAsync(p.collectionId);
+    if (collection === null) {
+      throw new Error(`add_variable_mode: collection ${p.collectionId} not found`);
+    }
+    const modeId = collection.addMode(p.name);
+
+    const result: ModeResult = { ok: true, modeId, name: p.name };
+    return result;
+  };

packages/plugin/src/handlers/apply-style-to-node.ts

@@ -0,0 +1,39 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+const STYLE_FIELDS = ['fill', 'stroke', 'effect', 'grid', 'text'] as const;
+type StyleField = (typeof STYLE_FIELDS)[number];
+
+// Each field maps to the node's async style-id setter (Figma deprecated the sync `*StyleId` setters).
+const SETTER_BY_FIELD: Record<StyleField, string> = {
+  fill: 'setFillStyleIdAsync',
+  stroke: 'setStrokeStyleIdAsync',
+  effect: 'setEffectStyleIdAsync',
+  grid: 'setGridStyleIdAsync',
+  text: 'setTextStyleIdAsync',
+};
+
+export const createApplyStyleToNodeHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { nodeId?: unknown; styleId?: unknown; field?: unknown };
+    if (typeof p.nodeId !== 'string') throw new TypeError('apply_style_to_node: nodeId must be a string');
+    if (typeof p.styleId !== 'string') throw new TypeError('apply_style_to_node: styleId must be a string');
+    if (!STYLE_FIELDS.includes(p.field as StyleField)) {
+      throw new TypeError(`apply_style_to_node: field must be one of ${STYLE_FIELDS.join(' / ')}`);
+    }
+
+    const node = await figmaCtx.getNodeByIdAsync(p.nodeId);
+    if (node === null) throw new Error(`apply_style_to_node: node ${p.nodeId} not found`);
+
+    const setter = SETTER_BY_FIELD[p.field as StyleField];
+    const fn = (node as unknown as Record<string, unknown>)[setter];
+    if (typeof fn !== 'function') {
+      throw new Error(`apply_style_to_node: node ${p.nodeId} cannot take a ${String(p.field)} style`);
+    }
+    await (fn as (id: string) => Promise<void>).call(node, p.styleId);
+
+    const result: MutateResult = { ok: true, nodeId: node.id };
+    return result;
+  };

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

@@ -0,0 +1,28 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+export const createBindVariableToNodeHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { nodeId?: unknown; field?: unknown; variableId?: unknown };
+    if (typeof p.nodeId !== 'string') throw new TypeError('bind_variable_to_node: nodeId must be a string');
+    if (typeof p.field !== 'string') throw new TypeError('bind_variable_to_node: field must be a string');
+    if (typeof p.variableId !== 'string') {
+      throw new TypeError('bind_variable_to_node: variableId must be a string');
+    }
+
+    const [node, variable] = await Promise.all([
+      figmaCtx.getNodeByIdAsync(p.nodeId),
+      figmaCtx.variables.getVariableByIdAsync(p.variableId),
+    ]);
+    if (node === null) throw new Error(`bind_variable_to_node: node ${p.nodeId} not found`);
+    if (variable === null) throw new Error(`bind_variable_to_node: variable ${p.variableId} not found`);
+    if (typeof (node as { setBoundVariable?: unknown }).setBoundVariable !== 'function') {
+      throw new Error(`bind_variable_to_node: node ${p.nodeId} cannot bind variables`);
+    }
+    (node as SceneNode).setBoundVariable(p.field as VariableBindableNodeField, variable);
+
+    const result: MutateResult = { ok: true, nodeId: node.id };
+    return result;
+  };

packages/plugin/src/handlers/convert.ts

@@ -0,0 +1,68 @@
+import type {
+  SerializedEffect,
+  SerializedLayoutGrid,
+  SerializedLineHeight,
+  SerializedVariableValue,
+} from '@figma-mcp-relay/shared';
+
+// Inverse of serializer.ts — turn the wire-format back into Figma API objects for write tools.
+// (serializer.ts owns the Figma → wire direction; these are the matching wire → Figma helpers.)
+
+/** Wire effect → Figma Effect. Shadows need color + offset; blurs need radius. */
+export const toFigmaEffect = (e: SerializedEffect): Effect => {
+  if (e.type === 'DROP_SHADOW' || e.type === 'INNER_SHADOW') {
+    if (e.color === undefined || e.offset === undefined) {
+      throw new TypeError(`${e.type} requires color and offset`);
+    }
+    return {
+      type: e.type,
+      visible: e.visible,
+      radius: e.radius ?? 0,
+      color: { r: e.color.r, g: e.color.g, b: e.color.b, a: e.color.a },
+      offset: { x: e.offset.x, y: e.offset.y },
+      spread: e.spread ?? 0,
+      blendMode: 'NORMAL',
+    } as Effect;
+  }
+  if (e.type === 'LAYER_BLUR' || e.type === 'BACKGROUND_BLUR') {
+    return { type: e.type, visible: e.visible, radius: e.radius ?? 0 } as Effect;
+  }
+  throw new TypeError(`unsupported effect type: ${e.type}`);
+};
+
+/** Wire layout grid → Figma LayoutGrid. GRID is uniform; ROWS/COLUMNS carry count + gutter. */
+export const toFigmaLayoutGrid = (g: SerializedLayoutGrid): LayoutGrid => {
+  if (g.pattern === 'GRID') {
+    return { pattern: 'GRID', visible: g.visible, sectionSize: g.sectionSize ?? 10 };
+  }
+  if (g.pattern === 'ROWS' || g.pattern === 'COLUMNS') {
+    return {
+      pattern: g.pattern,
+      visible: g.visible,
+      alignment: g.alignment ?? 'STRETCH',
+      gutterSize: g.gutterSize ?? 0,
+      count: g.count ?? 1,
+      offset: 0,
+      ...(g.sectionSize === undefined ? {} : { sectionSize: g.sectionSize }),
+    } as LayoutGrid;
+  }
+  throw new TypeError(`unsupported layout grid pattern: ${g.pattern}`);
+};
+
+/** Wire line height → Figma LineHeight (AUTO omits value). */
+export const toFigmaLineHeight = (lh: SerializedLineHeight): LineHeight => {
+  if (lh.unit === 'AUTO') return { unit: 'AUTO' };
+  if (typeof lh.value !== 'number') {
+    throw new TypeError(`lineHeight unit ${lh.unit} requires a numeric value`);
+  }
+  return { unit: lh.unit as 'PIXELS' | 'PERCENT', value: lh.value };
+};
+
+/** Wire variable value → Figma VariableValue (alias / color / primitive). */
+export const toFigmaVariableValue = (value: SerializedVariableValue): VariableValue => {
+  if (typeof value === 'object' && value !== null) {
+    if ('r' in value) return { r: value.r, g: value.g, b: value.b, a: value.a };
+    return { type: 'VARIABLE_ALIAS', id: value.id };
+  }
+  return value;
+};

packages/plugin/src/handlers/create-effect-style.ts

@@ -0,0 +1,21 @@
+import type { SerializedEffect, StyleResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+import { toFigmaEffect } from './convert.js';
+
+export const createCreateEffectStyleHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async params => {
+    const p = (params ?? {}) as { name?: unknown; effects?: unknown; description?: unknown };
+    if (typeof p.name !== 'string') throw new TypeError('create_effect_style: name must be a string');
+    if (!Array.isArray(p.effects)) throw new TypeError('create_effect_style: effects must be an array');
+
+    const style = figmaCtx.createEffectStyle();
+    style.name = p.name;
+    style.effects = (p.effects as SerializedEffect[]).map(toFigmaEffect);
+    if (typeof p.description === 'string') style.description = p.description;
+
+    const result: StyleResult = { ok: true, styleId: style.id, name: style.name };
+    return result;
+  };

packages/plugin/src/handlers/create-grid-style.ts

@@ -0,0 +1,21 @@
+import type { SerializedLayoutGrid, StyleResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+import { toFigmaLayoutGrid } from './convert.js';
+
+export const createCreateGridStyleHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async params => {
+    const p = (params ?? {}) as { name?: unknown; grids?: unknown; description?: unknown };
+    if (typeof p.name !== 'string') throw new TypeError('create_grid_style: name must be a string');
+    if (!Array.isArray(p.grids)) throw new TypeError('create_grid_style: grids must be an array');
+
+    const style = figmaCtx.createGridStyle();
+    style.name = p.name;
+    style.layoutGrids = (p.grids as SerializedLayoutGrid[]).map(toFigmaLayoutGrid);
+    if (typeof p.description === 'string') style.description = p.description;
+
+    const result: StyleResult = { ok: true, styleId: style.id, name: style.name };
+    return result;
+  };

packages/plugin/src/handlers/create-paint-style.ts

@@ -0,0 +1,21 @@
+import type { SerializedPaint, StyleResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+import { toFigmaPaint } from './set-fills.js';
+
+export const createCreatePaintStyleHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async params => {
+    const p = (params ?? {}) as { name?: unknown; paints?: unknown; description?: unknown };
+    if (typeof p.name !== 'string') throw new TypeError('create_paint_style: name must be a string');
+    if (!Array.isArray(p.paints)) throw new TypeError('create_paint_style: paints must be an array');
+
+    const style = figmaCtx.createPaintStyle();
+    style.name = p.name;
+    style.paints = (p.paints as SerializedPaint[]).map(toFigmaPaint);
+    if (typeof p.description === 'string') style.description = p.description;
+
+    const result: StyleResult = { ok: true, styleId: style.id, name: style.name };
+    return result;
+  };

packages/plugin/src/handlers/create-text-style.ts

@@ -0,0 +1,41 @@
+import type {
+  SerializedFontName,
+  SerializedLetterSpacing,
+  SerializedLineHeight,
+  StyleResult,
+} from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+import { toFigmaLineHeight } from './convert.js';
+
+export const createCreateTextStyleHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as {
+      name?: unknown;
+      fontName?: unknown;
+      fontSize?: unknown;
+      lineHeight?: unknown;
+      letterSpacing?: unknown;
+      description?: unknown;
+    };
+    if (typeof p.name !== 'string') throw new TypeError('create_text_style: name must be a string');
+
+    const style = figmaCtx.createTextStyle();
+    style.name = p.name;
+    if (p.fontName !== undefined) {
+      const fn = p.fontName as SerializedFontName;
+      await figmaCtx.loadFontAsync({ family: fn.family, style: fn.style });
+      style.fontName = { family: fn.family, style: fn.style };
+    }
+    if (typeof p.fontSize === 'number') style.fontSize = p.fontSize;
+    if (p.lineHeight !== undefined) style.lineHeight = toFigmaLineHeight(p.lineHeight as SerializedLineHeight);
+    if (p.letterSpacing !== undefined) {
+      const ls = p.letterSpacing as SerializedLetterSpacing;
+      style.letterSpacing = { unit: ls.unit as 'PIXELS' | 'PERCENT', value: ls.value };
+    }
+    if (typeof p.description === 'string') style.description = p.description;
+
+    const result: StyleResult = { ok: true, styleId: style.id, name: style.name };
+    return result;
+  };

packages/plugin/src/handlers/create-variable-collection.ts

@@ -0,0 +1,23 @@
+import type { CollectionResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+export const createCreateVariableCollectionHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async params => {
+    const p = (params ?? {}) as { name?: unknown };
+    if (typeof p.name !== 'string') {
+      throw new TypeError('create_variable_collection: name must be a string');
+    }
+
+    const collection = figmaCtx.variables.createVariableCollection(p.name);
+
+    const result: CollectionResult = {
+      ok: true,
+      collectionId: collection.id,
+      defaultModeId: collection.defaultModeId,
+      name: collection.name,
+    };
+    return result;
+  };