Documentation / Design & UI

Design system

The design system connects editable tokens, accessible controls, reusable compositions, and shared interaction behavior. It is one part of the same foundation as identity, application data, account services, and deployment.

Follow a component through the system

Palette scales → semantic roles → Base UI controls → shared forms → product interfaces.

A concrete example is primary palette → --primary → Button → PendingButton → SaveForm → ProfileSettings. Changing the semantic primary treatment reaches ordinary actions through those shared implementations. The profile form keeps its existing service operation and authorization boundary.

Two layers connect across that chain:

• Shared runtime: motion tokens, animated values, action-state handling, and shared styles.
• Canonical catalog: the real implementations, working previews, usage guidance, and source paths.

Start with the palette and semantic roles

The global stylesheet owns three independently editable scales: primary, accent, and neutral, each with eleven shades. Light and dark mappings assign those values to roles such as background, foreground, primary, border, and ring.

shadcn's semantic accent is a neutral hover/selection surface. Numbered classes such as accent-500 refer to the separate brand accent scale. React Bits --rb-accent follows semantic primary for ordinary controls.

The brand page reads these same values. ThemeToggle changes the real light/dark theme; it does not edit source or save a new palette. Use the UI colors skill when applying your product's colors.

Compose the existing controls

Use the Base UI/shadcn wrappers in src/components/ui. Their variants, semantics, keyboard behavior, and focus handling are shared by forms, account controls, and app compositions. Use the supported render composition prop where the wrapper permits it.

Geist typography, Pixelarticons, radius tokens, and Tailwind utilities complete the visual foundation. Spacing and layouts are authored in the components with Tailwind classes; the kit does not provide a separate universal spacing editor.

Start at the component catalog. Search for the behavior you need before adding another implementation.

Keep interaction behavior connected

Incoming data uses ContentSkeleton; a user action uses PendingButton or PendingIndicator. useAsyncAction prevents duplicate work and tracks the actual result. Ready content stays visible while an update runs.

Page entrances and changing content use the registered Motion primitives. AnimatedNumber and Progress animate visible values while preserving real accessible targets. The runtime owns timing and easing so these pieces move together.

Explore the motion dashboard and loading and motion guide. Its simulated data and operations belong to the gallery; application code uses actual service callbacks.

Make previews part of the component

A reusable component has its implementation, catalog entry, example loader, and working preview in the same change. Connected components expose a view receiving resolved data and callbacks. Production and previews render that same view.

The source tab reads the registered implementation at build time. bun run check:components enforces coverage and import boundaries. See components for the complete workflow.

Know where to make a change

Runtime upgrades update shared behavior. They do not overwrite your palette, visual components, routes, or database schema. Follow the separate paths in updating.