@usesketchbook/cli 0.2.1 → 0.4.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 (125) hide show
  1. package/.agents/skills/component-builder/SKILL.md +16 -0
  2. package/.agents/skills/contract-author/SKILL.md +16 -0
  3. package/.claude/commands/add.md +1 -5
  4. package/.claude/skills/component-builder/SKILL.md +15 -101
  5. package/.claude/skills/contract-author/SKILL.md +14 -132
  6. package/README.md +14 -30
  7. package/docs/agent-compatibility.md +43 -9
  8. package/docs/cli.md +31 -31
  9. package/harness/catalog/kits/dashboard/files/{63cde4f28d1c141c401d → 09d34e607ea6836480d1} +1 -1
  10. package/harness/catalog/kits/dashboard/files/{11a5797c4c9189b59fbe → 2239c4e4f1d873b03305} +1 -1
  11. package/harness/catalog/kits/dashboard/files/{864acc7ce20f541cf67c → 567a658f80560e3945c6} +1 -1
  12. package/harness/catalog/kits/dashboard/manifest.json +4 -4
  13. package/harness/catalog/kits/data-table/files/{b5d5d7f18347734138e0 → 35c832acd45c642705b1} +1 -1
  14. package/harness/catalog/kits/data-table/files/{36bac8f8e53119768b2e → aaf2d576ed0b53013ac3} +1 -1
  15. package/harness/catalog/kits/data-table/files/{1786ba4d3e0dba1d6a1f → ac8792b3aa3a43002c5e} +1 -1
  16. package/harness/catalog/kits/data-table/manifest.json +4 -4
  17. package/harness/catalog/kits/docs-article/files/{dbc2840f315f672e1d74 → 3c554edf05e9c8bb52c7} +1 -1
  18. package/harness/catalog/kits/docs-article/files/{7f36cb5f0d4f5e103bde → 9d0bb5a1be919431e8ce} +1 -1
  19. package/harness/catalog/kits/docs-article/files/{c2018b502a8094818d8f → e80ea70679e0065026d0} +1 -1
  20. package/harness/catalog/kits/docs-article/manifest.json +4 -4
  21. package/harness/catalog/kits/form-states/files/{b52fb2fc480f0c6352bd → 55a0558891d66e11c216} +1 -1
  22. package/harness/catalog/kits/form-states/files/{88252259f19ed675a0dc → 64566f1a9cb16592d296} +1 -1
  23. package/harness/catalog/kits/form-states/files/{b0b51ebf587b21fd89a1 → f086df13cb85411108a1} +1 -1
  24. package/harness/catalog/kits/form-states/manifest.json +4 -4
  25. package/harness/catalog/kits/onboarding/files/{e669d75a65f4d15d8289 → 738531c9cf4c8bfb9e28} +1 -1
  26. package/harness/catalog/kits/onboarding/files/{ce466020247ecf1ff5fe → b72445926f9763db6c4f} +1 -1
  27. package/harness/catalog/kits/onboarding/files/{322cf4dfc2ee0a035d85 → c969943667ca18e8b0d3} +1 -1
  28. package/harness/catalog/kits/onboarding/manifest.json +4 -4
  29. package/harness/catalog/kits/profile/files/{4aeca453e4792abf29de → 38a6ccd576aca5c96612} +1 -1
  30. package/harness/catalog/kits/profile/files/{0fdd3c14afbdadcf1969 → adccaa2829c56d7fa215} +1 -1
  31. package/harness/catalog/kits/profile/files/{5b58bb5f93ecf12d69ff → de99237cdcfb4ddef8dd} +1 -1
  32. package/harness/catalog/kits/profile/manifest.json +4 -4
  33. package/harness/catalog/kits/settings/files/{d2ebbd6e94570b2c6434 → 08c4411e3c8dbc9e614f} +1 -1
  34. package/harness/catalog/kits/settings/files/{b4a7a4ccdc59465b8de5 → d1cd9cf4acd3416e3f63} +1 -1
  35. package/harness/catalog/kits/settings/files/{1a5d639c6803e7d03acc → f325b6c93ce84d356228} +1 -1
  36. package/harness/catalog/kits/settings/manifest.json +4 -4
  37. package/harness/catalog/kits/sign-in/files/{ca224349b746c530f922 → 0ac413f342ed59e8f3d9} +1 -1
  38. package/harness/catalog/kits/sign-in/files/{552bdad5ce7559849e81 → 796309acee1d478d2692} +1 -1
  39. package/harness/catalog/kits/sign-in/files/{361745a3ed43c753c615 → a106d6104e40b13d7e82} +1 -1
  40. package/harness/catalog/kits/sign-in/manifest.json +4 -4
  41. package/harness/checks/run.mjs +1 -2
  42. package/harness/cli/commands/add.mjs +5 -3
  43. package/harness/cli/commands/api.d.mts +4 -4
  44. package/harness/cli/commands/api.mjs +1 -1
  45. package/harness/cli/commands/audit-css.mjs +1 -1
  46. package/harness/cli/commands/audit-decisions.mjs +1 -1
  47. package/harness/cli/commands/audit-page.mjs +1 -1
  48. package/harness/cli/commands/brand.mjs +1 -1
  49. package/harness/cli/commands/check.d.mts +1 -1
  50. package/harness/cli/commands/check.mjs +1 -1
  51. package/harness/cli/commands/docs.mjs +2 -2
  52. package/harness/cli/commands/doctor.d.mts +2 -2
  53. package/harness/cli/commands/doctor.mjs +7 -5
  54. package/harness/cli/commands/explain.mjs +1 -1
  55. package/harness/cli/commands/generate.mjs +1 -1
  56. package/harness/cli/commands/help.mjs +5 -5
  57. package/harness/cli/commands/icons.mjs +1 -1
  58. package/harness/cli/commands/init.d.mts +1 -1
  59. package/harness/cli/commands/init.mjs +4 -4
  60. package/harness/cli/commands/kits.mjs +3 -1
  61. package/harness/cli/commands/list.mjs +1 -1
  62. package/harness/cli/commands/prefix.mjs +1 -1
  63. package/harness/cli/commands/presets.mjs +1 -1
  64. package/harness/cli/commands/propagate.mjs +1 -1
  65. package/harness/cli/commands/remove.mjs +4 -2
  66. package/harness/cli/commands/selftest.mjs +1 -1
  67. package/harness/cli/commands/status.mjs +6 -4
  68. package/harness/cli/commands/swap.mjs +1 -1
  69. package/harness/cli/commands/sync.mjs +3 -3
  70. package/harness/cli/commands/tokens.mjs +9 -8
  71. package/harness/cli/commands/upgrade.mjs +7 -3
  72. package/harness/cli/docs.mjs +2 -2
  73. package/harness/cli/interactive.mjs +10 -10
  74. package/harness/cli/known-commands.json +26 -26
  75. package/harness/cli/presentation.d.mts +1 -1
  76. package/harness/cli/presentation.mjs +1 -1
  77. package/harness/cli/run.d.mts +3 -3
  78. package/harness/cli/run.mjs +5 -5
  79. package/harness/cli.mjs +0 -0
  80. package/harness/commands/add.mjs +1 -1
  81. package/harness/commands/bootstrap.mjs +4 -3
  82. package/harness/kits/index.json +8 -8
  83. package/harness/lib/agent-config.d.mts +1 -0
  84. package/harness/lib/agent-config.mjs +7 -6
  85. package/harness/lib/design/docs.mjs +2 -2
  86. package/harness/lib/design/sync.d.mts +1 -1
  87. package/harness/lib/installed.mjs +3 -1
  88. package/harness/lib/propagation.mjs +2 -2
  89. package/harness/manifest.json +3 -1
  90. package/harness/starters/blank.json +1 -1
  91. package/harness/starters/foundations.json +1 -1
  92. package/harness/starters/from-codebase.json +1 -1
  93. package/harness/starters/import.json +1 -1
  94. package/harness/starters/library+kits.json +1 -1
  95. package/harness/starters/library.json +1 -1
  96. package/harness/starters/pick.json +1 -1
  97. package/harness/templates/CLAUDE.md +1 -1
  98. package/harness/templates/project/.agents/skills/sketchbook/SKILL.md +1 -1
  99. package/harness/templates/project/AGENT-WORKFLOWS.md +2 -2
  100. package/harness/templates/project/docs/getting-started.md +17 -20
  101. package/harness/templates/project/package-lock.json +2 -2
  102. package/harness/templates/project/src/stories/contract.ts +4 -1
  103. package/harness/templates/project/src/stories/foundations/BorderWidth.stories.ts +1 -1
  104. package/harness/templates/project/src/stories/foundations/Color.stories.ts +1 -1
  105. package/harness/templates/project/src/stories/foundations/Density.stories.ts +1 -1
  106. package/harness/templates/project/src/stories/foundations/Elevation.stories.ts +1 -1
  107. package/harness/templates/project/src/stories/foundations/IconSizes.stories.ts +1 -1
  108. package/harness/templates/project/src/stories/foundations/LayoutGrid.stories.ts +2 -2
  109. package/harness/templates/project/src/stories/foundations/Motion.stories.ts +1 -2
  110. package/harness/templates/project/src/stories/foundations/Opacity.stories.ts +1 -1
  111. package/harness/templates/project/src/stories/foundations/Radius.stories.ts +1 -1
  112. package/harness/templates/project/src/stories/foundations/Spacing.stories.ts +1 -1
  113. package/harness/templates/project/src/stories/foundations/Typography.stories.ts +1 -1
  114. package/harness/templates/project/src/stories/foundations/ZIndex.stories.ts +1 -1
  115. package/harness/test/agent-config.test.mjs +21 -1
  116. package/harness/test/agent-guidance.test.mjs +16 -0
  117. package/harness/test/bootstrap.test.mjs +84 -15
  118. package/harness/test/checks.test.mjs +4 -1
  119. package/harness/test/claude-live.test.mjs +8 -3
  120. package/harness/test/cli.test.mjs +25 -5
  121. package/harness/test/copilot-live.test.mjs +12 -13
  122. package/harness/test/docs-reference.test.mjs +17 -0
  123. package/harness/test/opencode-live.test.mjs +25 -10
  124. package/harness/test/package.test.mjs +1 -0
  125. package/package.json +3 -1
