@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
@@ -2,13 +2,13 @@ import { lstatSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { readJsonSync } from './files.mjs';
4
4
  export const STAGED = 'move-to-.claude';
5
- const SHARED = ['AGENTS.md', 'AGENT-WORKFLOWS.md'];
6
- const SKILL = '.agents/skills/sketchbook/SKILL.md';
5
+ export const WORKFLOW_SKILLS = ['.agents/skills/contract-author/SKILL.md', '.agents/skills/component-builder/SKILL.md'];
6
+ const SHARED = ['AGENTS.md', 'AGENT-WORKFLOWS.md', '.agents/skills/sketchbook/SKILL.md', ...WORKFLOW_SKILLS];
7
7
  const PROFILE_FILES = {
8
- claude: ['CLAUDE.md'],
9
- codex: [...SHARED, SKILL, '.codex/hooks.json', '.codex/sketchbook-guard.mjs'],
8
+ claude: ['CLAUDE.md', ...WORKFLOW_SKILLS],
9
+ codex: [...SHARED, '.codex/hooks.json', '.codex/sketchbook-guard.mjs'],
10
10
  gemini: [...SHARED, 'GEMINI.md', '.gemini/settings.json', '.gemini/sketchbook-guard.mjs'],
11
- copilot: [...SHARED, SKILL, '.github/copilot-instructions.md', '.github/hooks/sketchbook.json', '.github/hooks/sketchbook-guard.mjs'],
11
+ copilot: [...SHARED, '.github/copilot-instructions.md', '.github/hooks/sketchbook.json', '.github/hooks/sketchbook-guard.mjs'],
12
12
  trae: [...SHARED, '.trae/rules/sketchbook.md'],
13
13
  jetbrains: [...SHARED, '.aiassistant/rules/sketchbook.md'],
14
14
  generic: SHARED,
@@ -80,7 +80,8 @@ export function selectedAgentProfiles(root) {
80
80
  if (found('GEMINI.md', /Sketchbook project instructions/) || found('.gemini/settings.json', /sketchbook-guard|harness\/agent\/gemini-guard/)
81
81
  || found('.gemini/sketchbook-guard.mjs', /gemini-guard/))
82
82
  profiles.push('gemini');
83
- if (found('.github/copilot-instructions.md', /AGENT-WORKFLOWS\.md/) || found('.github/hooks/sketchbook.json', /sketchbook-guard/)
83
+ // The source checkout links to the template, not an installed root-level workflow.
84
+ if (found('.github/copilot-instructions.md', /(?:^|[^/\w-])(?:\.\.?\/)?AGENT-WORKFLOWS\.md\b/) || found('.github/hooks/sketchbook.json', /sketchbook-guard/)
84
85
  || found('.github/hooks/sketchbook-guard.mjs', /sketchbook/i))
85
86
  profiles.push('copilot');
86
87
  if (found('.trae/rules/sketchbook.md', /AGENT-WORKFLOWS\.md/))
@@ -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
  ],
@@ -35,7 +35,7 @@ export declare function ingestVerify<R extends IngestReadback>(root: string, rea
35
35
  readFile: string | null;
36
36
  stale: unknown;
37
37
  wrongFile: boolean;
38
- tool: "none" | "figma" | undefined;
38
+ tool: "figma" | "none" | undefined;
39
39
  checkedAt: string;
40
40
  method: string;
41
41
  specHash: string;
@@ -65,6 +65,8 @@ export function installed(root) {
65
65
  const config = parseJson(read(join(root, 'harness.config.json')) ?? '{}');
66
66
  const files = [
67
67
  ['.agents/skills/sketchbook/SKILL.md', 'Portable Agent Skill routes Sketchbook tasks to the project workflows.'],
68
+ ['.agents/skills/contract-author/SKILL.md', 'Shared workflow for drafting and validating a component contract.'],
69
+ ['.agents/skills/component-builder/SKILL.md', 'Shared workflow for implementing, testing and reviewing a component.'],
68
70
  ['CLAUDE.md', 'Claude Code project instructions and the design-system index.'],
69
71
  ['AGENTS.md', 'Shared project instructions for coding agents; see AGENT-WORKFLOWS.md for task guidance.'],
70
72
  ['AGENT-WORKFLOWS.md', 'Provider-neutral component, token, kit and design workflows, with references to detailed guidance.'],
@@ -113,7 +115,7 @@ export function installed(root) {
113
115
  return { areas: areas.filter((a) => a.items.length) };
114
116
  }
115
117
  export function installedMarkdown(data) {
116
- const lines = ['# What Sketchbook installed', '', '<!-- Generated by sketchbook init when the project was created. Later changes are not reflected automatically. -->', '', 'This is the initial installation inventory. After adding, removing, restoring, or customizing files, inspect the project and run `npx sketchbook doctor` for its current status.', ''];
118
+ const lines = ['# What Sketchbook installed', '', '<!-- Generated by sketchbook init when the project was created. Later changes are not reflected automatically. -->', '', 'Use this list to see what Sketchbook set up when you created the project. Run `npx sketchbook doctor` for the current setup after changing or restoring files.', ''];
117
119
  for (const a of data.areas)
118
120
  lines.push(`## ${a.title} (${a.items.length})`, '', ...a.items.map((i) => `- **${i.name}**: ${i.what}`), '');
119
121
  return lines.join('\n');
@@ -52,8 +52,8 @@ export async function inputsHash(root) {
52
52
  }
53
53
  return h.digest('hex');
54
54
  }
55
- // What the docs site is built from: its pages and assets, the generators, the CLI reference and the brand (playground defaults).
56
- const DOCS_FILES = ['docs/cli.md', 'brand.config.json'];
55
+ // The docs build reads its pages, assets, generators, CLI reference, brand defaults and package version.
56
+ const DOCS_FILES = ['docs/cli.md', 'brand.config.json', 'package.json'];
57
57
  export async function docsInputsHash(root) {
58
58
  const files = [];
59
59
  await walk(root, 'apps/docs/content', files, /\.(json|md|html|css|js|svg|fig)$/);
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$description": "Who owns which files (SB-0048, SB-0099). sketchbook upgrade replaces harness-owned files and only reports team-owned and shared ones, which it never touches. Paths match top-down: team wins over harness, except exact harness paths (docs/cli.md and the schemas in spec/schemas, which a project keeps only as editor hints of the engine's). harness/** and scripts/** are the engine: a project runs them from node_modules. move-to-.claude/** is the Claude layer before Claude installs it into .claude/.",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "harness": [
5
5
  "harness/**",
6
6
  ".claude/skills/**",
@@ -45,6 +45,8 @@
45
45
  ".trae/rules/sketchbook.md",
46
46
  ".aiassistant/rules/sketchbook.md",
47
47
  ".agents/skills/sketchbook/SKILL.md",
48
+ ".agents/skills/contract-author/SKILL.md",
49
+ ".agents/skills/component-builder/SKILL.md",
48
50
  "AGENT-WORKFLOWS.md",
49
51
  ".codex/hooks.json",
50
52
  ".codex/sketchbook-guard.mjs",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "blank",
3
3
  "title": "Blank",
4
- "for": "Teams designing every component from zero.",
4
+ "for": "Build every component yourself, starting with an empty library.",
5
5
  "foundations": null,
6
6
  "components": "none",
7
7
  "kits": "none",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "foundations",
3
3
  "title": "Foundations first",
4
- "for": "Teams settling tokens before any component: foundations, their Storybook pages and Figma variables.",
4
+ "for": "Settle your tokens first and explore them in Storybook or your design file.",
5
5
  "foundations": null,
6
6
  "components": "none",
7
7
  "kits": "none",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "from-codebase",
3
3
  "title": "From a codebase",
4
- "for": "Teams with a product: audit its CSS and propose foundations from the values it repeats; the library and kits stay as they are.",
4
+ "for": "Audit your product CSS and review proposed foundations. The library and kits are included.",
5
5
  "foundations": null,
6
6
  "components": "all",
7
7
  "kits": "all",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "import",
3
3
  "title": "Import tokens",
4
- "for": "Teams with tokens already (DTCG / Tokens Studio, CSS variables): import them; the library and kits stay.",
4
+ "for": "Bring existing tokens from DTCG, Tokens Studio, or CSS variables. The library and kits are included.",
5
5
  "foundations": null,
6
6
  "components": "all",
7
7
  "kits": "all",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "library+kits",
3
3
  "title": "Library and template kits",
4
- "for": "Product teams that need screens fast: every component plus page templates.",
4
+ "for": "Start with every component and page templates you can adapt.",
5
5
  "foundations": null,
6
6
  "components": "all",
7
7
  "kits": "all",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "library",
3
3
  "title": "Reference library",
4
- "for": "Teams that want a working library now and rebrand it later (default).",
4
+ "for": "Start with a working component library and make it yours. This is the default.",
5
5
  "foundations": null,
6
6
  "components": "all",
7
7
  "kits": "none",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "pick",
3
3
  "title": "Pick components",
4
- "for": "Teams that need a subset: the chosen components (--components a,b) and what they depend on.",
4
+ "for": "Choose the components you need with --components. Sketchbook includes their dependencies.",
5
5
  "foundations": null,
6
6
  "components": [],
7
7
  "kits": "none",
@@ -16,7 +16,7 @@ This design system started from Sketchbook: the default (UI and theme following
16
16
  - `generated/**`, `src/components/*/*.styles.ts`, `src/index.ts` (`npm run generate`).
17
17
 
18
18
  ## Commands
19
- - `sketchbook` is the engine's CLI, installed in `node_modules` (a devDependency): run it as `npm run sketchbook -- <command>` (or `npx sketchbook <command>`). `sketchbook help <cmd>` for options (reference `docs/cli.md`); `--json` and `--dry-run` on commands.
19
+ - `sketchbook` is the engine's CLI, installed in `node_modules` (a devDependency): run it as `npm run sketchbook -- <command>` (or `npx sketchbook <command>`). `sketchbook help <cmd>` for options (reference `docs/cli.md`); `--json` is available on every command, and `--dry-run` where supported.
20
20
  - `sketchbook status`, `doctor`, `check`; `sketchbook add|remove|list`, `sketchbook kits list|add|remove`; `sketchbook tokens …`; `sketchbook explain <thing>`; `sketchbook generate` rebuilds the outputs.
21
21
  - `sketchbook init` again puts back what is missing and never overwrites. `npm update` brings a newer engine; `sketchbook upgrade` then refreshes the harness-owned files here (the Claude layer, the commit hook, `docs/cli.md`, the schemas); yours are never touched.
22
22
  - `npm run check`: deterministic checks (exit 0 pass, 1 fail, 2 pass with overrides); it also runs before every commit (`.githooks/pre-commit`).
@@ -7,4 +7,4 @@ description: Work on a Sketchbook design-system project using its component cont
7
7
 
8
8
  Read `AGENT-WORKFLOWS.md` at the project root for the relevant task and the project's `harness.config.json` for enabled workflow gates. Use `npx sketchbook help` for the installed CLI's commands and options. Treat the spec and decisions as the source of truth and validate changes with the checks appropriate to the task.
9
9
 
10
- If the project also includes the Claude Code integration, consult the matching skill or rule in `move-to-.claude/` while staged or `.claude/` once installed, as described in `AGENT-WORKFLOWS.md`. Those files may name Claude-only tools, model aliases, hooks or delegation; apply the underlying workflow using the current agent's available capabilities and permissions. Report any required step that could not be performed.
10
+ For component contracts or implementation, load the existing `contract-author` or `component-builder` skill. If your client cannot discover skills, read the matching `SKILL.md` under `.agents/skills/` in the project root. Client-specific integrations may add capabilities, but do not replace the shared workflow.
@@ -20,7 +20,7 @@ For a catalog component wanted as shipped, use `npx sketchbook add <name> --dry-
20
20
 
21
21
  ## Task routing
22
22
 
23
- When the project includes the Claude Code integration, the named skills below provide detailed workflows. Read the matching skill when available; use the local agent's own capabilities and permissions to perform its steps.
23
+ For contracts and implementation, use the shared `contract-author` and `component-builder` Agent Skills. If your client cannot load them natively, read their `SKILL.md` files under `.agents/skills/`. In the Sketchbook source checkout those same files live at the repository root. The other named skills below provide additional guidance when the project includes the Claude Code integration. Use the local agent's own capabilities and permissions to perform the steps.
24
24
 
25
25
  | Task | Existing skill |
26
26
  | --- | --- |
@@ -48,6 +48,6 @@ The staged or installed `commands/` directory also contains the original instruc
48
48
 
49
49
  ## Detailed guidance and existing workflows
50
50
 
51
- When the Claude Code integration is selected, its Sketchbook material is available under `move-to-.claude/` while staged, or `.claude/` after installation. Read the relevant rule in `rules/` and skill in `skills/<name>/SKILL.md` for detailed requirements. For example: `contract-first`, `planning-gate`, `test-first`, `form-associated-controls`, `spec-is-source`, `tokens-through-the-harness`, and `figma-fidelity` are rule files; `contract-author`, `component-builder`, `playwright-worker`, `a11y-checker`, `foundations`, `kits`, `design-figma`, `review-rangers`, and `security-guardian` are skills. The other skills and command descriptions are listed in `docs/harness.md`.
51
+ When the Claude Code integration is selected, its Sketchbook material is available under `move-to-.claude/` while staged, or `.claude/` after installation. Read the relevant rule in `rules/` and skill in `skills/<name>/SKILL.md` for detailed requirements. For example: `contract-first`, `planning-gate`, `test-first`, `form-associated-controls`, `spec-is-source`, `tokens-through-the-harness`, and `figma-fidelity` are rule files; `contract-author`, `component-builder`, `playwright-worker`, `a11y-checker`, `foundations`, `kits`, `design-figma`, `review-rangers`, and `security-guardian` are skills. In a project created by `sketchbook init`, `docs/harness.md` lists the initial installation; later changes may not be reflected. In the Sketchbook source checkout, inspect `.claude/skills/` and `.claude/commands/` instead. Use `sketchbook doctor` for current project setup.
52
52
 
53
53
  These files may contain Claude-specific tool names, model aliases, hooks, slash commands, and delegation instructions. Translate the underlying task into capabilities actually available in the current agent; do not claim that a hook or independent review ran when it did not. If delegation is unavailable or unauthorized, perform the applicable steps directly and report any unmet independent-review requirement. Rules and skills are guidance, while the deterministic CLI checks and configured Git hooks provide tool-independent verification.
@@ -1,17 +1,11 @@
1
1
  # Getting started
2
2
 
3
- This walkthrough is for an initialized design-system project. Follow the [Quickstart](https://sketchbook-docs.vercel.app/start/quickstart/) to create a project with `@usesketchbook/cli` from npm. `init` adds the CLI as a dev dependency and writes `docs/harness.md` with the initial installation inventory.
3
+ Start in your design-system folder. Run `npx sketchbook status` to see your brand and components, then follow the steps below to make and preview your first change. To create a project, follow the [Quickstart](https://sketchbook-docs.vercel.app/start/quickstart/).
4
4
 
5
- Coding agents can use `AGENTS.md` and `AGENT-WORKFLOWS.md`. The Claude Code layer is optional, and hook coverage varies by client. Run `npx sketchbook doctor` to inspect the local setup.
6
-
7
- In JetBrains AI Assistant chat, verify that the Sketchbook rule is set to **Always** under Settings → Tools → AI Assistant → Rules; check response attachments to confirm it is included. Existing project rules are preserved during init and upgrade.
8
-
9
- For Codex, verify hook trust and activation. New projects include a subdirectory launcher that runs only the shipped adapter (allowing line-ending differences); existing or customized hook settings are preserved and may need a deliberate update. `npx sketchbook doctor` reports the recognized launcher and warns when the adapter will be skipped. The guard does not cover shell edits or settled decisions.
10
-
11
- For a design system inside an existing Git repository, Copilot hook discovery varies by workspace and client; cloud and repository-root sessions need a root hook configuration. If your team wants to enable the nested project's edit guard, see the **Copilot repository hooks for an adopted app** section in the engine package's `docs/agent-compatibility.md` for a root configuration example. Review existing hooks before adding a separate file; initialization never changes them.
5
+ In a project created by `sketchbook init`, open `docs/harness.md` to see what init installed; this snapshot does not automatically reflect later changes. Run `npx sketchbook status` and `npx sketchbook doctor` for the current project and setup. If you selected an agent profile, confirm what your client loaded. [Agent compatibility](https://sketchbook-docs.vercel.app/concepts/agent-compatibility/)
12
6
 
13
7
  ## 1. What you are editing
14
- | You edit | It controls | Never edit (generated) |
8
+ | You edit | It controls | Sketchbook generates |
15
9
  | --- | --- | --- |
16
10
  | `brand.config.json` | every foundation (color, type, spacing, radius, density, motion …), as a preset or your own values | `spec/tokens/foundation/*` |
17
11
  | `spec/tokens/semantic/*.tokens.json` | what each color or size means, per light/dark mode | `generated/**` |
@@ -33,18 +27,21 @@ Sketchbook is a first draft: start from wherever you are, and edit or redo the d
33
27
 
34
28
  To see what your current project contains, run `npx sketchbook status`.
35
29
 
36
- ## 3. Make the foundations yours (the Foundations studio)
37
- `/foundations` in Claude Code walks through color, typography, spacing, radius, density, elevation, motion, layout grid, icons and z-index. Modes: `guided` (one question at a time, each with a recommendation), `preset` (pick a standard from the catalog), `expert` (your own values), `import` (bring tokens), `scratch` (start the foundations from zero; components keep working), `roast` (a fresh-eyes critique against the standards). `/roast-foundations` and `/import-tokens <file>` are shortcuts. Without Claude:
30
+ ## 3. Change your first foundation
31
+
32
+ Preview a primary color change and apply it when you’re ready.
33
+
38
34
  ```sh
39
- npx sketchbook tokens presets spacing
40
- npx sketchbook tokens preset spacing grid-8 --dry-run
35
+ npx sketchbook tokens set color.primary "#0F766E" --dry-run
41
36
  npx sketchbook tokens set color.primary "#0F766E"
42
- npx sketchbook tokens diff
37
+ npx sketchbook check
43
38
  ```
44
- Every change regenerates the foundation layer (color ramps in OKLCH, type and spacing scales), rebuilds `generated/css/tokens.css` and runs the checks. If a color pair fails contrast, the check names the pair and the nearest passing step. Run `npx sketchbook help tokens` for every option.
45
39
 
46
- ## 4. Look at it
47
- `npm run storybook`, then switch Mode in the toolbar. `Foundations/*` pages show each foundation; each component's page shows its contract summary, controls and every state.
40
+ If a color pair fails contrast, the check names the pair and suggests a passing step. Run `npx sketchbook tokens impact color.primary` to see what uses the color. See the [foundations guide](https://sketchbook-docs.vercel.app/guides/foundations/) for presets and other values you can change.
41
+
42
+ ## 4. See what changed
43
+
44
+ Run `npm run storybook` and open **Foundations → Color**. Switch **Mode** in the toolbar and compare how the new color is used in light and dark.
48
45
 
49
46
  ## 5. Trace any value
50
47
  ```sh
@@ -54,11 +51,11 @@ npx sketchbook explain SB-0009
54
51
  ```
55
52
 
56
53
  ## 6. Add or change a component
57
- `npx sketchbook add <name>` installs a reference component from the catalog; `npx sketchbook kits` manages page templates. To design a new one, follow `AGENT-WORKFLOWS.md` or use `/add <Name>` in Claude Code; the flow for a new component is always: contract → `npm run check` → plan → tests written first and seen failing → code → green → review → `beta`.
54
+ `npx sketchbook add <name>` installs a reference component from the catalog; `npx sketchbook kits` manages page templates. To design a new component, start with the contract and follow the project’s enabled planning and test-first gates. If you selected an agent profile, use `contract-author` and `component-builder` under `.agents/skills/`. If you selected a shared agent profile, `AGENT-WORKFLOWS.md` covers other workflows; if you selected and activated the Claude integration, you can also use `/add <Name>` in Claude Code. A core-only project includes neither integration; use `npx sketchbook init --agent <profile>` to add one, or follow the [component guide](https://sketchbook-docs.vercel.app/guides/add-component/) without an agent.
58
55
 
59
56
  ## 7. Keep the design file in step
60
57
 
61
58
  Download the [example Figma file](https://sketchbook-docs.vercel.app/assets/Sketchbook.fig) to explore a reference snapshot. To sync, open your own file in Figma, connect the Figma MCP, and set the target with `npx sketchbook swap design figma --file <your file key>` or the `SKETCHBOOK_FIGMA_FILE` environment variable. Run `npx sketchbook help sync` for the workflow. Check D1 reports drift for a configured target. [Figma setup](https://sketchbook-docs.vercel.app/concepts/design-file/).
62
59
 
63
- ## 8. Swap a piece
64
- `npx sketchbook swap tokens plain` (no Style Dictionary), `npx sketchbook swap design none` (no design file). The spec doesn't change.
60
+ ## 8. Change an adapter
61
+ `npx sketchbook swap tokens plain` (no Style Dictionary), `npx sketchbook swap design none` (no design file). Both commands use your existing spec.
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "@usesketchbook/cli",
3
- "version": "0.2.1",
3
+ "version": "0.4.0",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "@usesketchbook/cli",
9
- "version": "0.2.1",
9
+ "version": "0.4.0",
10
10
  "license": "MIT",
11
11
  "dependencies": {
12
12
  "lucide-static": "1.76.0",
@@ -52,10 +52,13 @@ export function matrixOf(contract: Contract, render: (combo: Record<string, stri
52
52
  // The component's contract.md as its docs page: front matter, the typed-spec link and the
53
53
  // agents-only section are dropped. The page updates whenever the contract changes.
54
54
  export function docsFrom(markdown: string) {
55
- return markdown
55
+ const contract = markdown
56
56
  .replace(/^---[\s\S]*?---\s*/, '')
57
57
  .replace(/^# .*\n+/, '')
58
58
  .replace(/ ?Typed spec: \[contract\.json\]\(\.\/contract\.json\)\.?/, '')
59
59
  .replace(/\n## Spec for agents[\s\S]*$/, '\n')
60
60
  .trim();
61
+ return `Open a story to try the component, then use its contract below to look up behavior and accessibility.
62
+
63
+ ${contract}`;
61
64
  }
@@ -11,7 +11,7 @@ export const Page: StoryObj = {
11
11
  foundationPage({
12
12
  id: 'border-width',
13
13
  intro: html`<p>
14
- Border widths are the few line weights the system draws with: hairline borders around fields and surfaces, a thicker line for emphasis
14
+ Compare the field border with the focus ring below. Border widths are the few line weights the system draws with: hairline borders around fields and surfaces, a thicker line for emphasis
15
15
  and indicators, and the focus ring. A focus ring must stay visible next to every surface it can sit on, so it is wider than a plain border.
16
16
  </p>`,
17
17
  samples: gallery(pageTokens('border-width'), (v) => html`<div style="width:4rem;height:2.5rem;border:${v} solid var(--sb-color-foreground)"></div>`),
@@ -105,7 +105,7 @@ export const Page: StoryObj = {
105
105
  id: 'color',
106
106
  configHint: 'color',
107
107
  intro: html`<p>
108
- Color has two layers. The <strong>foundation</strong> is a set of ramps, one per hue, each running from a near-white step to a near-black one;
108
+ Switch Mode in the toolbar and compare the primary, background, and border roles. Color has two layers. The <strong>foundation</strong> is a set of ramps, one per hue, each running from a near-white step to a near-black one;
109
109
  its values are generated from the brand inputs. The <strong>semantic</strong> layer names roles (background, primary, border, ring) and
110
110
  points each one at a ramp step, separately for every mode. Components only ever use semantic or component tokens.
111
111
  </p>
@@ -19,7 +19,7 @@ export const Page: StoryObj = {
19
19
  id: 'density',
20
20
  configHint: 'density',
21
21
  intro: html`<p>
22
- Density sets how much room interactive elements take: the height of buttons, inputs and selects, and the sizes of fixed parts such as
22
+ Compare the same controls at each density. Density sets how much room interactive elements take: the height of buttons, inputs and selects, and the sizes of fixed parts such as
23
23
  switches and avatars. The foundation is a plain size scale; the semantic layer picks a step for each control size, and the density setting
24
24
  moves those picks together. Compact layouts fit more on screen, but pointer targets should stay at least 24px.
25
25
  </p>
@@ -11,7 +11,7 @@ export const Page: StoryObj = {
11
11
  foundationPage({
12
12
  id: 'elevation',
13
13
  intro: html`<p>
14
- Elevation shows that something floats above the page: menus, popovers, dialogs. Each step is a shadow; the semantic elevation tokens say
14
+ Compare the shadows across surfaces and check how clearly each surface stands out in dark mode. Elevation shows that something floats above the page: menus, popovers, dialogs. Each step is a shadow; the semantic elevation tokens say
15
15
  which step a layer uses. Shadows are hard to see on dark backgrounds, so floating surfaces also keep a border and their own background.
16
16
  </p>`,
17
17
  samples: gallery(pageTokens('elevation'), (v) => html`<div class="box" style="width:6rem;height:4rem;border-radius:var(--sb-radius-surface);box-shadow:${v}"></div>`),
@@ -19,7 +19,7 @@ export const Page: StoryObj = {
19
19
  foundationPage({
20
20
  id: 'icon-sizes',
21
21
  intro: html`<p>
22
- Icon sizes keep glyphs in proportion with the text and controls around them: the default icon sits next to body text, smaller ones go in
22
+ Compare the glyph sizes before choosing one for a control. Icon sizes keep glyphs in proportion with the text and controls around them: the default icon sits next to body text, smaller ones go in
23
23
  compact controls, larger ones stand alone. An icon that can be clicked needs a hit area larger than its glyph; the control around it
24
24
  provides that, so icon size and target size are separate decisions.
25
25
  </p>`,
@@ -28,8 +28,8 @@ export const Page: StoryObj = {
28
28
  return foundationPage({
29
29
  id: 'layout-grid',
30
30
  intro: html`<p>
31
- The layout grid divides a page into columns separated by gutters, with a margin on each side. Page sections and cards snap to whole
32
- columns, so content lines up across a screen. Below is the grid at the width of this page; resize the window to see the columns flex.
31
+ Resize the Storybook preview to see how the columns and gutters adapt. The layout grid divides a page into columns separated by gutters, with a margin on each side. Page sections and cards snap to whole
32
+ columns, so content lines up across a screen.
33
33
  </p>`,
34
34
  samples: html`${STYLE}
35
35
  <section aria-labelledby="sbf-layout">
@@ -76,9 +76,8 @@ export const Page: StoryObj = {
76
76
  return foundationPage({
77
77
  id: 'motion',
78
78
  intro: html`<p>
79
- Motion is a handful of durations and easing curves. Short durations suit small feedback (a hover, a toggle); longer ones suit larger
79
+ Press Play to compare the curves on the same movement. Motion is a handful of durations and easing curves. Short durations suit small feedback (a hover, a toggle); longer ones suit larger
80
80
  movement (a panel sliding in). Easing shapes the speed over time: things that enter slow down at the end, things that leave speed up.
81
- Press Play to compare them.
82
81
  </p>
83
82
  <p>
84
83
  People can ask their system for reduced motion. Components then drop movement and keep only the change of state; these demos do the same and
@@ -11,7 +11,7 @@ export const Page: StoryObj = {
11
11
  foundationPage({
12
12
  id: 'opacity',
13
13
  intro: html`<p>
14
- Opacity steps fade an element without changing its color: disabled controls, loading pulses, overlays. Fading lowers contrast, so a faded
14
+ Compare each opacity step against the same surface. Opacity steps fade an element without changing its color: disabled controls, loading pulses, overlays. Fading lowers contrast, so a faded
15
15
  control must still be recognisable, and text that people need to read should not rely on opacity alone.
16
16
  </p>`,
17
17
  samples: gallery(pageTokens('opacity'), (v) => html`<div class="box" style="width:4rem;height:2.5rem;position:relative"><div class="fill" style="position:absolute;inset:0;opacity:${v}"></div></div>`),
@@ -12,7 +12,7 @@ export const Page: StoryObj = {
12
12
  id: 'radius',
13
13
  configHint: 'radius',
14
14
  intro: html`<p>
15
- Radius rounds the corners of controls and surfaces. The foundation is a short scale from square to fully round; the semantic layer says
15
+ Look at the corners on the control, surface, and pill examples. Radius rounds the corners of controls and surfaces. The foundation is a short scale from square to fully round; the semantic layer says
16
16
  which step each kind of element uses (control, surface, pill), so changing the radius style restyles every component at once. Keep nested
17
17
  corners consistent: an inner corner looks right when it is the outer radius minus the padding between them.
18
18
  </p>`,
@@ -39,7 +39,7 @@ export const Page: StoryObj = {
39
39
  id: 'spacing',
40
40
  configHint: 'spacing',
41
41
  intro: html`<p>
42
- Spacing is one scale of steps built on a base unit. Every gap, padding and margin in a component comes from it, which keeps layouts on a
42
+ Compare the raw steps with the gaps and insets you use in a layout. Spacing is one scale of steps built on a base unit. Every gap, padding and margin in a component comes from it, which keeps layouts on a
43
43
  shared rhythm. Foundation step names are multiples of the base unit (step 4 is four units); semantic tokens name the job instead: control
44
44
  padding, stack gaps, insets.
45
45
  </p>`,
@@ -83,7 +83,7 @@ export const Page: StoryObj = {
83
83
  id: 'typography',
84
84
  configHint: 'typography',
85
85
  intro: html`<p>
86
- Typography is a family pair (text and code), a size scale, a few weights, line heights and letter spacing. The foundation holds the raw
86
+ Compare the body and heading roles at the same viewport width. Typography is a family pair (text and code), a size scale, a few weights, line heights and letter spacing. The foundation holds the raw
87
87
  scale; the semantic layer gives sizes jobs (body, control, heading-1 to heading-4, caption) so a component asks for "a heading" rather than
88
88
  "24px". Sizes are shown in px and in rem against the 16px browser default.
89
89
  </p>`,
@@ -18,7 +18,7 @@ export const Page: StoryObj = {
18
18
  return foundationPage({
19
19
  id: 'z-index',
20
20
  intro: html`<p>
21
- Z-index decides what covers what when elements overlap. The foundation is a few spaced numbers; the semantic layer names each layer by role
21
+ Read from the bottom of the stack to find which layers can cover a dropdown. Z-index decides what covers what when elements overlap. The foundation is a few spaced numbers; the semantic layer names each layer by role
22
22
  (dropdown, sticky header, overlay, modal, toast) so no component invents its own number. The list below runs from the bottom of the stack to
23
23
  the top.
24
24
  </p>`,
@@ -4,9 +4,29 @@ import { mkdtemp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promis
4
4
  import { tmpdir } from 'node:os';
5
5
  import { join } from 'node:path';
6
6
  import { spawnSync } from 'node:child_process';
7
- import { renderAgentSetup } from '../lib/agent-config.mjs';
7
+ import { renderAgentSetup, selectedAgentProfiles } from '../lib/agent-config.mjs';
8
8
  import { nativeHookStatus } from '../lib/agent-diagnostics.mjs';
9
9
  import { packedFiles, ROOT, sourceRepoOnly } from './helpers.mjs';
10
+ test('a checkout Copilot entry point is not mistaken for an installed project profile', sourceRepoOnly, async () => {
11
+ const dir = await mkdtemp(join(tmpdir(), 'sketchbook-agent-profile-'));
12
+ try {
13
+ await mkdir(join(dir, '.github/hooks'), { recursive: true });
14
+ const name = '.github/copilot-instructions.md';
15
+ await writeFile(join(dir, name), await readFile(join(ROOT, name)));
16
+ assert.deepEqual(selectedAgentProfiles(dir), []);
17
+ const template = join(ROOT, 'harness/templates/project', name);
18
+ await writeFile(join(dir, name), await readFile(template));
19
+ assert.deepEqual(selectedAgentProfiles(dir), ['copilot']);
20
+ await writeFile(join(dir, name), await readFile(join(ROOT, name)));
21
+ await writeFile(join(dir, '.github/hooks/sketchbook.json'), await readFile(join(ROOT, 'harness/templates/project/.github/hooks/sketchbook.json')));
22
+ assert.deepEqual(selectedAgentProfiles(dir), ['copilot']);
23
+ await writeFile(join(dir, 'harness.config.json'), JSON.stringify({ agentProfiles: [] }));
24
+ assert.deepEqual(selectedAgentProfiles(dir), []);
25
+ }
26
+ finally {
27
+ await rm(dir, { recursive: true, force: true });
28
+ }
29
+ });
10
30
  test('native agent adapters use a renamed scoped engine and retain their edit protections', sourceRepoOnly, async () => {
11
31
  const dir = await mkdtemp(join(tmpdir(), 'sketchbook-renamed-agent-'));
12
32
  const name = '@acme/engine';
@@ -3,6 +3,22 @@ import assert from 'node:assert/strict';
3
3
  import { readFile, readdir } from 'node:fs/promises';
4
4
  import { join } from 'node:path';
5
5
  import { ROOT, sourceRepoOnly } from './helpers.mjs';
6
+ import { frontmatter } from '../lib/claude-layer.mjs';
7
+ test('shared component skills use standard frontmatter and Claude wrappers lead to the same source', sourceRepoOnly, async () => {
8
+ for (const name of ['contract-author', 'component-builder']) {
9
+ const path = `.agents/skills/${name}/SKILL.md`;
10
+ const source = await readFile(join(ROOT, path), 'utf8');
11
+ const data = frontmatter(source);
12
+ assert.deepEqual(Object.keys(data ?? {}).sort(), ['description', 'name']);
13
+ assert.equal(data?.name, name);
14
+ const description = data?.description;
15
+ assert.ok(typeof description === 'string' && description.length > 0 && description.length <= 400);
16
+ assert.match(source, /features\.planningGate/);
17
+ assert.doesNotMatch(source, /\.claude\/|`Agent`|haiku|sonnet|opus/);
18
+ const wrapper = await readFile(join(ROOT, '.claude/skills', name, 'SKILL.md'), 'utf8');
19
+ assert.ok(wrapper.includes(`(../../../${path})`));
20
+ }
21
+ });
6
22
  // Keep the portable routing map in sync with the workflows shipped in the Claude layer.
7
23
  test('portable guidance names every shipped skill and slash workflow', sourceRepoOnly, async () => {
8
24
  const guidance = await readFile(join(ROOT, 'harness/templates/project/AGENT-WORKFLOWS.md'), 'utf8');