Figma Assets

Figma — pegar design e assets via MCP

Skill para trabalhar com links do Figma usando o MCP do Figma (server user-Figma). Dois fluxos:

• Flow 1 — Design/specs: obter código de referência, estrutura, tokens/variáveis e screenshot de um nó.
• Flow 2 — Assets (SVG/imagens): exportar/baixar SVG, PNG, JPG e as imagens originais de um nó.

Pré-requisito

• Server MCP user-Figma com status ready. Se estiver "needsAuth", chamar mcp_auth desse server e autenticar.
• O usuário precisa fornecer um link de nó específico (com node-id). Sem node-id, pedir o link do nó selecionado.

Passo 0 — Extrair fileKey e nodeId do link (SEMPRE primeiro)

A partir de https://figma.com/design/:fileKey/:fileName?node-id=1-2:

• fileKey = segmento após /design/.
• nodeId = valor de node-id, trocando - por : (ex.: 21016-6080 → 21016:6080).

Variações:

• Branch: https://figma.com/design/:fileKey/branch/:branchKey/:fileName → usar branchKey como fileKey.
• Só funciona em URLs /design/. /board/ (FigJam), /slides/ e /make/ têm outras ferramentas/regras.
• Se a URL não tiver node-id, pedir ao usuário o link do nó específico (não adivinhar nodeId).

Exemplo (link deste projeto): .../design/RNLC1stgG6AljmbLflHgO9/...?node-id=21016-6080 → fileKey = RNLC1stgG6AljmbLflHgO9, nodeId = 21016:6080.

Flow 1 — Design / specs

Objetivo: entender e/ou implementar um nó (tela, componente) do Figma.

1.1 — Contexto principal (get_design_context)

Ferramenta primária para design-to-code. Retorna código de referência + screenshot + metadados e URLs dos assets referenciados.

server: user-Figma
toolName: get_design_context
arguments: {
  "fileKey": "<fileKey>",
  "nodeId": "<nodeId>",
  "clientLanguages": "javascript,css,typescript",
  "clientFrameworks": "react"   // ou "preact", "vue", "unknown"
}

• O código retornado é referência, não final — adaptar aos padrões do projeto (ex.: VTEX IO → CSS Handles + vtex-io-component; deco.cx → deco-section/deco-island).
• Por padrão inclui screenshot. Só usar excludeScreenshot: true para poupar contexto quando o usuário pedir.

1.2 — Estrutura do nó (get_metadata) — opcional

Use para ter um mapa (IDs, tipos, nomes, posições, tamanhos) e então chamar get_design_context em nós filhos específicos. Bom para telas grandes.

server: user-Figma
toolName: get_metadata
arguments: { "fileKey": "<fileKey>", "nodeId": "<nodeId>" }

• Sem nodeId: lista as páginas de topo do arquivo (útil quando não se sabe onde entrar).

1.3 — Tokens / variáveis (get_variable_defs)

Cores, tipografia, espaçamentos, etc. definidos como variáveis no nó.

server: user-Figma
toolName: get_variable_defs
arguments: { "fileKey": "<fileKey>", "nodeId": "<nodeId>" }

Ex. retorno: { "icon/default/secondary": "#949494", "spacing/md": 16 } — mapear para tokens/tema do projeto.

1.4 — Screenshot de referência (get_screenshot)

Imagem do nó para comparar com a implementação.

server: user-Figma
toolName: get_screenshot
arguments: { "fileKey": "<fileKey>", "nodeId": "<nodeId>", "maxDimension": 1024 }

• Retorna URL curta + instruções curl (preferível; gasta menos contexto). Aumente maxDimension para inspecionar detalhes.

1.5 — Tipografia e espaçamentos EXATOS (obrigatório)

Nunca "chutar" fontes, tamanhos, margens ou espaçamentos. Extrair os valores reais do Figma e usá-los exatamente.

Fonte de verdade (ordem de prioridade)

1. get_variable_defs — pega tokens/variáveis do nó (cores, tipografia, espaçamentos). Se o valor estiver como variável (ex.: spacing/md = 16, font/body/size = 14), usar o token, não o número solto.
2. get_design_context — o código de referência traz os valores computados de CSS (font-family, font-size, font-weight, line-height, letter-spacing, margin, padding, gap). Extrair daqui o que não for variável.
3. get_metadata — posições e tamanhos (x, y, width, height) de cada nó; útil para conferir espaçamentos/margens entre elementos quando não há auto-layout.

Tipografia — capturar SEMPRE estes campos

• Estilos de texto (Text styles): se o texto usar um estilo compartilhado do design system, preferir mapear para o token/estilo equivalente do projeto em vez de valores soltos.
• Família de fonte: confirmar que o font-family existe no projeto (import/@font-face/tema). Se não existir, avisar o usuário antes de implementar.

