analyze-fig (análise de figma)

analyze-fig

Análise da exportação do Figma (.fig) sem recorrer à API do Figma: a árvore de nós, textos e rasters são lidos diretamente do arquivo, enquanto os comentários do autor (que não estão no .fig) são obtidos separadamente via MCP usando um link. O resultado são arquivos Markdown em spcfctn/ui/, que passam a ser usados no lugar de uma nova leitura do Figma.

Quando não executar

Questões sobre um layout já analisado ("o que diz o comentário sobre o filtro…", "quais colunas na tela…") devem ser resolvidas lendo spcfctn/ui/*.md, não com esta skill. A análise é necessária apenas para um .fig novo ou atualizado, ou quando a resposta não está nos arquivos Markdown (veja spcfctn-code.md).

Diretórios (único diretório de rascunho draft, fora do git)

• spcfctn/ui/draft/ — entrada .fig (e quaisquer outros rascunhos). O arquivo é colocado pelo usuário.
• spcfctn/ui/draft/<nome>/ — resultado da descompactação: message.json (todos os nós), meta.json, images/, screens.json e screens.txt, além dos comentários coletados (comments.json). É gerado a partir do .fig e não entra no git. Não há subdiretórios separados raw/ e data/ (modeling.md).
• spcfctn/ui/*.md — resultado da análise; apenas isso permanece no git.

<nome> — nome do arquivo sem extensão, em minúsculas e com hífens (internal-interfaces).

Passo 0 — preparação

• Encontre o diretório spcfctn/ do projeto. Se não existir, peça ao usuário para criá-lo (spcfctn-code.md). Crie o artefato ui/ e seu subdiretório draft/ você mesmo.
• Verifique spcfctn/ui/.gitignore (repositório do artefato): deve conter draft (veja modeling.md); adicione o que estiver faltando usando gitignore.org.
• Arquivo .fig: o nome é indicado pelo usuário; se não for indicado, liste spcfctn/ui/draft/*.fig e pergunte.
• Leia o CLAUDE.md do projeto (idioma da prosa, convenções) e os arquivos spcfctn/ui/*.md existentes: a análise deve dar continuidade à estrutura e terminologia deles, não começar do zero.
• São necessários python3 e zstd no PATH.

Passo 1 — descompactar e decodificar

python3 ~/.claude/skills/analyze-fig/scripts/fig.py spcfctn/ui/draft/X.fig spcfctn/ui/draft/<nome>

Exibe a versão do formato, quantidade de nós, blobs e imagens. O script foi testado na versão 106; em outra versão ou com erro, não tente adivinhar o formato ou usar decodificadores de terceiros — informe o usuário. meta.json contém exported_at: a hora da exportação será usada no passo 5. message.json é grande e não deve ser impresso diretamente.

Passo 2 — dividir em seções e telas

python3 ~/.claude/skills/analyze-fig/scripts/screens.py spcfctn/ui/draft/<nome>

Exibe a lista de páginas, seções (frames de nível superior) e telas (seus filhos) com a quantidade de textos e rasters. A essência está em screens.txt: para cada tela, as camadas de texto são agrupadas em linhas de cima para baixo e da esquerda para a direita (assim são lidos filtros, títulos de colunas e botões), além de referências para rasters.

• Compare as quantidades com as esperadas (por exemplo, com um Markdown antigo); divergência é motivo para parar.
• As camadas de texto não capturam elementos sem texto (ícones vazios) nem o conteúdo dos rasters. Para cada raster em images/, abra o arquivo (Leitura) e descreva o que não está nas camadas de texto; indique que isso foi lido da imagem. A árvore e os textos são a evidência principal; as imagens são um complemento.
• Instâncias de componentes (INSTANCE) podem ter textos sobrescritos que o script não detecta; screens.txt avisa sobre isso.

Passo 3 — escrever spcfctn/ui/*.md

• Um Markdown por seção (ou por arquivo, quando há apenas uma seção). Se o arquivo já existir, leia-o por completo e atualize-o, não o reescreva: os arquivos Markdown são mantidos apenas pelo agente, mas as correções anteriores não podem ser perdidas.
• Idioma da prosa: conforme o CLAUDE.md do projeto.
• Estrutura (exemplo: spcfctn/ui/internal-dashboard.md em job/vale/kylada): introdução com fonte e verificação (o que foi lido, data de exportação, número de telas e textos), regras de leitura dos layouts, correspondência dos rótulos da interface com termos internos, telas em ordem (filtros na ordem do layout, botão de lista, colunas, ações nas linhas), questões em aberto.
• Tudo o que é sua interpretação, e não texto do layout ou comentário, marque como inferido.
• As regras de projeto para leitura de layouts (por exemplo, que Select abaixo do título de coluna controla a ordenação) devem ser obtidas do CLAUDE.md do projeto e aplicadas, não inventadas.

Passo 4 — comentários via MCP usando link

Os comentários não estão no .fig (verificado): eles ficam no servidor do Figma.

• É necessário um link para o arquivo no Figma (com ou sem node-id). Se não houver, peça ao usuário.
• Use apenas a ferramenta MCP comments do servidor Figma MCP configurado no projeto (pegue o nome da lista de servidores conectados); o parâmetro file é o link. Se essa ferramenta não existir, informe o usuário. O servidor oficial figma-cs não retorna comentários. Não chame a API REST diretamente com token e não mexa em .env.
• A chamada sem node_id retorna todos os comentários do arquivo por ramo (número, data, estado, nó @id, texto, respostas). Não use refresh desnecessariamente. O endpoint de comentários é contado separadamente da leitura do arquivo e funciona mesmo quando a leitura retorna 429.
• Vinculação à tela:
  • Se @id coincide com o ID de uma tela em screens.json, a tela está determinada.
  • Se @id é de uma seção ou página, a tela é determinada por geometria; para isso, são necessários node_id e node_offset do comentário. Monte linhas CHAVE NÓ X Y (exemplo: #144 979:3 500 5471) e passe para:

    python3 ~/.claude/skills/analyze-fig/scripts/place.py spcfctn/ui/draft/<nome> < linhas
    

    Saída: chave, seção, tela; ou o motivo e a tela mais próxima, se o ponto não estiver em uma tela.
  • Verifique a saída: a ferramenta comments pode não imprimir node_offset (era o caso quando a skill foi criada). Nesse caso, comentários vinculados a seções ou página não podem ser atribuídos a uma tela exata: não adivinhe a tela pelo texto; associe-os à seção, marque tela não determinada e informe ao usuário que é necessário o deslocamento do comentário.
• Respostas (↳) pertencem ao ramo do pai.

Passo 5 — verificar se os comentários correspondem ao arquivo

Para cada comentário com tela determinada (e para o grupo de comentários da seção), verifique:

• Se os campos, colunas, botões, valores mencionados no comentário estão entre as camadas de texto daquela tela (Amount of integrated services ↔ coluna Services; citações entre aspas; listas de valores).
• Se o comentário não contradiz o layout (número de colunas, ordem, tipo de elemento, "há filtro" / "não há").
• Data: se o comentário é mais recente que exported_at de meta.json, a exportação está desatualizada. Nesse caso, peça uma exportação nova em spcfctn/ui/draft/.
• Se o nó do comentário não existe mais no arquivo (foi removido ou renomeado), é um comentário órfão.
• Comentário sem tela e sem conteúdo reconhecível.

Resuma as divergências em uma pequena tabela (número #N, tela, divergência) e pergunte ao usuário o que está correto: não corrija silenciosamente nem escolha entre layout e comentário. Até a resposta, marque-as no Markdown como conflito.

Passo 6 — escrever o resumo

• No Markdown, adicione uma seção com os comentários do autor: um resumo (o que eles esclarecem) e todos os comentários por tela com números #N. Quando um comentário corrige algo que estava inferido, corrija o registro e referencie o comentário.
• Atualize a "Verificação" na introdução: o que foi lido (.fig, versão, data de exportação, textos, rasters, comentários, data de obtenção) e o que não foi coberto.
• Questões em aberto — em lista separada; respostas do usuário mova para "Resolvidas".
• Não faça commit sem solicitação. Resuma verbalmente (em português): quantas seções, telas, comentários, quantas divergências e o que precisa ser esclarecido.

O que não fazer

• Não chame a API REST do Figma com token, não leia nem edite .env.
• Não leia código de terceiros (decodificadores kiwi, etc.): o formato já está implementado em scripts/.
• Não coloque o .fig nem os resultados da análise (tudo em draft/) no git.
• Não adivinhe a tela de um comentário pelas palavras nem o conteúdo do layout pela imagem quando há camadas de texto disponíveis.