@usesketchbook/cli 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +13 -29
  2. package/docs/agent-compatibility.md +1 -1
  3. package/docs/cli.md +31 -31
  4. package/harness/catalog/kits/dashboard/files/{63cde4f28d1c141c401d → 09d34e607ea6836480d1} +1 -1
  5. package/harness/catalog/kits/dashboard/files/{11a5797c4c9189b59fbe → 2239c4e4f1d873b03305} +1 -1
  6. package/harness/catalog/kits/dashboard/files/{864acc7ce20f541cf67c → 567a658f80560e3945c6} +1 -1
  7. package/harness/catalog/kits/dashboard/manifest.json +4 -4
  8. package/harness/catalog/kits/data-table/files/{b5d5d7f18347734138e0 → 35c832acd45c642705b1} +1 -1
  9. package/harness/catalog/kits/data-table/files/{36bac8f8e53119768b2e → aaf2d576ed0b53013ac3} +1 -1
  10. package/harness/catalog/kits/data-table/files/{1786ba4d3e0dba1d6a1f → ac8792b3aa3a43002c5e} +1 -1
  11. package/harness/catalog/kits/data-table/manifest.json +4 -4
  12. package/harness/catalog/kits/docs-article/files/{dbc2840f315f672e1d74 → 3c554edf05e9c8bb52c7} +1 -1
  13. package/harness/catalog/kits/docs-article/files/{7f36cb5f0d4f5e103bde → 9d0bb5a1be919431e8ce} +1 -1
  14. package/harness/catalog/kits/docs-article/files/{c2018b502a8094818d8f → e80ea70679e0065026d0} +1 -1
  15. package/harness/catalog/kits/docs-article/manifest.json +4 -4
  16. package/harness/catalog/kits/form-states/files/{b52fb2fc480f0c6352bd → 55a0558891d66e11c216} +1 -1
  17. package/harness/catalog/kits/form-states/files/{88252259f19ed675a0dc → 64566f1a9cb16592d296} +1 -1
  18. package/harness/catalog/kits/form-states/files/{b0b51ebf587b21fd89a1 → f086df13cb85411108a1} +1 -1
  19. package/harness/catalog/kits/form-states/manifest.json +4 -4
  20. package/harness/catalog/kits/onboarding/files/{e669d75a65f4d15d8289 → 738531c9cf4c8bfb9e28} +1 -1
  21. package/harness/catalog/kits/onboarding/files/{ce466020247ecf1ff5fe → b72445926f9763db6c4f} +1 -1
  22. package/harness/catalog/kits/onboarding/files/{322cf4dfc2ee0a035d85 → c969943667ca18e8b0d3} +1 -1
  23. package/harness/catalog/kits/onboarding/manifest.json +4 -4
  24. package/harness/catalog/kits/profile/files/{4aeca453e4792abf29de → 38a6ccd576aca5c96612} +1 -1
  25. package/harness/catalog/kits/profile/files/{0fdd3c14afbdadcf1969 → adccaa2829c56d7fa215} +1 -1
  26. package/harness/catalog/kits/profile/files/{5b58bb5f93ecf12d69ff → de99237cdcfb4ddef8dd} +1 -1
  27. package/harness/catalog/kits/profile/manifest.json +4 -4
  28. package/harness/catalog/kits/settings/files/{d2ebbd6e94570b2c6434 → 08c4411e3c8dbc9e614f} +1 -1
  29. package/harness/catalog/kits/settings/files/{b4a7a4ccdc59465b8de5 → d1cd9cf4acd3416e3f63} +1 -1
  30. package/harness/catalog/kits/settings/files/{1a5d639c6803e7d03acc → f325b6c93ce84d356228} +1 -1
  31. package/harness/catalog/kits/settings/manifest.json +4 -4
  32. package/harness/catalog/kits/sign-in/files/{ca224349b746c530f922 → 0ac413f342ed59e8f3d9} +1 -1
  33. package/harness/catalog/kits/sign-in/files/{552bdad5ce7559849e81 → 796309acee1d478d2692} +1 -1
  34. package/harness/catalog/kits/sign-in/files/{361745a3ed43c753c615 → a106d6104e40b13d7e82} +1 -1
  35. package/harness/catalog/kits/sign-in/manifest.json +4 -4
  36. package/harness/checks/run.mjs +1 -2
  37. package/harness/cli/commands/add.mjs +4 -2
  38. package/harness/cli/commands/api.mjs +1 -1
  39. package/harness/cli/commands/audit-css.mjs +1 -1
  40. package/harness/cli/commands/audit-decisions.mjs +1 -1
  41. package/harness/cli/commands/audit-page.mjs +1 -1
  42. package/harness/cli/commands/brand.mjs +1 -1
  43. package/harness/cli/commands/check.mjs +1 -1
  44. package/harness/cli/commands/docs.mjs +2 -2
  45. package/harness/cli/commands/doctor.d.mts +2 -2
  46. package/harness/cli/commands/doctor.mjs +7 -5
  47. package/harness/cli/commands/explain.mjs +1 -1
  48. package/harness/cli/commands/generate.mjs +1 -1
  49. package/harness/cli/commands/help.mjs +5 -5
  50. package/harness/cli/commands/icons.mjs +1 -1
  51. package/harness/cli/commands/init.mjs +4 -4
  52. package/harness/cli/commands/kits.mjs +3 -1
  53. package/harness/cli/commands/list.mjs +1 -1
  54. package/harness/cli/commands/prefix.mjs +1 -1
  55. package/harness/cli/commands/presets.mjs +1 -1
  56. package/harness/cli/commands/propagate.mjs +1 -1
  57. package/harness/cli/commands/remove.mjs +4 -2
  58. package/harness/cli/commands/selftest.mjs +1 -1
  59. package/harness/cli/commands/status.mjs +6 -4
  60. package/harness/cli/commands/swap.mjs +1 -1
  61. package/harness/cli/commands/sync.mjs +3 -3
  62. package/harness/cli/commands/tokens.mjs +9 -8
  63. package/harness/cli/commands/upgrade.mjs +7 -3
  64. package/harness/cli/docs.mjs +2 -2
  65. package/harness/cli/interactive.mjs +10 -10
  66. package/harness/cli/known-commands.json +26 -26
  67. package/harness/cli/presentation.d.mts +1 -1
  68. package/harness/cli/presentation.mjs +1 -1
  69. package/harness/cli/run.d.mts +3 -3
  70. package/harness/cli/run.mjs +5 -5
  71. package/harness/kits/index.json +8 -8
  72. package/harness/lib/design/docs.mjs +2 -2
  73. package/harness/lib/installed.mjs +1 -1
  74. package/harness/lib/propagation.mjs +2 -2
  75. package/harness/starters/blank.json +1 -1
  76. package/harness/starters/foundations.json +1 -1
  77. package/harness/starters/from-codebase.json +1 -1
  78. package/harness/starters/import.json +1 -1
  79. package/harness/starters/library+kits.json +1 -1
  80. package/harness/starters/library.json +1 -1
  81. package/harness/starters/pick.json +1 -1
  82. package/harness/templates/project/docs/getting-started.md +17 -20
  83. package/harness/templates/project/package-lock.json +2 -2
  84. package/harness/templates/project/src/stories/contract.ts +4 -1
  85. package/harness/templates/project/src/stories/foundations/BorderWidth.stories.ts +1 -1
  86. package/harness/templates/project/src/stories/foundations/Color.stories.ts +1 -1
  87. package/harness/templates/project/src/stories/foundations/Density.stories.ts +1 -1
  88. package/harness/templates/project/src/stories/foundations/Elevation.stories.ts +1 -1
  89. package/harness/templates/project/src/stories/foundations/IconSizes.stories.ts +1 -1
  90. package/harness/templates/project/src/stories/foundations/LayoutGrid.stories.ts +2 -2
  91. package/harness/templates/project/src/stories/foundations/Motion.stories.ts +1 -2
  92. package/harness/templates/project/src/stories/foundations/Opacity.stories.ts +1 -1
  93. package/harness/templates/project/src/stories/foundations/Radius.stories.ts +1 -1
  94. package/harness/templates/project/src/stories/foundations/Spacing.stories.ts +1 -1
  95. package/harness/templates/project/src/stories/foundations/Typography.stories.ts +1 -1
  96. package/harness/templates/project/src/stories/foundations/ZIndex.stories.ts +1 -1
  97. package/harness/test/checks.test.mjs +4 -1
  98. package/harness/test/cli.test.mjs +25 -5
  99. package/package.json +1 -1
