@atelier-ui/create-workspace 0.4.0 → 0.4.2

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 (34) hide show
  1. package/CHANGELOG.md +27 -3
  2. package/package.json +1 -1
  3. package/src/generators/preset/files/claude/skills/figma-workspace-architect/SKILL.md +194 -0
  4. package/src/generators/preset/files/claude/skills/figma-workspace-architect/assets/audit-report-template.md +181 -0
  5. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-checklist.md +462 -0
  6. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-verify-queries.md +414 -0
  7. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-from-code-contract.md +87 -0
  8. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-workflow.md +260 -0
  9. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-sync.md +218 -0
  10. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-verify.md +152 -0
  11. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/component-design.md +198 -0
  12. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/decision-heuristics.md +262 -0
  13. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/iconography.md +150 -0
  14. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-generation.md +433 -0
  15. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-payload.md +490 -0
  16. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/migration-playbook.md +182 -0
  17. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/naming-and-file-structure.md +161 -0
  18. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/plugin-api-gotchas.md +79 -0
  19. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/scaffold-payload.md +279 -0
  20. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/sync-workflow.md +98 -0
  21. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/token-architecture.md +177 -0
  22. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/tool-map.md +398 -0
  23. package/src/generators/preset/files/claude/skills/uianatomy-mcp/SKILL.md +160 -0
  24. package/src/generators/preset/files/contracts/README.md +6 -6
  25. package/src/generators/preset/files/contracts/types.ts.template +9 -10
  26. package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/check-contracts.mjs +236 -223
  27. package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/figma-snapshot-contracts.mjs +107 -92
  28. package/src/generators/preset/files/tools/design-contracts/src/codespec.mjs +234 -0
  29. package/src/generators/preset/files/tools/design-contracts/src/config.mjs +63 -0
  30. package/src/generators/preset/files/tools/{scripts/lib → design-contracts/src}/docgen.mjs +78 -98
  31. package/src/generators/preset/files/tools/{scripts/lib/ts-eval.js → design-contracts/src/ts-eval.cjs} +3 -4
  32. package/src/generators/preset/files/tools/scripts/preflight.mjs +1 -1
  33. package/src/generators/preset/preset.js +79 -15
  34. package/src/generators/preset/preset.js.map +1 -1
@@ -1,20 +1,20 @@
1
1
  /**
2
- * Shared docgen plumbing (ADR-0121 §5 / S6(a)).
2
+ * Shared docgen plumbing.
3
3
  *
4
- * Extracted out of check-contracts.mjs so check-manifest-parity.mjs can reuse the
5
- * exact same recipe rather than re-deriving it: the framework-worker docgen call
6
- * for Angular/Vue (`@storybook/{angular-vite,vue3}/internal/docgen-worker`, a
7
- * story file as the entry point), `react-docgen`'s own `parse()` for React (the
8
- * worker's React export is the inactive react-component-meta engine in this
9
- * repo), and each framework's raw-payload normaliser into the common
10
- * `{ name, kind: 'enum'|'boolean'|'other', members, default, isOutput }` shape
11
- * check-contracts.mjs already established. Both scripts importing from one place
12
- * means they cannot silently diverge on what a framework's docgen payload means
13
- * — the exact drift class this repo's gates exist to prevent elsewhere.
4
+ * The recipe, kept in one place so every script that reads a component's API
5
+ * reads it the same way: the framework-worker docgen call for Angular/Vue
6
+ * (`@storybook/{angular-vite,vue3}/internal/docgen-worker`, a story file as the
7
+ * entry point), `react-docgen`'s own `parse()` for React (the worker's React
8
+ * export is the react-component-meta engine, which is not the default docgen
9
+ * path), and each framework's raw-payload normaliser into the common
10
+ * `{ name, kind: 'enum'|'boolean'|'other', members, default, isOutput }` shape.
11
+ * Scripts importing from one place cannot silently diverge on what a
12
+ * framework's docgen payload means.
14
13
  *
15
- * Every function here is parameterized (root, cwdRequire) rather than reading
16
- * module-level globals, so it works identically whichever script imports it and
17
- * from whatever cwd that script resolves its own framework packages.
14
+ * Every function here is parameterized (root, cwdRequire, story dirs) rather
15
+ * than reading module-level globals or paths derived from this file's own
16
+ * location, so it works identically whichever script imports it. The framework
17
+ * packages themselves are resolved from the consumer's install via `cwdRequire`.
18
18
  */
