A lei visual do Hub Central

Evidência

Todo par abaixo é calculado, não estimado: OKLCH → sRGB → luminância relativa → razão WCAG. O mesmo módulo alimenta esta página e o npm run verifica:contraste, que trava o commit quando um par reprova.

774 pares verificados nos dois temas — 515 de token contra token e 259 de superfície composta, aquela que só existe na tela quando um token semitransparente pousa sobre outro.

34 pares compostos estão abaixo do piso e aguardam decisão do Líder. Não travam o commit porque a correção mora no componente, não no token. Rode npm run verifica:contraste para ver cada um com a correção proposta.

Superfícies

Três papéis: conteúdo (background, card), estrutura (sidebar) e apoio (muted, accent, secondary). No tema escuro o card é MAIS CLARO que a página — por isso ele, e não o fundo, é o pior caso nos cálculos.

Marca e controles

O azul da marca PH SILVA é o único acento, reservado a ação primária, seleção e estado corrente. --border é divisória decorativa e não tem piso; --input é o contorno que IDENTIFICA um controle e por isso precisa de 3:1.

Alertas

Oito estados do RN-04.3, dois tokens cada. A TINTA é sempre texto e ícone; o SUAVE é sempre preenchimento. Inverter os papéis produz um bloco saturado e é defeito de revisão.

Energia

Rampa de cinco degraus dentro do matiz da marca. Piso de 3:1 porque é elemento gráfico, não texto — a informação está na contagem de barras, e a cor só reforça.

Distinguibilidade dos selos

Contraste diz se dá para LER o selo; distância diz se dá para DIFERENCIAR um do outro. A régua é o par hoje × amanhã, que já convivia na paleta sem objeção (AD-030).

Matriz dos pares de token

Token contra token, um a um. Os pares de superfície composta ficam de fora porque o eixo desta tabela é token × token, e um fundo composto não é um token — eles saem inteiros no npm run verifica:contraste. Fica recolhida porque é referência de conferência, não leitura corrida: divulgação progressiva vale também para a documentação.

Escala — fixa em rem, nunca fluida

clamp() não serve a UI de produto: o usuário trabalha em DPI consistente, e um título que encolhe dentro de uma coluna fica pior, não melhor. Razão entre degraus de 1,125 a 1,2. Acima de text-2xl, nada.

Pesos

400 corpo · 500 títulos e ênfase · 600 título de página. 700 não é usado: font-medium faz aqui o trabalho que bold faria em outro produto.

Números tabulares

Obrigatórios em horário, contador e duração, pelo atributo data-numerico. Sem isso a agenda dança quando 08:15 vira 09:00 — repare na coluna de baixo.

Medida

Prosa limitada a 65–75ch. Listas e dados podem correr mais densos; prosa, não.

Ritmo

Hierarquia vem de espaço e peso antes de vir de tamanho. Espaçamento uniforme na página inteira é ausência de hierarquia — varie de propósito. Valor arbitrário como p-[13px] é defeito de revisão.

Raio

Uma escala derivada de --radius. Misturar raios sem motivo é o tipo de inconsistência que o usuário não sabe nomear, mas sente.

Elevação

Superfície em repouso usa anel de 1px, como no Notion. Sombra é reservada a sobreposição — se tudo flutua, nada flutua.

Camadas

Escala semântica, nunca valor arbitrário. z-[999] e z-[9999] são defeito: significam que alguém perdeu a disputa e apelou.

Densidade e alvo de toque

Mínimo de 44×44 no que é tocado com frequência, mesmo quando o desenho é menor. A moldura tracejada mostra o alvo real da caixa de concluir.

Variantes

Uma forma de botão em todo o sistema. Se o botão de salvar tem aparência diferente em duas telas, uma das duas está errada.

Tamanhos

Estados

Os oito estados não são opcionais. O erro clássico é desenhar hover e esquecer foco — quem navega por teclado nunca vê hover. Tabule pelos botões abaixo para conferir o anel.

Campos

Rótulo visível sempre. Placeholder não é rótulo: some quando o campo é preenchido, e some justamente para quem mais precisaria dele.

Controles

Alvo de toque de 44px mesmo quando o desenho tem 16 — e aqui o alvo é o RÓTULO, não o desenho. A caixa de concluir tem 16px e o `after:` a leva a 40×32; quem fecha os 44 é o `<label>` em volta, como a LinhaItem faz com `size-11`. Esticar o `after:` até 44 faria as áreas de linhas vizinhas se sobreporem numa lista densa, que é justamente onde o gesto mais se repete.

Os oito estados

Matiz, ícone e palavra, sempre juntos. No tema claro as oito tintas vivem na mesma faixa de luminosidade por exigência de contraste — a cor sozinha não diz a urgência, e por isso ícone e palavra são obrigatórios, não enfeite.

Prazo concreto

Quando existe um prazo real, ele substitui a palavra na tela — e o rótulo canônico continua indo para o leitor de tela. O dado extra soma, não troca.

Só ícone — último recurso

A palavra some da tela, nunca do leitor de tela. Se você precisou disto em mais de um lugar, o problema é a densidade da lista, não o selo.

Medidor de energia

A informação está na contagem de barras. A altura cresce junto e a cor reforça — três canais para o mesmo dado, porque num dia ruim ninguém compara matizes.

A escala é uma só

O medidor não tem variante grande. Na linha de metadados ele é um metadado entre outros, e o teto da escada é a altura óptica dos ícones ao lado — o ícone ocupa caixa de 12px, mas o traço desenha uns 10, e é com a tinta que o olho compara. Um componente com dois tamanhos convida a escolher o errado.

