@usesketchbook/cli 0.2.0 → 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 +15 -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
@@ -5,7 +5,7 @@ const why = (r) => (r.reason === 'team-made' ? 'made by the team, not in the cat
5
5
  export default {
6
6
  name: 'remove',
7
7
  group: 'components',
8
- summary: '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.',
8
+ summary: 'Remove a component you no longer use. Review dependencies and local edits before removing it.',
9
9
  args: [{ name: 'Component Name', required: true, variadic: true, description: 'Installed component (button, "Button Group")' }],
10
10
  options,
11
11
  examples: ['sketchbook remove badge', 'sketchbook remove spinner --dry-run', 'sketchbook remove my-widget --yes'],
@@ -21,12 +21,14 @@ export default {
21
21
  out(`Needs --yes: ${name} is ${why(risk)}.`);
22
22
  return { changed: r.changed, data: { removed: [name], atRisk: r.atRisk } };
23
23
  }
24
- out(`Removed ${name} (${r.changed.length - 1} file(s)); registry -> planned; tokens, styles and barrel rebuilt.`);
24
+ out(`Removed ${name}. Rebuilt the token and style outputs and set its registry status to planned.`);
25
25
  const c = await componentChecks(root);
26
26
  out(`Checks: ${c.summary}`);
27
27
  const next = !risk ? `sketchbook add ${name} brings it back from the catalog.`
28
28
  : risk.reason === 'team-made' ? `${name} was not in the catalog: git is the only way back (git checkout -- the removed files).`
29
29
  : `sketchbook add ${name} brings back the catalog version; your edits are only in git.`;
30
+ if (!c.exitCode)
31
+ out(`Next: ${next}`);
30
32
  return { changed: r.changed, errors: c.errors, warnings: c.warnings, exitCode: c.exitCode, next, data: { removed: [name], atRisk: r.atRisk } };
31
33
  },
32
34
  };
