# Design file

Sync variables, styles and docs to the design file, and manage icons.

## icons

The icons the system uses (spec/icons.json, Lucide): list them, add one or more from Lucide (--category) or remove them. The design adapters draw one component per icon (sketchbook sync icons).

```
sketchbook icons [action] [names...] [--category <category>] [--dry-run] [--json]
```

Changes files; supports `--dry-run`.

| Argument | Meaning |
| --- | --- |
| `action` (optional) | list (default) | add | remove |
| `names` (optional) | Lucide icon names, e.g. chevron-down check |

| Option | Meaning |
| --- | --- |
| `--category` | add: group in the design file (action, navigation, feedback, content, ...) |

| Subcommand | What it does |
| --- | --- |
| `sketchbook icons list` | See `sketchbook help icons`. |
| `sketchbook icons add` | See `sketchbook help icons`. |
| `sketchbook icons remove` | See `sketchbook help icons`. |

**Examples**

- `sketchbook icons list`
- `sketchbook icons add chevron-down check --category navigation`
- `sketchbook icons remove star`

## sync

Write the Figma MCP (use_figma) scripts for the design file (tokens: variable collections, modes and styles), read the file back ("sync verify", then "--ingest"), record a push or a component stage with "sync stamp", list the progress of the component docs with "sync progress", or write the design realization of each contract from the library read-back with "sync realize".

```
sketchbook sync
  [what]
  [names...]
  [--verify]
  [--full]
  [--detail <combination>]
  [--url <http://localhost:6006>]
  [--ingest <file.json>]
  [--dry-run]
  [--json]
```

Changes files; supports `--dry-run`.

| Argument | Meaning |
| --- | --- |
| `what` (optional) | tokens (default) | verify | stamp | progress | describe | verify-library | layout | theme-matrix | components | patterns | compare | realize |
| `names` (optional) | After "stamp": tokens|foundations|components, or library|doc|checked|note|clear, then component names (clear takes names only, and removes the note and its fix flag without changing the stage); after "library" or "describe": the components (describe defaults to every drawn one); after "components": one batch id of spec/design-docs.json; after "realize" or "verify-library --ingest": the components (default every drawn one) |

| Option | Meaning |
| --- | --- |
| `--verify` | Same as "sync verify" |
| `--full` | With tokens: write every variable, not only what changed since the last stamp |
| `--detail` | With verify: also return that combination's values (e.g. "Dark \| Round \| Compact") so --ingest names each differing variable. With library: the variant (e.g. "Variant=Primary, Size=Medium, State=Rest, Disabled=False") whose node-by-node bindings its verify script lists when they differ |
| `--url` | With compare: the running Storybook to render the pattern states from (default http://localhost:6006) |
| `--ingest` | With compare: the folder holding what each compare-<id>.js returned (<id>.fg.json); writes docs/design-docs/parity.md. With verify: compare the JSON that verify.js returned with the spec per theme combination and write generated/design/verify.json (read by check D1). With verify-library: record what verify-all.js returned per set in generated/design/library-verify.json (read by sync realize and check D4) |

| Subcommand | What it does |
| --- | --- |
| `sketchbook sync tokens` | See `sketchbook help sync`. |
| `sketchbook sync pages` | See `sketchbook help sync`. |
| `sketchbook sync brand` | See `sketchbook help sync`. |
| `sketchbook sync guide` | See `sketchbook help sync`. |
| `sketchbook sync foundations` | See `sketchbook help sync`. |
| `sketchbook sync icons` | See `sketchbook help sync`. |
| `sketchbook sync library` | See `sketchbook help sync`. |
| `sketchbook sync describe` | See `sketchbook help sync`. |
| `sketchbook sync verify-library` | See `sketchbook help sync`. |
| `sketchbook sync layout` | See `sketchbook help sync`. |
| `sketchbook sync theme-matrix` | See `sketchbook help sync`. |
| `sketchbook sync components` | See `sketchbook help sync`. |
| `sketchbook sync patterns` | See `sketchbook help sync`. |
| `sketchbook sync verify` | See `sketchbook help sync`. |
| `sketchbook sync stamp` | See `sketchbook help sync`. |
| `sketchbook sync progress` | See `sketchbook help sync`. |
| `sketchbook sync realize` | See `sketchbook help sync`. |
| `sketchbook sync compare` | See `sketchbook help sync`. |

**Examples**

- `sketchbook sync tokens`
- `sketchbook sync verify`
- `sketchbook sync verify --ingest figma-verify.json`
- `sketchbook sync stamp tokens`
- `sketchbook sync stamp library button`
- `sketchbook sync compare settings --url http://localhost:6006`
- `sketchbook sync compare --ingest generated/design/compare`

## docs

Show a component's or a pattern's documentation, tool-neutral: the same doc a design file draws (variants and states grids, elements, anatomy, accessibility rules and source, tokens) as text, or its blueprint with --json for any design adapter.

```
sketchbook docs <name> [--json]
```

Read-only.

| Argument | Meaning |
| --- | --- |
| `name` | A component folder name (spec/components) or a pattern id (src/patterns) |

**Examples**

- `sketchbook docs button`
- `sketchbook docs field --json`
- `sketchbook docs sign-in`
