@atelier-ui/create-workspace 0.4.14 → 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.
- package/CHANGELOG.md +10 -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/tools/scripts/preflight.mjs +6 -10
- package/src/generators/preset/preset.js +136 -20
- package/src/generators/preset/preset.js.map +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,13 @@
|
|
|
1
|
+
## 0.4.15 (2026-11-19)
|
|
2
|
+
|
|
3
|
+
### 🩹 Fixes
|
|
4
|
+
|
|
5
|
+
- **create-workspace:** the seat carries the course material, not links to it ([7f136948](https://github.com/DominikPieper/atelier-ui/commit/7f136948))
|
|
6
|
+
|
|
7
|
+
### ❤️ Thank You
|
|
8
|
+
|
|
9
|
+
- Dominik Pieper @DominikPieper
|
|
10
|
+
|
|
1
11
|
## 0.4.14 (2026-11-19)
|
|
2
12
|
|
|
3
13
|
### 🩹 Fixes
|
package/package.json
CHANGED
|
@@ -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,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`.
|