Sketchbook
On this page

The design file is generated from spec/. It is never a source. Do not edit variables, styles or docs in the file by hand: change the spec, then sync. A hand edit shows up as a mismatch in check D1.

Download the example Figma file and import it into Figma to explore a reference snapshot of one possible Sketchbook output. Sketchbook ships with no file key: start by importing the example, then set your own file as the sync target with sketchbook swap design figma --file <your file key>. To sync without committing the key, set the SKETCHBOOK_FIGMA_FILE environment variable instead; it takes precedence over adapters.design.file.

What sync writes

With the design adapter set to Figma, sketchbook sync writes to the file named in adapters.design.file in harness.config.json, and nowhere else:

  • Variables: collections and modes for Mode, Shape and Density.
  • Text and effect styles.
  • Documentation pages and library components, drawn from spec/design-docs.json and the contracts.

The Guide page is static orientation with no sync date or hash. sketchbook sync guide redraws it when pages or theme axes change; it is outside the token stamp and check D1.

The scripts only create and update. They never delete, so removing or renaming something in the file is a separate step you confirm first.

Requirements

  • The Figma MCP with use_figma is connected. Without it, the sync stops and tells you what to do.
  • The file is on a plan that allows several modes per collection. Semantic - Shape has 4 modes and Semantic - Density has 3, and Figma's free Starter plan may allow only one mode per collection (not confirmed on an official page; see docs/research/figma-plans.md).

Sync flow

sync tokens writes numbered scripts with only what changed since the last stamp. You run each one through use_figma, in order, then stamp and read the file back.

sketchbook sync tokens
sketchbook sync stamp tokens
sketchbook sync verify
sketchbook sync verify --ingest figma-verify.json
sketchbook sync components <batch>
sketchbook sync progress

In Claude Code, /sync runs this flow through the design-figma skill, and /sync verify runs the read-back.

Warning

Library scripts carry a checksum and refuse to run if a paste differs by one character. Copy each file exactly. Do not hand the pasting to a sub-agent.

sketchbook docs <name> prints the same component doc as tool-neutral text.

Components and patterns

Storybook is the reference and the design file is an output that must look like it. A component or pattern is not done until sketchbook sync compare and a side-by-side look agree with Storybook; a clean read-back alone is not enough.

sketchbook sync compare settings --url http://localhost:6006
sketchbook sync compare --ingest generated/design/compare
sketchbook sync stamp note button

compare --ingest writes docs/design-docs/parity.md. When the library cannot match yet, record the gap with sync stamp note and fix it in place; stamp checked only after the comparison agrees. sync realize records each drawn component in its contract, and sync theme-matrix draws every theme combination side by side.

What is checked

  • D1: the file is behind the spec, or a value differs.
  • D3: token names in the design docs are real.
  • D4: the library read-back recorded per contract in realizations.design.

Next steps

View as Markdown