danielhall/agent-skills

Do site ao arquivo de design no Figma

Transforma um aplicativo web em execução em um arquivo Figma que um designer pode realmente usar para redesign: texto real, ícones reais, variáveis de cores e espaçamento com modos claro/escuro, estilos de texto, componentes reutilizáveis e cada página construída a partir de instâncias desses componentes. Capturas de tela servem apenas como referência, nunca como o entregável final.

Esta skill depende das skills do próprio plugin do Figma. Carregue figma-use e figma-generate-design antes de qualquer chamada use_figma, e figma-generate-library ao criar componentes ou variáveis.

Quando usar

• "Coloque meu site no Figma para que eu possa redesenhá-lo"
• "Recrie estas páginas no Figma" / "empurre este aplicativo para o Figma"
• Adicionar quadros mobile ou novas páginas a um arquivo Figma que foi construído desta forma

Passos

1. Leia a fonte da verdade

• O aplicativo em execução e a folha de estilo global têm prioridade sobre os documentos de design. Documentos podem ficar desatualizados durante um redesign; informe se encontrar uma discrepância.
• Colete: tokens de tema (claro e escuro), famílias e pesos de fonte, a grade de layout (gutters, rails, larguras de colunas) e os arquivos de componente por trás de cada seção da página.
• Verifique se as fontes existem no Figma com figma.listAvailableFontsAsync() antes de escrever estilos. Nunca use Inter como fallback silenciosamente.

2. Capture screenshots de referência com Playwright, não com page captures

Use scripts/ref-screenshots.mjs em cada largura alvo (por exemplo, 1440 e 390). O script define reducedMotion: "reduce", para que animações de scroll-reveal e de entrada não escondam o conteúdo.

As capturas de página do generate_figma_design não são confiáveis para esta tarefa: conteúdo atrás de animações em vista é capturado em branco, e capturas abertas em abas de navegador em segundo plano frequentemente ficam pending para sempre. Se você usá-las, abra uma aba por vez e delete a captura depois que ela tiver servido como referência. Se injetar o script de captura no aplicativo, remova-o depois.

3. Exporte dados reais e ícones do código-fonte

Escreva um script descartável tsx (fora do repositório ou excluído depois) que importe os módulos de dados do próprio aplicativo e renderize componentes de ícone para strings SVG com renderToStaticMarkup do react-dom/server. Então:

• Substitua currentColor por uma cor real e dê a cada SVG width/height explícitos. Bibliotecas de ícones emitem 1em, o que o Figma não consegue dimensionar.
• Deduplicar ícones pelos dados do path. Mapas de marca frequentemente apelidam muitos nomes para um único logo.
• Puxe conteúdo do CMS (títulos, resumos, categorias) com o cliente do CMS, em vez de redigitar.

4. Construa as fundações primeiro

Uma chamada cada, retornando todos os IDs criados:

1. Páginas: Fundações, Componentes, uma página por breakpoint.
2. Coleções de variáveis: cores do tema (modos Claro/Escuro), cores de categoria ou marca, tokens de layout (modos Desktop/Mobile). Defina scopes explícitos e sintaxe de código WEB.
3. Estilos de texto para cada função tipográfica, mais variantes mobile dos tamanhos de exibição.
4. Um estilo de efeito para qualquer sombra compartilhada.

5. Construa componentes, dos menores primeiro

Ícones, depois primitivos (botões, links, tiles, badges, chips), depois compostos (cabeçalho, rodapé, hero, cards). Exponha propriedades TEXT, BOOLEAN e INSTANCE_SWAP para que as páginas possam ser preenchidas sem desanexar. Dê às peças responsivas uma variante Breakpoint em vez de sobrescrever tamanhos nas instâncias. Capture cada grupo em tela uma vez e corrija o que estiver errado antes de prosseguir.

6. Monte as páginas a partir de instâncias

• Uma chamada use_figma por página, em posições fixas do canvas, para que as páginas possam ser construídas em paralelo.
• Espelhe a grade CSS com auto-layout e padding (por exemplo, um gutter e um rail), não com posições absolutas.
• Equalize alturas de cartões por linha explicitamente; o Figma não estica irmãos da mesma forma que a grade CSS.
• Compare a altura total de cada página e uma screenshot com a referência. Alturas com diferença de alguns por cento significam que o espaçamento está correto.

7. Vincule componentes de volta ao código

Code Connect funciona apenas nos planos Organization e Enterprise. Verifique whoami primeiro. Em outros planos, escreva o caminho do fonte, nome do componente e mapeamento de props na description de cada componente e defina documentationLinks para o arquivo no GitHub. O Modo Dev mostra ambos. Não adicione arquivos .figma.ts a um repositório que não pode publicá-los; eles quebram o tsc sem o pacote Code Connect.

8. Limpeza

Delete as capturas de referência, remova quaisquer scripts injetados, pare servidores de desenvolvimento que você iniciou e confirme que git status está limpo.

Armadilhas

Leia references/plugin-api-pitfalls.md antes de escrever scripts de componente ou página. Ele lista as falhas que custam mais tempo, cada uma com sua correção: opacidade de bound-paint, resize() bloqueando o dimensionamento automático, propriedades sendo re-chaveadas, referências perdidas em variantes clonadas, o limite de tamanho por chamada e mais.

references/helpers.md contém pequenas funções auxiliares que vale a pena colar no início de cada script de construção de página.