Sketchbook
On this page

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. is a family (typeScale), its config key (typography.scale) or an area (typography, color, z-index).
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/.proposal.json with a proposed mapping; "import apply" writes a reviewed proposal into brand.config and the semantic files.
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-run
  • sketchbook tokens impact color.border
  • sketchbook tokens rename color.muted color.subtle --dry-run
  • sketchbook tokens import theme.css --from css
  • sketchbook tokens rebuild --dry-run
  • sketchbook tokens rebuild
  • sketchbook tokens set typography.family Inter
  • sketchbook tokens set spacing.preset grid-8 --dry-run
  • sketchbook tokens set color.primary "#0F766E"
  • sketchbook tokens preset spacing grid-8 --dry-run
  • sketchbook tokens preset typography perfect-fourth
  • sketchbook tokens preset motion material-like
  • sketchbook tokens presets
  • sketchbook tokens presets color
  • sketchbook tokens diff
  • sketchbook tokens diff --against main
  • sketchbook tokens impact color.primary
  • sketchbook tokens impact color.neutral.900
  • sketchbook tokens add color.highlight --light "{color.neutral.100}" --dark "{color.neutral.800}" --pair color.foreground:color.highlight
  • sketchbook tokens add space.section --value "{space.16}"
  • sketchbook tokens remove color.legacy-accent --dry-run
  • sketchbook tokens rename color.muted color.subtle
  • sketchbook tokens import tokens.json --from dtcg
  • sketchbook tokens import theme.css --from css --name brand
  • sketchbook tokens import apply generated/import/brand.proposal.json --dry-run
  • sketchbook tokens scratch --dry-run
  • sketchbook tokens scratch --answers answers.json
  • sketchbook tokens overrides list
  • sketchbook tokens overrides reset radius.md
  • sketchbook 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 presets
  • sketchbook presets motion

brand

Several brands over one semantic interface: brands/.brand.json; add, list, use (copy into brand.config.json and regenerate) and build (tokens..css for each).

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 current
  • sketchbook brand list
  • sketchbook brand use ocean
  • sketchbook 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/src
  • sketchbook audit-css "app/**/*.css" --json

View as Markdown