altitude-design 0.3.2 → 0.4.1

package/dist/guidance/components/ChartReference/README.md

@@ -0,0 +1,115 @@
+# ChartReference and ChartAnnotation
+
+Reading a chart against something: an SLO target, a budget, a normal range, the average, the day you shipped v2. Overlays like these help people read charts (Kong & Agrawala 2012), and most dashboards need at least a target line and an event marker. Put them inside any cartesian chart type, or inside the container:
+
+```tsx
+<LineChart data={uptime} x="day">
+  <ChartReference y={[0.995, 1]} label="Normal range" />
+  <ChartReference y={0.999} label="Target 99.9%" />
+  <ChartReference y={0.99} label="Limit 99%" tone="critical" />
+  <ChartReference y="mean" label="Average" />
+  <ChartAnnotation x="2026-03-14" label="DNS outage" />
+</LineChart>
+```
+
+**Why they're flush.** References and annotations are part of the reading, not something to act on, so they lie on the ground with the marks:
+
+| Part | Drawn as | Words |
+|---|---|---|
+| Reference line | 1px `ink-muted`, solid, over the marks. Dashes mean "projected", so a reference line never has them | its label at the right end, above the line, in caption text; below it, at the left end or further along when that spot would cover a mark |
+| Status threshold (`tone`) | 1px `caution` or `critical` | the label in `ink`, with the status icon in its tone |
+| Band (`y={[low, high]}`) | a flat `line` fill under the marks: a decorative token, so it isn't read as data or as an opening | its label inside the band, at whichever corner covers no mark, or beside it when the band is under 20px tall |
+| Annotation | a `Badge` plate flush at the top of the plot, in a row of headroom above the data (a label is part of the record), with a 1px `line-control` leader down to its x | the plate's text |
+| Annotation with `onSelect` | the plate is a button and lifts one level when pointed at | button semantics, named "v2 launch, Mar 4, 2026" |
+
+**Labels stay clear, of each other and of the data.** The container draws every reference and annotation itself, so it can lay their words out together with the marks. Plates sit in rows 26px apart at the top of the plot, and the data starts below the last row, so a plate never covers a mark. A reference's label takes the first spot that covers no line, area or bar and no other word: the right end above its line, then below, then the left end, then along the line. On a plot too small for any of those, it takes the spot that covers least. Across a horizontal chart, references stand upright and their labels stack in a row above the bars. All labels are on a halo of the plot's colour.
+
+**Values.** A reference's own values count toward the y axis, so a target above every value is still on the plot. `y="mean"` and `y="median"` are read from the settled records of `series` (default: the first shown), and the label adds the value at the data's own precision: "Average 162.5 ms".
+
+**Motion.** References are drawn in the plot's coordinates, so they glide with a rescale and the marks ([Motion](../../visual/Motion.md), "Charts"), and a mean or median glides to its new value when the data changes. Under reduced motion they change in place.
+
+**Without colour.** Under forced colours lines, labels, icons and leaders are `CanvasText`, bands are hatched in `GrayText` on `Canvas`, and plates get a 1px `CanvasText` border.
+
+**Accessibility.** References and annotations are read after the chart's summary, written or generated, and on the keyboard path's summary node: "References: Normal range, 99.5% to 100%; Target 99.9% at 99.9%. 1 annotation: DNS outage, Mar 14, 2026." Plates that only label are hidden from assistive technology, since the summary lists them. Plates with `onSelect` are buttons in the tab order after the plot.
+
+**Props.** `ChartReference`: `y` (a value, `[low, high]`, `'mean'` or `'median'`), `label`, `tone` (`'caution'` or `'critical'`), `series`. `ChartAnnotation`: `x` (as the data's x values are written), `label`, `onSelect`.
+
+- Do say what a reference is in its label ("Target 99.9%"), not only its value.
+- Do use `tone` only when crossing the line means good or bad.
+- Do keep annotations to a few words; the plate is a label, not a note.
+- Don't dash a reference line; a dash means "projected".
+- Don't use a reference band for data. A range in the data is an uncertainty band (`LineChart`'s `band`).
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ChartReference` as first used in its preview:
+
+```tsx
+import { ChartReference } from 'altitude-design';
+
+<ChartReference y={[0.995, 1]} label="Normal range" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cr`, `row` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { BarChart, Button, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartAnnotation, ChartContainer, ChartReference, LineChart } from 'altitude-design';
+
+const uptime = Array.from({ length: 30 }, (_, i) => ({ day: `2026-03-${String(i + 1).padStart(2, '0')}`, uptime: [0.9995, 0.9991, 0.9998, 0.9962, 0.9971, 0.9993, 0.9997, 0.9999, 0.9994, 0.9988, 0.9996, 0.9999, 0.9997, 0.9921, 0.9984, 0.9995, 0.9998, 0.9996, 0.9999, 0.9997, 0.9993, 0.9996, 0.9998, 0.9999, 0.9995, 0.9997, 0.9999, 0.9998, 0.9996, 0.9999][i] }));
+const pct = new Intl.NumberFormat('en', { style: 'percent', maximumFractionDigits: 2 });
+const usd = new Intl.NumberFormat('en', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
+const weekA = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'].map((day, i) => ({ day, cost: [412, 455, 498, 430, 610, 220, 190][i] }));
+const weekB = weekA.map((d, i) => ({ ...d, cost: [520, 590, 640, 575, 780, 300, 260][i] }));
+const teams = [['Search', 92], ['Checkout', 81], ['Accounts', 74], ['Messaging', 66], ['Billing', 58]].map(([team, score]) => ({ team, score }));
+const deploys = Array.from({ length: 21 }, (_, i) => ({ day: `2026-04-${String(i + 1).padStart(2, '0')}`, latency: 180 + Math.round(30 * Math.sin(i / 3)) + (i > 9 ? -40 : 0) + (i === 14 ? 60 : 0) }));
+function Chart({ id, title, sub, children, ...props }) {
+  return (
+    <Card>
+      <CardHeader><CardTitle id={id}>{title}</CardTitle><CardDescription>{sub}</CardDescription></CardHeader>
+      <CardContent><ChartContainer aria-labelledby={id} aspect={1.9} {...props}>{children}</ChartContainer></CardContent>
+    </Card>
+  );
+}
+export default function App() {
+  const [later, setLater] = React.useState(false);
+  const [picked, setPicked] = React.useState(null);
+  return (
+    <div className="cr" data-tells-ignore="LA4 a gallery of references in each chart, to compare">
+      <Chart id="r1" title="Uptime" sub="March, against the SLO" config={{ uptime: { label: 'Uptime', format: pct.format } }}>
+        <LineChart data={uptime} x="day">
+          <ChartReference y={[0.995, 1]} label="Normal range" />
+          <ChartReference y={0.999} label="Target 99.9%" />
+          <ChartReference y={0.99} label="Limit 99%" tone="critical" />
+          <ChartAnnotation x="2026-03-14" label="DNS outage" />
+        </LineChart>
+      </Chart>
+      <Card>
+        <CardHeader><CardTitle id="r2">Cloud spend</CardTitle><CardDescription>Against the daily budget; the median moves with the week</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="r2" aspect={2.2} config={{ cost: { label: 'Cost', format: usd.format } }}>
+            <BarChart data={later ? weekB : weekA} x="day">
+              <ChartReference y={700} label="Budget $700" tone="caution" />
+              <ChartReference y="median" label="Median" />
+            </BarChart>
+          </ChartContainer>
+          <div className="row" style={{ marginTop: 12 }}><Button size="sm" onClick={() => setLater((v) => !v)}>{later ? 'Last week' : 'This week'}</Button></div>
+        </CardContent>
+      </Card>
+      <Chart id="r3" title="Accessibility score" sub="By team, against the bar of 75" config={{ score: { label: 'Score' } }}>
+        <BarChart data={teams} x="team" layout="horizontal"><ChartReference y={75} label="Bar 75" /></BarChart>
+      </Chart>
+      <Chart id="r4" title="p95 latency" sub={picked ? `Picked: ${picked}` : 'Events stack into rows where they would overlap'} config={{ latency: { label: 'p95', format: (v) => `${v} ms` } }}>
+        <LineChart data={deploys} x="day">
+          <ChartReference y="mean" label="Average" />
+          <ChartAnnotation x="2026-04-10" label="Cache rollout" onSelect={() => setPicked('Cache rollout')} />
+          <ChartAnnotation x="2026-04-11" label="v2 launch" onSelect={() => setPicked('v2 launch')} />
+          <ChartAnnotation x="2026-04-15" label="Incident 412" />
+        </LineChart>
+      </Chart>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/ChartTooltip/README.md

@@ -0,0 +1,101 @@
+# ChartTooltip
+
+Reading exact values off a chart. Point at a date on a line chart, or at a bar, and a hairline marks that x while a readout lists every series' value there, so you never have to land on a 2px line to get a number. It's on for every chart; `ChartTooltip` only changes what it shows.
+
+**Why it floats.** The readout is live: it exists while you're reading, so it's a level-3 floating surface like `Tooltip` (`surface-floating`, `elev-3`, `radius-lg`). The crosshair and the ringed points are marks on the plot, on the ground: a 1px `line-control` rule snapped to the nearest x, and each line's point there ringed in the plot's own surface colour (an outline, not height). Bars don't change at all, because hovering a static bar does nothing.
+
+**How it moves.** It rises 4px the first time, as its shadow grows from `elev-1` to `elev-3` over `dur-travel-3`, then doesn't rise again while you move. It steps from one x to the next with no easing: it follows the data, not each pixel of the pointer, so it never reads as a control drifting (E10). It opens on whichever side of the point has room, so it never covers it, and leaves in 70% of its entry time. Coming back within 400ms shows it at once, warm, shared with `Tooltip`. On touch, press and hold shows it, dragging scrubs along x, and lifting your finger leaves it until you tap elsewhere. Under reduced motion it fades with no travel.
+
+**Without height.** Under forced colours it has a 2px `CanvasText` border and its keys take each series' dash. With `contrast="more"` it stands on the hard ink slab every level-3 surface gets.
+
+**Accessibility.** The readout is `aria-hidden` decoration over data that's reachable elsewhere: the chart's summary, the keyboard path through the data, which opens the same readout on the focused record (#63), and the table view (#64). Its labels come from your data, so they're inserted as text, never as HTML.
+
+**Rows.** The heading is the x value (formatted by the container, or by `labelFormat`). Each row puts the value first (`ink`, weight 500, tabular figures) and the series name second (`ink-muted`), keyed by a short stroke of the series colour. Only series that are shown and have a value there are listed.
+
+**Props.** `ChartTooltip` takes `content`: a `ChartTooltipContent` with your options. `ChartTooltipContent` takes:
+
+- `indicator`: `'line'` (default), `'dot'` or `'dashed'`;
+- `labelFormat`, for the heading;
+- `hideLabel` and `hideIndicator`.
+
+Turn the readout off with `tooltip={false}` on the chart type or the container. From your own marks or keyboard code, `useChart().active` is the record being read and `setActive(index)` opens the readout on one.
+
+**Pinning a reading.** `pinnable` on a `LineChart`, `BarChart` or `AreaChart` lets people keep a number: with the readout open, a click on the plot (or P on the keyboard path, or a quick tap while the touch readout is open) sets the reading down. The live readout lands on the record as a `Badge` plate at the top of the plot, from level 3 to the ground over `dur-travel-3` on `ease-settle`, then takes the afterglow once. It has a pin icon, so it isn't read as a `ChartAnnotation`, a 1px `line-control` leader to its x, and a ghost remove button named "Remove pin, Mar 9, 2026". With two pins, a strip under the x axis says the difference ("+24% over 28 days", or per series), and pinning the second says it aloud ("Apr 6, 2026 is 52% higher than Mar 2, 2026."). `pinnable` allows two; a number allows that many, and a new pin replaces the oldest. Escape on the chart removes the last pin before it clears a selection. Where a click selects or drills, it keeps doing that and only P pins. `pins` and `onPinsChange` control them, to keep them in the URL. The readout's action line says how to pin ("Click to pin", "P to pin", "Tap to pin").
+
+**You provide:** nothing, for the default. To change it, a `ChartTooltip` inside the chart type or the container.
+
+```tsx
+<ChartContainer config={config}>
+  <LineChart data={months} x="month">
+    <ChartTooltip content={<ChartTooltipContent indicator="dot" labelFormat={(m) => monthLong(m)} />} />
+  </LineChart>
+</ChartContainer>
+```
+
+- Do keep it on: it's how people get exact numbers without hunting for a line.
+- Do format the heading the way people say the x ("Week of Mon, April 6"), not as stored.
+- Don't put anything in it that can't be reached another way: it's a convenience over the summary, the keyboard path and the table.
+- Don't add buttons or links to it; it doesn't take the pointer, and it moves away as soon as the pointer does.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ChartTooltip` as first used in its preview:
+
+```tsx
+import { ChartTooltip, ChartTooltipContent } from 'altitude-design';
+
+<ChartTooltip content={<ChartTooltipContent indicator="dot" labelFormat={(w) => 'Week of ' + long.format(new Date(w + 'T00:00:00Z'))} />} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`ct` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { BarChart, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, ChartTooltip, ChartTooltipContent, LineChart, useChart } from 'altitude-design';
+
+// The readout is on for every chart; point at one (or press and hold on touch). Here it's opened with setActive,
+// the same call the keyboard path uses, so the preview shows it without a pointer.
+const weeks = ['2026-03-02', '2026-03-09', '2026-03-16', '2026-03-23', '2026-03-30', '2026-04-06', '2026-04-13'].map((week, i) => ({ week, opened: [31, 38, 35, 44, 41, 47, 52][i], closed: [28, 30, 36, 39, 43, 45, 49][i] }));
+const long = new Intl.DateTimeFormat('en', { weekday: 'short', day: 'numeric', month: 'long', timeZone: 'UTC' });
+function Open({ at }) {
+  const { setActive } = useChart();
+  React.useEffect(() => { setActive(at); }, []);
+  return null;
+}
+export default function App() {
+  const [pins, setPins] = React.useState(['2026-03-09', '2026-04-06']);
+  return (
+    <div className="ct" data-tells-ignore="LA4 a gallery of the readout in each chart, to compare">
+      <Card>
+        <CardHeader><CardTitle id="t1">Issues opened and closed</CardTitle><CardDescription>The default readout, open on 23 Mar</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="t1" aspect={1.8} config={{ opened: { label: 'Opened' }, closed: { label: 'Closed' } }}>
+            <LineChart data={weeks} x="week" /><Open at={3} />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="t2">Same data, your own content</CardTitle><CardDescription>indicator="dot" and a long date</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="t2" aspect={1.8} config={{ opened: { label: 'Opened' }, closed: { label: 'Closed' } }}>
+            <BarChart data={weeks} x="week">
+              <ChartTooltip content={<ChartTooltipContent indicator="dot" labelFormat={(w) => 'Week of ' + long.format(new Date(w + 'T00:00:00Z'))} />} />
+            </BarChart>
+            <Open at={5} />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="t3">Pinned readings</CardTitle><CardDescription>pinnable: click (or P) sets a reading down; two compare</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="t3" aspect={1.8} config={{ opened: { label: 'Opened' } }}>
+            <LineChart data={weeks} x="week" pinnable pins={pins} onPinsChange={setPins} />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/Checkbox/README.md

@@ -0,0 +1,46 @@
+# Checkbox
+
+Toggles one independent option. A checkbox is built like the Switch and the RadioGroup, so the three read as one family.
+
+- **Off:** an empty 22px trench (`surface-trench`, `trench` shadow, `line-control` rim), like the uncovered part of a switch track or an unchosen radio.
+- **On:** the accent pours in from the centre (on `ease-settle`, as the switch fill follows its thumb), and since the fill covers the rim too, fill and outline are one shape. A **raised white check** is set on it: `on-accent` with a small drop shadow, the checkbox's equivalent of the switch thumb. It draws once the fill has landed. `indeterminate` sets a dash instead.
+- **Hover** is feedforward: an empty box darkens its rim and shows a faint ghost of the check it would get; a checked box lifts its mark half a pixel. **Pressing** deepens the trench and squeezes the mark. **Disabled** matches a disabled switch: a flat track and a grey mark.
+
+**You provide:** `label`, optional `description`, and `checked`/`onCheckedChange` (or `defaultChecked`). It's a real `<input type="checkbox">`, so it works in forms with `name` and `value`.
+
+- Use a Switch when the change takes effect immediately; a Checkbox is for choices submitted together.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Checkbox` as first used in its preview:
+
+```tsx
+import { Checkbox } from 'altitude-design';
+
+<Checkbox label="Select all" checked={a && b} indeterminate={a !== b} onCheckedChange={(c) => { setA(c); setB(c); }} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `family`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Checkbox, Switch } from 'altitude-design';
+
+export default function App() {
+  const [a, setA] = React.useState(true);
+  const [b, setB] = React.useState(false);
+  return (
+    <div className="col">
+      <Checkbox label="Select all" checked={a && b} indeterminate={a !== b} onCheckedChange={(c) => { setA(c); setB(c); }} />
+      <div className="col" style={{ paddingLeft: 34 }}>
+        <Checkbox label="Weekly digest" description="A summary every Monday morning." checked={a} onCheckedChange={setA} />
+        <Checkbox label="Product updates" checked={b} onCheckedChange={setB} />
+      </div>
+      <Checkbox label="Disabled" disabled defaultChecked />
+      <div className="family"><span className="cap">Same build as</span><Switch defaultChecked aria-label="Switch" /><Switch aria-label="Switch off" /></div>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/Checklist/README.md

@@ -0,0 +1,137 @@
+# Checklist
+
+A list you write into, one line per item: to-dos, acceptance criteria, a packing list, a runbook's steps. Enter makes the next item, Backspace on an empty item removes it, Tab nests it, and each item has a checkbox. It's the keyboard-first counterpart to a list of structured records: here an item is its text, and the list is edited the way people write, with the outliner conventions of Workflowy, Logseq, Things, Notion and GitHub task lists.
+
+```tsx
+<Checklist<Task>
+  aria-label="Launch tasks"
+  items={tasks}                       // { id, text, done, children? }
+  getKey={(t) => t.id}
+  getText={(t) => t.text}
+  isDone={(t) => t.done}
+  getChildren={(t) => t.children}
+  nested
+  onChange={(op) => { setTasks((list) => apply(list, op)); return api.applyChecklistOp(op); }}
+  onUndo={(op) => setTasks((list) => revert(list, op))}
+/>
+```
+
+Each action reaches `onChange` as one op (`add`, `edit`, `toggle`, `remove`, `move`, `indent`, `outdent`), so persistence can be granular and collaborators' edits merge per item. Apply the op to `items` synchronously (the line you're writing in must not wait on the network), then return `{ ok: true }`, nothing, or `{ ok: false, error }`, synchronously or as a promise. A failure marks the item and offers Retry on the line; the text stays. New items get ids from `createId` (default a random UUID), so you can insert them at once.
+
+## No Save button, on purpose
+
+`InlineEdit` and `EditRegion` have an explicit Save, and blur does nothing. A checklist where every line needs Save isn't a checklist, so here **the line is the editor and it commits when you leave it**: Enter, ↑/↓, Tab, Escape, a click elsewhere. Scoped to this component, it's an explicit act on a single field, and a refused change keeps the text in place with Retry, so nothing is lost silently.
+
+## Elevation
+
+- **Items** are the record, flush on the ground. The line is a plain text input with a focus ring, not a raised editor.
+- **The last line** (“Add an item”) is an opening: a well while it's focused or holds text, dashed in forced colours.
+- **The checkbox** is `Checkbox`: an empty trench, then the accent pours in with a raised mark.
+- **Done** is pressed into the record: the text goes `ink-muted` with a strike drawn left to right, and the item stays in place (or, with `sortDone`, goes after the open ones).
+- **A new item** opens as a well under the line (`ease-sink`). **Pending** writes hover at level 2 after `dur-grace`; a **failed** one drops to a trench with a critical rim and Retry.
+- **Removed**: the line glides shut where it was (`dur-travel-2`, `ease-glide`) while the caret is already on the line above. There's no receipt and no hold: removal only happens from the keyboard, on an empty line or by merging a line's text into the one above, so nothing was lost. Undo is Ctrl+Z (⌘Z on Apple platforms) through `onUndo`, and the polite announcement says so: “Empty item removed. Undo with Ctrl+Z.” Nothing is added after the list. Under reduced motion the line closes at once.
+
+Without height: nested `ul`s carry the structure; each checkbox is named by its item; done items say “done”; the list's description lists the keys; a polite status announces indents, moves, removals and errors. `contrast="more"`: the open well gets a solid inner top edge.
+
+## Keyboard (while writing a line)
+
+| Key | |
+|---|---|
+| Enter | split at the caret: the text after it becomes the next item (at the end: a new empty item) |
+| Backspace at the start | on an empty item: remove it and go to the end of the line above. Otherwise merge into the line above, caret at the join |
+| Tab / Shift+Tab | indent under the item above / outdent (only with `nested`) |
+| Escape | leave the line and focus the item; Tab then moves on, so the list never traps focus |
+| ↑ / ↓ | the line above / below, keeping the caret's position |
+| Alt+↑ / Alt+↓ | move the item among its siblings |
+| Ctrl/Cmd+Enter | check or uncheck it |
+| Ctrl/Cmd+Z | undo the last add, remove, move or indent, through `onUndo` |
+
+Nothing acts during IME composition. Pasting several lines adds one item per line; GitHub task-list markers (`- [ ]`, `- [x]`) and, with `nested`, two-space indentation are read.
+
+## Props
+
+| Prop | |
+|---|---|
+| `items`, `getKey`, `getText`, `isDone`, `getChildren` | the nested data |
+| `nested`, `sortDone` | allow Tab nesting (default false); show done items last (default false) |
+| `onChange`, `onUndo`, `createId` | the ops, their reversal, and ids for new items |
+| `placeholder`, `disabled`, `aria-label`, `aria-labelledby` | |
+
+## You provide
+
+The items, applying and persisting each op, and reversing ops for Undo.
+
+## Do and don't
+
+- **Do** use it when items are just text. When each item is a record with several fields, use a list of records with its own editor.
+- **Don't** use it for long-form text; a line is one line.
+
+## Demo and verification
+
+The `Checklist` section of `build/previews.txt` shows nested launch tasks (a fictional service refuses “TBD”) and a flat packing list with `sortDone`. `node checks/checklist.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers Enter, split and merge at the caret, Backspace on an empty line, Tab and Shift+Tab, Escape then Tab, ↑/↓, Alt+↑, Ctrl+Enter, IME Enter, a refused edit with Retry, remove and Ctrl+Z, the add line, task-list paste, `sortDone`, and 320/960px layouts in both schemes under reduced motion, forced colours and `contrast="more"`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Checklist` as first used in its preview:
+
+```tsx
+import { Checklist } from 'altitude-design';
+
+<Checklist aria-labelledby="cl-launch" nested {...props} {...launch} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cl-demo` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Checklist } from 'altitude-design';
+
+// A tiny store that applies the Checklist's ops to nested items, and reverses them for Undo.
+const clStrip = (list, id) => { let found = null; const out = list.filter(x => { if (x.id === id) { found = x; return false; } return true; }).map(x => { if (found || !x.children) return x; const [kids, hit] = clStrip(x.children, id); if (hit) found = hit; return hit ? { ...x, children: kids } : x; }); return [out, found]; };
+const clInsert = (list, parentId, index, node) => parentId === null ? [...list.slice(0, index), node, ...list.slice(index)]
+  : list.map(x => x.id === parentId ? { ...x, children: [...(x.children || []).slice(0, index), node, ...(x.children || []).slice(index)] } : x.children ? { ...x, children: clInsert(x.children, parentId, index, node) } : x);
+const clUpdate = (list, id, patch) => list.map(x => x.id === id ? { ...x, ...patch } : x.children ? { ...x, children: clUpdate(x.children, id, patch) } : x);
+const clApply = (list, op) => {
+  if (op.type === 'add') return clInsert(list, op.parentId, op.index, { id: op.id, text: op.text, done: op.done });
+  if (op.type === 'edit') return clUpdate(list, op.id, { text: op.text });
+  if (op.type === 'toggle') return clUpdate(list, op.id, { done: op.done });
+  const [rest, node] = clStrip(list, op.id);
+  if (op.type === 'remove') return rest;
+  return clInsert(rest, op.parentId, op.index, node);
+};
+function useChecklist(seed, refuse) {
+  const [items, setItems] = React.useState(seed);
+  const removedNodes = React.useRef(new Map());
+  const onChange = op => {
+    if (refuse && refuse(op)) return { ok: false, error: refuse(op) };
+    if (op.type === 'remove') removedNodes.current.set(op.id, clStrip(items, op.id)[1]);
+    setItems(list => clApply(list, op));
+  };
+  const onUndo = op => setItems(list => {
+    if (op.type === 'add') return clStrip(list, op.id)[0];
+    if (op.type === 'remove') return clInsert(list, op.parentId, op.index, removedNodes.current.get(op.id));
+    const [rest, node] = clStrip(list, op.id); return clInsert(rest, op.from.parentId, op.from.index, node);
+  });
+  return { items, onChange, onUndo };
+}
+const CL_LAUNCH = [
+  { id: 'venue', text: 'Book the venue', done: true },
+  { id: 'invites', text: 'Send invitations', done: false, children: [
+    { id: 'list', text: 'Confirm the guest list', done: true }, { id: 'design', text: 'Design the card', done: false } ] },
+  { id: 'catering', text: 'Choose catering', done: false },
+];
+const CL_PACK = [{ id: 'p1', text: 'Passport', done: false }, { id: 'p2', text: 'Charger', done: true }, { id: 'p3', text: 'Rain jacket', done: false }];
+export default function App() {
+  const launch = useChecklist(CL_LAUNCH, op => op.type === 'edit' && /tbd/i.test(op.text) ? 'Write the task, not “TBD”.' : undefined);
+  const pack = useChecklist(CL_PACK);
+  const props = { getKey: t => t.id, getText: t => t.text, isDone: t => t.done, getChildren: t => t.children };
+  return <div className="cl-demo">
+    <section><h3 id="cl-launch">Launch tasks</h3><p>Nested: Tab and Shift+Tab indent and outdent. Backspace on an empty line removes it; Ctrl+Z (⌘Z) brings it back. Writing “TBD” is refused.</p>
+      <Checklist aria-labelledby="cl-launch" nested {...props} {...launch} /></section>
+    <section><h3 id="cl-pack">Packing</h3><p>Flat, done items last.</p>
+      <Checklist aria-labelledby="cl-pack" sortDone {...props} {...pack} placeholder="Add something to pack" /></section>
+  </div>;
+}
+```
+<!-- /example -->

