Design & UI
Crie interfaces que pareçam intencionais e premium, não genéricas como templates. Esta é a maior alavanca de qualidade no construtor de aplicativos. Aplique-a à UI DOM / sobreposição — páginas, chrome, HUD, menus, formulários. (Para o canvas de gameplay de um jogo 3D, veja a skill building-games; esta skill governa a UI DOM sobreposta a ele.)
Leia references/ para aprofundamento (carregado sob demanda — não inclua tudo inline):
references/refined-ui.md— o sistema de design completo de produto-chrome/sobreposição.references/typography.md— escala tipográfica, pares, ritmo.references/surfaces.md— elevação, bordas, sombras, camadas.references/animations.md— movimento, easing, transições.references/performance.md— mantenha a UI fluida (60fps, sem travamentos).
1. Design-system-first (faça isso antes de estilizar qualquer coisa)
Defina o sistema uma vez, depois componha a partir dele. Nunca espalhe valores avulsos.
- Tokens no CSS (Tailwind v4 é CSS-first). Coloque a paleta, raios e fontes em
src/styles.cssdentro de@themecomo variáveis CSS; consuma-os como utilitários do Tailwind. Uma única fonte da verdade.@import "tailwindcss"; @theme { --color-bg: #0b0b0f; --color-surface: #16161d; --color-fg: #e7e7ea; --color-muted: #a0a0ab; --color-primary: #14b8a6; --color-border: #26262f; --radius: 0.75rem; --font-sans: "Inter", system-ui, sans-serif; } - Use componentes shadcn/ui (primitivas Radix + variantes
cva+tailwind-merge) para botões, diálogos, dropdowns, inputs, etc. Eles são acessíveis e consistentes. Gere-os emsrc/components/ui; estilize através de tokens, não hex inline. - Correção de base do Tailwind v4 — botões precisam de cursor pointer. O Preflight do v4 faz
<button>usarcursor: default, o que parece quebrado. Adicione isso uma vez emsrc/styles.csspara que botões/roles clicáveis mostrem um pointer:@layer base { button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer; } } - Proíba estilização avulsa: sem hex puro no JSX, sem literais
text-white/bg-black, sem valores arbitrários comop-[16px]outext-[13px]. Se precisar de um valor, ele vira um token ou um degrau de escala.
2. A rubrica quantificada (regras baratas que previnem o "feio")
- ≤ 3–5 cores no total (uma primária + neutras + no máximo um acento). Sem matizes extras aleatórios. Não use roxo como padrão a menos que seja solicitado.
- ≤ 2 famílias de fontes (geralmente uma). Combine uma fonte de exibição/título com uma de corpo, ou use apenas uma.
- Altura de linha 1.4–1.6 para corpo; mais justa para títulos grandes.
- Quando sobrescrever uma cor de fundo, sobrescreva também a cor do texto/primeiro plano (o contraste deve ser mantido — verifique tanto no modo claro quanto no escuro).
- Mobile-first: projete primeiro o layout de ~390px, depois escale. Sem overflow horizontal; alvos de toque ≥ 44px.
- Escala de espaçamento consistente (baseada em 4/8). Espaço em branco generoso é melhor do que apinhamento.
- Um acento, usado com moderação para ações primárias — não em todo lugar.
3. Anti-AI-slop (os sinais que fazem o resultado parecer genérico — evite)
- Sem preenchimento de gradiente-blob, sem gradientes enormes de herói como substituto de conteúdo.
- Sem emoji como ícones — use um conjunto de ícones real (
lucide-react). - Sem ilustrações SVG desenhadas à mão / mapas / gráficos — use bibliotecas reais (
rechartspara gráficos) ou imagens geradas reais. - Sem imagens placeholder / caixas cinza lorem no produto final — gere imagens reais ou use conteúdo real; defina
crossOrigin="anonymous"em imagens de canvas. - Evite a aparência de fonte excessivamente usada (apenas sistema padrão, ou escolhas no nível Comic Sans).
- Cada elemento ganha seu lugar. Corte ruído decorativo. Estabeleça um sistema, depois varie com intenção — não aleatoriedade.
- Combine com a UI existente ao editar um aplicativo no local; não introduza uma segunda linguagem visual.
4. Layout & hierarquia
- Hierarquia visual clara: uma ação primária por visualização; tamanho/peso/cor expressam importância. Veja
references/typography.mdereferences/surfaces.md. - Use estrutura de layout real (grid/flex, larguras máximas de contêiner), não hacks de posicionamento absoluto. Alinhe a uma grade consistente.
- Estados vazios, de carregamento e de erro fazem parte do design — não entregue estados intermediários em branco/com problemas.
5. Movimento (sutil, proposital)
- Transições curtas e suaves (150–250ms) ao passar o mouse/pressionar/entrar; respeite
prefers-reduced-motion. Detalhes emreferences/animations.md. - Nunca anime o layout de forma que cause travamento; prefira transform/opacity.
6. Sobreposições de jogos (quando combinado com building-games)
O canvas do jogo é de responsabilidade do building-games. Esta skill estiliza a sobreposição DOM: tela inicial/"clique para jogar", HUD, pontuação, menus, pausa, controles mobile. Mantenha a sobreposição legível sobre o canvas (fundo, contraste) e fora do caminho de entrada do pointer-lock/gameplay.
Checklist de finalização (antes de considerar a UI pronta)
- Tokens definidos em
@theme; sem hex avulso / valores arbitrários no JSX. - ≤ 5 cores, ≤ 2 fontes, escala de espaçamento consistente.
- Contraste mantido; primeiro plano sobrescrito onde o fundo é.
- Mobile (~390px) sem overflow; alvos ≥ 44px.
- Ícones/imagens/gráficos reais — nenhum dos sinais de AI-slop.
- Estados de carregamento/vazio/erro tratados; movimento sutil e seguro para reduced-motion.
- Renderizado e inspecionado visualmente em um navegador (veja verificação em AGENTS.md), não apenas curl.