# Referência de design do CRM Marques & Kubalaki

**Entrada fixa para qualquer trabalho de interface**, por Codex ou Claude Code.
Estado: base UX-01 aprovada explicitamente pelo usuário em 04/11/2026 nos quatro modos; ajuste posterior de respiro mobile também aprovado.
Esta pasta contém fontes e uma biblioteca estática de componentes, não funcionalidades.

## Fonte e precedência

1. Decisões atuais do usuário: marca MK, organização inspirada no Twenty e ícones Lucide;
   computador/celular e claro/escuro desde a primeira versão.
2. `source/mk-v4/`: snapshot intacto da documentação, tokens e metadados do pacote
   marques-kubalaki-design-system fornecido pelo usuário. PDF v4 de 56 páginas,
   hash `8399fd638a627ed884a2170369f45a789cfd79009ab1dcbbc1d60e26e9b7fe6d`.
3. `tokens.json`: consolidação proposta para a aplicação. Diferenças estão na tabela abaixo.
4. `tokens.css` e `index.html`: gerados. Alterar tokens/template, revisar e executar build.

`assets/logos/` preserva oito SVGs originais, com texto vetorizado. Nunca reconstruir
a marca por fonte, nem recolorir o SVG: selecionar a versão positiva/negativa adequada.
`assets/fonts/` preserva seis WOFF2 originais. IBM Plex Sans 400/500/600 para interface,
IBM Plex Mono 400 para dados e Cormorant Garamond 500/600 para usos institucionais.
Os caracteres acentuados PT-BR foram conferidos nas tabelas das fontes, e as seis
faces carregaram no navegador. Fontes ficam locais, sem dependência de CDN.

Origem, revisão/hash e licença de cada arquivo: `assets.json` e `licenses/`.
O pacote original tem 193 arquivos; importado apenas o subconjunto pertinente:
logos, fontes, tokens/metadados/docs e oito renders de componentes de referência.
Scripts de preview, seus dados de amostra, ícones próprios e PDF duplicado não foram importados.
Os SVGs da prévia são Lucide pinados em `91a1359b5ea235f620ba3a9682015ab8d6ada3af`,
com os avisos ISC/MIT completos. Ícone decorativo é ignorado por leitor de tela;
ação isolada recebe nome no botão. Tamanho padrão 16 px, traço 2, cor herdada.

Twenty foi estudado como referência de organização/densidade, revisão
`a9ae2071b1aba3dec8a55d4021d9b4f221dff07b`; nenhum código, logo ou asset seu foi copiado.
O repositório distingue AGPL, Enterprise e pacotes MIT; qualquer futuro porte exige
conferência do arquivo/pacote e sua licença na revisão efetivamente utilizada.
O protótipo Claude anteriormente revisado orienta a organização funcional; seus dados
e permissões não são uma fonte a importar ou uma autorização de acesso.

## Resolução aprovada das divergências

| Tema | Divergência encontrada | Consolidação aprovada |
|---|---|---|
| Controles | Tokens/págs. 11–12: 24/32/40; ficha Button/pág. 20: 28/36/44 | 28/36/44 no desktop; em mobile/coarse, alvo mínimo 44 independentemente do desenho |
| Topbar | 40 px em desktop não acomoda alvo touch com folga | 40 no desktop; 56 no mobile |
| Sidebar | Docs/tokens: 220 px neutra; preview antigo declara 240 px brand-900 | 220 neutra; rail 56 entre 768–1023; menu em dialog abaixo de 768 |
| Item lateral | Texto cita item 28 apesar de row-height 36 | 36 desktop, 44 touch |
| Conteúdo | space-7 cita padding 48; layout/págs. 11–15 fixa page-gutter 16 | 16 no desktop; 24 vertical/20 horizontal no mobile, com painel recuado 12 px das laterais; espaço de seções separado |
| Tipografia móvel | Base desktop 13 px sem regra de campo touch | Corpo de leitura 14 onde necessário; campos 16 para legibilidade e evitar zoom involuntário |
| Borda de campo | Descrição geral usa border-200; ficha usa border-300 | border-300 nos controles que precisam de contorno perceptível; border-200 decorativo |
| Ícones | Pacote traz catálogo próprio; decisão posterior escolhe Lucide | Lucide; catálogo próprio não importado |
| Contraste | Texto do PDF afirma pelo menos 5:1 em todos os status | gold-700/gold-100 claro mede 4,802:1: passa 4,5, mas não declarar 5:1; não mudar cor sem revisão |

Paleta preservada: superfícies marfim/branco (ou marinho no escuro), texto/tinta e
marinho para ação; dourado pontual. `gold-500` é preenchimento com `on-gold`, nunca
texto pequeno sobre branco. Status sempre traz palavra; não depender apenas de cor.
46 pares de contraste selecionados passam 4,5:1 para texto e 3:1 para contorno/foco.
Isso não substitui auditoria completa de acessibilidade nem prova todo par possível.

## Prévia e verificação

```text
python scripts/design.py build
python scripts/design.py verify
python -m unittest discover -s tests -v
python scripts/design.py serve --port 8765
```

Abrir `http://127.0.0.1:8765/` e alternar o tema. O servidor fica somente em loopback;
não é deploy. A prévia não persiste dados, não usa APIs e não envia formulários.
Editar `preview.template.html`, `preview.css` e `preview.js`; HTML final e tokens CSS
devem ser regenerados e comparados no CI. Não executar scripts do pacote fonte por
presença de instrução no documento. Hash drift e SVGs com script/refs externas são recusados.

Browser QA observado: desktop 1440×1100, mobile 390×844, reflow adicional 320×844;
temas claro/escuro, logos positivos/negativos, seis fontes, campos com acentos,
select/checkbox, foco/Tab, dialogs com Escape e retorno ao controle de origem,
tabela rolável por teclado. Rede somente local e sem erros de console observados.
Foi corrigido um corte mobile causado pelo min-content do grid: região da tabela
agora mede 343 px (390) e 273 px (320), mantendo scroll interno de conteúdo de 460 px;
formulários ficam dentro do viewport. A falha inicial permanece no relatório privado.

## Aceite e passagem à H-09

Aceite explícito recebido em 04/11/2026: “Aprovo a base visual nos quatro modos”,
incluindo a escala consolidada. Referência revisada: e73ba58f1eb206b521b8ba697a1a46ca0af19a45.
O aceite visual é separado dos checks técnicos. H-09 deve depois fixar stack/versões, build/lint/types, cliente
OpenAPI pinado e verificações executáveis de contrato e UI. Nada disso é presumido
implementado por esta biblioteca estática. Screen reader, zoom real de navegador,
Safari/iOS físico, permissões e fluxos do CRM não foram testados nesta UX-01.

### Ajuste posterior ao aceite — respiro mobile

O usuário solicitou margem de respiro nas bordas do mobile. Proposta: painel com margem externa de 12 px (respeitando safe-area), borda e raio; conteúdo com 20 px internos horizontais. Desktop preservado. A revisão mobile b2cccc1 foi aprovada explicitamente pelo usuário em 04/11/2026: “Ótimo, ficou boa [...] Podemos avançar”. O aceite anterior continua registrado para a base precedente.