Tinta para agir
O índigo marca tudo que é clicável e também a assinatura aplicada. A ação e a marca que ela deixa têm a mesma cor.
M. CostaMarina Costa
Guia · v0.1
Documentação do z-ui
Como instalar, como os tokens se organizam e quais regras mantêm o sistema coerente. Esta página é feita com os próprios componentes e classes do z-ui.
1 · Começar
Três passos até a primeira tela
O z-ui é um projeto Next.js com Tailwind v4. Você pode rodar o styleguide ou importar o tema em outro projeto.
Clone o repositório e instale as dependências. O styleguide abre em /styleguide.
git clone [email protected]:zforgehq/z-ui.git
cd z-ui
pnpm install
pnpm dev2 · Princípios
Tinta, lacre e papel
Três materiais definem a identidade. Cada um tem um papel e não invade o do outro.
Lacre para certificar
Selos, certificados e verificações usam lacre. Assim ninguém confunde “certificado” com “clique aqui”.
Assinatura válidaDocumento íntegro e assinado
- Hash
- 9f2c41abe07d3c58
- Certificado
- ICP-Brasil A1
O papel não inverte
A folha usa a ilha .theme-light. Troque o tema na barra lateral: a interface escurece e o documento continua claro.
CLÁUSULA 1ª · DO OBJETO. Prestação de serviços de assinatura eletrônica.
3 · Tokens
Anatomia de um token
Toda classe de cor percorre o mesmo caminho. Você só escreve as duas primeiras camadas. A ponte é gerada por pnpm theme:sync.
- 1Primitivaprimitives/colors/brand.css
--color-brand-700: oklch(0.475 0.166 268); - 2Semânticosemantic/colors/background.css
--color-bg-primary: var(--color-brand-700); - 3Pontesrc/app/theme-bridge.css
--color-bg-primary: var(--color-bg-primary); - 4Classecomponente
className="bg-bg-primary"
Resultado: bg-bg-primary. No escuro, o semântico aponta para brand-300 e a amostra ao lado clareia sem mudar a classe.
4 · Uso
Qual classe usar
Comece pela intenção, não pela cor.
| Quero | Classes | Resultado |
|---|---|---|
| Botão de ação principal | bg-bg-primary text-fg-on-primary | |
| Mostrar que algo foi certificado | bg-bg-accent text-fg-on-accent | Válido |
| Estado de um envelope | bg-status-*-subtle text-status-* | Em assinatura |
| Hash, CPF ou protocolo | text-data-sm text-doc-hash | 9f2c41ab…3c58 |
| Assinatura aplicada | text-signature-md text-doc-ink | M. Costa |
| Texto secundário | text-body-sm text-fg-muted | Enviado há 2 dias |
5 · Regras
O que manter e o que evitar
Só tokens semânticos
className="bg-bg-primary-subtle text-fg-primary"className="bg-brand-50 text-brand-700"A primitiva não muda no tema escuro. O semântico muda.
Nada de valor arbitrário
className="h-form-md text-body-md"className="h-[40px] text-[14px]"Se falta um token, ele é criado no tema e passa pelo teste de contraste.
Lacre não é botão
<Seal state="valid" … /><button className="bg-bg-accent">Assinar</button>Lacre significa certificado. A ação usa a tinta.
Classe de signatário por mapa
signerClasses[signer].solid`bg-signer-${n}`O Tailwind não enxerga classe montada por string.
6 · Revisão
Checklist antes de abrir um PR
Marque os itens conforme confere. O status acompanha o andamento, com o mesmo componente que mostra o estado de um envelope.
0 de 6 conferidosNão iniciado
7 · Contribuir
Propor um token novo
Antes de criar, confira as cores existentes. Se nenhuma serve, monte a proposta: o diálogo gera o trecho de CSS para os dois temas.
VocêAutor da proposta · aguardando