# CLAUDE.md — SEED Design System v2

Este repositório é o design system da SEED engenharia (engenharia elétrica,
atuação em MG/ES/BA): a especificação de marca, os tokens de design, os vetores
oficiais, os modelos de e-mail, as telas e bancadas de referência, a camada de
validação automatizada e as peças aprovadas. "Token" aqui é valor de design
nomeado (cor, espaço, raio, tempo); "bancada" é página HTML que exibe uma família
de componentes para revisão visual; "gate" é a revisão humana que aprova ou
reprova um artefato renderizado.

Contexto completo, com todas as decisões, alternativas descartadas, pendências e
fronteiras: HANDOFF-DS-PARA-CODE.md. Leia-o antes do primeiro trabalho sério aqui.

## Fonte de verdade

Este repositório é a fonte de verdade desde o commit de fundação fbba442
(2026-08-22), migrado da pasta do Google Drive "marca seed/Design System v2".
Pendência aberta GT-P1: decidir se o Drive vira espelho de leitura ou é
aposentado. Enquanto os dois forem graváveis existe o risco que já custou um
arquivo em 2026-08-06.

⚠⚠ GT-P1 MEDIDA em 2026-08-26 e apresentada a ele — o número mudou o tamanho do
problema, e a premissa de que "o Drive não tem mais papel" está invertida:

- **O repositório MORA no Drive.** `G:` é Google Drive File Stream 130.0.2.0; os
  399 MB em 1.309 arquivos do `.git` sincronizam para a nuvem a cada commit. O
  git já é a sincronização; o Drive sincronizando o `.git` por cima é uma segunda
  sincronização competindo com a primeira.
- **A pasta de origem NÃO foi removida** e segue gravável:
  `G:\Meu Drive\#nuvem\marca seed\Design System v2`, 945 arquivos / 105 MB.
  Conferida por MD5: 135 idênticos, **172 DIVERGENTES**, 629 só lá.
  Os 172 são versões ANTIGAS dos canônicos: `marca-seed.md` **v5.11** contra a
  v5.23 daqui. **Onze versões de atraso num arquivo com o nome certo** — e numa
  casa onde metade das pesquisas é feita por IA, um agente que varra o Drive lê a
  v5.11 sem nada indicar que está errado.
- **Custo de operar ali, medido:** `git status` 275 ms local × 522 ms Drive ·
  `git log --stat -20` 8.791 × 15.577 ms · `git fsck` 8,2 × 21,2 s. Drive de
  **1,8× a 2,6× mais lento**. `git fsck` passa nos dois: não há dano instalado.
- **Recomendação apresentada, aguardando o veredito dele:** (a) mover o
  repositório para disco local, GitHub como única cópia remota; (b) aposentar a
  pasta antiga **renomeando, nunca apagando**, com um LEIA-ME apontando a fonte
  de verdade. Não apagar porque 629 daqueles arquivos são evidência de gate da
  era anterior, e evidência não se descarta.

Registro completo: `09-pesquisa/medicao-fonte-mono-e-papel-do-drive.md` §2 e
MANIFESTO §131.7–§131.8.

✅ VEREDITOS DELE (2026-08-26): a pasta antiga do Drive foi **deletada por ele**
(conferida antes por MD5 e por execução — nada se perdeu; ver MANIFESTO §132).
A cópia de trabalho fica no Drive com **arquivos disponíveis offline** (decisão
dele; ataca a latência medida de 1,8×–2,6×; o risco residual da dupla
sincronização do `.git` fica registrado). E o repositório **saiu da pasta
`assistente de email`** — herança acidental de um projeto de maio/2026 sem
relação com o DS — para:

    G:\Meu Drive\Claude\code\seed-design-system

Conferido antes de mover: nenhum arquivo versionado citava o caminho antigo em
código (só documentação histórica, que permanece verdadeira como história), e os
únicos caminhos absolutos funcionais apontam para `C:` (Chrome e jsdom-env). O
histórico de sessões do Claude Code anterior à mudança vive no project-key
antigo (`G--Meu-Drive-Claude-code-assistente-de-email`); a memória foi copiada
para o novo.

