Sketchbook
On this page

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

Component button.background Semantic color.primary Foundation color.brand.600 used by points to generated from one step only
Each token points one layer down, never further.

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.

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.

Next steps

View as Markdown