Skip to content
Nana UI

Guides

Theming

Customize Nana UI with design tokens, CSS custom properties, and dark mode.

View .md Download

Components are headless by default; this page is about the Nana theme, the ready-made design you switch on with import "@nana-tec/ui-components/theme". It is styled from a shared set of design tokens exposed as CSS custom properties (all prefixed --nana-). Override them at any scope — the :root, a subtree, or a single element — to re-theme without touching component internals.

Without the theme, the tokens have no effect: style components directly through their parts and state attributes, as Getting Started shows.

In Svelte and React the look is Tailwind classes, and nana-theme.css maps Tailwind’s colours, radii and type onto the same tokens — so everything below applies there too.

Import the token base once in your app’s global stylesheet:

@import "@nana-tec/ui-themes/base";

This defines the full token set: color scales, surface semantics, spacing, radii, typography, shadows, z-index, and transitions.

TokenRole
--nana-surface-bgComponent background
--nana-surface-textPrimary text color
--nana-surface-text-mutedSecondary text color
--nana-surface-borderBorders and separators
--nana-surface-border-subtleFaint dividers, such as between table rows
--nana-surface-subtleSubtle fills / hover backgrounds
--nana-color-primary-600Brand accent
--nana-radius-mdDefault corner radius
--nana-focus-ringFocus outline

To use your own brand colour, set --nana-brand and import the brand stylesheet after the base theme. It builds the whole primary scale, 50 to 950, from that one value, so buttons, focus rings, badges, selection and the dark-mode accent all follow:

@import "@nana-tec/ui-themes/base";
@import "@nana-tec/ui-themes/brand";
:root {
--nana-brand: #2563eb;
}

Text on a solid brand fill is white. For a light brand, such as a yellow, set --nana-brand-contrast to a dark colour as well.

To brand one part of a page differently, give it the data-nana-brand attribute and its own value:

<section data-nana-brand style="--nana-brand: #16a34a">…</section>

For full control over each step, set the --nana-color-primary-* tokens yourself instead, as in Writing a theme.

Scope overrides to re-theme a subtree:

.checkout {
--nana-color-primary-600: #2563eb;
--nana-radius-md: 9999px;
}

Many components also expose component-scoped variables and ::part() hooks for finer control — see each component’s CSS Custom Properties section.

<nana-button style="--nana-button-bg:#2563eb">Buy now</nana-button>

A theme is a stylesheet that sets token values, scoped to an attribute on the root so it can be switched at runtime the way dark mode is. Import it after the base and every component follows:

:root[data-theme="ocean"] {
--nana-color-primary-50: oklch(0.97 0.02 220);
--nana-color-primary-100: oklch(0.93 0.04 220);
--nana-color-primary-200: oklch(0.87 0.07 220);
--nana-color-primary-400: oklch(0.7 0.13 225);
--nana-color-primary-600: oklch(0.52 0.14 235);
--nana-color-primary-700: oklch(0.45 0.12 238);
--nana-surface-bg: oklch(0.985 0.006 220);
--nana-surface-subtle: oklch(0.965 0.012 220);
--nana-surface-border: oklch(0.88 0.025 220);
--nana-radius-sm: 0.5rem;
--nana-radius-md: 0.875rem;
--nana-radius-lg: 1.25rem;
}

The theme applies only while the root carries its name. For a fixed theme, set the attribute in the page shell — src/app.html in SvelteKit, index.html in Vite:

<html lang="en" data-theme="ocean">

To switch at runtime, set it from script instead:

document.documentElement.dataset.theme = "ocean";

Dark mode uses the same attribute, so a page is either ocean or dark, not both. A theme that needs a dark version defines it under a name of its own, such as :root[data-theme="ocean-dark"], and the app switches between the two.

Override the scales — the design tokens — to move a colour everywhere it is used, and the semantic variables below to change what a role points at. A theme only has to set what it changes; the base supplies the rest.

