pretty-ui

O que pretty-ui faz?

Telas criadas por IA parecem todas iguais porque ninguém escolheu nada. O modelo preenche cada lacuna com a resposta mais comum que já viu, e o resultado é uma página que poderia pertencer a qualquer produto.

O pretty-ui corrige isso na ordem que um designer usaria: escolha uma direção, escreva-a e aplique-a em todos os lugares, verificando o resultado. A escolha é feita pela pessoa, a partir de opções reais que ela pode ver, não pelo agente sozinho.

A execução

Siga estes passos em ordem. Informe ao usuário em qual passo você está.

1. Leia o projeto

• Descubra o que está sendo construído: uma página que é lida e rolada (landing page, site de marketing, portfólio), uma tela de aplicativo web que as pessoas usam (dashboard, configurações, inbox) ou um aplicativo móvel.
• Descubra a stack: HTML puro, Tailwind, shadcn/ui, React, Vue, Svelte, React Native, SwiftUI, Compose ou Flutter. Trabalhe nessa stack. Nunca a migre.
• Procure por um sistema visual existente: DESIGN.md, AGENTS.md ou CLAUDE.md com anotações de design, variáveis de tema Tailwind ou shadcn, um guia de marca, um logotipo. Se a marca já tem cores e fontes, mantenha-as. As direções no passo 3 variam então layout, escala tipográfica, densidade e acentos dentro da marca, não a marca em si.
• Colete conteúdo real: o nome do produto, o que ele faz, para quem é, números reais, capturas de tela reais. Conteúdo placeholder faz todo design parecer genérico.

2. Auditoria (apenas quando uma UI já existe)

Leia references/tells.md. Execute o verificador nos arquivos que renderizam a UI:

node <skill>/scripts/check.mjs <arquivos ou pastas>

Liste os resultados para o usuário, agrupados por severidade, com arquivo e linha. Adicione qualquer coisa que o verificador não consegue ver lendo o código: três cartões idênticos, tudo centralizado, sem ponto focal claro, texto de preenchimento. Se a tela já for bem projetada, diga isso e sugira dois ou três pequenos refinamentos em vez de um redesign.

3. Ofereça três direções

Leia references/systems.md. Ele lista 24 sistemas de design completos, 12 para web e 12 para aplicativos móveis, cada um com um DESIGN.md público.

1. Escolha três sistemas que sejam diferentes de propósito: por exemplo, um claro e editorial, um escuro e denso, um suave e amigável. Corresponda à plataforma (web ou app) e ao universo do produto. Nunca ofereça três variações da mesma aparência.
2. Busque o DESIGN.md de cada sistema a partir de sua URL.
3. Construa a mesma tela chave em cada direção, com o mesmo conteúdo real, como arquivos HTML independentes:
   • pretty-ui/directions/a-<slug>.html, b-<slug>.html, c-<slug>.html
   • Páginas web em 1440×900, telas de aplicativo móvel em 390×844. CSS inline, links do Google Fonts, sem imagens externas.
