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.
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
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.jsonlists what contracts, stories, specs and.storybookdepend on, and check T7 guards it. Rename withsketchbook tokens rename <old> <new>, and runsketchbook 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.
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 turns each axis into a variable collection with one mode per value.