nikbearbrown/figma-appdesigner

Ideia de app → Telas no Figma → Livro-razão de decisões

Propósito

Transformar a descrição de um aplicativo feita por uma pessoa em: (1) um resumo escrito, (2) um mapa de telas, (3) wireframes e telas estilizadas no Figma, desenhados com variáveis de cor e tipo para que uma tela possa ser exibida em qualquer um dos quatro conjuntos de cores padrão, (4) um registro de cada alteração solicitada pela pessoa, em suas próprias palavras, (5) resultados da medição do desenho em relação a um livro de regras, (6) registros de decisões e aprovações humanas e (7) briefs de construção para designs aprovados. O diretório de design versionado em git é a fonte da verdade. O Figma é uma projeção dele. Esta skill projeta e registra; ela nunca escreve código de aplicativo.

Ela é irmã da figma-webdesigner. Essa skill começa a partir de um site existente e o audita. Esta começa do nada, apenas com o que a pessoa diz. Elas compartilham os conjuntos de cores (palettes/palettes.json), o formato do livro-razão e o comando de aprovação.

Como uma sessão funciona

A pessoa fala; Claude desenha. Uma iteração é uma das quatro coisas a seguir:

• Um fato sobre o aplicativo ("é para trilheiros, funciona offline"). Vai para o resumo.
• Uma solicitação ("aumente o botão adicionar", "mova a pesquisa para o topo", "mostre isso nas cores Northeastern"). Claude registra as palavras, faz a alteração no Figma e informa o que mudou.
• Uma pergunta ("esse botão é grande o suficiente?"). Claude mede e responde com o número e a regra.
• Uma decisão ("sim, construa este"). Apenas uma pessoa pode tomá-la, e somente com fad approve em seu próprio terminal.

Faça uma ou duas perguntas de cada vez. Desenhe cedo: um wireframe errado que a pessoa possa apontar vale mais do que uma longa entrevista.

Comandos

A pasta da skill contém um comando, fad, e um CLAUDE.md que diz como respondê-lo.

• help executa fad help (verificações de configuração mais um próximo passo) e, com as ferramentas Figma presentes, whoami para o usuário.
• tutorial executa o primeiro tutorial de sete etapas (projete a primeira tela do seu app). São as próprias fases desta skill, guiadas passo a passo.
• fad tutorials [name] lista os tutoriais prontos para aplicativos comuns (to-do, weather, chat) ou exibe um. fad init "<nome>" --tutorial to-do inicia uma pasta de design com o resumo de exemplo e as telas propostas desse tutorial. Veja Tutoriais para aplicativos comuns.
• fad init "<nome do app>" inicia uma pasta de design. --platform ios|android|both, --palette <id>.
• fad palettes [id] lista os quatro conjuntos de cores padrão ou exibe um com suas funções e contraste calculado. --json para um script. --figma exibe o script Figma pronto para ser executado que cria as variáveis de cor.
• fad devices exibe os tamanhos de tela, áreas seguras e menores alvos de toque para os quais os designs são desenhados.
• fad screens exibe o mapa de telas e o verifica (uma tela inicial, nada inacessível, nenhum link para uma tela que não existe).
• fad templates [kind] lista modelos e kits de design com licença aberta para tipos comuns de aplicativo, com a licença de cada um e o crédito a ser dado. --credits exibe a lista completa de créditos.
• fad approve|reject|defer <D-id> é executado pela pessoa, em seu próprio terminal. Inegociável 1 se aplica.
• fad ledger verify verifica a cadeia de hash e se cada arquivo de aprovação corresponde ao livro-razão.

Inegociáveis