## Invariantes — não altere sem decisão do Rafael

- `.gitattributes` contém `* -text`. Preserva LF e mantém a âncora MD5 válida em
  clones com `core.autocrlf=true`. Provado empiricamente: sem esse arquivo o MD5
  muda no clone (b9935b00… → 7e1db87b…). Removê-lo fura a âncora silenciosamente.
- `INVENTARIO-EXPORT.md` é âncora histórica do commit de fundação, não índice
  vivo. Não o atualize para refletir mudanças posteriores: uma âncora reescrita
  para casar com a realidade nova deixa de provar qualquer coisa. Arquivo novo
  entra no repositório e no histórico de commit, não no inventário.
- Os nomes de pasta numerados (`01-canonicos/` … `09-pesquisa/`) são decisão
  tomada, não pendência. O §15 do handoff propõe renomear para `canon/`,
  `tokens/` etc.; a proposta foi avaliada e recusada porque invalidaria os 347
  caminhos do inventário e porque a numeração codifica a ordem de governança
  (canônico governa, token deriva, validação prova, histórico não governa nada).
  Se um dia renomear: commit dedicado, `git mv`, e a âncora passa a ser
  "verificada em fbba442", sem reescrever o inventário.

## Mapa de consulta — onde cada classe de dúvida se responde

Aprovado pelo Rafael em 2026-08-22. Regra de uso: consultar ANTES de afirmar,
executar ou perguntar — a memória da sessão guarda a disciplina de consultar,
nunca o conteúdo consultado (cópia de canon diverge; já custou 4 rodadas).

**LEITURA DE ABERTURA de todo brick (ordem dele: "um arquivo como o roadmap vc
deveria lê-lo sempre, pois ele possui projeções do que precisamos fazer, e
você não precisa adivinhar"):** `01-canonicos/seed-ds-roadmap.md` (as fases e
o que vem depois — evita construir sem saber o destino, como quase aconteceu
com o llms.txt que a F8 já pedia) · `marca-seed.md` §17 (pendências) · o
`INDICE.md` (o censo). São pequenos o bastante para caber sempre.

**REGRA CANÔNICA DE PRODUÇÃO (dele, 2026-08-22): ~50% das pesquisas hoje são
feitas por IA.** Tudo que o DS produz — ERP, site, apps, peças — nasce 100%
pesquisável e consumível por IA. A doutrina já está no acervo: camada de
máquina no `seed-componentes.md` §47 (MK10 schema.org · MK20 marcação pela
camada de máquina) · publicação/descoberta na F9 do roadmap v2.1 (llms.txt, robots
para GPTBot/PerplexityBot/ClaudeBot, GEO) · `llms.txt` + `indice.json` na
raiz. Checagem de fechamento de peça: "um agente de IA consegue achar, ler e
citar isto?" — se não, não está pronta.

- Grafismo (regimes, serra, detalhe, emendas): `01-canonicos/marca-seed.md` §7
  · geometria e leis com número: `01-canonicos/seed-componentes.md` §76
- Cor, contraste, tinta sobre fundo: `02-tokens/seed-tokens.json` (semantic.*)
  · política de cor da marca: `marca-seed.md` §3
- O que já está aprovado e em produção: `06-validacao/geradores/gen-*.py` —
  o código É o registro; elemento visual novo não existe até provar que não
  existe (grep antes de criar)
- História de decisões, defeitos e vereditos verbatim:
  `06-validacao/ferramentas/MANIFESTO.md`
- Peças aprovadas (evidência visual de gate): `07-pecas/`

