michelangelo

Michelangelo

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

A skill opera em três escopos, e confundi-los é a falha mais cara que ela comete:

	Refino	Redesign do artefato	Redesign do design system
Pergunta	"o que está torto?"	"como esta tela pode funcionar e impressionar melhor?"	"qual deve ser a nova identidade?"
Unidade	a menor possível	a tela/componente inteiro	o sistema visual inteiro
Muda a lei visual?	não	não — recompõe dentro da lei	sim — é o ponto
Modos	`audit` → `polish`	`audit` → galeria nível tela → `polish`	`design-system new` → `rebuild`
Sucesso	craft elevado	estrutura melhor, identidade reconhecível	identidade nova, coerente e melhor

O detector mede defeito, não ambição. Um PASS é alcançável pelo design mais insosso possível. Por isso os dois redesigns usam comparação visual, mas com guardrails opostos: o redesign do artefato prova magnitude sem romper a lei, enquanto o redesign do DS usa orçamento de mudança e antes/depois para provar que a própria lei mudou. A primeira decisão da skill nunca é qual modo rodar, e sim qual escopo foi autorizado.

Abertura — três decisões antes de rotear

Pergunte as três juntas, numa única mensagem, em texto plano (nunca via UI de chips), antes de abrir qualquer arquivo do alvo:

Ambição: quer refino (mantenho a direção visual e conserto/elevo o craft) ou redesign do artefato (reorganizo estrutura e hierarquia, mantendo a identidade)?

Lei visual: o design system atual deve ser preservado ou o pedido é para redesenhar o próprio design system (paleta, tipografia e linguagem visual)?

Meio: o alvo é web, documento impresso/PDF ou slide? (muda quais regras valem — ver reference/medium.md)

Não há default seguro na primeira. Errar a ambição custa a sessão inteira: um refino entregue a quem queria redesign lê como você não ter feito o trabalho — o resultado "está igualzinho" aos olhos de quem pediu, porque a direção visual, que é o que se vê primeiro, não mudou.

Na segunda há um default seguro e obrigatório: preservar o design system vigente. Palavras como "redesign", "refaça", "repense", "100x melhor" ou "irreconhecível" descrevem a magnitude do artefato, não autorizam trocar a identidade do produto. Só roteie para design-system new quando o pedido disser explicitamente que quer mudar o design system, a identidade visual, a paleta ou a tipografia da marca/produto.

Pule a pergunta só quando a resposta já está escrita no pedido, e registre em uma linha qual leitura você fez:

Redesign do artefato, DS preservado — o pedido diz redesign/refaça/repense ou usa intensificador de magnitude, mas aponta uma tela, componente, seção, documento ou slide específico e não pede para mudar a identidade do produto.
Redesign do design system — o pedido nomeia explicitamente a lei a trocar: design system, identidade visual, paleta de marca, tipografia institucional ou linguagem visual do produto inteiro.
Refino — o pedido nomeia um defeito específico ("o espaçamento está apertado", "corrige o contraste"), OU pede explicitamente para não mexer na direção.

A resposta de meio fixa o perfil de checks e de craft para o resto da sessão, e é gravada no briefing quando houver (reference/audit.md §Passo 5).

Antes de rotear, abra a lei. Leia PRODUCT.md (quem usa, para quê, e as anti-referências — o que este projeto explicitamente não pode parecer) e DESIGN.md (a lei visual) na raiz do repo, se existirem. Se nenhum dos dois existir e o alvo for web com framework, ofereça design-system document uma vez e siga com o que foi pedido: a falta deles nunca bloqueia o trabalho.

Antes de travar o alvo, confirme que ele é o alvo de verdade. Um arquivo pode ser uma casca fina que só embala outros arquivos — um viewer de galeria cujo corpo é <img src="...">/<iframe> apontando para os assets reais. Abra o arquivo e olhe o que ele de fato renderiza antes de assumir que o HTML apontado é onde o design mora. Sinal de casca: o arquivo é majoritariamente chrome (nav, grid, <section> genérica) em volta de referências a outros arquivos. Se for o caso, diga o que você encontrou e confirme com o usuário qual dos dois é o alvo — a casca ou o que ela embala — antes de gastar a sessão redesenhando a camada errada.

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. Todo modo carrega reference/medium.md — é ele que diz quais regras do generate.md valem e quais checks do detector se aplicam ao alvo.

