acesso-figma

Acesso ao Figma

Você trabalha com o Figma através de uma ferramenta de linha de comando. Ela imprime KDL e salva seus arquivos de dados como .kdl: um nó por linha, com os campos simples de um nó como chave=valor nessa linha, para que grep, awk e sed funcionem diretamente nela. As exceções são spec, que imprime seu próprio esboço de texto de uma linha por nó, daemon log, que imprime as linhas de log do daemon como elas são, e render, screenshot, image-fills e compare, que salvam arquivos de imagem (o resumo na saída padrão ainda é KDL). Possui duas formas de acesso:

• REST (file, node, spec, render, image-fills, api): lê qualquer arquivo a partir de sua URL com o token do usuário. Nada precisa estar aberto. As leituras são armazenadas em cache localmente e repetidas em caso de limites de taxa.
• Plugin (exec, screenshot, selection, logs, changes, call): um daemon em segundo plano se comunica com o plugin Desktop Bridge em execução no Figma Desktop. Esta é a única maneira de alterar um arquivo. Sua principal ferramenta aqui é exec, que executa JavaScript da API de Plugin do Figma no arquivo.

references/tips.md contém lições de execuções reais, organizadas por situação. São orientações, não regras: leia a seção para a situação em que você se encontra e adapte-a ao seu caso.

Regras

• Nunca mostre o token. Não imprima, registre em log ou ecoe; teste-o com figma-access api /v1/me.
• Observe antes e depois de alterar qualquer coisa. Julgue cada resultado visível em uma imagem, não no código que a gerou.
• Leia os valores, não os adivinhe; o renderizador decide. Obtenha cores, tamanhos, espaçamentos, fontes e texto do arquivo, nunca a olho nu a partir de uma imagem. Quando os dados do arquivo e o render discordarem, o render é o que o usuário vê.
• Altere apenas o que o usuário pediu. Ler é sempre aceitável. Nunca delete ou sobrescreva o trabalho existente do usuário, a menos que a solicitação o exija.
• Um timeout não é uma falha. O Figma não pode parar um script em execução; verifique logs e o arquivo antes de executá-lo novamente.

Fluxo de trabalho

1. Configuração

1. <skill> é o diretório deste SKILL.md. Execute a ferramenta como bun <skill>/scripts/figma-access.js COMANDO ...; este arquivo a escreve como figma-access COMANDO .... Ela roda no Bun, não no Node: sempre inicie com bun, nunca node, e execute qualquer auxiliar JavaScript ou TypeScript que você escrever também com bun. Para encurtar o comando, defina uma função de shell no início de cada chamada de shell (fa(){ bun <skill>/scripts/figma-access.js "$@"; }; fa ...), não uma variável: o zsh não divide uma variável em palavras. Coloque entre aspas toda URL e id de nó que você passar: ?, & e ; são especiais para o shell. Se bun estiver faltando, diga ao usuário para instalá-lo em https://bun.sh e pare.
2. Execute figma-access --help uma vez, e figma-access <comando> --help antes do primeiro uso de cada comando. Códigos de saída: 0 ok, 1 Figma reportou uma falha, 2 argumentos ruins, 3 daemon, plugin ou token não disponível. "Lendo a saída" em references/tips.md explica o formato e como pesquisá-lo.
3. Escolha o caminho a partir da solicitação, como "Escolhendo um caminho" em references/tips.md descreve: uma URL e um trabalho somente leitura → REST; qualquer alteração no arquivo → plugin; ambos podem ser usados juntos.

2a. Conecte-se via REST

1. Execute figma-access api /v1/me. Em "sem token": encontre onde o usuário o definiu e carregue-o no mesmo comando, como "Token" em references/tips.md descreve. Peça ao usuário um token (Figma: Configurações > Segurança > Tokens de acesso pessoal, leitura de conteúdo do arquivo) apenas quando nenhum estiver definido em lugar nenhum.
2. Execute figma-access file <url> para ver as páginas e os quadros de nível superior. Escolha o nó no qual trabalhar, seguindo "Encontrando o nó certo" em references/tips.md.

2b. Conecte-se através do plugin

1. Execute figma-access status. Ele inicia o daemon quando necessário.
   • Arquivos listados: continue.
   • Sem arquivos: execute figma-access files, que aguarda o plugin. Se sair com 3, execute figma-access setup e dê ao usuário seus steps em palavras simples: importe o plugin uma vez do caminho do manifesto impresso, depois execute Plugins > Development > Figma Desktop Bridge no arquivo e mantenha sua janela aberta. Peça ao usuário para lhe dizer quando estiver em execução, então execute figma-access files novamente.
2. Mais de um arquivo conectado: passe --file <fileKey> em todos os comandos após este.

3. Entenda o design

1. Leia a menor visão que responda à pergunta, primeiro o esboço e detalhes apenas onde você trabalha:
   • estrutura: figma-access node <url|key> <id> --outline 2 (REST), ou a receita de esboço de página em references/plugin-api.md (plugin);
   • tudo que o código precisa, uma linha por nó visível: figma-access spec <url|key> <id> -o <arquivo>; para um quadro grande, salve-o uma vez com node ... -o <arquivo> e passe --from <arquivo> para cada spec posterior, como "Limites de taxa e o cache" em references/tips.md descreve;
   • o que o usuário quer dizer com "isso" ou "o selecionado": figma-access selection;
   • como se parece: figma-access render <key> <id> (REST, tamanho exato) ou figma-access screenshot <id> (plugin), então abra a imagem.