O ÍNDICE COMPLETO existe desde 2026-08-22 e tem TRÊS vistas, todas geradas
por `06-validacao/ferramentas/gen-indice.py` (nunca editadas à mão):
`INDICE.md` (humana) · `indice.json` (máquina) · `llms.txt` (agentes de IA,
formato llmstxt.org — antecipação da F8). Classes: vivo / gasto / evidência,
com motivo declarado por arquivo (metodologia: auditoria ROT + catálogo
mínimo padronizado tipo Backstage + ciclo de vida DS tipo USWDS).
⚠ **OBRIGAÇÃO DE FECHAMENTO DE TODO BRICK: rodar `gen-indice.py` e commitar
as três vistas atualizadas.** Arquivo novo sem regra de classificação sai
como "⚠ revisar" — resolver antes de fechar.
⚠⚠ **E A ORDEM IMPORTA: `git add -A` ANTES de rodar o gerador.** O censo vem
do `git ls-files`, então arquivo não rastreado é INVISÍVEL para ele — e o
placar sai verde e incompleto. Medido em 2026-08-25: o censo devolveu
"409 arquivos, 0 revisar" com **34 arquivos novos de fora**, e "0 revisar" se
lê como sucesso. Numa casa que é IA-primeiro, arquivo fora do índice é arquivo
que a IA não acha. Sequência: `git add -A` → `gen-indice.py` → `git add` das
três vistas → commit.
⚠⚠⚠ **DESDE A F9.1 (2026-09-05) A SEQUÊNCIA TEM UM PASSO ANTES:**
`06-validacao/geradores/gen-camada-ia.py` → `git add -A` → `gen-indice.py` →
`git add -A` → `06-validacao/guardas/guarda-camada-ia.py` → commit. O
`gen-camada-ia.py` fatia os 11 canônicos em um `.md` por § (`10-publicacao/ia/`),
emite `tokens.md`, `robots.txt`, `sitemap.xml` e a lista de publicação; o
`gen-indice.py` lê o índice das fatias para escrever o `llms.txt` (links
ABSOLUTOS em `https://ds.seed.eng.br` — o repositório é privado, a superfície
pública é o que um agente alcança). A guarda prova que as fatias reconstituem o
canon byte a byte e que todo link publicado existe e está no git. Publicação na
VM: `bash deploy/publicar.sh` (árvore limpa, commit no GitHub) e depois a guarda
com `--base https://ds.seed.eng.br --producao`. Decisões: MANIFESTO §153–§155.

## Verdade e medição

- Nunca afirmar número sem medir. Medir duas vezes, variando UMA condição. (§14.5)
- Conferência de arquivo é por MD5, nunca por tamanho. Conferência por tamanho já
  aprovou 21 de 21 arquivos com um deles sendo a versão errada. (§14, D-62)
- Valor de marca que não existe no canônico NÃO SE CRIA. Faltando valor: usar o
  stop canônico mais próximo medindo o custo, ou perguntar. Nunca inventar e
  avisar depois. (§14.1)
- Nunca inventar dado institucional. Fonte exclusiva: `01-canonicos/sobreaseed.md`. (§14.12)
- Toda pergunta ao decisor sai com o custo medido de cada saída. Pendência
  enunciada como "A ou B" transfere a decisão sem transferir a informação. (§14.13)

## Arquivo, edição e destruição

- Antes de editar um artefato, verificar se ele é GERADO:
  `ls 06-validacao/geradores/gen-<nome>.py`. Se for, editar o gerador, nunca o
  artefato. Se não existir gerador e o artefato for de bancada ou de tela,
  escrever o gerador. (§14.4)
- Antes de editar qualquer arquivo existente, abrir e ler o arquivo real. Nunca
  confiar em resumo, em memória de conversa anterior ou em descrição de terceiro.
- `cp`/`mv`/`rm` sempre por NOME, nunca por curinga. Curinga apaga o que você não
  listou. (§14.6)
- Deletar arquivo não committado: só com confirmação explícita do Rafael no chat,
  porque é irrecuperável. Deletar arquivo committado: também com confirmação —
  não pelo risco de perda, que o histórico cobre, mas porque remover um canônico
  é decisão de conteúdo, dele. (§14.6 + §13.3)
