Manual de Design LZR

Versão 1.1 — 2026-07-29. A aparência é livre por projeto, sem exceção — cor, fontes, cantos, sombras, movimento, densidade, tom de voz e composição das telas. O que permanece fixo para toda a casa é o que não é estética: acessibilidade, e as regras de construção que vivem nos manuais de código e testes. Mudança pedida pelo Paulo ao adotar no LZR Studio um sistema visual de cantos retos e outra família tipográfica: "cada projeto tem vida própria; o visual pode ser 100% diferente de um para o outro". Na prática isto libera os cantos (antes fixos em 4px) e confirma as fontes, que este manual já declarava livres desde a v1.0 — a proibição vivia, errada, nas cópias das instruções de projeto.

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): o que não é estética — acessibilidade (seção 6), a escala de espaçamento, o uso obrigatório dos componentes compartilhados, a estrutura dos padrões, e as regras de voz que valem para qualquer produto. Garante que o produto seja usável e construído com qualidade.
• Personalidade (por projeto): toda a aparência — cor de destaque, superfícies (claro e escuro), fontes, cantos, sombras, movimento, densidade, tom de voz e composição das telas. Cada projeto preenche os "lugares vazios" que a fundação define, e pode ficar 100% diferente de qualquer outro produto da casa.

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.

A fronteira, em uma pergunta: isto é gosto ou é gente conseguindo usar? Gosto (que cor, que fonte, canto reto ou arredondado, quanto movimento) é do projeto. Conseguir usar (enxergar o texto, achar o foco pelo teclado, acertar o toque no celular, entender o status sem depender da cor) é da casa e não se negocia.

2. Peças visuais de escala

Toda peça desta seção é uma escala fechada: o projeto escolhe os valores dela, e depois só usa esses valores — proibido valor cru fora da escala (o guarda barra). O que é da casa é a disciplina da escala; os valores são do projeto.

Os padrões históricos da casa (Plus Jakarta Sans para texto, Syne para títulos, DM Mono para código, canto de 4px) valem como ponto de partida de projeto novo — não como obrigação. Um projeto que declara outra escolha na personalidade está certo, não em exceção.

Valores exatos das escalas de referência no anexo.

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 identidade visual (verificam regra semântica, nunca um 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 cantos só pela escala declarada pelo projeto. 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.

Consequência da v1.1: um guarda que procure um valor da casa (a fonte X, o canto de 4px) está errado por construção — vai acusar projeto legítimo. O que se fiscaliza é "saiu da escala que este projeto declarou?", não "é o valor da casa?".

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.