Config files
The source and config files a team edits, who owns each, and the command to change it.
"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
uinames the visual and API reference your components follow.processnames 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
- Foundations and tokens: the layers these files feed.
- Rules: the rules that protect them.