Use in an existing app
Add the design system to an app repository in its own folder, then repair, check and upgrade it.
On this page
Adopting adds the design system in its own folder, design-system/ by default, and adds one script to the app's package.json that runs its checks.
Run the following commands from your app directory. npm fetches @usesketchbook/cli, and init adds it as a dev dependency of the design-system project.
-
Preview. Use
--dirto name another folder.npm exec --yes --package=@usesketchbook/cli -- sketchbook init --adopt --start library --dry-run -
Run it. Replace
libraryin both commands if you want a different starter.npm exec --yes --package=@usesketchbook/cli -- sketchbook init --adopt --start libraryThe command creates a core-only project. Append
--agent traeto select TRAE or use a comma-separated list to set up several clients. See available profiles and their files.--no-installskips dependency and Chromium setup. -
Open the design-system folder in your agent. For Claude Code, add
--agent claudeduring adoption and follow the activation steps from that folder. Client setup files live inside the design-system folder.
Repair
From the design-system folder, run init again to restore files for the selected profiles. Use --agent to add a profile or --with forge to set up Claude and the optional skill for writing your own skills.
npx sketchbook init
npx sketchbook init --agent codex --dry-run
npx sketchbook init --with forge
Check health
doctor is read-only. It reports the starter, harness version, components, kits, overrides, design sync, brands, the commit gate, failing checks and the selected agent integrations.
npx sketchbook doctor
Upgrade
From the design-system folder, install the intended CLI release and preview the changes to harness-owned files.
npm install --save-dev @usesketchbook/cli@latest
npx sketchbook upgrade --dry-run
Review the preview, then apply the changes.
npx sketchbook upgrade --yes
Replace latest with a version number to select a specific release. The install command also replaces an existing file: dependency on a local tarball. upgrade reads from the installed CLI and reports which team-owned files it leaves in your project. For upgrades directly from a Sketchbook checkout or Git URL, see upgrade in the CLI reference.
Next steps
- Project CLI: every option of
init,status,doctorandupgrade. - Claude layer: the staged skills, commands, rules and hooks.