package/README.md CHANGED
@@ -4,8 +4,8 @@
4
4
 
5
5
  # Sketchbook
6
6
 
7
- **The harness for building a design system with coding agents.**<br />
8
- Sources of truth, generators, deterministic checks, gates and agent guidance make design-system work repeatable. A component library is one of its outputs.
7
+ **Start with a working design system. Make it yours.**<br />
8
+ Choose a starter, change the sources your team owns, and use the Sketchbook CLI to rebuild and check your work.
9
9
 
10
10
  <br />
11
11
 
@@ -37,7 +37,7 @@ Sketchbook gives your team a workflow for building and maintaining a design syst
37
37
  | **Agent guidance** | Portable project instructions and task workflows, plus the existing Claude Code rules, skills, commands and hooks. |
38
38
  | **Outputs** | Tokens, a Web Components library, 8 page templates, Storybook, a Figma file and docs. The default library follows [shadcn/ui](https://ui.shadcn.com) and is a starting point you can edit or replace. |
39
39
 
40
- Bring nothing, your brand, your tokens or an existing product. The process is the same.
40
+ Bring your tokens or an existing app, or start with the library and change it as you go.
41
41
 
42
42
  ## Quick start
43
43
 
@@ -63,7 +63,7 @@ From the checkout root, run `npm ci` and then `npm run storybook` for the refere
63
63
 
64
64
  ## How it works
65
65
 
66
- Everything starts from a few files you own. The harness rebuilds every output from them, and checks stop anything that drifts.
66
+ Edit the source that owns the change, then rebuild. If a check finds drift, its result points you back to what needs attention.
67
67
 
68
68
  ```mermaid
69
69
  flowchart LR
@@ -73,7 +73,7 @@ flowchart LR
73
73
  K -- pass --> O["Outputs<br/>CSS · components · Storybook · Figma · docs"]
74
74
  ```
75
75
 
76
- **A component goes through the same path every time.**
76
+ Use this workflow to design a new component when the planning and test-first gates are enabled.
77
77
 
78
78
  1. **Contract.** `contract.json` and `contract.md` describe the API, tokens and accessibility. `npm run check` must pass.
79
79
  2. **Plan.** `plan.md` states scope, files, tokens, accessibility approach, test plan and open questions.
@@ -135,38 +135,22 @@ Dark mode follows `prefers-color-scheme`, or set `data-theme="dark"` on `<html>`
135
135
 
136
136
  | | |
137
137
  | --- | --- |
138
- | **A process, not a pile of files** | Contract, plan, approval, tests, checks and review, documented for contributors and agents. |
138
+ | **Agree on the component before building** | Contract, plan, approval, tests, checks and review, documented for contributors and agents. |
139
139
  | **Agent guidance** | Shared instructions describe the process; client-specific hooks and deterministic checks provide additional safeguards. |
140
- | **Checked without AI** | 26 deterministic checks cost no model spend and can each fail. |
141
- | **One source, every output** | Code, Storybook, CSS variables and Figma stay in step because they come from the same files. |
140
+ | **Run checks locally** | 26 deterministic checks cost no model spend and can each fail. |
141
+ | **Rebuild from shared sources** | Code, Storybook, CSS variables and Figma stay in step because they come from the same files. |
142
142
  | **Every foundation is yours** | 19 foundation families with 63 cited presets, or your own values, in one config. |
143
143
  | **Start where you are** | Seven starters, from blank to an existing codebase. |
144
- | **Accessible by default** | WCAG 2.2 AA, axe in every component test, screen-reader views of the accessibility tree. |
145
- | **Safe to upgrade** | Team-owned files are never overwritten. `sketchbook upgrade` only touches what the engine owns. |
144
+ | **Review accessibility as you build** | Contracts target WCAG 2.2 AA. Browser tests and accessibility audits cover different parts of that work. |
145
+ | **Review before you upgrade** | Preview how `sketchbook upgrade` will update harness-owned files. |
146
146
 
147
147
  ## Evidence
148
148
 
149
- Sketchbook was tested the way it is used: with a real AI agent, real projects and real installs.
149
+ In the November 2026 benchmark, 9 of 10 runs with project files alone produced a valid Switch contract, compared with 0 of 10 from an empty folder. The study used a small sample and Sketchbook’s own scoring scripts. [Benchmark results](./docs/research/value-benchmark/SUMMARY.md)
150
150
 
151
- **Does the harness make an agent follow your design system?** 252 headless Claude Code runs (Sonnet 5.5 and Opus 5.5) across five rounds, about $141 of API spend. The agent got the same tasks with and without the project's files, the CLI and the harness.
151
+ The November 11, 2026 installation retest covered a new project, an adopted app, and a checkout. It recorded 168 passing harness tests and 100 passing component behavior tests in an initialized project. One Claude setup step was simulated. [Installation retest](./docs/research/cli-distribution-retest-2/README.md)
152
152
 
153
- Round 3, before the lighter Claude layer (out of 10 runs):
154
-
155
- | Task | Empty folder | Project files | + CLI + harness |
156
- | --- | --- | --- | --- |
157
- | Writes a valid component spec | 0 | 9 | 10 |
158
- | Uses design-system components | 0 | 9 | 10 |
159
- | Uses tokens only, no literal colors | 0 | 10 | 10 |
160
- | Finds a real extra defect in a QA review | 0 | 9 | 10 |
161
-
162
- - The CLI makes authoring **21–32% cheaper** than files alone, and writes the same 8 files every run (round 3).
163
- - Round 5 (SB-0114) cut the harness's always-on context and reran the full setup. Evidence-backed findings per QA report rose from **4.0 to 5.6** (Sonnet) and **5.2 to 6.2** (Opus) over the CLI-only setup, with QA cost **−7% / +13%** against it. Every task now sits within +19% of that setup. Before the cut, the same harness added +66–68% to QA cost. Round 5 also recalibrated the scorer, so its numbers are not directly comparable with round 3's 3.8 → 5.0.
164
- - A bare model matched it on whether the page works, keyboard use and the planted defects, so the harness's value is conformance and evidence, not raw capability.
165
- - **What this does not show:** no comparison with other design systems, one component and one page, 10 runs per setup, and scorers written by the project. Read gaps as direction. Full report: [docs/research/value-benchmark/SUMMARY.md](./docs/research/value-benchmark/SUMMARY.md).
166
-
167
- **Does it install and upgrade safely?** From a packed tarball in an empty folder, `init`, `status`, `doctor`, `check`, `add`, `remove`, `upgrade` and repair all pass, with 100 of 100 behavior tests and 168 harness tests passing. Adopting into an existing app changes one line of its `package.json`. A team's own `.claude/` settings survive the install. In a hand-run Claude Code session, the installed rules made Claude decline an edit to a generated file and a rewrite of an accepted decision, and name the supported route instead. [Retest report](./docs/research/cli-distribution-retest-2/README.md).
168
-
169
- **Does the output match its reference?** Each of the 38 components (35 core and 3 more) has a parity audit: a read-only comparison of its code and behavior spec against its own contract, which was drafted from shadcn/ui. [docs/parity-audits/](./docs/parity-audits/).
153
+ Browse [Evidence](https://sketchbook-docs.vercel.app/reference/evidence/) for methods and limits. Use [Status](https://sketchbook-docs.vercel.app/reference/status/) for the current component and audit counts.
170
154
 
171
155
  ## What you can do with it
172
156
 
@@ -1,6 +1,6 @@
1
1
  # Agent compatibility map
2
2
 
3
- Sketchbook's CLI, configuration, contracts, generators, Git hooks and deterministic checks run without an AI provider. The model used by an agent is separate from the agent application's instruction and tool interfaces; changing model names alone cannot port integrations. This map records integration targets, not a claim of feature parity or an exhaustive list of models.
3
+ Use this map to check how your coding tool finds project guidance, which edit hooks it can run, and what has been verified. The CLI, contracts, generators, Git hooks, and checks run without an AI provider. Compatibility depends on the client’s tools and instruction interfaces as well as the model you choose.
4
4
 
5
5
  ## Install a profile
6
6
 
package/docs/cli.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  <!-- GENERATED from harness/cli/commands by npm run build:cli-docs. Do not edit; change the command module. -->
4
4
 
5
- Deterministic half of the harness. Run `sketchbook <command>` (or `node harness/cli.mjs <command>`).
5
+ Use the Sketchbook CLI to set up your project, change its sources, and verify the outputs. Run `sketchbook help <command> --details` for the full terminal reference.
6
6
 
7
7
  ## Conventions
8
8
 
@@ -10,21 +10,21 @@ Deterministic half of the harness. Run `sketchbook <command>` (or `node harness/
10
10
  - `--details` shows full human-readable output where a terminal view is abbreviated.
11
11
  - `--json` on every command prints one envelope: `{ ok, command, changed[], warnings[], errors[{file, msg, fix}], next, data? }`.
12
12
  - Exit codes: 0 ok, 1 failed, 2 ok with flags (for example overrides kept in spec/tokens/overrides.json).
13
- - Read-only commands never write. Mutating commands say what they change; those marked "dry run" accept `--dry-run`.
13
+ - Use `--dry-run` on commands marked as supporting it to review the paths and values that would change.
14
14
  - Conventions (one registry, introspect before mutate, JSON envelope) are adapted from CLI-Anything (HKUDS, Apache-2.0, https://github.com/HKUDS/CLI-Anything); no code is used.
15
15
 
16
16
  | Global option | Meaning |
17
17
  | --- | --- |
18
- | `--json` | Print one JSON envelope instead of human output |
19
- | `--dry-run` | Show what would change without writing (mutating commands that support it) |
18
+ | `--json` | Print a structured JSON result |
19
+ | `--dry-run` | Preview file changes on supported commands |
20
20
  | `--help` | Show help for the command |
21
- | `--details` | Show the full human-readable output |
21
+ | `--details` | Show the full terminal output |
22
22
 
23
23
  ## Project
24
24
 
25
25
  ### init
26
26
 
27
- In a new or empty folder: install the core harness and any selected agent integrations. In a project: add or repair integrations (--agent), pick a starting point (--start), or set the brand.
27
+ Set up a design system from a starter, or update the setup in an existing project. Choose --agent to add guidance for your coding tools.
28
28
 
29
29
  ```
30
30
  sketchbook init [--name <value>] [--primary <value>] [--font <value>] [--radius <value>] [--density <value>] [--danger <value>] [--design <value>] [--file <value>] [--prefix <value>] [--start <starter>] [--components <a,b>] [--from <file>] [--yes] [--dir <folder>] [--adopt] [--engine <spec>] [--no-install] [--agent <profiles>] [--with <groups>] [--detach-catalog] [--dry-run] [--json]
@@ -71,7 +71,7 @@ Examples:
71
71
 
72
72
  ### status
73
73
 
74
- Show the prefix, brand summary, components by status, overrides and design sync state (read-only).
74
+ See your active brand, component counts, token overrides, and design sync status.
75
75
 
76
76
  ```
77
77
  sketchbook status [--json]
@@ -86,7 +86,7 @@ Examples:
86
86
 
87
87
  ### doctor
88
88
 
89
- Health report (read-only): starter, harness version, installed vs catalog components, kits, brands, overrides, design sync, failing checks, selected agent integrations and the commit gate. Exits like check (0 pass, 1 a check fails, 2 pass with overrides).
89
+ See what needs attention in your project. Review checks, installed files, agent profiles, and design sync. Uses the same exit codes as sketchbook check.
90
90
 
91
91
  ```
92
92
  sketchbook doctor [--json]
@@ -101,7 +101,7 @@ Examples:
101
101
 
102
102
  ### upgrade
103
103
 
104
- Update harness-owned files. In a project that runs the engine from node_modules: from the installed engine (after npm update), no --from. Elsewhere: from a newer Sketchbook folder or git URL (harness-owned in both manifests); team-owned, shared, reclassified and protected files (the manifest itself, configs, package files) are listed, never touched; writing anything needs --yes (a dry run first shows what).
104
+ Update harness-owned files from the installed engine or a newer Sketchbook source. Preview the files with --dry-run. For a folder or Git URL, use --from. Updating from that source requires --yes when files would change.
105
105
 
106
106
  ```
107
107
  sketchbook upgrade [--from <path|git-url>] [--yes] [--dry-run] [--json]
@@ -122,7 +122,7 @@ Examples:
122
122
 
123
123
  ### propagate
124
124
 
125
- Carry a Foundations or harness change to every output: rebuild the tokens and components, build the engine, sync the design file scripts (tokens and foundations), and record what the outputs were built from. --maintainer also builds Storybook and the docs site (maintainers only).
125
+ Rebuild outputs after a source change and record the build. Use --maintainer to include Storybook and the Docs site. Run the generated design scripts to carry the change into Figma.
126
126
 
127
127
  ```
128
128
  sketchbook propagate [--maintainer] [--json]
@@ -141,7 +141,7 @@ Examples:
141
141
 
142
142
  ### generate
143
143
 
144
- Rebuild every generated output from the spec: token CSS, component tokens, component styles, the barrel, brand CSS and the token interface (what npm run generate runs in a project).
144
+ Rebuild tokens, styles, and other generated outputs from your project sources. Run npm run generate in an initialized project for the same build.
145
145
 
146
146
  ```
147
147
  sketchbook generate [--json]
@@ -156,7 +156,7 @@ Examples:
156
156
 
157
157
  ### prefix
158
158
 
159
- Rename the element and CSS prefix everywhere (sources, contracts, tests, docs), rebuild, then check.
159
+ Change the element and CSS prefix across your project, then rebuild and check the outputs.
160
160
 
161
161
  ```
162
162
  sketchbook prefix <new> [--dry-run] [--json]
@@ -175,7 +175,7 @@ Examples:
175
175
 
176
176
  ### swap
177
177
 
178
- Replace an adapter (token build or design tool) without touching the spec, then rebuild and check.
178
+ Change the tool that builds tokens or syncs your design file, then rebuild and check.
179
179
 
180
180
  ```
181
181
  sketchbook swap <output> <adapter> [--file <id>] [--dry-run] [--json]
@@ -201,7 +201,7 @@ Examples:
201
201
 
202
202
  ### add
203
203
 
204
- Install a component from the catalog (contract, code, stories, specs; dependencies first), or --blank to scaffold a new contract (status draft, proposed decision).
204
+ Install a catalog component with its dependencies, or start a new contract with --blank.
205
205
 
206
206
  ```
207
207
  sketchbook add <Component Name...> [--blank] [--dry-run] [--json]
@@ -225,7 +225,7 @@ Examples:
225
225
 
226
226
  ### remove
227
227
 
228
- Uninstall a component: refuses while another component or a kit needs it, and without --yes when it is team-made or customized; else removes its files, sets the registry to planned and rebuilds.
228
+ Remove a component you no longer use. Review dependencies and local edits before removing it.
229
229
 
230
230
  ```
231
231
  sketchbook remove <Component Name...> [--yes] [--dry-run] [--json]
@@ -249,7 +249,7 @@ Examples:
249
249
 
250
250
  ### list
251
251
 
252
- List catalog components (installed or available) with what each needs, plus template kits (read-only).
252
+ Browse installed and available components and see which dependencies they need.
253
253
 
254
254
  ```
255
255
  sketchbook list [--installed] [--available] [--json]
@@ -270,7 +270,7 @@ Examples:
270
270
 
271
271
  ### kits
272
272
 
273
- Template kits (harness/kits/index.json): list them, add one (its components come from the catalog first) or remove one (--yes when it was edited).
273
+ Browse template kits, install a kit with its components, or remove one.
274
274
 
275
275
  ```
276
276
  sketchbook kits [action] [kit...] [--yes] [--dry-run] [--json]
@@ -302,7 +302,7 @@ Examples:
302
302
 
303
303
  ### api
304
304
 
305
- The API vocabulary (spec/api.json): list every component prop, event and state against it (canonical, alias, extension), check that nothing is unregistered, explain one name, show the design-file axes and properties one component gets (figma), or the design-file practices Sketchbook adopted (practices, spec/figma-practices.json).
305
+ Look up component property, event, and state names in the shared API vocabulary.
306
306
 
307
307
  ```
308
308
  sketchbook api [action] [name] [--json]
@@ -334,7 +334,7 @@ Examples:
334
334
 
335
335
  ### tokens
336
336
 
337
- Change foundations and semantic tokens through the harness: set, preset, presets, diff, impact, add, remove, rename, import, scratch, overrides.
337
+ Set foundation values, manage semantic tokens, or trace the impact of a change.
338
338
 
339
339
  ```
340
340
  sketchbook tokens <subcommand> [args...] [--value <v>] [--light <v>] [--dark <v>] [--type <type>] [--pair <fg:bg>] [--kind <text|large-text|ui>] [--against <ref>] [--from <dtcg|css>] [--name <n>] [--only <semantic|foundation|mapped>] [--min-confidence <0.6>] [--answers <file.json>] [--all] [--yes] [--verbose] [--no-record] [--dry-run] [--json]
@@ -416,7 +416,7 @@ Examples:
416
416
 
417
417
  ### presets
418
418
 
419
- List the standards catalog: families, or one family's presets with sources (read-only).
419
+ Browse foundation presets by family, with their values and sources.
420
420
 
421
421
  ```
422
422
  sketchbook presets [family] [--json]
@@ -435,7 +435,7 @@ Examples:
435
435
 
436
436
  ### brand
437
437
 
438
- Several brands over one semantic interface: brands/<name>.brand.json; add, list, use (copy into brand.config.json and regenerate) and build (tokens.<brand>.css for each).
438
+ Add, list, or switch brands that share the same semantic token names.
439
439
 
440
440
  ```
441
441
  sketchbook brand [action] [name] [--from <current|brand>] [--yes] [--dry-run] [--json]
@@ -469,7 +469,7 @@ Examples:
469
469
 
470
470
  ### audit-css
471
471
 
472
- Audit an existing product's CSS: cluster its colors (OKLCH distance), font sizes, spacing, radii and shadows into a foundations proposal (generated/import/codebase.proposal.json).
472
+ Inspect an existing stylesheet to find recurring values and draft foundation choices.
473
473
 
474
474
  ```
475
475
  sketchbook audit-css <paths...> [--dry-run] [--json]
@@ -490,7 +490,7 @@ Examples:
490
490
 
491
491
  ### icons
492
492
 
493
- 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).
493
+ List the icons in your project or add icons from Lucide.
494
494
 
495
495
  ```
496
496
  sketchbook icons [action] [names...] [--category <category>] [--dry-run] [--json]
@@ -521,7 +521,7 @@ Examples:
521
521
 
522
522
  ### sync
523
523
 
524
- 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".
524
+ Prepare scripts to update or verify your Figma file. Record sync progress after you run the scripts. Use verify to compare a read-back with the spec, stamp to record a push or stage, and realize to write design realizations.
525
525
 
526
526
  ```
527
527
  sketchbook sync [what] [names...] [--verify] [--full] [--detail <combination>] [--url <http://localhost:6006>] [--ingest <file.json>] [--dry-run] [--json]
@@ -575,7 +575,7 @@ Examples:
575
575
 
576
576
  ### docs
577
577
 
578
- 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.
578
+ Read a component or kit’s variants, tokens, and accessibility guidance. Use --json for the design blueprint.
579
579
 
580
580
  ```
581
581
  sketchbook docs <name> [--json]
@@ -597,7 +597,7 @@ Examples:
597
597
 
598
598
  ### audit-page
599
599
 
600
- Check a complete HTML page using this design system for a level-one heading and main landmark. This static check is not a full accessibility audit.
600
+ Check a page for a level-one heading and a main landmark. This checks page structure only.
601
601
 
602
602
  ```
603
603
  sketchbook audit-page <file> [--json]
@@ -616,7 +616,7 @@ Examples:
616
616
 
617
617
  ### audit-decisions
618
618
 
619
- Compare the decision log with a trusted earlier copy or Git revision and report changes to settled entries. This read-only audit does not replace check X1.
619
+ Compare settled decisions with a trusted earlier copy or Git revision. Run sketchbook check to validate the log.
620
620
 
621
621
  ```
622
622
  sketchbook audit-decisions [baseline] [--git-ref <ref>] [--json]
@@ -639,7 +639,7 @@ Examples:
639
639
 
640
640
  ### check
641
641
 
642
- Run the deterministic checks (exit 0 pass, 1 fail, 2 pass with flagged overrides).
642
+ Check that your sources and outputs agree. Exit 0 means pass, 1 means a failure, and 2 means pass with flagged overrides.
643
643
 
644
644
  ```
645
645
  sketchbook check [--only <T1,T6>] [--fix] [--verbose] [--maintainer] [--json]
@@ -663,7 +663,7 @@ Examples:
663
663
 
664
664
  ### selftest
665
665
 
666
- Run the harness's own tests against the installed engine: they prove every check can still reject and that the CLI, starters and generators work (what npm run test:harness runs in a project).
666
+ Run the harness test suite to verify the tools that build and check your project.
667
667
 
668
668
  ```
669
669
  sketchbook selftest [--json]
@@ -677,7 +677,7 @@ Examples:
677
677
 
678
678
  ### explain
679
679
 
680
- Explain a token, CSS variable, component, tag or decision from the spec.
680
+ Trace a token to its source, find a component’s files, or look up a decision.
681
681
 
682
682
  ```
683
683
  sketchbook explain <thing...> [--json]
@@ -699,7 +699,7 @@ Examples:
699
699
 
700
700
  ### help
701
701
 
702
- List commands, or show one command's arguments, options and examples.
702
+ Find a command or look up its usage, options, and examples.
703
703
 
704
704
  ```
705
705
  sketchbook help [command] [--json]
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "Dashboard",
3
- "summary": "An overview page: a top bar, a page title with an action, view tabs, stat cards, a goal, a chart, recent activity and recent orders.",
3
+ "summary": "Give your team one place to check progress, review recent activity, and act on orders.",
4
4
  "components": [
5
5
  "sb-aspect-ratio",
6
6
  "sb-avatar",
@@ -122,7 +122,7 @@ const dashboard = (loading = false) => html`<div class="dashboard">
122
122
 
123
123
  const meta: Meta = {
124
124
  title: 'Patterns/Dashboard',
125
- parameters: { layout: 'fullscreen', controls: { disable: true } },
125
+ parameters: { docs: { description: { component: 'Give your team one place to check progress, review recent activity, and act on orders.' } }, layout: 'fullscreen', controls: { disable: true } },
126
126
  render: () => dashboard(),
127
127
  };
128
128
  export default meta;
@@ -1,6 +1,6 @@
1
1
  # Dashboard
2
2
 
3
- An overview page: a top bar, the page title with an action, view tabs, stat cards, a goal, a chart, recent activity and recent orders. States: default, loading.
3
+ Give your team one place to check progress, review recent activity, and act on orders.
4
4
 
5
5
  ## When to use
6
6
  The landing page of an app or workspace that summarizes what changed. Not a place for editing: link to the list or detail pages instead.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "dashboard",
3
3
  "title": "Dashboard",
4
- "summary": "An overview page: a top bar, a page title with an action, view tabs, stat cards, a goal, a chart, recent activity and recent orders.",
4
+ "summary": "Give your team one place to check progress, review recent activity, and act on orders.",
5
5
  "path": "src/patterns/dashboard",
6
6
  "components": [
7
7
  "aspect-ratio",
@@ -34,11 +34,11 @@
34
34
  },
35
35
  {
36
36
  "path": "src/patterns/dashboard/Dashboard.stories.ts",
37
- "hash": "11a5797c4c9189b59fbe"
37
+ "hash": "2239c4e4f1d873b03305"
38
38
  },
39
39
  {
40
40
  "path": "src/patterns/dashboard/README.md",
41
- "hash": "864acc7ce20f541cf67c"
41
+ "hash": "567a658f80560e3945c6"
42
42
  },
43
43
  {
44
44
  "path": "src/patterns/dashboard/dashboard.css",
@@ -46,7 +46,7 @@
46
46
  },
47
47
  {
48
48
  "path": "src/patterns/dashboard/pattern.json",
49
- "hash": "63cde4f28d1c141c401d"
49
+ "hash": "09d34e607ea6836480d1"
50
50
  }
51
51
  ]
52
52
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "Data table",
3
- "summary": "A list page: title and main action, search with a slash shortcut, a status filter, a selectable table, pagination, and loading and empty states.",
3
+ "summary": "Help people find orders, narrow the list by status, and select the rows they want to act on.",
4
4
  "components": [
5
5
  "sb-avatar",
6
6
  "sb-avatar-fallback",
@@ -128,7 +128,7 @@ const page = (body: unknown) => html`<main class="data-table" @keydown=${slash}>
128
128
 
129
129
  const meta: Meta = {
130
130
  title: 'Patterns/Data Table',
131
- parameters: { layout: 'fullscreen', controls: { disable: true } },
131
+ parameters: { docs: { description: { component: 'Help people find orders, narrow the list by status, and select the rows they want to act on.' } }, layout: 'fullscreen', controls: { disable: true } },
132
132
  render: () => page(html`<p role="status" class="data-table__hint">${shown(customers.length)}</p>${table(false)}${pages}`),
133
133
  };
134
134
  export default meta;
@@ -1,6 +1,6 @@
1
1
  # Data table
2
2
 
3
- A list page: title and main action, search, a status filter, a selectable table, pagination, and loading and empty states.
3
+ Help people find orders, narrow the list by status, and select the rows they want to act on.
4
4
 
5
5
  ## When to use
6
6
  Any collection people search, filter and act on in bulk: customers, orders, files. For a handful of items use the Item list from the profile kit instead.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "data-table",
3
3
  "title": "Data table",
4
- "summary": "A list page: title and main action, search with a slash shortcut, a status filter, a selectable table, pagination, and loading and empty states.",
4
+ "summary": "Help people find orders, narrow the list by status, and select the rows they want to act on.",
5
5
  "path": "src/patterns/data-table",
6
6
  "components": [
7
7
  "avatar",
@@ -38,11 +38,11 @@
38
38
  },
39
39
  {
40
40
  "path": "src/patterns/data-table/DataTable.stories.ts",
41
- "hash": "36bac8f8e53119768b2e"
41
+ "hash": "aaf2d576ed0b53013ac3"
42
42
  },
43
43
  {
44
44
  "path": "src/patterns/data-table/README.md",
45
- "hash": "1786ba4d3e0dba1d6a1f"
45
+ "hash": "ac8792b3aa3a43002c5e"
46
46
  },
47
47
  {
48
48
  "path": "src/patterns/data-table/data-table.css",
@@ -50,7 +50,7 @@
50
50
  },
51
51
  {
52
52
  "path": "src/patterns/data-table/pattern.json",
53
- "hash": "b5d5d7f18347734138e0"
53
+ "hash": "35c832acd45c642705b1"
54
54
  }
55
55
  ]
56
56
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "Docs article",
3
- "summary": "A long-form documentation page: contents sidebar, breadcrumb, typography for prose, a diagram, a code sample, a callout, a collapsible, an FAQ and previous/next links.",
3
+ "summary": "Help readers follow a guide with a contents sidebar, diagram, code sample, and links to what comes next.",
4
4
  "components": [
5
5
  "sb-accordion",
6
6
  "sb-accordion-content",
@@ -1,6 +1,6 @@
1
1
  # Docs article
2
2
 
3
- A long-form documentation page: contents sidebar, breadcrumb, prose set with Typography, a diagram, a code sample, a callout, a collapsible, an FAQ and previous/next links. States: default, right to left.
3
+ Help readers follow a guide with a contents sidebar, diagram, code sample, and links to what comes next.
4
4
 
5
5
  ## When to use
6
6
  Guides, help articles and any page that is mostly reading. Use it to check line length, line height and the heading scale with your brand.
@@ -101,7 +101,7 @@ const article = html`<div class="docs">
101
101
 
102
102
  const meta: Meta = {
103
103
  title: 'Patterns/Docs Article',
104
- parameters: { layout: 'fullscreen', controls: { disable: true } },
104
+ parameters: { docs: { description: { component: 'Help readers follow a guide with a contents sidebar, diagram, code sample, and links to what comes next.' } }, layout: 'fullscreen', controls: { disable: true } },
105
105
  render: () => article,
106
106
  };
107
107
  export default meta;
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "docs-article",
3
3
  "title": "Docs article",
4
- "summary": "A long-form documentation page: contents sidebar, breadcrumb, typography for prose, a diagram, a code sample, a callout, a collapsible, an FAQ and previous/next links.",
4
+ "summary": "Help readers follow a guide with a contents sidebar, diagram, code sample, and links to what comes next.",
5
5
  "path": "src/patterns/docs-article",
6
6
  "components": [
7
7
  "accordion",
@@ -32,11 +32,11 @@
32
32
  },
33
33
  {
34
34
  "path": "src/patterns/docs-article/DocsArticle.stories.ts",
35
- "hash": "c2018b502a8094818d8f"
35
+ "hash": "e80ea70679e0065026d0"
36
36
  },
37
37
  {
38
38
  "path": "src/patterns/docs-article/README.md",
39
- "hash": "7f36cb5f0d4f5e103bde"
39
+ "hash": "9d0bb5a1be919431e8ce"
40
40
  },
41
41
  {
42
42
  "path": "src/patterns/docs-article/docs-article.css",
@@ -44,7 +44,7 @@
44
44
  },
45
45
  {
46
46
  "path": "src/patterns/docs-article/pattern.json",
47
- "hash": "dbc2840f315f672e1d74"
47
+ "hash": "3c554edf05e9c8bb52c7"
48
48
  }
49
49
  ]
50
50
  }
@@ -1,6 +1,6 @@
1
1
  # Form states
2
2
 
3
- Every form control in its default, disabled, invalid and read-only states on one page, also in right to left.
3
+ Compare default, disabled, invalid, and read-only controls to check tokens, focus, and right-to-left layout.
4
4
 
5
5
  ## When to use
6
6
  To review a brand or token change: focus rings, border widths, contrast and spacing for all controls at once. It is a review page, not a product screen.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "Form states",
3
- "summary": "A gallery of every form control in its default, disabled, invalid and read-only states, for checking tokens, focus rings and right to left in one place.",
3
+ "summary": "Compare default, disabled, invalid, and read-only controls to check tokens, focus, and right-to-left layout.",
4
4
  "components": [
5
5
  "sb-checkbox",
6
6
  "sb-direction",
@@ -125,7 +125,7 @@ const gallery = html`<main class="form-states">
125
125
 
126
126
  const meta: Meta = {
127
127
  title: 'Patterns/Form States',
128
- parameters: { layout: 'fullscreen', controls: { disable: true } },
128
+ parameters: { docs: { description: { component: 'Compare default, disabled, invalid, and read-only controls to check tokens, focus, and right-to-left layout.' } }, layout: 'fullscreen', controls: { disable: true } },
129
129
  render: () => gallery,
130
130
  };
131
131
  export default meta;
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "form-states",
3
3
  "title": "Form states",
4
- "summary": "A gallery of every form control in its default, disabled, invalid and read-only states, for checking tokens, focus rings and right to left in one place.",
4
+ "summary": "Compare default, disabled, invalid, and read-only controls to check tokens, focus, and right-to-left layout.",
5
5
  "path": "src/patterns/form-states",
6
6
  "components": [
7
7
  "checkbox",
@@ -34,11 +34,11 @@
34
34
  },
35
35
  {
36
36
  "path": "src/patterns/form-states/FormStates.stories.ts",
37
- "hash": "b0b51ebf587b21fd89a1"
37
+ "hash": "f086df13cb85411108a1"
38
38
  },
39
39
  {
40
40
  "path": "src/patterns/form-states/README.md",
41
- "hash": "b52fb2fc480f0c6352bd"
41
+ "hash": "55a0558891d66e11c216"
42
42
  },
43
43
  {
44
44
  "path": "src/patterns/form-states/form-states.css",
@@ -46,7 +46,7 @@
46
46
  },
47
47
  {
48
48
  "path": "src/patterns/form-states/pattern.json",
49
- "hash": "88252259f19ed675a0dc"
49
+ "hash": "64566f1a9cb16592d296"
50
50
  }
51
51
  ]
52
52
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "Onboarding",
3
- "summary": "First-run screens: a setup step with progress and choices, an empty workspace with next steps, and a setting-up wait state.",
3
+ "summary": "Guide someone through their first setup, then show what to do in an empty workspace.",
4
4
  "components": [
5
5
  "sb-button",
6
6
  "sb-card",