bruno-baeta/clean-ui

Clean UI

Interface minimalista, moderna, com tema claro e escuro, que cabe na tela, com dados em primeiro lugar e cara de produto feito por gente, não por IA. As regras abaixo vieram de pedidos reais de ajuste. Cada uma já irritou o usuário quando foi quebrada: trate como requisito, não como sugestão.

Arquivos da skill

Caminhos relativos à pasta desta skill.

Arquivo	Quando usar
references/informacao.md	Toda tela nova ou redesign, antes do layout. Como escolher o que mostrar, a ordem de prioridade e a posição de cada informação (inventário, perguntas do usuário, níveis, filtro, mapa de posições, plano escrito).
references/padroes-aprovados.md	Blocos que o usuário aprovou ("ficou bem melhor"): cartão de decisão, gráfico da medida da decisão com a linha do limite, cartão de situação com saldo ao longo do tempo, lista do próprio usuário, apoio sazonal, cabeçalho do celular, ordem por prioridade, ultrawide. Use como ponto de partida para o conteúdo, não como esqueleto fixo.
references/armadilhas.md	Erros técnicos que já custaram retrabalho (Tailwind v4, cn sem merge, especificidade de [&>*]:, next-themes, servidor com CSS velho, testar estados que o banco local não tem). Leia antes de escrever o código.
references/migracao.md	Redesenhar o app inteiro (várias telas): tela de referência aprovada primeiro, base feita por você (moldura, peças de página, tokens no body, tema salvo), frentes paralelas com brief comum, integração (pedidos para o kit, apagar código antigo só no fim, reiniciar, verificar tudo).
references/exemplos.md	Casos reais de errado e certo. Leia ao criar uma tela nova ou quando estiver em dúvida se algo está bom.
references/dashboards.md	Toda tela com números, gráficos ou mapas. O que separa amador de profissional, princípios (NN/g, Stephen Few, IBM Carbon), 7 composições (escolha a que serve ao plano de informação), regras para telas largas e ultrawide, cor e acabamento dos gráficos.
references/paletas.md	Paletas prontas e validadas (Cobalto, Índigo, Ciano, Coral) com cinzas, destaque, escala ordenada e cores de séries para os dois temas. Escolha por aqui, nunca cores soltas.
assets/tokens.css	Projeto novo ou sem identidade: tema claro e escuro (segue o sistema, com troca manual), fonte, foco, gráficos e toque já configurados (Tailwind v4). Vem com a paleta Cobalto só como ponto de partida: troque pelo bloco completo da escolhida (fim de paletas.md). Inclui a variante tall, positivo/negativo/aviso e a mãozinha.
references/exemplos-dashboards/	As 7 referências do usuário de dashboard moderno. Abra todas antes de desenhar qualquer dashboard.
references/anatomia-dashboard.md	As referências traduzidas em medidas: cartão, título, indicador, chips, números no topo do gráfico, gráficos, partes de um todo, medidor, tabela, celular, e o que não copiar.
assets/dashboard.tsx	Kit de dashboard medido nas referências: DashCard, Kpi, IconCircle, DeltaChip, StatusChip, TrendDot, CountBadge, Tabs, SeriesStat, StatColumns, Dashed, KeyValue, StackedBar, LegendGrid, Gauge, classes TH/TR de tabela, TooltipCard, PillMark, props chart para Recharts, ListaAlta (a lista num cartão vertical, com páginas pela altura), Divergentes (o que somou e o que tirou), Quadro100 (de cada 100), Colunas (colunas flutuantes; cascata e funil foram reprovados como difíceis), useFitRows (quantas linhas cabem) e useFitHeight (altura de um gráfico pelo que sobra da janela; mede de novo quando o cartão de cima cresce).
assets/painel.tsx	Ajudantes de mapa: useMapColumns (largura da coluna do mapa) e FillMap (mapa-múndi que preenche).
assets/ui.tsx	Componentes base prontos (Card, Section, IconBox, Chip, Pill, Button, BottomActions, ListRow, ListCard, StatCard, DateBlock, FillEmpty, InfoTip, NavLoading, Spinner, ThemeToggle, FitScreen). Reaproveite ou adapte em vez de inventar. Se o projeto já tem equivalentes, use os do projeto.
scripts/lint-ui.mjs	node <skill>/scripts/lint-ui.mjs src: varre o código alterado (hover que move, reticências, bordas coloridas, largura estreita, fontes proibidas, cor fixa que quebra um dos temas, "—", " · ", minúscula, "Rótulo: valor").
scripts/check-ui.mjs	node <skill>/scripts/check-ui.mjs http://localhost:3000/rota --out=prints: tira prints em 320 e 390 px (mobile) e na área útil do navegador em 1366×650, 1536×730 e 1920×950 (notebooks e monitor) e 2560×960, 2752×1100 (21:9 com zoom de 125% do Windows) e 3440×1300 (ultrawide 21:9), nos temas escuro e claro, e mede estouro horizontal e vertical (cartão passando da borda de baixo da primeira tela ou mais alto que a tela), listas parecidas repetidas, gráfico esticado e linha de lista larga demais, "…", cartões vizinhos com alturas diferentes (também dentro de invólucro sem fundo), cartão com vão vazio por dentro ou conteúdo espalhado, grid incompleto, ícone sem container, hover que move, scroll interno, conteúdo estreito, fonte, clicável sem mãozinha, bordas de cartões quase alinhadas entre linhas, balão do "i" fora da tela (abre cada um), barra de rolagem no celular, linha de tabela larga demais (qualquer linha repetida), texto espremido, linha de lista com título ou descrição quebrando no celular e página vazia ou de erro (espera o carregamento; se os dados não vieram, o check não vale). Cada achado vem com tamanho e tema. Precisa de Playwright no projeto; --user/--pass para páginas com senha.