2. Leia os reports de node: fontes, preenchimentos de imagem e quantas camadas ocultas foram podadas. Leia "Camadas ocultas" e "Lendo uma imagem de design" em references/tips.md.
3. Para componentes, variantes, variáveis e estilos, leia sua estrutura real antes de alterá-los ou copiá-los, e reutilize o que existe em vez de criar duplicatas.

4. Faça o trabalho

Implementar um design em código. Antes de escrever código, leia "Do design ao código" em references/tips.md: a maioria das diferenças que permanecem após uma primeira construção (cortes de imagem, fontes, deslocamentos de texto, largura da página) são abordadas lá. Escreva o código onde o usuário ou seu projeto diz que ele pertence (o caminho que eles nomeiam, ou a estrutura do próprio projeto); _swe/figma-access/ contém apenas artefatos de trabalho, como renders, arquivos de nó salvos, especificações, capturas de tela e scripts.

1. Renderize o quadro na escala 1 como referência, e leia-o em partes quando for alto.
2. Escreva a spec do quadro em um arquivo, com --origin no canto onde o conteúdo da página começa, e tire cada valor dele. Renderize imagens, e o que ela marca como ICON ou MASKED, em vez de reconstruí-los. Construa quadros de layout automático a partir da direção, espaçamento, preenchimento e dimensionamento que spec imprime, em vez de suas caixas armazenadas, e coloque os filhos de grupos e quadros sem layout automático em suas caixas. Não posicione cada nó absolutamente em sua caixa armazenada, manualmente ou com um gerador: essa página copia cada caixa obsoleta, quebra quando um texto fica mais longo e não consegue se adaptar à janela. Verifique cada parte marcada como LAYOUT DRIFT em relação ao render.
3. Liste as fontes com cada peso; procure no projeto pelos arquivos de qualquer família que não seja pública, e pergunte ao usuário, em uma mensagem, pelas que ainda faltam, e por qualquer outra coisa que você não possa obter do arquivo. Até que cheguem, ou quando você não puder perguntar, use um substituto e diga isso.
4. Deixe de fora o chrome do dispositivo ou navegador, e deixe a página se adaptar à janela: a largura do quadro é a tela para a qual foi desenhada, então fundos e divisores se estendem pela janela e a coluna de conteúdo é centralizada, a menos que o usuário peça uma largura fixa.
5. Construa seção por seção, então meça a página em relação à referência com figma-access compare <referencia.png> <pagina> --nodes <arquivo de nó> --wide <px>: ele captura a página, imprime os pixels diferentes por seção do quadro com o deslocamento que explica cada um, quão longe cada estilo de texto e nó está, e quais estão faltando, escreve uma imagem de diferença e verifica uma janela mais larga. Com --nodes ele pega as seções dos próprios filhos do quadro e recorta uma referência que a sombra do quadro alargou. Olhe também para a captura e a imagem de diferença, e repita até que cada seção corresponda. Quando o usuário pedir um resultado perfeito em pixels ou 1:1 e uma skill para isso estiver listada em sua sessão, use-a com esses renders como as imagens de design.

Alterar o arquivo. Através do plugin:

1. Escreva a alteração como código da API de Plugin e execute-o com figma-access exec, seguindo references/plugin-api.md para o que a API impõe e para posicionamento. Código longo vai em um arquivo de trabalho (por exemplo, em _swe/figma-access/) e é executado com exec -f. Sempre return os ids que você precisar em seguida; adicione --timeout 30s ou mais para trabalhos longos.
2. Para trabalhos que uma rotina de plugin pronta cobre (conjuntos de componentes, auditorias de lint e acessibilidade, preenchimentos de imagem, anotações, auxiliares de FigJam e Slides), use figma-access call <METODO> '<json>'; figma-access methods <filtro> lista os parâmetros.
3. Leia a saída toda vez: em ok #false, corrija a causa e remova o trabalho parcial antes de tentar novamente; em um warning sob resultAnalysis, verifique ids e nomes; para o próprio rastreamento do script, figma-access logs --since 2m.
4. Capture a tela de cada nó que você criou ou alterou (--scale 2 para pequenos) e verifique-o em relação à solicitação. Corrija e capture novamente; após três rodadas que ainda erram, diga ao usuário o que falta e por quê.

"Trabalhando através do plugin" em references/tips.md cobre o que geralmente dá errado aqui.

5. Relatório

Diga ao usuário o que você leu ou alterou, com nomes e ids de nós, e os caminhos dos renders, capturas de tela e arquivos que você escreveu. Nomeie qualquer coisa que você não fez, cada suposição que você fez (uma fonte substituta, uma camada oculta ignorada, chrome deixado de fora), e o que não foi verificado.

Solução de problemas

• "Limite de taxa excedido" (429): a CLI já esperou e tentou novamente. Siga "Limites de taxa e o cache" em references/tips.md, e aguarde um minuto antes da próxima leitura grande.
• Saída 3, nenhum arquivo conectado: o plugin não está em execução naquele arquivo, ou ainda está procurando (ele verifica a cada poucos segundos). Peça ao usuário para executá-lo novamente. figma-access daemon log mostra as conexões conforme acontecem.
• Outra ferramenta usa o mesmo plugin (como figma-console-mcp): ambas funcionam lado a lado; figma-access status mostra se este daemon tem o arquivo.
• Comportamento desatualizado após a skill ser atualizada: execute figma-access setup novamente, peça ao usuário para reimportar o manifesto no Figma, então execute figma-access daemon restart.
• "Plugin desconectado antes de responder": o usuário fechou o plugin ou o arquivo, ou o plugin foi recarregado. Verifique o arquivo antes de repetir a alteração.