Contrato

Fontes da verdade

Onde cada coisa mora no repositório, e quem manda quando dois documentos discordam. Regra curta: em conflito com qualquer texto, vale o código + esta página.

repositório hipercliniAGENTS.mdLEARNINGS.md

O canon visual

Tudo que esta página documenta sai destes arquivos.

Arquivo	O que mora lá
src/app/globals.css	TODOS os tokens: cores dos 5 temas, escala φ, raios, sombras, o remap do shadcn, as utilities (focus-ring, skeleton, pulso) e as regras globais do foco em camadas.
src/app/layout.tsx	As fontes (next/font: Inter + JetBrains Mono), o data-theme do <html> e o Toaster.
src/components/ui/*	Os primitivos: botão, campos, card, diálogo, menu, selo, vazio, esqueleto, edição no lugar.
src/components/hiperclini-mark.tsx	A marca vetorizada — símbolo e trava, com a variante mono.
src/components/page-bar.tsx · page-body.tsx · page-stage.tsx	Os cabeçalhos e o corpo de uma tela: barra, palco e o slot de salvar.
src/lib/tema/*	Os temas (slug, rótulo, aparência, cookie) e os três testes que prendem o canon.
src/lib/format.ts · format-date.ts · phone.ts	Todo formato pt-BR de número, dinheiro, data, duração e telefone.
src/app/design-system/*	Esta página. Atualizar junto com qualquer mudança de canon.

O que NÃO é canon visual

Três perguntas que esta página não responde — e não deve.

Pergunta	Documento
O que o produto faz, pra quem, em que ordem construir	docs/PRODUTO.md
Quais entidades existem, que estados elas têm, o que significa cada status	docs/DOMINIO.md
O que testar antes de entregar (roteiro do founder)	docs/TESTES.md
Como o repositório funciona: stack, comandos, deploy, guardrails	AGENTS.md
O que já custou caro e não se repete (Next 16, React 19, Radix, Supabase, foco em camadas)	LEARNINGS.md
O estado das entregas e o que falta	CHECKLIST.md

NotaAGENTS.md é contexto estável; LEARNINGS.md é regra vinda de dor

Os dois não se duplicam de propósito. Se uma regra nasceu de um bug que custou tempo, ela vai pro LEARNINGS com o sintoma junto — é o sintoma que faz alguém reconhecer o problema da próxima vez.

Quem manda

A ordem, quando dois lugares dizem coisas diferentes.

1. O código           — o que está em globals.css e em ui/* é o que roda
2. Este guia          — a explicação do porquê, e o contrato pra tela nova
3. LEARNINGS.md       — as armadilhas, com o sintoma que as revela
4. AGENTS.md          — o contexto do repositório
5. Qualquer outro doc — se contradiz os quatro acima, está velho

Achou uma divergência? Ela é um bug de documentação, e fecha-se do jeito mais barato: mudar o código quando o guia está certo, ou mudar o guia quando o código está certo. Nunca deixar as duas versões no ar “pra decidir depois”.

Como este guia se mantém

Guia vivo não é promessa — é uma consequência de como ele foi feito.

As amostras leem o token

Cor exibida sai de getComputedStyle no navegador, no tema vestido. Nenhuma tabela de hexadecimais copiada à mão.

As demonstrações importam os componentes

Botão, campo, diálogo, selo e a gaveta são os de src/components/ui/*. Mudou o primitivo, mudou o guia.

Os formatos chamam as funções

Os exemplos de dinheiro, telefone e duração são gerados por src/lib/format.ts na renderização.

A navegação tem fonte única

src/app/design-system/ds/nav.ts alimenta o rail, a busca, o índice e os vizinhos. Página nova = uma linha lá.

Onde ele vive

Endereço	O que é
design.hiperclini.com.br	O endereço público do guia. Sem login, sem indexação no buscador.
app.hiperclini.com.br/design-system	O mesmo guia por dentro do app — útil pra quem já está logado.
localhost:3000/design-system	Em desenvolvimento, junto com o app.

O domínio próprio aponta pro MESMO projeto Vercel: quem reescreve o caminho é o src/proxy.ts, e o prefixo de cada link sai do host lido no layout. É o que garante que o guia e o app nunca saem de sincronia — eles são o mesmo deploy.

NotaEste guia não indexa no Google

robots: { index: false, follow: false } no layout — a metade forte da cerca. Quem tem o link entra; o buscador não. É uma escolha: o vocabulário aqui é interno.