Manual de Design LZR

Versão 1.0 — 2026-06-20. Consolida em um lugar só a fundação de design que antes vivia espalhada na pasta de design-system (foundation + personality + vigias + checklist).

O que este manual responde: como o produto se parece e se comporta visualmente. Tudo que é "como construo" mora no Manual de Código; "como provo que funciona" no Manual de Testes.

Regra de ouro deste acervo: cada regra mora em um lugar só. Quando uma regra depende de outra, ela aponta — nunca copia. Valores exatos das escalas, exemplos, modelos de personalidade e tabelas de formatação ficam no anexo.

Quanto deste manual é obrigatório depende do porte do projeto — ver Níveis de Exigência. Os tokens, o contraste e os estados visuais valem para todos; a auditoria de acessibilidade na norma nova e a comparação de tela por imagem sobem com o nível.

1. Arquitetura: fundação + personalidade

O design LZR tem duas camadas:

Fundação (fixa, universal): as regras que valem para todo projeto — escalas de espaçamento, raio, sombra, movimento e tipografia; os componentes e padrões obrigatórios; acessibilidade; responsividade; voz e tom. Garante qualidade e coerência.
Personalidade (por projeto): a identidade de cada produto — a cor de destaque, as superfícies (claro e escuro), as fontes escolhidas, o tom de voz, o modo de densidade. Cada projeto preenche os "lugares vazios" que a fundação define.

A engrenagem que liga as duas é um atributo no topo da página (data-product): o mesmo componente muda de cor e fonte sozinho conforme o produto, sem reescrever código. Detalhe do mecanismo na seção 9 e no anexo.

Princípio: a fundação define o comportamento e a estrutura; a personalidade define a aparência. Liberdade visual total por projeto, dentro de uma fundação de qualidade inegociável.

2. Peças visuais de escala (fixas na fundação)

Valores exatos no anexo. As escalas são fechadas — proibido valor cru fora delas (o guarda barra).

Espaçamento: escala base 4px (s1 a s9, de 4px a 96px). Padding, margem e espaço entre itens só por essa escala.
Raio de borda: 5 níveis (r-xs a r-full). Padrão é o pequeno (4px); maiores só para modal/contêiner grande; total só para pílula/etiqueta.
Sombra: 4 níveis. Os valores mudam entre claro e escuro; a sombra de destaque é tingida pela cor do projeto.
Movimento: 2 curvas e 4 durações. No máximo 2 propriedades animadas ao mesmo tempo; só animar transformação e opacidade (nunca largura/altura/layout); respeitar quem pede menos movimento.
Tipografia: escala de 9 níveis (do título grande ao rótulo de 12px). Piso de 12px — nenhum texto funcional menor. Três famílias com papel fixo: texto (padrão LZR: Plus Jakarta Sans), títulos (padrão: Syne) e código (padrão: DM Mono) — cada projeto escolhe equivalentes na personalidade.

3. Tokens semânticos (os lugares que a personalidade preenche)

A fundação define os nomes (a intenção), a personalidade preenche os valores. Mais de 25 nomes obrigatórios, em grupos: cor de destaque (com variações de fundo, borda e foco), superfícies (fundo, superfície, elevado, borda — em claro e escuro), texto (principal, secundário, suave, placeholder, sobre-destaque), estados (sucesso, alerta, erro, informação, cada um com fundo e borda) e as três fontes. Proibido cor crua no código de aplicação — só os nomes semânticos (o guarda barra). Lista completa no anexo.

4. Componentes obrigatórios

Todo projeto usa a biblioteca de componentes compartilhada — proibido etiqueta de formulário solta no código de aplicação (botão, campo, seleção, área de texto crus). Os componentes têm comportamento, tamanhos e estados definidos na fundação; a aparência vem da personalidade.

Base obrigatória: Botão (variações e tamanhos), Campo, Área de texto, Seleção, Caixa de marcação, Opção única, Interruptor, Cartão (o cartão de seção tem ícone temático no canto), Etiqueta e Aviso (em variações de estado). Estados padrão: repouso, foco, sobre, ativo, desabilitado, carregando. Especificações e exemplos no anexo.

5. Padrões obrigatórios

Padrões compostos com estrutura definida: tabelas (com ordenação, linha destacável, paginação no rodapé), modais (com as regras de acessibilidade de diálogo), abas, paginação, dicas, balões, avisos temporários (com ícone, nunca emoji), trilha de navegação, passos, estados vazios (com chamada para ação obrigatória), telas de sistema (404/500, com botão de volta), esqueletos de carregamento e notificações persistentes. Estrutura e exemplos no anexo.

