nikbearbrown/figma-webdesigner

Auditoria de Design de Site → Wireframes → Ledger de Decisões

Propósito

Transformar um clone local de um site em: (1) evidência com hash vinculada a um commit git, (2) descobertas que citam cada regra e apontam para arquivos fonte prováveis, (3) wireframes atuais e futuros no Figma, (4) registros de decisão explicando cada mudança, (5) registros de aprovação humana, e (6) briefs de implementação para decisões aprovadas que Claude Code ou Codex executam em uma sessão separada. O ledger git é a fonte da verdade. O Figma é uma projeção dele. Esta skill projeta e registra; ela nunca edita o código fonte do site.

Fluxo de trabalho pretendido

1. O estudante clona o repositório do seu site (do GitHub, ou o repositório que um projeto Vercel implanta) e o executa localmente. Espera-se que os estudantes tenham acesso educacional ao Figma MCP.
2. Esta skill captura do servidor de desenvolvimento local, audita e constrói wireframes no Figma.
3. Um humano tria as descobertas, revisa as decisões e aprova.
4. Esta skill escreve um brief de handoff por decisão aprovada. Claude Code ou Codex implementa cada um em seu próprio branch. Esta skill recaptura para verificar.

Comandos

A pasta da skill tem um comando, fwd, e um CLAUDE.md que diz como respondê-lo. Quando o usuário digitar help, check, init ou tutorial, siga CLAUDE.md:

• help executa fwd help (verificações de configuração mais um próximo passo) e, com as ferramentas Figma presentes, whoami para o assento. Itens faltantes primeiro; um próximo passo; nenhuma mudança feita em nome do estudante.
• tutorial executa o primeiro tutorial de sete passos (redesign da sua página inicial). São as próprias fases desta skill, conduzidas passo a passo.
• fwd approve|reject|defer <D-id> é do estudante, executado no terminal dele. Ele escreve o arquivo de aprovação e o evento do ledger. Inegociável 1 se aplica: nunca execute, nunca escreva audit/approvals/.
• fwd ledger verify verifica a cadeia de hash e que cada arquivo de aprovação corresponde ao ledger.

Inegociáveis

1. Apenas um humano pode definir uma decisão como aprovada, rejeitada ou adiada, ou reabrir uma. Nunca escreva esses estados. Nunca escreva arquivos em audit/approvals/.
2. Cada descoberta cita um rule_id de audit/rulebook/rules.yaml. Sem regra, sem descoberta: registre-a como uma observation para o humano.
3. Os rótulos das descobertas seguem a camada da regra: normativa → failure, heurística → concern, própria → deviation. Nunca chame uma descoberta heurística de falha. Nunca use ícones ou palavras de passar/falhar (✅ ❌ "violated") em descobertas heurísticas.
4. Cada diferença entre um frame atual e seu frame futuro carrega pelo menos um ID de decisão. Sinalize diferenças não etiquetadas; não as absorva.
5. Nunca edite a página 00 As-Is. Nunca modifique ou exclua nós que a skill não criou. Toque apenas em anotações nas próprias categorias da skill, e sempre leia-mescle-escreva.
6. Nunca defina o status Dev Mode (Pronto para desenvolvimento / Concluído). Nunca resolva ou exclua comentários humanos.
7. Nenhuma escrita no Figma em um arquivo existente até que o humano tenha salvo uma versão de linha de base nomeada e seu ID esteja registrado. Exceção: um arquivo Figma que esta execução criou. Ele começa vazio, então o arquivo vazio é sua própria linha de base; registre isso em capabilities.json.
8. Capture apenas de um clone local de um repositório que o usuário possui ou tem direitos para trabalhar, servido de localhost, ou do site implantado ou de uma pré-visualização do Vercel desse mesmo repositório quando o usuário fornecer sua URL. Nunca capture, injete scripts ou remova cabeçalhos de segurança em sites ativos de terceiros. intent.yaml deve registrar o repositório e o commit fixado.
9. Nunca sobrescreva um frame de descobertas anterior ou saída de execução anterior. Reexecuções criam um novo frame versionado (veja Fase 7). Nunca localize seus próprios nós por nome de camada, cor de preenchimento ou heurísticas de texto; use os IDs de nó registrados no ledger.
10. Nunca edite o código fonte do site. A implementação acontece apenas em uma sessão separada de Claude Code ou Codex, a partir de um brief de handoff para uma decisão aprovada.

