# 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 | set | preset | presets | diff | impact | add | remove | rename | import | scratch | overrides |
| `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. <foundation> 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/<name>.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/<name>.brand.json; add, list, use (copy into brand.config.json and regenerate) and build (tokens.<brand>.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) | add | use | build |
| `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`
