Canon Avancci · Hiperclini

Um sistema calmo pra uma clínica intensa.

Este é o guia vivo do design system da Hiperclini: cada cor, tipo, curva, sombra, componente e padrão de tela, renderizado com os tokens REAIS do produto. Serve de contrato pra qualquer tela nova, feita por gente ou por agente — e o alvo de todas elas é o mesmo: sua clínica no seu melhor.

Next.js 16Tailwind v4shadcn/ui + RadixLucideInter + JetBrains Mono5 temas

Como usar este guia

Três leituras diferentes do mesmo texto, dependendo de quem chega.

Designer

Comece por Princípios, Cor e Forma. O vocabulário é curto de propósito — duas formas, uma cor de marca, uma cor de IA — e é ele que faz qualquer tela nova parecer da casa. Antes de propor um elemento novo, procure nos Componentes: quase sempre já existe com outro nome.

Quem escreve o código

Cada página termina em token, classe e arquivo. Nada de hex ou px solto: o teste do repositório recusa cor literal fora de globals.css. Copie o nome do token (clique na amostra) e a receita do componente, não o valor.

Agente

Leia as doze regras e as Fontes da verdade antes de escrever a primeira linha. Em conflito com qualquer documento antigo, vale o código + esta página. Tela nova NÃO reimplementa padrão: herda de EditSurface, Field, PageBar e PageStage.

O guia inteiro

Trinta páginas, na ordem em que fazem sentido lidas de ponta a ponta.

Começar

PrincípiosSeis decisões que valem pra qualquer tela. Layout que briga com uma delas perde.MarcaSímbolo, trava, tamanhos mínimos, o verde congelado — e por que fora do app a marca é sempre o Claro.

Fundações

CorCinco temas, um vocabulário — e a trava: os escuros são só do app. Papéis, escalas, contraste.TipografiaInter e JetBrains Mono, escala completa, features, tabular-nums e medida de leitura.Espaço & ritmoA escala áurea φ, a base-4 do Tailwind, a receita de ritmo e a largura de página.Forma & elevaçãoToca = pílula · contém = canto 16. Raios, exceções, bordas e a escala de sombra.MovimentoDurações, curvas, a gaveta, o pulso e o contrato com prefers-reduced-motion.ÍconesLucide outline, tamanhos por contexto e o vocabulário fixo de cada domínio.Foco & acessibilidadeO anel de 3px, alvo de toque, teclado, ARIA e as regras de contraste.

Componentes

ÍndiceTodos os primitivos, onde moram no repositório e quando usar cada um.BotãoSete variantes, sete tamanhos, o crescimento no dedo e o botão de IA.Campos de formulárioInput, Textarea, Select, Busca, OTP, Checkbox, Label e o Field que costura tudo.CardA superfície padrão, o vivo ao toque, o card clicável e o cartão de resumo.Menus & seleçãoDropdownMenu pra agir e pra escolher — duas gramáticas na mesma peça, e por que não se trocam.Diálogos & confirmaçãoDialog, ConfirmDialog e a tarja de confirmação que substituiu o duplo clique.Status & selosStatusPill, os selos da jornada do paciente e as badges genéricas.Vazio, carregando & erroEmptyState, skeleton, erro de rota, alerta de formulário e toast.NavegaçãoSidebar, rail, barra de tela, abas e o retrato de conta.Edição no lugarCrudCard, Gaveta, EditSurface e a linha que vira ficha sem sair da tela.

Padrões de tela

Anatomia de uma telaA ordem vertical fixa: cabeçalho, resumo, ferramentas, lista, detalhe.Palco de telaAs três colunas e as duas linhas invisíveis que alinham toda tela com sub-telas.Barra de telaA faixa de 56px, o rastro Tela · Seção e o salvar que sobe pra ela.Foco em camadasA assinatura do produto: editar afunda o resto da tela em degraus.Split de acessoPainel de tinta à esquerda, formulário à direita — entrar, cadastro, convite.Ações em massaSeleção por checkbox e a barra pílula que sobe do rodapé.

Conteúdo

Voz & escritaComo o produto fala: verbo no infinitivo, sentence case, erro que não culpa.Números, datas & unidadesFormatos pt-BR de dinheiro, telefone, data, hora e tempo relativo.

Contrato

As doze regrasO checklist duro de toda tela nova — mais a regra que vale fora dela: material da marca é sempre o tema Claro.Fontes da verdadeOnde cada coisa mora no repositório e quem manda em caso de conflito.

Por que “guia vivo”

Nenhum valor desta página foi digitado duas vezes. As amostras leem o token no navegador, no tema que você escolheu no topo.

A página é o app

As amostras de cor são pintadas com var(--token) e o valor exibido sai de getComputedStyle. Os botões, campos, diálogos e selos são os componentes de src/components/ui/* importados de verdade — não cópias. Mudou o token ou o primitivo, o guia muda no mesmo deploy, sem ninguém lembrar de atualizar figura.

O que a máquina já garante

Três testes do repositório seguram o canon: tokens.test.ts recusa hex solto fora de globals.css; contraste.test.ts parseia o CSS e mede os pares texto/fundo dos cinco temas contra o WCAG AA; aparencia.test.ts prende a régua de “claro ou escuro”. Regra que virou teste não volta a ser disciplina de revisão.

NotaTrocar o tema aqui não mexe no app

O seletor no topo grava em localStorage com chave própria (hc-ds-tema). O tema do app é da CONTA — vive no banco e no cookie hc-tema, e é escolhido em Ajustes ◊ Aparência. Ver tudo em Ardósia por dez minutos não muda a tela de ninguém.

O que este guia não é

Ele responde “como a interface se comporta”. As outras duas perguntas moram em outro lugar.

Pergunta	Onde mora
O que o produto faz, pra quem, e em que ordem construir	docs/PRODUTO.md
Quais entidades existem, que estados elas têm, o que significa cada status da jornada	docs/DOMINIO.md
Como o repositório funciona: stack, comandos, deploy, guardrails do agente	AGENTS.md
As armadilhas já pagas (Next 16, React 19, Radix, Supabase, foco em camadas)	LEARNINGS.md
Como a interface se comporta	esta página

ordem de leitura pra uma tela nova

1. AGENTS.md            → o que este repositório espera de você
2. LEARNINGS.md         → o que já custou caro e não se repete
3. /design-system       → como a tela se parece e se comporta  ← você está aqui
4. docs/DOMINIO.md      → o que os dados da tela significam