@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.
Files changed (25) 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/figma/snapshot.json +1 -1
  23. package/src/generators/preset/files/tools/scripts/preflight.mjs +6 -10
  24. package/src/generators/preset/preset.js +136 -20
  25. package/src/generators/preset/preset.js.map +1 -1
package/CHANGELOG.md CHANGED
@@ -1,3 +1,23 @@
1
+ ## 0.4.16 (2026-11-19)
2
+
3
+ ### 🩹 Fixes
4
+
5
+ - **create-workspace:** regenerate the scaffold's Figma snapshot ([a5967b83](https://github.com/DominikPieper/atelier-ui/commit/a5967b83))
6
+
7
+ ### ❤️ Thank You
8
+
9
+ - Dominik Pieper @DominikPieper
10
+
11
+ ## 0.4.15 (2026-11-19)
12
+
13
+ ### 🩹 Fixes
14
+
15
+ - **create-workspace:** the seat carries the course material, not links to it ([7f136948](https://github.com/DominikPieper/atelier-ui/commit/7f136948))
16
+
17
+ ### ❤️ Thank You
18
+
19
+ - Dominik Pieper @DominikPieper
20
+
1
21
  ## 0.4.14 (2026-11-19)
2
22
 
3
23
  ### 🩹 Fixes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atelier-ui/create-workspace",
3
- "version": "0.4.14",
3
+ "version": "0.4.16",
4
4
  "description": "Nx preset for Atelier workshop workspaces",
5
5
  "keywords": [
6
6
  "nx",
@@ -0,0 +1,6 @@
1
+ # Course material
2
+
3
+ Everything you paste or read during the course is in this folder, so you never need a
4
+ website. Open the file for the block you are in.
5
+
6
+ {{INDEX}}
@@ -0,0 +1,40 @@
1
+ This stage uses the Angular template rules that `npm run lint` runs in this workspace.
2
+ Three prompts, in order, on the Settings Card you just generated. Prompt 1 is the clean
3
+ run; prompts 2 and 3 break it on purpose, the tool says so, and the agent repairs it.
4
+
5
+ **Prompt 1, the clean run.**
6
+
7
+ ```text
8
+ Run `npm run lint` and `npm run build`. Report each exit code. If one is not 0, read the
9
+ output (the full log when the summary has no error text), repair, and run both again.
10
+ ```
11
+
12
+ **Prompt 2, break it on purpose.** Do not let the agent fix anything yet.
13
+
14
+ ```text
15
+ Add an `<img src="/avatar.png">` without `alt` and a `<div (click)="save()">Save</div>`
16
+ to the Settings Card. Do not fix anything. Run `npm run lint`, report the exit code and
17
+ the rule ids it names.
18
+ ```
19
+
20
+ Expect a non-zero exit code and these rule ids: `alt-text` (the image),
21
+ `click-events-have-key-events` and `interactive-supports-focus` (the div).
22
+
23
+ **Prompt 3, repair from the output.**
24
+
25
+ ```text
26
+ Repair from the lint output. Run lint and build again and report both exit codes.
27
+ ```
28
+
29
+ Now read the repair. Did the agent write `alt=""`? Lint is green, and the image, if it
30
+ carries meaning, is now hidden from a screen reader. Green is not the same as right.
31
+
32
+ **Clean-up.**
33
+
34
+ ```text
35
+ Remove the image and the div again, run both, report the exit codes.
36
+ ```
37
+
38
+ What lint does not see: a raw `<button>` where a library component exists, and meaning
39
+ (`alt=""` passes). If the agent stalls or reports "failed" without error text, type
40
+ `npm run lint` (or `npm run build`) in the terminal and read the output yourself.
@@ -0,0 +1,10 @@
1
+ Prompt 1 (the clean run) works on any framework:
2
+
3
+ ```text
4
+ Run `npm run lint` and `npm run build`. Report each exit code. If one is not 0, read the
5
+ output (the full log when the summary has no error text), repair, and run both again.
6
+ ```
7
+
8
+ The break-it-on-purpose prompts of this stage plant Angular template syntax and were only
9
+ checked on Angular, so they are not part of the {{FRAMEWORK}} course material. If it is
10
+ time for them, watch the trainer's demo.
@@ -0,0 +1,30 @@
1
+ ## 5. The Figma bridge
2
+
3
+ The `figma-console` tools (`figma_take_screenshot`, `figma_get_selection`, ...) need the
4
+ Figma Desktop Bridge plugin running in Figma Desktop.
5
+
6
+ - **"bridge not connected" or a time-out.** In Figma Desktop run
7
+ **Plugins, Development, Figma Desktop Bridge** and leave the panel open while you work.
8
+ The panel scans ports 9223 to 9232; restart Claude Code so the MCP server claims a port,
9
+ and the panel flips from "searching" to "connected".
10
+ - **The plugin is missing from Development.** Run `npx -y figma-console-mcp@1.40.0 --help`
11
+ once (same version as the pin in `.mcp.json`) to put the plugin files into
12
+ `~/.figma-console-mcp/plugin/`, then in Figma Desktop **Plugins, Development, Import
13
+ plugin from manifest...** and pick that `manifest.json`.
14
+ - **The plugin is out of date** (preflight warns about it). Run the same `npx` command once
15
+ to refresh the files, close the panel and run the plugin again.
16
+ - **Every port 9223 to 9232 is in use.** Check who holds them (`lsof -nP -iTCP:9223
17
+ -sTCP:LISTEN`) before you stop anything. Old figma-console servers from earlier sessions
18
+ are the usual cause: `pkill -f figma-console-mcp` stops them, and Claude Code starts a
19
+ fresh one on the next tool call.
20
+ - **A node id returns nothing.** Node ids belong to one file and change when a frame is
21
+ recreated. Select the frame in Figma and call `figma_get_selection` to get the id that is
22
+ live in your session; in a duplicate the ids are new.
23
+ - **403 or "invalid token" on file reads.** `FIGMA_ACCESS_TOKEN` is optional: the bridge
24
+ covers inspection without it. To read metadata create a token in Figma (Settings,
25
+ Security, Personal access tokens; scope Files, File content: Read), export it
26
+ (`export FIGMA_ACCESS_TOKEN=figd_...` in your shell rc file) and restart Claude Code.
27
+
28
+ What works without the Figma Desktop Bridge: reading the readiness checklist in Figma, and
29
+ `docs-show` through the library MCP server. Anything that needs `figma_*` tools needs the
30
+ bridge: pair for that.
@@ -0,0 +1,3 @@
1
+ - **`atelier` is missing or not connected.** Run `npm install`, then `npm run preflight`
2
+ again. Start a new Claude Code session from the workspace root after the install; if the
3
+ server is still not listed, `/mcp` and reconnect `atelier`.
@@ -0,0 +1,6 @@
1
+ - **`storybook-{{FW}}` is disconnected, or every tool errors** (for example "Failed to
2
+ fetch manifest components.json: 522"). "Connected" only proves the URL answers, not that
3
+ the tools work. `npm run preflight` makes a real call against the endpoint and prints the
4
+ server's error text. If your network blocks outbound HTTPS, a corporate proxy needs
5
+ `HTTPS_PROXY=http://your-proxy:port` before you start Claude Code. A server-side fault is
6
+ not yours to fix: tell the trainer.
@@ -0,0 +1,32 @@
1
+ ## When you are stuck
2
+
3
+ Claude cannot see your terminal or your screen. A report that says "it does not work" gets a
4
+ guess; a report with the four things below gets a diagnosis. Paste these four things:
5
+
6
+ 1. **The exact error.** The first error, copied, not retyped and not summarised. The last
7
+ line of a long output is usually a consequence.
8
+ 2. **The exit code.** Run the gate as below and read the file afterwards. Piping into `head`
9
+ or `grep` reports the pipe's exit code, which is always `0`, so a red gate looks green.
10
+ 3. **What you expected.** One line: "exit 0", "the compact card is tighter", "no axe
11
+ violation".
12
+ 4. **What changed last.** The commands you ran in order, and the last thing that was green
13
+ before it broke.
14
+
15
+ ```shell
16
+ npm run check:stories > check.out 2>&1; echo $?
17
+ ```
18
+
19
+ A stuck report you can fill in and paste:
20
+
21
+ ```text
22
+ A gate is red. Help me find the cause, not just a patch.
23
+
24
+ Ran: npm run check:stories > check.out 2>&1; echo $?
25
+ Exit code: 1
26
+ Output: check.out (read it; the first error is the one that matters)
27
+ Expected: exit 0, every story renders and passes its play and axe check
28
+ Changed: since the last green run I only added the density prop and its stories (the failing story is the new one)
29
+
30
+ Before you change anything, tell me what you think the cause is and what
31
+ would prove you wrong.
32
+ ```
@@ -0,0 +1,126 @@
1
+ # Component briefs — Day 2
2
+
3
+ Four briefs, one per component you can choose on Day 2 of the course: [`toast.md`](toast.md), [`avatar.md`](avatar.md), [`tagchip.md`](tagchip.md), [`statcard.md`](statcard.md). Each one states **what a finished component owes** — its anatomy, its axes, its states and its accessibility obligations. None of them says how to draw it: that is the exercise. Toast and Avatar are canonical components; TagChip and StatCard are compositions of canonical ones, and say so on their first line.
4
+
5
+ ## Shared rules — true for all four
6
+
7
+ **Scope: 2 variants × 2 states.** The Figma block is 90 minutes with participants who
8
+ are new to Figma. Each brief names which two variants and which two states are in scope
9
+ and which are explicitly out. Building the full matrix is not the goal; building a
10
+ _correct_ slice of it is. The rest of the matrix is documented in the brief so the
11
+ participant knows what they deferred rather than what they forgot.
12
+
13
+ **Start from a starter frame, not a blank canvas.** Each brief names the frame on the
14
+ `🛠️ Workshop-Templates` page that comes across when you duplicate the Atelier file into
15
+ your own drafts. Fills, paddings and radii there are already bound to `Library Tokens`
16
+ variables. Copy it, rename it, build on it.
17
+
18
+ **Never mutate the original file.** `File → Duplicate to your drafts` first. The Atelier
19
+ file's variables are file-scoped; edits there collide globally.
20
+
21
+ **Bind tokens, do not type values.** Every fill, radius, padding and gap resolves through
22
+ a Figma Variable in the `Library Tokens` collection — the semantic tier that mirrors the
23
+ `--ui-*` custom properties. A hardcoded value is a Critical finding in the
24
+ Figma review.
25
+
26
+ **Elevation is a CSS-only token.** `Library Tokens` carries 84 variables — 50 colour, 10
27
+ spacing, 6 sizing (`control-height/*` + `row-height/*`), 5 radius, 12 typography, 1
28
+ opacity — and **no shadow**. `--ui-shadow-*` exists only in `tokens.css`. A component
29
+ whose design depends on a drop shadow (Toast, an elevated StatCard) has to state the
30
+ shadow in the brief and in code, because Figma cannot bind it. Notice this rather than
31
+ inventing a shadow variable.
32
+
33
+ **States get a Figma axis; the code's `variant` union never does.** Figma has exactly one
34
+ primitive for a mutually-exclusive option — a Component Property of type Variant — so a
35
+ master that needs to _draw_ hover, focus, active or disabled has no other way to do it
36
+ than a dedicated `state` axis, and Atelier's own library uses one routinely: `AtlButton`,
37
+ `AtlInput`, `AtlSelect`, `AtlCheckbox`, `AtlToggle` and ten more all carry a `state` axis
38
+ today (values such as `default`, `hover`, `focus`, `active`, plus data-flavoured ones like
39
+ `open`, `filled`, `invalid`). **What must never happen is that axis reaching the code
40
+ contract.** The boundary is the _component's own_ `variant` union — you declare it directly on your own
41
+ component, with no separate spec file. It holds only structural
42
+ values — `AtlButtonVariant = 'primary' | 'secondary' | 'outline' | 'danger'` — never a
43
+ state; in code, hover/focus/active/disabled stay CSS pseudo-classes and `disabled`/`aria-*`
44
+ attributes. `AtlButton`'s own master marks the boundary explicitly in its description:
45
+ every other property line reads "→ maps to AtlButtonSpec.X"; the `state` line reads only
46
+ "interaction state", with no arrow — nothing on the code side consumes it.
47
+
48
+ The canonical `card` component names the failure mode this protects against
49
+ (`variant-explosion-from-states`, severity minor): crossing a `state` axis against every
50
+ other axis multiplies frames — 3 variants × 4 states × 2 orientations is 24+ — **not**
51
+ that a `state` axis is forbidden. Keep it to one axis, and keep it curated rather than
52
+ fully crossed: Atelier draws 24 of `AtlButton`'s 48 possible `variant`×`size`×`state`
53
+ combinations, not all of them. Some masters skip the axis entirely and describe
54
+ interaction states in prose instead — `AtlCard`, `AtlBadge`, `AtlToast` and `AtlAvatar`
55
+ (the four components behind this workshop's own briefs) have no `state` axis, because
56
+ their own interactive affordance, where they have one at all, sits on a nested control
57
+ that already carries its own. Either choice is legitimate; what decides it is whether the
58
+ component itself is the interactive element. Structural differences (severity, shape,
59
+ elevation) are always the code's `variant`; everything else — a Figma `state` axis when
60
+ you draw one, prose when you don't — is a property, a state, or CSS.
61
+
62
+ **Colour is never the only signal.** Every severity, status or state that a sighted user
63
+ can see must also be available without colour — an icon, a word, or an accessible name.
64
+
65
+ ## Done when
66
+
67
+ The same bar for all four. It is reached in two steps, because the brief itself is only
68
+ the Figma half of the work: items 1–4 and 7 are checkable at the end of **Day 2 Block 01**
69
+ (Figma design and handoff document); items 5, 6 and 8 are checked against the
70
+ component and its stories, which do not exist until **Block 02** (component, stories) and
71
+ **Block 04** (verify). The numbering is kept across both lists because the briefs cite it.
72
+
73
+ ### Done after the Figma block (Day 2 Block 01)
74
+
75
+ 1. The Figma component set carries ≥ 2 variants on a `variant` axis named exactly as the
76
+ code union will be (`variant`, not `Variant`; `success`, not `Success`), **and** the
77
+ second axis your brief's scope line names — a lifecycle pair (`open` / `closing`), a
78
+ data pair (`image-loaded` / `initials-fallback`), or a curated interaction pair — drawn
79
+ as a `state` axis. If your component is not itself the interactive element, it does not
80
+ get an interaction axis at all: write those states into the master's description
81
+ instead, per the states rule above, and the closing check reads the description.
82
+ 2. Every fill, radius, padding and gap is bound to a `Library Tokens` variable.
83
+ 3. Every frame with children uses Auto Layout.
84
+ 4. A dark-mode variant renders correctly through the collection's `Dark` mode — no
85
+ second component, no hardcoded value.
86
+
87
+ <!-- numbering follows the full 1–8 list, which the briefs cite -->
88
+
89
+ 7. The a11y obligations tagged **(this block)** in the brief's own section are met, and
90
+ any blocker-severity mistakes among them are not present. Obligations tagged **(full
91
+ component)** describe the shipped component for later — each one depends on a state,
92
+ a scenario or a property this exercise's scope section puts out of scope to build, so
93
+ the closing check does not evaluate it; write it into the master's description instead
94
+ of building it.
95
+
96
+ ### Done after the code blocks (Day 2 Blocks 02 and 04)
97
+
98
+ 5. The component's prop names and values match the Figma property names one-for-one,
99
+ and there is one story per variant value and per Boolean state, so the Storybook shows
100
+ every axis you drew.
101
+ 6. The generated story file declares `tags: ['autodocs']`. Autodocs is not on globally in
102
+ any of the three Storybooks (`.storybook/main.ts` sets `docs: {}` and no preview file
103
+ sets a global tag) — every existing story opts in per file. A generated story usually
104
+ inherits the tag from the file it was modelled on; usually is not always, and without it
105
+ the component renders a Canvas and no Docs tab, failing the closing check for a reason
106
+ that has nothing to do with the participant's component.
107
+
108
+ <!-- numbering follows the full 1–8 list, which the briefs cite -->
109
+
110
+ 8. `figma_check_design_parity` on your own Figma node against the generated component
111
+ (needs the connected Desktop Bridge) comes back without unexplained deviations, and
112
+ the discrepancies it does report are understood, not merely absent. Use the parity prompt in `../parity-prompt.md`
113
+ (node id from your handoff document); Claude assembles what the call needs. A section
114
+ that is not compared is not reported, so a quiet report is not a clean component. Without the Desktop Bridge there is no parity call: sort the
115
+ differences by hand instead.
116
+
117
+ The shared checklist for the end of the day is the Definition of Done in `CLAUDE.md`
118
+ (format, stylelint, lint, build, unit tests and `npm run check:stories`, which `/verify`
119
+ runs) plus the dark-mode switch in the Storybook toolbar. This bar is the brief-specific
120
+ subset of it, not a second copy.
121
+
122
+ ## Before you prompt
123
+
124
+ Write a short handoff document for your component first (what is in scope, the token
125
+ bindings, the behaviour lines, what is out, the acceptance checks). A filled example,
126
+ built from the Toast brief, is in `../handoff-example.md`.
@@ -0,0 +1,153 @@
1
+ # Component brief — Avatar
2
+
3
+ > **Source:** a canonical component, mapped onto Atelier's `Library Tokens` vocabulary.
4
+ > **Starter frame:** `Avatar / Starter` — node `703:355` 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 graphic stand-in for a person, organisation, or entity — image, initials, or icon —
10
+ inside a bounded 1:1 surface. The component looks trivial and is not: its whole substance
11
+ is a **fallback chain** and the accessible name that has to survive every rung of it.
12
+ An avatar that renders correctly but announces "image, AB" has failed.
13
+
14
+ ---
15
+
16
+ ## 1. Anatomy
17
+
18
+ Five slots. One required; four conditional, and the conditions are the component.
19
+
20
+ | Slot | Required | Figma | What it is |
21
+ | ------------------ | -------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
22
+ | `container` | yes | frame, fixed size, aspect 1:1 | The bounded surface. Carries the shape, the size step, and the status anchor. Radius is bound to the shape variant. |
23
+ | `image` | no | image fill on the container | The primary representation. Loads async; `object-fit: cover`, cropped to the container shape. |
24
+ | `initials` | no | text, centred | Fallback when no image. One or two letters, size scaled to the avatar step. |
25
+ | `fallback-icon` | no | instance | Last rung. A generic person glyph when neither image nor name exists. |
26
+ | `status-indicator` | no | frame, small circle | Presence dot anchored to the container's **inline-end / block-end** corner, with a border matching the page background so it separates from the avatar surface. |
27
+
28
+ **The fallback chain is ordered and the order is a contract:**
29
+ `image` → `initials` → `icon`. The image rung activates when `src` is present _and_
30
+ the load succeeds; the initials rung when a name is present _and_ the image rung failed;
31
+ the icon rung when both failed.
32
+
33
+ **Token budget.** `container`: background `color/surface-sunken`, border `color/border`,
34
+ radius `radius/full` (circle) or `radius/md` (square). `initials`: foreground
35
+ `color/text-muted`, weight `font-weight/semibold`. `fallback-icon`: `color/text-muted`.
36
+ `status-indicator`: radius `radius/full`, border colour `color/surface`.
37
+
38
+ **Size is a token, not a number.** Bind the container's dimension to a step, not to
39
+ `24px`. A hardcoded pixel avatar drifts out of alignment with its neighbouring text the
40
+ first time the type scale is rebalanced.
41
+
42
+ ---
43
+
44
+ ## 2. Axes
45
+
46
+ **Variant (the shape axis):** `circle` · `square`.
47
+
48
+ **Properties (not variants):**
49
+
50
+ | Property | Kind | Values |
51
+ | -------------------- | ------- | ----------------------------------- |
52
+ | `size` | enum | `xs`, `sm`, `md`, `lg`, `xl` |
53
+ | `status` | enum | `online`, `offline`, `away`, `busy` |
54
+ | `hasStatusIndicator` | boolean | — |
55
+
56
+ Note what is _not_ here: there is no "image avatar" and no "initials avatar". Those are
57
+ **states of one component**, not variants of two (see §5).
58
+
59
+ ### Scope for the 90-minute block
60
+
61
+ **In scope: `circle` and `square`, in the `image-loaded` and `initials-fallback`
62
+ states.** That pair is the whole point of the component — it is where the fallback chain
63
+ becomes visible and where the accessible name has to be identical across both.
64
+
65
+ **Out of scope, and say so in the description rather than silently omitting:** the five
66
+ size steps (build `md`), the four `status` values, `image-loading`, and `icon-fallback`.
67
+
68
+ ---
69
+
70
+ ## 3. States
71
+
72
+ **Interactive:** `hover`, `focus-visible` — and only when the avatar is itself the
73
+ activator, which is rare. Usually the host element handles interaction.
74
+
75
+ **Data:** `image-loading`, `image-loaded`, `image-error`, `initials-fallback`,
76
+ `icon-fallback`.
77
+
78
+ These are data states, not variants — the runtime moves between them by itself as the
79
+ image resolves. The canonical record carries no named transitions for Avatar because the
80
+ movement is one-directional and driven by the load result rather than by user intent:
81
+ `image-loading` resolves to `image-loaded` or `image-error`, and `image-error` falls
82
+ through to `initials-fallback` and then `icon-fallback` as each rung's precondition
83
+ fails.
84
+
85
+ Draw at least the `image-loaded` and `initials-fallback` frames. The canonical guidance
86
+ is explicit: designers draw all three fallback rungs for **one** representative avatar,
87
+ so developers have a reference for the case the mock never shows.
88
+
89
+ ---
90
+
91
+ ## 4. Accessibility requirements
92
+
93
+ Two of these are blocker-severity. Both are about the name, not the picture. Each item is
94
+ also tagged **(this block)** — checkable on the `image-loaded` / `initials-fallback`
95
+ frames you draw and the description you write — or **(full component)** — real, but
96
+ dependent on the `status` axis, which §2 puts out of scope (see [`README.md` item
97
+ 7](README.md#done-when)).
98
+
99
+ 1. **Every rung has an accessible name.** _(blocker · this block)_ The initials and icon
100
+ rungs set `role="img"` plus `aria-label` on the container. The image rung uses
101
+ `<img alt="…">`. An avatar that renders "AB" with no label is meaningless to
102
+ assistive tech. Both in-scope frames exist for the same entity — write the shared
103
+ accessible name into the description (§6 requires this).
104
+ 2. **The fallback order is fixed.** _(blocker · this block)_ image → initials → icon,
105
+ always. An implementation that falls back differently depending on environment or
106
+ library version gives the same person a different identity on different screens. The
107
+ two frames you draw are two points on this order — checkable directly.
108
+ 3. **The name is the full name, never the initials.** _(major · this block)_
109
+ `aria-label="Alex Black"`, not `aria-label="AB"`. The initials are visual shorthand;
110
+ the accessible name is the source of truth. Same description requirement as item 1.
111
+ 4. **`alt` is always present on the image rung.** _(major · this block)_ `alt=""` for a
112
+ decorative avatar whose host already carries the name; `alt="<entity name>"`
113
+ otherwise. Never _undefined_ — some screen readers then announce the file path. The
114
+ `image-loaded` frame is in scope — state the `alt` value in its description.
115
+ 5. **The status dot carries a label.** _(major · full component)_ `aria-label="online"` /
116
+ `"offline"` / `"away"` / `"busy"`. A coloured dot alone is sighted-only information.
117
+ The `status` axis and `hasStatusIndicator` are both out of scope (§2) — nothing built
118
+ here has a status dot to label.
119
+ 6. **Decorative avatars opt out entirely.** _(this block)_ When a visible name sits
120
+ beside the avatar, set `aria-hidden="true"` and let the host's name carry it —
121
+ announcing the name twice is worse than not announcing it here at all. A content
122
+ decision, independent of which fallback rung is showing — state it in the description.
123
+ 7. **The status dot anchors with logical properties.** _(full component)_ `inset-inline-end`
124
+ / `inset-block-end`, so it mirrors under RTL instead of stranding itself on the wrong
125
+ edge. Depends on the status indicator, which is out of scope (§2).
126
+
127
+ ---
128
+
129
+ ## 5. Figma ↔ code gotchas
130
+
131
+ | Drawn as | Implemented as | Why it hurts |
132
+ | ------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
133
+ | "Avatar (image)" and "Avatar (initials)" as two components | One component with a runtime fallback chain | The two drift. Designers stop drawing the initials frame for new avatars, and developers have no reference for the fallback the user will actually see. |
134
+ | A coloured dot placed near the avatar at absolute coordinates | A slot anchored via logical properties | Identical in LTR, wrong in RTL. Model the dot as a **child** of the container, not a sibling. |
135
+ | Static text "AB" baked into the frame | Initials computed from a `name` prop | The file never documents the algorithm — first letter? first two? first of each word? — so every implementation reinvents it. Canon: **first letter of each word, max two**. |
136
+ | `width: 24px` on the frame | A size token (`xs`…`xl`) | The Figma file lags the next scale rebalance and the shipped avatar disagrees with the text beside it. |
137
+
138
+ ---
139
+
140
+ ## 6. What "finished" looks like here
141
+
142
+ Beyond the shared bar in [`README.md`](README.md):
143
+
144
+ - One component set with a `variant` axis of `circle` / `square` — not two components.
145
+ - The `image-loaded` and `initials-fallback` frames both exist, for the same entity,
146
+ with the **same** accessible name written into the description.
147
+ - The description states the fallback order and the initials algorithm.
148
+ - The status dot, if you build it, is a child of the container and positioned with
149
+ logical properties.
150
+
151
+ ---
152
+
153
+ **Before you prompt:** write the handoff document first. A filled example (for the Toast brief) is in `../handoff-example.md`.
@@ -0,0 +1,193 @@
1
+ # Component brief — StatCard
2
+
3
+ > **Source: composed, not canonical.** There is no `stat-card` among the canonical
4
+ > components. This brief assembles one from `card` and `badge`. Two of the slots below —
5
+ > `value` and `delta` — have **no canonical counterpart**; they are this composition's
6
+ > own, mapped onto slots that do exist. Every such mapping is marked.
7
+ > **Starter frame:** `StatCard / Starter` — node `703:348` on the
8
+ > `🛠️ Workshop-Templates` 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 bounded surface presenting one metric: a label, the number, and how it is trending.
13
+ The temptation is to treat it as "a Card with a big number in it". The reason it needs a
14
+ brief is that a Card's canonical anatomy has a **required** action slot and a StatCard
15
+ has no action — so the first thing this component owes is a recorded decision about what
16
+ it drops and why.
17
+
18
+ ---
19
+
20
+ ## 1. Anatomy
21
+
22
+ Six slots. Four map onto canonical Card slots; two are this composition's own.
23
+
24
+ | Slot | Required | Maps to | Figma | What it is |
25
+ | ----------- | -------- | ---------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
26
+ | `container` | yes | card (the surface itself) | frame, auto-layout vertical | The bounded surface. Carries the variant treatment, the radius and the padding budget. |
27
+ | `label` | yes | card `eyebrow` | text | What is being measured. Short, categorical, above the number — establishes context before the value. **Not** a heading: it is metadata. |
28
+ | `value` | yes | _composition-specific_ — occupies card `title` | text | The number itself, at display size. The card's primary identifier, and it must read as a standalone label outside the card's context. |
29
+ | `delta` | no | _composition-specific_ — a `badge` instance | instance | The trend marker: `+12%`, `−3.4%`. A Badge with a severity variant. |
30
+ | `caption` | no | card `subtitle` | text | Secondary descriptor narrowing the value — "vs. last week", "rolling 30 days". Not a place for prose. |
31
+ | `footer` | no | card `footer` | frame, auto-layout horizontal | Tertiary metadata at lower visual weight — timestamp, source, a link out. |
32
+
33
+ **The slot this composition drops.** Card marks `primary-action` **required** — exactly
34
+ one decision-committing button per card. A StatCard commits no decision. Dropping it is
35
+ legitimate, and recording the drop in the master's description is the difference between
36
+ a deliberate composition and an incomplete one. If your StatCard _does_ need a "View
37
+ details" affordance, read §4.1 first: it changes the component's keyboard story
38
+ completely.
39
+
40
+ **Token budget.** `container`: background `color/surface-raised` (elevated) or
41
+ `color/surface` with `color/border` (outlined), radius `radius/lg`, padding off
42
+ `spacing/*`. `label`: `color/text-muted`, `font-size/xs`, `font-weight/medium`, with
43
+ `letter-spacing` wide if you uppercase it. `value`: `color/text`, the largest step your
44
+ type scale offers. `caption` and `footer`: `color/text-muted`, `font-size/xs`.
45
+ `delta`: the Badge's own severity pair — `color/success-bg` + `color/success-text`, or
46
+ `color/danger-bg` + `color/danger-text`.
47
+
48
+ **Elevation is a CSS-only token.** The `elevated` variant needs `--ui-shadow-md`, and
49
+ `Library Tokens` carries no `shadow/*` — Figma cannot bind it. State the shadow in the
50
+ description; do not invent a variable for it. (This is why the `outlined` variant, which
51
+ needs only `color/border`, is the easier of the two to make token-true.)
52
+
53
+ ---
54
+
55
+ ## 2. Axes
56
+
57
+ **Variant (from `card`):** `elevated` · `outlined` · `flat`. These are structurally
58
+ different surfaces, which is what earns them a variant axis.
59
+
60
+ **Properties (not variants):**
61
+
62
+ | Property | Kind | Values | From |
63
+ | ------------- | ------- | ------------------------ | ---------------------- |
64
+ | `orientation` | enum | `vertical`, `horizontal` | card |
65
+ | `density` | enum | `comfortable`, `compact` | card |
66
+ | `interactive` | boolean | — | card |
67
+ | `hasDelta` | boolean | — | _composition-specific_ |
68
+
69
+ `orientation` is a **property**, not a variant — the single most common counting
70
+ mismatch on this component. Designers who model it as a variant see six variants where
71
+ developers see three variants and a binary prop, and the two files stop agreeing about
72
+ what exists.
73
+
74
+ ### Scope for the 90-minute block
75
+
76
+ **In scope: `elevated` and `outlined`, in the `delta-up` and `delta-down` states, with
77
+ `hasDelta: true`.** The two variants differ in exactly one dimension — border versus
78
+ shadow — which makes the Figma-cannot-bind-a-shadow lesson concrete rather than
79
+ theoretical. `delta-up` and `delta-down` are this composition's own `state` axis (§3) — a
80
+ data pair, not an interaction pair, since a static StatCard has no interaction states to
81
+ draw (see below) — and drawing both is what makes item 3's colour-alone blocker (§4)
82
+ checkable directly on the frame rather than merely asserted in prose. `hasDelta: true` is
83
+ what pulls the axis, and the Badge composition, into scope at all.
84
+
85
+ **Out of scope, and say so in the description rather than silently omitting:** `flat`,
86
+ both `orientation` values (build `vertical`), `density`, `interactive`, and the
87
+ `selected` / `loading` data states.
88
+
89
+ ---
90
+
91
+ ## 3. States
92
+
93
+ **Interactive (from `card`):** `hover`, `focus-visible`, `active`, `disabled` — and only
94
+ when `interactive: true`. A static StatCard has none of them, and drawing hover on a
95
+ non-interactive card promises an affordance that is not there.
96
+
97
+ **Data (from `card`):** `selected`, `loading`.
98
+
99
+ `loading` deserves a thought even though it is out of scope to build: a StatCard's
100
+ whole content is one asynchronous number, so the skeleton state is not decoration — it
101
+ is the state the component spends its first frames in. Note in the description what the
102
+ card shows before the number arrives.
103
+
104
+ **`selected` is a data state, not a variant.** Modelling it as "outline + filled
105
+ background" duplicates the treatment in two places and blocks the combination
106
+ `selected + disabled` outright.
107
+
108
+ **Data (composition-specific): `delta-up`, `delta-down`.** `card` carries no delta of its
109
+ own — this pair belongs to the `delta` slot's composition, not to `card` — and it is the
110
+ one `state` axis this brief actually draws (§2). A `hasDelta: true` card renders as
111
+ `delta-up` (the Badge `success` pairing) or `delta-down` (the Badge `danger` pairing);
112
+ both frames are in scope precisely because the direction has to survive without colour
113
+ (§4 item 3).
114
+
115
+ ---
116
+
117
+ ## 4. Accessibility requirements
118
+
119
+ Each item is tagged **(this block)** — checkable on the `elevated`/`outlined` frames,
120
+ drawn in both `delta-up` and `delta-down`, with `hasDelta: true` — or **(full
121
+ component)** — real, but dependent on `interactive`, a live data feed, or an optional
122
+ slot this brief's scope puts out of reach (see [`README.md` item 7](README.md#done-when)).
123
+
124
+ 1. **An interactive card is one activator, and nested controls need the overlay
125
+ pattern.** _(blocker · full component)_ Wrapping the whole card in an `<a>` makes it a
126
+ single tab stop and traps anything focusable inside it — a screen reader then reads the
127
+ nested controls as part of the link's name. The canonical fix: keep the card a plain
128
+ container, give the `value` (or `label`) a real `<a>` whose `::before` covers the card,
129
+ and lift genuinely separate controls onto a higher stacking context. `interactive` is
130
+ out of scope (§2) — nothing built here is clickable.
131
+ 2. **A clickable card has a real focusable activator.** _(blocker · full component)_ A
132
+ click handler on a `<div>` is unreachable by keyboard and unannounced. `<a href>` for
133
+ navigation, `<button>` for in-page actions — never `role="button"` on the card div.
134
+ Same dependency on `interactive` as item 1.
135
+ 3. **The delta is never colour alone.** _(blocker, from `badge` · this block)_ Green-up /
136
+ red-down is invisible to a large group of users. Pair it with a sign (`+` / `−`), an
137
+ arrow glyph _plus_ text, or a visually hidden word. The number's direction must survive
138
+ greyscale. `delta-up` and `delta-down` are both in scope (§2, §3) — checkable directly
139
+ by comparing the two drawn frames in greyscale, not merely asserted of a single one.
140
+ 4. **A live-updating value announces politely.** _(major, from `badge` · full component)_
141
+ If the number changes without a navigation, wrap it in `aria-live="polite"` with
142
+ `aria-atomic="true"` so the whole new value reads rather than a fragment — and
143
+ throttle it, or a fast-moving metric floods the screen reader. Requires an actual data
144
+ feed, which a static frame does not have — document the contract instead.
145
+ 5. **The label is not a heading.** _(this block)_ Card's canonical guidance: the eyebrow
146
+ is metadata. If the value and label need to be announced as a unit, associate them
147
+ with `aria-labelledby` rather than promoting the label to `<h3>`. The `label` slot's
148
+ text style is a drawn choice, checkable on the frame.
149
+ 6. **Value and label are announced together.** _(this block)_ "1,284" alone is
150
+ meaningless. Whichever mechanism you pick — DOM order, `aria-labelledby`, or a
151
+ visually hidden combined string — write it into the description.
152
+ 7. **A decorative delta icon is hidden.** _(major · this block)_ `aria-hidden="true"` on
153
+ the arrow glyph when a textual sign is already present; otherwise it double-announces.
154
+ The `delta` badge instance is in scope (`hasDelta: true`) — checkable on the frame.
155
+ 8. **Media alt never repeats the label.** _(minor · full component)_ If you add a
156
+ sparkline or an icon, its alt adds what the text does not say ("Chart showing 12%
157
+ growth"), or it is `alt=""`. Media is not part of this composition's anatomy (§1) — it
158
+ applies only if you add one later.
159
+
160
+ ---
161
+
162
+ ## 5. Figma ↔ code gotchas
163
+
164
+ | Drawn as | Implemented as | Why it hurts |
165
+ | --------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
166
+ | Variants for hover / focus / active / disabled | CSS pseudo-classes and ARIA attributes | 3 variants × 4 states × 2 orientations is 24+ frames, and none of them maps to a pseudo-class without a hand translation. Document interaction states on a separate states sheet. |
167
+ | Media-on-top and media-on-leading as separate variants | One component with an `orientation` prop | Designers count six variants, developers count three plus a binary union. The counts diverge and so do the files. |
168
+ | A card component stacked on an invisible button component | One `<a>`/`<button>` wrapping the card, or the overlay pattern | The Figma file does not encode the affordance, so neither side realises the whole card must be a single accessible activator. |
169
+ | A "selected" variant with outline + filled background | A `data-selected` / `aria-selected` attribute | The treatment is duplicated in two places and drifts, and `selected + disabled` becomes unrepresentable. |
170
+
171
+ ---
172
+
173
+ ## 6. What "finished" looks like here
174
+
175
+ Beyond the shared bar in [`README.md`](README.md):
176
+
177
+ - The variant axis is `variant` with values `elevated` and `outlined` — `orientation`
178
+ and `density` are properties if you model them at all.
179
+ - The master's description records: that `primary-action` was deliberately dropped, that
180
+ the `elevated` shadow is a CSS-only token, and what the card shows while the number is
181
+ loading.
182
+ - The delta's direction is readable in greyscale.
183
+ - The `state` axis is `delta-up` / `delta-down` — the composition's own data pair, not a
184
+ `card` state — and the description names the `card` states
185
+ (`hover`/`focus-visible`/`active`/`disabled`, `selected`, `loading`) this brief does not
186
+ build.
187
+ - The `delta` slot is an **instance** of your Badge (or of `Display/AtlBadge`), not a
188
+ hand-drawn pill — the composition has to be a real composition, or the next token
189
+ change breaks it silently.
190
+
191
+ ---
192
+
193
+ **Before you prompt:** write the handoff document first. A filled example (for the Toast brief) is in `../handoff-example.md`.