O que ui-craft faz?
Como construir interfaces que parecem premium e são fáceis de usar, em qualquer plataforma. Os números estão em px CSS; para apps nativos leia px como pt (iOS, macOS), dp (Android) ou epx (Windows).
Premium significa quatro coisas. Apropriado: adequa-se ao público, seu estado de espírito e à plataforma. Decidido: um sistema pequeno (poucos tamanhos, uma família de raios, um acento) aplicado em todos os lugares. Artesanal: os detalhes são finalizados. Honesto: conquista confiança e nunca engana. Uma tela que é apenas correta parece genérica; uma tela que é apenas decorada parece barata.
1. Fluxo de trabalho (faça isso toda vez)
- Olhe antes de construir. Verifique se existe um sistema de design: tokens, arquivo de tema, configuração do Tailwind, biblioteca de componentes, cores da marca, fontes ou um
DESIGN.mdetheme.cssexportados do ui-craft Studio. Se existir, use-o; não invente um segundo. Preencha apenas as lacunas. - Entenda a pessoa. Quem usa isso, em que estado de espírito (apressado, ansioso, cético, especialista em fluxo), e o que eles devem sentir? Uma linha. Veja
references/psychology-emotion.md. - Escolha uma direção. Sem uma identidade definida, escolha uma direção visual de
references/directions.mdque se adeque ao público (não por novidade), leia o cabeçalho do arquivo dela emassets/directions/e anote sua assinatura. Com uma cor de marca definida, mantenha a direção e recrie as cores:node <skill-dir>/scripts/palette.mjs --accent "#HEX". Quem prefere escolher visualmente pode usar o ui-craft Studio (https://najeebafridi.github.io/ui-craft/): escolha uma direção, ajuste em telas ao vivo e exportetheme.csse umDESIGN.mdpara você seguir. - Escreva o resumo de design antes do código (na sua resposta ou em um comentário):
Produto: folha de pagamento para pequenas empresas (app web, desktop primeiro) Usuário e sentimento: proprietário fazendo folha de pagamento à noite, ansioso com erros -> seguro, guiado, exato Direção: Livro-razão de confiança; acento verde-marinho profundo (marca deles), neutros frios, tema claro Tipo: IBM Plex Sans + Mono, corpo 14px, números tabulares Forma e profundidade: raio 6px, sombras suaves Densidade e movimento: compacto, nítido (120-200ms) Plataforma: web responsiva Assinatura: números dispostos como um livro-razão; confirmações informam o valor exato e a hora Tarefa principal nesta tela: revisar a execução deste mês e aprová-la - Construa a estrutura primeiro, depois o estilo. Layout e hierarquia com conteúdo real, depois o sistema (tokens), depois o detalhe. Sem lorem ipsum: escreva nomes, números e textos realistas. Construa a assinatura cedo e mantenha todo o resto mais quieto que ela. Mostre funcionando. A primeira vista é a tela em uso: dados reais, padrões sensatos já selecionados, a interação principal visível. Nunca abra em um estado vazio ou bloqueado, um total morto de "$0" ou uma etapa chave oculta até que uma anterior seja concluída.
- Projete cada estado: carregamento, vazio, erro, sucesso, texto longo, muitos itens, um item, sem permissão (
references/feedback-states.md). - Finalize e verifique. Faça a passada de finalização em
references/premium-craft.md. Em seguida, olhe para o resultado: com Node e Chrome disponíveis, executenode <skill-dir>/scripts/ui-audit.mjs page.html. Ele pontua contraste, tamanhos, alvos de toque e estouro em 1440px e 390px, anota problemas de acabamento e salva capturas de tela. Abra ambas as capturas e julgue a do telefone com a mesma rigidez que a do desktop: nada cortado, coberto ou espremido, o conteúdo chave na primeira tela. Verifique se a tela conta uma história: o resumo corresponde à seleção, os totais somam, as contagens combinam com as listas, as datas concordam. Corrija o que ver, então remova qualquer coisa que não ajude a tarefa principal. Lista de verificação:references/review-checklist.md.
Mockups rápidos para um cliente: references/mockups.md. Revisando ou pontuando um produto existente: references/review-mode.md.
Camadas sobre o mesmo tema. Para cenas 3D, shaders, storytelling com scroll ou movimento cinematográfico, use o skill immersive-web (mesmo plugin): ele lê esses mesmos tokens, e o nível --immersive do tema (0 parado a 3 história) indica até onde ir. Para pegar emprestado o visual de outro gênero ou mídia (jogo, ficção científica, filme) leia references/mixing.md.
2. Densidade por tipo de produto
| Produto | Texto do corpo | Densidade | Navegação |
|---|---|---|---|
| Ferramenta de dados, admin, ferramenta dev, finanças | 14px | compacta: linhas 36px, controles 32-36px | barra lateral esquerda 220-280px |
| SaaS web app | 14-16px | padrão: controles 36-40px | barra lateral ou barra superior |
| Dashboard, analytics | 14px | compacta | barra lateral + barra de filtros |
| Marketing, landing page | 16-18px | espaçosa: seções com 64-96px de distância | barra superior, 4-6 links + 1 ação |
| App mobile | 16-17px | toque: alvos com 44px ou mais | barra de abas inferior, 3-5 itens |
| App desktop | 13-14px (padrão da plataforma) | compacta | barra lateral + barra de ferramentas; siga o SO |
| Consumidor, divertido | 16px | padrão | por plataforma |
O texto do corpo padrão é 16px; 14px apenas em ferramentas desktop densas. Nunca abaixo de 12px. Densidade compacta é só para mouse e teclado: em telas sensíveis ao toque, todo controle cresce para 44px (§13).
3. Hierarquia (a maior vitória)
- Um herói e uma ação primária por tela. A ação primária é o único botão de acento sólido; outros são botões de contorno, sutis ou de texto.
- Construa hierarquia com tamanho, peso e cor juntos. Para destacar o título, acalme os rótulos e o texto meta em vez de aumentar o título.
- Rótulos são mais quietos que valores. Em "Receita $48.210", o rótulo é 12-14px suave e o valor 24px seminegrito.
- Agrupe por espaçamento primeiro, depois tom de fundo, depois uma linha, por último uma sombra. A distância entre grupos é pelo menos o dobro da distância dentro deles. Menos caixas e linhas parecem mais caras.
- A ordem de leitura corresponde à importância: a tarefa principal fica no canto superior esquerdo (em idiomas da esquerda para a direita) ou no centro.
4. Layout e espaçamento
- Escala de espaçamento (base 4px): 4, 8, 12, 16, 24, 32, 48, 64, 96. Apenas estas.
- Dentro de um componente 4-12; entre componentes 16-24; entre seções 32-48 (apps), 64-96 (marketing).
- Padding lateral da página: 16px mobile, 24px tablet, 32px ou mais desktop. Largura máxima do conteúdo 1200-1440px (apps), 1120-1280px (marketing); texto de leitura 65-75 caracteres.
- Faça o layout com grid ou flex e
gap. Alinhe em ambos os eixos: vizinhos compartilham bordas esquerdas e linhas de base. Quase-acertos parecem amadores. - O padding externo é pelo menos o gap interno. Quando em dúvida, adicione espaços em branco e remova uma borda.
- Sem espaço morto. Não estique um card para igualar um vizinho mais alto (
align-items: start), e não deixe um painel quase vazio: dê a ele conteúdo real, encolha-o ou remova-o. - Densidade é uma decisão: espaçosa ou compacta, sempre exata. Breakpoints 640, 1024, 1440; verifique 375 e 1440 no mínimo.
Detalhes: references/layout-spacing.md.
5. Tipografia
- Escala tipográfica: 12, 14, 16, 18, 20, 24, 30, 36, 48, 60 (maior apenas para display). 4-6 tamanhos por tela de app, até 7 em uma página de marketing.
- As fontes vêm da direção ou da marca: uma família para apps, no máximo duas (uma face de display para títulos mais uma face de texto neutra). Nunca uma fonte por ser a padrão. Todas as fontes sugeridas são gratuitas (SIL OFL).
- Ajuste o tipo para seu tamanho. Altura da linha 1.5 para corpo, 1.2-1.3 para títulos, 1.05-1.15 para display. Espaçamento entre letras: 0 em 14-16px, cerca de -0.015em em 20-24px, -0.025em em 30-36px, -0.03 a -0.04em em 48px e acima; +0.06em em rótulos pequenos em CAIXA ALTA.
- Pesos: 400 corpo, 500 rótulos e botões, 600 títulos; 700+ apenas para display grande. No máximo 3 por tela. O peso nunca muda ao passar o mouse.
text-wrap: balanceem títulos,prettyem parágrafos.font-variant-numeric: tabular-numsem todo número que muda ou se alinha; números alinhados à direita em tabelas.- Frase padrão para títulos, botões e rótulos. Aspas, travessões e reticências reais.
Detalhes: references/typography.md.
6. Cor
- Escolha o sentimento primeiro. Clareza e saturação mudam como uma tela se sente mais do que o matiz: mais claro é mais agradável, mais saturado é mais excitante, baixa saturação com contraste forte é calmo e sério. Então escolha o matiz para significado, adequação à categoria e diferença dos concorrentes.
references/color-theory.md. - Uma paleta é neutros matizados + um acento + cores de estado (sucesso, aviso, perigo, informação). Os neutros carregam um traço de cor (quente, frio ou o matiz da marca), nunca cinza morto; sem preto ou branco puro para grandes áreas.
- Principalmente neutro. O acento cobre cerca de 5-10%: botão primário, links, seleção, foco, dados chave. Alta saturação apenas em pontos pequenos e valiosos.
- Construa com
scripts/palette.mjs(OKLCH, claro + escuro, cada texto e cor de borda resolvida para passar no contraste) ou tire de uma direção. Nunca invente valores hex a olho. - Apenas tokens semânticos em componentes:
--bg,--surface,--surface-2,--border,--border-strong,--text,--text-muted,--text-subtle,--accent,--accent-fg,--accent-soft,--accent-text,--focus,--danger… Cada superfície tem seu parceiro de primeiro plano. - Piso de contraste (WCAG 2.2 AA): 4.5:1 para texto, 3:1 para texto grande (24px+, ou 18.66px+ negrito) e para partes da UI (bordas de input, ícones, anéis de foco, marcas de gráfico). Divisores podem ser fracos; bordas de input usam
--border-strong. - Nunca cor sozinha para significado: adicione um ícone, texto ou forma. Cores de estado permanecem separadas da cor da marca; uma marca vermelha nunca funciona como cor de erro.
- O modo escuro é sua própria paleta: superfícies matizadas quase pretas, superfícies elevadas mais claras, texto quase branco, acento mais calmo. Ofereça ambos os temas e siga o SO.
Detalhes: references/color-theory.md, references/color-dark-mode.md. Tokens: assets/tokens.css, assets/directions/.
7. Luz, profundidade e forma
- Uma fonte de luz, de cima, em todos os lugares. Apenas três níveis: plano, elevado (
--shadow-raised), sobreposição (--shadow-overlay). - Sombras são em camadas e matizadas: várias camadas finas, nunca um borrão cinza. Mais alto significa maior, mais suave, mais fraco.
- Cards e menus usam um anel de 1px na sombra em vez de uma borda; botões sólidos ganham um destaque interno superior fraco (
--shadow-button). - Uma família de raios. O raio cresce com a elevação (controles, depois cards, depois folhas). Cantos aninhados são concêntricos: raio interno = raio externo menos o padding entre eles.
- Em temas escuros, a profundidade vem de superfícies mais claras e do anel, não de sombras.
- Uma técnica de profundidade por produto (fino, suave, nítido, difuso, plano ou lábio, definido pela direção). Sem brilho, sem sombra em todo card.
- Desfoque e transparência pertencem apenas ao chrome (um cabeçalho fixo, uma folha, materiais do sistema), nunca a cards de conteúdo.
Detalhes: references/premium-craft.md.
8. Componentes
- Todo elemento interativo tem estados: padrão, hover, focus-visible, pressionado, desabilitado; carregando para botões; selecionado para linhas e alternâncias. Hover nunca é a única pista.
- Botões e inputs: 40px padrão, 32-36px compacto, 44-48px toque. Padding horizontal cerca do dobro do vertical. Rótulo = verbo + objeto ("Criar fatura"). Botões apenas com ícone precisam de
aria-labele uma dica. - Anel de foco sempre visível para usuários de teclado: 2px
--focus, 2px de deslocamento. Nuncaoutline: nonesem um substituto. - Inputs: rótulo visível acima (um placeholder não é um rótulo), borda
--border-strong, texto de ajuda abaixo, erro abaixo com ícone e palavras. Formulários longos adicionam um resumo de erros no topo. - A ação principal de um formulário (Salvar, Continuar) é visível desde o início. Ela pode parecer mais quieta até que algo mude; nunca aparece apenas após uma edição.
- Uma chave de alternância entra em vigor imediatamente; uma caixa de seleção aplica ao salvar.
- Cards apenas para coisas separadas e comparáveis. Não ao redor de cada seção; nunca cards dentro de cards.
- Ícones: um conjunto, uma espessura de traço, dimensionados para o texto ao lado. Nunca emojis como ícones.
- Imagens: conteúdo real,
aspect-ratiofixo,altsignificativo, um contorno interno de 1px. Sem serviços de placeholder. Sem foto real ainda, use um bloco tonal quieto no corte final com uma pequena legenda ("Fotografia: sala de jardim"); nunca um desenho grosseiro do assunto, que barateia tudo ao redor. - Modais apenas para tarefas curtas e focadas; prefira edição inline ou um painel lateral.
- Ações destrutivas: cor de perigo, nomeada ("Excluir projeto"), confirmada ou desfeita. Desfazer vence confirmar para ações frequentes.
references/forms.md, references/tables-lists.md, references/navigation.md, references/dashboards-charts.md.
9. Estados de feedback
- Reconheça cada pressionamento em até 100ms. Mostre um spinner ou esqueleto apenas após ~300ms, então mantenha por ~500ms.
- Esqueletos para carregamentos de página ou seção com layout conhecido; um spinner dentro de botões e widgets pequenos; uma barra de progresso com % após ~10s.
- Estado vazio = o que é isso + por que está vazio + uma ação. Erro = o que aconteceu + como corrigir, em palavras simples, onde aconteceu; nunca limpe a entrada do usuário.
- Sucesso é quieto e específico ("Fatura 1042 enviada para Ana, 14:02"). Toast por 4-6s, nunca a única cópia de informações importantes.
- Atualize otimisticamente onde for seguro, com desfazer em caso de falha. Velocidade é lida como qualidade.
Detalhes: references/feedback-states.md.
10. Emoção e confiança
- As pessoas julgam a aparência de uma tela em cerca de 50ms e essa aparência é seu primeiro teste de credibilidade. Simples, familiar em estrutura, distinto em detalhe vence.
- Combine o design com o estado do usuário: ansioso (diga o que acontece a seguir, resumo antes do commit, caminho fácil de volta), apressado (menos etapas, pré-preenchido, atalhos), cético (prova junto com as alegações, preço total cedo), especialista (densidade, atalhos, desfazer em vez de confirmar), envergonhado ou enlutado (tom neutro, sem celebração).
- Termine com força: a última etapa e a confirmação são o que as pessoas lembram.
- O deleite fica em momentos de baixo risco (primeira execução, estado vazio, sucesso) e nunca durante erros ou tarefas sensíveis. Quanto mais frequente algo acontece, mais simples é.
- Recuse padrões escuros: urgência ou escassez falsa, avaliações falsas, extras pré-selecionados, custos ocultos, difícil cancelar, confirmação vergonhosa, um grande Aceitar ao lado de um Rejeitar escondido. Ofereça a versão honesta.
Detalhes: references/psychology-emotion.md.
11. Plataforma e acessibilidade
- Um app web funciona em qualquer navegador. Um app nativo segue as convenções do SO e usa controles nativos onde possível. Um app Electron parece um app desktop, não um site.
- Acessibilidade significa que funciona para todos. Semântica HTML correta (
<button>,<nav>,<label>, funções ARIA onde a semântica é insuficiente), navegação por teclado,prefers-reduced-motion,prefers-color-scheme, tamanhos de texto redimensionáveis sem quebra, alvos de toque de 44px. - O contraste de cor é um requisito, não uma meta. Todos os temas passam no WCAG 2.2 AA.
- Uma única experiência funciona em todos os dispositivos, mas a prioridade dos controles e o layout se adaptam. As convenções da plataforma não são restrições; são atalhos para seus usuários.
references/accessibility.md, references/platform-conventions.md.
12. Tokens (variáveis CSS)
Todas as telas usam um conjunto consistente de tokens CSS personalizados que definem cores, tipografia, espaçamento, raios e sombras. Eles são definidos em assets/tokens.css e são a única maneira de definir o estilo de um componente. Quando você escreve CSS, use var(--nome-do-token). Quando você escolher uma direção ou executar palette.mjs, o theme.css resultante definirá esses tokens para você.
| Categoria | Token(s) de exemplo | Descrição |
|---|---|---|
| Fundo | --bg, --surface, --surface-2 | Fundo de página, card e elevado |
| Texto | --text, --text-muted, --text-subtle | Corpo, meta, ainda mais quieto |
| Acento | --accent, --accent-fg, --accent-soft | Ação primária e destaques |
| Borda | --border, --border-strong | Divisores e bordas de input |
| Foco | --focus | Anel de foco visível do teclado |
| Estado | --success, --warning, --danger, --info | Feedback e indicadores |
| Sombra | --shadow-raised, --shadow-overlay | Elevação e profundidade |
| Raio | --radius-sm, --radius-md, --radius-lg | Cantos de controles, cards, folhas |
| Espaçamento | --space-{1..10} | Mapeia para a escala 4-96px |
| Fonte | --font-body, --font-heading, --font-mono | Famílias de fontes |
Detalhes: assets/tokens.css.
13. Diretrizes específicas da plataforma
| Plataforma | Tamanho do texto | Toque / Alvo | Barra de rolagem | Navegação |
|---|---|---|---|---|
| Web (desktop) | 14-16px | 24px (mouse) | Fina, nativa | Barra lateral ou barra superior |
| Web (mobile) | 16px | 44px mínimo | None | Barra de abas (não um menu hambúrguer) |
| iOS | 17px corpo | 44x44pt | Invisível | Barra de abas (3-5) |
| Android | 14sp corpo | 48dp | Overlay | Barra de navegação inferior (3-5) |
| macOS | 13px corpo | Padrão | Fina, nativa | Barra lateral + barra de ferramentas |
| Windows | 14px corpo | Padrão | Fina, nativa | Barra lateral + barra de ferramentas |
| Electron | 13-14px | 24-44px | Fina ou invisível | Siga o SO alvo |
Alvos de toque de 44px são obrigatórios para todos os elementos tocáveis em mobile. A largura mínima e a altura mínima são definidas como var(--target-size).
14. Movimento
- Movimento deve ter propósito: foco, orientação, continuidade, feedback. Não por enfeite.
- Durações: 100-150ms micro-interações (hover, foco), 200-300ms pequenas transições (abrir dropdown, toggle), 300-500ms transições de página, 400-800ms entradas de tela.
- Facilitação (easing):
easepadrão,ease-outpara entradas,ease-in-outpara mudanças de estado. Não use transições lineares para movimento de UI. prefers-reduced-motion: desative movimento não essencial, substitua por crossfade ou instantâneo.- As animações nunca bloqueiam a interação. O conteúdo chave aparece antes da animação terminar.
references/motion.md.
15. Ícones
- Um conjunto de ícones por produto. Conjuntos recomendados: Lucide, Phosphor, Heroicons (linha).
- Tamanhos: 16px dentro de texto e botões pequenos, 20px em itens de lista, 24px em cards, 32px em estados vazios.
- Ícones decorativos têm
aria-hidden="true"; ícones funcionais (como no botão Fechar) têm texto acessível. - Não misture famílias ou pesos de traço.
16. Imagens
- Use imagens reais com o mais cedo possível. Serviços de placeholder criam expectativas erradas para clientes e desenvolvedores.
- Defina
aspect-rationo CSS para evitar mudanças de layout. - Sempre inclua
altsignificativo (funcional) oualt=""(decorativo). - Imagens com contornos internos nítidos podem se beneficiar de um 1px
inner-borderna cor--border.
17. Acessibilidade
- Navegação por teclado:
Tabem ordem lógica,:focus-visiblevisível, nenhum foco preso sem um mecanismo de saída. - Rótulos: todo input tem um
<label>ouaria-label. - Anúncios: mudanças de conteúdo que são importantes mas não focadas devem usar
aria-live. - Modo de alto contraste: teste com ambos,
prefers-contrast: moree modos de alto contraste do SO. Garanta que informações não sejam transmitidas apenas por cor. - Redução de movimento:
prefers-reduced-motion: reducedesativa movimento não essencial e o substitui por crossfade de 0ms.
18. Tabelas
- Cabeçalhos: fundo
--surface-2, rótulo--text-muted12-14px. - Linhas: altura compacta 36-40px. Zebrado opcional (linhas ímpares
--surfacemuito ligeiramente diferente). - Ação em linha: ícone ou link de texto, não um botão de ação primária.
- Coluna de seleção: 40px largura, checkbox centralizado.
- Números:
font-variant-numeric: tabular-nums, alinhados à direita. - Ordenação: clique no cabeçalho; ícone de seta indica direção.
- Estado vazio: "Nenhum resultado" com uma ação.
19. Formulários
- Rótulo acima do input (nunca placeholder como rótulo).
- Ajuda: texto de ajuda abaixo do input,
--text-muted, 12px. - Erro: abaixo do input, cor
--danger, com ícone e explicação textual. - Grupos de campo (radio, checkbox): legenda acima, opções em uma linha ou grade.
- Comprimento: formulários longos divididos em etapas com indicador de progresso. Cada etapa salva seu estado.
- Ação primária (Enviar, Salvar) visível o tempo todo; desabilitada apenas se inválida e o usuário ainda não tocou em nada. Uma ação secundária "Cancelar" deve estar presente.
20. Revisão final
- A tela parece premium (apropriada, decidida, artesanal, honesta)?
- O resumo corresponde aos dados?
- Existem estados vazios, de erro e de carregamento?
- O texto é frase padrão, sem lorem ipsum?
- O contraste passa WCAG AA?
- A navegação por teclado é lógica e anéis de foco são visíveis?
- As capturas de tela mostram o caso de uso principal com dados reais?
- Existem tokens repetidos ou quebrados?
- A tela funciona em 375px e 1440px sem quebras?
- Um tour do produto como iniciante seria suave?
Se alguma resposta for "não", corrija antes de finalizar.
21. Mockups de projeto
Quando você precisa de um feedback rápido de design, produza um HTML autônomo com estilos inline ou incorporados, usando os tokens do tema escolhido. Inclua dados de exemplo realistas. Mostre o estado principal primeiro (não vazio). Anexe uma nota do que não é real ("dados simulados para revisão").
references/mockups.md.
22. Modo de revisão
Quando solicitado a revisar um produto, site ou tela existente, trabalhe na seguinte ordem:
- Estado atual: diga o que você vê em uma frase, sem julgamento.
- Avaliação: uma ou duas áreas fortes e fracas.
- Direção: escolha uma direção visual de
references/directions.mde explique por que ela se adequa. - Pontuação: atribua uma nota de 0-10 baseada em: adequação (3), acabamento (3), consistência (2), honestidade (2).
- Etapas seguintes: 1-3 mudanças de alto impacto que melhorariam a tela em uma hora.
references/review-mode.md.
Referências
ASSETS.md– como os ativos estão estruturadosreferences/– todos os guias de detalhesassets/directions/– direções visuais com temasscripts/– scripts de construção (palette.mjs,ui-audit.mjs)assets/tokens.css– tokens de design canônicos