Theming

How it works

The theme is one file, styles/base.css, built in two layers:

• Values. --nui-* variables hold the actual colors, radius, shadows, and sizes. Light values sit in the :root block. The .dark block overrides only the values that change in dark mode.
• Tokens. An @theme inline block turns each value into a Tailwind token. --nui-card becomes card, which you use as bg-card, border-card, and so on.

Components use tokens only, never raw colors. Change a value and every component that uses it follows, in light and dark.

Tokens are named for their job, not their color. muted-foreground means secondary text, whatever color you give it.

Most grays point at one scale, --nui-neutral-50 to --nui-neutral-950. Shift that scale to make every gray warmer or cooler at once.

Colors

Naming

Color tokens come in families that share a base name:

When you change a fill, check that its -foreground still reads well on it.

Surfaces

Controls

Actions

Status

A destructive button uses the solid fill with its foreground; an alert uses the soft tint with its soft foreground.

Palette

Ten more colors for content that isn't a status. The full calendar uses them for events, and blocks use them for tags, categories, and avatars.

The solid fill's variable ends in -solid, for example --nui-palette-blue-solid.

Charts

Chart series take these colors in order. By default they reuse primary and the palette, so charts match the rest of the theme.

Shape and type

Radius

These point at a base scale, --nui-radius-xs to --nui-radius-2xl.

Shadows

Dark mode has its own shadows, which add a faint light edge so surfaces stay visible on dark backgrounds.

Sizes

Use them with h-, min-h-, or w-, for example h-control-md.

Stacking

If your app's own layers need to sit above or below these, change the matching --nui-z-* values.

Font

font-sans is the interface font: Inter, falling back to system fonts. font-mono is used for code. To use another font, change --font-sans.

Dark mode

Use an explicit dark or light class on <html>. If your appearance controller updates the root directly, keep both classes and the attribute aligned with the same mode value passed to your component provider:

const mode = isDark ? "dark" : "light";
const root = document.documentElement;
root.classList.toggle("dark", mode === "dark");
root.classList.toggle("light", mode === "light");
root.dataset.theme = mode;

The .dark class activates Tailwind dark: utilities as well as the dark tokens. A data-theme attribute alone selects tokens and is not a complete appearance switch. With the exported Theme Workbench wrapper, change its mode prop instead; it synchronizes the root signals as described below.

The .dark block lists only what changes. Surfaces, borders, controls, and the soft tints get dark values; primary and the solid status colors stay the same in both modes.

Change a value

Edit the variables in styles/base.css. For example, to change the primary color:

:root,
.light,
[data-theme='light'] {
    --nui-primary: #0f766e;
    --nui-primary-foreground: #ffffff;
    --nui-primary-hover: #14897f;
    --nui-primary-active: #0b5c55;
}

--nui-primary isn't in the .dark block, so this changes both modes. To give dark mode its own value, add the same variable to the .dark block.

Change a fill and its -foreground, -hover, and -active together, so text stays readable and states stay distinct.

Theme workbench

The theme workbench lets you build a theme visually instead of editing values by hand.

1. Pick a starting style: Default, Soft Flat, Neomorphism, Neobrutalism, Glass, or Editorial.
2. Adjust colors, font, density, and control sizes. Check them against real components in light and dark.
3. Open Code to preview or download nateui-theme.zip. It contains base.css, config-provider.tsx and DESIGN.md from the same effective settings and selected Light/Dark mode.
4. Replace your styles/base.css with the downloaded base.css.
5. Save config-provider.tsx in your project and wrap your app with it:

import { ThemeConfigProvider } from "@/components/theme-config-provider";
 
<ThemeConfigProvider>
  <App />
</ThemeConfigProvider>

The file carries the defaults and extra class names your chosen style depends on, so styles such as Neobrutalism look right beyond their colors.

Use the exported provider once at the application root. Its default mode is the selected appearance; on client mount and mode changes it synchronizes the root .light/.dark class and data-theme attribute before paint. For server-rendered pages, initialize the <html> class to that same mode before first paint, then hydrate with the matching provider mode. Pass a new mode prop to switch appearance at runtime.

Both palettes remain in base.css. With no root signal, CSS supplies the selected mode's token fallback; complete appearance also requires the provider's root-class initialization or matching server markup. The .dark class activates Tailwind dark: utilities. Setting data-theme alone selects tokens and is not a complete appearance switch. Keep an existing appearance controller as the mode source when adopting this wrapper, and avoid competing or nested root-mode owners. Font files are not included; retain your application's font loading and adjust import aliases to your project.

DESIGN.md records the selected preset and guide versions, effective configuration and composition guidance. It replaces affected baseline claims when token, font, default or slot customizations change their assumptions. Exact values stay in the paired CSS and provider files. This selected direction differs from the provisional Default document seeded by skill installation.

Review and deliberately merge or adopt the exported document. Preserve an existing project-owned DESIGN.md until you choose to revise it, and record your actual implementation paths after adoption. Keep its relative links beside the paired files or update them when moving the document. Downloading a guide applies no styles and does not replace project files.

Component defaults

ConfigProvider sets defaults for every component below it, so you don't repeat the same props across your app.

"use client";
 
import type { ReactNode } from "react";
import { ConfigProvider, defaultConfig } from "@/components/ui/config-provider";
 
export function Providers({ children }: { children: ReactNode }) {
  return (
    <ConfigProvider
      value={{
        ...defaultConfig,
        componentDefaults: {
          button: { size: "sm", variant: "solid" },
          input: { size: "sm" },
        },
        classNames: {
          button: { root: "tracking-tight" },
        },
      }}
    >
      {children}
    </ConfigProvider>
  );
}

• componentDefaults sets default props per component.
• classNames adds classes to named parts of a component everywhere it appears.

A prop set directly on a component always wins over the default.