@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
@@ -113,7 +113,7 @@ export function installed(root) {
113
113
  return { areas: areas.filter((a) => a.items.length) };
114
114
  }
115
115
  export function installedMarkdown(data) {
116
- const lines = ['# What Sketchbook installed', '', '<!-- Generated by sketchbook init when the project was created. Later changes are not reflected automatically. -->', '', 'This is the initial installation inventory. After adding, removing, restoring, or customizing files, inspect the project and run `npx sketchbook doctor` for its current status.', ''];
116
+ const lines = ['# What Sketchbook installed', '', '<!-- Generated by sketchbook init when the project was created. Later changes are not reflected automatically. -->', '', 'Use this list to see what Sketchbook set up when you created the project. Run `npx sketchbook doctor` for the current setup after changing or restoring files.', ''];
117
117
  for (const a of data.areas)
118
118
  lines.push(`## ${a.title} (${a.items.length})`, '', ...a.items.map((i) => `- **${i.name}**: ${i.what}`), '');
119
119
  return lines.join('\n');
@@ -52,8 +52,8 @@ export async function inputsHash(root) {
52
52
  }
53
53
  return h.digest('hex');
54
54
  }
55
- // What the docs site is built from: its pages and assets, the generators, the CLI reference and the brand (playground defaults).
56
- const DOCS_FILES = ['docs/cli.md', 'brand.config.json'];
55
+ // The docs build reads its pages, assets, generators, CLI reference, brand defaults and package version.
56
+ const DOCS_FILES = ['docs/cli.md', 'brand.config.json', 'package.json'];
57
57
  export async function docsInputsHash(root) {
58
58
  const files = [];
59
59
  await walk(root, 'apps/docs/content', files, /\.(json|md|html|css|js|svg|fig)$/);
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "blank",
3
3
  "title": "Blank",
4
- "for": "Teams designing every component from zero.",
4
+ "for": "Build every component yourself, starting with an empty library.",
5
5
  "foundations": null,
6
6
  "components": "none",
7
7
  "kits": "none",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "foundations",
3
3
  "title": "Foundations first",
4
- "for": "Teams settling tokens before any component: foundations, their Storybook pages and Figma variables.",
4
+ "for": "Settle your tokens first and explore them in Storybook or your design file.",
5
5
  "foundations": null,
6
6
  "components": "none",
7
7
  "kits": "none",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "from-codebase",
3
3
  "title": "From a codebase",
4
- "for": "Teams with a product: audit its CSS and propose foundations from the values it repeats; the library and kits stay as they are.",
4
+ "for": "Audit your product CSS and review proposed foundations. The library and kits are included.",
5
5
  "foundations": null,
6
6
  "components": "all",
7
7
  "kits": "all",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "import",
3
3
  "title": "Import tokens",
4
- "for": "Teams with tokens already (DTCG / Tokens Studio, CSS variables): import them; the library and kits stay.",
4
+ "for": "Bring existing tokens from DTCG, Tokens Studio, or CSS variables. The library and kits are included.",
5
5
  "foundations": null,
6
6
  "components": "all",
7
7
  "kits": "all",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "library+kits",
3
3
  "title": "Library and template kits",
4
- "for": "Product teams that need screens fast: every component plus page templates.",
4
+ "for": "Start with every component and page templates you can adapt.",
5
5
  "foundations": null,
6
6
  "components": "all",
7
7
  "kits": "all",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "library",
3
3
  "title": "Reference library",
4
- "for": "Teams that want a working library now and rebrand it later (default).",
4
+ "for": "Start with a working component library and make it yours. This is the default.",
5
5
  "foundations": null,
6
6
  "components": "all",
7
7
  "kits": "none",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "pick",
3
3
  "title": "Pick components",
4
- "for": "Teams that need a subset: the chosen components (--components a,b) and what they depend on.",
4
+ "for": "Choose the components you need with --components. Sketchbook includes their dependencies.",
5
5
  "foundations": null,
6
6
  "components": [],
7
7
  "kits": "none",
@@ -1,17 +1,11 @@
1
1
  # Getting started
2
2
 
3
- This walkthrough is for an initialized design-system project. Follow the [Quickstart](https://sketchbook-docs.vercel.app/start/quickstart/) to create a project with `@usesketchbook/cli` from npm. `init` adds the CLI as a dev dependency and writes `docs/harness.md` with the initial installation inventory.
3
+ Start in your design-system folder. Run `npx sketchbook status` to see your brand and components, then follow the steps below to make and preview your first change. To create a project, follow the [Quickstart](https://sketchbook-docs.vercel.app/start/quickstart/).
4
4
 
5
- Coding agents can use `AGENTS.md` and `AGENT-WORKFLOWS.md`. The Claude Code layer is optional, and hook coverage varies by client. Run `npx sketchbook doctor` to inspect the local setup.
6
-
7
- In JetBrains AI Assistant chat, verify that the Sketchbook rule is set to **Always** under Settings → Tools → AI Assistant → Rules; check response attachments to confirm it is included. Existing project rules are preserved during init and upgrade.
8
-
9
- For Codex, verify hook trust and activation. New projects include a subdirectory launcher that runs only the shipped adapter (allowing line-ending differences); existing or customized hook settings are preserved and may need a deliberate update. `npx sketchbook doctor` reports the recognized launcher and warns when the adapter will be skipped. The guard does not cover shell edits or settled decisions.
10
-
11
- For a design system inside an existing Git repository, Copilot hook discovery varies by workspace and client; cloud and repository-root sessions need a root hook configuration. If your team wants to enable the nested project's edit guard, see the **Copilot repository hooks for an adopted app** section in the engine package's `docs/agent-compatibility.md` for a root configuration example. Review existing hooks before adding a separate file; initialization never changes them.
5
+ Open `docs/harness.md` to see what init installed. If you selected an agent profile, run `npx sketchbook doctor` to inspect the files on disk, then confirm what your client loaded. [Agent compatibility](https://sketchbook-docs.vercel.app/concepts/agent-compatibility/)
12
6
 
13
7
  ## 1. What you are editing
14
- | You edit | It controls | Never edit (generated) |
8
+ | You edit | It controls | Sketchbook generates |
15
9
  | --- | --- | --- |
16
10
  | `brand.config.json` | every foundation (color, type, spacing, radius, density, motion …), as a preset or your own values | `spec/tokens/foundation/*` |
17
11
  | `spec/tokens/semantic/*.tokens.json` | what each color or size means, per light/dark mode | `generated/**` |
@@ -33,18 +27,21 @@ Sketchbook is a first draft: start from wherever you are, and edit or redo the d
33
27
 
34
28
  To see what your current project contains, run `npx sketchbook status`.
35
29
 
36
- ## 3. Make the foundations yours (the Foundations studio)
37
- `/foundations` in Claude Code walks through color, typography, spacing, radius, density, elevation, motion, layout grid, icons and z-index. Modes: `guided` (one question at a time, each with a recommendation), `preset` (pick a standard from the catalog), `expert` (your own values), `import` (bring tokens), `scratch` (start the foundations from zero; components keep working), `roast` (a fresh-eyes critique against the standards). `/roast-foundations` and `/import-tokens <file>` are shortcuts. Without Claude:
30
+ ## 3. Change your first foundation
31
+
32
+ Preview a primary color change and apply it when you’re ready.
33
+
38
34
  ```sh
39
- npx sketchbook tokens presets spacing
40
- npx sketchbook tokens preset spacing grid-8 --dry-run
35
+ npx sketchbook tokens set color.primary "#0F766E" --dry-run
41
36
  npx sketchbook tokens set color.primary "#0F766E"
42
- npx sketchbook tokens diff
37
+ npx sketchbook check
43
38
  ```
44
- Every change regenerates the foundation layer (color ramps in OKLCH, type and spacing scales), rebuilds `generated/css/tokens.css` and runs the checks. If a color pair fails contrast, the check names the pair and the nearest passing step. Run `npx sketchbook help tokens` for every option.
45
39
 
46
- ## 4. Look at it
47
- `npm run storybook`, then switch Mode in the toolbar. `Foundations/*` pages show each foundation; each component's page shows its contract summary, controls and every state.
40
+ If a color pair fails contrast, the check names the pair and suggests a passing step. Run `npx sketchbook tokens impact color.primary` to see what uses the color. See the [foundations guide](https://sketchbook-docs.vercel.app/guides/foundations/) for presets and other values you can change.
41
+
42
+ ## 4. See what changed
43
+
44
+ Run `npm run storybook` and open **Foundations → Color**. Switch **Mode** in the toolbar and compare how the new color is used in light and dark.
48
45
 
49
46
  ## 5. Trace any value
50
47
  ```sh
@@ -54,11 +51,11 @@ npx sketchbook explain SB-0009
54
51
  ```
55
52
 
56
53
  ## 6. Add or change a component
57
- `npx sketchbook add <name>` installs a reference component from the catalog; `npx sketchbook kits` manages page templates. To design a new one, follow `AGENT-WORKFLOWS.md` or use `/add <Name>` in Claude Code; the flow for a new component is always: contract → `npm run check` → plan → tests written first and seen failing → code → green → review → `beta`.
54
+ `npx sketchbook add <name>` installs a reference component from the catalog; `npx sketchbook kits` manages page templates. To design a new one, follow `AGENT-WORKFLOWS.md` or use `/add <Name>` in Claude Code; start with the contract and follow the project’s enabled planning and test-first gates.
58
55
 
59
56
  ## 7. Keep the design file in step
60
57
 
61
58
  Download the [example Figma file](https://sketchbook-docs.vercel.app/assets/Sketchbook.fig) to explore a reference snapshot. To sync, open your own file in Figma, connect the Figma MCP, and set the target with `npx sketchbook swap design figma --file <your file key>` or the `SKETCHBOOK_FIGMA_FILE` environment variable. Run `npx sketchbook help sync` for the workflow. Check D1 reports drift for a configured target. [Figma setup](https://sketchbook-docs.vercel.app/concepts/design-file/).
62
59
 
63
- ## 8. Swap a piece
64
- `npx sketchbook swap tokens plain` (no Style Dictionary), `npx sketchbook swap design none` (no design file). The spec doesn't change.
60
+ ## 8. Change an adapter
61
+ `npx sketchbook swap tokens plain` (no Style Dictionary), `npx sketchbook swap design none` (no design file). Both commands use your existing spec.
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "@usesketchbook/cli",
3
- "version": "0.2.1",
3
+ "version": "0.3.0",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "@usesketchbook/cli",
9
- "version": "0.2.1",
9
+ "version": "0.3.0",
10
10
  "license": "MIT",
11
11
  "dependencies": {
12
12
  "lucide-static": "1.76.0",
@@ -52,10 +52,13 @@ export function matrixOf(contract: Contract, render: (combo: Record<string, stri
52
52
  // The component's contract.md as its docs page: front matter, the typed-spec link and the
53
53
  // agents-only section are dropped. The page updates whenever the contract changes.
54
54
  export function docsFrom(markdown: string) {
55
- return markdown
55
+ const contract = markdown
56
56
  .replace(/^---[\s\S]*?---\s*/, '')
57
57
  .replace(/^# .*\n+/, '')
58
58
  .replace(/ ?Typed spec: \[contract\.json\]\(\.\/contract\.json\)\.?/, '')
59
59
  .replace(/\n## Spec for agents[\s\S]*$/, '\n')
60
60
  .trim();
61
+ return `Open a story to try the component, then use its contract below to look up behavior and accessibility.
62
+
63
+ ${contract}`;
61
64
  }
@@ -11,7 +11,7 @@ export const Page: StoryObj = {
11
11
  foundationPage({
12
12
  id: 'border-width',
13
13
  intro: html`<p>
14
- Border widths are the few line weights the system draws with: hairline borders around fields and surfaces, a thicker line for emphasis
14
+ Compare the field border with the focus ring below. Border widths are the few line weights the system draws with: hairline borders around fields and surfaces, a thicker line for emphasis
15
15
  and indicators, and the focus ring. A focus ring must stay visible next to every surface it can sit on, so it is wider than a plain border.
16
16
  </p>`,
17
17
  samples: gallery(pageTokens('border-width'), (v) => html`<div style="width:4rem;height:2.5rem;border:${v} solid var(--sb-color-foreground)"></div>`),
@@ -105,7 +105,7 @@ export const Page: StoryObj = {
105
105
  id: 'color',
106
106
  configHint: 'color',
107
107
  intro: html`<p>
108
- Color has two layers. The <strong>foundation</strong> is a set of ramps, one per hue, each running from a near-white step to a near-black one;
108
+ Switch Mode in the toolbar and compare the primary, background, and border roles. Color has two layers. The <strong>foundation</strong> is a set of ramps, one per hue, each running from a near-white step to a near-black one;
109
109
  its values are generated from the brand inputs. The <strong>semantic</strong> layer names roles (background, primary, border, ring) and
110
110
  points each one at a ramp step, separately for every mode. Components only ever use semantic or component tokens.
111
111
  </p>
@@ -19,7 +19,7 @@ export const Page: StoryObj = {
19
19
  id: 'density',
20
20
  configHint: 'density',
21
21
  intro: html`<p>
22
- Density sets how much room interactive elements take: the height of buttons, inputs and selects, and the sizes of fixed parts such as
22
+ Compare the same controls at each density. Density sets how much room interactive elements take: the height of buttons, inputs and selects, and the sizes of fixed parts such as
23
23
  switches and avatars. The foundation is a plain size scale; the semantic layer picks a step for each control size, and the density setting
24
24
  moves those picks together. Compact layouts fit more on screen, but pointer targets should stay at least 24px.
25
25
  </p>
@@ -11,7 +11,7 @@ export const Page: StoryObj = {
11
11
  foundationPage({
12
12
  id: 'elevation',
13
13
  intro: html`<p>
14
- Elevation shows that something floats above the page: menus, popovers, dialogs. Each step is a shadow; the semantic elevation tokens say
14
+ Compare the shadows across surfaces and check how clearly each surface stands out in dark mode. Elevation shows that something floats above the page: menus, popovers, dialogs. Each step is a shadow; the semantic elevation tokens say
15
15
  which step a layer uses. Shadows are hard to see on dark backgrounds, so floating surfaces also keep a border and their own background.
16
16
  </p>`,
17
17
  samples: gallery(pageTokens('elevation'), (v) => html`<div class="box" style="width:6rem;height:4rem;border-radius:var(--sb-radius-surface);box-shadow:${v}"></div>`),
@@ -19,7 +19,7 @@ export const Page: StoryObj = {
19
19
  foundationPage({
20
20
  id: 'icon-sizes',
21
21
  intro: html`<p>
22
- Icon sizes keep glyphs in proportion with the text and controls around them: the default icon sits next to body text, smaller ones go in
22
+ Compare the glyph sizes before choosing one for a control. Icon sizes keep glyphs in proportion with the text and controls around them: the default icon sits next to body text, smaller ones go in
23
23
  compact controls, larger ones stand alone. An icon that can be clicked needs a hit area larger than its glyph; the control around it
24
24
  provides that, so icon size and target size are separate decisions.
25
25
  </p>`,
@@ -28,8 +28,8 @@ export const Page: StoryObj = {
28
28
  return foundationPage({
29
29
  id: 'layout-grid',
30
30
  intro: html`<p>
31
- The layout grid divides a page into columns separated by gutters, with a margin on each side. Page sections and cards snap to whole
32
- columns, so content lines up across a screen. Below is the grid at the width of this page; resize the window to see the columns flex.
31
+ Resize the Storybook preview to see how the columns and gutters adapt. The layout grid divides a page into columns separated by gutters, with a margin on each side. Page sections and cards snap to whole
32
+ columns, so content lines up across a screen.
33
33
  </p>`,
34
34
  samples: html`${STYLE}
35
35
  <section aria-labelledby="sbf-layout">
@@ -76,9 +76,8 @@ export const Page: StoryObj = {
76
76
  return foundationPage({
77
77
  id: 'motion',
78
78
  intro: html`<p>
79
- Motion is a handful of durations and easing curves. Short durations suit small feedback (a hover, a toggle); longer ones suit larger
79
+ Press Play to compare the curves on the same movement. Motion is a handful of durations and easing curves. Short durations suit small feedback (a hover, a toggle); longer ones suit larger
80
80
  movement (a panel sliding in). Easing shapes the speed over time: things that enter slow down at the end, things that leave speed up.
81
- Press Play to compare them.
82
81
  </p>
83
82
  <p>
84
83
  People can ask their system for reduced motion. Components then drop movement and keep only the change of state; these demos do the same and
@@ -11,7 +11,7 @@ export const Page: StoryObj = {
11
11
  foundationPage({
12
12
  id: 'opacity',
13
13
  intro: html`<p>
14
- Opacity steps fade an element without changing its color: disabled controls, loading pulses, overlays. Fading lowers contrast, so a faded
14
+ Compare each opacity step against the same surface. Opacity steps fade an element without changing its color: disabled controls, loading pulses, overlays. Fading lowers contrast, so a faded
15
15
  control must still be recognisable, and text that people need to read should not rely on opacity alone.
16
16
  </p>`,
17
17
  samples: gallery(pageTokens('opacity'), (v) => html`<div class="box" style="width:4rem;height:2.5rem;position:relative"><div class="fill" style="position:absolute;inset:0;opacity:${v}"></div></div>`),
@@ -12,7 +12,7 @@ export const Page: StoryObj = {
12
12
  id: 'radius',
13
13
  configHint: 'radius',
14
14
  intro: html`<p>
15
- Radius rounds the corners of controls and surfaces. The foundation is a short scale from square to fully round; the semantic layer says
15
+ Look at the corners on the control, surface, and pill examples. Radius rounds the corners of controls and surfaces. The foundation is a short scale from square to fully round; the semantic layer says
16
16
  which step each kind of element uses (control, surface, pill), so changing the radius style restyles every component at once. Keep nested
17
17
  corners consistent: an inner corner looks right when it is the outer radius minus the padding between them.
18
18
  </p>`,
@@ -39,7 +39,7 @@ export const Page: StoryObj = {
39
39
  id: 'spacing',
40
40
  configHint: 'spacing',
41
41
  intro: html`<p>
42
- Spacing is one scale of steps built on a base unit. Every gap, padding and margin in a component comes from it, which keeps layouts on a
42
+ Compare the raw steps with the gaps and insets you use in a layout. Spacing is one scale of steps built on a base unit. Every gap, padding and margin in a component comes from it, which keeps layouts on a
43
43
  shared rhythm. Foundation step names are multiples of the base unit (step 4 is four units); semantic tokens name the job instead: control
44
44
  padding, stack gaps, insets.
45
45
  </p>`,
@@ -83,7 +83,7 @@ export const Page: StoryObj = {
83
83
  id: 'typography',
84
84
  configHint: 'typography',
85
85
  intro: html`<p>
86
- Typography is a family pair (text and code), a size scale, a few weights, line heights and letter spacing. The foundation holds the raw
86
+ Compare the body and heading roles at the same viewport width. Typography is a family pair (text and code), a size scale, a few weights, line heights and letter spacing. The foundation holds the raw
87
87
  scale; the semantic layer gives sizes jobs (body, control, heading-1 to heading-4, caption) so a component asks for "a heading" rather than
88
88
  "24px". Sizes are shown in px and in rem against the 16px browser default.
89
89
  </p>`,
@@ -18,7 +18,7 @@ export const Page: StoryObj = {
18
18
  return foundationPage({
19
19
  id: 'z-index',
20
20
  intro: html`<p>
21
- Z-index decides what covers what when elements overlap. The foundation is a few spaced numbers; the semantic layer names each layer by role
21
+ Read from the bottom of the stack to find which layers can cover a dropdown. Z-index decides what covers what when elements overlap. The foundation is a few spaced numbers; the semantic layer names each layer by role
22
22
  (dropdown, sticky header, overlay, modal, toast) so no component invents its own number. The list below runs from the bottom of the stack to
23
23
  the top.
24
24
  </p>`,
@@ -6,7 +6,7 @@ import { readFile, writeFile, mkdir, rm, cp } from 'node:fs/promises';
6
6
  import { join } from 'node:path';
7
7
  import { execFile } from 'node:child_process';
8
8
  import { promisify } from 'node:util';
9
- import { runChecks } from '../checks/run.mjs';
9
+ import { formatHuman, runChecks } from '../checks/run.mjs';
10
10
  import { compileStyles, mediaVars } from '../../scripts/build-styles.mjs';
11
11
  import { fixture, reference, ROOT, sourceRepoOnly, readJson, writeJson, must } from './helpers.mjs';
12
12
  import { parseJson } from '../lib/files.mjs';
@@ -125,6 +125,9 @@ test('generator keeps a hand edit and check flags it (exit 2)', async () => {
125
125
  assert.equal(kept.radius.md.$value, '7px');
126
126
  const r = await runChecks(dir);
127
127
  assert.equal(r.exitCode, 2);
128
+ const [summary, ...details] = formatHuman(r);
129
+ assert.equal(summary, 'All checks passed (with overrides).');
130
+ assert.match(details.join('\n'), /radius\.md/);
128
131
  assert.equal(must(r.overrides[0], 'the first override').token, 'radius.md');
129
132
  });
130
133
  test('C2 rejects state and contrast references to unknown tokens', async () => {
@@ -164,8 +164,8 @@ test('L10 interactive: prompts with current values, dry run first, applies only
164
164
  assert.match(required.text, /Required\./);
165
165
  assert.deepEqual(required.calls, [['prefix', 'acme', '--dry-run']]);
166
166
  const choices = await menu([groupIndex('tokens'), 'b', 'q']);
167
- assert.match(choices.text, /1 {2}tokens\n {6}Change foundations/);
168
- assert.match(choices.text, /2 {2}presets\n {6}List the standards catalog/);
167
+ assert.match(choices.text, /1 {2}tokens\n {6}Set foundation values/);
168
+ assert.match(choices.text, /2 {2}presets\n {6}Browse foundation presets/);
169
169
  const bad = await menu(['9', 'x', 'b', 'q']);
170
170
  assert.match(bad.text, /Type 1-/);
171
171
  assert.deepEqual(bad.calls, []);
@@ -176,6 +176,7 @@ test('L10 interactive: prompts with current values, dry run first, applies only
176
176
  assert.match(defaultCancel.text, /Not applied/);
177
177
  const apply = await menu([groupIndex('design'), commandIndex('sync'), 'tokens', '', '', 'y', 'q']);
178
178
  assert.deepEqual(apply.calls, [['sync', 'tokens', '--dry-run'], ['sync', 'tokens']]);
179
+ assert.match(apply.text, /Preview changes[\s\S]*sketchbook sync tokens --dry-run[\s\S]*Apply these changes\?\n {2}sketchbook sync tokens\n/);
179
180
  const guided = await menu([groupIndex('tokens'), commandIndex('tokens'), 'set', '', 'typography.family Inter', '', 'n', 'q']);
180
181
  assert.match(guided.text, /Arguments for set: <key> <value>/);
181
182
  assert.match(guided.text, /Example to type: typography\.family Inter/);
@@ -234,10 +235,10 @@ test('project commands identify the nearest ancestor project without executing f
234
235
  assert.equal(result.code, 1);
235
236
  const fix = must(must(result.json, 'JSON envelope').errors[0], 'an error').fix ?? '';
236
237
  assert.ok(fix.includes(project), fix);
237
- assert.match(fix, /Change directory to the project root/);
238
+ assert.match(fix, /Change directory to .*Sketchbook resolves file paths from the project root/s);
238
239
  }
239
240
  const human = cli(nested, 'status');
240
- assert.match(human.err, /Change directory to the project root/);
241
+ assert.match(human.err, /Change directory to .*Sketchbook resolves file paths from the project root/s);
241
242
  assert.ok(human.err.includes(project));
242
243
  assert.equal((await readFile(join(project, 'harness.config.json'), 'utf8')), '{}');
243
244
  }
@@ -257,7 +258,7 @@ test('L13 generate rebuilds every generated output from the spec (what a project
257
258
  assert.deepEqual((await runChecks(dir, { only: ['G1'] })).results[0]?.errors, []);
258
259
  await rm(dir, { recursive: true });
259
260
  });
260
- test('terminal presentation abbreviates lists without changing pipes or JSON', async () => {
261
+ test('terminal presentation shows concise help and respects pipes, NO_COLOR, and JSON', async () => {
261
262
  const dir = await reference();
262
263
  const run = async (args, human) => {
263
264
  let out = '';
@@ -268,6 +269,24 @@ test('terminal presentation abbreviates lists without changing pipes or JSON', a
268
269
  const help = await run(['help'], true);
269
270
  assert.match(help.out, /SKETCHBOOK/);
270
271
  assert.match(help.out, /help --details/);
272
+ const short = await run(['help', 'init'], true);
273
+ assert.match(short.out, /Usage[\s\S]*sketchbook init[\s\S]*Try:/);
274
+ assert.doesNotMatch(short.out, /\nOptions:/);
275
+ const detailed = await run(['help', 'init', '--details'], true);
276
+ assert.match(detailed.out, /Options:[\s\S]*--adopt[\s\S]*Examples:/);
277
+ const saved = process.env.NO_COLOR;
278
+ try {
279
+ process.env.NO_COLOR = '';
280
+ const noColor = await run(['help', 'init'], true);
281
+ assert.match(noColor.out, /SKETCHBOOK/);
282
+ assert.equal(noColor.out.includes('\x1b['), false);
283
+ }
284
+ finally {
285
+ if (saved === undefined)
286
+ delete process.env.NO_COLOR;
287
+ else
288
+ process.env.NO_COLOR = saved;
289
+ }
271
290
  const brief = await run(['list'], true);
272
291
  const full = await run(['list', '--details'], true);
273
292
  assert.match(brief.out, /more\. Use sketchbook list --details/);
@@ -281,4 +300,5 @@ test('terminal presentation abbreviates lists without changing pipes or JSON', a
281
300
  assert.equal(error.code, 1);
282
301
  assert.match(error.err, /Unknown command/);
283
302
  assert.match(error.err, /Next/);
303
+ await rm(dir, { recursive: true });
284
304
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@usesketchbook/cli",
3
- "version": "0.2.1",
3
+ "version": "0.3.0",
4
4
  "description": "Provider-neutral harness for building an accessible, white-label Web Components design system from a spec.",
5
5
  "type": "module",
6
6
  "publishConfig": {