To replace the base entirely rather than build on it, import @nana-tec/ui-tokens/css for the scales and define every variable in this table yourself, once for light and once under [data-theme="dark"]:

VariableRole
--nana-surface-bgPage and component background
--nana-surface-subtleHover fills, table headers
--nana-surface-mutedTracks, wells, disabled fills
--nana-surface-raisedToasts, popovers and menus above the page
--nana-shadow-raisedThe shadow under raised surfaces
--nana-surface-borderBorders and separators
--nana-surface-border-subtleFaint dividers, such as between table rows
--nana-surface-textPrimary text
--nana-surface-text-mutedSecondary text
--nana-surface-text-subtlePlaceholders and hints
--nana-surface-accentThe brand fill: primary buttons, selection, progress
--nana-surface-accent-contrastText and icons on the accent fill
--nana-surface-accent-softA quiet accent fill
--nana-surface-accent-lineAn accent border
--nana-focus-ringThe focus outline, as a box-shadow
--nana-tone-alert
--nana-tone-alert-strong
--nana-tone-alert-soft
Work under way
--nana-tone-change
--nana-tone-change-strong
--nana-tone-change-soft
Something about to change
--nana-badge-neutral-bg
--nana-badge-neutral-fg
--nana-badge-neutral-line
Neutral badge fill, text and edge
--nana-badge-primary-bg
--nana-badge-primary-fg
--nana-badge-primary-line
Primary badge
--nana-badge-success-bg
--nana-badge-success-fg
--nana-badge-success-line
Success badge
--nana-badge-warning-bg
--nana-badge-warning-fg
--nana-badge-warning-line
Warning badge
--nana-badge-danger-bg
--nana-badge-danger-fg
--nana-badge-danger-line
Danger badge
--nana-badge-info-bg
--nana-badge-info-fg
--nana-badge-info-line
Info badge
--nana-tab-thumb-bg
--nana-tab-thumb-line
The sliding thumb of segmented tabs
--nana-chart-1
--nana-chart-2
--nana-chart-3
--nana-chart-4
--nana-chart-5
Chart series, in order; each is checked for colour-blind separation on the theme’s surface

The web components style themselves in a shadow root, which your stylesheet does not cross. A rule like nana-input .helper { font-size: 1rem } will never match. There are three ways in, and it is worth knowing which one a given change needs.

Custom properties pass straight through. They inherit across the shadow boundary, so setting one on the element reaches the styles inside, scoped to that instance:

nana-breadcrumb { --nana-surface-border: #cbd5e1; }

This is the first thing to reach for. The limit is that it only changes values the component reads — if there is no variable for the thing you want to move, a variable will not move it.

::part() gives you real CSS on the elements a component exposes. Each component’s reference page lists its parts, and a rule from your stylesheet beats the component’s own rule for that property:

nana-input::part(input) { font-variant-numeric: tabular-nums; }

Not every inner element is a part. Where none is exposed, the remaining options are a custom property or editing the component — which you own, since the CLI copies the source into your project.

Slotted content is yours already. Anything you pass into a slot stays in your document, so your ordinary selectors apply to it with no special syntax.

::part() reaches one shadow root deep. When a component renders another Nana component inside itself, the inner parts are only reachable if the outer one forwards them with exportparts, which shows up on the outer component’s page as a forwarded part:

nana-bulk-progress::part(fill) { background: #16a34a; }

If you are composing Nana components inside your own component and want callers to reach through, forward the parts the same way:

<nana-progress-bar exportparts="track, fill"></nana-progress-bar>

Variable names are per component and not always derived from the tag — the progress bar reads --nana-progress-color, and the QR code reads --nana-qr-*. Check the component’s page rather than guessing.

Dark mode is driven by a single attribute on the document root:

document.documentElement.setAttribute("data-theme", "dark");

The token base ships :root[data-theme="dark"] overrides, so every component switches together. In these docs, Starlight’s theme toggle sets the same attribute, which is why the live examples follow the site theme.