- O PROCESSO DE REMOÇÃO, formalizado por ele em 2026-08-22 (origem da regra: o
  Cowork deletou um arquivo que SUPÔS não precisar): **a sessão é dona do
  processo** — identifica a necessidade, apresenta uma TABELA com nome do
  arquivo, o que ele faz e por que pode ser deletado, com veredito embasado
  (o INDICE.md já carrega isso por arquivo). O Rafael é só a contramedida:
  aprova ou veta. Verbatim: *"é voce quem toma conta do processo, eu só sirvo
  de conta medida para evitar deletar algo que nao poderia."*
- Nunca canalizar saída de gerador para `head`/`tail`. O gerador morre com broken
  pipe e grava saída parcial que parece completa. (§14.7)
- ANTES DE PROPAGAR material antigo (aprovado numa época, formalizado depois):
  verificar se ele não colide com o que foi construído DEPOIS dele — decisões
  posteriores revisam arquivos já feitos, e propagar sem essa revisão espalha
  não-conformidade. Ordem dele, 2026-08-22, na aprovação da MR-P11. A regra pegou
  seu primeiro caso REAL no mesmo dia em que nasceu: a "pendência crítica da F5"
  que esta linha citava como exemplo era um FANTASMA — o roadmap (parado em
  2026-08-10) a declarava aberta, mas ela fechou em 2026-08-11; só a verificação
  de conformidade contra o `seed-dataviz.md` v0.20 e o `ESTADO_ATUAL` v2.1 impediu
  reabrir um trabalho concluído. Corolário: a verificação vale também para
  DOCUMENTOS DE ESTADO — o mais recente vence (roadmap v2.1, nota de cabeçalho).

## Instrumento e prova

- Pasta de prova ANTES do instrumento, com placar de referência escrito antes de
  rodar. FAIL é o resultado desejado na cobaia. O placar só se ajusta depois de
  entendida a causa de cada divergência. (§14.8)
- Régua nova que reprova EM BLOCO está medindo outra coisa. Primeira hipótese: o
  instrumento, não o artefato. (§14.9)
- Um estado de render por carregamento fresco, mais prova de estabilidade: 0 px de
  diferença em duas cargas. (§14.10)
- O gate humano acha o que a automação não pode achar, e isso é estrutural.
  Quando o gate acha algo, o achado vira guarda antes de a spec ser promovida.
- Toda âncora de integridade é provada no ambiente de destino, não na origem:
  conferência de transporte via git roda dentro de um clone limpo do remoto,
  nunca só na cópia local. Provado nesta fundação: a cópia local passava com
  347 OK enquanto o clone, sem `.gitattributes`, devolveria 347 divergentes.

## Preview visual

- `preview/atual.html` é a ÚNICA página de trabalho visual, e mostra somente o
  problema ou brick em andamento.
- Ao iniciar brick novo: arquivar o `atual.html` vigente em
  `preview/arquivo/AAAA-MM-[tema].html` e só então sobrescrever. Sobrescrever sem
  arquivar antes é permitido apenas se o conteúdo já estiver committado; se
  estiver sujo e não arquivado, perguntar.
- No fechamento de cada brick: mover para `preview/arquivo/AAAA-MM-[tema].html`.
- Estilos compartilhados em `preview/preview.css`.
- O preview é lente de revisão, não documentação. As regras canônicas moram em
  `01-canonicos/` e `02-tokens/`. Nada é verdade porque está no preview.
- `preview/` é isento da regra de gerador (§14.4), que governa artefato promovido
  em `05-html-de-referencia/`. No momento em que um preview é promovido a
  bancada, a regra passa a valer e o gerador é pré-requisito da promoção.

## Escrita, documentação e commits

- **Não economize contexto. TUDO que for salvo — documentação, mensagem de
  commit, proposta, registro, memória — tem de trazer contexto suficiente para
  que alguém que não sabe NADA entenda do que se trata ao ler.**
  **A origem da regra (dele, 2026-08-24):** o Claude vinha salvando contexto tão
  curto que **nem ele próprio conseguia entender depois o que tinha salvado**.
  Registro que só faz sentido para quem estava na conversa não é registro — é
  lembrete, e lembrete vence. O caso que devolveu a regra à mesa foi a tabela de
  remoção: a contraprova devolveu "3 arquivos presos" sem mostrar O QUE estava
  preso, e ele teve de pedir os trechos para poder decidir.
  Corolário prático: nenhuma sigla órfã, nenhuma referência a "aquela decisão",
  nenhum número sem a unidade e sem de onde veio.
