Communitygithub.com

figma-state-board

Inventarie cada estado da UI de uma funcionalidade a partir do código e organize-os em uma tela do Figma (state board) — telas reais para estados que o protótipo já trata, mais uma verificação de lacunas de estados de erro, vazio e carregamento ausentes, divididos entre exigidos pela especificação e sugeridos. Use quando o usuário pedir um "state board", "todos os estados desta funcionalidade no Figma", "quais telas de erro estão faltando" ou para atualizar um board existente.

O que é figma-state-board?

Este skill, `figma-state-board`, é uma ferramenta especializada para agentes de IA que trabalham com design e desenvolvimento de produtos. Ele automatiza o processo de inventariar todos os estados de interface do usuário (UI) de uma funcionalidade a partir do código-fonte de um projeto e organizá-los visualmente em um quadro (state board) dentro do Figma. A principal utilidade é fornecer uma visão única e compartilhada de todos os estados que uma funcionalidade pode assumir, incluindo estados que o protótipo atual já implementa (exibidos como telas reais) e estados ausentes (listados em uma seção de "verificação de lacunas"). Estes estados ausentes são categorizados como "na especificação" (exigidos pelo Product Owner, mas não implementados) ou "sugeridos" (estados de erro, vazio e carregamento que não foram especificados nem implementados). O skill é compatível com qualquer stack de tecnologia e produto, e é ativado por comandos como "state board" ou "todos os estados desta funcionalidade no Figma". Ele funciona como o orquestrador de um fluxo de trabalho maior, delegando tarefas específicas a outros skills, como `state-discovery` (para inventariar estados e encontrar lacunas) e `code-to-figma` (para reconstruir telas a partir do código). O processo segue etapas claras: confirmação de entradas (repositório, especificações, arquivo Figma alvo), inventário de estados com um script que gera a matriz, preparação de dados para cada cartão, construção do esqueleto do board no Figma, e finalmente, a inserção de telas reais ou wireframes. O skill também gerencia orçamento de chamadas da API do Figma e oferece rotas alternativas (como o uso de screenshots de navegador) para planos com limitações de chamadas. O resultado é um board Figma completo, com seções de verificação de lacunas, que serve como uma única fonte da verdade para designers, engenheiros, QA e gerentes de produto.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/byby325/code-to-figma-ui-states/tree/HEAD/skills/figma-state-board

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Figma State Board

Um state board é uma seção do Figma que organiza todos os estados que uma funcionalidade pode ter em uma única tela. Os grupos são divididos por dispositivo, aba ou tópico. Cada cartão possui "ID · nome", "gatilho; resultado" e uma tela do produto. O último grupo, Verificação de lacunas (em zh-TW: 缺漏檢查), lista estados que o protótipo ainda não possui, mas a funcionalidade deveria ter. Designers, engenheiros, QA e gerentes de produto o utilizam como sua lista compartilhada de estados.

O código do projeto geralmente é um protótipo construído com dados mockados, não conectado a um backend real. Portanto, não divida os estados em "implementado / não implementado ainda". Faça apenas uma pergunta: o protótipo constrói este estado? Os cartões têm apenas três tags:

  • Protótipo (em zh-TW: 原型): o protótipo possui este ramo. Desenhe a tela real; sem rótulo de tag
  • Na especificação (em zh-TW: 規格有寫): mencionado nos critérios de aceitação, especificações, mockups ou texto de i18n não utilizado, mas o protótipo não o constrói. Vai para a verificação de lacunas
  • Sugerido (em zh-TW: 建議補): nem a especificação nem o protótipo o mencionam; inferido a partir de evidências do código ou do tipo de funcionalidade. Vai para a verificação de lacunas

Funciona para qualquer stack e qualquer produto. board-format.md é a fonte da verdade para a especificação do board.