Estrutura de diretórios

audit/
  intent.yaml                 # preenchido pelo humano (Fase 0)
  rulebook/rules.yaml         # confirmado pelo humano (Fase 1)
  schema/                     # esquemas de descoberta, decisão, aprovação, evento
  runs/R-YYYYMMDD-NN/
    capabilities.json         # o que esta execução realmente pôde fazer
    manifest.json             # hashes e estado da captura
    captures/{width}/         # screenshot.png, dom.html, axe.json, checks.json, skeleton.json
    findings.json
  decisions/D-NNNN.json
  approvals/A-NNNN.json       # apenas humanos
  handoff/                    # briefs de implementação, apenas decisões aprovadas
    README.md                 # regras compartilhadas para o agente implementador
    D-NNNN.md                 # um brief por decisão aprovada
  ledger.jsonl                # anexado apenas, eventos com cadeia de hash

O clone do site fica fora de audit/ (em local_path). Esta skill o lê e nunca escreve nele. audit/ pode ficar em uma pasta irmã ou em seu próprio branch, para que os registros de auditoria nunca se misturem com os commits do site.

Fase 0 — Intenção (Portão G0)

Se audit/intent.yaml estiver faltando ou tiver campos obrigatórios vazios, peça os campos faltantes conversacionalmente, um ou dois de cada vez. Não capture, avalie ou escreva nada até que cada campo obrigatório seja preenchido pelo usuário. Se o usuário ainda não clonou o repositório, dê a ele o comando git clone exato (para um projeto Vercel, o repositório GitHub do qual ele implanta) em seu próprio bloco de código e aguarde.

repo: ""                      # obrigatório: URL do GitHub (ou projeto Vercel) do site
local_path: ""                # obrigatório: caminho do clone local
commit: ""                    # obrigatório: SHA do commit ao qual a auditoria está fixada
dev_command: ""               # obrigatório: ex.: "npm run dev"
dev_url: "http://localhost:3000"
routes: []                    # obrigatório: caminhos para auditar, ex.: ["/", "/apply"]
ownership: ""                 # obrigatório: "próprio repositório", ou quem concedeu permissão e quando
implementer: ""               # obrigatório: "claude-code" ou "codex"
conformance_target: "WCAG 2.2 AA"
breakpoints: "derive"         # "derive" do CSS do site, ou uma lista de larguras
house_rules: ""               # caminho para tokens do sistema de design, ou "nenhum"
figma_file: ""                # obrigatório para fases Figma; em branco = modo apenas JSON
approvers: []                 # obrigatório: nomes e funções
out_of_scope: []

Fase 1 — Esquema (Portão G1)

Resuma o livro de regras (contagem de regras por camada e modo) e os esquemas de registro. Peça ao usuário para confirmar ou editar. Registre um evento de ledger schema.confirmed com o nome do usuário e a data. Não prossiga sem ele.

Sonda de capacidade de tempo de execução

Antes da Fase 2, escreva capabilities.json:

• Quais ferramentas Figma MCP estão presentes (use_figma, generate_figma_design, html_to_figma, get_metadata, get_screenshot, generate_diagram, upload_assets).
• Resultado whoami: tipo de assento no plano que possui figma_file. Se escritas não forem possíveis, defina mode: json-only e pule escritas no Figma para a execução. Espera-se que os estudantes tenham acesso a plano educacional; ainda registre o assento e plano reais em vez de assumir, e observe quaisquer erros de limite de taxa.
• Ambiente local: versões do Node e gerenciador de pacotes, se dev_command inicia e se a árvore de trabalho em local_path está limpa e em commit.
• Carregue a skill figma-use do Figma antes de qualquer chamada use_figma.
• Leia o esquema da ferramenta use_figma ativa e registre se ela aceita um parâmetro skillNames. Uma skill Figma comparável (Throughline) passa skillNames: "throughline" em cada chamada. Se o parâmetro existir, passe skillNames: "figma-webdesigner" em cada chamada use_figma; se não, registre skillNames: unsupported.
• Conhecido da primeira execução (2026-11-07, assento Full student), reverifique em vez de assumir: setSharedPluginData funciona; addAnnotationCategoryAsync e node.annotations (com labelMarkdown e categoryId) funcionam; figma.saveVersionHistoryAsync NÃO é suportado, então o agente nunca pode criar a versão de linha de base; figma.root.name NÃO é configurável, então o arquivo não pode ser renomeado através da API. Se algum destes agora falhar, carregue IDs de decisão em nomes de frame como ⟦D-0007⟧ mais anotações, e registre o resultado.
• Nomeie o arquivo Figma para o site (por exemplo jobs.humanitarians.ai) ao chamar create_new_file; ele não pode ser renomeado depois. Páginas são estágios (00 Kit & Legend, 01 As-Is Wireframes, 02 To-Be Wireframes); frames são page / width / as-is|to-be / state.

