@atelier-ui/create-workspace 0.2.42 → 0.2.44

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 (52) hide show
  1. package/CHANGELOG.md +50 -4
  2. package/package.json +1 -1
  3. package/src/generators/preset/files/claude/agents/component-review.md +53 -0
  4. package/src/generators/preset/files/claude/commands/verify.md +24 -0
  5. package/src/generators/preset/files/claude/hooks/format-edited.sh +77 -0
  6. package/src/generators/preset/files/claude/skills/atelier-component/SKILL.md +84 -0
  7. package/src/generators/preset/files/contracts/README.md +29 -0
  8. package/src/generators/preset/files/contracts/button.contract.ts.template +20 -0
  9. package/src/generators/preset/files/contracts/types.ts.template +55 -0
  10. package/src/generators/preset/files/figma/snapshot.json +164 -0
  11. package/src/generators/preset/files/storybook/angular/atl-button.stories.ts.template +85 -0
  12. package/src/generators/preset/files/storybook/angular/main.ts.template +39 -0
  13. package/src/generators/preset/files/storybook/angular/preview.ts.template +30 -0
  14. package/src/generators/preset/files/storybook/angular/tsconfig.json +16 -0
  15. package/src/generators/preset/files/storybook/angular/vitest.config.ts.template +40 -0
  16. package/src/generators/preset/files/storybook/angular/vitest.setup.ts.template +14 -0
  17. package/src/generators/preset/files/storybook/react/atl-button.stories.tsx +86 -0
  18. package/src/generators/preset/files/storybook/react/main.ts.template +37 -0
  19. package/src/generators/preset/files/storybook/react/preview.tsx +29 -0
  20. package/src/generators/preset/files/storybook/react/vitest.config.ts.template +32 -0
  21. package/src/generators/preset/files/storybook/react/vitest.setup.ts.template +8 -0
  22. package/src/generators/preset/files/storybook/vue/atl-button.stories.ts.template +89 -0
  23. package/src/generators/preset/files/storybook/vue/main.ts.template +38 -0
  24. package/src/generators/preset/files/storybook/vue/preview.ts.template +29 -0
  25. package/src/generators/preset/files/storybook/vue/vitest.config.ts.template +32 -0
  26. package/src/generators/preset/files/storybook/vue/vitest.setup.ts.template +9 -0
  27. package/src/generators/preset/files/styles/tokens.css +59 -43
  28. package/src/generators/preset/files/testing/angular/atl-button.spec.ts.template +27 -0
  29. package/src/generators/preset/files/testing/angular/test-setup.ts.template +6 -0
  30. package/src/generators/preset/files/testing/angular/vitest.unit.config.ts.template +36 -0
  31. package/src/generators/preset/files/testing/react/atl-button.spec.tsx +22 -0
  32. package/src/generators/preset/files/testing/react/test-setup.ts.template +1 -0
  33. package/src/generators/preset/files/testing/react/vitest.unit.config.ts.template +21 -0
  34. package/src/generators/preset/files/testing/vue/atl-button.spec.ts.template +25 -0
  35. package/src/generators/preset/files/testing/vue/test-setup.ts.template +1 -0
  36. package/src/generators/preset/files/testing/vue/vitest.unit.config.ts.template +50 -0
  37. package/src/generators/preset/files/tools/scripts/check-contracts.mjs +1644 -0
  38. package/src/generators/preset/files/tools/scripts/figma-snapshot-contracts.mjs +370 -0
  39. package/src/generators/preset/files/tools/scripts/lib/docgen.mjs +573 -0
  40. package/src/generators/preset/files/tools/scripts/lib/ts-eval.js +126 -0
  41. package/src/generators/preset/files/tools/scripts/preflight.mjs +163 -31
  42. package/src/generators/preset/files/tools/stylelint-rules/index.js +21 -0
  43. package/src/generators/preset/files/tools/stylelint-rules/no-primitive-token.js +362 -0
  44. package/src/generators/preset/files/tools/stylelint-rules/no-raw-color-literal.js +154 -0
  45. package/src/generators/preset/files/tools/stylelint-rules/no-token-bypass.js +497 -0
  46. package/src/generators/preset/files/tools/stylelint-rules/no-undeclared-token.js +122 -0
  47. package/src/generators/preset/files/tools/stylelint-rules/utils.js +71 -0
  48. package/src/generators/preset/preset.d.ts +1 -0
  49. package/src/generators/preset/preset.js +1463 -110
  50. package/src/generators/preset/preset.js.map +1 -1
  51. package/src/generators/preset/schema.d.ts +3 -1
  52. package/src/generators/preset/schema.json +23 -3
