Ui ux

Escopo: transversal. Aplica-se a qualquer linguagem ou stack do projeto.

Interface é o contrato entre o sistema e o usuário. Cada decisão de espaçamento, cor, hierarquia e estado comunica algo. Quando essas decisões são inconsistentes, o usuário trabalha mais para entender o que o sistema oferece.

Interfaces com excesso de elementos competindo por atenção cansam o olho e aumentam o tempo de decisão. Respiro (o espaço entre elementos) é a estrutura que guia a leitura.

A regra central é agrupamento semântico: elementos relacionados ficam próximos, grupos distintos têm espaço entre eles. O olho lê a interface como parágrafos antes de ler as palavras.

Espaçamentos arbitrários (margin: 13px, padding: 7px) criam inconsistência visual acumulada. Um sistema de espaçamento define uma escala com valores fixos que se repetem de forma consistente em toda a interface.

Escala típica baseada em múltiplos de 4:

Usar tokens (valores nomeados do sistema de design) em vez de valores livres garante que qualquer ajuste de escala se propague de forma consistente. A interface respira no mesmo ritmo em qualquer viewport (área visível da tela).

Texto sem hierarquia não orienta a leitura. O usuário precisa de âncoras visuais para identificar o que é título, o que é descrição, o que é detalhe.

Três níveis são suficientes para a maioria dos contextos:

Evitar mais de três níveis tipográficos na mesma tela: a hierarquia colapsa, tudo parece especial, nada parece importante.

Temas requerem paletas re-otimizadas para cada contexto, não apenas inversão de cores. Superfícies, sombras, opacidade e contraste se comportam de forma diferente em cada fundo.

A regra prática é usar variáveis semânticas em vez de valores fixos:

--text-primary        → texto de maior hierarquia
--text-secondary      → texto de apoio
--surface-base        → fundo da página
--surface-elevated    → fundo de cards e modais
--border-subtle       → bordas de separação
--interactive-default → cor de botões e links

Para o detalhamento de OKLCH, harmonias, escala tonal de 11 paradas, hierarquia de superfícies, WCAG 1.4.3 e estratégias específicas de light/dark, consulte color-theory.md.

Acessibilidade garante que a interface funciona para todos os usuários, incluindo quem usa leitores de tela, navega pelo teclado ou tem deficiência visual.

Texto e elementos interativos precisam de contraste suficiente contra o fundo. A regra prática: se precisar apertar os olhos para ler no mockup (protótipo visual), vai falhar em produção.

Todo elemento interativo (botão, link, campo, modal) deve ser acessível via Tab e ativável via Enter ou Space. A ordem de foco deve seguir a ordem visual da página.

Foco visível é obrigatório. Nunca remover o outline (contorno) de foco sem substituí-lo por algo equivalente ou melhor.

Elementos HTML (HyperText Markup Language, Linguagem de Marcação de Hipertexto) semânticos comunicam estrutura para leitores de tela:

Leitor de tela lê o que o HTML diz, não o que a tela mostra. Um <div> com visual de botão é invisível para quem usa tecnologia assistiva.

ARIA (Accessible Rich Internet Applications, Aplicações de Internet Ricas Acessíveis) complementa a semântica nativa para padrões complexos: menus, tooltips (dicas flutuantes), modais, comboboxes (campos de seleção combinados).

A regra de uso é simples: ARIA é o último recurso. Preferir elemento HTML semântico nativo antes de qualquer atributo ARIA. ARIA mal usado é pior que nenhum ARIA.

Cada ação do usuário precisa de resposta visível:

Toda tela tem variações de estado além do estado feliz. Projetar apenas o estado com dados é projetar metade da interface.

Estado empty bem projetado orienta o usuário para a próxima ação. Estado de erro bem projetado diz o que aconteceu e o que fazer. Tela em branco e mensagem técnica indicam estados sem tratamento.

Desenvolvido por @thiagocajadev · Fork baseado no repositório pmndrs/docs · Poimandres.