Espaçamentos / margens — capturar de forma exata

• Preferir auto-layout do Figma como fonte de gap/padding (valores intencionais do designer).
• Sem auto-layout, medir pela diferença de coordenadas (x/y, width/height) entre os nós no get_metadata.
• Respeitar a grid/escala de espaçamento do projeto: se o design usa 4/8px e há tokens (spacing/*), usar o token correspondente em vez do número cru.
• Não arredondar "no olho": usar o valor do Figma (arredondar só se o projeto tiver regra de escala explícita, e então mapear ao token mais próximo).

Checklist antes de implementar

• font-family, font-size, font-weight, font-style, line-height, letter-spacing de cada texto capturados do Figma
• Fonte(s) disponível(is) no projeto (import/@font-face/tema) — senão, avisar
• gap/padding/margin vindos de auto-layout ou coords, não estimados
• Tokens/variáveis usados quando existem (get_variable_defs)
• Conferência visual final com get_screenshot

Flow 2 — Assets (SVG / imagens)

Objetivo: exportar/baixar SVG, PNG/JPG ou as imagens originais de um nó (ícones, logos, fotos).

2.1 — Baixar assets (download_assets)

server: user-Figma
toolName: download_assets
arguments: {
  "fileKey": "<fileKey>",
  "nodeId": "<nodeId>",
  "defaultFormat": "svg"   // "svg" | "png" | "jpg" | "pdf" (opcional)
  // "defaultScale": 2      // 0.01–4, só p/ png/jpg quando pedir resolução específica
}

Retorna:

1. Um render exportado do nó (no formato pedido).
2. A lista de imagens originais (JPEG/PNG/GIF/WebP) usadas como fills no subtree (até 20). Cada uma traz o format real → salvar com a extensão correta.

Regras:

• SVG (ícones/vetores/logos): passar defaultFormat: "svg".
• Foto/bitmap (banner, foto de produto): usar as imagens originais retornadas, ou defaultFormat: "png"/"jpg".
• Só definir defaultFormat/defaultScale quando o usuário pedir formato/resolução específicos; sem isso, respeita as export settings do nó (senão PNG @1x).
• URLs são temporárias — baixar imediatamente.

2.2 — Salvar no projeto

1. Baixar cada asset a partir da URL retornada (via curl/download) para a pasta correta do projeto:
   • VTEX IO: assets/ do app ou onde o time versiona ícones/imagens.
   • deco.cx: static/ (ou pasta de assets do projeto).
2. Nomear de forma semântica (ex.: icon-cart.svg, banner-pdp-mobile.png).
3. Confirmar com o usuário antes de criar arquivos (regra geral de permissão).

2.3 — SVG inline (opcional)

Se o objetivo é usar o SVG inline no código (componente React/Preact), abrir o conteúdo do .svg baixado e colar como JSX, ou referenciar o arquivo. Otimizar (remover metadados do Figma) se necessário.

Fluxo recomendado (design-to-code a partir de um link)

1. Passo 0: extrair fileKey + nodeId.
2. get_design_context para código + screenshot.
3. get_variable_defs para tokens de tipografia/espaçamento/cor (usar tokens quando existirem).
4. Capturar tipografia e espaçamentos exatos (seção 1.5): fontes, tamanhos, pesos, line-height, letter-spacing, gap/padding/margin.
5. download_assets (svg/png) para ícones e imagens do nó.
6. Salvar assets no projeto (com confirmação) e implementar adaptando aos padrões da stack (vtex-io-component / vtex-css / deco-section), aplicando os valores exatos capturados.
7. Comparar com get_screenshot para conferir fidelidade (tipografia e espaçamentos incluídos).

Ferramentas MCP (server user-Figma)

Regras

• Sempre extrair fileKey/nodeId do link antes de chamar qualquer ferramenta; nunca adivinhar nodeId.
• Tipografia e espaçamentos: nunca estimar. Extrair font-family, font-size, font-weight, font-style, line-height, letter-spacing, gap, padding e margin do Figma (variáveis > design context > metadata) e aplicar os valores exatos. Ver seção 1.5.
• Confirmar que a família de fonte existe no projeto antes de implementar; se faltar, avisar o usuário.
• Código do get_design_context é referência — adaptar à stack (não colar cru).
• Baixar assets logo após receber as URLs (expiram).
• Pedir confirmação antes de criar/salvar arquivos no projeto.
• Só /design/ nesta skill; FigJam (/board/), Slides (/slides/) e Make (/make/) não são cobertos aqui.
• Integra com: vtex-io-component, vtex-css, deco-section, deco-island para implementar o design extraído.