`design-system` — a lei visual: registrar, trocar ou evoluir

Uma porta, três caminhos. O design-system é o único escritor da lei — audit mede contra ela, polish e rebuild propõem, e a escrita em DESIGN.md acontece sempre aqui dentro. Sem argumento, o caminho sai de dois sinais que já existem:

Estado do repo	Escopo autorizado	Caminho
sem `DESIGN.md`	—	`document` — inventaria o que já existe e escreve a lei
com `DESIGN.md`	redesign explícito do próprio DS	`new` — 3 direções divergentes, e a escolhida vira a lei
com `DESIGN.md`	refino	`improve` — deltas pequenos, uma dimensão por rodada

document — registro, não mudança: uma varredura escreve PRODUCT.md, DESIGN.md e a rota da vitrine. Não muda um pixel do alvo. Carregar: reference/design-system/document.md + reference/register.md + reference/brand.md.
new — troca a direção. Não termina no artefato: quem reconstrói é o rebuild, e os dois formam uma cadeia única. Carregar: reference/design-system/new.md + reference/directions.md (critério das 3 direções) + reference/brand.md (a identidade e os assets que alimentam as direções) + reference/register.md (brand vs product, dials) + reference/gallery.md (empacotar as 3 para escolha) + reference/generate.md (o craft de cada direção) + reference/slop.md (o que nenhuma direção pode parecer) + reference/inspiration.md (se houver consentimento para minerar referências).
improve — refina a lei sem trocar a direção. É também onde entram as propostas que vieram do polish e do rebuild, e onde a lei morta (token que ninguém consome mais) vira proposta de remoção. Sem DS ainda → redireciona para document. Carregar: reference/design-system/improve.md + reference/gallery.md + reference/generate.md + reference/audit.md (a renderização como canvas) + reference/register.md.

Carregue só o arquivo do caminho escolhido — os três juntos custam o triplo e remisturam os dois regimes que a Abertura acabou de separar.

`rebuild` — reconstruir o artefato na direção escolhida

O elo entre a lei nova e o arquivo do usuário. Recebe a direção aprovada e reescreve o alvo real, com antes/depois pareado e um orçamento de mudança que prova que a mudança aconteceu. É o modo que fecha um redesign — sem ele, design-system new entrega um DESIGN.md e o artefato continua como estava.

Carregar: reference/rebuild.md + reference/generate.md + reference/brand.md + reference/medium.md + reference/patterns/ (o repertório de estruturas já resolvidas).

`audit` — diagnosticar sem alterar

Mede um alvo contra o design system e devolve um briefing pronto. Não toca em código.

Carregar: reference/audit.md (Camada 1 = detector determinístico; Camada 2 = crítica perceptual) + reference/slop.md (a taxonomia de "cara de IA" que a Camada 2 procura) + reference/patterns/ (o repertório — o que a Camada 2 pode PROPOR no lugar do que está lá).

`polish` — aplicar o briefing

Transforma um briefing (do audit, ou pedido direto) em código, reusando o que existe.

Carregar: reference/polish.md + reference/generate.md + reference/patterns/ (quando o briefing propõe um padrão nomeado) + reference/gallery.md (quando a mudança de arranjo é ampla demais para aplicar às cegas).

As três cadeias

Refino: audit → polish. Não pule direto para polish sem medir o estado atual — sem baseline não há como saber o que mudou. Este é o default depois de a Abertura resolver que o caso é refino, nunca o default do pedido genérico.
Redesign do artefato com DS preservado: baseline real → galeria nível tela de reference/gallery.md → polish. As três opções variam arranjo, hierarquia, densidade local e composição, mas reutilizam os mesmos tokens, tipografia, componentes, raios, elevação e motion do DESIGN.md. Rode o detector com --ds DESIGN.md em cada opção. Trate mudar paleta, família tipográfica ou linguagem de superfície como falha de escopo.
Redesign do design system: design-system new → rebuild. A galeria escolhe a direção; o rebuild a aplica no artefato. Parar depois da galeria é entregar uma promessa, não um resultado. rebuild nunca aplica no artefato final sem antes mostrar a proposta e esperar reação do usuário — 3 direções quando fizer sentido, ou 1 proposta concreta e visual quando a identidade de cor/tipografia for fixa (brand.md caso 2: o artefato retrata outra marca). Identidade fixa restringe QUAIS eixos podem variar — nunca é licença para pular o checkpoint inteiro e decidir sozinho. Ver rebuild.md §Passo 0.