Idioma. Escreva a matriz, nomes dos cartões, descrições, texto dos wireframes e o relatório no idioma do usuário. Os rótulos fixos do board (tags, Verificação de lacunas, resumo de cobertura, cabeçalhos de wireframe, nomes de camadas) vêm de BOARD.lang: 'zh-TW' quando o usuário trabalha em Chinês Tradicional, 'en' caso contrário. Outros idiomas mantêm os rótulos em inglês com o texto do cartão no idioma do usuário.

Este skill é responsável pelo fluxo geral, pelo board e pela auditoria. Outros trabalhos vão para outros skills no mesmo plugin:

TarefaUsarQuando
Guarda de escalascale-guard.mdLeia antes do passo 1
Vincular a um sistema de designfigma-library-bindingConfirme no passo 1, use no passo 5
Inventariar estados, encontrar lacunasstate-discoveryPasso 2
Recriar telas a partir do códigocode-to-figmaPasso 5, na Rota B

Arquivos próprios deste skill:

  • board-format.md: layout do board, tamanhos de fonte, tags e regras de ID dos cartões. Leia antes de desenhar qualquer coisa
  • board-skeleton.js: constrói o esqueleto do board e os wireframes de lacunas a partir da matriz. Usado no passo 4
  • screenshot-slots.js: encaixa screenshots de navegador enviados nos cartões. Usado no passo 5 na Rota C
  • audit.js: auditoria do board. Usado no passo 6

Se o projeto tiver seu próprio skill de regras de UI (por exemplo, o skill de diretrizes de UI do projeto), siga-o para tokens de tela do produto, nomenclatura e aceitação.

Passos

1. Confirmar as entradas

Peça qualquer item ausente:

  • Fonte do código: repositório, branch, ponto de entrada da funcionalidade (rota, página, tela ou componente)
  • Fonte das regras: AC do Jira, PRD, Confluence, documentação de códigos de erro. Se não houver, escreva "Nenhum"; a verificação de lacunas terá mais cartões
  • Alvo: arquivo e página do Figma; uma nova seção, ou uma atualização de um state board existente. Para boards de prática, ou boards para compartilhar com outros, use o arquivo de prática compartilhado da equipe (regras em board-format.md "Arquivo de prática compartilhada"). Se o alvo for um arquivo existente, peça também ao usuário que informe o uso atual de memória (scale-guard.md)
  • Dimensões: os eixos ao longo dos quais os estados variam (largura do dispositivo, estado de login, função, aba, volume de dados, sequência de interação...), e a largura da viewport para cada dispositivo
  • Fonte da tela do produto: componentes no arquivo alvo ou em uma biblioteca, ou um protótipo em execução / servidor de desenvolvimento. Se não houver, você só pode desenhar wireframes; informe isso antecipadamente
  • Biblioteca do sistema de design: quais bibliotecas as telas do produto devem vincular (figma-library-binding). Se nenhuma, escreva "Nenhum"

Assim que tiver o link do Figma, faça duas coisas primeiro. Não espere o inventário ficar pronto para descobrir que não consegue desenhar no arquivo:

  1. Confirme o acesso de leitura e escrita: create_session, depois execute uma chamada use_figma somente leitura (liste páginas e nós de nível superior). Se relatar "could not access the requested file", use whoami para ver em qual conta o MCP está logado, e dê ao usuário duas opções: compartilhar o arquivo com essa conta com permissão de edição, ou fazer login com uma conta que tenha acesso nas configurações do conector (após a troca, os arquivos da conta original não poderão ser abertos)
  2. Estime o orçamento de chamadas: siga scale-guard.md "Orçamento de chamadas MCP" para estimar quantas chamadas esta execução precisa, e compare com os seats do plano do arquivo alvo em whoami. Se não for suficiente, informe primeiro e deixe o usuário escolher: Rota C (screenshots do navegador nos cartões, cerca de 3 chamadas para todo o board; passo 5), dividir em lotes, trocar de arquivos, ou fazer menos comparações

