figma/mcp-server-guide

figma-spec

This skill is required to create, read, edit, review, or comment on Figma specs.

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/figma/mcp-server-guide --skill figma-spec

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

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.

Create a Figma spec on a canvas

js
// 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')

const after = await figma.spec.getContent({ specNodeId })
if (!after.markdown.includes('A paragraph.')) {
  throw new Error('The new Figma spec content was not applied')
}

Always pass a non-empty title and a content string ('' is allowed). title names the root; include any desired # H1 in content.

Content methods

js
// READ — returns specNodeId, markdown, title, etc.
// The body is `markdown`, not `content`.
const before = await figma.spec.getContent({ specNodeId: chosenSpec.id })
const page = await figma.spec.getContent({
  specNodeId: before.specNodeId,
  offset: 100,
  maxLines: 50,
})

// REPLACE — clears + recreates the document; use only for an empty first draft.
await figma.spec.setContent({
  specNodeId: before.specNodeId,
  content: '# Title\n\nA paragraph.\n',
})

// EDIT — find/replace; each oldText must match exactly once.
await figma.spec.editContent({
  specNodeId: before.specNodeId,
  edits: [{ oldText: 'First paragraph.', newText: 'Edited first paragraph.' }],
})

const after = await figma.spec.getContent({ specNodeId: before.specNodeId })
if (!after.markdown.includes('Edited first paragraph.')) {
  throw new Error('The targeted Figma spec edit was not applied')
}
  • Use `getContent` with the same specNodeId before edits and to verify writes; DON'T rely on screenshots.
  • Default to multiplayer-safe, surgical `editContent`.
  • Use destructive `setContent` only for an empty first draft or an explicit whole-document replacement.

Critical rules

  1. `editContent` requires exactly one match. Zero or multiple oldText matches fail without changes. Add surrounding context to make it unique.
  2. Pass Markdown as plain strings. Never encode it with Buffer/base64 or decode it with atob(). Base64 is only for image data URLs inside Markdown.
  3. Keep Markdown and traversal separate. figma.spec.* handles content; node traversal exposes only document roots and embedded-canvas branches.
  4. Preserve comment markers. Keep overlapping [comment:<uuid>]…[/comment:<uuid>] pairs unchanged around the same text, or the thread may detach or disappear. When in doubt copy the marked span exactly and edit around it.
  5. Use portable references. Shared Figma specs must use links such as GitHub permalinks, never machine-local paths or localhost URLs.

Style

  • Keep the title block first and formatted as H1, even when its text is empty. Never remove it or insert blocks before it.
  • Prefer bold text in table header row.
  • Use <ins> for underline, including combined formatting: <ins>**bold and underlined**</ins>. Do not use <u>, which only works in HTML imports.

Images

Images use GFM image syntax inside setContent or editContent:

  • ![alt](data:image/png;base64,...) embeds bytes that are decoded and uploaded.
  • ![alt](https://host/img.png) is fetched server-side; disallowed hosts are rejected.

getContent emits image URLs as https://<host>/spec/<fileKey>/image/<sha>?w=<width>&h=<height>.

Comments

Use figma.spec.comments.* for anchored threads. Prefer comments over leaving silent edits when you're unsure of a change.

js
const comment = await figma.spec.comments.create({
  specNodeId: before.specNodeId,
  anchorText: 'the exact rendered text to anchor to', // MUST appear exactly once
  contextText: 'a longer unique substring containing anchorText', // optional; disambiguates repeats
  message: 'Comment body (markdown).',
})

const { root, replies, hasMore } = await figma.spec.comments.getThread({ uuid: comment.uuid })
await figma.spec.comments.reply({ uuid: comment.uuid, message: 'A reply.' })
  • anchorText must match exactly once in the rendered Figma spec. Use a longer contextText containing it to disambiguate repeated text.
  • getThread and reply require the root comment UUID surfaced by a [comment:<uuid>] marker; never pass a reply UUID to reply.

Relacionados por tarefa

do mesmo repositório

Mais Skills

Todos os Skills
figma
Oficial

figma-generate-design

Use this skill alongside figma-use when the task involves translating an application page, view, or multi-section layout into Figma. Triggers: 'write to Figma', 'create in Figma from code', 'push page to Figma', 'take this app/page and build it in Figma', 'create a screen', 'build a landing page in Figma', 'update the Figma screen to match code', 'convert this modal/dialog/drawer/panel to Figma'. This is the preferred workflow skill whenever the user wants to build or update a full page, modal,

Instalações / 1h
2
GitHub Stars
2,2 mil
Atualizado
16 de nov.
figma
Oficial

figma-swiftui

SwiftUI ↔ Figma translation. Use whenever the user mentions Swift, SwiftUI, iOS, iPhone, or iPad — in EITHER direction — translating a Figma design into SwiftUI (design → code), or pushing SwiftUI views / screens / tokens back into a Figma file (code → design). Triggers on phrases like 'implement this Figma design in SwiftUI', 'build this screen in Swift', 'push this SwiftUI view to Figma', 'mirror my Swift code in a Figma file', or whenever a Figma URL appears alongside .swift files / an .xcode

Instalações / 1h
2
GitHub Stars
2,2 mil
Atualizado
9 de nov.
figma
Oficial

figma-generate-library

Build or update a professional-grade design system in Figma from a codebase. Use when the user wants to create variables/tokens, build component libraries, create individual components with proper variant sets and variable bindings, set up theming (light/dark modes), document foundations, or reconcile gaps between code and Figma. Also use when the user asks to create or generate any component in Figma — even a single one — since components require proper variable foundations, variant states, and

Instalações / 1h
2
GitHub Stars
2,2 mil
Atualizado
9 de nov.
figma
Oficial

figma-use

MANDATORY prerequisite — you MUST invoke this skill BEFORE every usefigma tool call. NEVER call usefigma directly without loading this skill first. Skipping it causes common, hard-to-debug failures. Trigger whenever the user wants to perform a write action or a unique read action that requires JavaScript execution in the Figma file context — e.g. create/edit/delete nodes, set up variables or tokens, build components and variants, modify auto-layout or fills, bind variables to properties, or insp

Instalações / 1h
2
GitHub Stars
2,2 mil
Atualizado
9 de nov.