Sketchbook
On this page

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 starting point (--start), or set the brand.

sketchbook init
  [--name <value>]
  [--primary <value>]
  [--font <value>]
  [--radius <value>]
  [--density <value>]
  [--danger <value>]
  [--design <value>]
  [--file <value>]
  [--prefix <value>]
  [--start <starter>]
  [--components <a,b>]
  [--from <file>]
  [--yes]
  [--dir <folder>]
  [--adopt]
  [--engine <spec>]
  [--no-install]
  [--agent <profiles>]
  [--with <groups>]
  [--detach-catalog]
  [--dry-run]
  [--json]

Changes files; supports --dry-run.

Option Meaning
--name Brand or system name
--primary Primary color as #RRGGBB, or "neutral" for the shadcn default
--font Font family name (falls back to the system stack)
--radius sharp | soft | round | pill-heavy (sketchbook presets radius)
--density compact | comfortable | spacious
--danger Destructive color as #RRGGBB
--design Design-file adapter: figma | none
--file Figma file key (when design is figma)
--prefix Element and CSS prefix, e.g. acme (acme-button, --acme-*); rewrites sources (see sketchbook prefix)
--start Starting point: blank | foundations | library (default) | library+kits | pick | import | from-codebase (harness/starters)
--components With --start: the components to have (pick needs it; all | none also work); dependencies come along
--from With --start import: the tokens file; with --start from-codebase: the CSS path or glob to audit
--yes Confirm what would lose work: with --start, removing components or kits the starter does not include; with brand options or a starter that patches foundations, letting the brand links overwrite hand-edited linked tokens. It never detaches the catalog
--dir Create the project in this folder (new or empty), e.g. a design-system folder inside an existing repository; default: here
--adopt In an existing project: add the design system in its own folder (design-system/, or --dir) without changing your files; your package.json gets one script that runs its checks
--engine For new projects, override the engine dependency with an npm version or tag, a local tarball, or a Git URL. A published CLI uses its version range by default. Relative local paths are resolved from the directory where init starts
--no-install New project only: skip npm install and the Chromium download (init lists them as next steps)
--agent Install selected agent profiles (comma-separated): claude, codex, gemini, copilot, trae, jetbrains, generic. New projects default to core only
--with Select the Claude profile and add optional groups (comma-separated): forge. Forge adds the forge-me-a-skill skill
--detach-catalog With --start in the catalog source repo (catalog.source true): stop tracking harness/catalog; the components become the team's own

Examples

  • sketchbook init
  • sketchbook init --agent claude
  • sketchbook init --agent codex,trae --dry-run
  • sketchbook init --dir design-system --start library
  • sketchbook init --start library
  • sketchbook init --with forge
  • sketchbook init --start blank --yes
  • sketchbook init --start pick --components card,button
  • sketchbook init --start from-codebase --from "../app/**/*.css"
  • sketchbook init --primary "#2563EB" --font Inter --radius round
  • sketchbook init --density compact --dry-run

status

Show the prefix, brand summary, components by status, overrides and design sync state (read-only).

sketchbook status [--json]

Read-only.

Examples

  • sketchbook status
  • sketchbook status --json

doctor

Health report (read-only): starter, harness version, installed vs catalog components, kits, brands, overrides, design sync, failing checks, selected agent integrations and the commit gate. Exits like check (0 pass, 1 a check fails, 2 pass with overrides).

sketchbook doctor [--json]

Read-only.

Examples

  • sketchbook doctor
  • sketchbook doctor --json

upgrade

Update harness-owned files. In a project that runs the engine from node_modules: from the installed engine (after npm update), no --from. Elsewhere: from a newer Sketchbook folder or git URL (harness-owned in both manifests); team-owned, shared, reclassified and protected files (the manifest itself, configs, package files) are listed, never touched; writing anything needs --yes (a dry run first shows what).

sketchbook upgrade [--from <path|git-url>] [--yes] [--dry-run] [--json]

Changes files; supports --dry-run.

Option Meaning
--from A newer Sketchbook: a folder, or a git URL (cloned shallowly; its commit is printed)
--yes Confirm writing the upstream harness code (required whenever files would change), then run the checks with it

Examples

  • sketchbook upgrade --from ../sketchbook --dry-run
  • sketchbook upgrade --from ../sketchbook --yes
  • sketchbook upgrade --from https://example.com/sketchbook.git --dry-run

propagate

Carry a Foundations or harness change to every output: rebuild the tokens and components, build the engine, sync the design file scripts (tokens and foundations), and record what the outputs were built from. --maintainer also builds Storybook and the docs site (maintainers only).

sketchbook propagate [--maintainer] [--json]

Changes files.

Option Meaning
--maintainer Also build Storybook and the docs site, and record them for check --maintainer

Examples

  • sketchbook propagate
  • sketchbook propagate --maintainer

generate

Rebuild every generated output from the spec: token CSS, component tokens, component styles, the barrel, brand CSS and the token interface (what npm run generate runs in a project).

sketchbook generate [--json]

Changes files.

Examples

  • sketchbook generate
  • sketchbook generate --json

prefix

Rename the element and CSS prefix everywhere (sources, contracts, tests, docs), rebuild, then check.

sketchbook prefix <new> [--dry-run] [--json]

Changes files; supports --dry-run.

Argument Meaning
new Lowercase letters and digits, e.g. acme

Examples

  • sketchbook prefix acme
  • sketchbook prefix acme --dry-run

swap

Replace an adapter (token build or design tool) without touching the spec, then rebuild and check.

sketchbook swap <output> <adapter> [--file <id>] [--dry-run] [--json]

Changes files; supports --dry-run.

Argument Meaning
output What to swap: tokens
adapter tokens: style-dictionary
Option Meaning
--file Design file key (design figma)

Examples

  • sketchbook swap tokens plain
  • sketchbook swap design none

View as Markdown