@atelier-ui/create-workspace 0.4.13 → 0.4.15
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 +20 -0
- package/package.json +1 -1
- package/src/generators/preset/files/course/README.md +6 -0
- package/src/generators/preset/files/course/_fragments/ladder-angular.md +40 -0
- package/src/generators/preset/files/course/_fragments/ladder-other.md +10 -0
- package/src/generators/preset/files/course/_fragments/rescue-figma.md +30 -0
- package/src/generators/preset/files/course/_fragments/rescue-mcp-angular.md +3 -0
- package/src/generators/preset/files/course/_fragments/rescue-mcp-hosted.md +6 -0
- package/src/generators/preset/files/course/_fragments/stuck.md +32 -0
- package/src/generators/preset/files/course/briefs/README.md +126 -0
- package/src/generators/preset/files/course/briefs/avatar.md +153 -0
- package/src/generators/preset/files/course/briefs/statcard.md +193 -0
- package/src/generators/preset/files/course/briefs/tagchip.md +178 -0
- package/src/generators/preset/files/course/briefs/toast.md +177 -0
- package/src/generators/preset/files/course/day1-settings-card.md +46 -0
- package/src/generators/preset/files/course/day1-team-directory.md +154 -0
- package/src/generators/preset/files/course/day2-prompts.md +105 -0
- package/src/generators/preset/files/course/figma-linter-prompt.md +20 -0
- package/src/generators/preset/files/course/handoff-example.md +68 -0
- package/src/generators/preset/files/course/parity-prompt.md +38 -0
- package/src/generators/preset/files/course/rescue.md +59 -0
- package/src/generators/preset/files/tools/scripts/preflight.mjs +6 -10
- package/src/generators/preset/preset.js +144 -20
- package/src/generators/preset/preset.js.map +1 -1
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Day 2 prompts
|
|
2
|
+
|
|
3
|
+
Used in Day 2 Block 00 (the Definition-of-Done exercise), Block 02 (generation with plan mode, then `docs-show` on your own component) and Block 04 (accessibility).
|
|
4
|
+
The parity prompt of Block 04 is in `parity-prompt.md`; your handoff document is the input
|
|
5
|
+
for all of them (an example is in `handoff-example.md`).
|
|
6
|
+
|
|
7
|
+
## Block 00: the Definition-of-Done exercise (10 minutes)
|
|
8
|
+
|
|
9
|
+
The workspace carries a rule the agent reads every session: `CLAUDE.md`, section "Definition
|
|
10
|
+
of Done". Four steps:
|
|
11
|
+
|
|
12
|
+
1. Ask: "Which commands does this workspace's Definition of Done list? Only list them."
|
|
13
|
+
The answer names six.
|
|
14
|
+
2. Delete this exact line from the list in `CLAUDE.md` and save. Leave the count word
|
|
15
|
+
("all six") as it is:
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
- `npm run check:stories` — every story, rendered in Chromium, axe-checked
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
3. `/clear`, ask the same question again. The list now names five; `check:stories` is gone.
|
|
22
|
+
4. Put the line back (undo) and save.
|
|
23
|
+
|
|
24
|
+
The agent runs what the list names; a check that is not in the list is a check nobody asked
|
|
25
|
+
for. Stretch: write down the one line your own team would add to this list, the command and
|
|
26
|
+
what it proves.
|
|
27
|
+
|
|
28
|
+
## Block 02, part 1: `docs-show` on your own component (10 minutes)
|
|
29
|
+
|
|
30
|
+
Through the local Storybook MCP (`storybook-local`), once your component and its stories
|
|
31
|
+
render. The point: what would an agent that uses your component have to guess?
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
Call docs-list on storybook-local, then docs-show for my component <ComponentName>.
|
|
35
|
+
List what an agent using this component would have to guess: a missing component
|
|
36
|
+
description, a property without a description, a value set shown as a bare alias. Do not
|
|
37
|
+
change anything yet.
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Then:
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
Add the JSDoc that closes those gaps: a description for the component and one line per
|
|
44
|
+
property. Call docs-show again and show me what changed.
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Without the MCP, the same lookup through the CLI:
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
npx storybook tools --config-dir workshop-{{FRAMEWORK_LC}}/.storybook --json docs show --input '{"id":"<id>"}'
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Block 02: generate the component
|
|
54
|
+
|
|
55
|
+
**Plan mode first.** Before pasting, press Shift+Tab until the status line shows plan mode,
|
|
56
|
+
paste the prompt, and read the plan: every prop in it must be a prop of your handoff
|
|
57
|
+
document. Only then let it build. An invented prop is cheaper to catch as a line of plan
|
|
58
|
+
than as a red story.
|
|
59
|
+
|
|
60
|
+
The prompt is short on purpose. The standing rules that hold for every component (tokens,
|
|
61
|
+
composition by region, a name on every icon-only control, status visible without colour,
|
|
62
|
+
`tags: ['autodocs']`) live in the workspace's `atelier-component` skill, with their reasons.
|
|
63
|
+
The prompt carries only what is true of this task.
|
|
64
|
+
|
|
65
|
+
```text
|
|
66
|
+
Generate the {{FRAMEWORK}} implementation of <ComponentName> with its test and
|
|
67
|
+
its stories, from my handoff document <path or pasted text>, not from the
|
|
68
|
+
Figma picture alone. Do not write any other file.
|
|
69
|
+
|
|
70
|
+
The handoff document's "Deliberate differences" are given constraints, not
|
|
71
|
+
mistakes to correct: where the code differs from the design on purpose, build
|
|
72
|
+
it that way.
|
|
73
|
+
|
|
74
|
+
Every prop name matches the handoff document's sections one-for-one: add no
|
|
75
|
+
prop and rename no prop. Follow the atelier-component skill for tokens,
|
|
76
|
+
composition, accessibility and stories. If a requirement has no natural
|
|
77
|
+
mapping onto what you are generating, ask instead of inventing a workaround.
|
|
78
|
+
When you are done, run the Definition of Done checks from CLAUDE.md (the ones /verify runs) and
|
|
79
|
+
report each exit code.
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Block 04: the accessibility check
|
|
83
|
+
|
|
84
|
+
Three steps, in order. The Desktop Bridge must be running: confirm `figma_get_status`
|
|
85
|
+
reports `setup.valid: true` first. Fix only the obligations tagged **(this block)** in the
|
|
86
|
+
brief you chose (`briefs/`), for the variant and state you actually built.
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
Run the three-step accessibility check on <ComponentName>, in order, and report each
|
|
90
|
+
step's result before moving to the next:
|
|
91
|
+
|
|
92
|
+
1. figma_audit_component_accessibility against the Figma node (needs the Desktop
|
|
93
|
+
Bridge running: confirm figma_get_status reports setup.valid: true first).
|
|
94
|
+
2. Open the story in Storybook and read the A11y panel (axe-core): list every
|
|
95
|
+
violation, not just the count.
|
|
96
|
+
3. Keyboard-walk the rendered component yourself: Tab, Shift+Tab, Enter, Escape: does
|
|
97
|
+
focus order, activation and dismissal all work with no mouse?
|
|
98
|
+
|
|
99
|
+
Fix only the obligations tagged (this block) in section 4 of the brief, pasted below this
|
|
100
|
+
prompt, for the variant/state you actually built. Leave (full component) items as a
|
|
101
|
+
written note in the master's Figma description, not as code you claim passes a check
|
|
102
|
+
it was never exercised against.
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
{{STUCK}}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# The Figma linter prompt
|
|
2
|
+
|
|
3
|
+
Used in Day 1 Block 03 (on the master the trainer names, in your prepared duplicate) and in
|
|
4
|
+
Day 2 Block 01 (on your own component set, before you write the handoff document). It is
|
|
5
|
+
read-only: nothing is changed in the file. The Desktop Bridge must be connected.
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
Run figma_lint_design on the node <NODE> (<MASTER NAME>) with only the rules
|
|
9
|
+
hardcoded-color, default-name and detached-component. Return the findings as a list:
|
|
10
|
+
layer, rule, message. Change nothing in the file.
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`<NODE>`: Day 1, the master the trainer names (read its id in your duplicate, do not assume
|
|
14
|
+
it is the id you saw on the projector); Day 2, your own component set: select it in Figma and
|
|
15
|
+
say "the node I have selected" (the agent reads the id with `figma_get_selection`).
|
|
16
|
+
|
|
17
|
+
Sort each line of the result: **real** or **false alarm**. A finding is something to sort,
|
|
18
|
+
not a verdict. The three rules catch raw colours, layers left on default names and detached
|
|
19
|
+
instances. They do not see whether the design is right, nor spacing and radius. On Day 2,
|
|
20
|
+
fix the real findings first and note the false alarms.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Handoff document: a filled example
|
|
2
|
+
|
|
3
|
+
Used in Day 2 Block 01 (you write yours) and as the input of every Day 2 prompt. This is the
|
|
4
|
+
document filled in for the Toast brief (`briefs/toast.md`), in {{FRAMEWORK}}. It is a
|
|
5
|
+
checklist, not a form: its value is that you decide the scope and write the behaviour in
|
|
6
|
+
your own words before any code exists.
|
|
7
|
+
|
|
8
|
+
Note the two blanks only you can fill: your draft URL and node id, and the auto-dismiss time
|
|
9
|
+
(the brief says "configurable" and leaves the number to you).
|
|
10
|
+
|
|
11
|
+
Every line of it is something the diff can be held against: a variant that is not on the
|
|
12
|
+
"In scope" line is a finding, and so is a behaviour line with no play function.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Handoff — AtlToast · {{FRAMEWORK}}
|
|
17
|
+
|
|
18
|
+
**Source.** Duplicate of the Atelier file in my drafts, <draft URL>, node
|
|
19
|
+
`<node id of my copy>` (copied from the starter frame `Toast / Starter`, node
|
|
20
|
+
`703:341`). Page: my copy of the Toast frame.
|
|
21
|
+
|
|
22
|
+
**Canonical record.** The brief, `briefs/toast.md`, is the source
|
|
23
|
+
for what the component is.
|
|
24
|
+
|
|
25
|
+
**Reuse or new.** New component. The status glyph reuses AtlIcon. It is not an
|
|
26
|
+
Alert (inline, persistent) and not a Dialog (blocking).
|
|
27
|
+
|
|
28
|
+
**In scope.** variant = success | danger; states = open | closing.
|
|
29
|
+
`dismissible` and `hasIcon` as Booleans if time allows.
|
|
30
|
+
Hover and focus-visible are CSS, not variants.
|
|
31
|
+
|
|
32
|
+
**Explicitly out.** variants info and warning; the six position values (one
|
|
33
|
+
corner only); stacking; the progress affordance. Each is named in the Figma
|
|
34
|
+
description of the master, not left out silently.
|
|
35
|
+
|
|
36
|
+
**Token bindings.** Container: fill `--ui-color-surface-raised`, border
|
|
37
|
+
`--ui-color-border`, radius `--ui-radius-md`, padding and gap from the
|
|
38
|
+
`--ui-spacing-*` ladder. success: `--ui-color-success-bg` and
|
|
39
|
+
`--ui-color-success-text`. danger: `--ui-color-danger-bg` and
|
|
40
|
+
`--ui-color-danger-text`. Close button: `--ui-color-text-muted`.
|
|
41
|
+
Elevation: `--ui-shadow-lg`, CSS only. Figma has no shadow variable, so the
|
|
42
|
+
Figma description says so.
|
|
43
|
+
|
|
44
|
+
**Deliberate differences.** What the code does differently from the design on
|
|
45
|
+
purpose, and why. Hover and focus-visible are CSS, not variants or properties.
|
|
46
|
+
Elevation is `--ui-shadow-lg` in CSS only, because Figma has no shadow variable
|
|
47
|
+
to bind.
|
|
48
|
+
|
|
49
|
+
**Behaviour.** Each line becomes the title of one play function.
|
|
50
|
+
|
|
51
|
+
- Auto-dismisses after N seconds (I choose N and write it here: ___).
|
|
52
|
+
- Pauses on pointer-enter and on focus-in; resumes, does not restart, when both are out.
|
|
53
|
+
- Escape closes the toast while focus is inside it.
|
|
54
|
+
- success announces politely (role="status"); danger announces assertively (role="alert").
|
|
55
|
+
- The close button has one accessible name, from aria-label or hidden text, never both.
|
|
56
|
+
|
|
57
|
+
**Accessibility.** success and danger differ without colour (glyph and text).
|
|
58
|
+
The glyph is aria-hidden. The action, if present, is a real button. A critical
|
|
59
|
+
error is never shown as a toast.
|
|
60
|
+
|
|
61
|
+
**Target files.** The component, its unit test and its story file (one story
|
|
62
|
+
per variant value and Boolean state, a play function per behaviour line above).
|
|
63
|
+
|
|
64
|
+
**Acceptance.** Unit tests and lint exit 0. check:stories green (every story
|
|
65
|
+
renders, axe clean). docs-show describes the component: a description and a line
|
|
66
|
+
per property. figma_check_design_parity run on my node, every difference it
|
|
67
|
+
reports sorted: code, Figma, or kept on purpose (then it is listed under
|
|
68
|
+
Deliberate differences).
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Parity prompt
|
|
2
|
+
|
|
3
|
+
Used in Day 1 Block 02 (the Settings Card) and Day 2 Block 04 (your own component). It
|
|
4
|
+
compares the code against the Figma master through `figma_check_design_parity`, so it needs
|
|
5
|
+
the Figma Desktop Bridge connected. Without the bridge there is no parity call: sort the
|
|
6
|
+
list you made in Day 1 Block 02 instead.
|
|
7
|
+
|
|
8
|
+
## Day 1 Block 02: the Settings Card
|
|
9
|
+
|
|
10
|
+
Run it after lint and build are green: the comparison with Figma is the expensive,
|
|
11
|
+
judgement-heavy last step, so do not spend it on a component that fails lint or build.
|
|
12
|
+
The settings card node is the "Settings / Card" frame (node `936:2954` on the Workshop-Templates page of the original file; ids differ in your duplicate, so select the frame in Figma and say "the node I have selected").
|
|
13
|
+
|
|
14
|
+
```text
|
|
15
|
+
Run figma_check_design_parity on the settings card node
|
|
16
|
+
against the component I just generated. For each discrepancy, say whether the
|
|
17
|
+
code or the Figma master should change, and why. Fix only the code ones.
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Two labels only: **code** or **Figma**. A long list: label the three largest. A difference
|
|
21
|
+
that fits neither (someone chose it on purpose) is parked: "not code, not Figma, we name it on
|
|
22
|
+
Day 2", and is not "fixed" in code.
|
|
23
|
+
|
|
24
|
+
## Day 2 Block 04: your own component
|
|
25
|
+
|
|
26
|
+
The node id comes from your handoff document.
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
Run figma_check_design_parity on the node <NODE FROM THE HANDOFF DOCUMENT> against my
|
|
30
|
+
component <ComponentName>. For each discrepancy, say whether it is **code** (the code
|
|
31
|
+
should change), **Figma** (the master should change) or **kept on purpose**, and why. Only
|
|
32
|
+
call it "kept on purpose" if the handoff document's "Deliberate differences" section
|
|
33
|
+
names it. Do not fix anything yet.
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
A quiet report is not a clean component: what the call does not compare, it does not report.
|
|
37
|
+
Afterwards you sort every difference: code (hand it back to Claude), Figma (a note for the
|
|
38
|
+
designer) or kept on purpose (it must be in the handoff document's "Deliberate differences").
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Rescue: when your seat is red
|
|
2
|
+
|
|
3
|
+
Use this when `npm run preflight` is still red after the setup block, or a real prompt
|
|
4
|
+
fails. Setup has three independent parts: the Claude Code CLI, the MCP servers and model
|
|
5
|
+
access. Preflight checks the first two; model access is only proven by a real request.
|
|
6
|
+
|
|
7
|
+
## 1. Name what is missing
|
|
8
|
+
|
|
9
|
+
Read the preflight output and decide which of the three is missing: the CLI, an MCP server
|
|
10
|
+
or model access. Fix that one, not everything at once.
|
|
11
|
+
|
|
12
|
+
## 2. Model access
|
|
13
|
+
|
|
14
|
+
`claude --version` and a green preflight prove only that the CLI is installed. Prove model
|
|
15
|
+
access with a real request:
|
|
16
|
+
|
|
17
|
+
```shell
|
|
18
|
+
claude -p "Reply with exactly: PREFLIGHT-OK"
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
If it asks you to sign in or exits with an authentication error: in the course the machines
|
|
22
|
+
are provisioned and the login happens in the room (`claude auth login`, then finish the
|
|
23
|
+
browser sign-in). Tell the trainer.
|
|
24
|
+
|
|
25
|
+
## 3. MCP servers
|
|
26
|
+
|
|
27
|
+
Run `npm run preflight`, then start `claude` from the workspace root (the folder that holds
|
|
28
|
+
`.mcp.json`) and type `/mcp`.
|
|
29
|
+
|
|
30
|
+
- **No servers listed, or "Pending approval".** Claude Code was started before `.mcp.json`
|
|
31
|
+
existed, or from a different folder. Close it, start `claude` in the workspace root,
|
|
32
|
+
accept the "trust this folder" prompt and approve the project servers when asked. If you
|
|
33
|
+
declined one earlier: `claude mcp reset-project-choices`, then start `claude` again.
|
|
34
|
+
{{MCP_RESCUE}}
|
|
35
|
+
- **`storybook-local` is not connected.** Storybook is not running. Start it with
|
|
36
|
+
`npm run storybook`; the tools appear on their own. If they do not: `/mcp` and reconnect
|
|
37
|
+
`storybook-local`. If the port 6006 is taken, find the process first
|
|
38
|
+
(`lsof -nP -iTCP:6006 -sTCP:LISTEN`) and stop that one; do not kill what you have not
|
|
39
|
+
looked at.
|
|
40
|
+
- Do not edit `.mcp.json` and do not add a server by hand: the entries are part of the
|
|
41
|
+
workspace. A seat that stays red works on without `storybook-local`: the browser Storybook
|
|
42
|
+
and `npm run check:stories` show the same result.
|
|
43
|
+
|
|
44
|
+
## 4. Storybook does not start (port in use)
|
|
45
|
+
|
|
46
|
+
`EADDRINUSE` means a previous dev server still runs. Look at what holds the port:
|
|
47
|
+
`lsof -nP -iTCP:<port> -sTCP:LISTEN`. Stop that process only if it is the stale dev server.
|
|
48
|
+
The app serves on port 4200 (`npm start -- --port 4300` for another port); Storybook is
|
|
49
|
+
fixed to 6006.
|
|
50
|
+
{{FIGMA_RESCUE}}
|
|
51
|
+
|
|
52
|
+
## Still red
|
|
53
|
+
|
|
54
|
+
Do not repair a broken workspace yourself: tell the trainer, the machine is theirs to fix.
|
|
55
|
+
Whoever is still red in the setup block pairs with a neighbour (one keyboard, the neighbour
|
|
56
|
+
drives). Nobody starts Day 2 red: the trainer check happens at the coffee break or at lunch,
|
|
57
|
+
not as homework.
|
|
58
|
+
|
|
59
|
+
Still red: ask your neighbour, then the trainer.
|
|
@@ -592,7 +592,7 @@ async function checkFigmaSetup() {
|
|
|
592
592
|
warn(
|
|
593
593
|
'Plugin files vs. .mcp.json pin',
|
|
594
594
|
`on-disk .version is ${diskVersion}, .mcp.json pins ${pinnedVersion}`,
|
|
595
|
-
`Run \`npx -y ${pinnedSpec} --help\` once to refresh the files, then re-run (or re-import) the plugin in Figma Desktop
|
|
595
|
+
`Run \`npx -y ${pinnedSpec} --help\` once to refresh the files, then re-run (or re-import) the plugin in Figma Desktop (Figma: Plugins → Development → Figma Desktop Bridge; steps in course/rescue.md in your course workspace)`,
|
|
596
596
|
);
|
|
597
597
|
}
|
|
598
598
|
}
|
|
@@ -620,7 +620,7 @@ async function checkFigmaSetup() {
|
|
|
620
620
|
warn(
|
|
621
621
|
'Bridge port range 9223–9232',
|
|
622
622
|
'entire range in use',
|
|
623
|
-
'Close unrelated processes holding these ports
|
|
623
|
+
'Close unrelated processes holding these ports; check who holds them first (`lsof -nP -iTCP:9223 -sTCP:LISTEN`). See course/rescue.md in your course workspace',
|
|
624
624
|
);
|
|
625
625
|
}
|
|
626
626
|
|
|
@@ -630,7 +630,7 @@ async function checkFigmaSetup() {
|
|
|
630
630
|
warn(
|
|
631
631
|
'FIGMA_ACCESS_TOKEN (optional)',
|
|
632
632
|
'not set — REST reads disabled, plugin tools still work',
|
|
633
|
-
'
|
|
633
|
+
'Only needed for metadata reads: create a token in Figma (Settings → Security → Personal access tokens, scope File content read) and export it as FIGMA_ACCESS_TOKEN; see course/rescue.md in your course workspace',
|
|
634
634
|
);
|
|
635
635
|
return;
|
|
636
636
|
}
|
|
@@ -677,7 +677,7 @@ async function checkMcpEndpoints(env) {
|
|
|
677
677
|
fail(
|
|
678
678
|
`MCP: ${name}`,
|
|
679
679
|
`${url} ${res.detail}`,
|
|
680
|
-
'Server reachable but MCP calls fail —
|
|
680
|
+
'Server reachable but MCP calls fail — the server is broken, not your machine; tell the trainer (course/rescue.md in your course workspace)',
|
|
681
681
|
);
|
|
682
682
|
} else if (isLocal) {
|
|
683
683
|
warn(
|
|
@@ -880,7 +880,7 @@ async function main() {
|
|
|
880
880
|
if (warnings > 0) {
|
|
881
881
|
console.log(
|
|
882
882
|
dim(
|
|
883
|
-
'Warnings are non-blocking
|
|
883
|
+
'Warnings are non-blocking; steps for each in course/rescue.md in your course workspace',
|
|
884
884
|
),
|
|
885
885
|
);
|
|
886
886
|
}
|
|
@@ -892,11 +892,7 @@ async function main() {
|
|
|
892
892
|
dim(` · ${passes} ok, ${warnings} warning(s)`),
|
|
893
893
|
);
|
|
894
894
|
console.log(dim('Fix the items above, then re-run `npm run preflight`.'));
|
|
895
|
-
console.log(
|
|
896
|
-
dim(
|
|
897
|
-
'Full troubleshooting guide: https://atelier.pieper.io/troubleshooting',
|
|
898
|
-
),
|
|
899
|
-
);
|
|
895
|
+
console.log(dim('Rescue steps: course/rescue.md in your course workspace'));
|
|
900
896
|
console.log('');
|
|
901
897
|
process.exit(1);
|
|
902
898
|
}
|
|
@@ -69,6 +69,110 @@ function readOwnVersion() {
|
|
|
69
69
|
return pkg.version;
|
|
70
70
|
}
|
|
71
71
|
const SITE_URL = 'https://atelier.pieper.io';
|
|
72
|
+
// ─── course/ folder (ADR-0184) ───────────────────────────────────────────────
|
|
73
|
+
// Everything a participant pastes or reads during the course, as plain Markdown
|
|
74
|
+
// in the workspace: the docs site is password-protected, so no file here may
|
|
75
|
+
// point at it. Static templates under files/course/ carry `{{TOKEN}}`s for the
|
|
76
|
+
// few framework-specific spots; whole optional sections (the Figma rescue
|
|
77
|
+
// steps, the hosted-vs-local MCP rescue entry) are fragments under
|
|
78
|
+
// files/course/_fragments/ that are spliced in, never written out themselves.
|
|
79
|
+
const COURSE_SCAFFOLD = {
|
|
80
|
+
angular: {
|
|
81
|
+
name: 'Angular',
|
|
82
|
+
mcp: 'atelier',
|
|
83
|
+
file: 'workshop-angular/src/app/components/team-directory.component.ts',
|
|
84
|
+
css: 'workshop-angular/src/app/components/team-directory.component.css',
|
|
85
|
+
mount: 'add TeamDirectoryComponent to the imports array in workshop-angular/src/app/app.ts and replace <app-nx-welcome> with <app-team-directory> in app.html',
|
|
86
|
+
lint: 'On Angular, `npm run lint` also runs two Atelier template rules: an icon-only `<button atl-button>` needs an accessible name, and a sub-component such as `atl-option` must sit inside its parent (`atl-select`). The parent check covers a fixed list of parts (select, tabs, accordion, dialog, drawer, menu and a few more) and does not include the table parts: `atl-th` or `atl-tr` outside an `atl-table` passes it.',
|
|
87
|
+
},
|
|
88
|
+
react: {
|
|
89
|
+
name: 'React',
|
|
90
|
+
mcp: 'storybook-react',
|
|
91
|
+
file: 'workshop-react/src/components/TeamDirectory.tsx',
|
|
92
|
+
css: 'workshop-react/src/components/TeamDirectory.css',
|
|
93
|
+
mount: 'import TeamDirectory in workshop-react/src/app/app.tsx, replace the <NxWelcome /> placeholder with it and remove the now-unused NxWelcome import (an unused import fails npm run lint)',
|
|
94
|
+
lint: 'On React, `npm run lint` runs the framework rules (including jsx-a11y) but not the two Atelier template rules, which exist for Angular templates only.',
|
|
95
|
+
},
|
|
96
|
+
vue: {
|
|
97
|
+
name: 'Vue',
|
|
98
|
+
mcp: 'storybook-vue',
|
|
99
|
+
file: 'workshop-vue/src/components/TeamDirectory.vue',
|
|
100
|
+
css: 'workshop-vue/src/components/TeamDirectory.css',
|
|
101
|
+
mount: 'import TeamDirectory in workshop-vue/src/views/HomeView.vue, replace the <NxWelcome /> placeholder with it and remove the now-unused NxWelcome import (an unused import fails npm run lint)',
|
|
102
|
+
lint: 'The two Atelier template rules exist for Angular templates only; on Vue `npm run lint` runs the framework rules.',
|
|
103
|
+
},
|
|
104
|
+
};
|
|
105
|
+
function writeCourseFolder(tree, framework, figmaMcp) {
|
|
106
|
+
const c = COURSE_SCAFFOLD[framework];
|
|
107
|
+
const fragment = (name) => readTemplate(`course/_fragments/${name}.md`).trimEnd();
|
|
108
|
+
const tokens = {
|
|
109
|
+
FRAMEWORK: c.name,
|
|
110
|
+
FRAMEWORK_LC: framework,
|
|
111
|
+
LADDER: fragment(framework === 'angular' ? 'ladder-angular' : 'ladder-other')
|
|
112
|
+
.split('{{FRAMEWORK}}')
|
|
113
|
+
.join(c.name),
|
|
114
|
+
PKG: `@atelier-ui/${framework}`,
|
|
115
|
+
MCP: c.mcp,
|
|
116
|
+
FILE: c.file,
|
|
117
|
+
CSS: c.css,
|
|
118
|
+
MOUNT: c.mount,
|
|
119
|
+
LINTNOTE: c.lint,
|
|
120
|
+
CHECKS: `Run npm run lint, npm run check:stylelint and npm run check:format${framework === 'angular' ? ' and, on Angular, npm run build' : ''}. Report each exit code. If one is not 0, read the output (the full log when the summary has no error text), repair, and run it again. Then list what you changed.`,
|
|
121
|
+
// Without Figma there is no day2-prompts.md, so the stuck report moves
|
|
122
|
+
// into rescue.md instead of being lost.
|
|
123
|
+
STUCK_REF: figmaMcp
|
|
124
|
+
? '`day2-prompts.md` (section "When you are stuck")'
|
|
125
|
+
: '`rescue.md` (section "When you are stuck")',
|
|
126
|
+
STUCK: figmaMcp ? fragment('stuck') : '',
|
|
127
|
+
MCP_RESCUE: framework === 'angular'
|
|
128
|
+
? fragment('rescue-mcp-angular')
|
|
129
|
+
: fragment('rescue-mcp-hosted').split('{{FW}}').join(framework),
|
|
130
|
+
FIGMA_RESCUE: `\n${fragment(figmaMcp ? 'rescue-figma' : 'stuck')}\n`,
|
|
131
|
+
INDEX: '',
|
|
132
|
+
};
|
|
133
|
+
const render = (template) => Object.entries(tokens).reduce((text, [key, value]) => text.split(`{{${key}}}`).join(value), readTemplate(`course/${template}`));
|
|
134
|
+
const index = [
|
|
135
|
+
[
|
|
136
|
+
'day1-team-directory.md',
|
|
137
|
+
'Day 1, Block 05: the Team directory brief, start prompt, checks prompt, receipts prompt and time box',
|
|
138
|
+
],
|
|
139
|
+
];
|
|
140
|
+
const write = (file, template = file) => tree.write(`course/${file}`, render(template));
|
|
141
|
+
write('day1-team-directory.md');
|
|
142
|
+
if (figmaMcp) {
|
|
143
|
+
index.push([
|
|
144
|
+
'day1-settings-card.md',
|
|
145
|
+
'Day 1 Block 02: the Settings Card generation prompt, the token fix-up and the lint-and-build ladder stage',
|
|
146
|
+
], [
|
|
147
|
+
'figma-linter-prompt.md',
|
|
148
|
+
'Day 1 Block 03 and Day 2 Block 01: the Figma linter prompt',
|
|
149
|
+
], [
|
|
150
|
+
'parity-prompt.md',
|
|
151
|
+
'Day 1 Block 02 (Settings Card) and Day 2 Block 04 (your own component): the parity prompt',
|
|
152
|
+
], [
|
|
153
|
+
'day2-prompts.md',
|
|
154
|
+
'Day 2 Block 00 (Definition-of-Done exercise), Block 02 (`docs-show` on your component, generation with plan mode) and Block 04 (accessibility), and what to paste when you are stuck',
|
|
155
|
+
], [
|
|
156
|
+
'briefs/',
|
|
157
|
+
'Day 2 Block 00: the four component briefs to choose from (Toast, TagChip, StatCard, Avatar)',
|
|
158
|
+
], ['handoff-example.md', 'Day 2 Block 01: a filled handoff document']);
|
|
159
|
+
write('day1-settings-card.md');
|
|
160
|
+
write('figma-linter-prompt.md');
|
|
161
|
+
write('parity-prompt.md');
|
|
162
|
+
write('day2-prompts.md');
|
|
163
|
+
write('handoff-example.md');
|
|
164
|
+
for (const brief of ['README', 'toast', 'tagchip', 'statcard', 'avatar']) {
|
|
165
|
+
write(`briefs/${brief}.md`);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
index.push([
|
|
169
|
+
'rescue.md',
|
|
170
|
+
`When your seat is red: model access, preflight, /mcp, Storybook${figmaMcp ? ', the Figma bridge' : ', and what to paste when you are stuck'}`,
|
|
171
|
+
]);
|
|
172
|
+
tokens.INDEX = index.map(([f, when]) => `- \`${f}\` — ${when}`).join('\n');
|
|
173
|
+
write('rescue.md');
|
|
174
|
+
write('README.md');
|
|
175
|
+
}
|
|
72
176
|
// Pinned to the exact version this monorepo runs (root package.json
|
|
73
177
|
// devDependencies) — the workshop needs the same Storybook every attendee's
|
|
74
178
|
// neighbour has, not whatever `latest` resolves to on the day of the cohort.
|
|
@@ -368,6 +472,11 @@ const STYLELINT_VERSION = '17.15.0';
|
|
|
368
472
|
// narrow — package-lock.json resolves it to the same 3.9.6, so there's no
|
|
369
473
|
// "declared vs. actually resolved" gap to reconcile.
|
|
370
474
|
const PRETTIER_VERSION = '~3.9.6';
|
|
475
|
+
// Angular only: pins the devkit's architect to the line the scaffold's Angular
|
|
476
|
+
// 22.1 devkit uses. 0.2203.0 (Angular 22.3) ships an `exports` map without
|
|
477
|
+
// "./node/index", which nx's ngcli-adapter imports, and the wide ranges in
|
|
478
|
+
// @analogjs/vitest-angular and @storybook/angular pull it into a fresh install.
|
|
479
|
+
const ANGULAR_DEVKIT_ARCHITECT_VERSION = '0.2201.7';
|
|
371
480
|
// Browser-mode Storybook tests (owner correction, 2026-09-10, to ADR-0123's
|
|
372
481
|
// "no test runner" decision — see the dated correction on that record).
|
|
373
482
|
// Every scaffolded app gets its own vitest.config.ts + storybook-test target,
|
|
@@ -581,7 +690,7 @@ function installSkills(tree, skillsEnabled) {
|
|
|
581
690
|
}
|
|
582
691
|
function presetGenerator(tree, options) {
|
|
583
692
|
return tslib_1.__awaiter(this, void 0, void 0, function* () {
|
|
584
|
-
var _a, _b, _c, _d, _e, _f, _g;
|
|
693
|
+
var _a, _b, _c, _d, _e, _f, _g, _h;
|
|
585
694
|
const framework = (_a = options.framework) !== null && _a !== void 0 ? _a : 'angular';
|
|
586
695
|
const skillsEnabled = (_b = options.skills) !== null && _b !== void 0 ? _b : true;
|
|
587
696
|
// Pinned, not `latest` — see readOwnVersion()'s comment.
|
|
@@ -1651,7 +1760,7 @@ see the skill itself, or ask Claude Code to use it, for what each check actually
|
|
|
1651
1760
|
tree.write('CLAUDE.md', `# Atelier Workshop
|
|
1652
1761
|
|
|
1653
1762
|
This workspace uses Atelier for all UI components.
|
|
1654
|
-
|
|
1763
|
+
The API reference is the library's MCP server (see below): \`docs-list\`, then \`docs-show\`.
|
|
1655
1764
|
|
|
1656
1765
|
## MCP Servers
|
|
1657
1766
|
|
|
@@ -1678,12 +1787,7 @@ ${frameworkIdiomsSection}
|
|
|
1678
1787
|
|
|
1679
1788
|
## Composition Patterns
|
|
1680
1789
|
|
|
1681
|
-
When composing multi-component flows (login form, settings page, confirmation dialog, data list, notification center, management dashboard),
|
|
1682
|
-
|
|
1683
|
-
- Browse: ${SITE_URL}/patterns
|
|
1684
|
-
- JSON catalog (machine-readable): ${SITE_URL}/.well-known/cookbook-patterns.json
|
|
1685
|
-
|
|
1686
|
-
Patterns shown there are the canonical way to combine atoms in this library — prefer them over inventing a composition from scratch.
|
|
1790
|
+
When composing multi-component flows (login form, settings page, confirmation dialog, data list, notification center, management dashboard), look in the library's MCP server first: if \`docs-list\` has a \`cookbook\` entry, \`docs-show\` on it returns the patterns. They are the canonical way to combine atoms in this library — prefer them over inventing a composition from scratch.
|
|
1687
1791
|
|
|
1688
1792
|
## Design Tokens
|
|
1689
1793
|
|
|
@@ -1784,7 +1888,13 @@ composition over configuration, and a sensible default for every prop — so a m
|
|
|
1784
1888
|
has generated code for one component can infer the shape of the next. When you design
|
|
1785
1889
|
the API of your own component, these are the rules the library itself follows:
|
|
1786
1890
|
|
|
1787
|
-
-
|
|
1891
|
+
- One name for one concept, everywhere (\`variant\`, \`size\`, \`disabled\` mean the same on every component).
|
|
1892
|
+
- Narrow literal types, not wide strings (\`'primary' | 'secondary'\`, never \`string\`).
|
|
1893
|
+
- A sensible default for every prop, so bare usage always works.
|
|
1894
|
+
- Composition over configuration: slots and child components, not an opaque config object.
|
|
1895
|
+
- One reactivity model per framework; do not mix idioms.
|
|
1896
|
+
- The MCP server closes the loop: if a component or prop is not in \`docs-show\`, it does not exist.
|
|
1897
|
+
- Do not generate a design system from scratch: reuse the library's tokens and components.
|
|
1788
1898
|
## Definition of Done
|
|
1789
1899
|
|
|
1790
1900
|
This workspace is strict, not lenient-by-default: \`tsconfig.base.json\` has
|
|
@@ -1813,7 +1923,7 @@ npm run preflight
|
|
|
1813
1923
|
\`\`\`
|
|
1814
1924
|
|
|
1815
1925
|
It checks Node, Claude CLI, \`FIGMA_ACCESS_TOKEN\`, MCP endpoint reachability, and port availability.
|
|
1816
|
-
|
|
1926
|
+
Rescue steps for a red seat: \`course/rescue.md\`.
|
|
1817
1927
|
${options.figmaMcp
|
|
1818
1928
|
? `
|
|
1819
1929
|
## Figma Setup
|
|
@@ -1821,17 +1931,23 @@ ${options.figmaMcp
|
|
|
1821
1931
|
The \`figma-console\` MCP is enabled in \`.mcp.json\`. It needs the Figma Desktop Bridge
|
|
1822
1932
|
plugin installed in the Figma desktop app before the server can respond.
|
|
1823
1933
|
|
|
1824
|
-
Setup
|
|
1934
|
+
Setup, once: run \`npx -y figma-console-mcp@1.40.0 --help\` (puts the plugin files into
|
|
1935
|
+
\`~/.figma-console-mcp/plugin/\`), then in Figma Desktop choose
|
|
1936
|
+
**Plugins → Development → Import plugin from manifest…** and pick
|
|
1937
|
+
\`~/.figma-console-mcp/plugin/manifest.json\`. Run **Plugins → Development → Figma Desktop
|
|
1938
|
+
Bridge** and keep the panel open; it flips from "searching…" to "connected" once Claude Code
|
|
1939
|
+
starts the MCP. Check with \`npm run preflight\`; trouble: \`course/rescue.md\`.
|
|
1825
1940
|
|
|
1826
1941
|
A \`FIGMA_ACCESS_TOKEN\` is optional — only required for REST-backed reads (screenshots,
|
|
1827
|
-
file exports). The Desktop Bridge covers creation and inspection without a token.
|
|
1942
|
+
file exports). The Desktop Bridge covers creation and inspection without a token. Create one
|
|
1943
|
+
under Figma → Settings → Security → Personal access tokens (scope: Files → File content,
|
|
1944
|
+
Read) and export it in your shell rc file.
|
|
1828
1945
|
`
|
|
1829
1946
|
: ''}
|
|
1830
|
-
##
|
|
1947
|
+
## Course material
|
|
1831
1948
|
|
|
1832
|
-
|
|
1833
|
-
|
|
1834
|
-
- CLAUDE.md template: ${SITE_URL}/claude-md
|
|
1949
|
+
Prompts, briefs and rescue steps for the course are in \`course/\` (start with
|
|
1950
|
+
\`course/README.md\`).
|
|
1835
1951
|
`);
|
|
1836
1952
|
// The contract loop's own devDependencies (ADR-0121 S4), gated on Figma
|
|
1837
1953
|
// (ADR-0144) — neither exists without `--figma`: the MCP SDK is only
|
|
@@ -1945,6 +2061,9 @@ file exports). The Desktop Bridge covers creation and inspection without a token
|
|
|
1945
2061
|
var _a;
|
|
1946
2062
|
pkg.scripts = (_a = pkg.scripts) !== null && _a !== void 0 ? _a : {};
|
|
1947
2063
|
pkg.scripts.preflight = 'node tools/scripts/preflight.mjs';
|
|
2064
|
+
if (framework === 'angular') {
|
|
2065
|
+
pkg.overrides = Object.assign(Object.assign({}, pkg.overrides), { '@angular-devkit/architect': ANGULAR_DEVKIT_ARCHITECT_VERSION });
|
|
2066
|
+
}
|
|
1948
2067
|
// The contract loop (ADR-0121 S4), gated on Figma (ADR-0144): neither
|
|
1949
2068
|
// script exists without `--figma` — see the contract-loop file-writing
|
|
1950
2069
|
// block above. `figma:snapshot` names the attendee's own Figma file key
|
|
@@ -2063,7 +2182,7 @@ file exports). The Desktop Bridge covers creation and inspection without a token
|
|
|
2063
2182
|
}
|
|
2064
2183
|
if (options.figmaMcp) {
|
|
2065
2184
|
// Desktop Bridge plugin (installed separately). FIGMA_ACCESS_TOKEN is
|
|
2066
|
-
// optional — only needed for REST-backed reads.
|
|
2185
|
+
// optional — only needed for REST-backed reads.
|
|
2067
2186
|
mcpServers['figma-console'] = {
|
|
2068
2187
|
command: 'npx',
|
|
2069
2188
|
args: ['-y', 'figma-console-mcp@1.40.0'],
|
|
@@ -2139,8 +2258,13 @@ Claude Code MCP servers are pre-configured in \`.mcp.json\`. They — and the
|
|
|
2139
2258
|
permissions/hooks in \`.claude/settings.json\` — only take effect once you've
|
|
2140
2259
|
accepted Claude Code's folder-trust prompt in your first session here; run
|
|
2141
2260
|
\`npm run preflight\` if you're not sure whether that's happened yet.
|
|
2142
|
-
|
|
2261
|
+
${framework === 'angular'
|
|
2262
|
+
? `Browse the library's components in the local Storybook (\`npm run storybook\`, then
|
|
2263
|
+
http://localhost:${storybookPort}/atelier/).`
|
|
2264
|
+
: `Look up components through the \`storybook-${framework}\` MCP server (\`docs-list\`, \`docs-show\`).`}
|
|
2265
|
+
Course material (prompts, briefs, rescue steps): \`course/README.md\`.
|
|
2143
2266
|
`);
|
|
2267
|
+
writeCourseFolder(tree, framework, (_f = options.figmaMcp) !== null && _f !== void 0 ? _f : false);
|
|
2144
2268
|
// ─── Claude Code project setup ────────────────────────────────────────────
|
|
2145
2269
|
// tasks/todo.md's "S3 — the workspace is set up for Claude Code" — a later,
|
|
2146
2270
|
// unrelated plan from the S1-S4 labels elsewhere in this file (those mark
|
|
@@ -2295,7 +2419,7 @@ Browse components at ${SITE_URL}
|
|
|
2295
2419
|
// the `figmaMcp`-selected source file, ADR-0144), and CLAUDE.md's "Agent
|
|
2296
2420
|
// Skills" section (built above) for why this one is called out separately
|
|
2297
2421
|
// from those four.
|
|
2298
|
-
tree.write('.claude/skills/atelier-component/SKILL.md', renderAtelierComponentSkill(appName, framework, (
|
|
2422
|
+
tree.write('.claude/skills/atelier-component/SKILL.md', renderAtelierComponentSkill(appName, framework, (_g = options.figmaMcp) !== null && _g !== void 0 ? _g : false));
|
|
2299
2423
|
// The copied skill (see listTemplateFiles' comment above): only when the
|
|
2300
2424
|
// workspace has figma-console to drive.
|
|
2301
2425
|
if (options.figmaMcp)
|
|
@@ -2308,7 +2432,7 @@ Browse components at ${SITE_URL}
|
|
|
2308
2432
|
// never be committed, unlike the shared `.claude/settings.json` written
|
|
2309
2433
|
// above.
|
|
2310
2434
|
const existingGitignore = tree.exists('.gitignore')
|
|
2311
|
-
? ((
|
|
2435
|
+
? ((_h = tree.read('.gitignore', 'utf-8')) !== null && _h !== void 0 ? _h : '')
|
|
2312
2436
|
: '';
|
|
2313
2437
|
const gitignoreBase = existingGitignore.replace(/\n+$/, '');
|
|
2314
2438
|
tree.write('.gitignore', `${gitignoreBase}${gitignoreBase ? '\n\n' : ''}# Claude Code — personal overrides, never shared\n.claude/settings.local.json\n`);
|