@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,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`.
|