Theming

Token layers

Primitive tokens live in the tokens package across color, typography, spacing, radius, and motion 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

Foundation scales

The theme exports reusable typography, spacing, and motion scales so component work does not invent one-off values as the library grows.

Those scales are also exposed as CSS variables, which lets Tailwind configuration, package CSS, and consumer apps reference the same contract.

--font-body
--font-display
--font-mono
--space-1
--space-2
--space-3
--duration-fast
--ease-standard

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 -> @nimjs/ui -> docs and consumer apps