Um redesign do design system pode terminar com um audit de conferência, mas nunca começa por ele: o briefing mediria contra a lei antiga que será descartada. Um redesign do artefato faz o oposto: começa pelo baseline real e mede todas as opções contra a lei vigente, porque reconhecibilidade é parte do critério de sucesso.

Rodar o detector

A skill é global; o cwd é o projeto do usuário. Sempre invoque por caminho absoluto, nunca relativo:

node ~/.claude/skills/michelangelo/scripts/detector/run.mjs <url|arquivo.html> \
  [--ds DESIGN.md] [--medium web|print|slide]

No Windows/Git Bash, ~ resolve; se falhar, use /c/Users/<user>/.claude/skills/michelangelo/scripts/detector/run.mjs.

--medium desliga os checks que não fazem sentido no alvo (scrollbar, alvo de toque e transição não existem em papel). Default web. Ver reference/medium.md.
Gate: BLOCKED se P0 + P1 > 0; PASS caso contrário. P2/P3 não travam.
Código de saída: 1 se BLOCKED, 0 se PASS — use no loop de correção em vez de parsear texto.

Vale para todos os modos: cada direção candidata passa o gate antes de ir pra galeria, cada delta antes de entrar na mini-galeria, e nada é "aplicado" até o detector confirmar.

Setup (uma vez por máquina): a partir de ~/.claude/skills/michelangelo/, rode npm install && npx playwright install chromium. Já está instalado nesta máquina.

Pasta de saída — scratch datado por trabalho

Todo artefato que a skill escreve — prints, variantes da galeria, briefing.md — vai para uma pasta datada dentro do scratch do repo, nunca solto na raiz e nunca fora do repo:

Ache o scratch existente na raiz (_scratch/, scratch/, .scratch/, tmp/). Se não houver, crie .scratch/ (e adicione ao .gitignore se o repo usa git).
Dentro dele, michelangelo/<slug>-<AAAA-MM-DD>/.

Chamo essa pasta de <OUT> no resto da doc. Um novo pedido abre uma nova pasta datada — o histórico anterior nunca é sobrescrito.

Higiene de runtime — nenhum build temporário fica no repo

<OUT> guarda a entrega e a evidência visual. Cache de framework, build isolado, saída de teste, log e servidor são runtime descartável, não artefato: nunca deixe na raiz pastas como .next/.next-*/.next-e2e*, test-results/, playwright-report/, output/playwright/ ou logs soltos criados pela sessão.

Gate obrigatório antes de abrir servidor

Antes de executar qualquer comando que possa iniciar servidor ou build (dev, start, preview, serve, build ou equivalente), procure primeiro um servidor reutilizável:

Derive as URLs candidatas da configuração, scripts e documentação do projeto e inspecione os processos/portas locais que já estão escutando. Não teste apenas a porta default do framework.
Faça uma requisição à rota do alvo em cada candidata e confirme que a resposta pertence à aplicação certa por título, conteúdo, asset ou outro marcador conhecido. Porta aberta ou HTTP 200, sozinhos, não provam identidade.
Se uma candidata servir a superfície correta, registre a URL — e o processo/PID, quando local — como preexistente e reutilize-a durante todo o trabalho. Não abra outro servidor só para obter uma porta própria; nunca encerre o servidor reutilizado nem limpe o runtime que pertence a ele.
Só inicie um runtime novo quando nenhuma candidata válida existir. Registre essa conclusão antes do comando para distinguir descoberta feita de descoberta pulada.

Esse gate vale mesmo quando build + preview parecer mais conveniente. Servidor existente só é rejeitado por motivo verificável — aplicação/rota errada, superfície diferente da produção, estado quebrado ou indisponibilidade — e o motivo fica registrado.

Antes de iniciar runtime, registre os caminhos que já existem; nunca apague um caminho preexistente nem faça faxina genérica no repo.
Se o gate exigir build/servidor isolado, direcione cache, distDir, screenshots transitórios e logs para <OUT>/.runtime/ sempre que o projeto permitir.
Quando uma ferramenta exigir saída temporária fora de <OUT>, registre cada caminho criado pela sessão e envolva a execução em fechamento garantido (try/finally ou equivalente): encerre o processo e remova esses caminhos tanto em sucesso quanto em erro/interrupção.
Antes de entregar, confirme que nenhum runtime criado pela sessão permanece. Preserve apenas os arquivos duráveis documentados em <OUT> — inclusive artifact.html e as imagens usadas como evidência/rollback.

