figma-spec
Work with a Figma spec
You MUST always call whoami before using any figma.spec.* API and confirm that the target file’s plan (or the destination plan for a new file) has specs_enabled: true. whoami does not identify which plan owns a file. If the plan is unclear, you MUST ask the user; never infer it from the file key or another plan’s access. If specs_enabled is false or absent for that plan, explain that Specs is unavailable and stop the workflow.
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.