Theming

Token layers

Primitive colors live in the tokens package under brand, accent, neutral, and semantic groups. Applications consume semantic variables such as background, card, and primary instead of raw brand values.

The pipeline in this repository is explicit: registry metadata points to semantic tokens, the tokens package maps them to CSS variables, the UI package consumes those variables, and the docs app demonstrates the same system without a separate theme fork.

--background
--foreground
--card
--card-foreground
--muted
--muted-foreground
--border
--input
--primary
--primary-foreground
--secondary
--secondary-foreground
--accent
--accent-foreground
--ring
--destructive
--destructive-foreground

Why semantic mapping matters

Components can remain stable while visual direction changes, because the UI package refers to semantic roles rather than to individual brand colors. That lowers migration cost when the design language evolves.

• No hardcoded color values in the docs app or component package
• Light theme is fully implemented
• Dark theme hook points are present through data-theme selectors

Tailwind integration

The docs app maps semantic CSS variables into Tailwind theme keys so component classes stay readable and designers can reason about usage at a glance.

colors: {
  background: 'var(--background)',
  foreground: 'var(--foreground)',
  primary: 'var(--primary)',
  'primary-foreground': 'var(--primary-foreground)'
}

End-to-end pipeline

The docs are not a disconnected marketing surface. Each component page carries typed metadata that mirrors the registry, so tokens and dependencies shown in docs stay aligned with the component ecosystem contract.

registry -> docs meta -> design tokens -> CSS variables -> @nim-ui/ui -> docs and consumer apps