@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
@@ -105,7 +105,7 @@ const settingUp = html`<main class="onboarding">
105
105
 
106
106
  const meta: Meta = {
107
107
  title: 'Patterns/Onboarding',
108
- parameters: { layout: 'fullscreen', controls: { disable: true } },
108
+ parameters: { docs: { description: { component: 'Guide someone through their first setup, then show what to do in an empty workspace.' } }, layout: 'fullscreen', controls: { disable: true } },
109
109
  render: () => step,
110
110
  };
111
111
  export default meta;
@@ -1,6 +1,6 @@
1
1
  # Onboarding
2
2
 
3
- First-run screens: a setup step with progress and choices, an empty workspace with next steps, and a setting-up wait state.
3
+ Guide someone through their first setup, then show what to do in an empty workspace.
4
4
 
5
5
  ## When to use
6
6
  The first minutes after sign-up, and any empty area that needs to explain what goes there and how to fill it.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "onboarding",
3
3
  "title": "Onboarding",
4
- "summary": "First-run screens: a setup step with progress and choices, an empty workspace with next steps, and a setting-up wait state.",
4
+ "summary": "Guide someone through their first setup, then show what to do in an empty workspace.",
5
5
  "path": "src/patterns/onboarding",
6
6
  "components": [
7
7
  "button",
@@ -35,11 +35,11 @@
35
35
  },
36
36
  {
37
37
  "path": "src/patterns/onboarding/Onboarding.stories.ts",
38
- "hash": "ce466020247ecf1ff5fe"
38
+ "hash": "b72445926f9763db6c4f"
39
39
  },
40
40
  {
41
41
  "path": "src/patterns/onboarding/README.md",
42
- "hash": "322cf4dfc2ee0a035d85"
42
+ "hash": "c969943667ca18e8b0d3"
43
43
  },
44
44
  {
45
45
  "path": "src/patterns/onboarding/onboarding.css",
@@ -47,7 +47,7 @@
47
47
  },
48
48
  {
49
49
  "path": "src/patterns/onboarding/pattern.json",
50
- "hash": "e669d75a65f4d15d8289"
50
+ "hash": "738531c9cf4c8bfb9e28"
51
51
  }
52
52
  ]
53
53
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "Profile",
3
- "summary": "An account page: breadcrumb, the person with avatar and role, an editable public profile and a list of connected services.",
3
+ "summary": "Let people update their public profile and see which services are connected.",
4
4
  "components": [
5
5
  "sb-avatar",
6
6
  "sb-avatar-fallback",
@@ -1,6 +1,6 @@
1
1
  # Profile
2
2
 
3
- An account page: breadcrumb, the person with avatar and role, an editable public profile and connected services. States: default, with errors.
3
+ Let people update their public profile and see which services are connected.
4
4
 
5
5
  ## When to use
6
6
  A page about one person or one record with a short form and a list of related things. For many fields, split them into cards like the settings kit.
@@ -84,7 +84,7 @@ const profile = (errors = false) => html`<div class="profile">
84
84
 
85
85
  const meta: Meta = {
86
86
  title: 'Patterns/Profile',
87
- parameters: { layout: 'fullscreen', controls: { disable: true } },
87
+ parameters: { docs: { description: { component: 'Let people update their public profile and see which services are connected.' } }, layout: 'fullscreen', controls: { disable: true } },
88
88
  render: () => profile(),
89
89
  };
90
90
  export default meta;
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "profile",
3
3
  "title": "Profile",
4
- "summary": "An account page: breadcrumb, the person with avatar and role, an editable public profile and a list of connected services.",
4
+ "summary": "Let people update their public profile and see which services are connected.",
5
5
  "path": "src/patterns/profile",
6
6
  "components": [
7
7
  "avatar",
@@ -30,15 +30,15 @@
30
30
  },
31
31
  {
32
32
  "path": "src/patterns/profile/Profile.stories.ts",
33
- "hash": "5b58bb5f93ecf12d69ff"
33
+ "hash": "de99237cdcfb4ddef8dd"
34
34
  },
35
35
  {
36
36
  "path": "src/patterns/profile/README.md",
37
- "hash": "0fdd3c14afbdadcf1969"
37
+ "hash": "adccaa2829c56d7fa215"
38
38
  },
39
39
  {
40
40
  "path": "src/patterns/profile/pattern.json",
41
- "hash": "4aeca453e4792abf29de"
41
+ "hash": "38a6ccd576aca5c96612"
42
42
  },
43
43
  {
44
44
  "path": "src/patterns/profile/profile.css",
@@ -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.`,
@@ -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' },
@@ -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' },
@@ -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'],