@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.
- package/.agents/skills/component-builder/SKILL.md +16 -0
- package/.agents/skills/contract-author/SKILL.md +16 -0
- package/.claude/commands/add.md +1 -5
- package/.claude/skills/component-builder/SKILL.md +15 -101
- package/.claude/skills/contract-author/SKILL.md +14 -132
- package/README.md +14 -30
- package/docs/agent-compatibility.md +43 -9
- package/docs/cli.md +31 -31
- package/harness/catalog/kits/dashboard/files/{63cde4f28d1c141c401d → 09d34e607ea6836480d1} +1 -1
- package/harness/catalog/kits/dashboard/files/{11a5797c4c9189b59fbe → 2239c4e4f1d873b03305} +1 -1
- package/harness/catalog/kits/dashboard/files/{864acc7ce20f541cf67c → 567a658f80560e3945c6} +1 -1
- package/harness/catalog/kits/dashboard/manifest.json +4 -4
- package/harness/catalog/kits/data-table/files/{b5d5d7f18347734138e0 → 35c832acd45c642705b1} +1 -1
- package/harness/catalog/kits/data-table/files/{36bac8f8e53119768b2e → aaf2d576ed0b53013ac3} +1 -1
- package/harness/catalog/kits/data-table/files/{1786ba4d3e0dba1d6a1f → ac8792b3aa3a43002c5e} +1 -1
- package/harness/catalog/kits/data-table/manifest.json +4 -4
- package/harness/catalog/kits/docs-article/files/{dbc2840f315f672e1d74 → 3c554edf05e9c8bb52c7} +1 -1
- package/harness/catalog/kits/docs-article/files/{7f36cb5f0d4f5e103bde → 9d0bb5a1be919431e8ce} +1 -1
- package/harness/catalog/kits/docs-article/files/{c2018b502a8094818d8f → e80ea70679e0065026d0} +1 -1
- package/harness/catalog/kits/docs-article/manifest.json +4 -4
- package/harness/catalog/kits/form-states/files/{b52fb2fc480f0c6352bd → 55a0558891d66e11c216} +1 -1
- package/harness/catalog/kits/form-states/files/{88252259f19ed675a0dc → 64566f1a9cb16592d296} +1 -1
- package/harness/catalog/kits/form-states/files/{b0b51ebf587b21fd89a1 → f086df13cb85411108a1} +1 -1
- package/harness/catalog/kits/form-states/manifest.json +4 -4
- package/harness/catalog/kits/onboarding/files/{e669d75a65f4d15d8289 → 738531c9cf4c8bfb9e28} +1 -1
- package/harness/catalog/kits/onboarding/files/{ce466020247ecf1ff5fe → b72445926f9763db6c4f} +1 -1
- package/harness/catalog/kits/onboarding/files/{322cf4dfc2ee0a035d85 → c969943667ca18e8b0d3} +1 -1
- package/harness/catalog/kits/onboarding/manifest.json +4 -4
- package/harness/catalog/kits/profile/files/{4aeca453e4792abf29de → 38a6ccd576aca5c96612} +1 -1
- package/harness/catalog/kits/profile/files/{0fdd3c14afbdadcf1969 → adccaa2829c56d7fa215} +1 -1
- package/harness/catalog/kits/profile/files/{5b58bb5f93ecf12d69ff → de99237cdcfb4ddef8dd} +1 -1
- package/harness/catalog/kits/profile/manifest.json +4 -4
- package/harness/catalog/kits/settings/files/{d2ebbd6e94570b2c6434 → 08c4411e3c8dbc9e614f} +1 -1
- package/harness/catalog/kits/settings/files/{b4a7a4ccdc59465b8de5 → d1cd9cf4acd3416e3f63} +1 -1
- package/harness/catalog/kits/settings/files/{1a5d639c6803e7d03acc → f325b6c93ce84d356228} +1 -1
- package/harness/catalog/kits/settings/manifest.json +4 -4
- package/harness/catalog/kits/sign-in/files/{ca224349b746c530f922 → 0ac413f342ed59e8f3d9} +1 -1
- package/harness/catalog/kits/sign-in/files/{552bdad5ce7559849e81 → 796309acee1d478d2692} +1 -1
- package/harness/catalog/kits/sign-in/files/{361745a3ed43c753c615 → a106d6104e40b13d7e82} +1 -1
- package/harness/catalog/kits/sign-in/manifest.json +4 -4
- package/harness/checks/run.mjs +1 -2
- package/harness/cli/commands/add.mjs +5 -3
- package/harness/cli/commands/api.d.mts +4 -4
- package/harness/cli/commands/api.mjs +1 -1
- package/harness/cli/commands/audit-css.mjs +1 -1
- package/harness/cli/commands/audit-decisions.mjs +1 -1
- package/harness/cli/commands/audit-page.mjs +1 -1
- package/harness/cli/commands/brand.mjs +1 -1
- package/harness/cli/commands/check.d.mts +1 -1
- package/harness/cli/commands/check.mjs +1 -1
- package/harness/cli/commands/docs.mjs +2 -2
- package/harness/cli/commands/doctor.d.mts +2 -2
- package/harness/cli/commands/doctor.mjs +7 -5
- package/harness/cli/commands/explain.mjs +1 -1
- package/harness/cli/commands/generate.mjs +1 -1
- package/harness/cli/commands/help.mjs +5 -5
- package/harness/cli/commands/icons.mjs +1 -1
- package/harness/cli/commands/init.d.mts +1 -1
- package/harness/cli/commands/init.mjs +4 -4
- package/harness/cli/commands/kits.mjs +3 -1
- package/harness/cli/commands/list.mjs +1 -1
- package/harness/cli/commands/prefix.mjs +1 -1
- package/harness/cli/commands/presets.mjs +1 -1
- package/harness/cli/commands/propagate.mjs +1 -1
- package/harness/cli/commands/remove.mjs +4 -2
- package/harness/cli/commands/selftest.mjs +1 -1
- package/harness/cli/commands/status.mjs +6 -4
- package/harness/cli/commands/swap.mjs +1 -1
- package/harness/cli/commands/sync.mjs +3 -3
- package/harness/cli/commands/tokens.mjs +9 -8
- package/harness/cli/commands/upgrade.mjs +7 -3
- package/harness/cli/docs.mjs +2 -2
- package/harness/cli/interactive.mjs +10 -10
- package/harness/cli/known-commands.json +26 -26
- package/harness/cli/presentation.d.mts +1 -1
- package/harness/cli/presentation.mjs +1 -1
- package/harness/cli/run.d.mts +3 -3
- package/harness/cli/run.mjs +5 -5
- package/harness/cli.mjs +0 -0
- package/harness/commands/add.mjs +1 -1
- package/harness/commands/bootstrap.mjs +4 -3
- package/harness/kits/index.json +8 -8
- package/harness/lib/agent-config.d.mts +1 -0
- package/harness/lib/agent-config.mjs +7 -6
- package/harness/lib/design/docs.mjs +2 -2
- package/harness/lib/design/sync.d.mts +1 -1
- package/harness/lib/installed.mjs +3 -1
- package/harness/lib/propagation.mjs +2 -2
- package/harness/manifest.json +3 -1
- package/harness/starters/blank.json +1 -1
- package/harness/starters/foundations.json +1 -1
- package/harness/starters/from-codebase.json +1 -1
- package/harness/starters/import.json +1 -1
- package/harness/starters/library+kits.json +1 -1
- package/harness/starters/library.json +1 -1
- package/harness/starters/pick.json +1 -1
- package/harness/templates/CLAUDE.md +1 -1
- package/harness/templates/project/.agents/skills/sketchbook/SKILL.md +1 -1
- package/harness/templates/project/AGENT-WORKFLOWS.md +2 -2
- package/harness/templates/project/docs/getting-started.md +17 -20
- package/harness/templates/project/package-lock.json +2 -2
- package/harness/templates/project/src/stories/contract.ts +4 -1
- package/harness/templates/project/src/stories/foundations/BorderWidth.stories.ts +1 -1
- package/harness/templates/project/src/stories/foundations/Color.stories.ts +1 -1
- package/harness/templates/project/src/stories/foundations/Density.stories.ts +1 -1
- package/harness/templates/project/src/stories/foundations/Elevation.stories.ts +1 -1
- package/harness/templates/project/src/stories/foundations/IconSizes.stories.ts +1 -1
- package/harness/templates/project/src/stories/foundations/LayoutGrid.stories.ts +2 -2
- package/harness/templates/project/src/stories/foundations/Motion.stories.ts +1 -2
- package/harness/templates/project/src/stories/foundations/Opacity.stories.ts +1 -1
- package/harness/templates/project/src/stories/foundations/Radius.stories.ts +1 -1
- package/harness/templates/project/src/stories/foundations/Spacing.stories.ts +1 -1
- package/harness/templates/project/src/stories/foundations/Typography.stories.ts +1 -1
- package/harness/templates/project/src/stories/foundations/ZIndex.stories.ts +1 -1
- package/harness/test/agent-config.test.mjs +21 -1
- package/harness/test/agent-guidance.test.mjs +16 -0
- package/harness/test/bootstrap.test.mjs +84 -15
- package/harness/test/checks.test.mjs +4 -1
- package/harness/test/claude-live.test.mjs +8 -3
- package/harness/test/cli.test.mjs +25 -5
- package/harness/test/copilot-live.test.mjs +12 -13
- package/harness/test/docs-reference.test.mjs +17 -0
- package/harness/test/opencode-live.test.mjs +25 -10
- package/harness/test/package.test.mjs +1 -0
- 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
|
|
6
|
-
const
|
|
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,
|
|
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,
|
|
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
|
-
|
|
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: `
|
|
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: '
|
|
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: "
|
|
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. -->', '', '
|
|
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
|
-
//
|
|
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)$/);
|
package/harness/manifest.json
CHANGED
|
@@ -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
|
+
"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": "foundations",
|
|
3
3
|
"title": "Foundations first",
|
|
4
|
-
"for": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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`
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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 |
|
|
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.
|
|
37
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
47
|
-
|
|
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
|
|
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.
|
|
64
|
-
`npx sketchbook swap tokens plain` (no Style Dictionary), `npx sketchbook swap design none` (no design file).
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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.
|
|
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');
|