@huitzo/dashboard-primitives

Copy-in (shadcn-style) registry of hz-* primitives for Huitzo Dashboards.

Each primitive ships as readable .tsx source — not a compiled black box. An AI agent (or a human) reads the source, copies it into a dashboard project with huitzo primitives add <name> (PR-B6), and modifies it in place. Every file is SHA-256 hash-pinned in registry.json and the package is published with npm provenance so the supply chain is tamper-evident end to end.

Spec: docs/dashboards/v6/epic-b-ai-tooling-spec.md §3.3 (Phase 3: Primitives) and §7 (Primitive Seed).

Seed primitives

| Primitive | Import | Purpose | |-----------|--------|---------| | hz-card | @huitzo/dashboard-primitives/hz-card | Universal container (default / accent / success / warning, md / lg). | | hz-btn | @huitzo/dashboard-primitives/hz-btn | Universal CTA (primary / secondary / ghost); renders <button> or safe <a>. | | hz-stat | @huitzo/dashboard-primitives/hz-stat | Stat with delta arrow, inline SVG sparkline, locale-aware number formatting. | | hz-chart | @huitzo/dashboard-primitives/hz-chart | line / area / bar chart (Recharts), brand-token axes + locale-aware ticks. | | hz-table | @huitzo/dashboard-primitives/hz-table | Virtualized data grid (TanStack Table + Virtual), sortable, density variants. | | hz-form | @huitzo/dashboard-primitives/hz-form | Zod-schema-driven form (React Hook Form), field-level errors, optimistic submit. | | hz-stream | @huitzo/dashboard-primitives/hz-stream | Token-stream display with markdown, stop button, copy-on-complete. |

hz-eyebrow and hz-terminal remain CSS classes in @huitzo/dashboard-sdk-react and are deferred to PR-B5.5 — authors are not blocked.

Design contract

Every primitive in the seed obeys .claude/rules/dashboard-design.md:

• Brand tokens only. Color, spacing, radius, shadow, and transitions resolve through var(--*) brand tokens — no hex literal, RGB triple, or HSL value anywhere in the source.
• Accessibility floor. Every interactive element is keyboard-navigable; forms wire aria-describedby, tables sort by keyboard, charts expose an accessible data fallback.
• AI-friendly authoring. Discriminated string-union variant props, TSDoc with an example per prop, a className escape hatch, and sensible defaults.

Layout

registry/
  hz-card/
    index.tsx          # the component (copy-in source)
    hz-card.module.css # the styles  (copy-in source, brand tokens only)
    meta.json          # name, description, tags, variants, tokens, file hashes
    README.md          # usage notes (read by the MCP server / Claude Skill)
    hz-card.test.tsx   # co-located component + a11y + token tests
  ...
registry.json          # generated manifest: per-file SHA-256 across all primitives
scripts/gen-registry.mjs

Regenerate the manifest after editing any primitive:

npm run gen-registry   # rewrites meta.json files[] + registry.json
npm test               # registry-hashes.test.ts guards against drift

Tree-shaking

There is no barrel entry — you import one primitive at a time (@huitzo/dashboard-primitives/hz-card). Importing hz-card never pulls in Recharts, TanStack, React Hook Form, or react-markdown; those stay external to their respective primitive bundles.