Work with a Figma spec

Check that figma.spec is defined in your first use_figma script; it exists only when the file’s plan has Specs enabled. If it is undefined, or use_figma reports that it is not supported for Figspec files, explain that Specs is not enabled for this file’s plan and stop the workflow. To create a new standalone Figma spec file, call whoami, choose a destination plan with specs_enabled: true, and call create_new_file with editorType: "figspec" and that plan's key as planKey; if no plan has it, explain that Specs is unavailable and stop.

A native Figma spec is GitHub-Flavored Markdown (GFM) under a SPEC_BLOCK node. A standalone Figma spec is just one spec; a FigJam or Design file can contain several embedded specs.

Discover and choose the Figma spec

Resolve a supplied URL node-id when present with figma.getNodeByIdAsync and require type === "SPEC_BLOCK" plus specBlockType === "DOCUMENT". Otherwise, search the current page with findAllWithCriteria({ types: ['SPEC_BLOCK'] }), filtering for specBlockType === "DOCUMENT" (and examine content with figma.spec.getContent if needed) until you find your target. If it's not on the current page, load other pages one at a time with page.loadAsync() and repeat your query, stopping once the target is resolved.

Pass the resolved root ID to every content call. Omit specNodeId only when the file is known to contain exactly one Figma spec; omission throws otherwise. Never edit ordinary canvas text nodes as a fallback.

Create a Figma spec on a canvas

// Creates an embedded Figma spec on a Design or FigJam canvas (not a standalone Figma spec file).
const { specNodeId } = await figma.spec.createOnCanvasAsync({
  title: 'Untitled spec',
  content: '# Title\n\nA paragraph.\n',
})

const specNode = await figma.getNodeByIdAsync(specNodeId)
if (!specNode) throw new Error('The created Figma spec could not be resolved')