1. Apenas um humano pode definir uma decisão como aprovada, rejeitada ou adiada, ou reabri-la. Nunca escreva esses estados. Nunca escreva arquivos em design/approvals/. Nunca execute fad approve, reject ou defer.
2. Cada constatação cita um rule_id de design/rulebook/rules.yaml. Sem regra, sem constatação: registre-a como uma observation para o humano.
3. Os rótulos das constatações seguem a camada da regra: normativa → failure, heurística → concern, interna → deviation. As diretrizes da Apple e do Google são da camada heurística: um botão de 40 pontos no iOS é uma preocupação, não uma falha. Nunca use ícones ou palavras de aprovação/reprovação em constatações heurísticas.
4. Registre uma solicitação antes de agir sobre ela: um evento de livro-razão request.made com as palavras da pessoa, na íntegra, e qual tela. Em seguida, o recibo figma.write. O registro é o que permite que alguém pergunte posteriormente por que o botão foi movido.
5. Uma solicitação que quebra uma regra ainda é da pessoa para fazer. Informe qual regra e por quanto, ofereça a versão mais próxima que passa e desenhe o que eles escolherem. Se mantiverem a versão que quebra a regra, escreva a constatação; ela acompanha o registro de decisão. Não "corrija" silenciosamente o que foi solicitado e não recuse.
6. Toda cor em uma tela é uma variável Palette e toda família de fontes é uma variável type/. Nenhum hex solto em um nó de tela. Os valores vêm de fad palettes, nunca da memória.
7. Nunca modifique ou exclua nós que a skill não criou. Encontre seus próprios nós pelos IDs de nó registrados no livro-razão, nunca pelo nome da camada, cor ou texto.
8. Nunca defina o status do Modo Dev (Pronto para dev / Concluído). Nunca resolva ou exclua comentários humanos.
9. Desenhe apenas em um arquivo Figma que esta skill criou para este aplicativo ou em um arquivo que a pessoa nomeou depois de salvar uma versão de base dele e fornecer seu ID. Um arquivo criado pela execução começa vazio e é sua própria linha de base; registre isso em capabilities.json.
10. Nunca escreva código de aplicativo. A construção acontece apenas em uma sessão separada do Claude Code ou Codex, a partir de um brief de transferência para uma decisão aprovada.
11. Nunca coloque o logotipo, nome ou marca registrada de uma organização real em uma tela, a menos que a pessoa o forneça e diga que pode usá-lo. O conjunto de cores Northeastern é uma paleta publicada, não uma permissão para usar as marcas da universidade.
12. Nunca copie as telas de um modelo ou de outro aplicativo. Um modelo (veja Modelos) é algo para ler em busca de estrutura e construir a partir dele sob sua licença, com crédito registrado no resumo; qualquer coisa sem licença aberta é apenas para olhar.
13. Desenhe cada tela com seus estados. Uma tela que carrega ou lista coisas tem default, empty, loading e error desenhados antes de ser proposta (regra HOUSE-STATES).

Estrutura de diretórios

design/
  brief.yaml                  # preenchido pelo humano (Fase 0)
  rulebook/rules.yaml         # confirmado pelo humano (Fase 1)
  screens.json                # o mapa de telas (Fase 2)
  capabilities.json           # o que esta execução realmente pode fazer
  checks/R-YYYYMMDD-NN/       # medições do desenho: checks.json, findings.json, PNGs exportados
  decisions/D-NNNN.json
  approvals/A-NNNN.json       # apenas humanos
  handoff/                    # briefs de construção, apenas decisões aprovadas
    README.md                 # regras compartilhadas para o construtor
    D-NNNN.md                 # um brief por decisão aprovada
  ledger.jsonl                # eventos anexados com cadeia de hash

fad init coloca isso em ~/figma-appdesigner-work/<app>/design/ e torna ~/figma-appdesigner-work/<app>/ um repositório git, para que as aprovações possam ser commitadas. Ele não commita nada.

Fase 0 — Resumo (Gate G0)

Se design/brief.yaml estiver faltando ou tiver campos obrigatórios vazios, pergunte pelos campos ausentes de forma conversacional, um ou dois de cada vez. Não desenhe nada até que todos os campos obrigatórios sejam preenchidos pela pessoa.

