@atelier-ui/create-workspace 0.4.14 → 0.4.16
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/figma/snapshot.json +1 -1
- package/src/generators/preset/files/tools/scripts/preflight.mjs +6 -10
- package/src/generators/preset/preset.js +136 -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.
|
|
@@ -586,7 +690,7 @@ function installSkills(tree, skillsEnabled) {
|
|
|
586
690
|
}
|
|
587
691
|
function presetGenerator(tree, options) {
|
|
588
692
|
return tslib_1.__awaiter(this, void 0, void 0, function* () {
|
|
589
|
-
var _a, _b, _c, _d, _e, _f, _g;
|
|
693
|
+
var _a, _b, _c, _d, _e, _f, _g, _h;
|
|
590
694
|
const framework = (_a = options.framework) !== null && _a !== void 0 ? _a : 'angular';
|
|
591
695
|
const skillsEnabled = (_b = options.skills) !== null && _b !== void 0 ? _b : true;
|
|
592
696
|
// Pinned, not `latest` — see readOwnVersion()'s comment.
|
|
@@ -1656,7 +1760,7 @@ see the skill itself, or ask Claude Code to use it, for what each check actually
|
|
|
1656
1760
|
tree.write('CLAUDE.md', `# Atelier Workshop
|
|
1657
1761
|
|
|
1658
1762
|
This workspace uses Atelier for all UI components.
|
|
1659
|
-
|
|
1763
|
+
The API reference is the library's MCP server (see below): \`docs-list\`, then \`docs-show\`.
|
|
1660
1764
|
|
|
1661
1765
|
## MCP Servers
|
|
1662
1766
|
|
|
@@ -1683,12 +1787,7 @@ ${frameworkIdiomsSection}
|
|
|
1683
1787
|
|
|
1684
1788
|
## Composition Patterns
|
|
1685
1789
|
|
|
1686
|
-
When composing multi-component flows (login form, settings page, confirmation dialog, data list, notification center, management dashboard),
|
|
1687
|
-
|
|
1688
|
-
- Browse: ${SITE_URL}/patterns
|
|
1689
|
-
- JSON catalog (machine-readable): ${SITE_URL}/.well-known/cookbook-patterns.json
|
|
1690
|
-
|
|
1691
|
-
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.
|
|
1692
1791
|
|
|
1693
1792
|
## Design Tokens
|
|
1694
1793
|
|
|
@@ -1789,7 +1888,13 @@ composition over configuration, and a sensible default for every prop — so a m
|
|
|
1789
1888
|
has generated code for one component can infer the shape of the next. When you design
|
|
1790
1889
|
the API of your own component, these are the rules the library itself follows:
|
|
1791
1890
|
|
|
1792
|
-
-
|
|
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.
|
|
1793
1898
|
## Definition of Done
|
|
1794
1899
|
|
|
1795
1900
|
This workspace is strict, not lenient-by-default: \`tsconfig.base.json\` has
|
|
@@ -1818,7 +1923,7 @@ npm run preflight
|
|
|
1818
1923
|
\`\`\`
|
|
1819
1924
|
|
|
1820
1925
|
It checks Node, Claude CLI, \`FIGMA_ACCESS_TOKEN\`, MCP endpoint reachability, and port availability.
|
|
1821
|
-
|
|
1926
|
+
Rescue steps for a red seat: \`course/rescue.md\`.
|
|
1822
1927
|
${options.figmaMcp
|
|
1823
1928
|
? `
|
|
1824
1929
|
## Figma Setup
|
|
@@ -1826,17 +1931,23 @@ ${options.figmaMcp
|
|
|
1826
1931
|
The \`figma-console\` MCP is enabled in \`.mcp.json\`. It needs the Figma Desktop Bridge
|
|
1827
1932
|
plugin installed in the Figma desktop app before the server can respond.
|
|
1828
1933
|
|
|
1829
|
-
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\`.
|
|
1830
1940
|
|
|
1831
1941
|
A \`FIGMA_ACCESS_TOKEN\` is optional — only required for REST-backed reads (screenshots,
|
|
1832
|
-
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.
|
|
1833
1945
|
`
|
|
1834
1946
|
: ''}
|
|
1835
|
-
##
|
|
1947
|
+
## Course material
|
|
1836
1948
|
|
|
1837
|
-
|
|
1838
|
-
|
|
1839
|
-
- 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\`).
|
|
1840
1951
|
`);
|
|
1841
1952
|
// The contract loop's own devDependencies (ADR-0121 S4), gated on Figma
|
|
1842
1953
|
// (ADR-0144) — neither exists without `--figma`: the MCP SDK is only
|
|
@@ -2071,7 +2182,7 @@ file exports). The Desktop Bridge covers creation and inspection without a token
|
|
|
2071
2182
|
}
|
|
2072
2183
|
if (options.figmaMcp) {
|
|
2073
2184
|
// Desktop Bridge plugin (installed separately). FIGMA_ACCESS_TOKEN is
|
|
2074
|
-
// optional — only needed for REST-backed reads.
|
|
2185
|
+
// optional — only needed for REST-backed reads.
|
|
2075
2186
|
mcpServers['figma-console'] = {
|
|
2076
2187
|
command: 'npx',
|
|
2077
2188
|
args: ['-y', 'figma-console-mcp@1.40.0'],
|
|
@@ -2147,8 +2258,13 @@ Claude Code MCP servers are pre-configured in \`.mcp.json\`. They — and the
|
|
|
2147
2258
|
permissions/hooks in \`.claude/settings.json\` — only take effect once you've
|
|
2148
2259
|
accepted Claude Code's folder-trust prompt in your first session here; run
|
|
2149
2260
|
\`npm run preflight\` if you're not sure whether that's happened yet.
|
|
2150
|
-
|
|
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\`.
|
|
2151
2266
|
`);
|
|
2267
|
+
writeCourseFolder(tree, framework, (_f = options.figmaMcp) !== null && _f !== void 0 ? _f : false);
|
|
2152
2268
|
// ─── Claude Code project setup ────────────────────────────────────────────
|
|
2153
2269
|
// tasks/todo.md's "S3 — the workspace is set up for Claude Code" — a later,
|
|
2154
2270
|
// unrelated plan from the S1-S4 labels elsewhere in this file (those mark
|
|
@@ -2303,7 +2419,7 @@ Browse components at ${SITE_URL}
|
|
|
2303
2419
|
// the `figmaMcp`-selected source file, ADR-0144), and CLAUDE.md's "Agent
|
|
2304
2420
|
// Skills" section (built above) for why this one is called out separately
|
|
2305
2421
|
// from those four.
|
|
2306
|
-
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));
|
|
2307
2423
|
// The copied skill (see listTemplateFiles' comment above): only when the
|
|
2308
2424
|
// workspace has figma-console to drive.
|
|
2309
2425
|
if (options.figmaMcp)
|
|
@@ -2316,7 +2432,7 @@ Browse components at ${SITE_URL}
|
|
|
2316
2432
|
// never be committed, unlike the shared `.claude/settings.json` written
|
|
2317
2433
|
// above.
|
|
2318
2434
|
const existingGitignore = tree.exists('.gitignore')
|
|
2319
|
-
? ((
|
|
2435
|
+
? ((_h = tree.read('.gitignore', 'utf-8')) !== null && _h !== void 0 ? _h : '')
|
|
2320
2436
|
: '';
|
|
2321
2437
|
const gitignoreBase = existingGitignore.replace(/\n+$/, '');
|
|
2322
2438
|
tree.write('.gitignore', `${gitignoreBase}${gitignoreBase ? '\n\n' : ''}# Claude Code — personal overrides, never shared\n.claude/settings.local.json\n`);
|