Diretrizes

Governança

Como um componente nasce, amadurece e sai. Versão, drift e contribuição.

Ciclo de vida de um componente#

01
Proposta: o problema real e onde aparece
02
Contrato no registry ou no manifesto, revisado por uma pessoa
03
Implementação no Core, sem funil nem copy de um app
04
Documentação e story no mesmo verbo
05
Release SemVer com changelog
06
Sensor: pnpm ds:check e pnpm verify

Maturidade#

Nível	Promessa
experimental	Pode mudar sem aviso. Não use em fluxo crítico.
beta	API estável na intenção; pode ganhar props. Breaking só em minor com nota.
estável	Breaking só em major, com guia de migração.
obsoleto	Tem substituto documentado. Sai na próxima major.

Regras#

01Tokens são a fonte da verdade. Derivados (CSS, JS, JSON, MD) são gerados; editar derivado é bug e o check de drift bloqueia.
02O Core não conhece funil, estágio nem copy de um app. Consentimento, margem e sessão ficam no produto.
03Componente, token ou padrão que não está no registry não se inventa. Diga o que falta.
04Componente novo entra como experimental e só sobe com documentação completa e uso real.
05Mudança de contrato começa no manifesto ou no registry, com revisão humana, antes do código. pnpm verify é o sensor: typecheck, drift, lint de valor solto, axe por story e uma story por slug.
06Tamanho de texto só com a escala text-hb-*. Foco só com a utilitária hb-focus; campo usa hb-pupil.
07Overlay no celular é folha (hb-sheet); toast nasce no topo.

SemVer#

Tipo	Quando
major	Remover prop, renomear token, mudar comportamento padrão.
minor	Novo componente, nova prop opcional, novo token.
patch	Correção visual ou de acessibilidade sem mudar a API.

Contribuir#

# 1. edite a fonte (tokens, manifest ou registry)
# 2. regenere e verifique
pnpm ds:build && pnpm verify
# 3. registre no CHANGELOG.md com o tipo SemVer

Componente novo entra como experimental

Com todos os campos do registry preenchidos: anatomia, estados, props, teclado, leitor de tela, fazer/evitar, conteúdo e tokens. O schema recusa verbete incompleto.