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.

Começar Ver a tela de assinatura

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 git@github.com:zforgehq/z-ui.git
cd z-ui
pnpm install
pnpm dev

2 · Princípios

Tinta, lacre e papel

Três materiais definem a identidade. Cada um tem um papel e não invade o do outro.

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

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.

Página 1DOC-001

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);
4ClassecomponenteclassName="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

Usei apenas classes semânticas, sem primitivas nem valores arbitrários

Conferi a tela no tema claro e no escuro

Conferi em 375px de largura, sem rolagem horizontal

Todo controle tem foco visível com focus-ring

Rodei pnpm theme:sync depois de mexer no tema

pnpm lint, pnpm test --maxWorkers=2 e pnpm build passaram

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