Construir / Atualizar Telas e Visualizações a partir do Sistema de Design
Use esta skill para criar ou atualizar telas, visualizações e contêineres de UI com várias seções no Figma reutilizando o sistema de design publicado: componentes, variáveis e estilos, em vez de desenhar primitivas com valores codificados. Isso inclui páginas completas, modais, diálogos, gavetas, barras laterais, painéis e qualquer visualização composta com várias seções. O insight principal: o arquivo do Figma provavelmente tem um sistema de design publicado com componentes, variáveis de cor/espaçamento e estilos de texto/efeito que correspondem aos componentes de UI e tokens do código. Encontre e use-os em vez de desenhar caixas com cores hexadecimais.
OBRIGATÓRIO: Você DEVE também carregar figma-use antes de qualquer chamada use_figma. Essa skill contém regras críticas (intervalos de cores, carregamento de fontes, etc.) que se aplicam a cada script que você escrever.
Sempre passe skillNames: "figma-generate-design" ao chamar use_figma como parte desta skill. Este é um parâmetro de registro. Não afeta a execução.
Limites da Skill
- Use esta skill quando a entrega for uma visualização Figma composta (nova ou atualizada), telas de página inteira, modais, diálogos, gavetas, barras laterais, painéis ou qualquer contêiner de várias seções, construído a partir de instâncias de componentes do sistema de design.
- Se o usuário quiser criar novos componentes ou variantes reutilizáveis, use figma-use diretamente.
- Se o usuário quiser escrever mapeamentos Code Connect, mude para figma-code-connect.
Pré-requisitos
- O servidor MCP do Figma deve estar conectado
- O arquivo Figma de destino deve ter um sistema de design publicado com componentes (ou acesso a uma biblioteca de equipe)
- O usuário deve fornecer:
- Uma URL do arquivo Figma / chave do arquivo para trabalhar
- Ou contexto sobre qual arquivo segmentar (o agente pode descobrir páginas)
- Código-fonte ou descrição da tela/visualização a ser construída/atualizada
Fluxo de Trabalho Paralelo com generate_figma_design (Apenas Aplicativos Web)
Ao construir uma tela a partir de um aplicativo web que pode ser renderizado em um navegador, os melhores resultados vêm da execução de ambas as abordagens em paralelo:
- Em paralelo:
- Comece a construir a tela usando o fluxo de trabalho desta skill (use_figma + componentes do sistema de design)
- Execute
generate_figma_designpara capturar uma captura de tela perfeita em pixels do aplicativo web em execução
- Assim que ambos estiverem concluídos: Atualize a saída do use_figma para corresponder ao layout perfeito em pixels da captura do
generate_figma_design. A captura fornece o espaçamento, dimensionamento e tratamento visual exatos a serem buscados, enquanto sua saída use_figma possui instâncias de componentes adequadas vinculadas ao sistema de design. Se a captura contiver imagens, transfira-as para sua saída use_figma copiando os valoresimageHashdos preenchimentos de imagem da captura (consulte a Etapa 5 para obter detalhes). - Assim que confirmar que está com boa aparência: Exclua a saída do
generate_figma_design. Ela foi usada apenas como referência visual.
Isso combina o melhor dos dois mundos: generate_figma_design fornece precisão de layout perfeita em pixels, enquanto use_figma fornece instâncias de componentes adequadas do sistema de design que permanecem vinculadas e atualizáveis.
Este fluxo de trabalho paralelo é OBRIGATÓRIO quando a fonte contém imagens. A API do Plugin use_figma não pode buscar URLs de imagens externas. Ela só pode definir preenchimentos de imagem copiando valores imageHash de nós já presentes no arquivo. generate_figma_design rasteriza todas as imagens visíveis no Figma, fornecendo os hashes que você precisa. Se você pular a captura quando houver imagens, os quadros de imagem ficarão em branco.
Para aplicativos não web (iOS, Android, etc.) ou ao atualizar telas existentes, use o fluxo de trabalho padrão abaixo.
Fluxo de Trabalho Obrigatório
Siga estas etapas em ordem. Não pule etapas.
Portões rígidos, atalhos proibidos:
- Proibido:
search_design_systempara chaves de componentes até que 2a-i esteja completo e 2a-ii seja tentado ou registrado como N/A (por exemplo, "arquivo vazio, sem telas existentes").- Proibido: Qualquer chamada
use_figmaque mude a tela (Etapa 3+) até que todas as linhas da Etapa 2 na lista de verificação abaixo estejam preenchidas.
Etapa 1: Entender a Entrega
Antes de tocar no Figma, entenda o que você está construindo:
- Se estiver construindo a partir do código, leia os arquivos de origem relevantes para entender a estrutura, seções e quais componentes são usados.
- Identifique as principais seções da visualização (por exemplo, para uma página: Cabeçalho, Heroi, Painéis de Conteúdo, Rodapé; para um modal: Barra de Título, Seções de Formulário, Barra de Ações; para uma barra lateral: Navegação, Área de Conteúdo, Ações do Rodapé).
- Para cada seção, liste os componentes de UI envolvidos (botões, entradas, cartões, navegações, acordeões, etc.).
- Verifique se a visualização contém imagens (por exemplo,
<img>,<Image>, imagens de fundo, fotos de produtos, avatares, ícones carregados de URLs). Se sim e for um aplicativo web, você deve executar o fluxo de trabalho paralelo de capturagenerate_figma_design, inicie-o imediatamente junto com a Etapa 2 para que a captura seja executada enquanto você descobre componentes. Consulte "Fluxo de Trabalho Paralelo com generate_figma_design" acima.
Etapa 2: Coletar Chaves de Componentes, Variáveis e Estilos
Você precisa de três coisas do sistema de design: componentes (botões, cartões, etc.), variáveis (cores, espaçamento, raios) e estilos (estilos de texto, estilos de efeito como sombras). Não codifique cores hexadecimais ou valores de pixel quando existirem tokens do sistema de design.
2a: Descobrir componentes
2a-i. OBRIGATÓRIO: Verificar Code Connect para componentes necessários. A partir da lista de componentes que você construiu na Etapa 1, verifique se cada componente tem um arquivo Code Connect no código. Os arquivos Code Connect ficam ao lado do código-fonte do componente e são nomeados por plataforma:
- TypeScript/JS:
*.figma.ts,*.figma.js - React (baseado em parser):
*.figma.tsx - Kotlin/Compose: arquivos
.ktcontendo@FigmaConnect - Swift: arquivos
.swiftcontendoFigmaConnect
Para cada componente que você precisa (por exemplo, Button, Card, Input), procure seu arquivo Code Connect, faça glob ou grep pelo nome do componente (por exemplo, **/Button.figma.tsx, **/Card.figma.ts). Leia apenas arquivos que correspondam a componentes que você realmente precisa.
De cada arquivo Code Connect correspondente, extraia a URL do componente Figma. Analise fileKey e nodeId da URL (converta hífens em dois pontos: 123-456 → 123:456). Em seguida, resolva as chaves dos componentes via use_figma:
Exemplo: O arquivo Code Connect contém // url=https://figma.com/design/ABC123/File?node-id=609-35535. Analise fileKey = ABC123, nodeId = 609:35535. Execute use_figma contra o arquivo da biblioteca (fileKey ABC123, não o arquivo de destino) para resolver a chave:
const node = await figma.getNodeByIdAsync("609:35535");
const set = node?.parent?.type === "COMPONENT_SET" ? node.parent : node;
return { componentKey: set.key };
Agrupe múltiplas consultas em uma única chamada. Use as chaves retornadas com importComponentSetByKeyAsync() na Etapa 4.
Marque os componentes resolvidos. Se todos os componentes estiverem resolvidos, pule 2a-ii e 2a-iii. Se nenhum dos componentes necessários tiver arquivos Code Connect, prossiga para 2a-ii.
2a-ii. OBRIGATÓRIO se componentes não resolvidos permanecerem: Inspecionar telas existentes. Verifique se o arquivo de destino já contém telas usando o mesmo sistema de design. Uma única chamada use_figma que percorre as instâncias de um quadro existente fornece um mapa de componentes exato e autoritativo:
// Descoberta somente leitura, pule conteúdo invisível dentro de instâncias (variantes
// ocultas etc.) para o findAllWithCriteria centenas de vezes mais rápido.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const uniqueSets = new Map();
frame.findAllWithCriteria({ types: ["INSTANCE"] }).forEach(inst => {
const mc = inst.mainComponent;
const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
const key = cs ? cs.key : mc?.key;
const name = cs ? cs.name : mc?.name;
if (key && !uniqueSets.has(key)) {
uniqueSets.set(key, { name, key, isSet: !!cs, sampleVariant: mc.name });
}
});
return [...uniqueSets.values()];
Combine os resultados com seus componentes não resolvidos. Marque quaisquer novos resolvidos. Se todos os componentes estiverem resolvidos, pule 2a-iii.
2a-iii. ÚLTIMO RECURSO: search_design_system. Apenas se componentes permanecerem não resolvidos após concluir tanto 2a-i quanto 2a-ii.
Antes de pesquisar, chame get_libraries para descobrir quais bibliotecas estão disponíveis para o arquivo. Isso retorna duas listas: bibliotecas já adicionadas ao arquivo e bibliotecas disponíveis para adicionar (kits de UI da comunidade e bibliotecas da organização). Cada entrada inclui um libraryKey que você pode passar para search_design_system através do parâmetro includeLibraryKeys para limitar sua pesquisa a bibliotecas específicas em vez de pesquisar em tudo.
// Etapa 1: Descobrir bibliotecas disponíveis
get_libraries({ fileKey })
// Retorna: {
// libraries_added_to_file: [...],
// libraries_available_to_add: [...],
// libraries_available_to_add_next_offset: number | null
// }
// Etapa 2: Pesquisar dentro de uma biblioteca específica usando seu libraryKey
search_design_system({ query: "button", fileKey, includeLibraryKeys: ["lk-abc123..."] })
As bibliotecas da organização em libraries_available_to_add são paginadas (20 por página). Quando libraries_available_to_add_next_offset não é nulo, mais bibliotecas da organização estão disponíveis, chame get_libraries novamente com offset definido para esse valor para buscar a próxima página. Os kits de UI da comunidade aparecem apenas na primeira página. Se o usuário nomear uma biblioteca específica que você não vê na página atual, avance mais páginas antes de desistir.
Isso é especialmente útil quando o arquivo tem muitas bibliotecas e você deseja resultados direcionados (por exemplo, pesquisar apenas em "iOS 26" ou "Material 3" em vez de obter correspondências de todas as bibliotecas).
Pesquise amplamente: tente vários termos e sinônimos (por exemplo, "button", "input", "nav", "card", "accordion", "header", "footer", "tag", "avatar", "toggle", "icon", etc.). Use includeComponents: true para focar em componentes.
Inclua propriedades de componentes no seu mapa. Você precisa saber quais propriedades TEXT cada componente expõe para substituições de texto. Crie uma instância temporária, leia suas componentProperties (e as de instâncias aninhadas) e, em seguida, remova a instância temporária.
Exemplo de mapa de componentes com informações de propriedade:
Component Map:
- Button → key: "abc123", type: COMPONENT_SET
Properties: { "Label#2:0": TEXT, "Has Icon#4:64": BOOLEAN }
- PricingCard → key: "ghi789", type: COMPONENT_SET
Properties: { "Device": VARIANT, "Variant": VARIANT }
Nested "Text Heading" has: { "Text#2104:5": TEXT }
Nested "Button" has: { "Label#2:0": TEXT }
2b: Descobrir variáveis (cores, espaçamento, raios)
Inspecione telas existentes primeiro (mesmo que componentes). Ou use search_design_system com includeVariables: true.
AVISO: Dois métodos diferentes de descoberta de variáveis, não os confunda.
use_figmacomfigma.variables.getLocalVariableCollectionsAsync(): retorna apenas variáveis locais definidas no arquivo atual. Se isso retornar vazio, isso não significa que não existem variáveis. Variáveis de biblioteca remotas/publicadas são invisíveis para esta API.search_design_systemcomincludeVariables: true: pesquisa em todas as bibliotecas vinculadas, incluindo remotas e publicadas. Esta é a ferramenta correta para descobrir variáveis do sistema de design.Nunca conclua "não existem variáveis" com base apenas em
getLocalVariableCollectionsAsync()retornar vazio. Sempre execute tambémsearch_design_systemcomincludeVariables: truepara verificar variáveis da biblioteca antes de decidir criar as suas próprias.
Estratégia de consulta: search_design_system corresponde a nomes de variáveis (por exemplo, "Gray/gray-9", "core/gray/100", "space/400"), não categorias. Execute várias consultas curtas e simples em paralelo em vez de uma consulta composta:
- Cores primitivas: "gray", "red", "blue", "green", "white", "brand"
- Cores semânticas: "background", "foreground", "border", "surface", "text"
- Espaçamento/dimensionamento: "space", "radius", "gap", "padding"
Se as pesquisas iniciais retornarem vazio, tente fragmentos mais curtos ou convenções de nomenclatura diferentes, as bibliotecas variam muito ("grey" vs "gray", "spacing" vs "space", "color/bg" vs "background").
Inspecione as variáveis vinculadas de uma tela existente para obter os resultados mais autoritativos:
// Descoberta somente leitura, pule interiores de instância invisíveis para velocidade.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
// boundVariables pode viver em qualquer nó de cena, enumerar cada tipo de cena
// apenas para alimentar findAllWithCriteria é aproximadamente o mesmo que findAll(() => true)
// e é muito mais ruidoso na saída do script.
const uniqueIds = new Set(
frame.findAll(() => true).flatMap(n =>
Object.values(n.boundVariables ?? {})
.flatMap(b => Array.isArray(b) ? b : [b])
.map(b => b?.id)
.filter(Boolean)
)
);
const variables = await Promise.all(
[...uniqueIds].map(id => figma.variables.getVariableByIdAsync(id))
);
return variables
.filter(Boolean)
.map(v => ({ name: v.name, id: v.id, key: v.key, type: v.resolvedType, remote: v.remote }));
Para variáveis de biblioteca (remote = true), importe-as pela chave com figma.variables.importVariableByKeyAsync(key). Para variáveis locais, use figma.variables.getVariableByIdAsync(id) diretamente.
Consulte variable-patterns.md para padrões de vinculação.
2c: Descobrir estilos (estilos de texto, estilos de efeito)
Pesquise estilos usando search_design_system com includeStyles: true e termos como "heading", "body", "shadow", "elevation". Ou inspecione o que uma tela existente usa:
// Descoberta somente leitura, pule interiores de instância invisíveis para velocidade.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const styles = { text: new Map(), effect: new Map() };
for (const node of frame.findAll(() => true)) {
// textStyleId está em TEXT e TEXT_PATH; effectStyleId está na maioria
// dos tipos de forma/contêiner de cena. Use guards 'in' para lidar com ambos
// sem uma lista exaustiva de tipos.
if ('textStyleId' in node && node.textStyleId) {
cons
...
[conteúdo truncado para tradução]