Guides
Theming
Customize Nana UI with design tokens, CSS custom properties, and dark mode.
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.
Token foundation
Section titled “Token foundation”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.
Common tokens
Section titled “Common tokens”| Token | Role |
|---|---|
--nana-surface-bg | Component background |
--nana-surface-text | Primary text color |
--nana-surface-text-muted | Secondary text color |
--nana-surface-border | Borders and separators |
--nana-surface-border-subtle | Faint dividers, such as between table rows |
--nana-surface-subtle | Subtle fills / hover backgrounds |
--nana-color-primary-600 | Brand accent |
--nana-radius-md | Default corner radius |
--nana-focus-ring | Focus outline |
Brand colour
Section titled “Brand colour”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.
Overriding tokens
Section titled “Overriding tokens”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>Writing a theme
Section titled “Writing a theme”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"]:
| Variable | Role |
|---|---|
--nana-surface-bg | Page and component background |
--nana-surface-subtle | Hover fills, table headers |
--nana-surface-muted | Tracks, wells, disabled fills |
--nana-surface-raised | Toasts, popovers and menus above the page |
--nana-shadow-raised | The shadow under raised surfaces |
--nana-surface-border | Borders and separators |
--nana-surface-border-subtle | Faint dividers, such as between table rows |
--nana-surface-text | Primary text |
--nana-surface-text-muted | Secondary text |
--nana-surface-text-subtle | Placeholders and hints |
--nana-surface-accent | The brand fill: primary buttons, selection, progress |
--nana-surface-accent-contrast | Text and icons on the accent fill |
--nana-surface-accent-soft | A quiet accent fill |
--nana-surface-accent-line | An accent border |
--nana-focus-ring | The 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 |
Styling inside a web component
Section titled “Styling inside a web component”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.
Parts do not nest on their own
Section titled “Parts do not nest on their own”::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
Section titled “Dark mode”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.