- Nenhuma sigla órfã: explique na primeira ocorrência.
- Toda decisão vem com o porquê e as alternativas descartadas. Decisão sem motivo
  registrado é decisão que a próxima pessoa desfaz por engano.
- Fato e inferência declarados como tais: onde mediu, o número; onde deduziu,
  `[inferência]`; onde não sabe, `[não conferido]`.
- Pendências explícitas e nomeadas.
- Nada que a próxima sessão precise vive só no chat. Nenhum documento de abertura
  pede anexo. (§14.3)
- Relatar não é parar. Sem pergunta pendente para o decisor, executa e reporta. (§14.2)

## Marca

- Grafia: "SEED engenharia". (§14.16)
- NUNCA recriar o logo ou o mascote EEny manualmente. Use os SVG oficiais em
  `03-assets/`. (§14.11)
- Tipografia: Montserrat. Cores e valores: só o que está em `02-tokens/`.

## Conformidade

- LGPD: nenhum dado pessoal de cliente (nome, CPF/CNPJ, endereço, número de
  unidade consumidora, valor de fatura) em resposta, em nome de arquivo ou em
  busca na web. Nenhuma credencial, identificador de conta de anúncio ou chave de
  API em conteúdo gerado. Chave de API é descartável: criada no uso, revogada
  depois. (§14.14)
- Nenhum resultado técnico vai a cliente ou a órgão sem revisão de engenheiro
  responsável. O design system não substitui a ART (Anotação de Responsabilidade
  Técnica, o registro no CREA que vincula um engenheiro ao serviço). (§14.15)

## Idioma

Português do Brasil. Tom direto, acolhedor, sem floreio vazio. (§14.17)

## Pendências abertas herdadas da fundação

- ~~`RM-P1` — `seed-ds-roadmap.md` desatualizado.~~ **FECHADA em 2026-08-22
  (roadmap v2.1, reconciliação de estado):** F5 e F6 marcadas fechadas, renumeração
  de fases de 2026-08-15 aplicada (F7 cobertura · F8 aplicações · F9 publicação),
  tabela de canônicos nas versões vigentes, e a regra de frescor no cabeçalho
  ("se o roadmap contradisser o ESTADO_ATUAL ou um changelog, o mais recente
  vence"). A previsão da pendência se confirmou antes de fechar: o documento
  "parecia confiável" e quase reabriu a formalização da F5, concluída 11 dias antes.
- `GT-P1` — definir o papel do Google Drive depois da migração. **MEDIDA e
  apresentada a ele em 2026-08-26** (ver a seção "Fonte de verdade" acima):
  o repositório mora dentro do Drive, e a pasta de origem segue gravável com
  172 canônicos divergentes. Aguarda o veredito dele sobre mover o repositório
  e renomear a pasta antiga. Nada foi executado.
- ~~Caminhos por nome nu: 34 scripts em `06-validacao/` abrem 121 arquivos por
  nome sem pasta.~~ **FECHADA em 2026-08-23/24 (F7.7-P1, o porte):** nasce o
  contrato `06-validacao/ferramentas/ambiente.mjs` (deps locais via
  `%JSDOM_DIR%`, Chrome real via `%CHROME_BIN%`, `acha`/`alvo`/`acervo` que
  ABORTAM em ambiguidade); as 55 suítes, as guardas, os contrastes e os 20
  geradores rodam na estrutura nova. Placar geral em `06-validacao/PLACAR.md`;
  registro completo no MANIFESTO §115. Régua nova de porte: gerador se prova
  por regeneração BYTE-IDÊNTICA contra o committado (a classe do CRLF), nunca
  por "rodou sem erro".