Começar
Para agentes de IA
O contrato que um agente segue para gerar interface HibouPay sem inventar.
No site publicado
O contrato curto está em /llms.txt. O laboratório visual está em /playground.
O contrato#
Um agente não precisa desta página renderizada: tudo aqui existe como JSON validado por schema.
| Leia | Para quê |
|---|---|
| /llms.txt | Contrato curto no site. O mesmo texto está na raiz do repositório e em @hiboupay/content/llms.txt. |
| AGENTS.md | Mapa: onde editar, o que nunca editar, comandos. |
| packages/content/dist/index.js | manifest + registry como objeto tipado (index.d.ts). |
| packages/content/domain/registry.json | Contrato de cada componente: props, estados, teclado, leitor de tela, fazer/evitar. |
| packages/tokens/dist/hibou.tokens.json | Todos os tokens DTCG com descrição. |
| /exports/HIBOUPAY_DESIGN_SYSTEM.md | Tudo acima num Markdown só, para colar no contexto. |
ts
import { registry, manifest } from "@hiboupay/content";
const button = registry.find((c) => c.slug === "button");
button.whenNotToUse; // quando não usar
button.props; // [{ name, type, default, required, description }]
button.keyboard; // [{ keys, action }]Regras invioláveis#
- 01Papel e vidro. Papel guarda dado e decisão. Vidro só no que navega por cima: barras, busca, compositor, toast.
- 02A coruja é o agente. Nenhum ícone genérico de IA. A coruja pisca quando vigia e ganha órbita quando trabalha.
- 03Mono é máquina. Índices, IDs, rótulos e estados em mono. O que a pessoa lê fica em Inter; o que decide, em Sora.
- 04Raios concêntricos. Raio interno = externo − padding. Cartão 16 com 4 de respiro abriga controle 12.
- 05Uma margem só. 16 · 24 · 40 por largura. Nenhuma tela inventa o próprio padding lateral.
- 06Luz, não faixa. Tom aparece como ponto e brilho. Nada de barra colorida no topo do cartão.
- 07Tokens são a fonte da verdade. Derivados (CSS, JS, JSON, MD) são gerados; editar derivado é bug e o check de drift bloqueia.
- 08O Core não conhece funil, estágio nem copy de um app. Consentimento, margem e sessão ficam no produto.
- 09Componente, token ou padrão que não está no registry não se inventa. Diga o que falta.
- 10Componente novo entra como experimental e só sobe com documentação completa e uso real.
- 11Mudanç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.
- 12Tamanho de texto só com a escala text-hb-*. Foco só com a utilitária hb-focus; campo usa hb-pupil.
- 13Overlay no celular é folha (hb-sheet); toast nasce no topo.
- 14Dinheiro, permissão, exclusão e execução de agente sempre abrem ConfirmGate.
- 15Se a ação entra no histórico, peça motivo (requireReason). Mínimo de 3 caracteres.
- 16Sempre com unidade: R$, %, pp, tokens. Valor em real usa formatBRL / formatCents do Core — o formato não é escolha de cada app.
- 17Célula vazia segue vazia.
- 18Faltou componente, token ou campo no contrato: diga o que falta. Não invente.
- 19Decisão ainda aberta não vira código. A pessoa registra a escolha antes.
Proposta, não ação
A coruja propõe; a pessoa decide. Consultar margem, enviar ou cobrar passa por um gate visível. Veja o padrão Agente propõe, humano decide.
Qual componente usar#
Gerado do registry. É a mesma tabela que o agente lê.
| Componente | Use quando | Não use quando | |
|---|---|---|---|
| Button | Disparar uma ação na tela atual: salvar, confirmar, abrir diálogo. | Navegar para outra página: use link. | estável |
| Card | Agrupar dado relacionado com título e ações. | Envolver a página inteira. | estável |
| Badge | Estado de um item: aplicado, aguardando, falhou. | Ação clicável: use Button. | estável |
| Input | Texto curto de uma linha: nome, e-mail, valor, busca. | Texto longo: Textarea. | estável |
| Select | Escolher um valor de lista curta dentro de formulário. | Filtro em barra: FilterChip. | estável |
| Textarea | Motivo, nota, descrição. | Uma linha: Input. | estável |
| Tabs | Alternar vistas do mesmo conjunto (Todos, Aguardando, Decididos). | Navegação entre páginas. | estável |
| FilterChip | Barra de filtros sobre lista ou quadro. | Campo de formulário: Select. | beta |
| Modal | Tarefa curta que precisa de foco: atribuir, editar um campo, revisar. | Confirmação de ação irreversível: ConfirmGate. | estável |
| ConfirmGate | Qualquer ação que não volta. | Ação desfazível: execute e ofereça desfazer. | estável |
| DataTable | Lista de registros com colunas comparáveis. | Poucos itens ricos: cartões. | estável |
| Avatar | Pessoa responsável em lista, cartão, conta. | Empresa ou marca: use logo. | beta |
| MetricWidget | Número-chave de painel com contexto. | Série temporal: gráfico. | beta |
| EmptyState | Lista ou área sem dados. | Erro recuperável numa área: ErrorBanner. | estável |
| ErrorBanner | Falha ao carregar ou salvar uma área. | Erro de campo: use error no Input. | estável |
| Spinner | Ação curta dentro de botão (automático com loading). | Carregando lista: Skeleton. | estável |
| Skeleton | Lista, tabela ou cartão carregando. | Ação curta: Button loading. | beta |
| HibouMark | Representar o agente. | Decoração repetida. | estável |
| Wordmark | Topo da navegação. | Espaço menor que 96px de largura: HibouMark. | estável |
| Checkbox | Aceitar um termo no formulário. | Uma entre poucas opções exclusivas: Radio. | beta |
| RadioGroup | 2 a 5 opções exclusivas no formulário: método, prazo, tom. | Lista longa: Select ou FilterChip. | beta |
| Switch | Preferência persistente: aviso por e-mail, modo compacto. | Escolher entre A e B: Radio. | beta |
| DropdownMenu | Ações secundárias de uma linha ou de um botão ícone. | Filtrar lista: FilterChip. | beta |
| Pagination | Rodapé de DataTable ou lista longa. | Poucos itens: mostre tudo. | beta |
| Progress | Upload, importação, job do agente com progresso conhecido. | Ação curta: Button loading / Spinner. | beta |
| FileUpload | Importar planilha, comprovante, anexo único ou poucos arquivos. | Galeria de mídia. Campo de texto. Arrastar para mudar ordem (não é este componente). | beta |
| ToastProvider | Confirmar que algo já aconteceu: "Planilha importada". | Erro que bloqueia a tarefa: ErrorBanner no lugar. | beta |
| Tooltip | Ícone sem texto (aria-label no gatilho + tooltip de apoio). | Informação essencial: coloque na tela. | beta |
| Grid | Fila de MetricWidget. | Tabela: DataTable. | beta |
| ChoiceCardGroup | Forma de pagamento no checkout. | Opção que cabe numa linha: Radio. | beta |
| Stepper | Checkout em etapas. | Processo de duração desconhecida: Progress. | beta |
| Notice | Consentimento e termo legal antes de uma ação. | Confirmação efêmera de algo que deu certo: Toast. | estável |
| SummaryList | Resumo do pedido antes de pagar. | Muitas linhas comparáveis com ordenação: DataTable. | beta |
| Slider | Quanto usar de um saldo: pontos, crédito, limite. | Valor exato que a pessoa já sabe: Input. | beta |
| StatusView | Espera de resultado que a pessoa não controla: análise, assinatura, liquidação. | Aviso dentro de uma tela cheia: Notice. | estável |
Prompt de sistema#
prompt
Você gera interface para produtos HibouPay.
Antes de escrever código, leia o contrato pelo pacote instalado:
import { registry, manifest } from "@hiboupay/content";
Regras:
1. Papel e vidro. Papel guarda dado e decisão. Vidro só no que navega por cima: barras, busca, compositor, toast.
2. A coruja é o agente. Nenhum ícone genérico de IA. A coruja pisca quando vigia e ganha órbita quando trabalha.
3. Mono é máquina. Índices, IDs, rótulos e estados em mono. O que a pessoa lê fica em Inter; o que decide, em Sora.
4. Raios concêntricos. Raio interno = externo − padding. Cartão 16 com 4 de respiro abriga controle 12.
5. Uma margem só. 16 · 24 · 40 por largura. Nenhuma tela inventa o próprio padding lateral.
6. Luz, não faixa. Tom aparece como ponto e brilho. Nada de barra colorida no topo do cartão.
7. Tokens são a fonte da verdade. Derivados (CSS, JS, JSON, MD) são gerados; editar derivado é bug e o check de drift bloqueia.
8. O Core não conhece funil, estágio nem copy de um app. Consentimento, margem e sessão ficam no produto.
9. Componente, token ou padrão que não está no registry não se inventa. Diga o que falta.
10. Componente novo entra como experimental e só sobe com documentação completa e uso real.
11. Mudanç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.
12. Tamanho de texto só com a escala text-hb-*. Foco só com a utilitária hb-focus; campo usa hb-pupil.
13. Overlay no celular é folha (hb-sheet); toast nasce no topo.
14. Dinheiro, permissão, exclusão e execução de agente sempre abrem ConfirmGate.
15. Se a ação entra no histórico, peça motivo (requireReason). Mínimo de 3 caracteres.
16. Sempre com unidade: R$, %, pp, tokens. Valor em real usa formatBRL / formatCents do Core — o formato não é escolha de cada app.
17. Célula vazia segue vazia.
18. Faltou componente, token ou campo no contrato: diga o que falta. Não invente.
19. Decisão ainda aberta não vira código. A pessoa registra a escolha antes.