6. Acessibilidade

Nível AA da norma internacional é obrigatório e fiscalizado — não é sugestão.

Contraste mínimo 4,5:1 em texto funcional; 3:1 em elementos não-textuais (ícones, bordas de campo, componentes de UI). Um guarda mede o contraste real entre as cores da paleta do projeto e barra combinações abaixo do mínimo (funciona em qualquer paleta).
Foco visível em todo elemento interativo, no padrão único da fundação.
Alvo de toque mínimo no celular para qualquer elemento clicável.
Nunca transmitir informação só por cor — sempre cor + ícone + texto.
Semântica correta (botão é botão, rótulo ligado ao campo) e marcação de acessibilidade nos pontos certos (botão só com ícone, diálogo, aviso, carregamento).
Movimento só de transformação e opacidade; respeitar quem pede menos movimento; zero movimento que cause desconforto.

Meta de melhoria: subir da norma de 2018 para a de 2023 (alvo de toque mínimo, alternativa para qualquer gesto de arrastar, login que não dependa de memorização). Detalhe no anexo.

7. Responsividade, layout e densidade

Cinco faixas de tela (do celular ao ultralargo), com grade adaptativa (2 colunas no celular, 6 no tablet, 12 no computador). Começar pelo celular.
Trilha de experiência por projeto: cada produto escolhe uma — computador primeiro, multi-dispositivo, ou celular primeiro — que define o comportamento do layout.
Modo de densidade por projeto: compacto, padrão ou confortável.
Layout de detalhe 2/3 + 1/3 para páginas de detalhe, formulário e configuração (principal à esquerda, apoio à direita). Não aplicar em quadro de tarefas, listagens, landing nem modal.
Ícones de uma biblioteca única (Lucide Icons), com tamanhos por contexto.

Valores de faixa, grade, sidebar e densidade no anexo.

8. Voz e tom

Princípios universais (fixos), tom específico por projeto (personalidade).

Regras universais: clareza e precisão acima de tudo; zero exclamação em erro/alerta; sempre específico (números, prazos, protocolos concretos); botão descreve a ação; carregamento descreve o que está sendo feito; confirmação destrutiva nomeia o que será afetado e a consequência; estado vazio traz chamada para ação.

Cada projeto define em sua personalidade: o tom em uma frase, a persona, o tratamento, o vocabulário do domínio e o que o produto nunca faz.

9. Theming / personalidade por projeto

O mecanismo que dá a cada produto sua identidade sem reescrever componente:

Um atributo no topo da página (data-product) identifica o produto; outro (data-theme) escolhe claro ou escuro.
A fundação declara os nomes semânticos vazios; cada projeto declara os valores desses nomes (a paleta, as superfícies claro/escuro, as fontes); os componentes usam só os nomes.
Trocar de produto ou de tema = trocar o conjunto de valores. O que nunca muda entre claro e escuro: a cor de destaque do projeto, a tipografia, o espaçamento, o movimento e o raio.

Cada projeto preenche de 5 a 7 arquivos de personalidade. Exemplos e modelos no anexo.

10. Vigias de design (os guardas)

Rodam no projeto, antes de qualquer mudança subir, e funcionam em qualquer paleta (verificam regra semântica, não valor específico): sem cor crua no código; sem etiqueta de formulário solta; sem texto fixo de mensagem; cartão de seção com ícone; "voltar" pelo histórico; aviso temporário sem emoji; placeholder com contraste correto; tipografia, espaçamento e raio só pela escala. Mais o guarda avançado de contraste que mede a paleta real do projeto e barra o que fica abaixo do mínimo. Severidades e detalhes no anexo.

11. Idioma e formatação local

Código e banco em inglês; interface no idioma do país. O mesmo dado vai de inglês no banco a rótulo traduzido na tela.
Nunca texto fixo na tela — tudo pela central de tradução.
Datas, dinheiro, números e documentos (CPF, CNPJ, telefone, CEP) no formato do país, automático. Tabelas de formatação e os idiomas de partida no anexo.

Fronteiras deste manual: como construir → Manual de Código. Como provar → Manual de Testes. A esteira automática de peças, a vitrine viva de componentes e o versionamento do design como produto são melhorias industriais à parte (ainda não feitas) — não governadas por este manual de regras.