Component-first UI system (primitives/composites/layout, CVA, tokens)

Generated from mcp/patterns.registry.json — do not edit by hand; change the registry and run bun run patterns:build.

Category: UI Components & Design System · Tier: deep · Risk: low — frontend only

A layered component system — Bits UI → primitives (styled atoms) → composites (business logic) → layout (structural wrappers) — styled entirely through CVA → UnoCSS → design-token CSS variables.

When to use: Emulate when a project needs consistent UI at any scale: the layer split keeps styling decisions in one place and bans ad-hoc HTML.

Docs

• docs/blueprint/design/README.md — Design philosophy hub (GitHub · GitLab)
• docs/blueprint/design/components.md — Layer system and CVA variant rules (GitHub · GitLab)
• docs/blueprint/design/tokens.md — Token architecture (breakpoints, fluid type/space, elevation) (GitHub · GitLab)
• docs/blueprint/design/styling.md — Styling flow and layout primitives (GitHub · GitLab)

Code

• src/lib/components/primitives/ — ~40 styled atoms wrapping Bits UI (GitHub · GitLab)
• src/lib/components/composites/ — Components with business logic (GitHub · GitLab)
• src/lib/components/layout/ — Structural wrappers (Stack, Cluster, Surface) (GitHub · GitLab)
• src/lib/styles/tokens.ts — Design tokens (GitHub · GitLab)
• uno.config.ts — UnoCSS theme wiring (GitHub · GitLab)

Tests

• src/lib/components/composites/dock/dock.operations.test.ts — Example colocated component test (GitHub · GitLab)

Proof

• /showcases/ui/components
• /showcases/ui/layouts
• /showcases/ui/tokens

Invariants

• Never use raw HTML elements when a project component exists — raw // bypass the design system.
• Styling flows through CVA → UnoCSS utilities → token-backed CSS variables; components never hardcode colors or spacing.
• Components are zero-margin; layout is gap-based on the spacing scale.

Emulation notes

• Adopt the layer vocabulary first (primitive/composite/layout) — it decides where every new component goes.
• Port the token file before porting any component; components without tokens re-create the ad-hoc styling problem.

Machine-readable record: ui-component-system in mcp/patterns.registry.json.