package/CHANGELOG.md CHANGED
@@ -1,3 +1,49 @@
1
+ ## 0.2.44 (2026-09-13)
2
+
3
+ ### 🚀 Features
4
+
5
+ - **create-workspace:** the workspace knows which Figma file is the attendee's ([40a2eff2](https://github.com/DominikPieper/atelier-ui/commit/40a2eff2))
6
+ - **create-workspace:** a unit-test runner, without disturbing the browser one ([fa60042d](https://github.com/DominikPieper/atelier-ui/commit/fa60042d))
7
+ - **create-workspace:** the workspace ships the skill for the loop it runs ([50169e2e](https://github.com/DominikPieper/atelier-ui/commit/50169e2e))
8
+ - **create-workspace:** the generated workspace is set up for the agent that works in it ([e2772040](https://github.com/DominikPieper/atelier-ui/commit/e2772040))
9
+ - **create-workspace:** a pinned workspace whose example teaches the doctrine ([de06988e](https://github.com/DominikPieper/atelier-ui/commit/de06988e))
10
+ - **create-workspace:** the preset takes one framework, not a list ([d4b1cfb1](https://github.com/DominikPieper/atelier-ui/commit/d4b1cfb1))
11
+
12
+ ### 🩹 Fixes
13
+
14
+ - **create-workspace:** the CLAUDE.md it writes quoted the wrong radius values ([35ccffa7](https://github.com/DominikPieper/atelier-ui/commit/35ccffa7))
15
+ - **create-workspace:** the generator validates the Figma key it interpolates ([e6eb441d](https://github.com/DominikPieper/atelier-ui/commit/e6eb441d))
16
+
17
+ ### ❤️ Thank You
18
+
19
+ - Claude Opus 5 (1M context)
20
+ - Dominik Pieper @DominikPieper
21
+
22
+ ## 0.2.43 (2026-09-12)
23
+
24
+ ### 🚀 Features
25
+
26
+ - **scaffold:** Prettier ships enforced, and a types script does not ship at all ([543dc71](https://github.com/DominikPieper/atelier-ui/commit/543dc71))
27
+ - **scaffold:** a generated workspace gets the CSS-discipline rules on day one ([68b097c](https://github.com/DominikPieper/atelier-ui/commit/68b097c))
28
+ - **lint:** the linter is a gate, where the invariant fits in one file ([e4e6a02](https://github.com/DominikPieper/atelier-ui/commit/e4e6a02))
29
+ - **gates:** a gate that measured nothing is not a gate that found nothing ([a45a685](https://github.com/DominikPieper/atelier-ui/commit/a45a685))
30
+ - **gates:** check:manifest-parity — the three manifests, diffed — ADR-0121 S6a ([fbd5fd3](https://github.com/DominikPieper/atelier-ui/commit/fbd5fd3))
31
+ - **spec:** the contract on every Docs tab, imported by every story meta — ADR-0121 S5b ([30dd54c](https://github.com/DominikPieper/atelier-ui/commit/30dd54c))
32
+ - **create-workspace:** the scaffold ships the contract loop — ADR-0121 S4 ([74aa640](https://github.com/DominikPieper/atelier-ui/commit/74aa640))
33
+ - **create-workspace:** Storybook and the skills ship together — ADR-0123 ([79b60e9](https://github.com/DominikPieper/atelier-ui/commit/79b60e9))
34
+
35
+ ### 🩹 Fixes
36
+
37
+ - **lint:** a broken allowlists module made the staleness check silent ([a41ff02](https://github.com/DominikPieper/atelier-ui/commit/a41ff02))
38
+ - **gates:** check:contracts skips package-imported components before docgen ([caa7633](https://github.com/DominikPieper/atelier-ui/commit/caa7633))
39
+ - **skill:** the Day-2 loop, walked as a participant — twenty findings, five blockers ([e1fe140](https://github.com/DominikPieper/atelier-ui/commit/e1fe140))
40
+
41
+ ### ❤️ Thank You
42
+
43
+ - Claude Fable 5.1
44
+ - Claude Opus 5 (1M context)
45
+ - Dominik Pieper @DominikPieper
46
+
1
47
  ## 0.2.42 (2026-09-10)
2
48
 
3
49
  This was a version bump only for create-workspace to align it with other projects, there were no code changes.
@@ -286,11 +332,11 @@ This was a version bump only for create-workspace to align it with other project
286
332
 
287
333
  ### 🚀 Features
288
334
 
289
- - ⚠️ **docs:** rename Llm prefix to Atl across docs, generated artifacts, and tooling docs ([965787d](https://github.com/DominikPieper/atelier-ui/commit/965787d))
335
+ - ⚠️ **docs:** rename Llm prefix to Atl across docs, generated artifacts, and tooling docs ([965787d](https://github.com/DominikPieper/atelier-ui/commit/965787d))
290
336
 
291
- ### ⚠️ Breaking Changes
337
+ ### ⚠️ Breaking Changes
292
338
 
293
- - **docs:** rename Llm prefix to Atl across docs, generated artifacts, and tooling docs ([965787d](https://github.com/DominikPieper/atelier-ui/commit/965787d))
339
+ - **docs:** rename Llm prefix to Atl across docs, generated artifacts, and tooling docs ([965787d](https://github.com/DominikPieper/atelier-ui/commit/965787d))
294
340
 
295
341
  ### ❤️ Thank You
296
342
 
@@ -576,4 +622,4 @@ This was a version bump only for create-workspace to align it with other project
576
622
  ### ❤️ Thank You
577
623
 
578
624
  - Claude Opus 4.7 (1M context)
579
- - Dominik Pieper @DominikPieper
625
+ - Dominik Pieper @DominikPieper
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atelier-ui/create-workspace",
3
- "version": "0.2.42",
3
+ "version": "0.2.44",
4
4
  "description": "Nx preset for Atelier workshop workspaces",
5
5
  "keywords": [
6
6
  "nx",
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: component-review
3
+ description: Reviews ONE existing component in this workspace against its contract file, its Storybook stories, and its accessibility posture — reports findings, never edits anything. Use for "review <component>", "does <component> match its contract", "check <component>'s story coverage", or an accessibility pass on one component before a PR. Do NOT use for general code review, cross-file refactors, or a change that also touches other components — read the diff directly for those instead.
4
+ tools: Read, Grep, Glob, Bash
5
+ model: sonnet
6
+ ---
7
+
8
+ You are **component-review**. Given one component name (e.g. `AtlButton`), audit it against the three sources of truth this workspace already has, and report what's missing or inconsistent. You never edit a file — a finding you can't fix by editing is exactly what this agent exists to surface.
9
+
10
+ ## Finding the component
11
+
12
+ This is a single-framework scaffold — there is exactly one app, under
13
+ `workshop-*/src`. Inside it:
14
+
15
+ - `src/contracts/<name>.contract.ts` — the one hand-authored contract file:
16
+ the Figma master's node id, plus intentional Figma ↔ code mismatches
17
+ (`figmaOnly`, `codeOnly`, `axisMap`, `probes`) — never props, defaults, or
18
+ prose.
19
+ - the component's own source and its `*.stories.*` file — the real props,
20
+ variants, defaults, and `play` functions live there, not in the contract.
21
+
22
+ Glob for both before reading anything else; do not assume a path.
23
+
24
+ ## Review checklist
25
+
26
+ 1. **Contract exists and still matches.** Read the contract file for the
27
+ named component. Does its Figma node id look real, not a placeholder? Grep
28
+ the component's own source for every prop/variant the contract's
29
+ `figmaOnly`/`codeOnly`/`axisMap` entries name — an exemption naming a prop
30
+ that no longer exists, or missing one that now does, is a finding.
31
+ 2. **Story coverage.** Read the stories file. Is there one story per variant
32
+ value and one per boolean state? A variant value with no story rendering
33
+ it is a finding. Does the story meta import the component's contract and
34
+ set `parameters.contract`? (Currently only a warning workspace-wide —
35
+ still worth naming.)
36
+ 3. **Accessibility posture.** Read the component source for ARIA attributes,
37
+ roles, and keyboard handling appropriate to its type (button, dialog,
38
+ listbox, …). Check the stories for a `play` function exercising keyboard
39
+ interaction, and for any `parameters.a11y` override — an override that
40
+ _disables_ a rule is itself a finding worth surfacing, not something to
41
+ accept silently because it's already there.
42
+ 4. **Corroborate, read-only.** You may run `npm run check:contracts` and
43
+ `nx lint <project>` to check your reading against the gates — read their
44
+ output, never edit in response to it. A clean gate proves shape and
45
+ coverage; it does not excuse skipping the reading above, since a stale
46
+ exemption or a disabled a11y rule can be gate-clean and still wrong.
47
+
48
+ ## Report shape
49
+
50
+ One finding per line, prefixed with a rough severity — `BLOCKING`,
51
+ `WORTH FIXING`, or `NIT` — naming the exact file (and line, where that helps).
52
+ End with a one-line verdict: ready to ship, or not yet and why. Do not edit
53
+ any file; that is the caller's job once they've read your findings.
@@ -0,0 +1,24 @@
1
+ ---
2
+ description: Run this workspace's five verification gates and report each one's exit code.
3
+ ---
4
+
5
+ Run these five checks, in order, and report each one's exit code — never a
6
+ single pass/fail summary. A gate's result is its exit code: run it as
7
+
8
+ ```
9
+ <command> > /tmp/verify-<name>.log 2>&1; echo $?
10
+ ```
11
+
12
+ and read the log file afterwards. Never pipe a gate into `head` or `grep` to
13
+ read it — the pipe's own exit status is always `0`, which silently turns a
14
+ failing gate into a passing one.
15
+
16
+ 1. `npm run check:format` — Prettier
17
+ 2. `npm run check:stylelint` — the ported CSS-discipline rules
18
+ 3. `npm run check:contracts` — contract ↔ docgen ↔ Figma-snapshot parity
19
+ 4. `npm run check:unit` — jsdom unit tests (components, composables, helpers)
20
+ 5. `npm run check:stories` — every story, rendered in Chromium, axe-checked
21
+
22
+ Report a short table: check name → exit code → pass/fail. For any non-zero
23
+ exit code, show only the relevant lines from that check's log (not the whole
24
+ log) and stop there — do not attempt a fix unless asked to.
@@ -0,0 +1,77 @@
1
+ #!/usr/bin/env bash
2
+ # PostToolUse hook (matcher: Edit|Write) — formats whatever file the tool
3
+ # call just touched.
4
+ #
5
+ # Why not jq: this workspace declares no jq dependency and it isn't
6
+ # guaranteed to be on an attendee's machine. Node is (package.json's own
7
+ # "engines" requires >=22), so the JSON-on-stdin event is parsed with
8
+ # `node -e` instead.
9
+ #
10
+ # Why not npx: resolving prettier/stylelint through npx pays their full
11
+ # resolution cost on *every* edit — a hook that slow is a hook people turn
12
+ # off. Both are devDependencies this preset installs, so the locally
13
+ # installed binary under node_modules/.bin is invoked directly.
14
+ #
15
+ # This is a formatter, not a gate: it must always exit 0, and must do
16
+ # nothing at all when the path is missing, outside the workspace, or of a
17
+ # type neither tool handles. Blocking an edit because Prettier disliked a
18
+ # file is the wrong failure mode — check:format and check:stylelint are the
19
+ # real gates (see /verify).
20
+ set -u
21
+
22
+ project_dir="${CLAUDE_PROJECT_DIR:-$PWD}"
23
+ cd "$project_dir" || exit 0
24
+
25
+ # The event arrives as JSON on stdin; the edited path is at
26
+ # `.tool_input.file_path`. Malformed/empty stdin, or a payload with no
27
+ # string there, prints nothing — handled as "no path" below, same as a
28
+ # missing key.
29
+ file_path="$(node -e '
30
+ let data = "";
31
+ process.stdin.on("data", (chunk) => { data += chunk; });
32
+ process.stdin.on("end", () => {
33
+ try {
34
+ const event = JSON.parse(data);
35
+ const path = event && event.tool_input && event.tool_input.file_path;
36
+ if (typeof path === "string") process.stdout.write(path);
37
+ } catch {
38
+ // Leave stdout empty — treated as "no path" below.
39
+ }
40
+ });
41
+ ' 2>/dev/null)"
42
+
43
+ [ -z "$file_path" ] && exit 0
44
+
45
+ # Edit/Write always report an absolute path. Anything not rooted at this
46
+ # workspace (a stray edit against some other tree opened in the same
47
+ # session) is out of scope for this hook.
48
+ case "$file_path" in
49
+ "$project_dir"/*) ;;
50
+ *) exit 0 ;;
51
+ esac
52
+
53
+ [ -f "$file_path" ] || exit 0
54
+
55
+ # Only extensions Prettier actually formats in this workspace — anything
56
+ # else (an image, a lockfile, a binary asset) is a type neither tool
57
+ # handles, and the hook does nothing rather than shell out for no reason.
58
+ case "$file_path" in
59
+ *.ts | *.tsx | *.js | *.jsx | *.mjs | *.cjs | *.vue | *.json | *.css | *.md | *.html | *.yml | *.yaml) ;;
60
+ *) exit 0 ;;
61
+ esac
62
+
63
+ prettier_bin="./node_modules/.bin/prettier"
64
+ if [ -x "$prettier_bin" ]; then
65
+ "$prettier_bin" --write "$file_path" >/dev/null 2>&1
66
+ fi
67
+
68
+ case "$file_path" in
69
+ *.css)
70
+ stylelint_bin="./node_modules/.bin/stylelint"
71
+ if [ -x "$stylelint_bin" ]; then
72
+ "$stylelint_bin" --fix "$file_path" >/dev/null 2>&1
73
+ fi
74
+ ;;
75
+ esac
76
+
77
+ exit 0
@@ -0,0 +1,84 @@
1
+ ---
2
+ name: atelier-component
3
+ description: Build, change or review one component in this Atelier workshop workspace, running the Figma → contract → stories → checks loop against the surfaces this workspace actually has (`<app>/src/contracts/`, `contracts.config.json`, `npm run check:contracts`, `npm run check:stories`). Use whenever the ask is to implement, add, port, restyle or review a component here, when a figma.com/design link arrives with a component name, or when `check:contracts` or `check:stories` report findings that need explaining. Do NOT use for Storybook configuration, for editing `.storybook/*`, or for work that is not about a single component.
4
+ ---
5
+
6
+ # One component, in this workspace
7
+
8
+ This is a generated Atelier workshop workspace: one app (`workshop-<framework>`), one
9
+ framework, a local Storybook on port 6006, and a contract loop. The loop below is the one
10
+ the Atelier monorepo runs, minus the parts that need the monorepo — say so plainly when you
11
+ reach one, rather than pretending the step happened.
12
+
13
+ ## What this workspace can check, and what it cannot
14
+
15
+ | Can | How |
16
+ | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
17
+ | That a contract matches its Figma master's shape | `npm run check:contracts` against `tools/figma/snapshot.json` |
18
+ | That every variant value and Boolean state has a story | the same check's `[COVERAGE]` findings |
19
+ | That a component, composable, service, or helper behaves as unit-tested | `npm run check:unit` (jsdom, `@testing-library/*`) |
20
+ | That every story renders, behaves, and passes axe | `npm run check:stories` (Chromium, headless) |
21
+ | That CSS uses tokens rather than literals | `npm run check:stylelint` |
22
+
23
+ It cannot check design parity against the live Figma file unless the `figma-console` MCP is
24
+ wired in `.mcp.json` and the Desktop Bridge plugin is running. If it is not, the loop ends at
25
+ `check:stories` — and you say that, instead of claiming parity.
26
+
27
+ For a component imported from `@atelier-ui/<framework>` rather than written here,
28
+ `check:contracts` skips docgen (the import resolves into `node_modules`) and reports only
29
+ `[NO-STORY-META]`. A green run on such a component proves the wiring, not the component.
30
+
31
+ ## The loop
32
+
33
+ 1. **Get the shape from Figma, not from a picture.** `figma_get_component_for_development` on
34
+ the node if the MCP is available. Write down the variant axes, the Boolean properties, the
35
+ tokens, and the interaction states before writing any code. If you were handed a screenshot
36
+ and nothing else, say that behaviour has not been specified yet and ask for the node.
37
+ 2. **Write the contract.** `<app>/src/contracts/<name>.contract.ts` — the master's node id and
38
+ only the Figma ↔ code mismatches you are making on purpose (`figmaOnly`, `codeOnly`,
39
+ `axisMap`). Never props, defaults, unions or prose: those live in the component's own types
40
+ and JSDoc. See `<app>/src/contracts/README.md`.
41
+ 3. **Write the component.** Tokens only — every colour, space and radius is a `--ui-*` custom
42
+ property. A raw hex or a hardcoded `2.5rem` is a stylelint error here, not a style opinion.
43
+ 4. **Write the stories, because the stories are the claims.** One story per variant value and
44
+ per Boolean state, `args`-based; one `play` per behaviour you are asserting, with a real
45
+ assertion. Copy the shape from `<app>/src/atl-button.stories.*`, which ships with this
46
+ workspace for exactly that purpose.
47
+ 5. **Run the checks.** `npm run check:contracts`, then `npm run check:stories`. Read the exit
48
+ code, not the last line of output.
49
+ 6. **Close the loop against Figma** if the MCP is available: `figma_check_design_parity`,
50
+ with the code side assembled from `check:contracts` and `figma_scan_code_accessibility`.
51
+
52
+ ## Never invent a prop
53
+
54
+ Before using any prop of a component from `@atelier-ui/<framework>`: call `docs-list` once to
55
+ get valid ids, then `docs-show` for the component. The answer comes back shaped for this
56
+ framework — two-way bindings and split Inputs/Outputs for Angular, `v-model` and typed slots
57
+ for Vue, JSX and `children` for React. If a prop is not in the docs, it does not exist; say so
58
+ rather than guessing from another library's naming.
59
+
60
+ For a component whose source lives in this workspace, its own types are the API.
61
+
62
+ ## Reading `check:contracts`
63
+
64
+ | Finding | What it means |
65
+ | ----------------------------------------------------- | ------------------------------------------------------------ |
66
+ | `[CONTRACT-MISSING]` / `[CONTRACT-NODE]` | no contract file, or its node id disagrees with the snapshot |
67
+ | `[AXIS]` / `[BOOLEAN]` / `[ENUM-UNDRAWN]` | a Figma property has no matching code prop |
68
+ | `[COVERAGE]` / `[COVERAGE-BOOL]` | a variant value or Boolean state that no story renders |
69
+ | `[FIGMA-ONLY]` / `[STALE-EXEMPTION]` / `[UNMIRRORED]` | an exemption is missing, stale, or unexplained |
70
+ | `[NO-STORY-META]` / `[NO-MASTER]` | a contract with nothing yet to check it against |
71
+ | `[CONTRACT-IMPORT]` | a story meta does not import its contract (a warning here) |
72
+
73
+ A `[COVERAGE]` finding is not noise to silence. It means a state exists in the design that
74
+ nothing in this workspace has ever rendered — which is the one thing this loop exists to
75
+ catch.
76
+
77
+ ## Definition of done
78
+
79
+ `npm run check:format`, `npm run check:stylelint`, `npm run check:contracts`,
80
+ `npm run check:unit` and `npm run check:stories` each exit 0 — checked as exit codes, one at
81
+ a time. Never pipe a check into `head` or `grep` to read it: the pipe's status is 0 whatever
82
+ the check did, and that turns a red run into a green report.
83
+
84
+ Then say which of the six loop steps you actually ran, and which you could not.
@@ -0,0 +1,29 @@
1
+ # Contracts
2
+
3
+ A micro-contract (`types.ts`, ADR-0121 Decision 3) is the one hand-authored spec
4
+ artefact per component: which Figma master it is, and where Figma and code differ on
5
+ purpose (`figmaOnly`, `codeOnly`, `axisMap`, `probes`). Everything else — props,
6
+ defaults, unions, variant matrices, descriptions, token lists — is forbidden here; it
7
+ lives in the component's types/JSDoc, a story, or the master.
8
+
9
+ The planned check reads each `<name>.contract.ts` statically with
10
+ `tools/scripts/lib/ts-eval.js`'s `parseExportedVars`, so a contract must stay a plain
11
+ object literal (no imports of values, no computed members).
12
+
13
+ Every component story meta whose component has a contract must import it and set
14
+ `contract` in its `parameters` (`docs-block.ts`'s `ContractBlock` reads
15
+ `parameters.contract` to render the "Contract" section on the docs page); a story file
16
+ that has a contract but doesn't wire it in is `[CONTRACT-IMPORT]` — an error where
17
+ `docs-block.ts` ships beside the contracts (the Atelier monorepo does), a warning in a
18
+ scaffolded workspace until it ships the block.
19
+
20
+ To add one: create `<kebab-selector-without-atl-prefix>.contract.ts` in the contracts
21
+ directory (`AtlButton` → `button.contract.ts`), `import type { ComponentContract } from
22
+ './types';`, and `export const contract = { ... } satisfies ComponentContract;` —
23
+ `satisfies`, not a type annotation, so an extra key fails the build.
24
+
25
+ This file is shared verbatim between two locations: `libs/spec/src/contracts/README.md`
26
+ in this repo, and `<app>/src/contracts/README.md` in a scaffolded workspace
27
+ (`create-workspace`'s preset, kept byte-identical by `tools/scripts/sync-preflight.mjs`).
28
+ That is why it says "the contracts directory" above rather than naming a path — the
29
+ directory itself is `libs/spec/src/contracts/` here and `<app>/src/contracts/` there.
@@ -0,0 +1,20 @@
1
+ import type { ComponentContract } from './types';
2
+
3
+ export const contract = {
4
+ component: 'AtlButton',
5
+ figmaNodeId: '129:20',
6
+ codeOnly: [
7
+ {
8
+ name: 'type',
9
+ reason:
10
+ "Native HTML button 'type' passthrough ('button'|'submit'|'reset') — a form-semantics attribute the button element always carries, not a Figma-drawn visual axis.",
11
+ },
12
+ ],
13
+ figmaOnly: [
14
+ {
15
+ name: 'hasIcon',
16
+ reason:
17
+ 'Master description (2026-08-27, ADR-0058): a Figma-side slot toggle for placing an Icon instance (Instance Swap → Icon library), a legitimate authoring affordance but not part of the component contract — AtlButtonSpec has no hasIcon.',
18
+ },
19
+ ],
20
+ } satisfies ComponentContract;
@@ -0,0 +1,55 @@
1
+ /**
2
+ * The micro-contract (ADR-0121, Decision 3): the ONLY hand-authored spec artefact per
3
+ * component. It records what no derived artefact can know — which Figma master this
4
+ * component is, and where Figma and code differ on purpose. Everything else about the
5
+ * component is derived: props, types, defaults and descriptions from the docgen manifest;
6
+ * variant coverage from the stories; geometry and paint from the rendered story and the
7
+ * Figma snapshot.
8
+ *
9
+ * Forbidden here, by design: props, defaults, unions, variant matrices, prose
10
+ * descriptions, token lists. If you want to write one of those, the place is the
11
+ * component's types and JSDoc, a story, or the master. A contract that regrows into a
12
+ * metadata file has failed.
13
+ *
14
+ * Contracts are plain object literals — no imports of values, no computed members — so
15
+ * `tools/scripts/lib/ts-eval.js` can read them statically, the way it reads the metadata
16
+ * registry.
17
+ */
18
+ export interface ComponentContract {
19
+ /** Spec selector, e.g. `'AtlButton'`. Must equal the master's `selector` in `tools/figma/snapshot.json`. */
20
+ component: string;
21
+ /** The master's `COMPONENT_SET` (or lone `COMPONENT`) node id in the Atelier file, e.g. `'129:20'`. */
22
+ figmaNodeId: string;
23
+ /**
24
+ * Figma properties — variant axes, Booleans, Texts, instance swaps — that have no code
25
+ * prop on purpose, each with the reason. The `state` axis is NOT listed: interaction
26
+ * states are CSS pseudo-classes by repo-wide convention (ADR-0114) and the check knows it.
27
+ */
28
+ figmaOnly?: ReadonlyArray<{ name: string; reason: string }>;
29
+ /**
30
+ * Code props or events that have no Figma property on purpose, each with the reason
31
+ * (e.g. `open` — "false renders nothing", ADR-0056). Domain: only string-literal enum
32
+ * props — the code's own axes — ever need an entry here, for the same reason
33
+ * `[ENUM-UNDRAWN]` only ever reports enum props. Booleans, strings, numbers, callbacks
34
+ * and events with no Figma counterpart are normal (behaviour and content) and never
35
+ * need one.
36
+ */
37
+ codeOnly?: ReadonlyArray<{ name: string; reason: string }>;
38
+ /**
39
+ * A Figma axis that maps to a code prop under another name or value set, e.g. the
40
+ * `selection` axis (`checked` | `unchecked`) that is `checked: boolean` in code.
41
+ * Verbatim-equal axes need no entry. `codeProp` may be dotted (`Child.prop`, e.g.
42
+ * `AtlStep.completed`) when the prop lives on a CHILD component's own manifest rather
43
+ * than the story's primary component — the check resolves it there. Several entries
44
+ * may target the same `figmaAxis` (e.g. AtlStepper's `state` axis maps to three
45
+ * different `AtlStep` flags, one entry each).
46
+ */
47
+ axisMap?: ReadonlyArray<{
48
+ figmaAxis: string;
49
+ codeProp: string;
50
+ values?: Readonly<Record<string, string | number | boolean | null>>;
51
+ reason: string;
52
+ }>;
53
+ /** Only when the root frame is not the comparable layer: the part a parity probe measures instead. */
54
+ probes?: ReadonlyArray<{ part: string; selector: string; reason: string }>;
55
+ }
@@ -0,0 +1,164 @@
1
+ {
2
+ "meta": {
3
+ "fileKey": "QMnDD8uZQPldPrlCwZZ58T",
4
+ "figmaLastModified": "2026-09-10T04:18:29Z",
5
+ "projectedFrom": "tools/figma/snapshot.json"
6
+ },
7
+ "components": [
8
+ {
9
+ "selector": "AtlButton",
10
+ "nodeId": "129:20",
11
+ "name": "Inputs/AtlButton",
12
+ "description": "Action button. Maps to AtlButtonSpec in libs/spec.\n\nUse when: a user-initiated action — submit, save, delete, navigate. Pick the visual based on hierarchy: `primary` for the screen's main action (one per screen), `secondary` for supporting actions, `outline` for tertiary/inline, `danger` for destructive actions (delete, irreversible).\n\nDon't use when: the action is a navigation link (use a real `<a>` element, not a styled button), the choice is between two states (use Form/AtlToggle), or the user is filling a form field (use Form/AtlInput / Form/AtlSelect).\n\nAPI surface (Figma → spec):\n- Variant `variant`: primary | secondary | outline | danger — maps to AtlButtonSpec.variant\n- Variant `size`: sm | md | lg — maps to AtlButtonSpec.size\n- Variant `state`: default | hover | focus | active — interaction state\n- Boolean `disabled`: maps to AtlButtonSpec.disabled\n- Boolean `loading`: maps to AtlButtonSpec.loading — shows spinner, disables interaction\n- Boolean `hasIcon`: toggles the leading icon slot (Instance Swap → Icon library)\n\nA11y: native HTML <button>. When the button has no visible label (icon-only), supply `aria-label` — required by spec. Disabled state uses HTML `disabled` (not aria-disabled) for buttons since they're never expected to remain in the tab order.\n\nStatus: structural restructure 2026-04-27 — `state` enum slimmed to interaction (default/hover/focus/active); `loading` and `disabled` moved out as Booleans matching AtlButtonSpec; `hasIcon` Boolean added for icon-slot toggle.\n\nDeclared Boolean properties that reference no layer (2026-08-27, ADR-0058). check:figma reads these lines, so the reason is stated where a designer opening the master sees it:\n- Boolean `hasIcon`: declared but unbound — and it maps to nothing: `AtlButtonSpec` has no `hasIcon`. It is a Figma-side slot toggle for placing an Icon instance, which is a legitimate authoring affordance but not part of the component contract. Bind it to the icon slot layer when that slot exists, or drop it.",
13
+ "variantAxes": {
14
+ "variant": [
15
+ "primary",
16
+ "secondary",
17
+ "outline",
18
+ "danger"
19
+ ],
20
+ "size": [
21
+ "sm",
22
+ "md",
23
+ "lg"
24
+ ],
25
+ "state": [
26
+ "default",
27
+ "focus",
28
+ "hover",
29
+ "active"
30
+ ]
31
+ },
32
+ "properties": {
33
+ "disabled#507:192": "BOOLEAN",
34
+ "loading#507:217": "BOOLEAN",
35
+ "hasIcon#507:242": "BOOLEAN",
36
+ "variant": "VARIANT",
37
+ "size": "VARIANT",
38
+ "state": "VARIANT"
39
+ },
40
+ "variants": [
41
+ {
42
+ "variant": "primary",
43
+ "size": "sm",
44
+ "state": "default"
45
+ },
46
+ {
47
+ "variant": "primary",
48
+ "size": "md",
49
+ "state": "default"
50
+ },
51
+ {
52
+ "variant": "primary",
53
+ "size": "lg",
54
+ "state": "default"
55
+ },
56
+ {
57
+ "variant": "secondary",
58
+ "size": "sm",
59
+ "state": "default"
60
+ },
61
+ {
62
+ "variant": "secondary",
63
+ "size": "md",
64
+ "state": "default"
65
+ },
66
+ {
67
+ "variant": "secondary",
68
+ "size": "lg",
69
+ "state": "default"
70
+ },
71
+ {
72
+ "variant": "outline",
73
+ "size": "sm",
74
+ "state": "default"
75
+ },
76
+ {
77
+ "variant": "outline",
78
+ "size": "md",
79
+ "state": "default"
80
+ },
81
+ {
82
+ "variant": "outline",
83
+ "size": "lg",
84
+ "state": "default"
85
+ },
86
+ {
87
+ "variant": "primary",
88
+ "size": "md",
89
+ "state": "focus"
90
+ },
91
+ {
92
+ "variant": "primary",
93
+ "size": "md",
94
+ "state": "hover"
95
+ },
96
+ {
97
+ "variant": "primary",
98
+ "size": "md",
99
+ "state": "active"
100
+ },
101
+ {
102
+ "variant": "danger",
103
+ "size": "sm",
104
+ "state": "default"
105
+ },
106
+ {
107
+ "variant": "danger",
108
+ "size": "md",
109
+ "state": "default"
110
+ },
111
+ {
112
+ "variant": "danger",
113
+ "size": "lg",
114
+ "state": "default"
115
+ },
116
+ {
117
+ "variant": "danger",
118
+ "size": "md",
119
+ "state": "hover"
120
+ },
121
+ {
122
+ "variant": "danger",
123
+ "size": "md",
124
+ "state": "active"
125
+ },
126
+ {
127
+ "variant": "danger",
128
+ "size": "md",
129
+ "state": "focus"
130
+ },
131
+ {
132
+ "variant": "secondary",
133
+ "size": "md",
134
+ "state": "hover"
135
+ },
136
+ {
137
+ "variant": "secondary",
138
+ "size": "md",
139
+ "state": "active"
140
+ },
141
+ {
142
+ "variant": "secondary",
143
+ "size": "md",
144
+ "state": "focus"
145
+ },
146
+ {
147
+ "variant": "outline",
148
+ "size": "md",
149
+ "state": "hover"
150
+ },
151
+ {
152
+ "variant": "outline",
153
+ "size": "md",
154
+ "state": "active"
155
+ },
156
+ {
157
+ "variant": "outline",
158
+ "size": "md",
159
+ "state": "focus"
160
+ }
161
+ ]
162
+ }
163
+ ]
164
+ }