Pronto quando: todos os seis itens têm um valor claro, ou o usuário disse explicitamente que não se aplicam; o arquivo alvo é legível; o orçamento de chamadas é suficiente, ou o usuário escolheu como dividir o trabalho.

2. Inventariar estados e construir a matriz de estados

Construa a matriz com state-discovery. Atribua IDs aos cartões antecipadamente, seguindo as regras em board-format.md.

Não desenhe até que o usuário tenha confirmado a matriz. Como os grupos são divididos, quais cartões mesclar e quais cartões Sugeridos manter são decididos nesta etapa; alterá-los depois de desenhar custa muito mais. Se houver mais de 150 cartões de Protótipo, siga scale-guard.md e peça ao usuário para decidir se deseja mesclar cartões, dividir páginas ou dividir arquivos. Não desenhe até que eles decidam.

3. Preparar dados para cada cartão

  • Protótipo: reproduza-o com dados mockados fixos ou uma história do Storybook. Adicione dados ausentes na camada de mock; não adicione branches a componentes apenas para screenshots.
  • Na especificação, Sugerido: o protótipo não tem tela, então nenhum dado é necessário; desenhe um wireframe. Para cartões Na especificação, escreva no wireframe o que a especificação requer e onde ela diz isso.

Pronto quando: cada cartão de Protótipo tem dados reproduzíveis, ou está claramente marcado como "Ilustrativo apenas no Figma".

4. Construir o esqueleto do board

