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:
| Tarefa | Usar | Quando |
|---|---|---|
| Guarda de escala | scale-guard.md | Leia antes do passo 1 |
| Vincular a um sistema de design | figma-library-binding | Confirme no passo 1, use no passo 5 |
| Inventariar estados, encontrar lacunas | state-discovery | Passo 2 |
| Recriar telas a partir do código | code-to-figma | Passo 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:
- Confirme o acesso de leitura e escrita:
create_session, depois execute uma chamadause_figmasomente leitura (liste páginas e nós de nível superior). Se relatar "could not access the requested file", usewhoamipara 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) - 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
slotIdpara__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:
- 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_systeme 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.
- 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.
- 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:
- Capture: siga web-capture.md passos 1–3 com
shotOnly: truena configuração. Ele escreveshot/<ID>.jpgem 2x e pula a árvore de layout. Leiastats.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 - 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
- Envie: chame
upload_assetscomnodeIdsdefinido como osslotIds 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. Seupload_assetsnão preencher os slots, chame-o comcurrentPageIdecount; 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 - Execute screenshot-slots.js com
SECTION_IDsubstituído, na mesma chamadause_figmaque audit.js (passo 6): envolva cada um em uma função async, chame-os em ordem, entãoawait 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 retornaplaced,missingeskipped. Envie novamente para os cartões emmissing - 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
- Execute ambos os scripts de auditoria, substituindo
SECTION_IDpela seção alvo. Cole ambos na mesma chamadause_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.