Começar

Arquitetura

Domínio, portas e adaptadores: onde cada decisão mora e por quê.

Hexagonal, em três camadas#

As decisões vivem num núcleo de dados. Tudo que aparece na tela é um adaptador que lê esse núcleo.

Domínio

O que o sistema decide

packages/tokens/src/hibou.tokens.json
packages/content/domain/manifest.json
packages/content/domain/registry.json

JSON puro. Não importa React, Next nem o app consumidor.

Portas

O contrato que o domínio aceita

packages/content/schema/manifest.schema.json
packages/content/schema/registry.schema.json
packages/content/scripts/validate.mjs

Dado fora do schema, slug repetido, token inexistente ou related quebrado falham o build.

Adaptadores

Quem só lê o domínio

packages/tokens/scripts/build.mjs → CSS, JS, d.ts
packages/react · packages/icons
apps/docs · apps/storybook · tooling/export
apps consumidores: checkout e backoffice

Trocar um adaptador nunca muda uma decisão.

Repositório#

árvore

hiboupay-design-system/
├─ packages/
│  ├─ tokens/     src/hibou.tokens.json  →  dist/tokens.css · index.js · index.d.ts
│  ├─ content/    domain/*.json · schema/*.json  →  dist/index.js · HANDBOOK.md
│  ├─ react/      src/components/* · src/styles/* · tailwind-preset.js
│  └─ icons/      src/HibouMark.tsx · Wordmark.tsx · paths.ts
├─ apps/
│  ├─ docs/       Next 15 · esta documentação (raiz / ; local porta 3100)
│  └─ storybook/  laboratório visual (/playground ; local porta 6006)
├─ tooling/
│  └─ export/     handbook · bundle ZIP · PDF · check-drift
├─ legacy/        Storybook antigo (Gymove), só leitura
├─ AGENTS.md      mapa para agentes e mantenedores
├─ llms.txt       contrato curto para o contexto
├─ GOVERNANCE.md  ciclo de vida e SemVer
└─ CHANGELOG.md

Onde editar#

Quer mudar	Edite	Nunca edite
Cor, espaço, raio, vidro, movimento	packages/tokens/src/hibou.tokens.json	packages/tokens/dist/*
Princípios, marca, padrões, voz, governança	packages/content/domain/manifest.json	packages/content/dist/*
Contrato de um componente (props, estados, a11y)	packages/content/domain/registry.json	Texto solto no TSX das docs
Visual e comportamento do componente	packages/react/src/components/*.tsx	Classe copiada no app
Classes globais (vidro, label, animação)	packages/react/src/styles/utilities.css	globals.css do app
Coruja e imagotipo	packages/icons/src/*	SVG colado no app
Exemplo vivo de componente	apps/docs/content/components/demos/*.tsx	registry.json

Fluxo de uma mudança#

01Edite a fonte (tokens JSON, manifest ou registry).
02pnpm ds:build regenera CSS, JS, tipos e handbook; o schema valida o domínio.
03Ajuste o componente em packages/react, se for visual.
04pnpm verify roda typecheck, drift e uma story por slug do registry.
05Atualize o CHANGELOG com o tipo SemVer da mudança.

Drift é erro

Nenhum arquivo em dist/ ou public/exports é editado à mão. Se o check de drift falhar, rode o build; não conserte o derivado.

O que fica fora do sistema#

Semântica de produto fica no aplicativo: consentimento, margem, sessão, contrato. O Core entrega a peça e a regra visual. Quando dois produtos precisarem da mesma peça, ela sobe para o sistema como experimental.