Entrega visual — SEMPRE um Artifact

Toda vez que a skill produz versões para o usuário comparar ou aprovar — as 3 direções, a mini-galeria de deltas, o par antes/depois, a proposta única de identidade fixa —, ela publica um Artifact do Claude. Print no chat e arquivo em <OUT> continuam existindo, mas são insumo e rollback, não a entrega: ninguém abre file:// para julgar design, e print perde hover, foco, scroll e o texto real.

Link clicável obrigatório

Na mesma mensagem que entrega qualquer Artifact, inclua uma linha visível em Markdown com um link clicável para a URL absoluta e completa da peça:

[Abrir o artefato completo](https://host.example/caminho-completo-do-artefato)

Se a ferramenta de publicação devolver uma URL, use exatamente essa URL completa.
Se só houver o HTML local, mantenha um servidor HTTP local ativo, verifique que a rota responde e entregue uma URL completa no formato http://127.0.0.1:<porta>/<rota>/artifact.html.
Um preview embutido, uma referência de visualização, um caminho de arquivo ou file:// pode acompanhar a entrega, mas nunca substitui o link clicável.
Não encurte, esconda nem torne relativo o destino. O usuário não deve precisar localizar o arquivo, copiar caminho ou adivinhar como abri-lo.

O Artifact é um arquivo HTML autossuficiente em <OUT>/artifact.html, com cada versão dentro de um <iframe srcdoc> — o mesmo documento que passou no gate, sem transformação. Ajustou uma versão? Republica pelo mesmo caminho de arquivo, que é a mesma URL.

→ leia reference/gallery.md §Artifact antes de montar — é lá que estão as quatro coisas que quebram calado num Artifact (caminho relativo, <!doctype> próprio, asset externo, tema do visitante) e o que fazer quando o alvo é impresso.

Repertório de padrões

reference/patterns/ guarda estruturas de tela já resolvidas — não tokens, não craft: o arranjo que substitui um arranjo que não funciona. Cada arquivo diz quando o padrão se aplica, quando NÃO se aplica, a anatomia com as decisões que carregam peso, e o que o detector vai dizer sobre ele (inclusive falsos-positivos já corrigidos no check).

sectioned-form.md — formulário longo como checklist de seções, no lugar de uma coluna corrida de campos. Gatilho medível: altura > ~2 viewports + 3 blocos de pergunta de mesmo peso.
single-offer-panel.md — seção de compra de produto único como UM painel (corpo, coluna de compra, rodapé de confiança), com o cupom como bilhete destacável de serrilha real. Gatilho medível: 1 oferta + 6+ entregáveis + 2+ números de preço concorrendo. Traz a §Contra-achados: três recomendações de pesquisa de checkout que pioram uma seção de venda quando aplicadas ao pé da letra.

Um padrão do repertório é uma proposta de Camada 2, nunca um fix mecânico: ele muda a estrutura da tela, então num refino só entra com o usuário avisado.

Bans absolutos

Reflexo, não parágrafo. Qualquer um destes na saída é falha:

Roxo de IA (gradiente roxo/violeta genérico).
Fonte default não-intencional: Inter sem decisão em cima, ou stack de sistema (Segoe UI, Helvetica Neue, Arial, -apple-system, Consolas). Alvo impresso embute a família escolhida (reference/brand.md §Aquisição).
Herói centrado + 3 cards idênticos.
Valor cru (padding: 13px, hex solto) onde já existe token do DS.
Criar componente/modal novo sem procurar um reutilizável antes.
Concluir sem passar o gate do detector.
Concluir sem o passo de fechamento do guardião — a pergunta "o que eu fiz é melhor que o DS?", com uma das três saídas nomeada. Pular equivale a decidir "nada muda" sem ter olhado.
Entregar versões para escolha ou aprovação sem Artifact publicado — mandar só print no chat, ou só o caminho de um .html na pasta de trabalho, não é entrega.
Entregar Artifact sem link clicável para sua URL absoluta e completa — preview embutido e caminho local não contam como link de abertura.
Narrar uma saída de gate BLOCKED. Se P0+P1 > 0 a entrega não está pronta. Ou conserta, ou o veredito é "NÃO ENTREGUE — travado por X", nunca "entregue, mas aceitável". Reclassificar um P1 como candidato de DS não destrava o gate.
Auditar superfície que diverge da produção — um /dev sandbox, um mockup, ou fullPage numa tela de altura travada (expande a página e esconde o corte, o clamp e a scrollbar). Ver audit.md §Passo 1.
Dar veredito de gosto sem olhar o pixel real.
Entregar alvo impresso sem validar num segundo motor de render (rebuild.md §Verificação cruzada). O Chromium aprova o que ele mesmo gerou.
Medir um alvo que outra sessão está reescrevendo. Sinais: Edit falha com "file has been modified"; um fix seu volta ao valor antigo; o gate oscila sem você ter causado. Cheque o mtime dos arquivos do alvo antes de aplicar fix; mtime recente = pare, o baseline é ficção.
Interruptor que liga uma NEGATIVA. Um toggle só ativa algo: o rótulo nomeia o comportamento que passa a valer quando ligado ("Esperar antes de entrar de novo"), nunca o que deixa de acontecer ("Não repetir na mesma conversa"). Ligado + rótulo negativo é dupla negação, e ninguém sabe o que a tela está fazendo. Vale igual para checkbox e para o texto de apoio: o estado desligado DIZ o que acontece, em vez de ficar mudo.

Leis transversais

Guardião do design system

A lei é a convenção vigente, não o teto. Em quase todo caso o DS não é o padrão ideal a perseguir — é o que o projeto usa hoje e sempre precisa melhorar. Guardião zeloso demais é o que faz uma skill de design parar de propor e começar a obedecer, e aí ela entrega o que já existia, arrumado.

Por isso o guardião mora no fluxo de cada modo — passo de abertura (leia a lei antes) e passo de fechamento (a lei precisa mudar?) — e obriga por regime, igual à §Localidade abaixo. O fechamento pergunta "o que eu fiz é melhor que o DS?", nunca "o que eu fiz violou o DS?". Três saídas, e as três são caminhos reais:

Nada muda — o que fiz já era a lei.
Falta lei — produzi ou encontrei um padrão bom que não está no DS → vira candidato a token/componente, e os consumidores off-DS são refatorados para referenciá-lo.
A lei perdeu — o que fiz é melhor do que o DS manda → o token vigente é derrubado, não contornado; se ninguém decidir agora, vai para Em disputa.

A saída 3 custa exatamente o mesmo que a 2. Se derrubar for mais caro que acrescentar, o DS engorda e nunca melhora — vira museu por incentivo, não por descuido.

Quem escreve é sempre o design-system (caminho improve quando a proposta veio de outro modo). Telas que consomem tokens propagam de graça quando o token muda; o estado ideal — "mexo só no DS, as telas seguem" — é o destino, e a vitrine é a prova visível de que ele vale.

Localidade — e quando ela NÃO se aplica

No regime de refino, a skill nunca julga uma unidade grande como bloco único: sempre a menor unidade delimitada (uma dimensão do DS, uma seção), nunca "a página inteira" como um veredito só. "Melhora esta página" produz mush por falta de foco; "melhora a tipografia" ou "melhora este hero" produz ganho real.

No redesign do artefato, a unidade passa a ser a tela/componente inteiro, mas o DS continua sendo lei. A ambição vem de recompor hierarquia, topologia e densidade dentro da mesma linguagem — não de trocar paleta e fontes. As três opções passam com --ds DESIGN.md, e a comparação inclui a pergunta perceptual: "ainda reconheço este produto sem ler o logo?". Se a resposta for não, a opção falhou mesmo com P0/P1 = 0.

Só no redesign explícito do design system a lei se inverte. A unidade vira o sistema inteiro, porque se julga a coerência entre paleta, tipografia, estrutura e capa. Nesse escopo o DS antigo é o que se tenta bater, e o detector mede contra a direção candidata. Usar essa liberdade num redesign de tela é quebra de escopo.

DRY reuse-first

Antes de criar componente, modal ou bloco: procure um reutilizável e reuse/adapte; componentize padrão repetido em vez de copiar. Regras concretas (quando extrair, token vs valor cru, master + overrides) em reference/generate.md §DRY — a fonte única.

Na auditoria vale o inverso: um componente que é espelho de um canônico (design system, repo irmão) precisa ser verificado contra a fonte. Espelho que divergiu é violação, não candidato de DS, e o fix é re-sincronizar com o original.