@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.
- package/CHANGELOG.md +50 -4
- package/package.json +1 -1
- package/src/generators/preset/files/claude/agents/component-review.md +53 -0
- package/src/generators/preset/files/claude/commands/verify.md +24 -0
- package/src/generators/preset/files/claude/hooks/format-edited.sh +77 -0
- package/src/generators/preset/files/claude/skills/atelier-component/SKILL.md +84 -0
- package/src/generators/preset/files/contracts/README.md +29 -0
- package/src/generators/preset/files/contracts/button.contract.ts.template +20 -0
- package/src/generators/preset/files/contracts/types.ts.template +55 -0
- package/src/generators/preset/files/figma/snapshot.json +164 -0
- package/src/generators/preset/files/storybook/angular/atl-button.stories.ts.template +85 -0
- package/src/generators/preset/files/storybook/angular/main.ts.template +39 -0
- package/src/generators/preset/files/storybook/angular/preview.ts.template +30 -0
- package/src/generators/preset/files/storybook/angular/tsconfig.json +16 -0
- package/src/generators/preset/files/storybook/angular/vitest.config.ts.template +40 -0
- package/src/generators/preset/files/storybook/angular/vitest.setup.ts.template +14 -0
- package/src/generators/preset/files/storybook/react/atl-button.stories.tsx +86 -0
- package/src/generators/preset/files/storybook/react/main.ts.template +37 -0
- package/src/generators/preset/files/storybook/react/preview.tsx +29 -0
- package/src/generators/preset/files/storybook/react/vitest.config.ts.template +32 -0
- package/src/generators/preset/files/storybook/react/vitest.setup.ts.template +8 -0
- package/src/generators/preset/files/storybook/vue/atl-button.stories.ts.template +89 -0
- package/src/generators/preset/files/storybook/vue/main.ts.template +38 -0
- package/src/generators/preset/files/storybook/vue/preview.ts.template +29 -0
- package/src/generators/preset/files/storybook/vue/vitest.config.ts.template +32 -0
- package/src/generators/preset/files/storybook/vue/vitest.setup.ts.template +9 -0
- package/src/generators/preset/files/styles/tokens.css +59 -43
- package/src/generators/preset/files/testing/angular/atl-button.spec.ts.template +27 -0
- package/src/generators/preset/files/testing/angular/test-setup.ts.template +6 -0
- package/src/generators/preset/files/testing/angular/vitest.unit.config.ts.template +36 -0
- package/src/generators/preset/files/testing/react/atl-button.spec.tsx +22 -0
- package/src/generators/preset/files/testing/react/test-setup.ts.template +1 -0
- package/src/generators/preset/files/testing/react/vitest.unit.config.ts.template +21 -0
- package/src/generators/preset/files/testing/vue/atl-button.spec.ts.template +25 -0
- package/src/generators/preset/files/testing/vue/test-setup.ts.template +1 -0
- package/src/generators/preset/files/testing/vue/vitest.unit.config.ts.template +50 -0
- package/src/generators/preset/files/tools/scripts/check-contracts.mjs +1644 -0
- package/src/generators/preset/files/tools/scripts/figma-snapshot-contracts.mjs +370 -0
- package/src/generators/preset/files/tools/scripts/lib/docgen.mjs +573 -0
- package/src/generators/preset/files/tools/scripts/lib/ts-eval.js +126 -0
- package/src/generators/preset/files/tools/scripts/preflight.mjs +163 -31
- package/src/generators/preset/files/tools/stylelint-rules/index.js +21 -0
- package/src/generators/preset/files/tools/stylelint-rules/no-primitive-token.js +362 -0
- package/src/generators/preset/files/tools/stylelint-rules/no-raw-color-literal.js +154 -0
- package/src/generators/preset/files/tools/stylelint-rules/no-token-bypass.js +497 -0
- package/src/generators/preset/files/tools/stylelint-rules/no-undeclared-token.js +122 -0
- package/src/generators/preset/files/tools/stylelint-rules/utils.js +71 -0
- package/src/generators/preset/preset.d.ts +1 -0
- package/src/generators/preset/preset.js +1463 -110
- package/src/generators/preset/preset.js.map +1 -1
- package/src/generators/preset/schema.d.ts +3 -1
- 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
|
-
- ⚠️
|
|
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
|
-
### ⚠️
|
|
337
|
+
### ⚠️ Breaking Changes
|
|
292
338
|
|
|
293
|
-
- **docs:** rename Llm prefix to Atl across docs, generated artifacts, and tooling docs
|
|
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
|
@@ -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
|
+
}
|