Sketchbook
On this page

Each component has a folder, spec/components/<name>/, with three files.

File Holds
contract.json Machine-readable spec: props, events, states, accessibility, and the component tokens in tokens
contract.md The same spec for people
plan.md Scope, files, tokens, accessibility approach, test plan, risks, open questions

No implementation is added without a contract.json that passes sketchbook check. The component tokens it declares are the only token variables the component's CSS may use. The full field list is in Contract format.

button/contract.json props variant, size, disabled states loading, focus, pressed a11y name, keyboard, contrast tokens --sb-button-* <sb-button> built from the contract checks confirm both still match
The contract is the source the component is built and checked against.

Lifecycle

spec/registry.json gives every component a status: planned, draft, wip, beta, stable, deprecated or code-only.

The evidence each status needs is in Lifecycle statuses. stable needs an accessibility audit with an Approved-by: line.

Note

Editing the registry alone cannot raise a status. Check R1 fails when the evidence is missing.

Workflow

  1. Scaffold the contract. The name must already be in spec/registry.json.

    sketchbook add "<Name>" --blank
    
  2. Fill contract.json and contract.md with the contract-author skill. Anything the sources do not confirm is marked "proposal": true.

  3. Run the checks until they pass.

    sketchbook check
    
  4. Write plan.md, then stop at the planning gate. Write no tests or code until the plan is approved. Record the answers in the contract's openQuestions and in the plan.

  5. Build test-first with the component-builder skill: write the story and behavior spec, see the tests fail, then write the smallest code that passes.

In Claude Code, /add <Name> runs this flow and stops at the planning gate. The gates are described in Checks.

Next steps

View as Markdown