figma-ui-web

Normas para desenvolvimento de UI Web com Figma (versão Framelink MCP)

Resolve o problema de baixa fidelidade ao desenvolver UI Web front-end a partir de um design Figma. A causa raiz é tratar os dados do canvas da Figma (coordenadas absolutas, cores inline, camadas de pixels) como "dados de implementação", copiando-os diretamente, o que leva a responsividade quebrada, cores e fontes imprecisas e recursos ausentes.

Este skill é direcionado às duas ferramentas do Framelink figma-developer-mcp:

Ferramenta	Canal	Função
get_figma_data	Canal Preciso	Puxa dados do canvas por fileKey + nodeId: informações de layout, conteúdo, visuais e componentes
download_figma_images	Canal Visual	Exporta nós como SVG/PNG/GIF para um diretório local

Nota: Esta é a versão Framelink, não o servidor MCP oficial do Figma (as ferramentas oficiais são get_design_context/get_variable_defs/download_assets). A metodologia deste skill é genérica para ambos, mas os nomes das ferramentas seguem o Framelink.

Se o alvo for desktop (Qt Widget / QML / WinUI / Flutter), utilize figma-ui-desktop em vez deste skill.

Princípios Centrais

1. Canais em paralelo, proibido codificar com apenas um canal. O canal preciso fornece valores exatos, o canal visual fornece layout e texto gerais. Usar apenas um leva à distorção — especialmente usar só o canal visual (equivale a adivinhar pela imagem) ou só o canal de dados (equivale a codificar às cegas).
2. Use valores exatos, não estimativas visuais. Cor, tamanho da fonte, altura da linha, peso da fonte, espaçamento, borda arredondada, borda e sombra devem sempre vir dos valores exatos do design.
3. Primeiro solicite o design, não crie UI por conta própria.
4. Após implementar, feche o ciclo de validação: compare screenshot com o design → corrija automaticamente defeitos visíveis → revisão manual e iteração. Não há mágica para atingir 100% de uma vez; atingir 70-80% depende do processo, e o restante depende do ciclo de validação.

Fluxo de Trabalho

Fase 1: Leitura Superficial (Entender Requisitos e Estrutura)

Quando o design for grande, faça uma leitura superficial primeiro para evitar sobrecarga de contexto ao puxar tudo de uma vez:

1. Use get_figma_data para puxar a estrutura de alto nível (depth controla a profundidade da travessia, comece raso) para entender quais páginas/seções/componentes existem.
2. Use download_figma_images para exportar a imagem geral da página, entendendo layout e texto.

Fase 2: Leitura Detalhada (Obter Dados Precisos Antes de Implementar)

Para o componente/seção específico a ser implementado, chame simultaneamente:

• get_figma_data (com nodeId, leia coordenadas, cores, tamanhos de fonte, espaçamentos, bordas arredondadas e bordas nó por nó)
• download_figma_images (exporte a imagem da seção para confirmar as relações de posicionamento relativo dos componentes)

Após obter os dados, faça análise estrutural antes de codificar:

• Quais nós são padrões repetitivos (cards, itens de lista, botões) → extraia como componentes
• Quais posições absolutas são na verdade layout (alinhamento horizontal, centralização, justificação) → converta para flex/grid
• Quais são papéis semânticos (navegação/formulário/lista) → mapeie para a biblioteca de componentes existente do framework alvo
• Nós de imagem/ícone → use download_figma_images para baixar os arquivos originais para a pasta assets, não desenhe manualmente

Fase 3: Implementação

• Use valores exatos de cor, tamanho de fonte e espaçamento do design, não "parece estar próximo"
• Priorize o uso da biblioteca de componentes existente do projeto; consulte primeiro as props dos componentes (theme/size/variant) para evitar redefinir estilos
• Ícones: use a biblioteca de ícones do projeto, não ícones de terceiros
• A nomeação de arquivos de estilo, nomes de classes CSS e profundidade de aninhamento devem seguir as convenções do projeto

Fase 4: Ciclo de Validação Fechado

Use o Playwright MCP para abrir a página local, capturar screenshot e comparar lado a lado com o screenshot do design. Corrija automaticamente defeitos visíveis; faça revisão manual: identifique problemas mais sutis (espaçamento, peso da fonte, pequenas diferenças de cor) e ativamente submeta ao AI para correção precisa, entrando na próxima iteração.

Regras Contra Preguiça

O AI tende a usar apenas um canal para codificar; é necessário exigir explicitamente:

• "Chame get_figma_data e download_figma_images simultaneamente para ler o design"
• "Não é permitido usar apenas imagens/screenshots do design para codificar"
• "Leia linha por linha os valores exatos de get_figma_data, compare cores/tamanhos de fonte/espaçamentos, não faça estimativas visuais"

Especificações de Componentes (Substituir Conforme o Projeto)

Abaixo está um modelo; ao aplicar em um projeto específico, substitua pelas convenções desse projeto:

• Priorize o uso da biblioteca de componentes do projeto (ex.: @notta/components); em caso de dúvida, pergunte ativamente ao usuário
• Consulte primeiro as props da biblioteca de componentes para evitar redefinir estilos
• Ícones: use a biblioteca de ícones do projeto
• A nomeação de arquivos de estilo, nomes de classes CSS e profundidade de aninhamento devem seguir as convenções do projeto

Checklist de Autoverificação de Fidelidade

Após gerar, verifique item por item (mais confiável do que "parece semelhante no geral"):

• Cores (se usou o hex exato, não aproximado)
• Tamanho da fonte / altura da linha / peso da fonte
• Espaçamento / margem / padding
• Borda arredondada / borda / sombra
• Layout (se flex/grid é equivalente à disposição do design)
• z-index / níveis
• Se ícones/imagens usam os arquivos originais, não desenhados manualmente

Fonte de Referência

A metodologia é baseada no fluxo oficial Figma MCP + Playwright para desenvolvimento de UI (consulte "Uso do Figma MCP e Playwright MCP para aumentar a eficiência de desenvolvimento e depuração de UI"), cujo núcleo é "dois canais + ciclo de validação fechado + exigências explícitas contra preguiça"; os nomes das ferramentas foram adaptados para o Framelink figma-developer-mcp.