Ui ux

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

A interface é o contrato entre o sistema e quem o usa. Cada decisão de espaçamento, cor, hierarquia e estado comunica alguma coisa ao usuário. Quando essas decisões são inconsistentes, ele precisa de mais esforço para entender o que o sistema oferece.

Quando muitos elementos disputam atenção ao mesmo tempo, o olho cansa e a decisão demora. O respiro (o espaço entre os elementos) organiza a leitura: ele mostra por onde começar e onde cada grupo termina.

A regra é o agrupamento semântico: o que se relaciona fica perto, o que é distinto ganha distância. Antes de ler as palavras, o olho lê a interface como parágrafos.

Valores escolhidos caso a caso (margin: 13px, padding: 7px) se acumulam e produzem uma inconsistência difícil de localizar depois. Um sistema de espaçamento define uma escala de valores fixos que se repetem na interface toda.

Escala típica, com os valores subindo a cada 4px:

Usar tokens (valores nomeados do sistema de design) em vez de números soltos tem um ganho concreto: ajustar a escala uma vez propaga o ajuste por toda parte. A interface passa a respirar no mesmo ritmo em qualquer viewport (área visível da tela).

Texto sem hierarquia não diz por onde começar. O leitor precisa de âncoras visuais para separar num relance o que é título, o que é descrição e o que é detalhe.

Três níveis bastam para quase todo contexto:

Passar de três níveis na mesma tela derruba a hierarquia em vez de refiná-la: quando tudo parece especial, nada parece importante.

Uma interface é lida em camadas antes de ser lida em palavras. O olho identifica o que está no fundo, o que está apoiado sobre ele e o que flutua por cima, e usa essa leitura para decidir o que é conteúdo, o que é moldura e o que exige resposta agora. A superfície (o plano visual que sustenta o conteúdo) é a peça que carrega essa informação.

A pilha tem cinco níveis, e quase toda tela cabe neles:

modal      → interrompe: exige decisão do usuário
overlay    → flutua: dropdown, popover, tooltip
card       → agrupa: unidade de conteúdo
surface    → estrutura: sidebar, header
background → base: o plano da página

A ordem importa mais que os valores. Uma camada só aparece acima de outra quando o conteúdo dela é mais urgente ou mais temporário. Um card que flutua como se fosse modal, ou um modal que se confunde com o fundo, faz o usuário perder o rastro do que está ativo.

Três recursos separam uma camada da que está embaixo, e cada um comunica uma coisa diferente:

O erro comum é acumular os três no mesmo componente. Um card com fundo diferente, borda visível e sombra pesada grita três vezes a mesma informação e ainda assim não fica mais legível. Um recurso resolve a maioria dos casos; dois já é uma decisão que precisa de motivo.

A força do recurso acompanha a altura da camada. Um card em repouso pede uma sombra que mal se nota. Um modal pede uma sombra funda, porque ele precisa parecer descolado de tudo o que está atrás. Quando a sombra do card e a do modal são iguais, o usuário deixa de distinguir o que é conteúdo do que é interrupção.

Para o lado da cor (quanto de luminosidade separa duas camadas em OKLCH, quanto de croma cabe num fundo, como tonalizar a sombra), o SSOT é color-theory.md.

Cada camada nova disputa a atenção do usuário e ocupa um lugar na pilha do código. Três anti-patterns aparecem quando a pilha cresce sem controle:

O z-index merece a mesma disciplina do espaçamento: uma escala fixa, com um valor por camada, definida num lugar só.

--z-base       → 0     conteúdo da página
--z-sticky     → 10    header e sidebar fixos
--z-dropdown   → 20    menus e popovers
--z-modal      → 30    diálogos
--z-toast      → 40    notificações sobre o modal

Com a escala nomeada, quem escreve um componente novo escolhe a camada pelo papel dele. Sem ela, cada desenvolvedor descobre o número que funciona no dia e soma um.

O contraste é medido contra a superfície imediata, e não contra o fundo da página. Um texto cinza que passa no WCAG sobre o branco da página pode falhar sobre o cinza claro de um card. Cada camada que muda o fundo obriga a reconferir o texto e os ícones que vivem em cima dela.

Elevação sozinha não comunica estado. Um item selecionado que se distingue apenas por uma sombra some para quem enxerga pouco ou usa alto contraste. A sombra entra como reforço, acompanhada de uma borda, uma mudança de cor de fundo ou um ícone.

Cada tema pede uma paleta própria, reajustada para o seu contexto. Superfície, sombra, opacidade e contraste se comportam de maneira diferente conforme o fundo, e inverter as cores do tema claro não resolve isso.

Na prática, isso se resolve com 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, cor das superfícies, WCAG 1.4.3 e estratégias específicas de light/dark, consulte color-theory.md.

Acessibilidade é a garantia de que a interface funciona para todo mundo, incluindo quem usa leitor de tela, navega só pelo teclado ou enxerga pouco.

Texto e elementos interativos precisam se destacar do fundo. Um teste caseiro resolve a maioria dos casos: se você aperta os olhos para ler no mockup (protótipo visual), vai falhar em produção.

Todo elemento interativo (botão, link, campo, modal) tem que ser alcançável com Tab e acionável com Enter ou Space, e a ordem do foco precisa seguir a ordem visual da página.

Foco visível é obrigatório. Remover o outline (contorno) de foco sem colocar nada equivalente no lugar deixa quem navega por teclado sem saber onde está.

Os elementos HTML (HyperText Markup Language · Linguagem de Marcação de Hipertexto) semânticos são o que comunica estrutura ao leitor de tela:

O leitor de tela anuncia o que o HTML declara. Um <div> com aparência de botão fica invisível para quem usa tecnologia assistiva, porque o HTML nunca disse que aquilo era um botão.

ARIA completa a semântica nativa nos padrões que o HTML não cobre sozinho: menus, tooltips (dicas flutuantes), modais, comboboxes (campos de seleção combinados).

ARIA é o último recurso. Tente o elemento HTML semântico primeiro, sempre. ARIA aplicado errado anuncia ao leitor de tela uma estrutura que não corresponde ao comportamento real, e isso confunde mais do que a ausência de ARIA.

Toda ação do usuário precisa de uma resposta que ele consiga ver:

Toda tela tem mais estados do que o estado feliz. Desenhar apenas a versão com dados deixa os outros estados para a produção resolver.

Um estado vazio bem feito aponta a próxima ação. Um estado de erro bem feito diz o que aconteceu e o que fazer agora. Tela em branco e mensagem técnica crua indicam estados que ninguém desenhou.

DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.