@@ -1,6 +1,6 @@
1
1
  # Settings
2
2
 
3
- Preferences split into tabs; each tab is one form in a card with a save bar. States: default, notifications, saved.
3
+ Group preferences by topic so people can find, change, and save them.
4
4
 
5
5
  ## When to use
6
6
  Account or workspace preferences with a few groups of options that are saved together per group. For a single long form, drop the tabs and stack the cards.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "Settings",
3
- "summary": "A preferences page split into tabs, each a card-wrapped form with selects, radios, switches, a slider and a save bar.",
3
+ "summary": "Group preferences by topic so people can find, change, and save them.",
4
4
  "components": [
5
5
  "sb-alert",
6
6
  "sb-alert-description",
@@ -105,7 +105,7 @@ const settings = (tab = 'general', saved = false) => html`<main class="settings"
105
105
 
106
106
  const meta: Meta = {
107
107
  title: 'Patterns/Settings',
108
- parameters: { layout: 'fullscreen', controls: { disable: true } },
108
+ parameters: { docs: { description: { component: 'Group preferences by topic so people can find, change, and save them.' } }, layout: 'fullscreen', controls: { disable: true } },
109
109
  render: () => settings(),
110
110
  };
111
111
  export default meta;
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "settings",
3
3
  "title": "Settings",
4
- "summary": "A preferences page split into tabs, each a card-wrapped form with selects, radios, switches, a slider and a save bar.",
4
+ "summary": "Group preferences by topic so people can find, change, and save them.",
5
5
  "path": "src/patterns/settings",
6
6
  "components": [
7
7
  "alert",
@@ -37,15 +37,15 @@
37
37
  },
38
38
  {
39
39
  "path": "src/patterns/settings/README.md",
40
- "hash": "d2ebbd6e94570b2c6434"
40
+ "hash": "08c4411e3c8dbc9e614f"
41
41
  },
42
42
  {
43
43
  "path": "src/patterns/settings/Settings.stories.ts",
44
- "hash": "1a5d639c6803e7d03acc"
44
+ "hash": "f325b6c93ce84d356228"
45
45
  },
46
46
  {
47
47
  "path": "src/patterns/settings/pattern.json",
48
- "hash": "b4a7a4ccdc59465b8de5"
48
+ "hash": "d1cd9cf4acd3416e3f63"
49
49
  },
50
50
  {
51
51
  "path": "src/patterns/settings/settings.css",
@@ -72,7 +72,7 @@ const signIn = ({ error = false, loading = false, email = '' }: SignInOptions =
72
72
 
73
73
  const meta: Meta = {
74
74
  title: 'Patterns/Sign In',
75
- parameters: { layout: 'fullscreen', controls: { disable: true } },
75
+ parameters: { docs: { description: { component: 'Help people sign in or create an account, with password visibility, single sign-on, and a place to explain errors.' } }, layout: 'fullscreen', controls: { disable: true } },
76
76
  render: () => signIn(),
77
77
  };
78
78
  export default meta;
@@ -1,6 +1,6 @@
1
1
  # Sign in
2
2
 
3
- A centered card for signing in or creating an account. States: default, with error, loading, sign up.
3
+ Help people sign in or create an account, with password visibility, single sign-on, and a place to explain errors.
4
4
 
5
5
  ## When to use
6
6
  The first screen of an app that asks for an email and a password. Use the Sign up story when the same page also creates accounts. Not for multi-step identity checks: chain the onboarding kit after it instead.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "Sign in",
3
- "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.",
3
+ "summary": "Help people sign in or create an account, with password visibility, single sign-on, and a place to explain errors.",
4
4
  "components": [
5
5
  "sb-alert",
6
6
  "sb-alert-description",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "sign-in",
3
3
  "title": "Sign in",
4
- "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.",
4
+ "summary": "Help people sign in or create an account, with password visibility, single sign-on, and a place to explain errors.",
5
5
  "path": "src/patterns/sign-in",
6
6
  "components": [
7
7
  "alert",
@@ -37,15 +37,15 @@
37
37
  },
38
38
  {
39
39
  "path": "src/patterns/sign-in/README.md",
40
- "hash": "552bdad5ce7559849e81"
40
+ "hash": "796309acee1d478d2692"
41
41
  },
42
42
  {
43
43
  "path": "src/patterns/sign-in/SignIn.stories.ts",
44
- "hash": "ca224349b746c530f922"
44
+ "hash": "0ac413f342ed59e8f3d9"
45
45
  },
46
46
  {
47
47
  "path": "src/patterns/sign-in/pattern.json",
48
- "hash": "361745a3ed43c753c615"
48
+ "hash": "a106d6104e40b13d7e82"
49
49
  },
50
50
  {
51
51
  "path": "src/patterns/sign-in/sign-in.css",
@@ -68,7 +68,7 @@ export async function runChecks(root, { only, maintainer = false } = {}) {
68
68
  // The human report as lines (npm run check prints them; sketchbook tokens prints them for its staged checks).
69
69
  // Clean checks fold into one line unless verbose: agents read this output on every run (SB-0114).
70
70
  export function formatHuman(report, { verbose = false } = {}) {
71
- const lines = [];
71
+ const lines = [`${report.ok ? 'All checks passed' : 'Checks failed'}${report.exitCode === 2 ? ' (with overrides)' : ''}.`, ''];
72
72
  const clean = report.results.filter((r) => !r.errors.length && !r.warnings.length);
73
73
  if (!verbose && clean.length)
74
74
  lines.push(`pass ${clean.map((r) => r.id).join(' ')}`);
@@ -91,7 +91,6 @@ export function formatHuman(report, { verbose = false } = {}) {
91
91
  for (const o of report.overrides)
92
92
  lines.push(` ${o.token} = ${JSON.stringify(o.value)} (${o.added ? 'added by hand' : `generated ${JSON.stringify(o.generated)}`})`);
93
93
  }
94
- lines.push('', `${report.ok ? 'All checks passed' : 'Checks failed'}${report.exitCode === 2 ? ' (with overrides)' : ''}.`);
95
94
  return lines;
96
95
  }
97
96
  const printHuman = (report, opts) => {
@@ -12,7 +12,7 @@ const options = { blank: { type: 'boolean', description: 'Scaffold an empty cont
12
12
  export default {
13
13
  name: 'add',
14
14
  group: 'components',
15
- summary: 'Install a component from the catalog (contract, code, stories, specs; dependencies first), or --blank to scaffold a new contract (status draft, proposed decision).',
15
+ summary: 'Install a catalog component with its dependencies, or start a new contract with --blank.',
16
16
  args: [{ name: 'Component Name', required: true, variadic: true, description: 'Catalog name (button, "Button Group") or a registry entry for --blank' }],
17
17
  options,
18
18
  examples: ['sketchbook add button', 'sketchbook add Button Group --dry-run', 'sketchbook add Date Picker --blank'],
@@ -33,9 +33,11 @@ export default {
33
33
  out(`Would install ${r.installed.join(', ')} from the catalog (order: ${order.filter((n) => !present.includes(n)).join(' -> ')}), writing:\n ${r.changed.join('\n ')}`);
34
34
  return { changed: r.changed, data: { installed: r.installed, order } };
35
35
  }
36
- out(`Installed from the catalog: ${r.installed.join(', ')} (${r.changed.length} file(s)); registry, tokens, styles and barrel rebuilt.`);
36
+ out(`Installed from the catalog: ${r.installed.join(', ')}. Rebuilt the token and style outputs and updated the registry.`);
37
37
  const c = await componentChecks(root);
38
38
  out(`Checks: ${c.summary}`);
39
+ if (!c.exitCode)
40
+ out('Next: Run npm run storybook to try the component.');
39
41
  return {
40
42
  changed: [...r.changed, 'generated/css/tokens.css', 'src/index.ts'], errors: c.errors, warnings: c.warnings, exitCode: c.exitCode,
41
43
  next: c.exitCode ? 'Fix the failing checks, then sketchbook check.' : `npm run storybook (Components/${r.installed.at(-1)}), then sketchbook check.`,
@@ -43,7 +45,7 @@ export default {
43
45
  };
44
46
  }
45
47
  const r = await scaffold(root, display, { dryRun });
46
- const next = 'Draft the contract with the contract-author skill, then npm run check, then fill plan.md and stop for approval.';
48
+ const next = 'Draft the contract from the design and accessibility references, then run npm run check. If the planning gate is enabled, fill plan.md and stop for approval before implementation.';
47
49
  if (dryRun)
48
50
  out(`Would scaffold spec/components/${r.name}/ (${r.tag}) and write:\n ${r.files.join('\n ')}`);
49
51
  else
@@ -47,15 +47,15 @@ declare const _default: {
47
47
  } | {
48
48
  data: {
49
49
  entry: {
50
- type: "variant" | "boolean" | "text" | "number";
51
- values?: string | string[];
50
+ kind: "text" | "icon" | "slot";
52
51
  meaning: string;
53
52
  figma: null | import("../../../generated/types/api.js").Figma;
54
- proposal?: boolean;
55
53
  } | {
56
- kind: "text" | "icon" | "slot";
54
+ type: "variant" | "boolean" | "text" | "number";
55
+ values?: string | string[];
57
56
  meaning: string;
58
57
  figma: null | import("../../../generated/types/api.js").Figma;
58
+ proposal?: boolean;
59
59
  } | null;
60
60
  used: import("../../lib/api.mjs").PropRow[];
61
61
  aspects?: undefined;
@@ -7,7 +7,7 @@ const MARK = { canonical: ' ', alias: '~', extension: '+', unregistered: '!' };
7
7
  export default {
8
8
  name: 'api',
9
9
  group: 'components',
10
- 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).',
10
+ summary: 'Look up component property, event, and state names in the shared API vocabulary.',
11
11
  subcommands: ACTIONS,
12
12
  args: [
13
13
  { name: 'action', required: false, description: 'list (default) | check | explain' },
@@ -2,7 +2,7 @@ import { auditCss, writeProposal } from '../../commands/audit-css.mjs';
2
2
  export default {
3
3
  name: 'audit-css',
4
4
  group: 'tokens',
5
- 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).',
5
+ summary: 'Inspect an existing stylesheet to find recurring values and draft foundation choices.',
6
6
  args: [{ name: 'paths', required: true, variadic: true, description: 'CSS/SCSS files, folders or globs (quote globs), relative to the project' }],
7
7
  options: {},
8
8
  examples: ['sketchbook audit-css ../product/src', 'sketchbook audit-css "app/**/*.css" --json'],
@@ -17,7 +17,7 @@ function gitBaseline(root, ref, file) {
17
17
  export default {
18
18
  name: 'audit-decisions',
19
19
  group: 'quality',
20
- 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.',
20
+ summary: 'Compare settled decisions with a trusted earlier copy or Git revision. Run sketchbook check to validate the log.',
21
21
  args: [{ name: 'baseline', required: false, description: 'Path to a trusted earlier copy of spec/decisions/DECISIONS.md' }],
22
22
  options,
23
23
  examples: ['sketchbook audit-decisions ../decisions-before.md', 'sketchbook audit-decisions --git-ref HEAD --json'],
@@ -5,7 +5,7 @@ import { readJsonSync } from '../../lib/files.mjs';
5
5
  export default {
6
6
  name: 'audit-page',
7
7
  group: 'quality',
8
- 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.',
8
+ summary: 'Check a page for a level-one heading and a main landmark. This checks page structure only.',
9
9
  args: [{ name: 'file', required: true, description: 'HTML file to check, relative to the current project' }],
10
10
  options: {},
11
11
  examples: ['sketchbook audit-page preview.html', 'sketchbook audit-page preview.html --json'],
@@ -7,7 +7,7 @@ const options = {
7
7
  export default {
8
8
  name: 'brand',
9
9
  group: 'tokens',
10
- 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).',
10
+ summary: 'Add, list, or switch brands that share the same semantic token names.',
11
11
  subcommands: ['add', 'list', 'use', 'build'],
12
12
  args: [
13
13
  { name: 'action', required: false, description: 'list (default) | add | use | build' },
@@ -52,7 +52,7 @@ declare const _default: {
52
52
  next?: undefined;
53
53
  data?: undefined;
54
54
  } | {
55
- exitCode: 0 | 2 | 1;
55
+ exitCode: 0 | 1 | 2;
56
56
  errors: {
57
57
  id: string;
58
58
  file?: string | null;
@@ -11,7 +11,7 @@ const options = {
11
11
  export default {
12
12
  name: 'check',
13
13
  group: 'quality',
14
- summary: 'Run the deterministic checks (exit 0 pass, 1 fail, 2 pass with flagged overrides).',
14
+ summary: 'Check that your sources and outputs agree. Exit 0 means pass, 1 means a failure, and 2 means pass with flagged overrides.',
15
15
  args: [],
16
16
  options,
17
17
  examples: ['sketchbook check', 'sketchbook check --only T6', 'sketchbook check --maintainer', 'sketchbook check --json'],
@@ -6,7 +6,7 @@ import { join } from 'node:path';
6
6
  export default {
7
7
  name: 'docs',
8
8
  group: 'design',
9
- 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.',
9
+ summary: 'Read a component or kit’s variants, tokens, and accessibility guidance. Use --json for the design blueprint.',
10
10
  args: [{ name: 'name', required: true, description: 'A component folder name (spec/components) or a pattern id (src/patterns)' }],
11
11
  options: {},
12
12
  examples: ['sketchbook docs button', 'sketchbook docs field --json', 'sketchbook docs sign-in'],
@@ -17,7 +17,7 @@ export default {
17
17
  const [name = ''] = args;
18
18
  const isComponent = existsSync(join(root, 'spec/components', name, 'contract.json'));
19
19
  const doc = !isComponent && (await patternIds(root)).includes(name) ? await patternDoc(root, name) : await componentDoc(root, name);
20
- const tty = process.stdout.isTTY && !process.env.NO_COLOR;
20
+ const tty = process.stdout.isTTY && !('NO_COLOR' in process.env);
21
21
  out(docText(doc, { highlight: tty ? (s) => `\x1b[34m${s}\x1b[0m` : (s) => s }));
22
22
  return { data: { doc } };
23
23
  },
@@ -30,7 +30,7 @@ declare const _default: {
30
30
  overrides: number;
31
31
  design: import("./status.mjs").DesignState;
32
32
  checks: {
33
- exitCode: 0 | 1 | 2;
33
+ exitCode: 0 | 2 | 1;
34
34
  failing: string[];
35
35
  warnings: number;
36
36
  };
@@ -67,7 +67,7 @@ declare const _default: {
67
67
  gitHook: string;
68
68
  };
69
69
  next: string | null;
70
- exitCode: 0 | 1 | 2;
70
+ exitCode: 0 | 2 | 1;
71
71
  }>;
72
72
  };
73
73
  export default _default;
@@ -15,7 +15,7 @@ import { designState } from './status.mjs';
15
15
  export default {
16
16
  name: 'doctor',
17
17
  group: 'project',
18
- 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).',
18
+ 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.',
19
19
  args: [],
20
20
  options: {},
21
21
  examples: ['sketchbook doctor', 'sketchbook doctor --json'],
@@ -67,6 +67,7 @@ export default {
67
67
  gitHook: spawnSync('git', ['-C', root, 'config', 'core.hooksPath'], { encoding: 'utf8' }).stdout.trim().match(/(^|\/)\.githooks\/?$/) && existsSync(join(root, '.githooks/pre-commit')) && statSync(join(root, '.githooks/pre-commit')).mode & 0o111 ? 'active' : 'inactive',
68
68
  };
69
69
  const c = data.components;
70
+ out(`Checks: ${data.checks.failing.length ? `failed ${data.checks.failing.join(', ')}` : data.checks.exitCode === 2 ? 'passed with overrides' : 'passed'}${data.checks.warnings ? `, ${data.checks.warnings} warnings` : ''}.`);
70
71
  out(`Starter: ${data.starter ?? 'not recorded (sketchbook init --start <starter>)'}`);
71
72
  out(`Harness: ${data.harnessVersion ?? 'unrecorded'} (files here: ${data.harnessAvailable ?? 'no harness/manifest.json'})${data.catalogSource ? '; this repo is the catalog source' : ''}`);
72
73
  out(`Components: ${c.installed.length} installed, ${c.available.length} more in the catalog, ${c.customized.length} customized${c.customized.length ? ` (${c.customized.join(', ')})` : ''}, ${c.teamMade.length} team-made`);
@@ -74,12 +75,11 @@ export default {
74
75
  out(`Brands: ${data.brands.list.length ? `${data.brands.list.join(', ')} (active ${data.brands.active ?? 'none of them'})` : 'single brand'}`);
75
76
  out(`Overrides: ${data.overrides}`);
76
77
  out(`Design: ${data.design.tool ?? 'none'}${data.design.tool ? `, tokens ${data.design.tokens}, ${data.design.components.stale.length} stale component(s)` : ''}`);
77
- out(`Checks: ${data.checks.failing.length ? `failing ${data.checks.failing.join(', ')}` : 'all pass'}${data.checks.warnings ? `, ${data.checks.warnings} warning(s)` : ''}`);
78
78
  const missingInstructions = Object.entries(data.agentInstructions).filter(([, present]) => !present).map(([file]) => file);
79
79
  if (!profiles.length)
80
80
  out('Agent integrations: core only.');
81
81
  else
82
- out(`Agent setup (${profiles.join(', ')}): ${missingInstructions.length ? `missing ${missingInstructions.join(', ')} (sketchbook init can restore missing setup files when paths are available)` : 'all selected files present'}; presence does not verify client loading`);
82
+ out(`Agent setup (${profiles.join(', ')}): ${missingInstructions.length ? `missing ${missingInstructions.join(', ')} (sketchbook init can restore missing setup files when paths are available)` : 'all selected files present'}; confirm what your client loaded before relying on these files`);
83
83
  const reviewInstructions = Object.entries(data.agentInstructionReferences).filter(([, status]) => status === 'not-detected').map(([file]) => file);
84
84
  if (reviewInstructions.length)
85
85
  out(`Agent instruction references not detected: ${reviewInstructions.join(', ')}. Review preserved team instructions for the shared workflow; a textual check cannot determine whether equivalent guidance is present or loaded.`);
@@ -103,11 +103,13 @@ export default {
103
103
  if (data.claude !== 'not-selected')
104
104
  out(`Claude layer: ${data.claude === 'staged' ? 'staged in move-to-.claude/ (optional Claude Code setup: move-to-.claude/INSTALL.md)' : data.claude === 'missing' ? 'missing (sketchbook init puts it back)' : data.claude}${data.contextBudget && data.claude !== 'missing' ? `, always-on context ${data.contextBudget.bytes} of ${data.contextBudget.budget} bytes (${Math.round((data.contextBudget.bytes / data.contextBudget.budget) * 100)}%)` : ''}`);
105
105
  out(`Commit gate: ${data.gitHook === 'active' ? 'active (npm run check runs before every commit)' : 'inactive (git config core.hooksPath .githooks at the repository root, or call npm run check from your own hook)'}`);
106
- const next = data.checks.failing.length ? 'sketchbook check (each error has a fix)'
106
+ const next = data.checks.failing.length ? 'Run sketchbook check to see the suggested fix for each failure.'
107
107
  : missingInstructions.length ? 'sketchbook init (restores missing setup files when paths are available)'
108
108
  : data.claude === 'staged' ? 'For Claude Code, optionally install the layer from move-to-.claude/ (move-to-.claude/INSTALL.md)'
109
109
  : data.claude === 'missing' ? 'sketchbook init (restores what is missing)'
110
- : !data.starter ? 'sketchbook init --start <starter>' : null;
110
+ : !data.starter ? 'Run sketchbook help init --details to review the starter options.' : null;
111
+ if (next)
112
+ out(`\nNext: ${next}`);
111
113
  return { data, next, exitCode: report.exitCode };
112
114
  },
113
115
  };
@@ -2,7 +2,7 @@ import { explain } from '../../commands/explain.mjs';
2
2
  export default {
3
3
  name: 'explain',
4
4
  group: 'quality',
5
- summary: 'Explain a token, CSS variable, component, tag or decision from the spec.',
5
+ summary: 'Trace a token to its source, find a component’s files, or look up a decision.',
6
6
  args: [{ name: 'thing', required: true, variadic: true, description: 'Token path, --css-var, component name, tag, SB-NNNN or free text' }],
7
7
  options: {},
8
8
  examples: ['sketchbook explain color.primary', 'sketchbook explain button', 'sketchbook explain SB-0024'],
@@ -3,7 +3,7 @@ export const GENERATED = ['generated/css/tokens.css', 'generated/css/fonts.css',
3
3
  export default {
4
4
  name: 'generate',
5
5
  group: 'project',
6
- 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).',
6
+ summary: 'Rebuild tokens, styles, and other generated outputs from your project sources. Run npm run generate in an initialized project for the same build.',
7
7
  args: [],
8
8
  options: {},
9
9
  examples: ['sketchbook generate', 'sketchbook generate --json'],
@@ -7,7 +7,7 @@ const describe = (c) => ({ name: c.name, group: c.group, summary: c.summary, usa
7
7
  export default {
8
8
  name: 'help',
9
9
  group: 'meta',
10
- summary: 'List commands, or show one command\'s arguments, options and examples.',
10
+ summary: 'Find a command or look up its usage, options, and examples.',
11
11
  args: [{ name: 'command', required: false, description: 'A command name' }],
12
12
  options: {},
13
13
  examples: ['sketchbook help', 'sketchbook help init'],
@@ -22,7 +22,7 @@ export default {
22
22
  if (!c)
23
23
  throw Object.assign(new Error(`Unknown command "${args[0]}".`), { fix: 'Run sketchbook help to list commands.' });
24
24
  if (human && !details) {
25
- out(`${ui.section(c.name)} ${c.mutates ? 'Changes files' : 'Read-only'}\n\n${c.summary}`);
25
+ out(`${c.summary}\n\n${ui.section('Usage')}\n ${usage(c)}\n ${c.mutates ? 'Changes files' : 'Read-only'}`);
26
26
  if (c.args.length) {
27
27
  out('\nArguments:');
28
28
  for (const a of c.args)
@@ -32,7 +32,7 @@ export default {
32
32
  out(`\nSubcommands: ${subcommandsOf(c).map((sc) => sc.name).join(' · ')}`);
33
33
  if (c.examples.length)
34
34
  out(`\nTry: ${c.examples[0]}`);
35
- out(`\n${ui.dim('Explore')} sketchbook help ${c.name} --details\nDocumentation ${DOCS_URL}`);
35
+ out(`\nMore options sketchbook help ${c.name} --details\nDocumentation ${DOCS_URL}`);
36
36
  return { data: { command: describe(c) } };
37
37
  }
38
38
  out(`${usage(c)}\n\n${c.summary}${c.mutates ? ' Changes files.' : ' Read-only.'}`);
@@ -57,13 +57,13 @@ export default {
57
57
  return { data: { command: describe(c) } };
58
58
  }
59
59
  if (human && !details) {
60
- out('Your design system, from the terminal.\n');
60
+ out('Choose a command for the work you want to do.\n\nUsage sketchbook <command> [arguments]\nTry sketchbook status\n');
61
61
  for (const [g, label] of Object.entries(GROUPS)) {
62
62
  const list = commands().filter((c) => c.group === g);
63
63
  if (list.length)
64
64
  out(`${ui.section(label)}\n ${list.map((c) => c.name).join(' · ')}\n`);
65
65
  }
66
- out(`${ui.dim('Explore')} sketchbook help <command> · sketchbook help --details\nDocumentation ${DOCS_URL}`);
66
+ out(`More help sketchbook help <command> · sketchbook help --details\nDocumentation ${DOCS_URL}`);
67
67
  return { data: { commands: commands().map(describe) } };
68
68
  }
69
69
  out('sketchbook <command> [arguments] [--json] [--dry-run]\n');
@@ -4,7 +4,7 @@ const options = { category: { type: 'string', value: 'category', description: 'a
4
4
  export default {
5
5
  name: 'icons',
6
6
  group: 'design',
7
- 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).',
7
+ summary: 'List the icons in your project or add icons from Lucide.',
8
8
  subcommands: ACTIONS,
9
9
  args: [
10
10
  { name: 'action', required: false, description: 'list (default) | add | remove' },
@@ -226,7 +226,7 @@ declare const _default: {
226
226
  exitCode?: undefined;
227
227
  } | {
228
228
  changed: string[];
229
- warnings: (IssueLike | import("../types.mjs").EnvelopeIssue)[];
229
+ warnings: (import("../types.mjs").EnvelopeIssue | IssueLike)[];
230
230
  errors: import("../types.mjs").EnvelopeIssue[];
231
231
  exitCode: number;
232
232
  next: string;
@@ -26,7 +26,7 @@ const densityOf = (density) => (density && typeof density === 'object' ? density
26
26
  export default {
27
27
  name: 'init',
28
28
  group: 'project',
29
- 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.',
29
+ 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.',
30
30
  args: [],
31
31
  options,
32
32
  examples: ['sketchbook init', 'sketchbook init --agent claude', 'sketchbook init --agent codex,trae --dry-run', 'sketchbook init --dir design-system --start library', 'sketchbook init --start library', 'sketchbook init --with forge', 'sketchbook init --start blank --yes', 'sketchbook init --start pick --components card,button', 'sketchbook init --start from-codebase --from "../app/**/*.css"', 'sketchbook init --primary "#2563EB" --font Inter --radius round', 'sketchbook init --density compact --dry-run'],
@@ -48,7 +48,7 @@ export default {
48
48
  return r;
49
49
  // Past the exitCode 1 return, data is the install summary; `in` only narrows the inferred union.
50
50
  if (!dryRun && 'target' in r.data) {
51
- out(`\nSketchbook installed in ${r.data.target}. What it installed (docs/harness.md has the full list):`);
51
+ out(`\nCreated your design system in ${r.data.target}. See docs/harness.md in that folder for the installation details.`);
52
52
  for (const l of installedSummary(r.data.installed))
53
53
  out(l);
54
54
  }
@@ -61,7 +61,7 @@ export default {
61
61
  return r;
62
62
  }
63
63
  if (options.dir && target !== resolve(root))
64
- throw Object.assign(new Error(`${options.dir} is already a Sketchbook project.`), { fix: `cd ${options.dir}, then run sketchbook init there.` });
64
+ throw Object.assign(new Error(`${options.dir} is already a Sketchbook project.`), { fix: `cd ${options.dir}, then run sketchbook init again.` });
65
65
  for (const k of ['no-install', 'adopt', 'engine'])
66
66
  if (options[k] !== undefined)
67
67
  throw Object.assign(new Error(`--${k} goes with a new project (a folder without harness.config.json).`), { fix: `Drop --${k}.` });
@@ -78,7 +78,7 @@ export default {
78
78
  if (r.added.length)
79
79
  out(`${dryRun ? 'Would restore' : 'Restored'} ${r.added.length} missing file(s):\n ${r.added.join('\n ')}`);
80
80
  else if (!r.skipped.length)
81
- out('Nothing missing: every harness-owned and setup file is here.');
81
+ out('All expected setup files are present.');
82
82
  const { hooks } = r;
83
83
  if (hooks.length)
84
84
  out(`${dryRun ? 'Would add or update' : 'Added or updated'} ${hooks.length} Sketchbook hook(s) in settings.json (your own hooks and settings are kept):\n ${hooks.join('\n ')}`);
@@ -12,7 +12,7 @@ const options = { yes: { type: 'boolean', description: 'remove: confirm removing
12
12
  export default {
13
13
  name: 'kits',
14
14
  group: 'components',
15
- 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).',
15
+ summary: 'Browse template kits, install a kit with its components, or remove one.',
16
16
  subcommands: ['list', 'add', 'remove'],
17
17
  args: [
18
18
  { name: 'action', required: false, description: 'list (default) | add | remove' },
@@ -60,6 +60,8 @@ export default {
60
60
  // catalog:build (not run here: it would drop the only copy kits add restores from). See docs/simplicity-debt.md.
61
61
  const source = readConfig(root).catalog?.source === true;
62
62
  const removedNext = source && errors.some((e) => e.id === 'G1') ? `This repo is the catalog source: npm run catalog:build to drop ${ids.join(', ')} from the catalog too (G1 then passes), or sketchbook kits add ${ids.join(' ')} to put it back.` : 'sketchbook check';
63
+ if (!errors.length && action === 'add')
64
+ out('Next: Run npm run storybook and open the kit under Patterns.');
63
65
  return { changed: r.changed, errors, exitCode: errors.length ? 1 : 0, next: action === 'add' ? 'npm run storybook (Patterns/<Kit>), then sketchbook check.' : removedNext, data: r };
64
66
  },
65
67
  };
@@ -7,7 +7,7 @@ const options = {
7
7
  export default {
8
8
  name: 'list',
9
9
  group: 'components',
10
- summary: 'List catalog components (installed or available) with what each needs, plus template kits (read-only).',
10
+ summary: 'Browse installed and available components and see which dependencies they need.',
11
11
  args: [],
12
12
  options,
13
13
  examples: ['sketchbook list', 'sketchbook list --available', 'sketchbook list --installed --json'],
@@ -2,7 +2,7 @@ import { renamePrefix } from '../../commands/prefix.mjs';
2
2
  export default {
3
3
  name: 'prefix',
4
4
  group: 'project',
5
- summary: 'Rename the element and CSS prefix everywhere (sources, contracts, tests, docs), rebuild, then check.',
5
+ summary: 'Change the element and CSS prefix across your project, then rebuild and check the outputs.',
6
6
  args: [{ name: 'new', required: true, description: 'Lowercase letters and digits, e.g. acme' }],
7
7
  options: {},
8
8
  examples: ['sketchbook prefix acme', 'sketchbook prefix acme --dry-run'],
@@ -4,7 +4,7 @@ import { show } from '../../lib/files.mjs';
4
4
  export default {
5
5
  name: 'presets',
6
6
  group: 'tokens',
7
- summary: 'List the standards catalog: families, or one family\'s presets with sources (read-only).',
7
+ summary: 'Browse foundation presets by family, with their values and sources.',
8
8
  args: [{ name: 'family', required: false, description: 'A family id, e.g. spacing, typeScale, motion' }],
9
9
  options: {},
10
10
  examples: ['sketchbook presets', 'sketchbook presets motion'],
@@ -22,7 +22,7 @@ const options = {
22
22
  export default {
23
23
  name: 'propagate',
24
24
  group: 'project',
25
- 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).',
25
+ 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.',
26
26
  args: [],
27
27
  options,
28
28
  examples: ['sketchbook propagate', 'sketchbook propagate --maintainer'],
@@ -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'],