app_name: ""                  # obrigatório: um nome de trabalho é suficiente
one_line: ""                  # obrigatório: o que faz, para quem, em uma frase
people: []                    # obrigatório: quem usa
top_tasks: []                 # obrigatório: as três coisas que uma pessoa deve ser capaz de fazer
platform: ios                 # obrigatório: ios, android ou both
palette: bear-brown           # obrigatório: bear-brown, brutalist, northeastern, humanitarians
dark_mode: false              # também desenhar o modo escuro da paleta, onde houver
implementer: ""               # obrigatório: "claude-code" ou "codex"
stack: undecided              # swiftui, compose, react-native, flutter ou undecided
approvers: []                 # obrigatório: nomes e funções
conformance_target: "WCAG 2.2 AA"
existing_app: none            # caminho para um repositório se estiver redesenando um app existente
figma_file: ""                # em branco até o arquivo ser criado
out_of_scope: []

Bons top_tasks são coisas que uma pessoa faz ("escrever uma nota sem sinal"), não recursos ("sincronização offline"). Se a pessoa fornecer recursos, pergunte o que alguém está tentando realizar.

Fase 1 — Livro de regras (Gate G1)

Resuma o livro de regras (contagem de regras por camada e modo). Peça à pessoa para confirmar ou editar. O iniciador nomeia suas fontes para que possam ser abertas; diga que as entradas da Apple e do Material são nomeadas, não linkadas, e devem ser confirmadas em relação às diretrizes atuais. Registre um evento de livro-razão schema.confirmed com o nome da pessoa e a data. Não prossiga sem ele.

Sonda de capacidade em tempo de execução

Antes da primeira gravação no Figma, escreva capabilities.json:

• Quais ferramentas Figma MCP estão presentes (use_figma, create_new_file, create_session, get_screenshot, get_metadata, generate_diagram, get_libraries, search_design_system).
• whoami: o plano e o usuário que possuirão o arquivo. Um usuário somente visualização não pode desenhar: defina mode: json-only, informe e pare antes da Fase 3. Com mais de um plano, use aquele com um usuário Full; se dois tiverem um, pergunte.
• Carregue a skill figma-use do Figma antes de qualquer chamada use_figma, e figma-create-new-file antes de create_new_file. Para as variáveis, carregue figma-generate-library; para telas, carregue figma-generate-design. Passe os nomes das skills Figma que você está seguindo em skillNames.
• Chame create_session assim que a chave do arquivo for conhecida e passe seu sessionId em todas as chamadas de arquivo posteriores.
• Conhecido desde a primeira execução (2026-11-10, plano educacional, camada estudante, usuário Full). Re-verifique em vez de presumir:
  • Uma coleção de variáveis aceitou oito modos (os quatro conjuntos de cores, três deles com modo escuro e o modo cinza Wireframe).
  • Uma variável STRING com escopo FONT_FAMILY, vinculada ao fontFamily de um nó de texto, alterna a tipografia com o modo. Cada família em cada modo deve ser carregada primeiro.
  • EB Garamond, Inter e Lato tinham cada uma Regular, Medium e Bold. Lato não tem "Semi Bold". Use apenas esses três pesos para que um nó de texto funcione em todos os modos.
  • frame.setExplicitVariableModeForCollection(collection, modeId) recolor e retipografa tudo dentro do quadro, incluindo instâncias de componentes.
  • Um componente na página do kit pode ser instanciado em outra página na mesma chamada: busque-o com figma.getNodeByIdAsync(id) e chame createInstance().
  • Uma camada de texto em um quadro de layout automático com maxWidth definido e textAutoResize = 'WIDTH_AND_HEIGHT' abraça uma linha curta e quebra uma longa (as bolhas de chat).
  • Da primeira execução de figma-webdesigner: figma.saveVersionHistoryAsync não é suportado (a pessoa salva versões), figma.root.name não pode ser definido (nomeie o arquivo ao criá-lo), anotações funcionam.
• Se o plano recusar um segundo modo (modeErrors no recibo do script), use apenas o modo claro do conjunto de cores escolhido e registre modes: 1.

Nomeie o arquivo Figma para o aplicativo ao chamar create_new_file; ele não pode ser renomeado depois.

