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
--surface-raised
--surface-subtle
--card
--card-foreground
--muted
--muted-foreground
--foreground-subtle
--border
--border-strong
--input
--primary
--primary-hover
--primary-active
--primary-foreground
--secondary
--secondary-foreground
--accent
--accent-foreground
--ring
--destructive
--destructive-foreground

Foundation scales

The tokens package 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.

• Shared semantic color roles across docs and components
• A light theme is provided; external consumer validation is still in progress
• A dark selector exists in CSS; supported dark mode is not yet validated

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.

primitive tokens -> semantic CSS variables -> @nimjs/ui -> package and copy consumers; registry metadata -> docs and CLI