package/dist/guidance/components/CodeBlock/README.md

@@ -0,0 +1,72 @@
+# CodeBlock
+
+Code to read and copy: install commands, API examples in several languages, webhook payloads, config, code an agent wrote.
+
+**Elevation.** Code shown to read and copy is the record, so it lies flush on the ground: a 1px `line` rim, mono type and no shadow. It isn't a `Card`, because code isn't a live surface. The header carries its name, a segmented `Tabs` switch between forms of the same thing (npm, pnpm; curl, Node, Python), and a ghost `CopyButton` ("Copy code"). Highlighted lines are `accent-soft` bands with an `accent-ink` edge behind the text. Line numbers sit in an `ink-faint` gutter. **Code still arriving** (`streaming`, from an agent) isn't the record yet: it has a dashed `line-control` rule down its left, says "Writing…", is `aria-busy`, and can't be copied until it's done.
+
+**Syntax colours are yours.** Altitude ships no highlighter. Pass `syntax={(code, language) => …}` (Shiki, Prism, your own) and it renders whatever you return. The default token classes (`tok-comment`, `tok-keyword`, `tok-string`, and Prism's and highlight.js's equivalents) use `ink-muted`, `accent-ink` and `ink`, never the `data-*` palette. Colours carry nothing on their own.
+
+**Overflow.** Code taller than `maxHeight` (default 360) or wider than its box scrolls. Only then does the scroll area become a focusable, named region (`tabIndex=0`, `role="region"`), so keyboard users can scroll it with the arrows.
+
+**Accessibility.** A `<figure>` named by its title, holding `<pre><code>`. Line numbers are `aria-hidden`. Highlighted lines are said in words before the code ("Lines 3 and 7 are highlighted."). The form switch is `Tabs`, with `aria-selected`. Under forced colours the rim is `CanvasText` and highlighted lines are `Mark`. Under `contrast="more"` the rim is `line-control`. Switching forms cross-fades the code over `dur-travel-1` and nothing travels.
+
+**Props:** `code` and `language` for one block, or `tabs` (`{ label, code, language? }[]`); `title`; `highlight` (line numbers from 1); `syntax`; `lineNumbers`; `streaming`; `maxHeight`; `copyable` (default true).
+
+**You provide:** the code, a title (a filename, or what it does), and a highlighter if you want colour.
+
+```tsx
+<CodeBlock title="Install" tabs={[
+  { label: 'npm', language: 'sh', code: 'npm install altitude-design' },
+  { label: 'pnpm', language: 'sh', code: 'pnpm add altitude-design' },
+]} />
+<CodeBlock title="invoice.paid" language="json" code={payload} highlight={[3]} lineNumbers />
+```
+
+- Do give every block a title, so it's named and so people know what to paste where.
+- Do use tabs for the same thing in several forms, not for different things.
+- Don't raise a code block into a card or give it a shadow.
+- Don't colour code with the chart palette.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`CodeBlock` as first used in its preview:
+
+```tsx
+import { CodeBlock } from 'altitude-design';
+
+<CodeBlock title="Install" tabs={[{ label: 'npm', language: 'sh', code: 'npm install altitude-design' }, { label: 'pnpm', language: 'sh', code: 'pnpm add altitude-design' }, { label: 'yarn', language: 'sh', code: 'yarn add altitude-design' }]} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cbk` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { CodeBlock } from 'altitude-design';
+
+const payload = `{
+  "id": "evt_1Q8xZ2",
+  "type": "invoice.paid",
+  "created": 1793304000,
+  "data": {
+    "invoice": "INV-0042",
+    "amount": 4900,
+    "currency": "eur"
+  }
+}`;
+// A stand-in highlighter, to show the syntax prop: comments in ink-muted, keywords in accent-ink.
+const tiny = (code) => code.split(/(\/\/.*$|\b(?:const|await|import|from)\b)/m).map((part, i) => part.startsWith('//') ? <span key={i} className="tok-comment">{part}</span> : /^(const|await|import|from)$/.test(part) ? <span key={i} className="tok-keyword">{part}</span> : part);
+export default function App() {
+  const [streamed, setStreamed] = React.useState('');
+  const full = "import { Altitude } from 'altitude-design';\n// Verify the signature before trusting the event\nconst event = await verify(request, secret);";
+  React.useEffect(() => { let i = 0; const t = setInterval(() => { i = Math.min(full.length, i + 3); setStreamed(full.slice(0, i)); if (i >= full.length) clearInterval(t); }, 60); return () => clearInterval(t); }, []);
+  return (
+    <div className="cbk">
+      <CodeBlock title="Install" tabs={[{ label: 'npm', language: 'sh', code: 'npm install altitude-design' }, { label: 'pnpm', language: 'sh', code: 'pnpm add altitude-design' }, { label: 'yarn', language: 'sh', code: 'yarn add altitude-design' }]} />
+      <CodeBlock title="invoice.paid" language="json" code={payload} highlight={[3, 7]} lineNumbers maxHeight={220} />
+      <CodeBlock title="webhook.ts" language="ts" code={streamed} syntax={tiny} streaming={streamed.length < full.length} />
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/ColorPicker/README.md

@@ -0,0 +1,69 @@
+# ColorPicker and ColorSwatchPicker
+
+A brand colour for a white-label portal, a label or tag colour, a calendar colour. `AltitudeProvider accent` already takes any colour and derives a scheme from it. This is the settings control that chooses one.
+
+**Elevation: choices are switches.** Swatches are built like `RadioGroup`. Each swatch is a trench (with a `line-control` rim) that its colour pours into. **The chosen one carries the raised white mark**, one mark that travels between swatches on `ease-glide`, as the radio thumb does. Pointing at another swatch shows a ghost of the mark where it would land (feedforward).
+
+**Any colour.** With `allowCustom`:
+- **The hex field** is an `Input` with a chip of the colour. It fills only when it holds a whole colour; a partial one ("0f8") is still an opening when you leave it.
+- **"Custom…"** opens a `Popover` (level 3) with a saturation/brightness area and a hue strip. Both are wells, and their handles are raised.
+
+**Contrast.** `accent` is the product's one hue, and text sits on it, so `checkContrast` says in words, for white text and for dark text, whether each reaches 4.5:1 on the colour ("White text fails: 4.3:1", "Dark text passes: 4.8:1"), as `Badge` plates. Some text nearly always passes, so it says which.
+
+**Accessibility.** Swatches are a [radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/): one tab stop, and arrows move and choose. **Every swatch has a name** ("Teal"), so colour is never the only way to tell them apart, and the chosen colour's name and hex are announced. The area is a [slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/) for saturation and brightness: Left and Right change saturation, Up and Down brightness, and Shift moves 10%. Its value text is "Saturation 80%, brightness 54%". The hue strip is a slider from 0 to 360°. Under forced colours swatches keep their real colour (`forced-color-adjust: none`) with a 1px `CanvasText` border, or 2px for the chosen one. Under `contrast="more"` the chosen swatch gets a hard ring. Under reduced motion the mark appears in place.
+
+**Props.**
+- `ColorPicker`: `label`, `value`, `defaultValue`, `onValueChange` (a lower-case `#rrggbb`), `swatches` (`{ value, name }[]`), `allowCustom`, `checkContrast`.
+- `ColorSwatchPicker` (the swatches alone): `swatches`, `value`, `defaultValue`, `onValueChange`, `aria-label`.
+
+**You provide:** a named palette (six to eight swatches), and whether any colour is allowed.
+
+```tsx
+<ColorPicker label="Brand colour" value={brand} onValueChange={setBrand}
+  swatches={[{ value: '#0f8a6b', name: 'Teal' }, { value: '#2f5fd0', name: 'Blue' }]}
+  allowCustom checkContrast />
+```
+
+- Do name every swatch.
+- Do turn on `checkContrast` wherever the colour will carry text (an accent, a button).
+- Don't offer a free colour where a palette will do; custom colours make labels hard to tell apart.
+- Don't use the `data-*` chart palette as label colours; it means series.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ColorPicker` as first used in its preview:
+
+```tsx
+import { ColorPicker } from 'altitude-design';
+
+<ColorPicker label="Brand colour" value={color} onValueChange={setColor} swatches={brand} allowCustom checkContrast />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cpk`, `col`, `demo`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AltitudeProvider, Button, ColorPicker } from 'altitude-design';
+
+const brand = [
+  { value: '#0f8a6b', name: 'Teal' }, { value: '#2f5fd0', name: 'Blue' }, { value: '#7d3c6f', name: 'Plum' },
+  { value: '#c23a6b', name: 'Rose' }, { value: '#c8571f', name: 'Ember' }, { value: '#d9a521', name: 'Ochre' },
+];
+const labels = [{ value: '#66738a', name: 'Slate' }, { value: '#2f8f4e', name: 'Green' }, { value: '#c9372c', name: 'Red' }, { value: '#16869e', name: 'Cyan' }];
+export default function App() {
+  const [color, setColor] = React.useState('#0f8a6b');
+  const [tag, setTag] = React.useState('#2f8f4e');
+  return (
+    <div className="cpk">
+      <ColorPicker label="Brand colour" value={color} onValueChange={setColor} swatches={brand} allowCustom checkContrast />
+      <div className="col">
+        <ColorPicker label="Label colour" value={tag} onValueChange={setTag} swatches={labels} />
+        <div className="demo"><span className="cap">Preview:</span><AltitudeProvider accent={color}><Button variant="primary">Upgrade plan</Button></AltitudeProvider></div>
+        <p className="cap">The check says, for white text and for dark text, whether it reaches 4.5:1 on the colour. Arrow keys move the mark between swatches; Custom… opens a full picker.</p>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/Combobox/README.md

@@ -0,0 +1,51 @@
+# Combobox
+
+An editable Select: type to narrow a long list, then choose. What you type is a query, not yet a value.
+
+**Elevation.** The field is the same opening as `Select` and `Input`. The difference is what counts as filled: typing doesn't fill a Combobox, choosing does. So while you type, the field keeps its back wall showing under your text (lit and rimmed in accent, because it has focus); only when an option is chosen does its floor rise flush. A form shows which comboboxes still hold a mere query. Invalid drops it to trench depth.
+
+**The list** rises from the field's edge at level 3 with one gliding highlight, as in Select, and narrows as you type: options are ranked by the CommandPalette's matching (exact, then prefix, word start, substring, letters in order), the best match is first and highlighted, and the letters that matched are drawn in `accent-ink`. The chosen option wears the Checkbox family's tick. A new value settles in with a brief afterglow.
+
+**Keyboard and screen readers.** The WAI-ARIA combobox pattern with a listbox popup: the text field has `role="combobox"`, `aria-expanded`, `aria-autocomplete="list"` and `aria-activedescendant`, so focus stays in the field. Typing opens and filters; ↓ and ↑ move (↓ also opens it, Alt+↓ without moving); Enter chooses; Escape closes and puts back the previous value. Home and End stay with the text. Leaving the field, by Tab or by clicking away, commits what's typed: an exact name chooses that option, an empty field clears the value, anything else goes back to the value it had. The chevron opens the list for pointer users.
+
+**On a phone.** The list stays under the field you're typing in by default (`presentation="auto"` or `"anchored"`), so the on-screen keyboard hides neither. `presentation="sheet"` opens it at the bottom edge instead.
+
+**You provide:** `items` (`{ value, label, textValue?, description?, disabled? }`), `value`/`onValueChange` or `defaultValue`, a `placeholder` that invites typing ("Search people"), optionally `filter` (return 0 or false to hide, higher to rank first), `empty` (default "No matches") and `name` for forms. Wrap it in `Field`.
+
+- Do use it when the list is long enough that scrolling is slower than typing (people, countries, repositories).
+- Don't use it for free text that may not be in the list; it only accepts listed values.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Combobox` as first used in its preview:
+
+```tsx
+import { Combobox } from 'altitude-design';
+
+<Combobox items={people} value={who} onValueChange={setWho} placeholder="Search people" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `grid` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Combobox, Field } from 'altitude-design';
+
+const people = ["Ada Obi", "Eli Ward", "Ivy Chen", "Jon Reyes", "Kai Ito", "Lena Park", "Mara Quist", "Noa Levi", "Rui Costa", "Sam Okafor", "Theo Marsh"].map((n) => ({ value: n.toLowerCase().replace(" ", "-"), label: n }));
+const countries = ["Brazil", "Canada", "Germany", "Japan", "Peru", "Portugal", "Singapore", "Spain"].map((c) => ({ value: c.toLowerCase(), label: c }));
+export default function App() {
+  const [who, setWho] = React.useState("");
+  return <div className="col">
+  <div className="grid">
+    <Field label="Assignee" hint={who ? "Assigned." : "Start typing a name."}>
+      <Combobox items={people} value={who} onValueChange={setWho} placeholder="Search people" />
+    </Field>
+    <Field label="Country">
+      <Combobox items={countries} defaultValue="portugal" defaultOpen={true} />
+    </Field>
+  </div>
+</div>;
+}
+```
+<!-- /example -->