/understand-figma

Analisa um arquivo Figma e produz um grafo de conhecimento de design interativo no painel existente.

Pré-requisitos

• Variável de ambiente FIGMA_TOKEN — um token de acesso pessoal do Figma (crie um em https://www.figma.com/settings). Se estiver faltando, PARE e diga ao usuário:

  Defina um token do Figma primeiro: crie um em figma.com/settings, depois export FIGMA_TOKEN=<token>.

• Node ≥ 22, pnpm ≥ 10.

Segurança: o token é lido apenas do ambiente e viaja apenas no cabeçalho da requisição X-Figma-Token. Nunca o escreva no grafo, meta.json, logs ou arquivos intermediários. Esta habilidade faz chamadas de saída para api.figma.com — ao contrário de /understand, ela não é totalmente offline. Diga isso ao usuário uma vez.

Fase 0 — Preparação

1. Analisa $ARGUMENTS para obter uma URL do Figma ou chave de arquivo pura (o token sem flag) e um --language <lang> opcional.
2. Resolve PROJECT_ROOT para o diretório de trabalho atual. Resolve o diretório de dados $UA_DIR uma vez e reutilize-o para cada leitura e escrita abaixo: UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)" — o .understand-anything/ legado quando ele já existe, caso contrário, o novo .ua/. Como cada fase pode ser executada em um shell novo, leve $UA_DIR adiante como $PROJECT_ROOT, resolvendo-o novamente com a mesma linha se um bloco de comando posterior precisar dele.
3. Resolve PLUGIN_ROOT e garante que o core esteja compilado (mesma lógica de /understand Fase 0.1.5). Se packages/core/dist/figma/index.js estiver faltando, execute:

   cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build
   

4. mkdir -p $UA_DIR/intermediate.

Fase 1 — BUSCAR & ANALISAR (determinístico)

Execute o script de varredura empacotado (<SKILL_DIR> é o diretório desta habilidade):

FIGMA_TOKEN="$FIGMA_TOKEN" node <SKILL_DIR>/figma-scan.mjs "$PROJECT_ROOT" "<url-or-key>"

Ele escreve $UA_DIR/intermediate/scan-manifest.json e imprime as contagens de nós. Relate as contagens ao usuário. Se sair com código diferente de zero, relate o stderr e PARE.

Se a varredura imprimir UP_TO_DATE, relate "O grafo de design já está atualizado para esta versão do arquivo Figma" e PARE. Para forçar uma reconstrução completa, reexecute com UNDERSTAND_FIGMA_FORCE=1 definido no ambiente.

Fase 2 — ANALISAR (enriquecimento com LLM)

1. Leia scan-manifest.json. Agrupe os nós em lotes de ~15, agrupados por página quando possível.
2. Para cada lote, envie um subagente usando a definição de agente design-analyzer (agents/design-analyzer.md). Passe:
   • o lote de nós (id, type, name, figmaMeta, nomes de filhos, uso de token),
   • a lista completa de IDs de nós existentes,
   • $INTERMEDIATE_DIR = $UA_DIR/intermediate,
   • o número do lote para nomear a saída. O agente escreve analysis-batch-<N>.json. Anexe $LANGUAGE_DIRECTIVE se --language foi fornecido (reutilize o texto da diretiva de /understand).
3. Execute até 5 lotes simultaneamente. Se um lote falhar, registre um aviso e continue — o manifesto é uma base sólida.

Fase 3 — MESCLAR

node <SKILL_DIR>/figma-merge.mjs "$PROJECT_ROOT"

Ele combina scan-manifest.json + analysis-batch-*.json, executa mergeDesignGraph (valida, reanexa kind:"design") e escreve knowledge-graph.json + meta.json. Relate as estatísticas impressas e quaisquer problemas não-auto-corrected.

Fase 4 — SALVAR & INICIAR

1. Limpe os arquivos intermediários exceto scan-manifest.json:

   INTER="$UA_DIR/intermediate"
   find "$INTER" -mindepth 1 -maxdepth 1 -not -name 'scan-manifest.json' -exec rm -rf {} +
   

2. Relate um resumo: nome do projeto, contagens por tipo de nó, arestas por tipo, camadas, etapas do tour e o caminho $UA_DIR/knowledge-graph.json.
3. Inicie automaticamente o painel invocando a habilidade /understand-dashboard.