Variantes numa lista

Deliberadamente não é card: a tela de execução mostra dezenas destas, e card sobre card come altura útil. A separação é uma hairline; o agrupamento vem do espaço. Marque uma caixa para ver o estado concluído.

Casos de borda de texto

O título corta em duas linhas. Só quem passa disso ganha o “ver mais”, no fim da segunda linha — quem cabe não mostra botão, reticência nem espaço reservado. Reduza a janela: o mesmo título que cabe no desktop transborda no celular, e o botão aparece sozinho.

Título navegável — o alvo estendido da §5.3

Quando a linha leva a algum lugar, o título é o elo, porque é o maior alvo que a linha tem. O texto tem 19px de altura e o dedo precisa de 44: quem fecha a conta é um pseudo-elemento transparente que estende a área tocável sem engordar o desenho. Ele mora no elo; quem corta em duas linhas é o span de dentro — as duas coisas no mesmo elemento fariam o recorte comer o alvo, em silêncio. Aponte 8px acima do texto: o cursor vira mão.

Contexto e área — lista de seleção (AD-061)

Eram fileiras de chips. O Líder decidiu que contexto é vocabulário do dono, sem ícone, apresentado como lista de seleção; área veio junto, porque dois controles da mesma natureza a 40px de distância não podem ter formas diferentes. As opções vêm por prop, na ordem do servidor: renomear um termo não exige deploy.

O mesmo controle, no formulário

`uso` não é decoração: é o predicado. No filtro a opção neutra significa “não restrinja”; no formulário significa “este campo fica vazio”. A cópia acompanha, e a combinação errada deixa de ser expressável.

Carregando — e por que `undefined` não é `[]`

A §5.1 exige os oito estados e diz que metade deles não é “quase pronto”: é não pronto. Este componente saiu sem `loading`, e os dois consumidores resolveram por fora, de formas diferentes — um inventou um esqueleto à mão, o outro afirmou “você ainda não tem contextos cadastrados” enquanto a consulta ainda estava em voo. A distinção mora no componente porque é ele quem garante que “não sei ainda” e “sei, e está vazio” não sejam ditos com a mesma frase. O esqueleto tem a altura EXATA do gatilho (44px), então o campo troca de conteúdo sem mover um pixel do que está abaixo.

Vocabulário vazio

Lista vazia não vira menu vazio. Um gatilho que abre e não oferece nada é a tela mentindo que existe uma escolha — o componente troca o controle por uma frase que explica a ausência e diz que o item segue sem o campo (§9). Agora que o carregando existe, esta frase AFIRMA em vez de hedgear: ela só roda depois de a resposta ter chegado vazia.

Energia — dois componentes, não um com rótulo trocável (R-3)

Os dois têm a MESMA assinatura (`NivelEnergia | null`) e predicados diferentes: o filtro é limiar (≤ N), a atribuição é valor exato (= N). Um componente parametrizado por texto tornaria a combinação errada invisível ao TypeScript. Quando o tipo não distingue, o nome distingue.

O chip neutro não usa o acento (A-1)

“Qualquer energia” e “Sem definir” significam nada escolhido. Pintá-los de azul cheio é acento em estado inativo, que a §2.10 proíbe pelo nome — e a AD-030 já tinha decidido a mesma coisa ao tirar o alerta `livre` do verde: ausência não é estado positivo, é ausência, e ausência é neutra. Marcado, o chip neutro se distingue por superfície, tinta e um ✓ — e é o ✓ que o separa de “sob o cursor”, porque o hover pousa na mesma superfície. Clique entre eles e compare com um degrau da escala.

Desativado

Energia mantém a fileira de chips mesmo depois da AD-061, e isso não é incoerência: escala ordinal de cinco degraus com medidor gráfico perde o canal que carrega a informação se for escondida dentro de um menu. Forma igual para coisas iguais; forma diferente para coisas diferentes.

Espaço entre cards

Um valor só, em qualquer largura: o que colapsa no celular é o número de colunas, nunca o espaço. Nunca gap-* solto entre cards — use GradeDeCards, PilhaDeCards ou a constante.

Indicadores e card de página

Faixa de KPIs (2 × 2 no celular, em linha de lg em diante) e, abaixo, a composição 2/3 + 1/3. tom=acao marca o único card que pede uma ação agora.

Vazio de partida

Ensina o próximo passo. “Nada por aqui” informa a ausência e não faz nada com ela — é defeito.

Vazio de conquista

Havia itens e acabaram. É outro vazio, e confundir os dois faz o sistema parabenizar quem ainda não começou.

Carregando

Skeleton que antecipa a forma da lista, nunca spinner solto. Salto de layout custa o foco inteiro de quem já está lutando para mantê-lo.

Erro

Três obrigações: o que falhou, o que NÃO foi perdido, e a saída. A segunda é a que mais some das mensagens de erro por aí.

Sem rede

A captura offline saiu do escopo (AD-021), então o sistema diz isso na cara. Um “salvo!” que evapora destrói a confiança que faz o usuário parar de reconferir tudo à mão.

Sincronização — o quinto estado

O canal do Google expira e o sync para sem gerar erro nenhum. Falha silenciosa não é problema de infraestrutura, é problema de interface. Note que o sinal é a MUDANÇA DE FORMA; a cor só acompanha.

Lista longa

Rola dentro do próprio contêiner e termina com uma marca de fim. Sem ela o usuário rola mais um pouco só para conferir se acabou — atrito pequeno, repetido dezenas de vezes por dia.