@uncinq/design-tokens 1.7.3 → 1.8.1

package/docs/dtcg.md

@@ -0,0 +1,232 @@
+---
+isIndex: false
+title: DTCG format
+description: The Design Tokens Community Group JSON format, its keys, types and naming conventions as used in this package.
+weight: 6
+icon: braces
+---
+
+
+The [W3C Design Token Community Group (DTCG)](https://www.w3.org/community/design-tokens/) defines a standard interchange format for design tokens, so they can travel between tools (Figma, code, documentation) without loss of meaning.
+
+`@uncinq/design-tokens` uses DTCG JSON as its source format. [Style Dictionary v5](https://styledictionary.com/) transforms those JSON files into CSS custom properties — see [STYLE-DICTIONARY.md](STYLE-DICTIONARY.md) for the build pipeline. The DTCG spec informs the architecture (primitive → semantic → component, naming conventions, token types).
+
+---
+
+## The DTCG format
+
+The [DTCG spec](https://tr.designtokens.org/format/) defines tokens as JSON objects with reserved `$`-prefixed keys:
+
+```json
+{
+  "color": {
+    "brand": {
+      "$value": "oklch(0.530 0.195 22.0)",
+      "$type": "color",
+      "$description": "Primary brand color — used for CTAs and highlights."
+    }
+  }
+}
+```
+
+> **Note on OKLCH:** The DTCG `color` type accepts any valid CSS color value, including `oklch(…)`. `@uncinq/design-tokens` uses OKLCH throughout — perceptually uniform, wide-gamut, and natively supported in modern browsers.
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `$value` | ✅ | The token's value |
+| `$type` | recommended | The token type (see below) |
+| `$description` | optional | Human-readable documentation |
+| `$extensions` | optional | Vendor-specific metadata (e.g. Figma) |
+
+---
+
+## DTCG token types
+
+### Scalar types
+
+| Type | Example value | CSS usage |
+| --- | --- | --- |
+| `color` | `oklch(0.530 0.195 22.0)` | `color`, `background-color` |
+| `dimension` | `1rem`, `4px` | `width`, `padding`, `font-size` |
+| `fontFamily` | `"system-ui, sans-serif"` | `font-family` |
+| `fontWeight` | `700` | `font-weight` |
+| `duration` | `300ms` | `transition-duration` |
+| `cubicBezier` | `[0.165, 0.84, 0.44, 1]` | `animation-timing-function` |
+| `number` | `1.5` | `line-height`, `opacity` |
+| `string` | `"uppercase"` | free-form text values |
+| `strokeStyle` | `"solid"`, `"dashed"` | `border-style` |
+
+### Composite types
+
+| Type | Shape | CSS usage |
+| --- | --- | --- |
+| `shadow` | `{offsetX, offsetY, blur, spread, color}` | `box-shadow` |
+| `border` | `{width, style, color}` | `border` shorthand |
+| `transition` | `{duration, delay, timingFunction}` | `transition` shorthand |
+| `typography` | `{fontFamily, fontSize, fontWeight, letterSpacing, lineHeight}` | typography rules |
+| `gradient` | `{gradientType, stops[]}` | `background: linear-gradient(…)` |
+
+→ Full type list: [tr.designtokens.org/format/#types](https://tr.designtokens.org/format/#types)
+
+> **Note on `clamp()` values:** DTCG has no native `fluid` type. Fluid tokens (`--font-size-fluid-sm`, `--font-size-fluid-md`, `--spacing-fluid-*`) use `$type: "dimension"` as the closest match — a documented gap in the spec.
+
+---
+
+## Naming conventions
+
+### CSS compound properties → camelCase
+
+CSS property names that are two words (kebab-case in CSS) are written as a single **camelCase key** — not as a nested group. The `pathToKebab` transform converts them back to kebab-case for the CSS output, so the result is identical either way.
+
+| JSON key | CSS custom property |
+| --- | --- |
+| `"fontFamily"` | `--btn-font-family` |
+| `"fontSize"` | `--btn-font-size` |
+| `"fontStyle"` | `--btn-font-style` |
+| `"fontWeight"` | `--btn-font-weight` |
+| `"lineHeight"` | `--btn-line-height` |
+| `"maxHeight"` | `--btn-max-height` |
+| `"maxWidth"` | `--btn-max-width` |
+| `"textAlign"` | `--btn-text-align` |
+| `"textDecoration"` | `--btn-text-decoration` |
+| `"textTransform"` | `--btn-text-transform` |
+
+```json
+// ✅ correct
+"btn": {
+  "fontSize": { "$value": "{fontSize.sm}", "$type": "dimension" },
+  "fontWeight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" }
+}
+
+// ❌ wrong
+"btn": {
+  "font": {
+    "size": { "$value": "{fontSize.sm}", "$type": "dimension" },
+    "weight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" }
+  }
+}
+```
+
+**Exception — semantic namespaces:** `border`, `color`, `padding`, `margin`, `shadow` used to group multiple sub-properties stay nested, because the group key itself is not a CSS property compound word.
+
+```json
+// ✅ border as a namespace grouping multiple properties
+"border": {
+  "radius": { "$value": "{radius.control}", "$type": "dimension" },
+  "width":  { "$value": "{border.width.sm}", "$type": "dimension" }
+}
+
+// ✅ color as a semantic grouping
+"color": {
+  "background": { "$value": "{color.background.default}", "$type": "color" },
+  "text":       { "$value": "{color.text.default}", "$type": "color" }
+}
+```
+
+### Logical properties → sub-keys of `padding` / `margin`
+
+Sub-axes of `padding` and `margin` use **CSS logical property names** as sub-keys — not physical directions (`x`, `y`, `top`, `bottom`, `left`, `right`).
+
+| Sub-key | CSS logical property | Physical equivalent |
+| --- | --- | --- |
+| `"inline"` | `padding-inline` / `margin-inline` | left + right |
+| `"block"` | `padding-block` / `margin-block` | top + bottom |
+| `"inlineStart"` | `padding-inline-start` / `margin-inline-start` | left (LTR) |
+| `"inlineEnd"` | `padding-inline-end` / `margin-inline-end` | right (LTR) |
+| `"blockStart"` | `padding-block-start` / `margin-block-start` | top |
+| `"blockEnd"` | `padding-block-end` / `margin-block-end` | bottom |
+
+```json
+// ✅ correct
+"padding": {
+  "inline": { "$value": "{spacing.sm}", "$type": "dimension" },
+  "block":  { "$value": "{spacing.xs}", "$type": "dimension" }
+}
+
+// ❌ wrong
+"padding": {
+  "x": { "$value": "{spacing.sm}", "$type": "dimension" },
+  "y": { "$value": "{spacing.xs}", "$type": "dimension" }
+}
+```
+
+**Exception — CSS `top`/`bottom`/`left`/`right` as positioning values** (not margin/padding sub-keys) keep their physical names, since they map to CSS position properties, not logical shorthands.
+
+```json
+// ✅ positioning — physical names are correct here
+"sticky": {
+  "top": { "$value": "4rem", "$type": "dimension" }
+}
+```
+
+### States → nested sub-keys
+
+Interactive states (`default`, `hover`, `active`, `disabled`…) are expressed as **nested keys** under the property they modify. The `default` key is automatically stripped by the build transform.
+
+```json
+"color": {
+  "background": {
+    "default": { "$value": "{color.brand.default}", "$type": "color" },
+    "hover":   { "$value": "{color.brand.hover}",   "$type": "color" }
+  }
+}
+```
+
+```css
+/* output */
+--btn-color-background: var(--color-brand);
+--btn-color-background-hover: var(--color-brand-hover);
+```
+
+States and camelCase properties compose naturally:
+
+```json
+"color": {
+  "textDecoration": {
+    "default": { "$value": "transparent", "$type": "color" },
+    "hover":   { "$value": "{color.link.default}", "$type": "color" }
+  }
+}
+```
+
+```css
+--btn-color-text-decoration: transparent;
+--btn-color-text-decoration-hover: var(--color-link);
+```
+
+---
+
+## References (aliases)
+
+Tokens can reference other tokens using `{dotted.path}` syntax:
+
+```json
+{
+  "color": {
+    "link": {
+      "default": {
+        "$value": "{color.brand.default}",
+        "$type": "color"
+      }
+    }
+  }
+}
+```
+
+In CSS, this maps to `var()`:
+
+```css
+--color-link: var(--color-brand);
+```
+
+This is the key mechanism behind the **primitive → semantic → component** hierarchy.
+
+→ [tr.designtokens.org/format/#alias](https://tr.designtokens.org/format/#alias)
+
+---
+
+## References
+
+- [DTCG specification](https://tr.designtokens.org/format/) — W3C Community Group draft
+- [DTCG GitHub](https://github.com/design-tokens/community-group) — issues, discussion
+- [Style Dictionary v5](https://styledictionary.com/) — token build pipeline, see [STYLE-DICTIONARY.md](STYLE-DICTIONARY.md)

package/docs/naming.md

@@ -0,0 +1,128 @@
+---
+isIndex: false
+title: Naming
+description: The naming grammar for semantic and component tokens, the rules that keep it consistent, and the scales in use.
+weight: 1
+icon: tag
+---
+
+A token name is an API. Once a project references `--color-text-muted`, renaming it is a breaking change, so the grammar below is worth following closely.
+
+## Semantic tokens
+
+```
+--{category}-{subcategory?}-{variant?}-{state?}
+```
+
+| Pattern | Example |
+| --- | --- |
+| `--{category}` | `--color` |
+| `--{category}-{subcategory}` | `--color-text` |
+| `--{category}-{subcategory}-{variant}` | `--color-text-muted` |
+| `--{category}-{subcategory}-{state}` | `--color-text-disabled` |
+
+## Component tokens
+
+```
+--{component}-{property}-{sub-property?}-{state?}
+```
+
+The property mirrors the CSS property name, so the token reads the same way as the declaration it controls. Colors are the exception: `color` leads and the role follows, for the reason given in the rules below.
+
+| Pattern | Example |
+| --- | --- |
+| `--{component}` | `--btn` |
+| `--{component}-{property}` | `--btn-padding-inline` |
+| `--{component}-{property}-{sub-property}` | `--btn-color-text-decoration` |
+| `--{component}-{property}-{state}` | `--btn-color-background-hover` |
+
+## Rules
+
+**Lowercase kebab-case**, always.
+
+**No component names in primitive or semantic tokens.** `--button-*` belongs in [@uncinq/component-tokens](https://github.com/uncinq/component-tokens), not here. A semantic token that names a component has stopped being semantic.
+
+**Semantic tokens are named by intent.** They usually reference a primitive through `var()`, but they may carry a raw value when the value itself is the design decision, such as `--z-index-modal: 400` or `--radius-pill: 9999px`.
+
+**`color-[role]` for every color token.** `color` is the category prefix and the UI role follows: `color-background`, `color-border`, `color-text`, `color-accent`, `color-placeholder`. This groups all color tokens alphabetically under `color-*`, and it makes the component token mirror the global one, `--color-background` becoming `--btn-color-background`. `background` is never abbreviated, so `color-background` and never `color-bg`.
+
+| Token | Role | CSS property it drives |
+| --- | --- | --- |
+| `--btn-color-background` | background | `background-color` |
+| `--btn-color-border` | border | `border-color` |
+| `--btn-color-text` | text | `color` |
+| `--btn-color-text-decoration` | text-decoration | `text-decoration-color` |
+| `--form-color-accent` | accent | `color` |
+| `--input-color-placeholder` | placeholder | `color` |
+
+**States go last**: `-hover`, `-focus`, `-active`, `-disabled`, `-checked`.
+
+**Alphabetical order within a file**, grouped with a comment once a file has many entries.
+
+```css
+/* Brand */
+--color-brand:       var(--color-sienna-600);
+--color-brand-hover: var(--color-sienna-700);
+
+/* Text */
+--color-text:        var(--color-gray-900);
+--color-text-muted:  var(--color-gray-500);
+```
+
+## The `default` convention
+
+In the JSON source, a state lives in a nested key and `default` is the unstated one. The build strips it from the generated name, so `color.brand.default` becomes `--color-brand` while `color.brand.hover` becomes `--color-brand-hover`.
+
+```json
+"brand": {
+  "default": { "$value": "{color.sienna.600}", "$type": "color" },
+  "hover":   { "$value": "{color.sienna.700}", "$type": "color" }
+}
+```
+
+This is what lets `--color-brand` and `--color-brand-hover` sit in the same group without one of them being named `--color-brand-default`. See [DTCG format](../dtcg/) for the full set of authoring conventions.
+
+## Scales
+
+| Use case | Scale | Example |
+| --- | --- | --- |
+| Color palettes | Numeric, 50 to 950 | `--color-gray-500` |
+| Heading levels | Zero-padded, 01 to 06 | `--font-size-heading-01` |
+| Layout and spacing | T-shirt, `2xs xs sm md lg xl 2xl` | `--spacing-md` |
+| Radius, shadow, size | T-shirt | `--radius-sm` |
+| Purposeful aliases | Named | `--radius-control`, `--radius-pill` |
+
+The zero-padding on heading levels is there so that `01` through `06` sort correctly as text, which matters because the generated CSS is ordered alphabetically.
+
+## Category reference
+
+| Category | Covers | Example |
+| --- | --- | --- |
+| `color` | All color values | `--color-brand`, `--color-text-on-dark` |
+| `font-family` | Typefaces | `--font-family-heading` |
+| `font-size` | Text sizes | `--font-size-sm`, `--font-size-heading-01` |
+| `font-size-fluid` | Responsive fluid type scale | `--font-size-fluid-xl` |
+| `font-weight` | Weight values | `--font-weight-bold` |
+| `line-height` | Line heights | `--line-height-heading` |
+| `letter-spacing` | Tracking | `--letter-spacing-md` |
+| `text-decoration` | Decoration properties | `--text-decoration-offset` |
+| `spacing` | Margin and padding | `--spacing-md`, `--spacing-section` |
+| `spacing-fluid` | Responsive fluid spacing scale | `--spacing-fluid-lg` |
+| `size` | Width and height | `--size-16`, `--size-tablet` |
+| `max-width` | Readability caps | `--max-width-paragraph` |
+| `radius` | Border radius | `--radius-md`, `--radius-pill` |
+| `border` | Border style and width | `--border-width-sm` |
+| `shadow` | Box shadows | `--shadow-md` |
+| `blur` | Blur values | `--blur-md` |
+| `gradient` | Overlay gradients | `--gradient-darken-color-from` |
+| `opacity` | Opacity values | `--opacity-disabled` |
+| `duration` | Animation timing | `--duration-fast` |
+| `easing` | Timing functions | `--easing-out-expo` |
+| `transition` | Shorthand transitions | `--transition-normal` |
+| `ratio` | Aspect ratios | `--ratio-video` |
+| `focus` | Focus ring tokens | `--focus-outline-width` |
+| `grid` | Column counts, gaps, fractions | `--columns-tablet`, `--gap` |
+| `icon` | SVG icons as data URIs | `--icon-arrow` |
+| `z-index` | Stacking order | `--z-index-modal` |
+
+For the actual values behind each of these, see the [Reference](../reference/), which is generated from the JSON sources and cannot drift.

package/docs/reference.md

@@ -0,0 +1,129 @@
+---
+isIndex: false
+title: Reference
+description: Every token in the package, generated from the JSON sources so it can never drift from the shipped CSS.
+weight: 5
+icon: table
+---
+
+Every table below is generated at build time from `dist/tokens.json`, which Style Dictionary produces from the same JSON sources as the CSS. Nothing here is written by hand, so a token cannot appear in the reference without existing in the package, or change value without the page changing with it.
+
+Values are shown as they are emitted. A semantic token that references a primitive shows `var(--the-primitive)` rather than a flattened value, because that is literally what ships, and it is what makes an override of the primitive propagate.
+
+{{< alert-block state="info" >}}
+Reading this offline, from the repository or from `node_modules`? The tables below are rendered by the documentation site. The same data, in machine-readable form, sits in `dist/tokens.json`, and the final CSS is in `dist/css/`.
+{{< /alert-block >}}
+
+## Primitive
+
+Raw, context-free values. These answer "what is the value?" and carry no opinion about usage.
+
+### Color palette
+
+19 hues at 11 steps, plus black and white. See [Colors](../colors/) for the hue table and the step guide.
+
+{{< tokens pkg="design" file="primitive/color" >}}
+
+### Size scale
+
+{{< tokens pkg="design" file="primitive/size" >}}
+
+### Font primitives
+
+{{< tokens pkg="design" file="primitive/font" >}}
+
+### Shadow scale
+
+{{< tokens pkg="design" file="primitive/shadow" >}}
+
+### Blur scale
+
+{{< tokens pkg="design" file="primitive/blur" >}}
+
+## Semantic
+
+Named by purpose. These answer "what is this value for?" and are the layer a project should override.
+
+### Color roles
+
+{{< tokens pkg="design" file="semantic/color" >}}
+
+### Typography
+
+Font sizes (fixed and fluid), heading sizes, line heights, letter spacing, and the `--max-width-*` readability caps, which are authored as a `maxWidth` group in this file.
+
+{{< tokens pkg="design" file="semantic/typography" >}}
+
+### Spacing
+
+{{< tokens pkg="design" file="semantic/spacing" >}}
+
+### Size aliases
+
+{{< tokens pkg="design" file="semantic/size" >}}
+
+### Grid
+
+{{< tokens pkg="design" file="semantic/grid" >}}
+
+### Radius
+
+{{< tokens pkg="design" file="semantic/radius" >}}
+
+### Border
+
+{{< tokens pkg="design" file="semantic/border" >}}
+
+### Shadow aliases
+
+{{< tokens pkg="design" file="semantic/shadow" >}}
+
+### Blur aliases
+
+{{< tokens pkg="design" file="semantic/blur" >}}
+
+### Gradient
+
+{{< tokens pkg="design" file="semantic/gradient" >}}
+
+### Opacity
+
+{{< tokens pkg="design" file="semantic/opacity" >}}
+
+### Motion
+
+Durations, easing curves and the transition shorthands built from them.
+
+{{< tokens pkg="design" file="semantic/motion" >}}
+
+### Ratio
+
+{{< tokens pkg="design" file="semantic/ratio" >}}
+
+### Focus
+
+{{< tokens pkg="design" file="semantic/focus" >}}
+
+### Form
+
+The largest semantic file. It covers inputs, labels, checkboxes, radios, switches, selects and textareas, and is what [@uncinq/css-base](../../css-base/base/) reads to style native form controls.
+
+{{< tokens pkg="design" file="semantic/form" >}}
+
+### Icon
+
+SVG icons encoded as `url('data:image/svg+xml;utf8,...')`, usable as a `background-image` or a `mask-image`.
+
+{{< tokens pkg="design" file="semantic/icon" >}}
+
+### Z-index
+
+{{< tokens pkg="design" file="semantic/z-index" >}}
+
+## Themes
+
+### Dark
+
+The overlay applied under `prefers-color-scheme: dark`. See [Dark mode](../dark-mode/) for how the selector works and how to opt out.
+
+{{< tokens pkg="design" file="themes/dark" >}}

package/docs/style-dictionary.md

@@ -0,0 +1,182 @@
+---
+isIndex: false
+title: Style Dictionary
+description: How the JSON token sources are compiled into CSS custom properties, including the dark theme pass.
+weight: 7
+icon: gear
+---
+
+
+[Style Dictionary v5](https://styledictionary.com/) transforms the DTCG JSON token files into CSS custom properties.
+
+## Run the build
+
+```bash
+npm run build
+```
+
+Output is written to `dist/css/`. One CSS file is generated per JSON source file, preserving the same directory structure:
+
+```
+tokens/primitive/color.json   →   dist/css/primitive/color.css
+tokens/semantic/color.json    →   dist/css/semantic/color.css
+```
+
+---
+
+## Config — `style-dictionary.config.js`
+
+The config is a single ES module. It registers a custom name transform and a custom format, then maps every JSON file to a CSS output.
+
+### Name transform — `name/kebab/strip-default`
+
+Converts the token path to a kebab-case CSS custom property name, dropping any `default` segment:
+
+```
+color.background.default   →   --color-background
+color.text.muted           →   --color-text-muted
+```
+
+### Format — `css/layer-tokens`
+
+All tokens are wrapped in `@layer tokens { :root { … } }`. This is a low-priority layer in the Un Cinq stack (order: `reset, tokens, base, layouts, vendors, components`), so any project can override any token by importing after this package inside its own `@layer tokens` block.
+
+References are preserved as `var()` — tokens are **not** resolved to their final values:
+
+```css
+/* output */
+--color-text: var(--color-gray-900);   /* not oklch(0.208 0.006 264.542) */
+```
+
+This is done by reading `token.original.$value` and replacing every `{path.to.token}` reference with `var(--path-to-token)`. References embedded in a string value are also handled:
+
+```json
+{ "$value": "{size.8} {size.12}" }
+```
+
+```css
+--file-button-padding: var(--size-8) var(--size-12);
+```
+
+### Composite tokens
+
+Tokens whose `$value` is an object or an array of objects (e.g. `shadow`) are serialized as a space-separated CSS value. References inside the composite are converted to `var()`.
+
+**Property order matters** — list properties in the order CSS expects them. For `box-shadow`:
+
+```json
+{
+  "shadow": {
+    "sm": {
+      "$type": "shadow",
+      "$value": [
+        {
+          "offsetX": "0",
+          "offsetY": "1px",
+          "blur": "2px",
+          "spread": "0",
+          "color": "{color.shadow.light}",
+          "inset": false
+        }
+      ]
+    }
+  }
+}
+```
+
+```css
+--shadow-sm: 0 1px 2px 0 var(--color-shadow-light);
+```
+
+`inset` is always treated as a boolean prefix (`inset` or nothing), not a positional value.
+
+---
+
+## Dark mode — `themes/dark.json`
+
+Dark mode is a **separate token set**, `tokens/themes/dark.json` — **not** declared inline on tokens (there is no `$mods`/`$modes` extension).
+
+The model is **default + override**:
+
+- The `semantic` layer carries the **default (light)** values, at their natural place (`semantic/color.json`, `semantic/form.json`). There is **no** `themes/light.json` — light is the baseline, not a mode you switch into.
+- `themes/dark.json` holds **only the tokens that differ** in dark mode (background, text, heading, shadow, border, form background). Everything mode-invariant (brand, accent, status, …) is inherited automatically through `var()`.
+
+This mirrors the DTCG **Resolver** philosophy (a base set + an overlay holding only the differences), so it stays forward-compatible as the Resolver spec stabilises.
+
+### Generated output
+
+The build emits `dist/css/themes/dark.css` with a single rule, inside `@layer tokens`:
+
+```css
+@layer tokens {
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-color-scheme="light"]) {
+      --color-background: var(--color-gray-950);
+      /* … */
+    }
+  }
+}
+```
+
+The light defaults stay in `dist/css/semantic/*.css` on `:root`. The dark file is purely additive — a light-only (mono-mode) site never needs to load it.
+
+### Activation matrix
+
+Dark mode follows the OS preference. The only attribute that does anything is `data-color-scheme="light"`, which **forces light** even when the OS prefers dark. Forcing dark against a light OS is intentionally **not** supported (there is no `[data-color-scheme="dark"]` rule).
+
+| `data-color-scheme` on `<html>` | OS preference | Result | Why |
+| --- | --- | --- | --- |
+| *(none)* | light | **light** | `:root` defaults; the media query is inactive |
+| *(none)* | dark | **dark** | the media rule matches `:root` (not forced light) |
+| `light` | dark | **light** | `:not([data-color-scheme="light"])` excludes it → `:root` defaults |
+| `light` | light | **light** | `:root` defaults; the media query is inactive |
+| *(any other)* | dark | **dark** | the media rule still matches — only `light` opts out |
+
+> **Note** — `color-scheme: dark` is intentionally absent from the generated block. The `color-scheme` property is managed at the HTML level by the consuming application (e.g. via `<meta name="color-scheme">`), not by the token layer.
+
+### Rules
+
+- Only colour tokens that actually change between modes belong in `themes/dark.json`; everything mode-invariant stays in `semantic`.
+- Dark values follow the same `{dotted.path}` reference syntax as `$value` (e.g. `{color.gray.950}`).
+
+---
+
+## Adding a new token file
+
+1. Create a JSON file anywhere under `tokens/` with DTCG structure.
+2. Run `npm run build` — the file is detected automatically.
+3. A matching CSS file is generated in `dist/css/`.
+
+No changes to `style-dictionary.config.js` are needed.
+
+---
+
+## References
+
+- [Style Dictionary v5 docs](https://styledictionary.com/)
+- [DTCG format](DTCG.md) — token structure and types
+- [Utopia fluid scales](UTOPIA.md) — `clamp()` values in spacing and typography tokens
+
+---
+
+## The JSON manifest
+
+Alongside the CSS, the build writes `dist/tokens.json`: a flat array of every token the package ships.
+
+```json
+[
+  {
+    "name": "--color-brand",
+    "value": "var(--color-sienna-600)",
+    "type": "color",
+    "file": "semantic/color",
+    "description": ""
+  }
+]
+```
+
+The documentation site renders its reference tables from this file, which is why the reference cannot drift from the stylesheets.
+
+The guarantee comes from a single shared function. `tokenToCssValue()` serializes a token to its CSS value, and **both** the CSS format and the manifest format call it. There is no second implementation of the naming or the value logic to fall out of step, and the build asserts the equivalence: the manifest holds exactly one entry per declaration emitted in `dist/css/`, with the same name and the same value.
+
+`description` comes from the DTCG `$description` key. Adding one to a token source makes it appear in the published reference with no other change.