# Michelangelo > 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. - Skill: `renatoasse/michelangelo` (Agent Skill, multi-file: 52 files) - Install (CLI): `npx skillmds@latest add renatoasse/michelangelo` - Raw SKILL.md: https://api.skillmd.com/api/skills/renatoasse/michelangelo/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: renatoasse (https://skillmd.com/u/renatoasse) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/renatoasse/michelangelo --- # 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/`: ```bash 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 (`/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:** `/michelangelo/-/`, onde `` 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 **``** no resto da doc. Tudo daquele trabalho mora ali: `/briefing.md`, `/variant-1.html`…`/variant-3.html`, `/gallery.html`, `/*.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 `/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: ```bash node scripts/detector/run.mjs [--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.