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

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

Category: UI Components & Design System · Tier: deep · Maturity: proven (verified 2026-08-20 @ 1a130d67) · 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.

Avoid when

• A non-Svelte frontend — every primitive wraps Bits UI, which is Svelte-native and the layer system depends on it
• A project committed to a Tailwind theme config or another styled kit — token CSS variables are core to theming and hard to reverse

Alternatives

• Radix or Headless UI primitives under the same CVA + token layering — prefer when the frontend is React or Vue rather than Svelte
• Tailwind with its theme config instead of UnoCSS + CSS-variable tokens — prefer when a larger ecosystem and documentation matter more than build speed and the app needs no runtime theming or rebuild-free dark mode

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/desk/dock.state.svelte.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 pattern-library/registry.json.