Quickstart
Create a Sketchbook project and run its first checks.
Use Node.js 26.13.1 LTS and npm 12.2.3. For older LTS lines, use Node.js 24.22.3 or 22.23.5, or a newer security patch on the same line.
The CLI is published as @usesketchbook/cli on npm. For a project inside an existing app, follow Use in an existing app.
-
Create an empty project folder.
mkdir my-design-system cd my-design-system -
Preview the setup.
--dry-runshows what would change in the project.npm exec --yes --package=@usesketchbook/cli -- sketchbook init --start library --dry-run -
Run init. It creates and checks the project, adds
@usesketchbook/clitodevDependencies, and installs dependencies and Chromium for the browser tests.npm exec --yes --package=@usesketchbook/cli -- sketchbook init --start library -
Look at the project. Run
npx sketchbookcommands from this folder to use the installed CLI. Opendocs/harness.mdfor the initial installation inventory.npx sketchbook status -
Run the checks. Exit 0 means pass, 1 a failure, 2 a pass with hand edits kept as overrides.
npx sketchbook check
Choose agent integrations
The commands above create a core-only project. To set up Claude Code during install, append --agent claude to both init commands. To add it later, run npx sketchbook init --agent claude from the project and follow Claude Code activation. For multiple clients, pass a comma-separated list such as --agent codex,trae.
See available profiles and their files. Run npx sketchbook doctor to inspect your project's setup.
Commands you will use
| Command | What it does |
|---|---|
npm run check |
Run the standard checks (same as sketchbook check) |
npm run generate |
Rebuild tokens, styles and the other outputs |
npm run storybook |
Generate, then start Storybook |
npm run test:install |
Install the Chromium the browser tests use |
npm run test:component |
Run the component behavior tests |
npm run typecheck |
Type-check sources and stories |
Starting points
In both init commands, pass the starter you need to --start.
| Starter | Choose it when |
|---|---|
blank |
You want to design every component from zero. |
foundations |
You want to settle tokens before any component. |
library |
You want a working library now and a rebrand later (default). |
library+kits |
You need screens fast: all components plus template kits. |
pick |
You need a subset: add --components card,button. |
import |
You already have tokens: add --from <file>. |
from-codebase |
You already have a product: add --from "<css glob>". |
For example, replace --start library with --start pick --components card,button to start with two components.
Warning
Commit or stash first when you run a starter in an existing project. It can remove components, and git is the undo.