michelangelo

name	michelangelo
description	Transforma uma UI existente numa versão muito mais bonita e profissional, com um detector determinístico que mede o render real (Playwright) e trava a entrega por número — não por gosto. Use quando o pedido for "deixa essa UI bonita/profissional", "redesenha essa tela", "audita o design", "melhora o design system", ou "michelangelo". Layout-only — nunca gera ou revisa copy.

Michelangelo

Skill de design de UI com quatro modos e uma regra fixa: nenhuma entrega termina sem passar pelo detector. Não é "acho que ficou melhor" — é P0/P1 = 0.

Setup (uma vez por máquina)

Antes de rodar o detector, leia ~/.claude/playwright.md.

Na primeira vez que esta skill for usada neste projeto, a partir de skills/michelangelo/:

cd skills/michelangelo && npm install && npx playwright install chromium

Sem isso, npx vitest run e node scripts/detector/run.mjs não têm o que rodar.

Roteador — qual modo usar

Quatro modos, cada um carrega sua própria prosa de reference/. Não carregue o que o modo não usa.

design-system-new — definir ou trocar a lei visual do repo

Quando não existe design system, ou existe e precisa mudar de direção/expandir para uma direção nova. Propõe 3 direções divergentes; o usuário escolhe 1, e ela substitui a lei.

Carregar: reference/design-system-new.md (fluxo principal) + reference/directions.md (critério para propor 3 direções distintas) + reference/register.md (brand vs product e como os dials — cor, densidade, ornamentação, motion — derivam do register) + reference/gallery.md (empacotar as 3 direções num HTML navegável de escolha) + reference/inspiration.md (quando o usuário consente a mineração de referências — ver §Leis transversais e o próprio arquivo).

design-system-improve — refinar a lei visual existente, ponto a ponto

Quando já existe um design system que agrada e o pedido é deixá-lo melhor sem trocar a direção. Loop de rodadas temáticas: cada rodada propõe deltas pequenos de uma fatia do DS (default: uma dimensão — tipografia, cor, espaço…), previsualizados numa seção real, e o usuário aceita/refina; os aceitos são gravados de volta no DS e propagados. Se não houver DS ainda, redireciona para design-system-new (não há lei a refinar).

Carregar: reference/design-system-improve.md (fluxo principal) + reference/gallery.md (mini-galeria de deltas antes/depois) + reference/generate.md (craft que o detector mede)

• reference/audit.md (a renderização usada como canvas) + reference/register.md (dials)
• reference/inspiration.md (quando o usuário consente a mineração de referências).

audit — diagnosticar sem alterar

Mede uma tela/componente contra o design system e devolve um briefing de mudanças pronto. Não toca em código — é leitura, render e medição.

Carregar: reference/audit.md (as duas camadas: Camada 1 é o detector determinístico scripts/detector/run.mjs, que reprova por número; Camada 2 é a crítica perceptual sobre screenshot) + reference/slop.md (taxonomia de "cara de IA" que a Camada 2 procura, tell por tell, nunca um veredito solto).

polish — aplicar o briefing

Transforma um briefing (do audit, ou pedido direto do usuário) em código de verdade, reusando o que já existe em vez de duplicar. É o único modo que escreve no projeto.

Carregar: reference/polish.md (fluxo de aplicação) + reference/generate.md (regras concretas de craft — tipografia/cor/espaço/sombra/hover/grid — que o detector mede) + reference/gallery.md (quando a mudança é ampla demais para aplicar às cegas, apresentar variantes em vez de escolher sozinho).

Encadeamento audit → polish

O caminho padrão para "melhora essa tela" sem um briefing pronto é audit primeiro, depois polish sobre o briefing gerado (<OUT>/briefing.md, ver §Pasta de saída). Não pule direto para polish sem medir o estado atual — sem baseline não há como saber o que mudou.

Pasta de saída — scratch datado por trabalho