19
19
  'use strict';
20
20
 
@@ -41,19 +41,15 @@ export function collectStoryFilesUnder(dir) {
41
41
  }
42
42
 
43
43
  /**
44
- * Story files for `fw`: every `storiesDirs` root walked recursively when given
45
- * (a scaffold's one roster for its one framework), else the monorepo's
46
- * `libs/<fw>/src/lib` convention under `root`.
44
+ * Every story file under the `storiesDirs` roots (absolute paths), walked
45
+ * recursively, de-duplicated and sorted. The caller decides the roots — there
46
+ * is no default location.
47
47
  */
48
- export function findStoryFiles(fw, { root, storiesDirs } = {}) {
49
- if (storiesDirs) {
50
- const out = new Set();
51
- for (const dir of storiesDirs)
52
- for (const f of collectStoryFilesUnder(dir)) out.add(f);
53
- return [...out].sort();
54
- }
55
- const base = path.join(root, 'libs', fw, 'src', 'lib');
56
- return collectStoryFilesUnder(base).sort();
48
+ export function findStoryFiles(storiesDirs) {
49
+ const out = new Set();
50
+ for (const dir of storiesDirs)
51
+ for (const f of collectStoryFilesUnder(dir)) out.add(f);
52
+ return [...out].sort();
57
53
  }
58
54
 
59
55
  export function toRepoImportPath(absPath, root) {
@@ -63,9 +59,9 @@ export function toRepoImportPath(absPath, root) {
63
59
  /** Best-effort human-readable message for a caught value that might not be an
64
60
  * `Error` (a thrown string, a plain object, ...). Shared so a [DOCGEN-FAILED]
65
61
  * reason reads consistently across every catch site that reports one: this
66
- * file's own `makeWorkerDocgen()`, and check-contracts.mjs's / check-
67
- * manifest-parity.mjs's own try/catch around `reactParseFile()` (react-docgen
68
- * isn't guaranteed to throw an `Error` instance either). */
62
+ * file's own `makeWorkerDocgen()`, and a caller's own try/catch around
63
+ * `reactParseFile()` (react-docgen isn't guaranteed to throw an `Error`
64
+ * instance either). */
69
65
  export function errorMessage(e) {
70
66
  return e && e.message ? e.message : String(e);
71
67
  }
@@ -79,11 +75,10 @@ export function errorMessage(e) {
79
75
  * same way Node's own `node_modules` resolution does (parent directories,
80
76
  * `node_modules/<pkg>/package.json` at each). Returns that `node_modules/<pkg>`
81
77
  * directory, or `null` when `rawSpecifier` is missing/relative/absolute, when
82
- * the walk finds no matching install (e.g. a workspace tsconfig path alias
83
- * like this monorepo's own `@atelier-ui/*`, which has no real `node_modules`
84
- * entry at all), or when the matching `node_modules/<pkg>` entry is an
85
- * npm-workspaces SYMLINK back into the repo's own source (e.g. this repo's own
86
- * `node_modules/@atelier-ui/generators -> tools/generators`) — resolved via
78
+ * the walk finds no matching install (e.g. a workspace tsconfig path alias,
79
+ * which has no real `node_modules` entry at all), or when the matching
80
+ * `node_modules/<pkg>` entry is an npm-workspaces SYMLINK back into the
81
+ * repo's own source (`node_modules/@scope/pkg -> packages/pkg`) — resolved via
87
82
  * `fs.realpathSync` and classed as external only when the REAL path still
88
83
  * contains a `node_modules` path segment; a workspace symlink's real path
89
84
  * doesn't, so it's workspace code and must be docgen'd, not skipped.
@@ -91,7 +86,7 @@ export function errorMessage(e) {
91
86
  * Deliberately NOT `require.resolve`: a package's `exports` map makes that
92
87
  * throw for a subpath it doesn't list and for an ESM-only package resolved
93
88
  * through a CJS `createRequire` — exactly the packages this check exists to
94
- * catch (`@atelier-ui/angular` et al. in a real scaffold install). The
89
+ * catch (a component library installed from the registry). The
95
90
  * directory walk sidesteps both failure modes because it only needs to know
96
91
  * the package is INSTALLED, not import anything from it.
97
92
  */
@@ -149,18 +144,16 @@ export function resolveWithExtensions(base) {
149
144
  * Angular/Vue docgen via the Storybook framework worker, story file as the
150
145
  * entry point. The worker package itself is resolved from `cwdRequire`'s
151
146
  * node_modules (the caller's cwd), not this file's own directory, so a copy
152
- * dropped into a scaffold picks up the scaffold's own installed Storybook —
153
- * same portability rule check-contracts.mjs already followed.
147
+ * dropped into a workspace picks up that workspace's own installed Storybook.
154
148
  *
155
149
  * The returned function resolves to a DISCRIMINATED result rather than a bare
156
150
  * payload-or-null: `{ ok: true, payload }` on success, `{ ok: false, reason }`
157
151
  * for every failure mode — the provider throwing, an empty/falsy payload, or
158
152
  * `payload.error` being set. Collapsing all three into `null` (the shape this
159
- * function had until ADR-0124) is exactly what let a broken docgen worker
160
- * read as "no component here": both call sites treated `null` as "skip,
161
- * nothing to see" with no residual signal at all (ADR-0034's
162
- * roster-derivation convention, applied to this gate by ADR-0124). `reason`
163
- * is always a string, ready to drop straight into a finding message.
153
+ * function had at first) is exactly what let a broken docgen worker
154
+ * read as "no component here": every call site treated `null` as "skip,
155
+ * nothing to see" with no residual signal at all, so a gate's roster could
156
+ * shrink silently instead of failing. `reason` is always a string, ready to drop straight into a finding message.
164
157
  */
165
158
  export async function makeWorkerDocgen(fw, cwdRequire, root) {
166
159
  const spec =
@@ -291,7 +284,7 @@ export function normalizeVue(payload) {
291
284
  /**
292
285
  * React docgen tooling bound to one `cwdRequire`. `react-docgen` is required
293
286
  * lazily and from the caller's cwd (an Angular/Vue-only scaffold never installs
294
- * it), mirroring check-contracts.mjs's original lazy `getReactDocgen()`.
287
+ * it).
295
288
  */
296
289
  export function makeReactDocgenTools(cwdRequire) {
297
290
  let _reactDocgen = null;
@@ -338,59 +331,42 @@ export function makeReactDocgenTools(cwdRequire) {
338
331
  return { getReactDocgen, makeReactImporter, reactParseFile };
339
332
  }
340
333
 
341
- /**
342
- * Walk up from `startDir` looking for `libs/spec/src/index.ts` — the
343
- * framework-agnostic contract every `Atl<X>Spec` extends. Bounded (10 levels)
344
- * and returns `null` rather than throwing when nothing is found, so a
345
- * standalone scaffold that doesn't carry `libs/spec` at all (see this file's
346
- * own "parameterized, no module globals" header note) degrades to no
347
- * candidates instead of an error.
348
- */
349
- function findSpecIndexFile(startDir) {
350
- let dir = startDir;
351
- for (let i = 0; i < 10; i++) {
352
- const candidate = path.join(dir, 'libs', 'spec', 'src', 'index.ts');
353
- if (fs.existsSync(candidate)) return candidate;
354
- const parent = path.dirname(dir);
355
- if (parent === dir) break;
356
- dir = parent;
357
- }
358
- return null;
359
- }
360
-
361
- const _formFieldStringPropsCache = new Map(); // specFile -> string[]
334
+ const _sharedPropsCache = new Map(); // "<file>#<interface>" -> string[]
362
335
 
363
336
  /**
364
- * The string-typed field names declared on `AtlFormFieldSpec` in
365
- * `libs/spec/src/index.ts` (found by walking up from `componentFilePath`) —
366
- * `['name']` today (`value` is `any`, `onValueChange` a callback, `disabled`/
367
- * `invalid`/`required` boolean). This is the ONLY candidate set the
368
- * destructuring fallback below considers: it is the exact, narrow class of
369
- * prop this fallback exists for (a string field inherited two levels deep
370
- * through `Atl<X>Spec extends Omit<AtlFormFieldSpec, …>`, with no default for
371
- * react-docgen's own heuristic to latch onto) — never a general "every
372
- * destructured identifier react-docgen missed" scan, which would just as
373
- * happily "recover" a native HTML passthrough attribute (`id`, `style`,
374
- * `onChange`, …) a component destructures for its own unrelated reasons.
337
+ * The string-typed field names declared on the interface `sharedProps.name` in
338
+ * `sharedProps.file` — the framework-agnostic base interface several
339
+ * components' own prop types extend (e.g. a form-field spec: `['name']` when
340
+ * `value` is `any`, `onValueChange` a callback, `disabled`/`invalid`/`required`
341
+ * boolean). This is the ONLY candidate set the destructuring fallback below
342
+ * considers: it is the exact, narrow class of prop this fallback exists for (a
343
+ * string field inherited two levels deep through `Props extends
344
+ * Omit<SharedBase, …>`, with no default for react-docgen's own heuristic to
345
+ * latch onto) — never a general "every destructured identifier react-docgen
346
+ * missed" scan, which would just as happily "recover" a native HTML
347
+ * passthrough attribute (`id`, `style`, `onChange`, …) a component destructures
348
+ * for its own unrelated reasons. Returns `[]` when `sharedProps` is not
349
+ * configured or the file/interface is not found.
375
350
  */
376
- function formFieldStringProps(componentFilePath) {
377
- const specFile = findSpecIndexFile(path.dirname(componentFilePath));
378
- if (!specFile) return [];
379
- if (_formFieldStringPropsCache.has(specFile))
380
- return _formFieldStringPropsCache.get(specFile);
381
- const src = fs.readFileSync(specFile, 'utf-8');
382
- const ifaceMatch = /interface\s+AtlFormFieldSpec\s*\{([\s\S]*?)\n\}/.exec(
383
- src,
384
- );
351
+ function sharedPropsStringProps(sharedProps) {
352
+ if (!sharedProps) return [];
353
+ const key = `${sharedProps.file}#${sharedProps.name}`;
354
+ if (_sharedPropsCache.has(key)) return _sharedPropsCache.get(key);
385
355
  const out = [];
386
- if (ifaceMatch) {
387
- const fieldRe = /^\s*(\w+)\??:\s*(.+?);\s*$/gm;
388
- let fm;
389
- while ((fm = fieldRe.exec(ifaceMatch[1])) !== null) {
390
- if (fm[2].trim() === 'string') out.push(fm[1]);
356
+ if (fs.existsSync(sharedProps.file)) {
357
+ const src = fs.readFileSync(sharedProps.file, 'utf-8');
358
+ const ifaceMatch = new RegExp(
359
+ `interface\\s+${sharedProps.name}\\s*\\{([\\s\\S]*?)\\n\\}`,
360
+ ).exec(src);
361
+ if (ifaceMatch) {
362
+ const fieldRe = /^\s*(\w+)\??:\s*(.+?);\s*$/gm;
363
+ let fm;
364
+ while ((fm = fieldRe.exec(ifaceMatch[1])) !== null) {
365
+ if (fm[2].trim() === 'string') out.push(fm[1]);
366
+ }
391
367
  }
392
368
  }
393
- _formFieldStringPropsCache.set(specFile, out);
369
+ _sharedPropsCache.set(key, out);
394
370
  return out;
395
371
  }
396
372
 
@@ -469,8 +445,12 @@ function scanDestructuredReactProps(source, componentName) {
469
445
  return out;
470
446
  }
471
447
 
472
- /** react-docgen's raw per-component payload -> array of props in the common shape. */
473
- export function normalizeReactDocgen(d) {
448
+ /**
449
+ * react-docgen's raw per-component payload -> array of props in the common shape.
450
+ * `sharedProps` (`{ file, name }`, optional) enables the destructuring fallback
451
+ * at the end — see `sharedPropsStringProps()`; without it the fallback is off.
452
+ */
453
+ export function normalizeReactDocgen(d, sharedProps) {
474
454
  const out = [];
475
455
  const known = new Set();
476
456
  for (const [propName, info] of Object.entries(d.props || {})) {
@@ -503,10 +483,10 @@ export function normalizeReactDocgen(d) {
503
483
  info.defaultValue.value === 'false')
504
484
  ) {
505
485
  // react-docgen sometimes resolves a prop inherited through a multi-level interface
506
- // chain (AtlCheckboxSpec extends AtlFormFieldSpec) without a tsType at all — seen
486
+ // chain (a component's props extending a shared base interface) without a tsType at all — seen
507
487
  // on 'disabled'/'required' here, though the sibling 'invalid' (declared one level
508
488
  // shallower) resolves fine. A literal true/false default is otherwise only ever a
509
- // boolean prop in this codebase, so infer the kind from it rather than losing the
489
+ // boolean prop, so infer the kind from it rather than losing the
510
490
  // prop to 'other' and under-reporting a real BOOLEAN drift.
511
491
  kind = 'boolean';
512
492
  }
@@ -533,14 +513,14 @@ export function normalizeReactDocgen(d) {
533
513
  // infer a boolean kind (above) from a literal true/false DEFAULT VALUE it
534
514
  // already found, which requires it to have returned an entry in the first
535
515
  // place — that happens for 'disabled'/'required' here (inherited two levels
536
- // deep through `AtlCheckboxSpec extends Omit<AtlFormFieldSpec, …>`, same as
516
+ // deep through `Props extends Omit<SharedBase, …>`, same as
537
517
  // 'name', but destructured WITH a `= false` default for react-docgen's
538
518
  // resolver to latch onto). A same-depth prop with no default at all (`name`,
539
519
  // no default) gives react-docgen nothing to find, so it is missing from
540
520
  // `d.props` entirely rather than merely untyped. Recovered from the
541
521
  // component's own destructured props parameter — same regex-over-the-source
542
- // idiom check-defaults.js/check-contracts.mjs use — but ONLY for the exact,
543
- // narrow candidate set formFieldStringProps() names (see its own doc comment
522
+ // idiom the check's other source scans use — but ONLY for the exact,
523
+ // narrow candidate set sharedPropsStringProps() names (see its own doc comment
544
524
  // for why: this is not a general "every destructured identifier react-docgen
545
525
  // missed" scan, which would just as happily manufacture a finding for a
546
526
  // native HTML passthrough attribute — `id`, `style`, `onChange`, … — that a
@@ -549,7 +529,7 @@ export function normalizeReactDocgen(d) {
549
529
  // react-docgen's resolver can't traverse at all, not this two-level-Omit
550
530
  // shape).
551
531
  if (d.__source && d.displayName && d.__file) {
552
- const candidates = new Set(formFieldStringProps(d.__file));
532
+ const candidates = new Set(sharedPropsStringProps(sharedProps));
553
533
  if (candidates.size > 0) {
554
534
  for (const {
555
535
  name,
@@ -15,10 +15,9 @@
15
15
  * resolve identifiers, or follow imports. Drift-gates want a fast,
16
16
  * deterministic read of a configuration-shaped file, not a JS runtime.
17
17
  *
18
- * Extracted from `tools/scripts/gen-llms-txt.mjs` (commit 7a61c26-era)
19
- * so `check-metadata.js`, `check-css-tokens.js`, and the generator share
20
- * one implementation. CommonJS so the existing `check-*.js` scripts can
21
- * `require` it without an ESM wrapper.
18
+ * CommonJS (`.cjs`) on purpose: it works unchanged in a `"type": "module"`
19
+ * package and from the ESM scripts that load it via `createRequire`.
20
+ * `typescript` is resolved from the consumer's own install (a peer dependency).
22
21
  */
23
22
 
24
23
  const ts = require('typescript');
@@ -514,7 +514,7 @@ async function checkFigmaSetup() {
514
514
  warn(
515
515
  'Plugin files vs. .mcp.json pin',
516
516
  `on-disk .version is ${diskVersion}, .mcp.json pins ${pinnedVersion}`,
517
- `Run \`npx -y ${pinnedSpec} --help\` once to refresh the files, then re-run (or re-import) the plugin in Figma Desktop — see https://atelier.pieper.io/runbook#plugin-update`,
517
+ `Run \`npx -y ${pinnedSpec} --help\` once to refresh the files, then re-run (or re-import) the plugin in Figma Desktop — see https://atelier.pieper.io/troubleshooting#plugin-update`,
518
518
  );
519
519
  }
520
520
  }
@@ -86,7 +86,30 @@ function testingTemplateName(framework, base) {
86
86
  }
87
87
  return `testing/${framework}/${base}.ts.template`;
88
88
  }
89
- // The workspace's own component skill (`.claude/skills/atelier-component/`)
89
+ // Two more skills ship as verbatim copies — no remote pull, nothing to
90
+ // substitute — and are held byte-identical to their repo sources by
91
+ // `check:preflight-clone-sync` (tools/scripts/sync-preflight.mjs, DIRS):
92
+ // `uianatomy-mcp` (always) and `figma-workspace-architect` (only with
93
+ // `figmaMcp`: it drives figma-console-mcp, which the scaffold wires only then,
94
+ // ADR-0144's figma/no-figma split). `design-to-code` deliberately does not
95
+ // ship: `atelier-component` below is the design-to-code loop for a workspace.
96
+ // The set of files is whatever sits under the template directory, so a
97
+ // reference added to the source reaches the scaffold through the sync gate
98
+ // alone, with no edit here.
99
+ function listTemplateFiles(relativeDir) {
100
+ return (0, node_fs_1.readdirSync)((0, node_path_1.join)(__dirname, 'files', relativeDir), {
101
+ withFileTypes: true,
102
+ }).flatMap((entry) => entry.isDirectory()
103
+ ? listTemplateFiles(`${relativeDir}/${entry.name}`)
104
+ : [`${relativeDir}/${entry.name}`]);
105
+ }
106
+ function writeCopiedSkill(tree, skill) {
107
+ const templateDir = `claude/skills/${skill}`;
108
+ for (const templatePath of listTemplateFiles(templateDir)) {
109
+ tree.write(templatePath.replace(/^claude\//, '.claude/'), readTemplate(templatePath));
110
+ }
111
+ }
112
+ // The workspace's own component skill (`.claude/skills/atelier-component/SKILL.md`)
90
113
  // ships as a static `files/` template, in two variants selected by
91
114
  // `figmaMcp` (ADR-0144: SKILL.md when `--figma`, SKILL.no-figma.md
92
115
  // otherwise — whole sections differ, not just a couple of words, so this is
@@ -272,7 +295,7 @@ const SKILLS_CLONE_TIMEOUT_MS = 60000;
272
295
  // exact version this monorepo runs (root package.json devDependencies) so
273
296
  // the scaffold's copy behaves the same as the canonical script.
274
297
  const MCP_SDK_VERSION = '^1.29.0';
275
- // ts-eval.js (shared by check-contracts.mjs and figma-snapshot-contracts.mjs)
298
+ // ts-eval.cjs (shared by check-contracts.mjs and figma-snapshot-contracts.mjs)
276
299
  // needs `typescript` at runtime. Every framework's Nx application generator
277
300
  // already adds it, so this is a safety net, not the primary source — see the
278
301
  // conditional add near the end of presetGenerator, which only includes this
@@ -1288,8 +1311,8 @@ function presetGenerator(tree, options) {
1288
1311
  // mismatches — with no Figma there is nothing for a contract to disagree
1289
1312
  // with, so `options.figmaMcp` (the same flag that decides whether
1290
1313
  // `figma-console` reaches .mcp.json, below) is the one switch for this
1291
- // whole loop: the contract files, the two loop scripts + their shared
1292
- // lib/, the Figma snapshot projection, and contracts.config.json.
1314
+ // whole loop: the contract files, the vendored contract-loop package
1315
+ // (tools/design-contracts/), the Figma snapshot projection, and contracts.config.json.
1293
1316
  // check-contracts.mjs's own snapshot read
1294
1317
  // (`JSON.parse(fs.readFileSync(snapshotPath, ...))`) is unguarded — it
1295
1318
  // throws, not degrades, the moment tools/figma/snapshot.json is missing —
@@ -1305,10 +1328,22 @@ function presetGenerator(tree, options) {
1305
1328
  tree.write(`${appName}/src/contracts/types.ts`, readTemplate('contracts/types.ts.template'));
1306
1329
  tree.write(`${appName}/src/contracts/README.md`, readTemplate('contracts/README.md'));
1307
1330
  tree.write(`${appName}/src/contracts/button.contract.ts`, readTemplate('contracts/button.contract.ts.template'));
1308
- tree.write('tools/scripts/check-contracts.mjs', readTemplate('tools/scripts/check-contracts.mjs'));
1309
- tree.write('tools/scripts/lib/ts-eval.js', readTemplate('tools/scripts/lib/ts-eval.js'));
1310
- tree.write('tools/scripts/lib/docgen.mjs', readTemplate('tools/scripts/lib/docgen.mjs'));
1311
- tree.write('tools/scripts/figma-snapshot-contracts.mjs', readTemplate('tools/scripts/figma-snapshot-contracts.mjs'));
1331
+ // The contract-loop package (`@conciso/design-contracts`, canonical in this
1332
+ // repo's libs/design-contracts, kept byte-identical by sync-preflight.mjs),
1333
+ // vendored whole under tools/design-contracts/. `.mjs`/`.cjs` only, so no
1334
+ // package.json is needed beside it. check-contracts.mjs and
1335
+ // figma-snapshot-contracts.mjs resolve everything from contracts.config.json
1336
+ // at the workspace root (written below), never from their own location.
1337
+ for (const file of [
1338
+ 'bin/check-contracts.mjs',
1339
+ 'bin/figma-snapshot-contracts.mjs',
1340
+ 'src/codespec.mjs',
1341
+ 'src/config.mjs',
1342
+ 'src/docgen.mjs',
1343
+ 'src/ts-eval.cjs',
1344
+ ]) {
1345
+ tree.write(`tools/design-contracts/${file}`, readTemplate(`tools/design-contracts/${file}`));
1346
+ }
1312
1347
  // The AtlButton-only projection of this repo's own tools/figma/snapshot.json
1313
1348
  // (gen-scaffold-snapshot.mjs) — gives check:contracts a Figma side for the
1314
1349
  // example contract + story on day one, before the attendee ever runs
@@ -1319,6 +1354,9 @@ function presetGenerator(tree, options) {
1319
1354
  contracts: `${appName}/src/contracts`,
1320
1355
  stories: [`${appName}/src`],
1321
1356
  snapshot: 'tools/figma/snapshot.json',
1357
+ // The design-token prefix `check:contracts --emit` scans stylesheets for
1358
+ // (the package's default is any `--` custom property).
1359
+ tokenPrefix: '--ui-',
1322
1360
  });
1323
1361
  }
1324
1362
  else {
@@ -1483,6 +1521,18 @@ actually check — see the skill itself, or ask Claude Code to use it, for the l
1483
1521
  \`check:contracts\`'s finding codes.`
1484
1522
  : `It runs the component → stories → checks loop this workspace ships without Figma —
1485
1523
  see the skill itself, or ask Claude Code to use it, for what each check actually proves.`;
1524
+ // What the generator writes itself into .claude/skills/ (CLAUDE.md and
1525
+ // README.md both list it): the figma-workspace-architect line exists only
1526
+ // when the skill does (--figma).
1527
+ const shippedSkillsList = [
1528
+ '- **atelier-component** (`.claude/skills/atelier-component/SKILL.md`) — build or review one component: the loop from the component to its stories and checks',
1529
+ ...(options.figmaMcp
1530
+ ? [
1531
+ '- **figma-workspace-architect** (`.claude/skills/figma-workspace-architect/SKILL.md`) — structural work in the Figma file (tokens/Variables, variants, naming, audits) via figma-console-mcp; load it before larger `figma_execute` / variable calls',
1532
+ ]
1533
+ : []),
1534
+ '- **uianatomy-mcp** (`.claude/skills/uianatomy-mcp/SKILL.md`) — canonical component anatomy, axes and cross-library divergences, looked up through the `uianatomy` MCP server',
1535
+ ].join('\n');
1486
1536
  // Definition of Done (below): four checks without Figma, five with it —
1487
1537
  // `check:contracts` only exists when the contract loop does (ADR-0144).
1488
1538
  const doneChecks = [
@@ -1584,9 +1634,13 @@ npm run check:stories
1584
1634
 
1585
1635
  ## Agent Skills
1586
1636
 
1587
- This workspace also ships \`atelier-component\` (\`.claude/skills/atelier-component/SKILL.md\`)
1588
- unconditionally — this generator writes it straight to disk as part of scaffolding, with no
1589
- network fetch and no \`skills: false\` opt-out, unlike the four skills below. ${atelierComponentSkillBlurb}
1637
+ This workspace ships these skills unconditionally — the generator writes them straight to
1638
+ disk as part of scaffolding, with no network fetch and no \`skills: false\` opt-out, unlike
1639
+ the four \`storybookjs/mcp\` skills below:
1640
+
1641
+ ${shippedSkillsList}
1642
+
1643
+ \`atelier-component\` is the loop for building or reviewing a component. ${atelierComponentSkillBlurb}
1590
1644
 
1591
1645
  ${skillsEnabled
1592
1646
  ? `The scaffold attempted to install four \`storybookjs/mcp\` skills for Claude
@@ -1700,7 +1754,7 @@ file exports). The Desktop Bridge covers creation and inspection without a token
1700
1754
  // The contract loop's own devDependencies (ADR-0121 S4), gated on Figma
1701
1755
  // (ADR-0144) — neither exists without `--figma`: the MCP SDK is only
1702
1756
  // imported by figma-snapshot-contracts.mjs, and the defensive `typescript`
1703
- // add exists only because ts-eval.js (shared by check-contracts.mjs and
1757
+ // add exists only because ts-eval.cjs (shared by check-contracts.mjs and
1704
1758
  // figma-snapshot-contracts.mjs) needs it at runtime — read from the tree's
1705
1759
  // package.json as it stands right now, after the framework's generator has
1706
1760
  // run and before this generator's own writes below it.
@@ -1814,10 +1868,11 @@ file exports). The Desktop Bridge covers creation and inspection without a token
1814
1868
  // Loop" section (figmaSnapshotRefreshInstruction above) spells out how to
1815
1869
  // fill it in either way.
1816
1870
  if (options.figmaMcp) {
1817
- pkg.scripts['check:contracts'] = 'node tools/scripts/check-contracts.mjs';
1871
+ pkg.scripts['check:contracts'] =
1872
+ 'node tools/design-contracts/bin/check-contracts.mjs';
1818
1873
  pkg.scripts['figma:snapshot'] = options.figmaFile
1819
- ? `node tools/scripts/figma-snapshot-contracts.mjs --file ${options.figmaFile}`
1820
- : 'node tools/scripts/figma-snapshot-contracts.mjs --file <YOUR_FIGMA_FILE_KEY>';
1874
+ ? `node tools/design-contracts/bin/figma-snapshot-contracts.mjs --file ${options.figmaFile}`
1875
+ : 'node tools/design-contracts/bin/figma-snapshot-contracts.mjs --file <YOUR_FIGMA_FILE_KEY>';
1821
1876
  }
1822
1877
  // Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123).
1823
1878
  // Identical to the monorepo's own root package.json script.
@@ -1968,6 +2023,10 @@ Every story is also a browser-mode test — run them all headless in Chromium wi
1968
2023
 
1969
2024
  ## Agent Skills
1970
2025
 
2026
+ Written by the generator itself, always (no network, no \`skills: false\` opt-out):
2027
+
2028
+ ${shippedSkillsList}
2029
+
1971
2030
  ${skillsEnabled
1972
2031
  ? `The scaffold attempted to install the four \`storybookjs/mcp\` skills (\`stories\`,
1973
2032
  \`storybook-init\`, \`storybook-setup\`, \`storybook-upgrade\`) for Claude Code under
@@ -2153,6 +2212,11 @@ Browse components at ${SITE_URL}
2153
2212
  // Skills" section (built above) for why this one is called out separately
2154
2213
  // from those four.
2155
2214
  tree.write('.claude/skills/atelier-component/SKILL.md', renderAtelierComponentSkill(appName, framework, (_f = options.figmaMcp) !== null && _f !== void 0 ? _f : false));
2215
+ // The two copied skills (see listTemplateFiles' comment above). The
2216
+ // architect only when the workspace has figma-console to drive.
2217
+ writeCopiedSkill(tree, 'uianatomy-mcp');
2218
+ if (options.figmaMcp)
2219
+ writeCopiedSkill(tree, 'figma-workspace-architect');
2156
2220
  // .gitignore: create-nx-workspace already writes this file (before any
2157
2221
  // preset runs) with its own standard ignores (node_modules, dist, .nx, …)
2158
2222
  // — appended to, never overwritten, so a future create-nx-workspace