Sketchbook
On this page

The sketchbook CLI is the deterministic half of the harness. Run sketchbook <command>, or node harness/cli.mjs <command>. This section is split by topic and generated from the command modules by npm run generate, so it matches the CLI as of the last build.

sketchbook help <command>
sketchbook check --json
sketchbook tokens set color.primary "#0F766E" --dry-run

Conventions

  • Bare sketchbook in a terminal opens an interactive menu built from this registry: pick a group and a command, answer prompts (current values shown), see the dry run, then confirm. Piped input or --json prints help instead.
  • --json on every command prints one envelope: { ok, command, changed[], warnings[], errors[{file, msg, fix}], next, data? }.
  • Exit codes: 0 ok, 1 failed, 2 ok with flags (for example overrides kept in spec/tokens/overrides.json).
  • Read-only commands never write. Mutating commands say what they change; those marked "dry run" accept --dry-run.
  • Conventions (one registry, introspect before mutate, JSON envelope) are adapted from CLI-Anything (HKUDS, Apache-2.0, https://github.com/HKUDS/CLI-Anything); no code is used.
Global option Meaning
--json Print one JSON envelope instead of human output
--dry-run Show what would change without writing (mutating commands that support it)
--help Show help for the command

Getting help

help

List commands, or show one command's arguments, options and examples.

sketchbook help [command] [--json]

Read-only.

Argument Meaning
command (optional) A command name

Examples:

  • sketchbook help
  • sketchbook help init

Project setup

Create, inspect, repair and upgrade a Sketchbook project.

Command What it does
init In a new or empty folder: install the core harness and any selected agent integrations. In a project: add or repair integrations (--agent), pick a…
status Show the prefix, brand summary, components by status, overrides and design sync state (read-only).
doctor Health report (read-only): starter, harness version, installed vs catalog components, kits, brands, overrides, design sync, failing checks,…
upgrade Update harness-owned files. In a project that runs the engine from node_modules: from the installed engine (after npm update), no --from.…
propagate Carry a Foundations or harness change to every output: rebuild the tokens and components, build the engine, sync the design file scripts (tokens…
generate Rebuild every generated output from the spec: token CSS, component tokens, component styles, the barrel, brand CSS and the token interface (what…
prefix Rename the element and CSS prefix everywhere (sources, contracts, tests, docs), rebuild, then check.
swap Replace an adapter (token build or design tool) without touching the spec, then rebuild and check.

Tokens and brand

Change foundations, presets and brands, and import or audit existing styles.

Command What it does
tokens Change foundations and semantic tokens through the harness: set, preset, presets, diff, impact, add, remove, rename, import, scratch, overrides.
presets List the standards catalog: families, or one family's presets with sources (read-only).
brand Several brands over one semantic interface: brands/.brand.json; add, list, use (copy into brand.config.json and regenerate) and build…
audit-css Audit an existing product's CSS: cluster its colors (OKLCH distance), font sizes, spacing, radii and shadows into a foundations proposal…

Components and kits

Install, remove and list components and kits, and read the naming standard.

Command What it does
add Install a component from the catalog (contract, code, stories, specs; dependencies first), or --blank to scaffold a new contract (status draft,…
remove Uninstall a component: refuses while another component or a kit needs it, and without --yes when it is team-made or customized; else removes its…
list List catalog components (installed or available) with what each needs, plus template kits (read-only).
kits Template kits (harness/kits/index.json): list them, add one (its components come from the catalog first) or remove one (--yes when it was edited).
api The API vocabulary (spec/api.json): list every component prop, event and state against it (canonical, alias, extension), check that nothing is…

Design file

Sync variables, styles and docs to the design file, and manage icons.

Command What it does
icons The icons the system uses (spec/icons.json, Lucide): list them, add one or more from Lucide (--category) or remove them. The design adapters draw…
sync Write the Figma MCP (use_figma) scripts for the design file (tokens: variable collections, modes and styles), read the file back ("sync verify",…
docs Show a component's or a pattern's documentation, tool-neutral: the same doc a design file draws (variants and states grids, elements, anatomy,…

Quality and checks

Run the deterministic checks, self-test the harness and trace where a value comes from.

Command What it does
audit-page Check a complete HTML page using this design system for a level-one heading and main landmark. This static check is not a full accessibility audit.
audit-decisions Compare the decision log with a trusted earlier copy or Git revision and report changes to settled entries. This read-only audit does not replace…
check Run the deterministic checks (exit 0 pass, 1 fail, 2 pass with flagged overrides).
selftest Run the harness's own tests against the installed engine: they prove every check can still reject and that the CLI, starters and generators work…
explain Explain a token, CSS variable, component, tag or decision from the spec.

View as Markdown