Convenções de script use_figma

Cada script que esta skill envia através de use_figma deve seguir estas regras:

0. Irmãos de mesma altura precisam de layoutSizingVertical = 'FILL' em cada filho (e layoutAlign = 'STRETCH' sozinho não é suficiente quando o pai ajusta sua altura). Texto em um hub ou célula de tabela que deve quebrar precisa de textAutoResize = 'HEIGHT' e uma largura.
1. Fontes primeiro. Chame figma.loadFontAsync para cada estilo de fonte que o script usa (incluindo Itálico e Médio se usados) em um único Promise.all no topo, antes de criar ou editar qualquer texto.
2. Defina dimensionamento após parentesco. Anexe cada nó ao seu pai, então defina layoutSizingHorizontal e layoutSizingVertical. Use apenas nomes de propriedade documentados (cornerRadius, não corner); uma propriedade desconhecida é silenciosamente ignorada.
3. Retorne um recibo de escrita. O script deve retornar um objeto com createdNodeIds e mutatedNodeIds (ambos sempre preenchidos honestamente; arrays vazios apenas quando nada desse tipo aconteceu), mais frameId, stamped (se dados de plugin foram escritos) e pageId.
4. Registre o recibo no ledger. Após cada chamada, anexe um evento figma.write contendo o recibo, o ID da execução, os IDs de decisão envolvidos e version_before. Fases posteriores encontram nós de propriedade da skill a partir desses IDs, nunca de nomes ou cores.
5. Estado anterior para mutações. Se o script alterar qualquer nó existente (anotações em um nó criado pela skill, texto, preenchimentos), retorne os valores anteriores no recibo para que o ledger possa registrá-los. Sobrescrever sem um estado anterior registrado não é permitido.
6. Falhe alto. Sem sucesso silencioso. Se uma busca não encontrar nada, retorne um erro que liste o que foi encontrado; nunca relate sucesso para uma operação nula.

Fase 2 — Captura

0. Prepare o clone. Confirme que local_path está em commit com uma árvore de trabalho limpa (se não, registre dirty: true e pare para perguntar), instale dependências, inicie dev_command e confirme que dev_url responde. Registre o SHA do commit, o flag dirty e a versão do Node em manifest.json. Não modifique nenhum arquivo fonte. Se o projeto precisar de variáveis de ambiente ou segredos que não estão presentes, pergunte ao usuário; nunca os invente.
1. Derive breakpoints da configuração do próprio repositório (configuração Tailwind, mídia CSS customizada, tema do framework) e das consultas de mídia CSS computadas do site (a menos que a intenção liste larguras). Capture em 320, em cada breakpoint menos um e no breakpoint, e em uma largura grande de desktop.
2. Por largura: captura de tela de página inteira, DOM, resultados de axe-core (tags wcag2a, wcag2aa, wcag21aa, wcag22aa), verificação de estouro, verificação de geometria de alvo, esqueleto estrutural (marcos, títulos, clusters interativos com caixas delimitadoras).
3. Registre o estado da captura (banner de consentimento, autenticação, variante) e SHA-256 de cada arquivo em manifest.json.
4. Anexe um evento capture.completed.

Fase 3 — Medir

Execute verificações automatizadas e assistidas. Resultados automatizados tornam-se descobertas diretamente. Resultados assistidos tornam-se descobertas com mode: assisted e triage: null; anote qual exceção (espaçamento, inline, equivalente, essencial, tabela de dados) pode se aplicar.

Mapeamento de fonte. Para cada descoberta, procure no clone a fonte do elemento (seu texto, nomes de classe, nome do componente ou atributos de dados) e registre source: {file, line, confidence}. Isso é de melhor esforço: use confidence: low para um palpite e omita source em vez de reivindicar uma localização que você não encontrou. Estas são dicas para o implementador, não instruções.

Fase 4 — Avaliar

Execute a passada heurística. Para cada descoberta registre:

