# Foundations and tokens

Set foundations once in brand.config.json and let tokens flow through three layers.

`brand.config.json` holds the foundations: color, modes, typography, spacing, radius, density, contrast and breakpoints, among others (see `sketchbook presets` for every family). Each foundation is a `preset` from the standards catalog in `harness/standards/`, or `custom` values. The generator turns it into the foundation layer.

```terminal
sketchbook presets
sketchbook tokens preset spacing grid-8 --dry-run
sketchbook tokens set color.primary "#0F766E"
sketchbook tokens diff
```

Use `--dry-run` first, then end with `sketchbook tokens diff`, `sketchbook tokens impact` and `sketchbook check`. The `foundations` skill drives the same commands in Claude Code.

## Three layers

<figure class="illustration"><svg viewBox="0 0 720 240" role="img" aria-label="Three token layers stacked: a component token points to a semantic token, which points to a foundation value. Each step goes down one layer only.">
<defs><filter id="sketch-layers" x="-3%" y="-5%" width="106%" height="110%"><feTurbulence type="fractalNoise" baseFrequency="0.035" numOctaves="2" seed="11" result="n"/><feDisplacementMap in="SourceGraphic" in2="n" scale="2.4"/></filter><marker id="arrow-layers" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10 z" fill="currentColor"/></marker></defs>
<g filter="url(#sketch-layers)" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
<rect x="180" y="20" width="360" height="52" rx="8"/>
<rect x="180" y="94" width="360" height="52" rx="8"/>
<rect x="180" y="168" width="360" height="52" rx="8" stroke="var(--sb-color-primary)" stroke-width="2"/>
<path d="M360 74 L360 88" marker-end="url(#arrow-layers)"/>
<path d="M360 148 L360 162" marker-end="url(#arrow-layers)"/>
</g>
<g font-family="inherit" text-anchor="middle">
<text x="360" y="45" font-size="16" fill="var(--sb-color-foreground)">Component  <tspan fill="var(--sb-color-muted-foreground)" font-size="13">button.background</tspan></text>
<text x="360" y="119" font-size="16" fill="var(--sb-color-foreground)">Semantic  <tspan fill="var(--sb-color-muted-foreground)" font-size="13">color.primary</tspan></text>
<text x="360" y="193" font-size="16" fill="var(--sb-color-primary)">Foundation  <tspan fill="var(--sb-color-muted-foreground)" font-size="13">color.brand.600</tspan></text>
</g>
<g font-family="inherit" font-size="13" fill="var(--sb-color-muted-foreground)">
<text x="24" y="45">used by</text>
<text x="24" y="119">points to</text>
<text x="24" y="193">generated from</text>
</g>
<text x="576" y="119" font-family="inherit" font-size="13" fill="var(--sb-color-muted-foreground)">one step only</text>
</svg>
<figcaption>Each token points one layer down, never further.</figcaption></figure>

Each layer may reference only the layer directly below it.

| Layer | Holds | May reference |
| --- | --- | --- |
| Foundation | Literal values, generated from `brand.config.json` | Nothing |
| Semantic | Meaning, such as a primary color, per mode | Foundation |
| Component | `--sb-<component>-*` values, declared in the contract | Semantic |

Check T2 enforces this. A component token that aliases a foundation token fails; use a semantic token in between.

> **Note** Component CSS may use only its own component tokens and private `--_*` properties. Need another value? Add a component token to the contract first.

## Semantic tokens

The files in `spec/tokens/semantic/` are yours. Change values freely, or use `sketchbook tokens add` and `sketchbook tokens remove`. `spec/tokens/brand-links.json` declares which tokens follow the brand; to unlink one, remove its link instead of overwriting its value.

> **Note** Semantic tokens are an interface: `spec/tokens/interface.json` lists what contracts, stories, specs and `.storybook` depend on, and check T7 guards it. Rename with `sketchbook tokens rename <old> <new>`, and run `sketchbook tokens impact <token>` first to see what depends on it.

## Overrides

A hand edit to a foundation token is kept, but recorded in `spec/tokens/overrides.json` and flagged, and `sketchbook check` exits 2. Resolve it into `brand.config.json`, then reset it.

```terminal
sketchbook tokens overrides list
sketchbook tokens overrides reset <path>
```

## Themes

Three independent axes change the look from the same tokens. Any combination is valid, which gives 2 × 4 × 3 = 24.

| Axis | What changes | Values |
| --- | --- | --- |
| Mode | Color roles | light, dark (`brand.config.json` `modes`) |
| Shape | The radius scale | sharp, soft (default), round, pill-heavy |
| Density | The control sizes and paddings | compact, comfortable (default), spacious |

`spec/tokens/brand-links.json` says which semantic tokens follow the brand, grouped by foundation (density, radius, motion, elevation, icons, z); `docs/design-docs/themes.md` maps them to axes. Density changes components only; Shape and Mode also reach the page chrome. The [design file](/concepts/design-file/) turns each axis into a variable collection with one mode per value.

## Next steps

- [Foundations guide](/guides/foundations/)
- [Import tokens](/guides/import-tokens/)
- [Contracts](/concepts/contracts/)
