# Token Architecture

## Purpose

How decisions are encoded as design tokens.

## Decisions

### Colour token names

Colour tokens are named **colour and step**, such as `violet-600` or `teal-400` (see [Colour Palette](../foundations/colour-palette.md)). Other naming (spacing `s-1` to `s-8`, radius `r-1` to `r-4`, control heights) is defined with each foundation.

### Token architecture

- **Source of truth:** a single **master CSS file**, `ndl.css` at the repository root, that projects import. These Markdown pages document it.
- **Two tiers.** Palette tokens are the raw values (`--ndl-violet-500`). Role tokens point at them and are what components use (`--ndl-color-primary`).
- **Naming:** category first, for example `--ndl-color-bg`, `--ndl-color-surface`, `--ndl-color-primary`, `--ndl-space-4`, `--ndl-radius-2`. Palette tokens keep colour-step names.
- **Prefix:** `--ndl-` everywhere.
- **Remapping:** a role can be pointed at another palette value in one line, for example `--ndl-color-primary: var(--ndl-red-pink-500);`. Because hover and pressed are their own role tokens, a full remap also needs their two lines (or a single switch that sets all three). This also supports re-skins.
- **States are tokens:** each role has hover, pressed and focus tokens taken from the palette steps (for example `--ndl-color-primary-hover` is `violet-600`).
- **Also tokens:** font sizes and line heights, the three durations and two easing curves, the shadow values and the focus ring.
- **Light and dark:** one set of variable names, with values switched under a theme attribute on the root element (`[data-theme="dark"]` or `"light"`). The first visit follows the system setting, falling back to dark.
- **Delivery:** projects link or `@import` the CSS file by URL. Obsidian (a local snippet) keeps a copy instead, since a snippet cannot depend on a URL.
- **Fonts are bundled inside the master CSS** (the embedded fonts are about 150 KB, so the file is large).