TECHNICAL DOCUMENTATION

Protocol Specifications

Data models, streaming WebSocket packets, and plugin execution primitives for the Dizzy engine.

AST Schema

Semantic Buffer Tree

The semantic buffer is a typed tree representing your Figma canvas. The schema validator enforces valid node types, layout modes, and numeric ranges before sending any command to the plugin bridge.

Every node retains its corresponding native Figma object ID in _figma_ref so future voice commands update existing elements instead of creating duplicates.

Schema: BufferNode (TypeScript)
interface BufferNode {
  id: string;               // UUID-v4 identifier
  type: 'FRAME' | 'TEXT' | 'BUTTON' | 'IMAGE';
  intent: string;           // Transcribed voice command
  properties: {
    layout: 'HORIZONTAL' | 'VERTICAL' | 'NONE';
    padding?: [number, number, number, number];
    gap?: number;
    fill?: string;          // Hex color or token key
    cornerRadius?: number;
    width?: number | 'HUG' | 'FILL';
    height?: number | 'HUG' | 'FILL';
  };
  children: BufferNode[];
  _figma_ref?: string;      // Figma native node ID
}

Network Protocol

WebSocket Event Loop (Port 4040)

The client chunks microphone input into 250ms audio frames and streams them to the transcription worker over WebSocket.

When a partial transcript contains an explicit property keyword (like "padding", "darker", or "blue"), the engine calculates an immediate preview diff and sends it to the Figma plugin.

Live Session Stream
[15:42:01.102] connect: client=local_designer_1
[15:42:01.350] audio: 4096 bytes chunk received
[15:42:01.420] transcript: "add a primary button" (conf: 0.91)
[15:42:01.440] patch: +Node(type: "BUTTON", text: "Submit", fill: "#111827")
[15:42:01.455] figma_sync: 1 node created in 15ms

Plugin Runtime

Figma Plugin API Bridge

The Figma plugin listens for local mutation messages. It reads the targeted node from Figma's current selection and applies Auto-Layout dimensions directly through the official Plugin API.

Because changes use native Figma frame properties, the result is completely editable with standard keyboard shortcuts and mouse clicks.

plugin/mutator.ts
async function applyNodeMutation(node: BufferNode) {
  if (node._figma_ref) {
    const frame = await figma.getNodeByIdAsync(node._figma_ref);
    if (frame && frame.type === 'FRAME') {
      if (node.properties.fill) {
        frame.fills = [{ type: 'SOLID', color: hexToRgb(node.properties.fill) }];
      }
      if (node.properties.padding) {
        frame.paddingTop = node.properties.padding[0];
        frame.paddingRight = node.properties.padding[1];
        frame.paddingBottom = node.properties.padding[2];
        frame.paddingLeft = node.properties.padding[3];
      }
    }
    return;
  }

  // Create new Auto-Layout frame
  const frame = figma.createFrame();
  frame.layoutMode = node.properties.layout === 'VERTICAL' ? 'VERTICAL' : 'HORIZONTAL';
  frame.itemSpacing = node.properties.gap || 12;
  node._figma_ref = frame.id;
  figma.currentPage.appendChild(frame);
}