revisão-de-tema

ultrahand: revisão-de-tema

Auditar o quão bem um projeto segue seu tema: se o próprio arquivo de tema é sólido e se os designs e o código realmente o utilizam. A saída é uma lista ranqueada de descobertas mais uma lista de alterações propostas no tema. O revisor constrói sobre o tema do projeto; nunca inventa um novo. Uma lacuna no tema vira uma adição proposta para o skill theme fazer, não uma nova paleta.

As regras estão em shared/theme/rules.md (não negociáveis NN-n, eixos criativos CR-n, regras de evolução EV-n); cada verificação está em references/checklist.md, e ambas citam shared/theme/sources.md. Para problemas de UX além do tema (fluxos, rótulos, convenções de plataforma), aponte para o skill review.

Os scripts abaixo ficam em ${CLAUDE_PLUGIN_ROOT}/shared/theme/.

1. Obter o tema e o alvo

• O tema: encontre design/THEME.md e o arquivo de tokens (pesquise como o skill theme faz no passo 1). Leia THEME.md: sua personalidade, quais decisões estão bloqueadas, seu inventário de componentes e seu changelog. Esses são os padrões aos quais o alvo deve se ater.
• Ainda não há tema: não invente um. Execute node scan.mjs <diretório src> para mostrar os valores que o código usa hoje e revise apenas contra os não negociáveis. Recomende o skill theme para extrair um tema disso e coloque os principais clusters da varredura no relatório como ponto de partida.
• O alvo: código (uma pasta de origem, um diff ou um PR), um artefato de canvas ou uma captura de tela. Assim como em review, diga qual você tem e marque cada descoberta como Confirmado (medido no código, no arquivo de tokens ou no canvas) ou Provável (julgado a partir de uma imagem). Para um diff, revise o que ele altera e observe qualquer desvio que ele adiciona.

2. Executar as verificações

1. Arquivo de tema: node check.mjs design/theme.tokens.json --json. Cada erro é uma descoberta; leia a tabela de contraste para ambos os esquemas.
2. Uso de tokens no código: node scan.mjs <diretório src> --theme design/theme.tokens.json.
   • valores brutos que correspondem a um token: uma cópia codificada de um valor do tema. Quando o tema mudar, estes não vão [HIG-COLOR] [PRIMER-LINT].
   • valores sem token: desvio do tema. Cada um é ou um erro (ajuste ao token mais próximo mostrado) ou uma necessidade real (proponha um token).
   • tokens que nenhum arquivo menciona: possivelmente não utilizados. Confirme antes de propor remoção; a varredura corresponde a nomes por padrão.
   • cores quase duplicadas e espaçamento fora da grade: uma descoberta por cluster, não por linha. Também procure por tokens primitivos usados diretamente no código (primitive., ou o equivalente da plataforma), que pula o papel (NN-1).
3. No canvas ou em uma página ativa: leia os estilos computados dos elementos em revisão. A auditoria de composição (shared/composition/audit.mjs, executada via shared/input/drive.mjs) relata estilos de controle, tamanhos de fonte e lacunas por seção, o que mostra um segundo estilo de botão ou um tamanho de fonte perdido de uma vez.
4. Trabalhe através das passagens em references/checklist.md: saúde do tema, uso de tokens, reuso de componentes, consistência entre telas, ambos os esquemas, e caráter.

Os scripts encontram padrões, não provas. Investigue cada lead e confirme antes de transformá-lo em uma descoberta.

3. Avaliar e relatar

Avalie com a mesma escala 0–4 de review (veja o guia de gravidade em sua checklist), usando as âncoras na checklist deste skill. Um problema em muitos lugares é uma descoberta com uma contagem e suas principais localizações.

## Verdicto
<Versão do tema e alvo, evidência, contagens por gravidade, a maior fonte única de
desvio.>

## Descobertas
### T1 · 3 Grave · <título curto>
- **Onde:** <arquivo:linha, tela › elemento ou caminho de token>; ×<contagem>
- **Evidência:** Confirmado | Provável
- **Problema:** <o que desvia e qual o custo: inconsistência que as pessoas veem, ou um valor que
  não vai seguir a próxima mudança de tema>
- **Regra:** <NN-n / EV-n / CR-n> [<chave da fonte>]
- **Correção:** <concreta: "substituir #8e3f27 por var(--color-primary) em 3 lugares">

## Alterações propostas no tema
<Para o skill theme aplicar. Cada: adicionar / descontinuar / bloquear, o token ou decisão, seu
valor como alias, por que e quais descobertas precisam disso. Deixe de fora qualquer coisa que os tokens
já cubram.>

## O que funciona
## Não verificado

Mantenha as correções dentro do tema: alinhe a um token existente primeiro, proponha um token em segundo lugar, e nunca sugira um valor que quebre um não negociável. Ofereça-se para aplicar as correções de código e para executar o skill theme para as alterações propostas.