Cores

As telas são desenhadas em um dos quatro conjuntos de cores padrão. Eles estão em palettes/palettes.json, cada um lido do site para o qual é nomeado (o arquivo registra a página e a data). figma-webdesigner entrega o mesmo arquivo.

id	Nome	Lido de	Modos	Tipo
bear-brown (padrão)	Bear Brown	bearbrown.co	light, dark	EB Garamond, Inter
brutalist	Brutalist	brutalist.art	light, dark	Inter
northeastern	Northeastern	brand.northeastern.edu, a página de cores	light	Lato
humanitarians	Humanitarians AI	humanitarians.ai	light, dark	Inter

Cada conjunto preenche as mesmas sete funções: ground, surface, ink, ink-soft, border, accent, on-accent.

1. Pergunte, não presuma. Na Fase 0, mostre os quatro (fad palettes) e pergunte qual. Sem resposta, use o padrão e informe.
2. Obtenha os valores do comando. fad palettes --figma exibe figma/palette-variables.js com as cores preenchidas. Execute esse script; não digite um valor hex.
3. Coloque todos os quatro no arquivo. O script cria uma coleção Palette com um modo para cada conjunto de cores e seu modo escuro, além de um modo cinza Wireframe, para que a pessoa possa pedir para ver qualquer tela em outro conjunto sem redesenhar: defina o modo do quadro. A palette do resumo é o modo no qual as telas são desenhadas por padrão. O primeiro modo (padrão do Figma) é sempre um conjunto de cores real; Wireframe é o último.
4. Relate os pares baixos. fad palettes <id> marca qualquer par de texto ou controle abaixo do mínimo WCAG como LOW. Informe à pessoa quais são baixos em seu conjunto e nunca coloque texto em um par baixo. Hoje existem dois: o texto secundário do Brutalist em sua superfície slate (4,34:1) e o vermelho do modo escuro do Humanitarians contra seu fundo escuro (2,47:1).
5. Uma ação principal por tela leva o acento (HOUSE-ONE-MAIN-ACTION). Acento não é decoração.
6. Uma cor própria da pessoa ("nossa marca é teal") é um novo modo de variável que eles nomeiam, adicionado à coleção Palette do arquivo com todas as sete funções preenchidas e seu contraste calculado da mesma forma antes de ser usado. Não edite os quatro conjuntos padrão.

Dispositivos

fad devices exibe o que starter/devices.json contém: um quadro iPhone de 390 × 844 pt e um quadro Android de 412 × 915 dp, cada um com uma área segura e um menor alvo de toque (44 pt, Diretrizes de Interface Humana da Apple; 48 dp, Material Design 3). Estes são pontos de partida para desenho. Informe isso ao usá-los e diga à pessoa para verificá-los em um dispositivo real antes de construir. platform no resumo decide quais são desenhados; both desenha cada tela duas vezes.

Convenções de script use_figma

Todo script que esta skill envia através de use_figma segue as regras do figma-use do Figma e estas:

1. Fontes primeiro. Carregue cada família e peso que qualquer modo pode exibir (Promise.all no topo) antes de criar ou editar texto. Um nó de texto vinculado a type/heading precisa de todas as famílias dessa variável carregadas.
2. Layout automático para tudo com filhos. figma.createAutoLayout(), anexe o filho e defina layoutSizingHorizontal/Vertical. resize() antes dos modos de dimensionamento.
3. Vincule, não pinte. Preenchimentos, traços e cores de texto através de variáveis, não hex. Um retângulo que é a cor de fundo de uma tela tem seu fills[0] vinculado a Palette.ground.
4. Componentes da página do kit. Colete componentes (barra de status, navegação inferior, alvos de toque) em uma página /KIT criada antes da primeira tela. O script cria cada um, o nomeia e o chama de Kit no arquivo. Uma página /SCREENS contém as telas do aplicativo. Uma página /DRAFT contém esboços, explorações e o que não está em uma tela.
5. figma.createComponent(), não figma.createFrame(), salvo se uma tela precisar de um grupo que nunca será reutilizado.
6. Uma tela é uma página (ou duas, se platform: both). Uma página /SCREENS/<nome da tela> com cada estado em um quadro IMG (default, empty, loading, error). Os quadros são nomeados <nome da tela> / <estado>. Quando você criar a tela no Figma pela primeira vez, nomeie o nó Frame com <nome da tela> / default.
7. Uma regra por encontro. Uma medição de verificação verifica uma regra de uma só vez. Uma chamada use_figma que att tamanhos de alvos de toque e cores (2 regras) está errada.
8. Anotações. Adicione como comentários do Figma anexados ao nó de tela (figma.comment). Cada comentário cita o rule_id.
9. Aceite crédito. Para um modelo, adicione uma anotação ao nó de tela: "Este design usa [nome do modelo] por [autor], licenciado sob [licença]."