Os scripts são guias: confira cada achado e, principalmente, abra os prints e olhe.

1. Processo (o que mais causa retrabalho)

1. Faça só o que foi pedido. Nunca remova, troque ou "simplifique" elementos existentes sem pedido explícito. Se a proposta exige tirar algo, pergunte antes. Na dúvida, mantenha.
2. Respeite o breakpoint pedido. Pediu ajuste no mobile: o web não muda (use sm:/md: para preservar o web, e vice-versa).
3. Mostre antes de publicar, olhando todos os tamanhos. Antes de dizer que está bom, abra o print de cada tamanho do check (inclusive 1366, 1536 e 2752, onde tabela quebra e cartão sobra), não só 390 e 1920. Trabalho de agente delegado também: confira você mesmo. Rode localmente, tire print no mobile (390 px, e confira 320 px) e no web (1366×650, 1536×730 e 1920×950, a área útil real do navegador), nos dois temas, olhe de verdade cada print e só faça commit/push/deploy com aprovação explícita.
4. Tela nova ou redesign: primeiro as informações, depois o layout. Siga references/informacao.md (e veja os blocos de references/padroes-aprovados.md e os erros de references/armadilhas.md): inventário do que o produto sabe (inclusive tudo que a tela antiga mostrava), perguntas do usuário em ordem de urgência, níveis de prioridade, filtro de cada informação, mapa de posições e o plano escrito. A composição sai desse plano. Escolha você a composição e a paleta (a da marca, se o projeto tiver; senão a de paletas.md que combina com o assunto). Não monte várias versões ou visões da tela para o usuário escolher. Construa uma, a melhor, e diga em poucas linhas por que cada coisa está onde está. Nunca parta do esqueleto de um projeto anterior nem repita "4 indicadores + grade de cartões + listas" por padrão.
5. Detalhe reprovado duas vezes = opções lado a lado. Só quando o usuário já reprovou o mesmo detalhe (posição de um chip, fonte) duas vezes, mostre 2 ou 3 variações desse detalhe em print. Nunca para a tela inteira.
6. Depois de apagar ou recriar arquivos, reinicie o servidor de desenvolvimento (ou salve o CSS de novo) antes do check: o Tailwind pode continuar servindo o CSS antigo, sem as classes novas.
7. Revise com a checklist (seção 10) antes de cada print. Se não houver simetria, não está pronto.

2. Tipografia

• Proibidas (cara de IA): Inter, Roboto, Arial, Helvetica, system-ui como fonte de marca, Geist, Poppins, Montserrat, Space Grotesk, Open Sans, Lato.
• Boas e pouco usadas por IA: Plus Jakarta Sans (preferida e já aprovada), Manrope, Onest, Figtree, Hanken Grotesk, Schibsted Grotesk, Instrument Sans, Albert Sans, Familjen Grotesk. Para títulos de destaque, Bricolage Grotesque. Uma família só por app.
• Números com font-variant-numeric: tabular-nums (tabular-nums). Nada de fonte mono com zero cortado ou pontilhado.
• Hierarquia por peso e tamanho moderados. Rótulo pequeno em cima (12 px, cor apagada) e valor embaixo (16 px, semibold). Valores lado a lado com o mesmo tamanho de fonte. Nada de texto gigante colorido.
• Todo texto visível começa com maiúscula, inclusive abreviações soltas ("Qui", "Sex"). No meio de uma frase, escreva normal: "Vs terça anterior", não "Vs Ter anterior". Títulos em sentence case, nunca CAIXA ALTA.

3. Cor e tema