@@ -5,7 +5,7 @@ import { HARNESS } from '../../lib/files.mjs';
5
5
  export default {
6
6
  name: 'selftest',
7
7
  group: 'quality',
8
- summary: '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).',
8
+ summary: 'Run the harness test suite to verify the tools that build and check your project.',
9
9
  args: [],
10
10
  options: {},
11
11
  examples: ['sketchbook selftest'],
@@ -35,7 +35,7 @@ export async function designState(root, config) {
35
35
  const status = {
36
36
  name: 'status',
37
37
  group: 'project',
38
- summary: 'Show the prefix, brand summary, components by status, overrides and design sync state (read-only).',
38
+ summary: 'See your active brand, component counts, token overrides, and design sync status.',
39
39
  args: [],
40
40
  options: {},
41
41
  examples: ['sketchbook status', 'sketchbook status --json'],
@@ -61,9 +61,9 @@ const status = {
61
61
  };
62
62
  if (human) {
63
63
  const ui = presentation(true);
64
- out(`${ui.section('Overview')}\n ${data.brand.name} · ${data.prefix} · ${data.components.total} components\n`);
64
+ out(`${ui.section('Project')}\n ${data.brand.name} · ${data.prefix} · ${data.components.total} components\n`);
65
65
  out(`${ui.section('Brand')}\n Primary ${data.brand.primary} · ${data.brand.font} · ${data.brand.modes.join(' / ')}\n Spacing ${show(data.brand.spacingBase)}px · Radius ${data.brand.radiusLg}px · ${data.brand.contrast}\n`);
66
- out(`${ui.section('Health')}\n ${Object.entries(byStatus).map(([s, n]) => `${n} ${s}`).join(' · ')} · ${data.overrides} overrides\n Design: ${design.tool ?? 'none'}${design.tool ? ` · tokens ${design.tokens} · ${design.components.synced} synced${design.components.stale.length ? ` · stale: ${design.components.stale.join(', ')}` : ''}${design.patterns.total ? ` · ${design.patterns.checked}/${design.patterns.total} pattern docs checked` : ''}` : ''}`);
66
+ out(`${ui.section('Components and sync')}\n ${Object.entries(byStatus).map(([s, n]) => `${n} ${s}`).join(' · ')} · ${data.overrides} overrides\n Design: ${design.tool ?? 'none'}${design.tool ? ` · tokens ${design.tokens} · ${design.components.synced} synced${design.components.stale.length ? ` · stale: ${design.components.stale.join(', ')}` : ''}${design.patterns.total ? ` · ${design.patterns.checked}/${design.patterns.total} pattern docs checked` : ''}` : ''}`);
67
67
  }
68
68
  else {
69
69
  out(`Prefix: ${data.prefix}`);
@@ -72,7 +72,9 @@ const status = {
72
72
  out(`Overrides: ${data.overrides}${data.overrides ? ' (spec/tokens/overrides.json)' : ''}`);
73
73
  out(`Design: ${design.tool ?? 'none'}${design.tool ? `, tokens ${design.tokens}, ${design.components.synced} component(s) synced${design.components.stale.length ? `, stale: ${design.components.stale.join(', ')}` : ''}${design.patterns.total ? `, ${design.patterns.checked} of ${design.patterns.total} pattern docs checked` : ''}` : ''}`);
74
74
  }
75
- const next = design.tokens === 'changed since last sync' || design.components.stale.length ? 'sketchbook sync tokens (or components <names>)' : 'sketchbook check';
75
+ const next = design.tokens === 'changed since last sync' || design.components.stale.length ? 'Run sketchbook sync tokens for token changes or sketchbook sync components <batch> for component changes.' : 'sketchbook check';
76
+ if (human)
77
+ out(`\nNext: ${next === 'sketchbook check' ? 'Run sketchbook check to verify the project.' : next}`);
76
78
  return { data, next };
77
79
  },
78
80
  };
@@ -4,7 +4,7 @@ const options = { file: { type: 'string', value: 'id', description: 'Design file
4
4
  export default {
5
5
  name: 'swap',
6
6
  group: 'project',
7
- summary: 'Replace an adapter (token build or design tool) without touching the spec, then rebuild and check.',
7
+ summary: 'Change the tool that builds tokens or syncs your design file, then rebuild and check.',
8
8
  args: [
9
9
  { name: 'output', required: true, description: `What to swap: ${Object.keys(SWAPPABLE).join(' | ')}` },
10
10
  { name: 'adapter', required: true, description: `tokens: ${(SWAPPABLE.tokens ?? []).join(' | ')}; design: ${(SWAPPABLE.design ?? []).join(' | ')}` },
@@ -26,7 +26,7 @@ async function verify({ root, options, dryRun, out, file }) {
26
26
  }
27
27
  const written = await prepareVerify(root, { detail: options.detail });
28
28
  const next = `Run ${written} with the Figma MCP use_figma tool, save the returned JSON (e.g. figma-verify.json), then: sketchbook sync verify --ingest figma-verify.json. A differing combination is located with sketchbook sync verify --detail "<combination>".`;
29
- out(`Prepared for Figma file ${file}:\n ${written}\nNext: ${next}`);
29
+ out(`Prepared a verification script for Figma file ${file}:\n ${written}\nNext: ${next}`);
30
30
  return { changed: [written], next };
31
31
  }
32
32
  let readback;
@@ -59,7 +59,7 @@ async function verify({ root, options, dryRun, out, file }) {
59
59
  export default {
60
60
  name: 'sync',
61
61
  group: 'design',
62
- summary: '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".',
62
+ summary: '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.',
63
63
  args: [
64
64
  { name: 'what', required: false, description: 'tokens (default) | verify | stamp | progress | describe | verify-library | layout | theme-matrix | components | patterns | compare | realize' },
65
65
  { name: 'names', required: false, variadic: true, description: '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)' },
@@ -188,7 +188,7 @@ export default {
188
188
  const { written, skipped, delta, coverage } = await prepare(root, what, { full: options.full, names: args.slice(1), detail: options.detail });
189
189
  if (what === 'library' && skipped.length)
190
190
  out(`Tokens without a Figma variable or style (left unbound): ${skipped.map((s) => (typeof s === 'string' ? s : s.token)).join(', ')}`);
191
- out(`Prepared for Figma file ${file}${delta ? ' (only what changed since the last stamp; --full for everything)' : ''}:\n ${written.join('\n ')}${coverage.total ? `\nCoverage: ${coverage.total - coverage.missing.length} of ${coverage.total} spec tokens reach the file${coverage.missing.length ? ` (missing: ${coverage.missing.slice(0, 10).join(', ')}${coverage.missing.length > 10 ? ' ...' : ''})` : ''}.` : ''}\nNext: ${next}`);
191
+ out(`Prepared ${what} scripts for Figma file ${file}${delta ? ' (changes since the last stamp, or use --full for all inputs)' : ''}:\n ${written.join('\n ')}${coverage.total ? `\nCoverage: ${coverage.total - coverage.missing.length} of ${coverage.total} spec tokens reach the file${coverage.missing.length ? ` (missing: ${coverage.missing.slice(0, 10).join(', ')}${coverage.missing.length > 10 ? ' ...' : ''})` : ''}.` : ''}\nNext: ${next}`);
192
192
  return { changed: written, next, warnings: coverage.missing.length ? [{ file: 'spec/tokens', msg: `${coverage.missing.length} token(s) do not reach the design file`, fix: 'Map their kind in harness/adapters/design/figma/variables.mts.' }] : [], data: { file, skipped: skipped.length, coverage } };
193
193
  },
194
194
  };
@@ -42,10 +42,6 @@ const watchOutOf = (diff, imp) => {
42
42
  // stage with the token checks, apply only when they pass, and propose an SB record only when a file changed.
43
43
  async function mutate(ctx, plan, next) {
44
44
  const { root, dryRun, out, json, options } = ctx;
45
- for (const s of plan.summary)
46
- out(s);
47
- for (const w of plan.warnings)
48
- out(`warning: ${w}`);
49
45
  const stale = await staleLinks(root);
50
46
  if (stale.length && !options.yes) {
51
47
  return {
@@ -57,6 +53,11 @@ async function mutate(ctx, plan, next) {
57
53
  if (stale.length)
58
54
  out(`--yes: the brand links overwrite ${stale.length} hand-edited value(s): ${stale.join('; ')}`);
59
55
  const r = await runPlan(root, plan, { dryRun, check: (dir) => runChecks(dir, { only: TOKEN_CHECKS }) });
56
+ out(r.failed ? 'Token change stopped before writing files.' : dryRun ? `Preview: ${r.changed.length} files would change.` : r.changed.length ? `Updated ${r.changed.length} files.` : 'Your token files already match this change.');
57
+ for (const s of plan.summary)
58
+ out(s);
59
+ for (const w of plan.warnings)
60
+ out(`Warning: ${w}`);
60
61
  out(formatDiff(r.diff).join('\n'));
61
62
  const imp = r.failed ? { semantic: [], components: [] } : await impactOfDiff(root, r.diff);
62
63
  if (imp.semantic.length)
@@ -86,16 +87,16 @@ async function mutate(ctx, plan, next) {
86
87
  return { changed: [], warnings, errors: r.errors, exitCode: 1, data: { ...data, dryRun, applied: false, wouldChange: r.changed }, next: 'Fix the change (each error names its fix), then run it again.' };
87
88
  }
88
89
  if (dryRun) {
89
- out(`(dry run: nothing written; ${r.changed.length} file(s) would change)`);
90
90
  return { changed: r.changed, warnings, data: { ...data, dryRun: true }, next: 'Run the same command without --dry-run to apply it.' };
91
91
  }
92
- if (!r.changed.length)
93
- out('Nothing changed: the files already say this.');
94
92
  let decision = null;
95
93
  if (plan.decision && !options['no-record'] && r.changed.length) {
96
94
  decision = await proposeDecision(root, { section: 'Theme', title: plan.decision.title, context: 'PROPOSAL: what prompted the change (roast finding, brand, product need).', decision: plan.decision.decision, why: 'PROPOSAL: the trade-off accepted, with the standard\'s source link.', watchOut: watchOutOf(r.diff, imp) });
97
95
  out(`Proposed decision ${decision} in ${DECISIONS} (fill the PROPOSAL parts; set accepted when agreed).`);
98
96
  }
97
+ const followUp = next ?? 'Review the change in Storybook under Foundations.';
98
+ if (r.changed.length)
99
+ out(`Next: ${followUp}`);
99
100
  return {
100
101
  changed: [...r.changed, ...(decision ? [DECISIONS] : [])], warnings, errors: [], exitCode: 0,
101
102
  data: { ...data, decision },
@@ -321,7 +322,7 @@ export const findSub = (name) => SUBCOMMANDS.find((s) => s.name === name);
321
322
  export default {
322
323
  name: 'tokens',
323
324
  group: 'tokens',
324
- summary: 'Change foundations and semantic tokens through the harness: set, preset, presets, diff, impact, add, remove, rename, import, scratch, overrides.',
325
+ summary: 'Set foundation values, manage semantic tokens, or trace the impact of a change.',
325
326
  args: [
326
327
  { name: 'subcommand', required: true, description: SUBCOMMANDS.map((s) => s.name).join(' | ') },
327
328
  { name: 'args', required: false, variadic: true, description: 'The subcommand\'s arguments (see below)' },
@@ -11,7 +11,7 @@ const options = {
11
11
  export default {
12
12
  name: 'upgrade',
13
13
  group: 'project',
14
- summary: '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).',
14
+ summary: '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.',
15
15
  args: [],
16
16
  options,
17
17
  examples: ['sketchbook upgrade --from ../sketchbook --dry-run', 'sketchbook upgrade --from ../sketchbook --yes', 'sketchbook upgrade --from https://example.com/sketchbook.git --dry-run'],
@@ -44,6 +44,7 @@ export default {
44
44
  out(`Blocked agent setup paths (kept): ${r.skipped.join(', ')}`);
45
45
  if (!r.skipped.length && !r.added.length && !r.updated.length && !hooks.length)
46
46
  out('The harness-owned files here already match the installed engine.');
47
+ out(dryRun ? 'Next: Review these paths, then run sketchbook upgrade to apply the update.' : 'Next: Run sketchbook check to verify the project.');
47
48
  return { changed: [...r.added, ...r.updated, ...(hooks.length && r.hookSettings ? [r.hookSettings] : []), ...(dryRun ? [] : ['harness.config.json'])], warnings: r.skipped.map((file) => ({ file, msg: 'Existing path blocks agent setup.', fix: 'Review the path and run sketchbook init.' })), data: { version: { before, after: version }, ...r }, next: dryRun ? 'sketchbook upgrade' : 'sketchbook check' };
48
49
  }
49
50
  if (!options.from)
@@ -63,8 +64,11 @@ export default {
63
64
  const globs = Object.entries(r.manifest).flatMap(([k, d]) => [...d.added.map((g) => `${k} + ${g}`), ...d.removed.map((g) => `${k} - ${g}`)]);
64
65
  section('Upstream harness/manifest.json differs (not applied; merge by hand what you agree with)', globs);
65
66
  const data = { version: r.version, commit: r.commit, update: r.update, add: r.add, removedUpstream: r.removedUpstream, teamDiffers: r.teamDiffers, sharedDiffers: r.sharedDiffers, upstreamOnly: r.upstreamOnly, reclassified: r.reclassified, protected: r.protected, manifest: r.manifest };
66
- if (dryRun)
67
- return { changed: [...r.update, ...r.add], data, next: `sketchbook upgrade --from ${options.from}${r.update.length + r.add.length ? ' --yes' : ''}` };
67
+ if (dryRun) {
68
+ const next = `sketchbook upgrade --from ${options.from}${r.update.length + r.add.length ? ' --yes' : ''}`;
69
+ out('Next: Review the listed files, then rerun with the same --from value and --yes to apply updates.');
70
+ return { changed: [...r.update, ...r.add], data, next };
71
+ }
68
72
  const next = r.sharedDiffers.includes('package.json') ? 'Merge package.json by hand, npm install, then npm run check.' : 'npm run check, then npm run test:harness';
69
73
  // The checks are the code just written: they run only when the upstream was confirmed with --yes.
70
74
  if (!options.yes) {
@@ -10,7 +10,7 @@ export function cliDocs() {
10
10
  '',
11
11
  '<!-- GENERATED from harness/cli/commands by npm run build:cli-docs. Do not edit; change the command module. -->',
12
12
  '',
13
- 'Deterministic half of the harness. Run `sketchbook <command>` (or `node harness/cli.mjs <command>`).',
13
+ '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.',
14
14
  '',
15
15
  '## Conventions',
16
16
  '',
@@ -18,7 +18,7 @@ export function cliDocs() {
18
18
  '- `--details` shows full human-readable output where a terminal view is abbreviated.',
19
19
  '- `--json` on every command prints one envelope: `{ ok, command, changed[], warnings[], errors[{file, msg, fix}], next, data? }`.',
20
20
  '- Exit codes: 0 ok, 1 failed, 2 ok with flags (for example overrides kept in spec/tokens/overrides.json).',
21
- '- Read-only commands never write. Mutating commands say what they change; those marked "dry run" accept `--dry-run`.',
21
+ '- Use `--dry-run` on commands marked as supporting it to review the paths and values that would change.',
22
22
  '- 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.',
23
23
  '',
24
24
  '| Global option | Meaning |',
@@ -77,7 +77,7 @@ export async function interactive({ root = process.cwd(), input = process.stdin,
77
77
  try {
78
78
  if (ui.enabled)
79
79
  write(ui.header('explore'));
80
- write(`${line(' Explore your design system, one step at a time.')}\n Choose a number and press Enter. Type q and press Enter to quit.\n`);
80
+ write(`${line(' Choose what you want to do in your design system.')}\n Choose a number and press Enter. Type q and press Enter to quit.\n`);
81
81
  for (;;) {
82
82
  const groups = Object.entries(GROUPS).map(([g, label]) => ({ g, label, list: commands().filter((c) => c.group === g) })).filter((x) => x.list.length);
83
83
  const group = await choose('Groups:', groups.map((x) => ({ label: `${x.label.padEnd(12)} ${x.list.length} ${x.list.length === 1 ? 'command' : 'commands'}`, value: x })), 'q) quit');
@@ -121,31 +121,31 @@ export async function interactive({ root = process.cwd(), input = process.stdin,
121
121
  break;
122
122
  }
123
123
  }
124
- const configure = Object.keys(cmd.options).length > 0 && await confirm('Configure optional settings?', 'review options', 'use defaults');
124
+ const configure = Object.keys(cmd.options).length > 0 && await confirm('Review optional settings?', 'review options', 'continue with defaults');
125
125
  if (configure)
126
126
  for (const [k, o] of Object.entries(cmd.options)) {
127
- const hint = current[k] !== undefined ? ` [current: ${current[k]}; Enter keeps it]` : ' [Enter skips]';
127
+ const hint = current[k] !== undefined ? ` [current: ${current[k]}, Enter keeps it]` : ' [Enter skips]';
128
128
  if (o.type === 'boolean') {
129
129
  if (await confirm(`--${k}: ${o.description}`, 'enable', 'leave off'))
130
130
  argv.push(`--${k}`);
131
131
  continue;
132
132
  }
133
133
  const example = o.value && /^(?:https?:\/\/\S+|\d+(?:\.\d+)?)$/.test(o.value) ? `\n Example to type: ${o.value}` : '';
134
- const v = await ask(`\n --${k}: ${brief(o.description)}${hint}${example}\n Value: `);
134
+ const v = await ask(`\n --${k}: ${brief(o.description)}${hint}${example}\n Enter a value: `);
135
135
  if (v)
136
136
  argv.push(`--${k}`, v);
137
137
  }
138
138
  // Display a shell-safe command for people who want to repeat it.
139
139
  const shown = `sketchbook ${argv.map((x) => (/^[a-zA-Z0-9_./:=@+-]+$/.test(x) ? x : `'${x.replace(/'/g, `'\\''`)}'`)).join(' ')}`;
140
140
  if (cmd.mutates && cmd.dryRun) {
141
- write(`\n${heading('Preview · no files will be changed')}\n ${shown} --dry-run\n\n`);
141
+ write(`\n${heading('Preview changes')}\n ${shown} --dry-run\n\n`);
142
142
  last = await run([...argv, '--dry-run'], { root, stdout: write, stderr: write, human: ui.enabled });
143
143
  if (last === 1) {
144
- write('The dry run failed; nothing was changed.\n');
144
+ write('The dry run failed. Review the message above and try again.\n');
145
145
  continue;
146
146
  }
147
- if (!await confirm('Apply these changes?', 'apply changes', 'cancel without applying')) {
148
- write(`\n ${ui.warning('Not applied.')} No files were changed.\n`);
147
+ if (!await confirm(`Apply these changes?\n ${shown}`, 'apply changes', 'cancel without applying')) {
148
+ write(`\n ${ui.warning('Not applied.')} Your files are as they were before the preview.\n`);
149
149
  continue;
150
150
  }
151
151
  }
@@ -153,9 +153,9 @@ export async function interactive({ root = process.cwd(), input = process.stdin,
153
153
  write(`\n ${ui.warning('Not run.')} No files were changed.\n`);
154
154
  continue;
155
155
  }
156
- write(`\n${heading('Running')}\n Running: ${shown}\n\n`);
156
+ write(`\nRunning: ${shown}\n\n`);
157
157
  last = await run(argv, { root, stdout: write, stderr: write, human: ui.enabled });
158
- write(`\n${heading(last === 0 ? ui.success('Done') : ui.warning(last === 2 ? 'Done with notices' : 'Command failed'))} ${note(`exit ${last}`)}\n`);
158
+ write(`\n${heading(last === 0 ? ui.success('Command completed') : ui.warning(last === 2 ? 'Command completed with overrides' : 'Command failed'))} ${note(`exit ${last}`)}\n`);
159
159
  }
160
160
  }
161
161
  catch (e) {
@@ -11,40 +11,40 @@
11
11
  ],
12
12
  "commands": {
13
13
  "init": {
14
- "summary": "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."
14
+ "summary": "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."
15
15
  },
16
16
  "status": {
17
- "summary": "Show the prefix, brand summary, components by status, overrides and design sync state (read-only)."
17
+ "summary": "See your active brand, component counts, token overrides, and design sync status."
18
18
  },
19
19
  "doctor": {
20
- "summary": "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)."
20
+ "summary": "See what needs attention in your project. Review checks, installed files, agent profiles, and design sync. Uses the same exit codes as sketchbook check."
21
21
  },
22
22
  "upgrade": {
23
- "summary": "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)."
23
+ "summary": "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."
24
24
  },
25
25
  "propagate": {
26
- "summary": "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)."
26
+ "summary": "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."
27
27
  },
28
28
  "generate": {
29
- "summary": "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)."
29
+ "summary": "Rebuild tokens, styles, and other generated outputs from your project sources. Run npm run generate in an initialized project for the same build."
30
30
  },
31
31
  "prefix": {
32
- "summary": "Rename the element and CSS prefix everywhere (sources, contracts, tests, docs), rebuild, then check."
32
+ "summary": "Change the element and CSS prefix across your project, then rebuild and check the outputs."
33
33
  },
34
34
  "swap": {
35
- "summary": "Replace an adapter (token build or design tool) without touching the spec, then rebuild and check."
35
+ "summary": "Change the tool that builds tokens or syncs your design file, then rebuild and check."
36
36
  },
37
37
  "add": {
38
- "summary": "Install a component from the catalog (contract, code, stories, specs; dependencies first), or --blank to scaffold a new contract (status draft, proposed decision)."
38
+ "summary": "Install a catalog component with its dependencies, or start a new contract with --blank."
39
39
  },
40
40
  "remove": {
41
- "summary": "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."
41
+ "summary": "Remove a component you no longer use. Review dependencies and local edits before removing it."
42
42
  },
43
43
  "list": {
44
- "summary": "List catalog components (installed or available) with what each needs, plus template kits (read-only)."
44
+ "summary": "Browse installed and available components and see which dependencies they need."
45
45
  },
46
46
  "kits": {
47
- "summary": "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).",
47
+ "summary": "Browse template kits, install a kit with its components, or remove one.",
48
48
  "subcommands": [
49
49
  "list",
50
50
  "add",
@@ -52,7 +52,7 @@
52
52
  ]
53
53
  },
54
54
  "tokens": {
55
- "summary": "Change foundations and semantic tokens through the harness: set, preset, presets, diff, impact, add, remove, rename, import, scratch, overrides.",
55
+ "summary": "Set foundation values, manage semantic tokens, or trace the impact of a change.",
56
56
  "subcommands": [
57
57
  "rebuild",
58
58
  "set",
@@ -69,10 +69,10 @@
69
69
  ]
70
70
  },
71
71
  "presets": {
72
- "summary": "List the standards catalog: families, or one family's presets with sources (read-only)."
72
+ "summary": "Browse foundation presets by family, with their values and sources."
73
73
  },
74
74
  "brand": {
75
- "summary": "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).",
75
+ "summary": "Add, list, or switch brands that share the same semantic token names.",
76
76
  "subcommands": [
77
77
  "add",
78
78
  "list",
@@ -81,7 +81,7 @@
81
81
  ]
82
82
  },
83
83
  "icons": {
84
- "summary": "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).",
84
+ "summary": "List the icons in your project or add icons from Lucide.",
85
85
  "subcommands": [
86
86
  "list",
87
87
  "add",
@@ -89,7 +89,7 @@
89
89
  ]
90
90
  },
91
91
  "api": {
92
- "summary": "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).",
92
+ "summary": "Look up component property, event, and state names in the shared API vocabulary.",
93
93
  "subcommands": [
94
94
  "list",
95
95
  "check",
@@ -99,16 +99,16 @@
99
99
  ]
100
100
  },
101
101
  "audit-css": {
102
- "summary": "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)."
102
+ "summary": "Inspect an existing stylesheet to find recurring values and draft foundation choices."
103
103
  },
104
104
  "audit-page": {
105
- "summary": "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."
105
+ "summary": "Check a page for a level-one heading and a main landmark. This checks page structure only."
106
106
  },
107
107
  "audit-decisions": {
108
- "summary": "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."
108
+ "summary": "Compare settled decisions with a trusted earlier copy or Git revision. Run sketchbook check to validate the log."
109
109
  },
110
110
  "sync": {
111
- "summary": "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\".",
111
+ "summary": "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.",
112
112
  "subcommands": [
113
113
  "tokens",
114
114
  "pages",
@@ -132,19 +132,19 @@
132
132
  ]
133
133
  },
134
134
  "docs": {
135
- "summary": "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."
135
+ "summary": "Read a component or kit’s variants, tokens, and accessibility guidance. Use --json for the design blueprint."
136
136
  },
137
137
  "check": {
138
- "summary": "Run the deterministic checks (exit 0 pass, 1 fail, 2 pass with flagged overrides)."
138
+ "summary": "Check that your sources and outputs agree. Exit 0 means pass, 1 means a failure, and 2 means pass with flagged overrides."
139
139
  },
140
140
  "selftest": {
141
- "summary": "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)."
141
+ "summary": "Run the harness test suite to verify the tools that build and check your project."
142
142
  },
143
143
  "explain": {
144
- "summary": "Explain a token, CSS variable, component, tag or decision from the spec."
144
+ "summary": "Trace a token to its source, find a component’s files, or look up a decision."
145
145
  },
146
146
  "help": {
147
- "summary": "List commands, or show one command's arguments, options and examples."
147
+ "summary": "Find a command or look up its usage, options, and examples."
148
148
  }
149
149
  }
150
150
  }
@@ -9,5 +9,5 @@ export declare function presentation(enabled: boolean, color?: boolean): {
9
9
  header: (label: string) => string;
10
10
  line: (value: string) => string;
11
11
  section: (label: string) => string;
12
- error: (message: string, fix?: string | null) => string;
12
+ error: (message: string, fix?: string | null, file?: string | null) => string;
13
13
  };
@@ -40,6 +40,6 @@ export function presentation(enabled, color = enabled && !('NO_COLOR' in process
40
40
  return match ? `${match[1]}${bold(match[2] ?? '')}${match[3]}` : line;
41
41
  }).join('\n'),
42
42
  section: (label) => `${accent('▸')} ${bold(label)}`,
43
- error: (message, fix) => wrap(`${accent('✕')} ${bold('Error')} ${message}${fix ? `\n ${dim('Next')} ${fix}` : ''}`) + '\n',
43
+ error: (message, fix, file) => wrap(`${accent('✕')} ${bold('Error')} ${message}${file ? `\n ${dim('File')} ${file}` : ''}${fix ? `\n ${dim('Next')} ${fix}` : ''}`) + '\n',
44
44
  };
45
45
  }
@@ -2,11 +2,11 @@ import type { Command } from './types.mjs';
2
2
  export declare const GLOBAL_OPTIONS: {
3
3
  readonly json: {
4
4
  readonly type: "boolean";
5
- readonly description: "Print one JSON envelope instead of human output";
5
+ readonly description: "Print a structured JSON result";
6
6
  };
7
7
  readonly 'dry-run': {
8
8
  readonly type: "boolean";
9
- readonly description: "Show what would change without writing (mutating commands that support it)";
9
+ readonly description: "Preview file changes on supported commands";
10
10
  };
11
11
  readonly help: {
12
12
  readonly type: "boolean";
@@ -14,7 +14,7 @@ export declare const GLOBAL_OPTIONS: {
14
14
  };
15
15
  readonly details: {
16
16
  readonly type: "boolean";
17
- readonly description: "Show the full human-readable output";
17
+ readonly description: "Show the full terminal output";
18
18
  };
19
19
  };
20
20
  export interface DispatchIO {
@@ -13,10 +13,10 @@ import { runChecks } from '../checks/run.mjs';
13
13
  import { errorMessage, show } from '../lib/files.mjs';
14
14
  const HARNESS = fileURLToPath(new URL('../', import.meta.url));
15
15
  export const GLOBAL_OPTIONS = {
16
- json: { type: 'boolean', description: 'Print one JSON envelope instead of human output' },
17
- 'dry-run': { type: 'boolean', description: 'Show what would change without writing (mutating commands that support it)' },
16
+ json: { type: 'boolean', description: 'Print a structured JSON result' },
17
+ 'dry-run': { type: 'boolean', description: 'Preview file changes on supported commands' },
18
18
  help: { type: 'boolean', description: 'Show help for the command' },
19
- details: { type: 'boolean', description: 'Show the full human-readable output' },
19
+ details: { type: 'boolean', description: 'Show the full terminal output' },
20
20
  };
21
21
  const asError = (e) => ({ file: e.file ?? null, msg: e.msg ?? show(e), fix: e.fix ?? null, ...(e.token ? { token: e.token } : {}), ...(e.id ? { check: e.id } : {}) });
22
22
  // Runs the deterministic checks after a mutating command: in-process for --json, with live output otherwise.
@@ -61,7 +61,7 @@ export async function dispatch(argv, { root = process.cwd(), stdout = (s) => pro
61
61
  stdout(JSON.stringify(envelope, null, 2) + '\n');
62
62
  else
63
63
  for (const e of errors)
64
- stderr(ui.enabled ? errorUi.error(e.msg, e.fix) : `${e.msg}${e.fix ? `\n fix: ${e.fix}` : ''}\n`);
64
+ stderr(ui.enabled ? errorUi.error(e.msg, e.fix, e.file) : `${e.msg}${e.fix ? `\n fix: ${e.fix}` : ''}\n`);
65
65
  return exitCode;
66
66
  };
67
67
  const fail = (cmdName, msg, fix, file = null) => finish(cmdName, { errors: [{ file, msg, fix }], exitCode: 1 });
@@ -89,7 +89,7 @@ export async function dispatch(argv, { root = process.cwd(), stdout = (s) => pro
89
89
  if (cmd.project !== false && !existsSync(join(root, 'harness.config.json'))) {
90
90
  const ancestor = ancestorProject(root);
91
91
  return fail(name, `Not a Sketchbook project (no harness.config.json in ${root}).`, ancestor
92
- ? `Change directory to the project root ${ancestor} and retry; file paths are interpreted from that root.`
92
+ ? `Change directory to ${ancestor} and run the command again. Sketchbook resolves file paths from the project root.`
93
93
  : 'sketchbook init (in an empty folder, or --dir <new folder>) creates one; or cd into your design-system folder.');
94
94
  }
95
95
  if (values['dry-run'] && !cmd.dryRun)
@@ -4,7 +4,7 @@
4
4
  {
5
5
  "id": "sign-in",
6
6
  "title": "Sign in",
7
- "summary": "Sign-in and sign-up pages: a centered card with email, a password that can be revealed, a remember-me choice, single sign-on and a form-level error.",
7
+ "summary": "Help people sign in or create an account, with password visibility, single sign-on, and a place to explain errors.",
8
8
  "path": "src/patterns/sign-in",
9
9
  "components": [
10
10
  "alert",
@@ -20,7 +20,7 @@
20
20
  {
21
21
  "id": "settings",
22
22
  "title": "Settings",
23
- "summary": "A preferences page split into tabs, each a card-wrapped form with selects, radios, switches, a slider and a save bar.",
23
+ "summary": "Group preferences by topic so people can find, change, and save them.",
24
24
  "path": "src/patterns/settings",
25
25
  "components": [
26
26
  "alert",
@@ -40,7 +40,7 @@
40
40
  {
41
41
  "id": "data-table",
42
42
  "title": "Data table",
43
- "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.",
43
+ "summary": "Help people find orders, narrow the list by status, and select the rows they want to act on.",
44
44
  "path": "src/patterns/data-table",
45
45
  "components": [
46
46
  "avatar",
@@ -61,7 +61,7 @@
61
61
  {
62
62
  "id": "dashboard",
63
63
  "title": "Dashboard",
64
- "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.",
64
+ "summary": "Give your team one place to check progress, review recent activity, and act on orders.",
65
65
  "path": "src/patterns/dashboard",
66
66
  "components": [
67
67
  "aspect-ratio",
@@ -82,7 +82,7 @@
82
82
  {
83
83
  "id": "profile",
84
84
  "title": "Profile",
85
- "summary": "An account page: breadcrumb, the person with avatar and role, an editable public profile and a list of connected services.",
85
+ "summary": "Let people update their public profile and see which services are connected.",
86
86
  "path": "src/patterns/profile",
87
87
  "components": [
88
88
  "avatar",
@@ -99,7 +99,7 @@
99
99
  {
100
100
  "id": "docs-article",
101
101
  "title": "Docs article",
102
- "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.",
102
+ "summary": "Help readers follow a guide with a contents sidebar, diagram, code sample, and links to what comes next.",
103
103
  "path": "src/patterns/docs-article",
104
104
  "components": [
105
105
  "accordion",
@@ -118,7 +118,7 @@
118
118
  {
119
119
  "id": "onboarding",
120
120
  "title": "Onboarding",
121
- "summary": "First-run screens: a setup step with progress and choices, an empty workspace with next steps, and a setting-up wait state.",
121
+ "summary": "Guide someone through their first setup, then show what to do in an empty workspace.",
122
122
  "path": "src/patterns/onboarding",
123
123
  "components": [
124
124
  "button",
@@ -136,7 +136,7 @@
136
136
  {
137
137
  "id": "form-states",
138
138
  "title": "Form states",
139
- "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.",
139
+ "summary": "Compare default, disabled, invalid, and read-only controls to check tokens, focus, and right-to-left layout.",
140
140
  "path": "src/patterns/form-states",
141
141
  "components": [
142
142
  "checkbox",
@@ -297,7 +297,7 @@ export async function guideDoc(root, { collections } = {}) {
297
297
  return {
298
298
  name: titleCase(pkg.name),
299
299
  link: 'docs/design-docs/README.md',
300
- definition: `Brand ${brand.name}. Change the source and sync; never edit the docs here.`,
300
+ definition: `Explore components, tokens, and themes for ${brand.name}. Edit the project sources, then sync to update this file.`,
301
301
  sections: [
302
302
  {
303
303
  title: 'How this file works',
@@ -312,7 +312,7 @@ export async function guideDoc(root, { collections } = {}) {
312
312
  title: 'Switch the theme',
313
313
  cards: [
314
314
  { type: 'instruction', span: [1, 2], title: 'Theme axes', lines: collections ? collections.filter((c) => c.modes.length > 1).map((c) => `${c.name}: ${c.modes.join(', ')}`) : groups.map((g) => `${g}: ${payload.themes.filter((t) => t.group === g).map((t) => t.name).join(', ')}`) },
315
- { type: 'instruction', span: [1, 2], title: 'How', lines: ['Select a frame or a page; in the right panel pick one mode per collection.', 'Modes of different collections combine.', `Combinations: ${groups.map((g) => payload.themes.filter((t) => t.group === g).length).join(' x ')} = ${groups.reduce((n, g) => n * payload.themes.filter((t) => t.group === g).length, 1)}`] },
315
+ { type: 'instruction', span: [1, 2], title: 'Try a theme', lines: ['Select a frame or page, then choose one mode per collection in the right panel.', 'Change one mode at a time to see how the choices work together.', `Combinations: ${groups.map((g) => payload.themes.filter((t) => t.group === g).length).join(' x ')} = ${groups.reduce((n, g) => n * payload.themes.filter((t) => t.group === g).length, 1)}`] },
316
316
  ],
317
317
  },
318
318
  ],