Tokens and brand
Change foundations, presets and brands, and import or audit existing styles.
tokens
Change foundations and semantic tokens through the harness: set, preset, presets, diff, impact, add, remove, rename, import, scratch, overrides.
sketchbook tokens <subcommand>
[args...]
[--value <v>]
[--light <v>]
[--dark <v>]
[--type <type>]
[--pair <fg:bg>]
[--kind <text|large-text|ui>]
[--against <ref>]
[--from <dtcg|css>]
[--name <n>]
[--only <semantic|foundation|mapped>]
[--min-confidence <0.6>]
[--answers <file.json>]
[--all]
[--yes]
[--verbose]
[--no-record]
[--dry-run]
[--json]
Changes files; supports --dry-run.
| Argument | Meaning |
|---|---|
subcommand |
rebuild |
args (optional) |
The subcommand's arguments (see below) |
| Option | Meaning |
|---|---|
--value |
add: mode-less value (alias like {space.4}, or a literal) |
--light |
add: value for light-role modes |
--dark |
add: value for dark-role modes |
--type |
add: $type when it cannot be inferred (color, dimension, number, …) |
--pair |
add: also declare a contrast pair (fg:bg or fg/bg) in spec/tokens/contrast.json |
--kind |
add: kind of the contrast pair (default text) |
--against |
diff: git ref to compare with (default HEAD) |
--from |
import: source format (default: from the file, .css/.scss is css, .json or a folder is dtcg) |
--name |
import: proposal name (default: the file name) |
--only |
import apply: only semantic (alias mapped) or only foundation entries |
--min-confidence |
import apply: skip entries below this confidence |
--answers |
scratch: answers (name, primary, neutral, font, scale, spacing, radius, density, motion, elevation, contrast) |
--all |
overrides reset: every override |
--yes |
overrides reset --all: confirm without asking; any mutating subcommand: let the brand links overwrite hand-edited linked tokens |
--verbose |
impact: list every file reference |
--no-record |
Do not propose an SB decision record (each mutating call that changes a file proposes one otherwise) |
| Subcommand | What it does |
|---|---|
sketchbook tokens rebuild |
Rebuild foundations and linked tokens from the current brand, preserving recorded and hand-edited foundation overrides. Review the dry run first. |
sketchbook tokens set <key> <value> |
Set one value in brand.config.json by dot path (validated against the schema and the catalog); a .preset key replaces its sibling fine overrides. |
sketchbook tokens preset <foundation> <id> |
Switch a foundation to a catalog preset. |
sketchbook tokens presets [foundation] |
List the standards catalog (same as sketchbook presets); an area lists each of its families. Read-only. |
sketchbook tokens diff [--against <ref>] |
CSS custom properties added, removed and changed per mode: generated/css/tokens.css now vs a git ref (default HEAD). Read-only. |
sketchbook tokens impact <token-path | --css-var> |
What depends on a token: semantic aliases, brand links, contracts (component tokens, contrast pairs), and stories, specs, .storybook and patterns using its CSS variable. Read-only. |
sketchbook tokens add <semantic.path> (--value v | --light v --dark v) [--type t] [--pair fg:bg --kind text|large-text|ui] |
Add a semantic token: one mode-less value (--value) or one per mode (--light, --dark; modes by role); optionally a contrast pair. |
sketchbook tokens remove <semantic.path> |
Remove a semantic token from every semantic file; refused (with the impact) while anything depends on it. |
sketchbook tokens rename <old> <new> |
Rename a semantic token (or group) everywhere: semantic files and aliases, brand links, contracts (tokens, contrast), contrast.json, CSS variables in stories, specs, patterns and .storybook. |
sketchbook tokens import <file|folder> --from dtcg|css [--name n] | import apply <proposal> [--only semantic|foundation|mapped] [--min-confidence 0.6] |
Parse existing tokens (DTCG / Tokens Studio, one file or a folder of sets, CSS custom properties) into generated/import/ |
sketchbook tokens scratch [--answers file.json] |
Restart the foundations: a minimal brand.config.json from answers (a JSON file, or questions when interactive; defaults otherwise). The semantic interface is kept. |
sketchbook tokens overrides list | reset <path> | reset --all [--yes] |
Hand edits kept in spec/tokens/overrides.json: list them, reset one to the generated value (a hand-added token is removed), or reset all (asks unless --yes). |
Examples
sketchbook tokens set typography.family Inter --dry-runsketchbook tokens impact color.bordersketchbook tokens rename color.muted color.subtle --dry-runsketchbook tokens import theme.css --from csssketchbook tokens rebuild --dry-runsketchbook tokens rebuildsketchbook tokens set typography.family Intersketchbook tokens set spacing.preset grid-8 --dry-runsketchbook tokens set color.primary "#0F766E"sketchbook tokens preset spacing grid-8 --dry-runsketchbook tokens preset typography perfect-fourthsketchbook tokens preset motion material-likesketchbook tokens presetssketchbook tokens presets colorsketchbook tokens diffsketchbook tokens diff --against mainsketchbook tokens impact color.primarysketchbook tokens impact color.neutral.900sketchbook tokens add color.highlight --light "{color.neutral.100}" --dark "{color.neutral.800}" --pair color.foreground:color.highlightsketchbook tokens add space.section --value "{space.16}"sketchbook tokens remove color.legacy-accent --dry-runsketchbook tokens rename color.muted color.subtlesketchbook tokens import tokens.json --from dtcgsketchbook tokens import theme.css --from css --name brandsketchbook tokens import apply generated/import/brand.proposal.json --dry-runsketchbook tokens scratch --dry-runsketchbook tokens scratch --answers answers.jsonsketchbook tokens overrides listsketchbook tokens overrides reset radius.mdsketchbook tokens overrides reset --all --yes
presets
List the standards catalog: families, or one family's presets with sources (read-only).
sketchbook presets [family] [--json]
Read-only.
| Argument | Meaning |
|---|---|
family (optional) |
A family id, e.g. spacing, typeScale, motion |
Examples
sketchbook presetssketchbook presets motion
brand
Several brands over one semantic interface: brands/
sketchbook brand [action] [name] [--from <current|brand>] [--yes] [--dry-run] [--json]
Changes files; supports --dry-run.
| Argument | Meaning |
|---|---|
action (optional) |
list (default) |
name (optional) |
Brand name (lowercase), for add and use |
| Option | Meaning |
|---|---|
--from |
add: start from brand.config.json (current, default) or another brand |
--yes |
use: confirm overwriting brand.config.json edits saved in no brand file, and clearing foundation overrides |
| Subcommand | What it does |
|---|---|
sketchbook brand add |
See sketchbook help brand. |
sketchbook brand list |
See sketchbook help brand. |
sketchbook brand use |
See sketchbook help brand. |
sketchbook brand build |
See sketchbook help brand. |
Examples
sketchbook brand add ocean --from currentsketchbook brand listsketchbook brand use oceansketchbook brand build
audit-css
Audit an existing product's CSS: cluster its colors (OKLCH distance), font sizes, spacing, radii and shadows into a foundations proposal (generated/import/codebase.proposal.json).
sketchbook audit-css <paths...> [--dry-run] [--json]
Changes files; supports --dry-run.
| Argument | Meaning |
|---|---|
paths |
CSS/SCSS files, folders or globs (quote globs), relative to the project |
Examples
sketchbook audit-css ../product/srcsketchbook audit-css "app/**/*.css" --json