Todo artefato que esta skill escreve — prints, variantes .html da galeria, o shell da galeria e o briefing.md — vai para uma pasta datada dentro do scratch do repo, nunca solto na raiz do repo e nunca fora do repo. Resolva a pasta uma vez por trabalho:

1. Ache o scratch do repo. Procure uma pasta de scratch/temp já existente na raiz (scratch/, .scratch/, tmp/, .tmp/, .cache/…). Se não houver nenhuma, invente .scratch/ na raiz do repo (e adicione a pasta ao .gitignore se o repo usa git — o CLAUDE.md global exige scratch gitignorado onde há git).
2. Crie um subdiretório michelangelo/ dentro dele.
3. Crie uma pasta datada por trabalho: <scratch>/michelangelo/<slug>-<AAAA-MM-DD>/, onde <slug> descreve o alvo em kebab-case. Ex.: uma galeria pra refatorar o visual da landing page home hoje → scratch/michelangelo/landing-page-refactor-2026-07-19/.

Chamo essa pasta de <OUT> no resto da doc. Tudo daquele trabalho mora ali: <OUT>/briefing.md, <OUT>/variant-1.html…<OUT>/variant-3.html, <OUT>/gallery.html, <OUT>/*.png. Um novo pedido/alvo abre uma nova pasta datada — o histórico anterior nunca é sobrescrito. Onde a doc dos modos disser .michelangelo/briefing.md, leia <OUT>/briefing.md.

Escopo de breakpoints — pergunte antes de medir

Antes de rodar audit ou polish, sempre pergunte ao usuário o escopo de breakpoints, oferecendo o default em texto (nunca via UI de chips):

Ajusto o design em todos os breakpoints (mobile + tablet + desktop) ou desktop primeiro (default)?

Default: desktop primeiro. Corrigir mobile/tablet antes de o desktop estar 100% é gastar tempo e tokens numa base que ainda vai mudar — o arranjo do desktop redefine o que o mobile precisa reempacotar. Acerte o desktop primeiro; responsividade é uma segunda passada, depois que o desktop trava em PASS.

Dois escopos:

• desktop (default) — mede, critica e conserta só o breakpoint desktop (1280px). Um único print (desktop), crítica perceptual só sobre ele, e o loop do detector fecha quando o desktop dá PASS. Mobile/tablet ficam explicitamente adiados — não são finding, são fora de escopo desta passada.
• all — os 3 breakpoints obrigatórios (mobile/tablet/desktop); o comportamento completo de responsividade.

A resposta fixa o escopo para o resto da sessão (o audit e o polish encadeado). O audit grava o escopo escolhido no briefing (## Escopo, ver reference/audit.md §Passo 5) para o polish honrar o mesmo recorte quando rodar em outra sessão.

Bans absolutos

Reflexo, não parágrafo — qualquer um destes na saída é falha, sem exceção:

• Roxo de IA (gradiente roxo/violeta genérico).
• Inter como fonte default não-intencional.
• Herói centrado + 3 cards idênticos.
• Valor cru (padding: 13px, cor hex solta) onde já existe um token do design system.
• Criar componente/modal novo sem antes procurar um reutilizável existente no projeto.
• Concluir a tarefa sem passar o gate do detector.
• Narrar uma saída de um gate BLOCKED. Se P0+P1 > 0, a entrega NÃO está pronta — ponto. É proibido escrever um parágrafo explicando por que o BLOCKED "tá ok". Ou você conserta, ou o veredito é literalmente "NÃO ENTREGUE — travado por X", nunca "entregue, mas aceitável". Reclassificar um P1 como "candidato de DS" (audit.md §Passo 4) não destrava o gate — é uma proposta paralela, não uma licença pra shippar BLOCKED.
• Auditar uma superfície que diverge da produção. Medir um /dev sandbox, um mockup, ou qualquer render que não seja o que o usuário realmente vê é medir uma tela que não existe (ver audit.md §Passo 1). Inclui o pecado do fullPage: capturar fullPage numa tela de altura travada / scroll interno expande a página e esconde o corte, o clamp e a scrollbar nativa — exatamente os defeitos que quebram a tela.
• Dar veredito de gosto sem olhar o pixel real. "Parece ótimo/ok" sobre o render errado é pior que silêncio (audit.md §Passo 3).

DRY reuse-first (princípio fundamental)

Antes de criar qualquer componente, modal ou bloco: procurar um reutilizável já existente no projeto e reusar/adaptar; componentizar um padrão que se repete em vez de copiar. Vale tanto na geração das variantes (design-system-new, design-system-improve, polish com galeria) quanto na integração final.

E o inverso, na auditoria: um componente que JÁ existe e é um espelho/porte de um canônico (design system, repo irmão) precisa ser verificado contra a fonte — um espelho que divergiu (proporção, tamanho de sub-elemento, ornamento cobrindo o texto) é violação, não "candidato de DS", e o fix é re-sincronizar com o original. Ver reference/audit.md §Proveniência e reference/slop.md §Componente.

Leis transversais

Valem para TODOS os modos, não só os de design system.

Guardião do design system + componentização

O michelangelo é o guardião do DS. Sempre que a skill produzir ou encontrar um valor fora do DS (uma cor/espaço/raio/sombra solto, um padrão de componente não tokenizado):

1. Promove aquilo a um token/padrão nomeado no DS (DESIGN.md + tokens file), seguindo a catraca de design-system-new.md.
2. Refatora os consumidores — todo componente/tela que usa o valor solto passa a referenciar o token.

Telas que já consomem tokens propagam de graça quando o token muda; telas com valor solto são o alvo do guardião. O estado ideal — "mexo só no DS, as telas seguem" — é o destino; o guardião é o mecanismo que leva o repo até lá, uso após uso. É a extensão ativa do DRY reuse-first acima: não basta não duplicar; um valor solto é dívida a ser promovida e propagada, não deixada onde está.

O custo do guardião não é uniforme: refinar a lei dimensão por dimensão (editar o token direto) mantém esse custo baixo, porque não há one-off novo a promover; melhorar seção por seção gera valores locais que depois precisam ser promovidos e propagados um a um. Por isso o design-system-improve tem a dimensão do DS como lente default (ver reference/design-system-improve.md §Passo 3).

Localidade

A skill nunca julga uma unidade grande como um bloco único. Sempre a menor unidade delimitada — uma dimensão do DS ou uma seção — nunca "a página inteira" como um veredito só. Melhorias vêm de decisões pontuais acumuladas, não de um julgamento global. A IA decide melhor sobre unidades pequenas e focadas: "melhora esta página" produz mush por falta de foco; "melhora a tipografia" ou "melhora este hero" produz ganho real. Mesmo quando o pedido é uma página inteira, a skill a decompõe em seções e resolve uma por vez.

Existem duas localidades distintas, e a distinção decide o default de um refino de DS: localidade de concern (uma dimensão por vez — só tipografia, com o resto congelado: uma variável isolada) e localidade de superfície (uma seção por vez — tipo, cor, espaço e elevação juntos naquele lugar: várias variáveis de uma vez). Concern-locality é mais focada que surface-locality — por isso o design-system-improve percorre por dimensão do DS por default, não por seção (ver reference/design-system-improve.md §Passo 3).

Loop central: o gate

Toda alteração de UI feita por esta skill termina rodando o detector:

node scripts/detector/run.mjs <url|arquivo.html> [--ds tokens.json]

P0 e P1 bloqueiam — a entrega não está pronta enquanto gate !== 'PASS'. P2/P3 são melhoria contínua, não travam. Isso vale para design-system-new (cada direção candidata passa pelo detector antes de ir pra galeria), para design-system-improve (cada delta passa pelo detector antes de entrar na mini-galeria), audit (Camada 1 é o próprio detector) e polish (não é "aplicado" até o detector confirmar).

Layout-only

Esta skill nunca gera nem revisa copy. Texto, tom de voz e conteúdo ficam como estão — o trabalho é tipografia, cor, espaço, hierarquia, estrutura e interação sobre o que já existe.