4. Facilite a comparação:
   • Se as ferramentas de canvas do Codex Design estiverem disponíveis (por exemplo create_canvas e add_node), coloque os três arquivos em um canvas lado a lado e abra-o.
   • Caso contrário, execute node <skill>/scripts/compare.mjs pretty-ui/directions/*.html --out pretty-ui/directions/index.html e diga ao usuário para abrir esse arquivo.
5. Peça ao usuário para escolher um, ou para combinar partes ("o tipo do A com as cores do C"). Se ele pediu para você decidir, escolha o que melhor se adequa ao produto e explique o motivo em uma frase.

Quando a marca é fixa, as três direções usam as cores e fontes da marca e diferem em layout, escala e densidade.

4. Escreva o sistema

• Salve o sistema escolhido como DESIGN.md na raiz do projeto. Mantenha seu formato: front matter YAML com tokens, depois Visão Geral, Cores, Tipografia, Layout, Formas, Componentes e O que Fazer e Não Fazer.
• Aplique quaisquer alterações solicitadas pelo usuário (uma cor da marca, uma fonte de título diferente) ao arquivo, não apenas ao código.
• Adicione uma linha ao AGENTS.md (e ao CLAUDE.md se o projeto tiver um): Siga DESIGN.md para todas as telas: cores, tipo, espaçamento, raio e componentes. O Codex lê AGENTS.md automaticamente, mas não DESIGN.md.
• Para projetos shadcn ou Tailwind, mapeie os tokens nas variáveis de tema (--background, --primary, --radius e as demais). Cada página de sistema linka um tema shadcn pronto: npx shadcn@latest add https://codexdesign.io/r/<slug>.json.

5. Aplique, passagem por passagem

Trabalhe em toda a tela uma camada de cada vez, como uma revisão de designer. Mantenha os recursos, conteúdo e ordem das seções, a menos que o usuário peça o contrário.

1. Tokens. Substitua cores, tamanhos e raios codificados manualmente pelos tokens do sistema.
2. Tipo. No máximo duas famílias. Use a escala do sistema. Faça a linha mais importante da tela ser claramente a maior. Use figuras tabulares para números que se alinham.
3. Espaçamento e layout. Uma unidade de espaçamento do sistema e seus múltiplos. Alinhe tudo ao grid ou ao padding da tela. Agrupe itens relacionados de forma compacta e separe grupos generosamente.
4. Cor. Neutros carregam a tela. A cor primária aparece onde o usuário age, aproximadamente uma vez por visualização. Gráficos usam as cores do sistema na ordem.
5. Componentes. Botões, inputs, cartões, listas e navegação seguem a seção de Componentes do sistema. Ícones reais (Lucide, Phosphor, SF Symbols, Material Symbols), nunca emoji como ícone.
6. Cópia. Palavras simples e específicas do produto. Corte palavras de enchimento ("sem interrupções", "desbloquear", "acelerar"). Títulos dizem o que a coisa é ou faz.
7. Detalhes. Estados de hover, foco e pressionado; estados vazio, carregando e erro; contraste de pelo menos 4.5:1 para texto.
8. Movimento. Apenas onde explica algo: uma mudança de estado, uma transição entre telas. Sem fade-in em cada seção, sem decoração pulsante.

Para aplicativos móveis, leia também references/app.md.

6. Verifique

• Execute o verificador novamente nos arquivos alterados e corrija todos os erros e tantos avisos quantos fizerem sentido.
• Olhe o resultado. Se Playwright ou uma ferramenta de navegador estiver disponível, tire uma captura de tela com 1440 e 390 de largura (ou o tamanho do dispositivo para aplicativos) e corrija o que parece errado: sem ponto focal, grupos apertados, texto que quebra mal, contraste baixo.
• Para um redesign, escreva uma página de antes e depois que o usuário possa compartilhar:

node <skill>/scripts/compare.mjs before.html after.html --labels "Antes,Depois" --out pretty-ui/antes-depois.html

7. Relate

Diga ao usuário, de forma breve: a direção escolhida e o motivo, os arquivos alterados, o que o verificador encontrou antes e depois, e qualquer coisa que ainda precise de decisão dele (fotos reais, um logotipo, texto que só ele pode escrever).

Regras que sempre se aplicam

• Mostre opções antes de se comprometer com uma. Nunca escolha um estilo silenciosamente.
• Mantenha a marca, o conteúdo e a stack do usuário.
• Um sistema de design por produto, escrito em DESIGN.md, seguido em todos os lugares.
• Sem gradientes roxos ou violetas, texto gradiente, painéis glassmorphism, sombras brilhantes, ícones emoji, selos de pílula acima de cada título ou linhas de cartões de ícone idênticos, a menos que o usuário explicitamente os queira.
• Não troque um clichê por outro. Creme com uma serifa e um acento terracota, ou quase preto com um acento verde-ácido, são os novos padrões; use-os apenas quando o universo do produto os pedir.
• Remover decoração é metade do trabalho. Preencha o espaço com conteúdo real, tipo maior para o que importa, e um elemento memorável tirado do próprio produto.

Arquivos

• references/systems.md: os 24 sistemas de design, com plataforma, estilo e URL do DESIGN.md.
• references/tells.md: o que faz uma UI parecer feita por IA, e o que fazer em vez disso.
• references/app.md: regras para telas de aplicativos iOS, Android e multiplataforma.
• scripts/check.mjs: um verificador estático para marcas de IA em arquivos HTML, CSS, JSX, TSX, Vue e Svelte. Node 18+, sem dependências.
• scripts/compare.mjs: escreve uma página HTML que mostra várias telas lado a lado, para escolher uma direção ou mostrar antes e depois.