Primeiro, carregue os dois skills do plugin Figma, figma-use e figma-generate-design (no Claude Code: figma:figma-use / figma:figma-generate-design; sem o plugin Figma, use get_figma_skill para ler skill://figma/figma-use/SKILL.md e assim por diante, com um prefixo resource: em skillNames).

Se o alvo for um arquivo existente, peça ao usuário para salvar uma versão antes de escrever. O mesmo se aplica antes de excluir ou reconstruir cartões que você mesmo construiu. Se a página alvo não tiver nada além do que você construiu (um arquivo novo, uma página em branco), você pode pular a gravação; informe isso no relatório.

Para um novo state board, use board-skeleton.js: preencha a matriz confirmada no passo 2 em BOARD no topo, e cole o script inteiro em uma chamada use_figma. Seguindo board-format.md, ele constrói a seção (nomeada "-", posicionada à direita do conteúdo existente na página) → título do board, subtítulo, resumo de cobertura (calculado automaticamente) → grupos → Cenários → cartões. O último grupo é a verificação de lacunas, com seus wireframes desenhados. As telas dos cartões de Protótipo começam como slots placeholder com placeholder = true; o script retorna o slotId de cada cartão, que você passa ao construir telas no passo 5. Em um arquivo compartilhado, use uma página por funcionalidade e defina BOARD.pageName como o nome da página. Defina BOARD.lang conforme "Idioma" acima, e a tag de cada cartão de lacuna como 'spec' (Na especificação) ou 'suggested' (Sugerido).

Ao atualizar um state board existente, não execute o script de esqueleto. Use estas regras:

  • Releia o nó alvo antes de cada mutação; o designer pode ter movido ou dividido coisas manualmente
  • Altere apenas os cartões afetados. Mantenha seus IDs; novos cartões continuam após o último número em seu grupo
  • Quando o protótipo construir o estado de um cartão da verificação de lacunas, mova o cartão para o grupo ao qual pertence, remova a tag, dê a ele um novo ID e anote o ID G antigo na descrição
  • Recalcule os números no resumo de cobertura
  • Mantenha o idioma existente do board para os rótulos que você adicionar, mesmo que o usuário agora escreva em outro idioma; um board com rótulos mistos é difícil de ler
  • Não toque na área de notas do designer à direita ou na seção de Feedback

Pronto quando: cada cartão de Protótipo tem um slot placeholder e um slotId; todos os wireframes da verificação de lacunas estão desenhados.

5. Construir as telas no Figma

Use use_figma para construir camadas nativas e colocá-las nos slots placeholder do passo 4. send_code_to_figma importa uma camada de Código e não produz camadas de Design editáveis, então não funciona para state boards.

Na Rota B, siga code-to-figma "Regras rígidas para escrever no Figma" e envie apenas uma tela por vez. Com mais de 100 cartões de Protótipo ou mais de 20 imagens únicas, peça ao usuário para informar o uso de memória após cada grupo, seguindo scale-guard.md. Se você atingir uma condição de parada do scale-guard.md enquanto escreve (incluindo limite de chamadas atingido), pare e não tente novamente.

Escolha uma rota primeiro e confirme com o usuário:

  • Rota A: copiar os mockups (padrão). Use quando o arquivo alvo ou biblioteca tiver telas mockup completas. Você pode vincular variáveis e manter o Auto Layout.
  • Rota B: recriar a partir do código do projeto. Use quando o arquivo alvo não tiver mockups para copiar, ou quando o usuário pedir para recriar a partir do código em vez de colar mockups. Siga code-to-figma e passe slotId para __alBuild; a tela do produto vai para o slot placeholder do cartão. Atualmente apenas para front-ends Web.
  • Rota C: screenshots do navegador. Cada cartão de Protótipo mostra uma screenshot do aplicativo em execução; nada é recriado. Todo o board leva cerca de 3 chamadas contadas, independentemente de quantos cartões tiver, então ofereça-a quando o orçamento de chamadas não puder cobrir a Rota B (planos Starter, seats de Visualização e Colaboração), ou quando o usuário precisar apenas da lista de estados e da verificação de lacunas. As telas são imagens, não camadas editáveis; informe isso ao oferecer e novamente no relatório. Apenas front-ends Web. As etapas estão abaixo em "Rota C".

Nas Rotas A e B, as telas do produto devem seguir screen-structure.md: frame raiz da tela Largura Fixa = W; Auto Layout para containers cujos filhos são organizados; sem Grupos; UI repetida como componentes (variantes para diferentes estados); containers de carrossel cortam e nunca são Hug; texto longo Fill + altura automática. Cartões da verificação de lacunas (Na especificação, Sugerido) seguem a especificação de wireframe em board-format.md; não desenhe UI de produto falsa.

Passos 1–3 abaixo são para a Rota A:

  1. Encontre telas e componentes: se o arquivo alvo já tiver telas mockup completas, prefira copiá-las e alterar o estado (alternar variantes, ocultar camadas); isso é o mais próximo do produto. Em seguida, use search_design_system e componentes locais. Somente se nenhum existir, construa camadas locais a partir da estrutura e estilos do código. Vincule cores, tamanhos de fonte e espaçamento às variáveis do projeto. Onde os mockups e o código discordarem, siga o código e anote na descrição.
    • Se a fonte do produto não puder ser carregada no runtime do Figma (por exemplo Arial), não altere texto existente. Para novo texto, use uma fonte com larguras compatíveis (Arial → Arimo) e liste onde você a usou no relatório.
  2. Construa uma tela representativa por dispositivo primeiro e compare sua screenshot com o protótipo ou a tela ao vivo: prossiga somente quando texto, espaçamento, raio de canto e tokens estiverem todos corretos. Se não houver nada para comparar, informe no relatório que essas telas não foram comparadas.
  3. Gere os cartões de Protótipo restantes a partir da tela representativa por clone ou instância mais sobrescritas, alterando apenas o que difere neste estado.

Rota C:

  1. Capture: siga web-capture.md passos 1–3 com shotOnly: true na configuração. Ele escreve shot/<ID>.jpg em 2x e pula a árvore de layout. Leia stats.json: um aviso sobre 4096px significa que a tela é muito longa para uma imagem; capture-a como vários cartões de altura de viewport
  2. Olhe para cada screenshot localmente antes de enviar. Esta é a etapa de comparação na Rota C: um estado errado, um spinner que nunca terminou ou uma barra de desenvolvedor deixada no print não custa nada para corrigir aqui
  3. Envie: chame upload_assets com nodeIds definido como os slotIds dos cartões em ordem de cartão (no máximo 60 por chamada). Escreva os submitUrls em um arquivo, um por linha, e envie as screenshots na mesma ordem: python3 al-upload.py urls.txt capture/shot/C01.jpg capture/shot/C02.jpg. Se upload_assets não preencher os slots, chame-o com currentPageId e count; as screenshots caem na página como camadas nomeadas <ID>.jpg, e o próximo passo as move para seus cartões. Não renomeie os arquivos
  4. Execute screenshot-slots.js com SECTION_ID substituído, na mesma chamada use_figma que audit.js (passo 6): envolva cada um em uma função async, chame-os em ordem, então await section.screenshot() na seção do board antes de retornar ambos os resultados, para que a imagem do board retorne com a mesma chamada. Ele redimensiona cada slot para sua screenshot e retorna placed, missing e skipped. Envie novamente para os cartões em missing
  5. Para transformar um cartão de screenshot em camadas editáveis mais tarde, recrie esse cartão com a Rota B e passe o mesmo slotId; a recriação substitui a imagem

Pronto quando: você olhou para uma screenshot da tela representativa de cada dispositivo, e ela corresponde ao protótipo, ou você observou que não havia nada para comparar. A Rota B também deve atender aos critérios de conclusão em code-to-figma. Na Rota C, cada cartão de Protótipo está em placed, ou o relatório lista os que não estão.

6. Auditoria

  1. Execute ambos os scripts de auditoria, substituindo SECTION_ID pela seção alvo. Cole ambos na mesma chamada use_figma (envolva cada um em uma função async, chame-os em ordem e retorne ambos os resultados) para economizar uma chamada do orçamento:
    • audit.js: o board. Se os grupos têm título e descrição, IDs de cartão duplicados, se os cartões de carrossel...

[truncado para tradução]

7. Relatório e conclusão

Após a auditoria, escreva um resumo no chat: localize cada problema encontrado pelos scripts de auditoria e sugira ações. Se a auditoria não encontrou nenhum problema, informe. Liste também quaisquer telas que não foram comparadas com o protótipo (Rota A, Rota B) ou cartões que não foram colocados (Rota C).

Se houver cartões na verificação de lacunas, liste-os com seus IDs e tags (Na especificação ou Sugerido).

Por fim, pergunte se o usuário deseja fazer ajustes manuais no board ou se está satisfeito.

Pronto quando: o relatório é entregue e o usuário confirmou que o board está completo.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

code-to-figma

Rebuild screens from a running web app as native, editable Figma layers (Auto Layout, components, instances) and diff them against browser screenshots — not a screenshot import or a Code layer. Use when the user asks to "turn this page into Figma", "code to Figma", "push this screen to Figma" or "rebuild the UI in Figma". 把 Web 專案實際跑出來的畫面重建成 Figma 原生圖層:造狀態、抽 DOM 版面樹,建 Auto Layout 和 component/instance,再跟瀏覽器截圖比對。單一畫面或一批畫面都能用,不需要做情境稿。Use when 使用者要「code to figma」「把這頁轉成 Figma」「從程式重建畫面」「push 畫面到 Figma」,或 figma-state-board 走路線 B。產出是可編輯圖層,不是 Code layer 或截圖。

figma-library-binding

Bind Figma screens to a design system library — tokens only on exact value matches, swap icons and components for library versions, and list unmatched values for designers instead of snapping to the nearest token. Use when the user asks to "bind tokens", "use library components" or "find unbound colors". 把 Figma 畫面綁到專案的 design system library:顏色、圓角、邊框、間距、字級完全相同才綁 token,圖示和元件換成 library 版本,沒有對應的值列給設計決定,不取最近值。Use when 使用者要「綁 library」「綁 token」「換成 design system 元件」「檢查沒綁 variable 的顏色」,或 code-to-figma、figma-state-board 的畫面要綁 design system。

Habilidades Relacionadas