@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,178 @@
1
+ # Component brief — TagChip
2
+
3
+ > **Source: composed, not canonical.** There is no `tag-chip` or `chip` among the
4
+ > canonical components. This brief assembles one from two that _are_ canonical: the
5
+ > `tag` and `tag-remove` slots of a tag input, and the whole of `badge`. Where the two
6
+ > disagree, the disagreement is called out rather than smoothed over.
7
+ > **Starter frame:** `TagChip / Starter` — node `703:352` on the `🛠️ Workshop-Templates`
8
+ > page.
9
+ > **Read [`README.md`](README.md) first** — the shared rules and the "done when" bar
10
+ > live there and are not repeated here.
11
+
12
+ A compact labelled token that can be removed. It looks like a Badge and behaves like the
13
+ `tag` inside a Tag Input, and the gap between those two facts is the entire brief: a
14
+ Badge is **read-only by canonical contract**, and the moment you put an × on it you have
15
+ inherited a hit-target obligation the Badge was never designed to meet.
16
+
17
+ ---
18
+
19
+ ## 1. Anatomy
20
+
21
+ Six slots. Three come from `badge`. `remove-button` is `tag-input`'s `tag-remove`;
22
+ its two children are not slots `tag-input` declares — they follow the
23
+ `close-button` / `close-icon` / `close-label` split that `toast` records, which is
24
+ where the canonical roster puts an accessible name on an icon-only control.
25
+
26
+ | Slot | Required | From | Figma | What it is |
27
+ | --------------- | ------------------- | ------------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
28
+ | `root` | yes | badge `root` + tag-input `tag` | frame, auto-layout horizontal | The pill surface. Carries the variant treatment, the radius, and the padding budget. |
29
+ | `icon-leading` | no | badge | instance | Optional glyph before the label, on the leading edge with a consistent gap. |
30
+ | `label` | yes | badge | text | The chip's text and its accessible name. A noun phrase, truncating with ellipsis when it overflows. |
31
+ | `remove-button` | no | tag-input `tag-remove` | instance | Real `<button>`. Icon-button at the inline-end. Absent on read-only chips. |
32
+ | `remove-icon` | yes (of the button) | toast `close-icon` | instance | The × glyph. Decorative, always. |
33
+ | `remove-label` | yes (of the button) | toast `close-label` | text | The accessible name: `"Remove <label>"` — the wording is `tag-input`'s. Visually hidden, or an `aria-label` on the button. |
34
+
35
+ **Token budget.** `root`: background `color/surface-sunken` (neutral) or the severity's
36
+ `color/<severity>-bg`, foreground `color/text` or `color/<severity>-text`, border
37
+ `color/border`, radius `radius/full` for a pill or `radius/sm` for a rectangular chip,
38
+ padding and gap off `spacing/*`, type `font-size/xs` at `font-weight/semibold`.
39
+ `remove-button`: foreground `color/text-muted`, focus ring off `color/input-border-focus`.
40
+
41
+ **Where the two sources disagree.** `badge` puts the pill at `radius.pill` and the type
42
+ at `text.xs`; `tag-input`'s `tag` puts it at `radius.sm` and `text.sm`, because a tag
43
+ sits inside a form control and matches the input's type. Pick one and write the reason
44
+ into the description. A standalone chip is closer to a Badge; a chip inside a field is
45
+ closer to a tag. This decision _is_ the design work.
46
+
47
+ ---
48
+
49
+ ## 2. Axes
50
+
51
+ **Variant (the severity axis, from `badge`):** `default` · `success` · `warning` ·
52
+ `danger` · `info`. A closed enum — the same one the CSS contract maps to token pairs.
53
+
54
+ **Properties (not variants):**
55
+
56
+ | Property | Kind | Values | From |
57
+ | ----------- | ------- | ---------- | --------- |
58
+ | `size` | enum | `sm`, `md` | badge |
59
+ | `removable` | boolean | — | tag-input |
60
+ | `hasIcon` | boolean | — | badge |
61
+
62
+ `removable` is the axis that turns a Badge into a TagChip, and it is a **property**, not
63
+ a variant — exactly as `badge` models `dot`. Forking "Chip" and "Removable Chip" into two
64
+ components is the documented drift: they diverge in padding, size and border within a
65
+ release or two.
66
+
67
+ ### Scope for the 90-minute block
68
+
69
+ **In scope: `default` and `success`, with `removable: true`.** Two severities prove the
70
+ token pairing; `removable: true` is what makes this a TagChip at all and drags in the
71
+ whole a11y section. The chip is not itself the interactive element — the remove button
72
+ is (§3) — so per [`README.md` item 1](README.md#done-when) it draws no `state` axis at
73
+ all: hover and focus-visible on the × go into the master's description, exactly like the
74
+ states listed as out of scope below.
75
+
76
+ **Out of scope, and say so in the description rather than silently omitting:**
77
+ `warning`, `danger`, `info`, the `sm` size, `hasIcon`, Badge's own data states (`idle`,
78
+ `updated`, `max`, `hidden` — §3), the remove button's `hover`/`focus-visible` states, and
79
+ the selected/keyboard-navigated state a chip acquires inside a Tag Input — none of these
80
+ draws as a chip-level `state` axis; document them in the master's description instead.
81
+
82
+ ---
83
+
84
+ ## 3. States
85
+
86
+ **Interactive:** `hover`, `focus-visible` — on the **remove button**, not on the chip.
87
+ The chip itself is not a button. `badge`'s canonical record lists _no_ interactive states
88
+ at all, which is the honest starting point: the only focusable thing here is the ×.
89
+ Neither is drawn as a chip-level `state` axis — the chip is not the interactive element,
90
+ so per [`README.md` item 1](README.md#done-when) these go into the master's description
91
+ instead.
92
+
93
+ **Data (from `badge`):** `idle`, `updated`, `max`, `hidden`.
94
+
95
+ A chip living inside a Tag Input inherits that component's states as well — `empty`,
96
+ `filled`, `busy`, `invalid` belong to the field, not to the chip. Do not model them here.
97
+
98
+ There is one transition worth drawing even though it is out of scope to build: removal.
99
+ Activating the remove button takes the chip out of the value list **and moves focus to
100
+ the next chip**, or to the input if it was the last. Focus that lands nowhere after a
101
+ removal is the most common way this component breaks for keyboard users.
102
+
103
+ ---
104
+
105
+ ## 4. Accessibility requirements
106
+
107
+ The blocker here is the one people are most surprised by. Each item is also tagged
108
+ **(this block)** — checkable on the `default`/`success` frame with `removable: true` you
109
+ draw — or **(full component)** — real, and one of them blocker-severity, but dependent on
110
+ a behaviour (removal itself, multiple chips, `hasIcon`) this brief's scope puts out of
111
+ reach for the 90 minutes (see [`README.md` item 7](README.md#done-when)). A **(full
112
+ component)** tag is not permission to skip it — it is why the closing check does not fail
113
+ you for not having built it.
114
+
115
+ 1. **The hit target is at least 24 × 24 px.** _(blocker — WCAG 2.5.8 · this block)_ A
116
+ remove button sized to look right inside a compact chip is routinely 16px. Extend the
117
+ activation region with padding or an `::after` overlay so the _visible_ chip stays
118
+ compact while the _target_ meets the threshold. The canonical record's own advice is
119
+ blunter: if the design genuinely needs an interactive badge, reach for Tag Input or
120
+ Button instead — this component exists in the seam between them, and that is worth
121
+ knowing before you draw it. `removable: true` is in scope — the target size is
122
+ measurable directly on the frame.
123
+ 2. **Chips are removable by keyboard, not only by pointer.** _(blocker · full component)_
124
+ Inside a field, the canonical model is: Backspace at an empty input _selects_ the last
125
+ chip; a second Backspace removes it; ArrowLeft / ArrowRight navigate between selected
126
+ chips. Standalone, the minimum is that the remove button is a real `<button>` in the
127
+ tab order. Mouse-only removal is a hard fail. **Removal is explicitly out of scope to
128
+ build here (§3)** — a static Figma frame has no keyboard to fail with, so this cannot
129
+ be demonstrated in the 90-minute close. Draw the transition (§3) and write the keyboard
130
+ contract into the description; build it when you write the code.
131
+ 3. **Chips carry list structure.** _(blocker · full component)_ A row of chips is a
132
+ `<ul>` (or `role="list"`) with each chip an `<li>` — not a `<div>` of styled spans.
133
+ Without it a screen reader hears an undifferentiated run of text and cannot tell chip
134
+ from chrome. Depends on a row of chips; the starter frame is one chip.
135
+ 4. **Severity is never colour alone.** _(blocker · this block)_ Pair the variant with an
136
+ icon, a textual prefix, or a visually hidden severity word. Colour is reinforcement.
137
+ `default` and `success` are exactly the pair you draw — checkable directly.
138
+ 5. **The remove button names its target.** _(this block)_ `aria-label="Remove <label>"`
139
+ — not "Remove", not "Close". The user needs to know _which_ one they are about to
140
+ delete. `remove-label` is an anatomy slot (§1) present whenever `removable: true` —
141
+ checkable on the frame.
142
+ 6. **The remove icon announces nothing.** _(major · this block)_ `aria-hidden="true"` on
143
+ the glyph. Naming both the icon and the button double-announces. `remove-icon` is an
144
+ anatomy slot (§1), marked decorative — checkable on the frame.
145
+ 7. **The leading icon announces nothing either.** _(major · full component)_ Decorative
146
+ whenever a visible label is present. `hasIcon` — and with it `icon-leading` — is out of
147
+ scope (§2); nothing built here has a leading icon to mark.
148
+
149
+ ---
150
+
151
+ ## 5. Figma ↔ code gotchas
152
+
153
+ | Drawn as | Implemented as | Why it hurts |
154
+ | ----------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
155
+ | Static text-with-border decorations | Live elements with remove buttons that are part of the form value | Implementations follow the mock and ship styled spans: no remove affordance, no keyboard contract, no way to change a value except retyping all of it. |
156
+ | A "Chip" and a separate "Removable Chip" component | One component with a `removable` boolean | The two drift independently — different padding, different border, different size — and the canonical anatomy forks visually. |
157
+ | The × drawn, but no keyboard navigation between chips | Arrow-key navigation plus Backspace removal | Keyboard users must Tab through every chip's × in turn. The design encodes the affordance and omits the model. |
158
+ | Five separate frames, one per severity | One `variant` prop mapped to token pairs | The matrix doubles for nothing, and severity drift becomes invisible — `success` and `info` can quietly converge on the same hue. |
159
+
160
+ ---
161
+
162
+ ## 6. What "finished" looks like here
163
+
164
+ Beyond the shared bar in [`README.md`](README.md):
165
+
166
+ - One component set with `variant` (`default` / `success`) and a `removable` boolean —
167
+ not two components.
168
+ - The remove button's activation region measures ≥ 24 × 24 px even where the chip is
169
+ smaller, and the description says how that is achieved.
170
+ - The master's description states the remove button's `hover`/`focus-visible` styling and
171
+ the selected/keyboard-navigated model — neither is drawn as a chip-level axis (§2, §3).
172
+ - The description records **which** source you followed for radius and type (badge or
173
+ tag), and why.
174
+ - `default` and `success` are distinguishable with colour removed.
175
+
176
+ ---
177
+
178
+ **Before you prompt:** write the handoff document first. A filled example (for the Toast brief) is in `../handoff-example.md`.
@@ -0,0 +1,177 @@
1
+ # Component brief — Toast
2
+
3
+ > **Source:** a canonical component, mapped onto Atelier's `Library Tokens` vocabulary.
4
+ > **Starter frame:** `Toast / Starter` — node `703:341` on the `🛠️ Workshop-Templates`
5
+ > page.
6
+ > **Read [`README.md`](README.md) first** — the shared rules and the "done when" bar
7
+ > live there and are not repeated here.
8
+
9
+ A transient floating notification anchored to a corner of the viewport, auto-dismissing
10
+ after a short visible duration. It is **not** an Alert (inline, persistent) and not a
11
+ Modal (blocking). What separates it from both is ephemerality plus positioning — and
12
+ that distinction is the first thing the component owes: a message the user can afford
13
+ to miss.
14
+
15
+ ---
16
+
17
+ ## 1. Anatomy
18
+
19
+ Nine slots. Three are required outright — `viewport`, `container`, `body`; two more
20
+ become required the moment you add the close button. The two-tier structure —
21
+ a viewport that owns stacking and a container that owns one message — is the part
22
+ people get wrong, so it is the part to get right.
23
+
24
+ | Slot | Required | Figma | What it is |
25
+ | -------------- | ------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
+ | `viewport` | yes | frame | Fixed-position region at one viewport corner holding every visible toast. **One per page.** Owns stacking, hover-pause, and the landmark. |
27
+ | `container` | yes | frame, auto-layout horizontal | One toast's surface. Max inline size 360–420px. Carries the severity treatment and its own live-region role. |
28
+ | `icon` | no | instance | Severity glyph at the inline-start. Glyph swap bound to the severity variant. Decorative. |
29
+ | `title` | no | text | Optional brief heading. Only when the body runs multi-line — a single-line toast _is_ its headline. |
30
+ | `body` | yes | text | The message. One or two sentences, by canon. Anything longer is an Alert. |
31
+ | `action` | no | instance | **Exactly one** inline action ("Undo", "View"). Two actions is a redesign signal. |
32
+ | `close-button` | no | instance | Real button. Icon-button, close variant, inline-end. |
33
+ | `close-icon` | yes (of the button) | instance | The × glyph. Decorative, always. |
34
+ | `close-label` | yes (of the button) | text | The accessible name — a visually hidden "Dismiss notification", or an `aria-label` on the button. Counted as a slot so the dependency is structural, not prose. |
35
+
36
+ **Token budget.** `container`: background `color/surface-raised`, border `color/border`,
37
+ radius `radius/md`, padding and gap off the `spacing/*` ladder. `viewport`: `spacing/*`
38
+ padding and gap only. `icon` and `action` foreground: `color/text` or the severity
39
+ colour. `close-button` foreground: `color/text-muted`.
40
+
41
+ **The shadow is not a variable.** A toast floats, which means `--ui-shadow-lg`. There is
42
+ no `shadow/*` in `Library Tokens` — elevation lives only in `tokens.css`. State that in
43
+ your Figma description; do not invent a variable for it.
44
+
45
+ ---
46
+
47
+ ## 2. Axes
48
+
49
+ **Variant (the severity axis):** `info` · `success` · `warning` · `danger`.
50
+
51
+ **Properties (not variants):**
52
+
53
+ | Property | Kind | Values |
54
+ | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
55
+ | `position` | enum | `block-start-start`, `block-start-end`, `block-start-center`, `block-end-start`, `block-end-end`, `block-end-center` |
56
+ | `dismissible` | boolean | — |
57
+ | `hasAction` | boolean | — |
58
+ | `hasIcon` | boolean | — |
59
+
60
+ `position` is a property of the **viewport**, not of a toast. It selects a corner; it
61
+ does not restyle the message.
62
+
63
+ ### Scope for the 90-minute block
64
+
65
+ **In scope: `success` and `danger`, in the `open` and `closing` states.** Those two
66
+ severities are the pair that must differ in more than hue (see §4) and the pair whose
67
+ live-region politeness differs — so they carry the whole lesson between them. Model
68
+ `dismissible` and `hasIcon` as booleans if time allows.
69
+
70
+ **Out of scope, and say so in the description rather than silently omitting:** `info`
71
+ and `warning`, the six `position` values (build one corner), the stacking behaviour, and
72
+ the progress affordance.
73
+
74
+ ---
75
+
76
+ ## 3. States
77
+
78
+ **Interactive:** `hover`, `focus-visible`. These are CSS, not variants.
79
+
80
+ **Data:** `opening` → `open` → `paused` → `open` → `closing` → `closed`.
81
+
82
+ | From | To | Trigger |
83
+ | --------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
84
+ | `closed` | `opening` | The consumer fires the toast. It mounts; the timer is initialised but not started. |
85
+ | `opening` | `open` | Slide-in completes (or immediately under `prefers-reduced-motion: reduce`). **Now** the timer starts and the live region announces. |
86
+ | `open` | `paused` | Pointer enters the viewport **or** focus moves into it. Every visible toast pauses, not just the hovered one. |
87
+ | `paused` | `open` | Pointer and focus are both out. The timer **resumes** — it does not restart. Elapsed time counts. |
88
+ | `open` | `closing` | Timer expires; or Escape with focus in the region; or dismiss/action activated; or a programmatic close. |
89
+ | `closing` | `closed` | Slide-out completes (or immediately under reduced motion). Removed from the viewport and from the live region; the stack reflows. |
90
+
91
+ Announcement happens on entering `open`, not on mount. A toast that announces while it
92
+ is still sliding in announces content the user cannot yet read.
93
+
94
+ ---
95
+
96
+ ## 4. Accessibility requirements
97
+
98
+ Non-negotiable. Three of these are blocker-severity in the canonical record. Each is also
99
+ tagged **(this block)** — checkable against the frame and description you actually build
100
+ in the 90 minutes — or **(full component)** — true of Toast in production, worth writing
101
+ into the master's description, but dependent on the `paused` state, a multi-toast
102
+ scenario, or a runtime mechanism this exercise's scope does not build (see [`README.md`
103
+ item 7](README.md#done-when)).
104
+
105
+ 1. **Timers pause on hover and focus.** _(blocker — WCAG 2.2.1 Timing Adjustable · full
106
+ component)_ Pause on pointer-enter **and** focus-into the viewport; resume only when
107
+ both are out. Pause at viewport level, not per toast, so a user can move between
108
+ adjacent toasts. Without this, a slow reader loses the message mid-sentence. Depends on
109
+ the `paused` state, which is out of scope here — document the contract in the
110
+ description; you are not building the pause itself.
111
+ 2. **Escape dismisses.** _(blocker · full component)_ With focus inside the toast region,
112
+ Escape closes the focused toast — or the most recent one if none is focused. Otherwise
113
+ the only exits are tabbing to the button or waiting, and the keyboard contract feels
114
+ broken next to every other light-dismiss surface. Keydown handling is code; document
115
+ the binding.
116
+ 3. **Severity drives live-region politeness.** _(major · full component)_ `info` and
117
+ `success` → `role="status"` (polite). `danger` → `role="alert"` (assertive). `warning`
118
+ is canonically polite. Marking every toast assertive interrupts the user for every
119
+ "Copied" and trains them to switch notifications off. The role split is a code
120
+ attribute with no Figma equivalent — state the mapping in the description; `success`
121
+ and `danger` are exactly the pair you draw, so this is the one place the description
122
+ carries real weight.
123
+ 4. **Critical errors are not toasts.** _(blocker · this block)_ Anything the user must act
124
+ on — a network failure, a data-loss warning — is an Alert or a Modal. Toast is for what
125
+ can be missed without consequence. Getting this wrong is a content decision that no
126
+ amount of correct markup repairs, and it is checkable directly on what you draw: neither
127
+ `success` nor `danger` should represent something un-missable.
128
+ 5. **The region is a landmark, not a live region.** _(full component)_ `role="region"`
129
+ with `aria-label="Notifications"` on the viewport; the live-region roles sit on the
130
+ individual toasts. Both are ARIA roles with no Figma representation — document them.
131
+ 6. **The close control announces once.** _(this block)_ `aria-label="Dismiss"` **or** a
132
+ visually hidden span — never both. The `close-icon` is `aria-hidden="true"` and never
133
+ carries a name of its own. `close-icon` and `close-label` are anatomy slots (§1) —
134
+ checkable directly on the frame if you build `dismissible`.
135
+ 7. **The icon is never the severity.** _(this block)_ `aria-hidden="true"` on the glyph;
136
+ severity reaches assistive tech through the role and the visible text. The `icon` slot
137
+ is marked decorative in the anatomy table (§1) — checkable on the frame you draw for
138
+ both in-scope severities.
139
+ 8. **Stack depth is capped.** _(major · full component)_ Three visible toasts; queue the
140
+ rest. An unbounded stack floods the screen and the screen reader alike. Requires
141
+ multiple live toasts, which the stacking behaviour this brief puts out of scope (§2)
142
+ makes undemonstrable here — document the cap, do not build the queue.
143
+ 9. **The action is a button.** _(this block)_ Reachable by Tab after the dismiss button,
144
+ with a real accessible name. Tab order is runtime, but "a button, not a styled span" is
145
+ a composition choice checkable on the frame if you build `hasAction` (§2).
146
+
147
+ ---
148
+
149
+ ## 5. Figma ↔ code gotchas
150
+
151
+ The four places this component's design file and its implementation habitually disagree.
152
+ Each one is worth a sentence in your Figma description.
153
+
154
+ | Drawn as | Implemented as | Why it hurts |
155
+ | ---------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
156
+ | A toast next to the button that triggered it | A single fixed-position viewport region per page | Per-trigger floating surfaces compete with each other and lose the stacking, the auto-dismiss and the live region all at once. |
157
+ | One static visual with no timer affordance | An auto-dismiss timer at a configurable duration | Designers do not see that it vanishes; developers ship no progress affordance and no sane default. Document the duration and the hover-pause as canonical behaviour. |
158
+ | "One toast" / "two toasts" / "three toasts" variants | One toast plus a viewport that stacks | The three-toast frame is decorative. Stacking is a viewport concern; document the max depth in the viewport slot, not as a toast variant. |
159
+ | An inline link "Undo" inside the body text | A Button in the `action` slot | An anchor is the wrong semantic (Undo does not navigate) and a click-handler span has no semantic at all. The body describes; the action is separately reachable. |
160
+
161
+ ---
162
+
163
+ ## 6. What "finished" looks like here
164
+
165
+ Beyond the shared bar in [`README.md`](README.md):
166
+
167
+ - The variant axis is named `variant` with values `success` and `danger` — lowercase,
168
+ matching the string-literal union the spec will carry.
169
+ - `success` and `danger` are distinguishable with colour removed.
170
+ - The description on the master states: the auto-dismiss duration, the hover-pause
171
+ contract, the Escape binding, and that the shadow is CSS-only.
172
+ - The two in-scope states are `open` and `closing`, and the description names the four
173
+ data states you did not build.
174
+
175
+ ---
176
+
177
+ **Before you prompt:** write the handoff document first. A filled example (for the Toast brief) is in `../handoff-example.md`.
@@ -0,0 +1,46 @@
1
+ # Day 1, Block 02: the Settings Card
2
+
3
+ Used in Day 1 Block 02. The Figma frame "Settings / Card" becomes a {{FRAMEWORK}} component
4
+ built from `@atelier-ui/{{FRAMEWORK_LC}}`. Select the frame in Figma first (the Desktop
5
+ Bridge must be connected, see `rescue.md`).
6
+
7
+ ## Generate the component
8
+
9
+ ```text
10
+ I've selected the "Settings / Card" frame in Figma.
11
+
12
+ 1. Use figma-console MCP (figma_get_component_for_development) to read
13
+ the frame's spec — I need the boundVariables and the visual reference.
14
+ 2. Use {{MCP}} MCP to look up AtlCard, AtlInput, AtlToggle,
15
+ and AtlButton props.
16
+ 3. Generate the {{FRAMEWORK}} component using:
17
+ - The Atelier UI components matched from Storybook
18
+ - The exact token names from boundVariables (they map 1-to-1 to CSS
19
+ custom properties — no conversion needed)
20
+ ```
21
+
22
+ ## If the first draft still drifts on tokens
23
+
24
+ Pattern-matching models sometimes fall back to a literal px or hex value even when told not
25
+ to. Paste this one-line fix-up instead of a full re-prompt:
26
+
27
+ ```text
28
+ Re-check every inline style/CSS value you just wrote against
29
+ var(--ui-*). AtlCard's heading in the canonical example uses
30
+ var(--ui-font-size-lg) for size, var(--ui-color-text) for colour, and the card's
31
+ own padding/gap are var(--ui-spacing-6) / var(--ui-spacing-4) — no literal px,
32
+ no hex, no Tailwind class. Replace anything that isn't a --ui-* custom property with
33
+ the matching one and tell me which line you changed.
34
+ ```
35
+
36
+ A font weight such as `600` in a `.css` file also fails `npm run check:stylelint`; the token
37
+ is `var(--ui-font-weight-semibold)`.
38
+
39
+ ## The agent checks itself (11:25 to 11:45)
40
+
41
+ {{LADDER}}
42
+
43
+ ## The comparison with Figma
44
+
45
+ The parity prompt for this row is in `parity-prompt.md`. Do not run it on a component that
46
+ fails lint or build.
@@ -0,0 +1,154 @@
1
+ # Day 1, Block 05: a screen from Storybook, against the clock
2
+
3
+ Used in Day 1 Block 05. You build a "Team directory" screen out of components that
4
+ already exist in `{{PKG}}`. The only thing you know about those components is what the
5
+ `{{MCP}}` MCP server tells you. Nobody gives you the steps: a brief, four rules, a clock
6
+ and closing checks.
7
+
8
+ ## The brief
9
+
10
+ A "Team directory" screen:
11
+
12
+ - A heading "Team directory".
13
+ - A toolbar: a search field labelled "Search people", a select labelled "Role" (All roles,
14
+ Engineer, Designer, Manager) and a primary button "Invite member".
15
+ - A table of members: Name, Email, Role, Status. Status is a badge: active is success,
16
+ invited is warning, suspended is danger.
17
+ - Pagination under the table, 5 rows per page.
18
+ - Search narrows by name or email, the role select narrows by role, both together.
19
+ Changing a filter goes back to page 1. No match shows the table's own empty state.
20
+ - Data: a hard-coded array of 12 members in the component. No HTTP.
21
+
22
+ Components involved: AtlInput (search), AtlSelect (role filter), AtlButton `primary`
23
+ (Invite member), AtlTable, AtlBadge (one per status), AtlPagination.
24
+
25
+ ## The four rules
26
+
27
+ 1. **Look before you write.** The agent calls `docs-list`, then `docs-show` for every
28
+ component, before the first line of code.
29
+ 2. **Every prop has a source.** A prop, input, slot or event in your code must appear in the
30
+ `docs-show` output (its code examples count) or in `docs-show-story`. Not documented
31
+ means not used, and the agent says so. The one exception: the import class names and the
32
+ package name come from the installed package's type exports, and the receipts say so.
33
+ 3. **No hand-built twin.** Where the library has a component, you use it. A `div` with a
34
+ border is not a card, a hand-styled `span` is not a badge.
35
+ 4. **No raw colours.** Every colour and every spacing is a `var(--ui-*)` token, in a plain
36
+ `.css` file. This is a rule you keep, not a check that enforces it: the checks below
37
+ catch only part of it.
38
+
39
+ **Done when** the screen runs and behaves as the brief says, and you can point to the
40
+ `docs-show` passage behind every prop you pick at random (or the prop was removed).
41
+
42
+ ## The start prompt
43
+
44
+ Paste this into Claude Code. It is only a start: where the agent goes wrong, and how you
45
+ steer it, is the exercise.
46
+
47
+ **Checkpoint:** before any file is written, the agent has shown you the component list and
48
+ the `docs-show` calls behind it. If it skipped that, stop it and have it start over from
49
+ rule 1.
50
+
51
+ ```text
52
+ Build a "Team directory" screen with components from {{PKG}} only.
53
+
54
+ Before you write any code:
55
+ 1. Call docs-list on the {{MCP}} MCP, then docs-show for every
56
+ component you plan to use. Tell me the list first.
57
+ 2. A prop, input, slot or event may be used only if it appears in the
58
+ docs-show output (its code examples count) or in docs-show-story.
59
+ If something you want is not documented, do not use it. Tell me.
60
+ 3. docs-show prints full code for only some stories and lists the rest by
61
+ name. If you need one of those (Sortable, Empty State), call
62
+ docs-show-story with its id. Do not guess what a story does from its name.
63
+
64
+ The screen:
65
+ - A heading "Team directory".
66
+ - A toolbar: a search field labelled "Search people", a select labelled
67
+ "Role" (All roles, Engineer, Designer, Manager) and a primary button
68
+ "Invite member".
69
+ - A table of members: Name, Email, Role, Status. Status is a badge:
70
+ active is success, invited is warning, suspended is danger.
71
+ - Pagination under the table, 5 rows per page.
72
+ - Search narrows by name or email, the role select narrows by role,
73
+ both together. Changing a filter goes back to page 1. No match shows
74
+ the table's own empty state.
75
+ - Data: a hard-coded array of 12 members in the component. No HTTP.
76
+
77
+ Rules:
78
+ - No hand-built element where the library has a component. Plain layout
79
+ elements (div, h1) are fine.
80
+ - Styles go in {{CSS}} (a separate .css file), only
81
+ var(--ui-*) tokens for colour and spacing: no hex, rgb, hsl or named
82
+ colours, no pixel values for spacing.
83
+ - Save the screen as {{FILE}}. Then mount it so the
84
+ app shows it instead of the Nx welcome page: {{MOUNT}}.
85
+
86
+ When you are done, list every library component you used with the
87
+ docs-list id it came from, and every prop with the docs-show line
88
+ it came from.
89
+ ```
90
+
91
+ {{LINTNOTE}}
92
+
93
+ ## The checks prompt
94
+
95
+ Paste this when the build time ends (16:30 on the clock, whatever the state of the screen).
96
+
97
+ ```text
98
+ {{CHECKS}}
99
+ ```
100
+
101
+ If the agent repairs formatting by hand, tell it: "`npm run format` is the fix for
102
+ `check:format`, and for nothing else."
103
+
104
+ ## The receipts prompt
105
+
106
+ Paste this after the checks. These checks do not catch an invented name or a hand-built
107
+ element, which is why the receipts come next.
108
+
109
+ ```text
110
+ You listed the components and props you used. Now check yourself against the
111
+ docs, not against memory: call docs-show again for each component and, for every
112
+ prop, input, slot and event in the code you wrote, print one line: the name, the
113
+ docs-show passage it appears in, or NOT DOCUMENTED. Remove everything marked NOT
114
+ DOCUMENTED, or tell me why you kept it.
115
+ ```
116
+
117
+ ## When the agent goes wrong
118
+
119
+ If it starts writing without calling `docs-list`:
120
+
121
+ ```text
122
+ Stop. Do not write more code yet. Call docs-list on {{MCP}} and give me the
123
+ ids of the components you will use. Then call docs-show on each and tell me, for
124
+ every prop you plan to use, where it appears in the output.
125
+ ```
126
+
127
+ If it uses an input the docs do not list:
128
+
129
+ ```text
130
+ You used <INPUT> on <ELEMENT>. Show me the exact line of the docs-show or
131
+ docs-show-story output it comes from. If there is none, remove it and tell me what
132
+ you do instead.
133
+ ```
134
+
135
+ If it hand-builds something the library has:
136
+
137
+ ```text
138
+ <ELEMENT> is hand-built. Call docs-list and check whether the library has a
139
+ component for it. If it does, replace it with that component, using only documented
140
+ props.
141
+ ```
142
+
143
+ ## The time box (80 minutes)
144
+
145
+ | Minutes | What happens |
146
+ | ------- | ------------------------------------------------------------------------------------------------------- |
147
+ | 5 | The brief and the four rules, plus one live `docs-show` on AtlTable from the trainer. The clock starts. |
148
+ | 30 | Build. The trainer stays quiet, then walks the room. |
149
+ | 15 | Checks and receipts. |
150
+ | 25 | Two volunteers show their receipts. Which prop had no source, and where did the import names come from? |
151
+ | 5 | Recap question. |
152
+
153
+ The build ends at 16:30 on the clock. If you are stuck, paste the four things in
154
+ {{STUCK_REF}}, or see `rescue.md`.