Sketchbook
On this page

"Team" means you edit it. "Generated" means a command rebuilds it and hand edits are flagged. "Harness" means the engine owns it and sketchbook upgrade replaces it.

Project configuration

File Controls Owner Change with
brand.config.json Foundations: color, typography, spacing, radius, density, contrast, breakpoints and more. Each is a preset or custom. Team sketchbook tokens set|preset, or the foundations skill
harness.config.json Prefix, the language of AI and human output, adapters, feature switches, the ui and process references, white-label terms, catalog source, selected agentProfiles, and contextBudget (the always-on context limit that check H1 enforces). Team Edit it; sketchbook prefix <new> renames the prefix
brand/ The brand mark (icon SVG and PNG), shipped in the package. The size.brand.mark semantic token sizes it. Team Replace the files
spec/registry.json Components, tier, status, tag and path. Team sketchbook add, sketchbook remove
{
  "prefix": "sb",
  "agentProfiles": [],
  "features": { "planningGate": true, "testFirst": true },
  "ui": { "reference": "shadcn/ui" },
  "process": { "reference": "contract-first standard" }
}

Note

ui names the visual and API reference your components follow. process names the standard for contract pairs, file layout and decision logs. Replace either to follow your own way of working.

Tokens

File Controls Owner Change with
spec/tokens/semantic/*.tokens.json Semantic tokens: light, dark and base. Team Edit values; sketchbook tokens add|remove; renames only with sketchbook tokens rename
spec/tokens/brand-links.json Which semantic tokens follow the brand. Team Remove a link to own that token
spec/tokens/interface.json The semantic tokens components, stories and specs depend on. Generated npm run generate
spec/tokens/overrides.json Hand edits to foundation tokens, kept and flagged. Generated sketchbook tokens overrides list
spec/tokens/foundation/* The foundation layer. Generated npm run tokens:generate

Warning

Do not rename a semantic token by hand. A manual rename breaks contracts and stories without an error.

Docs and vocabulary

File Controls Owner Change with
spec/design-docs.json The doc shell the design adapters render. Team Edit it; checks D3 and T7 verify it
spec/api.json Prop, content, state and event names every component speaks. Team Edit it; check A1 verifies contracts
spec/decisions/DECISIONS.md One entry per design-system decision. Team Add an entry; supersede, never edit
docs/simplicity-debt.md Shortcuts taken on purpose. Team hammock skill, debt mode

Ownership for upgrades

harness/manifest.json splits files into groups. sketchbook upgrade replaces the harness group and only reports on the others.

Group Paths (abridged)
harness harness/**, .claude/skills/**, .claude/rules/**, .claude/commands/**, scripts/**, docs/cli.md
team spec/**, src/**, brands/**, brand.config.json, harness.config.json, playwright/tests/**, docs/**
shared package.json, tsconfig.json, .storybook/**, CLAUDE.md, README.md

Next steps

View as Markdown