Modelos

Modelos e kits de design com licença aberta são mantidos em starter/templates.yaml. Use fad templates para listar e buscar. Eles vêm de Dribbble (licenciado MIT), open-ui (licenciado MIT), Untitled UI (licenciado CC BY 4.0) e Lucide (licenciado ISC). Cada entrada em templates.yaml especifica a licença e o crédito a ser dado. Sempre dê crédito e nunca copie o design de um modelo exatamente; construa a partir de sua estrutura sob sua licença.

Tutoriais para aplicativos comuns

Tutoriais estão em starter/tutorials/<nome>.yaml. Eles fornecem um resumo de exemplo e telas propostas, com instruções para cada fase. Use fad init "<nome do app>" --tutorial to-do para iniciar um projeto de design de exemplo. Os tutoriais incluídos são:

• to-do: Um aplicativo de lista de tarefas com telas de lista, de detalhes e de adição.
• weather: Um aplicativo meteorológico com tela de clima atual e tela de previsão.
• chat: Um aplicativo de chat com tela de conversas e tela de conversa.

Gerenciamento de decisões

As decisões são registradas em design/decisions/ como D-NNNN.json. Cada decisão contém um estado (proposed, approved, rejected, deferred) e referências às telas e constatações relevantes. Apenas um humano pode alterar o estado de uma decisão usando fad approve|reject|defer <D-id>. O livro-razão (design/ledger.jsonl) registra cada evento com uma cadeia de hash para verificação.

Handoff

Quando uma decisão é aprovada, um brief de construção é gerado em design/handoff/D-NNNN.md. Este brief inclui:

• O resumo do aplicativo
• O mapa de telas com descrições
• As regras de design aplicáveis
• As variáveis de cor e tipo usadas
• Quaisquer constatações não resolvidas
• O alvo de conformidade (WCAG 2.2 AA)

Verificação do livro-razão

fad ledger verify verifica:

• Que cada evento em ledger.jsonl tem um hash válido
• Que a cadeia de hash é contínua
• Que cada arquivo de aprovação em design/approvals/ corresponde a um evento de aprovação no livro-razão

Fases de design

Fase 0 — Resumo

O resumo é preenchido pelo humano através de conversa. Todos os campos obrigatórios devem ser preenchidos antes de prosseguir.

Fase 1 — Livro de regras

O livro de regras é confirmado pelo humano. Nenhuma regra pode ser alterada sem confirmação.

Fase 2 — Mapa de telas

O mapa de telas (design/screens.json) lista todas as telas e suas conexões. Deve ser verificado antes do desenho.

Fase 3 — Wireframes

Os wireframes são desenhados no modo Wireframe (cinza) usando layout automático e componentes do kit.

Fase 4 — Telas estilizadas

As telas são estilizadas com variáveis de cor e tipo do conjunto de cores escolhido.

Fase 5 — Medição

Cada tela é medida contra o livro de regras. As constatações são registradas em design/checks/.

Fase 6 — Decisão

A pessoa revisa as telas e as constatações e toma uma decisão (aprovar, rejeitar, adiar).

Fase 7 — Handoff

Se aprovado, um brief de construção é gerado para o implementador (Claude Code ou Codex).