• rule_id, localizador, caminho e hash da evidência
• gravidade 0–4 (Nielsen: frequência, impacto, persistência)
• confiança (alta/média/baixa)
• scope: um de single-section, cross-section, component, interaction
• uma frase sobre o que a evidência mostra

Orientação de escopo:

• single-section: o problema está dentro de um bloco de uma página.
• cross-section: o problema só aparece entre blocos, páginas ou larguras (ordem de prioridade versus ordem visual, padrões inconsistentes, navegação que muda entre páginas). Procure por estes deliberadamente; eles são frequentemente os mais consequentes e são os mais fáceis de perder ao revisar uma seção de cada vez.
• component: um elemento reutilizável se comporta ou parece inconsistente onde quer que apareça.
• interaction: o problema está em um estado, fluxo ou comportamento, em vez de um layout estático.

Para páginas longas, avalie cada seção a partir de sua própria captura de tela e anote posições y; então faça uma passada separada para descobertas entre seções. Inclua apenas regras com evidência visível suficiente; pule regras que não podem ser avaliadas a partir da captura, em vez de adivinhar. Trate-se como um avaliador; diga isso no resumo das descobertas.

Portão G2 — Triage

Apresente as descobertas agrupadas por gravidade, depois por página, como uma tabela: ID, regra, rótulo, escopo, página/largura, gravidade, confiança, evidência de uma linha. Peça ao usuário para aceitar, rejeitar ou repontuar. Registre cada chamada de triagem como um evento de ledger atribuído ao usuário. Apenas descobertas aceitas avançam.

Fase 5 — Linha de base Figma (Portão G3)

1. Capture telas atuais na página 00 As-Is via generate_figma_design (ou html_to_figma), um frame por largura capturada que mostre uma mudança estrutural.
2. Construa wireframes estruturais atuais na página 01 As-Is Wireframes a partir de skeleton.json, usando o kit de wireframe do arquivo se search_design_system encontrar um.
3. Handoff: peça ao usuário para travar 00 As-Is e salvar uma versão nomeada intitulada baseline R-…, então lhe dê seu ID de versão. Você não pode salvar versões por conta própria.
4. Registre o ID como version_before. Nenhuma escrita adicional até que você o tenha.

Fase 6 — Propor

1. Agrupe descobertas aceitas em decisões. Cada D-NNNN.json: título, IDs de descoberta, contexto, proposta, alternativas, anotações do ledger.
2. Para cada decisão, escreva um breve resumo executivo.
3. Anexe um evento decision.proposed.

Portão G4 — Aprovação Humana

1. Apresente as decisões agrupadas por página: ID, título, gravidade, descobertas, mudança proposta, alternativas.
2. O humano usa fwd approve|reject|defer <D-id> no terminal. A skill nunca escreve o arquivo de aprovação.
3. Quando o ledger mostrar uma aprovação, anexe um evento decision.approved.

Fase 7 — Briefs de Handoff

1. Para cada decisão aprovada, escreva handoff/D-NNNN.md: resumo, descobertas, proposta, arquivos fonte, trechos de código (se for relevante para o design), instruções de implementação.
2. Escreva handoff/README.md: regras para o agente implementador (Claude Code ou Codex), ordem de implementação, dependências.
3. Anexe um evento handoff.written.

Fase 8 — Verificação de Recaptura (Opcional)

Se o implementador relatou conclusão, recapture a nova implantação e verifique se as mudanças correspondem às decisões. Anexe um evento verification.completed com o resultado.

Tratamento de Erros e Rollback

• Toda operação Figma deve ser precedida por um backup do estado atual (via get_metadata ou consulta ao ledger).
• Se uma escrita Figma falhar, registre o erro no ledger, pare a execução e informe o usuário com detalhes.
• Se a captura falhar (site não responde, dependências ausentes), registre capture.failed e pare.
• Se uma decisão for rejeitada após o handoff, anexe decision.rejected e remova o brief correspondente.

Considerações de Segurança e Ética

• Esta skill nunca modifica o código fonte do site. Ela opera exclusivamente na camada de design e documentação.
• O ledger é anexado apenas, garantindo que nenhum registro seja alterado retroativamente.
• Apenas humanos podem aprovar, rejeitar ou adiar decisões. A skill nunca toma decisões de design.
• O usuário deve ter direitos sobre o repositório clonado. A skill verifica a propriedade em intent.yaml.
• Nenhum dado é enviado para terceiros além do Figma (via MCP) e do repositório git local.