# Theming

> Source: https://design.nanatec.co.ke/guides/theming/
> Customize Nana UI with design tokens, CSS custom properties, and dark mode.

Every component 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.

## Token foundation

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

```css
@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

| 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-subtle` | Subtle fills / hover backgrounds |
| `--nana-color-primary-600` | Brand accent |
| `--nana-radius-md` | Default corner radius |
| `--nana-focus-ring` | Focus outline |

## Overriding tokens

Scope overrides to re-theme a subtree:

```css
.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.

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

## Dark mode

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

```js
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.