@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.
Files changed (24) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/package.json +1 -1
  3. package/src/generators/preset/files/course/README.md +6 -0
  4. package/src/generators/preset/files/course/_fragments/ladder-angular.md +40 -0
  5. package/src/generators/preset/files/course/_fragments/ladder-other.md +10 -0
  6. package/src/generators/preset/files/course/_fragments/rescue-figma.md +30 -0
  7. package/src/generators/preset/files/course/_fragments/rescue-mcp-angular.md +3 -0
  8. package/src/generators/preset/files/course/_fragments/rescue-mcp-hosted.md +6 -0
  9. package/src/generators/preset/files/course/_fragments/stuck.md +32 -0
  10. package/src/generators/preset/files/course/briefs/README.md +126 -0
  11. package/src/generators/preset/files/course/briefs/avatar.md +153 -0
  12. package/src/generators/preset/files/course/briefs/statcard.md +193 -0
  13. package/src/generators/preset/files/course/briefs/tagchip.md +178 -0
  14. package/src/generators/preset/files/course/briefs/toast.md +177 -0
  15. package/src/generators/preset/files/course/day1-settings-card.md +46 -0
  16. package/src/generators/preset/files/course/day1-team-directory.md +154 -0
  17. package/src/generators/preset/files/course/day2-prompts.md +105 -0
  18. package/src/generators/preset/files/course/figma-linter-prompt.md +20 -0
  19. package/src/generators/preset/files/course/handoff-example.md +68 -0
  20. package/src/generators/preset/files/course/parity-prompt.md +38 -0
  21. package/src/generators/preset/files/course/rescue.md +59 -0
  22. package/src/generators/preset/files/tools/scripts/preflight.mjs +6 -10
  23. package/src/generators/preset/preset.js +144 -20
  24. 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 — see https://atelier.pieper.io/troubleshooting#plugin-update`,
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, or see /troubleshooting#figma-bridge-port-conflict',
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
- 'See https://atelier.pieper.io/figma-token if you need metadata reads',
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 — see https://atelier.pieper.io/troubleshooting#mcp-tools-error',
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 — see https://atelier.pieper.io/troubleshooting',
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
- Full API reference: ${SITE_URL}/llms-full.txt
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), check the cookbook first:
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
- - Guide: ${SITE_URL}/design-principles
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
- Full troubleshooting guide: ${SITE_URL}/troubleshooting
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 guide: ${SITE_URL}/figma-token
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
- ## Reference
1947
+ ## Course material
1831
1948
 
1832
- - Component browser + docs: ${SITE_URL}
1833
- - MCP Playground (inspect tool responses): ${SITE_URL}/mcp
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. See ${SITE_URL}/figma-token.
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
- Browse components at ${SITE_URL}
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, (_f = options.figmaMcp) !== null && _f !== void 0 ? _f : false));
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
- ? ((_g = tree.read('.gitignore', 'utf-8')) !== null && _g !== void 0 ? _g : '')
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`);