• Sempre dois temas, claro e escuro. Todo app nasce com os dois: segue o tema do sistema (prefers-color-scheme) e tem um botão para trocar (ThemeToggle em assets/ui.tsx), com a escolha salva. E-mails e prévias também respondem a prefers-color-scheme. Nenhuma tela pode existir só num tema.
• Cores sempre por token (var(--card), bg-card, text-muted-foreground). Nada de #000, #fff, bg-black, text-white ou hex solto em componente, gráfico ou SVG: isso quebra o outro tema.
• Escuro: fundo bem escuro (perto de preto), cartão um degrau acima, borda discreta, texto quase branco. Claro: fundo cinza muito claro, cartão branco, borda leve, texto quase preto. Os dois com o mesmo cuidado e conferidos em print.
• Paleta não é fixa, mas também não é solta. Não existe "preto + laranja" padrão: use uma paleta inteira de references/paletas.md (cinzas, destaque, escala e séries que combinam e já foram validadas para contraste e daltonismo), escolhida pelo assunto e mostrada renderizada. Nada de juntar cores avulsas (o azul de um lugar, o amarelo de outro, o vermelho de outro). Projeto com marca segue a sua (ex.: o MegaLab escolheu laranja); cor nova só com contraste de pelo menos 3:1 contra o cartão nos dois temas e distinguível para daltônicos (se o agente tiver o guia dataviz, use o validador dele).
• Base neutra, cor com propósito. Cinzas fazem ~90% da tela. Uma cor de destaque por app (versão por tema). Dado ordenado (magnitude, nível, faixa) usa a escala de uma cor só (--seq-1..4), nunca arco-íris de cinza, azul, amarelo e vermelho. Séries sem ordem usam --cat-1..3 em ordem fixa. Vermelho/amarelo de alerta só para status de verdade, com ícone e rótulo. Verde nunca é cor de marca, mas pode aparecer em dado: chip de variação "melhorou", status bom e a série categórica 3 das paletas validadas. Sem roxo aleatório, sem marrom.
• Número nunca pintado. Valores e rótulos ficam na cor do texto; a cor do dado vai numa marca pequena ao lado (ponto, barra fina, selo neutro com barrinha colorida).
• Variação para melhor e para pior (como nas referências do usuário): chip verde suave e chip vermelho suave, sempre com seta para quem não distingue as cores (DeltaChip). Igual: chip cinza.
• Estados parecidos (ex.: Errei, Difícil, Bom, Fácil) precisam de cores claramente diferentes entre si.
• Sem bordas ou anéis coloridos para destacar cartões. Destaque só com fundo suave da cor (bg-primary/10).
• Texto sempre legível nos dois temas, inclusive legendas e tooltips de gráficos depois de clicados.

4. Layout e simetria

• Largura total no web. Nada de conteúdo estreito centralizado (max-w-* + mx-auto na página). Use grid para ocupar a tela.
• Tela larga ganha colunas, não esticar. De 1920 px para cima e em ultrawide 21:9 (2560 e 3440 px), aumente o número de colunas com 3xl: (1920 px) e 4xl: (2560 px), definidos no tokens.css; nunca min-[1920px]: (no Tailwind v4 ele perde para lg:), abra painéis que antes ficavam escondidos (detalhe ao lado, tabela ao lado do gráfico) e limite a proporção: gráfico de tempo até ~4:1, barras e mapas até ~2,5:1, linha de lista até ~720 px. Veja references/dashboards.md seção 4.
• Mobile first. Espaçamento lateral confortável (16 px), nada apertado, carrossel com respiro horizontal, primeiro item com espaço em cima.
• Cabe na altura da tela. O conteúdo se adapta à janela nas duas direções, não só à largura. Nenhum mapa, gráfico, imagem ou cartão de tamanho fixo passa da borda de baixo da primeira tela nem é mais alto que a janela (só listas continuam abaixo, rolando a página): mapas, gráficos e imagens grandes têm a altura limitada pela janela (max-h-[calc(100dvh-<cabeçalho>)], h-[min(…,60dvh)], SVG com preserveAspectRatio="xMidYMid meet" dentro de um container de altura definida). Nunca dimensione um visual largo só pela largura (w-full h-auto, aspect-[2/1]): num monitor largo ou num notebook ele estoura para baixo. A primeira tela (cabeçalho, indicadores e o bloco principal) cabe inteira em 390×844, 1366×650, 1536×730 e 1920×950 (área útil do navegador, já descontadas as barras; a tela inteira não serve de medida). Use FitScreen de assets/ui.tsx.
• Tela sempre preenchida. O último bloco estica até o fim (flex-1). Sem metade da tela vazia: use conteúdo real ou um estado vazio visual (ícone em container + 1 linha).
• Simetria é obrigatória:
  • cartões lado a lado com a mesma altura (items-stretch, h-full), e o conteúdo interno (gráfico, tabela) cresce junto e ocupa toda a altura;
  • mesmo número de linhas de texto à esquerda e à direita;
  • cartão esticado pela grade não fica com vão por dentro: linhas de lista com altura fixa e o bloco (título + linhas) centralizado na vertical, nunca justify-around/justify-between espalhando as linhas; colunas comparáveis (A x B) com a mesma altura de linha, para as linhas se alinharem (ver references/armadilhas.md, "Cartão que estica");
  • linhas do grid completas (sem 3 + 1 sobrando);
  • na mesma coluna, itens e chips com a mesma largura;
  • colunas de