@kruzer/ds

Design System Kruzer — sucessor da @kruzer/[email protected]. Construído com React 19 + Tailwind 4 + Radix + shadcn + tsup. Compatível com React 18.3+ ou 19 no consumer (peer dep).

Status: Fase 1 — alpha interno. Em uso no OMS Demo. API ainda pode mudar.

Sumário

• Como consumir
• Scripts
• Desenvolvimento local
• Estrutura do repo
• Distribuição
• Convenções
• Documentação interna

Como consumir

A lib é publicada no npm público, sob a tag alpha (mesmo modelo da @kruzer/lib-ui). No projeto consumidor:

npm install @kruzer/ds@alpha

Instale com @alpha — não existe tag latest enquanto a lib estiver em alpha. npm install @kruzer/ds puro falha.

Uso

import { Button, KPICard, EmptyState } from "@kruzer/ds";
import "@kruzer/ds/styles.css";

export function App() {
  return (
    <div>
      <KPICard label="Pedidos hoje" value="1.247" />
      <Button>Novo pedido</Button>
    </div>
  );
}

Peer dependencies

A lib aceita React 18.3+ ou 19. No consumer, garante que estes estão instalados:

npm install react@^18.3.0 react-dom@^18.3.0 react-router-dom@^6
# ou react@^19 / react-dom@^19

A lib em si é desenvolvida em React 19 (ver devDependencies). A peer dep é ampla pra suportar consumers que ainda estão em React 18 (ex: OMS Demo).

Scripts

| Comando | O que faz | |---|---| | pnpm dev | Sobe o portal /ui-kit em http://localhost:5173 (Vite + HMR) | | pnpm build | Build da lib via tsup (gera dist/ com ESM + CJS + d.ts + styles.css minificado) | | pnpm build:docs | Build estático do portal em dist-docs/ (pra GitHub Pages) | | pnpm preview | Preview do build do portal | | pnpm typecheck | tsc --noEmit | | pnpm lint | ESLint |

Desenvolvimento local

pnpm install
pnpm dev

Abre http://localhost:5173 — portal interno com Landing, 5 foundations (Cores / Tipografia / Espaçamento / Sombras / Border radius), 32 docs de componente, 6 patterns, 4 guidelines e o Legacy (referência).

Modo dev paralelo com o consumer

Pra refletir mudanças locais da lib no OMS Demo sem commitar a cada vez:

# Na lib (este repo)
cd ~/Desktop/lib-ui-v2
npm link

# No consumer
cd ~/Desktop/prototipo-oms-demo
npm link @kruzer/ds

Se npm install falhar com EACCES no cache global, rode com --cache /tmp/npm-cache-kruzer ou conserte com sudo chown -R "$(id -u):$(id -g)" "$HOME/.npm".

Estrutura do repo

.
├── src/                          # ⭐ CÓDIGO DA LIB (API pública)
│   ├── index.ts                  # barrel export (raiz + shadcn + wrappers + tipos)
│   ├── lib/utils.ts              # cn() helper
│   ├── hooks/use-mobile.ts
│   ├── styles/
│   │   ├── kruzer-tokens.ts      # 110 tokens HEX extraídos do Figma
│   │   └── globals.css           # :root semântico + @theme Tailwind 4 + @source
│   └── components/
│       ├── ui/                   # 81 componentes (40 shadcn primitives + 40 wrappers Kruzer)
│       ├── PageHeader.tsx
│       ├── DetailPageHeader.tsx
│       ├── KpiCard.tsx
│       └── Timeline.tsx
│
├── docs/                         # ⭐ PORTAL /ui-kit (Vite app interno)
│   ├── index.html
│   ├── main.tsx
│   ├── App.tsx                   # 39 rotas BrowserRouter
│   └── pages/
│       ├── Layout.tsx            # sidebar de navegação
│       ├── Landing.tsx           # hero + 5 princípios
│       ├── Legacy.tsx            # demos rolantes (referência)
│       ├── foundations/          # Colors, Typography, Spacing, Shadow, Radius
│       ├── components/           # 32 *Doc.tsx + _DocLayout.tsx
│       ├── patterns/             # 6 *Pattern.tsx + _PatternLayout.tsx
│       └── guidelines/           # voice-and-tone, naming, a11y, i18n
│
├── dist/                         # ⭐ BUILD DA LIB (commitado no git)
│   ├── index.js / index.cjs      # ESM + CJS
│   ├── index.d.ts / index.d.cts  # TypeScript types
│   ├── styles.css                # CSS pré-processado pelo Tailwind CLI 4 (minificado)
│   └── kruzer-tokens.ts          # tokens do Figma (consumível direto)
│
├── _work/                        # Artefatos de planejamento (não publicado)
│   ├── inventario-side.md
│   ├── catalogo-v1.md
│   └── checklist.md
│
├── CLAUDE.md                     # Regras invariantes e decisões do projeto
├── package.json                  # peer deps: React 18 ou 19, react-router-dom 6
├── tsup.config.ts                # build da lib + Tailwind CLI no onSuccess
├── vite.config.ts                # root=docs, outDir=../dist-docs
├── tsconfig.json / tsconfig.build.json
├── eslint.config.js
└── .prettierrc.json

Distribuição

Publicado no npm público sob a tag alpha, mesmo modelo da @kruzer/lib-ui:

• Release: GitHub Release no repo kruzer-corp/Kruzer-DS dispara o workflow .github/workflows/publish.yml, que roda npm ci → npm run build → npm publish --tag <alpha|beta|rc|latest> --access public (tag derivada da versão no package.json).
• Auth: token via .npmrc (//registry.npmjs.org/:_authToken=${NPM_TOKEN}) + secret NPM_TOKEN_PUBLISH no repo.
• Versão: o workflow não incrementa — faça o bump em package.json antes de cada release.

Convenções

• React.forwardRef em todo componente que renderiza um elemento HTML.
• asChild via @radix-ui/react-slot para composição.
• Variantes via cva() — sem inline conditionals em className.
• cn() helper em src/lib/utils.ts.
• displayName sempre setado.
• Tokens: brandbook Kruzer (HEX em kruzer-tokens.ts) é a fonte; CSS vars em :root mapeiam pra tokens semânticos (--primary, --background, etc.); Tailwind 4 @theme inline expõe como classes utilitárias (bg-primary, text-foreground).
• Tipografia: DM Sans (display, headings) + Inter (body) — carregadas via <link> no docs/index.html (consumer carrega por conta).
• Tailwind 4: arbitrary CSS vars usam parênteses (w-(--var), não w-[--var]).

Documentação interna

• CLAUDE.md — regras invariantes e decisões pós-revisão do time.
• _work/inventario-side.md — inventário do side project (OMS Demo).
• _work/catalogo-v1.md — catálogo de exports da v1 (sem implementação).
• _work/checklist.md — cross-reference side × v1 (Checkpoint A).