altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,58 @@
+# Button
+
+Triggers an action. A button is a slab standing on the page: its height is drawn as a visible wall under the face, and that height is its importance.
+
+| Variant | Height | Use |
+|---|---|---|
+| `primary` | level 2, `wall-2` (4px), `accent` | The one thing this view is for. At most one per view. |
+| `secondary` | level 1, `wall-1` (2px), `surface-raised` | Everything else. The default. |
+| `ghost` | level 0, flush, no wall | Low-emphasis actions in toolbars, a dialog's cancel, table rows. On hover it rises out of the page with a 2px wall. |
+| `danger` | level 2, `wall-2`, `critical` | Irreversible actions, usually confirmed in a Dialog or a HoldButton. |
+
+The wall is the face colour darkened, so it reads in every scheme and with any custom accent. A button stays exactly where it is until the pointer is on it: it doesn't react to an approaching pointer or follow it across its face, because a control that moves on its own reads as something going wrong. Hover raises the face 1px while the wall grows to keep its foot on the ground. Pressing pushes the face all the way down: the wall disappears, the sheen flattens, and on release it settles back up on `ease-settle`. `loading` holds it down with a spinner and ignores clicks. `disabled` has no height at all: flush, on `surface-well`, in `ink-faint`. In high-contrast mode the wall becomes solid ink. The keyboard focus ring wraps the whole slab, face and wall, 4px out, in `accent-ink`.
+
+**You provide:** a label (verb first, sentence case: "Publish changes"), `variant`, `size` (`sm` 30px, `md` 36px, `lg` 44px), optional `leading`/`trailing` icons at 16px. Icon-only buttons take `square` and an `aria-label`.
+
+- Don't put two primary buttons in one view. Promote one, demote the other to secondary.
+- Leave room below a row of buttons: the wall extends up to 5px under the face.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Button` as first used in its preview:
+
+```tsx
+import { Button } from 'altitude-design';
+
+<Button variant="primary">Publish changes</Button>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Icons } from 'altitude-design';
+
+export default function App() {
+  const [busy, setBusy] = React.useState(false);
+  return (
+    <div className="col">
+      <div className="row">
+        <Button variant="primary">Publish changes</Button>
+        <Button>Preview</Button>
+        <Button variant="ghost">Cancel</Button>
+        <Button variant="danger">Delete project</Button>
+      </div>
+      <div className="row">
+        <Button variant="primary" size="sm">Small</Button>
+        <Button variant="primary" size="lg">Large</Button>
+        <Button square aria-label="Close"><Icons.X /></Button>
+        <Button variant="primary" loading={busy} onClick={() => { setBusy(true); setTimeout(() => setBusy(false), 1600); }}>Save</Button>
+        <Button disabled>Disabled</Button>
+      </div>
+      <p className="cap">Primary rests at level 2, secondary at 1, ghost at 0. Hover climbs one level; pressing returns to the ground. Click Save: a loading button stays pressed.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,52 @@
+# Card
+
+A raised surface that groups related content; it moves only if the whole card is one action.
+
+A static Card sits at level 1 and never reacts to the pointer. An `interactive` Card stays put until the pointer is on it, lifts to level 2 and 2px on hover or focus and presses to ground on click; with `onClick` it becomes keyboard-reachable (`role="button"`, Enter and Space).
+
+**Loading.** Pass your data as it is. A `CardTitle` whose text is undefined imprints one line of its own type; a `CardDescription`, or text passed straight to `CardContent`, imprints too, but only while the card's required parts (title, avatar, badge) are still waiting, so a missing field never leaves an imprint behind. A Card and its `CardContent` also hold a Suspense boundary for anything of yours that suspends inside them (`skeleton={{ lines }}`, default 3; `false` passes it to your own boundary). See `Await`.
+
+**You provide:** content through `CardHeader` (with `CardTitle` and `CardDescription`), `CardContent` and `CardFooter` (right-aligned actions), or your own children. Padding is `space-5`.
+
+Cards take the same depth signals as `Surface`: `settle`, `status`, `heldBy` and `relevance`.
+
+- Do make the entire card the target when it navigates somewhere (a project tile).
+- Don't make a card interactive *and* put buttons inside it: nested targets break the press metaphor. Keep the card static and let its buttons lift.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Card` as first used in its preview:
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from 'altitude-design';
+
+<Card>
+  <CardHeader><CardTitle>Usage this month</CardTitle><CardDescription>Static: a grouping surface, it never lifts.</CardDescription></CardHeader>
+  <CardContent>18,240 requests · 62% of plan</CardContent>
+</Card>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`grid` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from 'altitude-design';
+
+export default function App() {
+  const [n, setN] = React.useState(0);
+  return (
+    <div className="grid">
+      <Card>
+        <CardHeader><CardTitle>Usage this month</CardTitle><CardDescription>Static: a grouping surface, it never lifts.</CardDescription></CardHeader>
+        <CardContent>18,240 requests · 62% of plan</CardContent>
+      </Card>
+      <Card interactive onClick={() => setN(n + 1)}>
+        <CardHeader><CardTitle>Open project</CardTitle><CardDescription>Interactive: the whole card is the target, so it lifts and presses.</CardDescription></CardHeader>
+        <CardContent>{n ? `Opened ${n}×` : 'Click or press Enter'}</CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,98 @@
+# ChartBrush
+
+Picks a time window on an overview of the whole series, under the plot: look at a year and read a fortnight without losing where you are (overview + detail; Cockburn, Karlson & Bederson, 2009). Put it inside a `LineChart`, `AreaChart` or `BarChart` over time.
+
+**Why it's sunk, and why the window lifts.** Most chart libraries draw a brush as a grey rectangle with handles, which nobody recognises as something to drag. Altitude already has a build for "a window you slide along a range": the range `Slider`. The overview is an opening, a 40px trench (`surface-trench`, `trench`) with the series lying in it as a flat 1.5px line, because it's a track you slide along. Like a `Sparkline`'s line it spans its own low to high: it's there for the shape, and an area that didn't stand on zero would misstate every value. The window is a raised lens over it: level 1, a 2px `accent` rim and a clear face, level 2 on hover and 3 while held. Its two grips are the slider's thumbs. Outside the window the overview recedes to 35%.
+
+**What it does.**
+
+- **Drag the lens** to pan. The window keeps its length and stops at the ends.
+- **Drag a grip** to resize. A grip pushed against the other stops a record short; the window always holds at least two records.
+- **Press outside the lens** to centre the window there, then keep dragging to pan from it.
+- A held grip shows its date in a bubble below the overview, clear of the plot's axis; panning shows both. Near an end, the bubble aligns to that end so it never leaves the frame.
+- The frame says the window in words under the overview: "1 Mar – 30 Apr 2026".
+- The chart shows only the window, and its axis spans exactly the window. The plot cross-fades to it, because the x values under the marks changed ([Motion](../../visual/Motion.md), "Charts", rule 5).
+
+**Accessibility.** The brush is a group named "Overview, 1 Jan – 31 Dec 2026" (or your `aria-label`). It follows the APG multi-thumb slider: "Window start" and "Window end" are each a Tab stop and a `role="slider"` with the date as `aria-valuetext`, bounded by the other grip; arrows step a record, Page Up/Down a tenth, and Home/End go to the grip's own bounds. The lens is a focusable group named "Window, 1 Mar – 30 Apr 2026": arrows pan both ends by a record, Page Up/Down by a tenth, Home and End to the start and the end.
+
+**Without height.** Under forced colours the trench is dashed, the lens is a 1px `Highlight` border (2px while held), the grips are outlined in `CanvasText` and the line is `CanvasText`. With `contrast="more"` the lens rim is `ink`.
+
+**Props.** `series`: the series the overview draws (default the chart's first shown series); `aria-label`; `className`. The window itself is the chart type's:
+
+- `window={{ start, end }}` with `onWindowChange`, controlled. `start` and `end` are the records' own x values, so a `DateRange` from a `DateRangePicker` fits as it is, and the picker and the brush share one state. `null` leaves an end open.
+- Neither, and the brush keeps its own window, starting over every record.
+
+**You provide:** a `ChartBrush` inside the chart type, and the window state if anything else needs it.
+
+```tsx
+const [range, setRange] = React.useState({ start: '2026-03-01', end: '2026-04-30' });
+
+<DateRangePicker value={range} onValueChange={setRange} />
+<ChartContainer config={config}>
+  <AreaChart data={year} x="day" window={range} onWindowChange={setRange}>
+    <ChartBrush />
+  </AreaChart>
+</ChartContainer>
+```
+
+- Do use a brush when the whole range matters for context and a part of it for reading: a year and a fortnight.
+- Do give the window a typed twin (a `DateRangePicker`) when exact dates matter; dragging is for finding, typing for stating.
+- Don't use a brush for a few dozen records: the chart can show them all.
+- Don't put a brush on a chart of categories; it windows records in their order, which only means something over time.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ChartBrush` as first used in its preview:
+
+```tsx
+import { ChartBrush } from 'altitude-design';
+
+<ChartBrush />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cb`, `col`, `pick` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AreaChart, BarChart, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartBrush, ChartContainer, DateRangePicker, Field } from 'altitude-design';
+
+// A year of daily active users, with a dip in August and a launch in late September.
+const cbYear = Array.from({ length: 365 }, (_, i) => {
+  const day = new Date(Date.UTC(2026, 0, 1 + i)).toISOString().slice(0, 10);
+  const trend = 4200 + i * 9, week = [0.82, 1, 1.04, 1.05, 1.03, 0.97, 0.78][i % 7];
+  const summer = i > 212 && i < 243 ? 0.8 : 1, launch = i > 265 ? 1.18 : 1;
+  return { day, active: Math.round((trend + 260 * Math.sin(i / 9)) * week * summer * launch) };
+});
+const cbWeeks = Array.from({ length: 52 }, (_, i) => ({ week: new Date(Date.UTC(2026, 0, 5 + i * 7)).toISOString().slice(0, 10), signups: Math.round(310 + i * 6 + 90 * Math.sin(i / 3) + (i > 37 ? 160 : 0)) }));
+const cbK = new Intl.NumberFormat('en', { notation: 'compact', maximumFractionDigits: 1 });
+export default function App() {
+  const [range, setRange] = React.useState({ start: '2026-03-01', end: '2026-04-30' });
+  return (
+    <div className="cb">
+      <Card>
+        <CardHeader><CardTitle id="cb1">Daily active users</CardTitle><CardDescription>Drag the lens to pan, a grip to resize, or press the overview to centre it there. The picker is the same state, typed.</CardDescription></CardHeader>
+        <CardContent className="col">
+          <Field label="Window" className="pick"><DateRangePicker value={range} onValueChange={setRange} min="2026-01-01" max="2026-12-31" locale="en-GB" /></Field>
+          <ChartContainer aria-labelledby="cb1" config={{ active: { label: 'Active users', format: cbK.format } }} aspect={3.4} locale="en-GB">
+            <AreaChart data={cbYear} x="day" window={range} onWindowChange={setRange}>
+              <ChartBrush />
+            </AreaChart>
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="cb2">Weekly sign-ups</CardTitle><CardDescription>Bars over time with a brush that keeps its own window</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="cb2" config={{ signups: { label: 'Sign-ups' } }} aspect={4} locale="en-GB">
+            <BarChart data={cbWeeks} x="week">
+              <ChartBrush />
+            </BarChart>
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,229 @@
+# ChartContainer
+
+The frame every chart shares. It sizes the plot, turns data into positions (the scales), draws the axes, the gridlines and the ground line, gives each series a label, a format and a colour slot, and names and summarises the chart. Every chart type renders inside it, and so can marks you draw yourself.
+
+**Why it's flush.** A chart is the record drawn as a shape (see [Charts](../../visual/Charts.md)), so everything in the frame lies on whatever it sits on, the page or a `Card`'s `surface-raised`, at no level and with no shadow. Amounts are length and position on a flat plot standing on the ground line, never height: the zero baseline is a 1px `ink-muted` rule, the same ground line `Stepper` and the `Drilldown` staircase stand on. Gridlines are `line` hairlines, horizontal only. When zero isn't on the axis (a line chart may leave it off), the plot's foot is an ordinary gridline, not the ground line. Tick labels are caption text in `ink-muted` with tabular figures. Marks wear `data-*` colours and nothing else. On resize the frame lays out again without animating.
+
+**Without height, and without colour.** Nothing here relies on height to begin with. Colour is never alone either: each slot carries a redundant encoding, fixed like its colour.
+
+| Slot | Line dash | Marker | Fill hatch |
+|---|---|---|---|
+| `data-1` | solid | circle | none (solid) |
+| `data-2` | 6 3 | square | 45° lines |
+| `data-3` | 2 2 | triangle | 135° lines |
+| `data-4` | 8 3 2 3 | diamond | dots |
+| `data-5` | 12 4 | ring | horizontal lines |
+| `data-6` | 4 2 1 2 | cross | crosshatch |
+| `data-other` | 1 3 | circle | dots |
+
+Patterns are on under forced colours and in print, and anywhere with `patterns` (for readers who want them, or a chart whose slots fall in the colour-blind warning band). Under forced colours:
+
+- marks are `CanvasText`, hatches are `CanvasText` on `Canvas`, and fills get a `CanvasText` edge;
+- tick labels and the ground line are `CanvasText`, and gridlines are `GrayText`;
+- `directLabels` turns on, as it does in print, so chart types label series at their marks.
+
+With `contrast="more"`, lines are 3px, adjacent marks are 3px apart, fills get a 1px `ink` edge, gridlines take `line-control` and the ground line `ink`.
+
+**Accessibility.** It's a `figure`, named by its `title` or by `aria-labelledby` (point it at the `CardTitle`), and described by its description and a summary. Pass `summary` with what the chart shows ("Revenue rose 44% while costs held flat."): it's shown under the plot. Without it a summary is generated for screen readers: the chart's kind, its series, the x range, and each series' lowest and highest values with where they fall. The plot is a `group` with `aria-roledescription="chart"`, and its SVG is hidden from assistive technology.
+
+**Say one thing first.** `takeaway` is the one thing the chart says, set as its heading in `text-heading` ink ("Cedar deployed nearly three times as often as Delta"). The `title` then sits above it as a caption-sized `ink-muted` label, so the chart is still named: the figure's accessible name stays the title, and its description is the takeaway, then the summary. When the takeaway's words change with the data they cross-fade over `dur-travel-2`, without the afterglow. Write it yourself, from the data shown; nothing generates one, because a slanted or trivial headline is worse than none. In a `Card`, name the chart with the figure's `title` rather than a `CardTitle`, so the takeaway isn't a second heading under the card's. See [Charts](../../visual/Charts.md), rule 9.
+
+```tsx
+<ChartContainer config={config} title="Deploys by team" takeaway="Cedar deployed nearly three times as often as Delta"
+  summary="Cedar deployed most, 51 times; Delta least, 19.">
+  <BarChart data={deploys} x="team" sort="desc" />
+</ChartContainer>
+```
+
+**Axis text.** Tick labels are captions: 13px, weight 400, `ink-muted`, tabular figures. Weight 500 is for labels on controls, so axis text is lighter, and the frame's words rank below the marks, the ground line and the references. (This changed from 500 12.5px in #193, with no API change.) `yLabels="inline"` sets each y label just above its gridline at the plot's left, on a halo of the plot's colour, so the plot runs the card's full width: 56px more in a 440px card, about a fifth of the plot at phone width. The top label carries the unit ("250 ms"), the rest only the number. A label that would sit on a line, an area or a bar is left out, and its gridline stays. The ground line goes unlabelled, because it's zero. It's for vertical cartesian charts; the default stays `'gutter'`.
+
+**The keyboard path.** The plot is one Tab stop: a layer of focusable nodes over the SVG, one level at a time, with a roving tabindex. After Olli and Data Navigator, it goes from the summary to the series to the data:
+
+| Key | On the summary | On a series | On a point |
+|---|---|---|---|
+| ←/→ | — | previous/next series | previous/next x |
+| ↑/↓ | — | previous/next series | same x, previous/next series |
+| Home/End | — | first/last series | first/last x |
+| Page Up/Down | — | — | ±10% of the x range |
+| Enter | into the series | into its points | — |
+| Escape | — | back to the summary | back to its series |
+
+A chart with one series skips the series level. In a stacked `AreaChart`, whose bands are drawn from the bottom up, ↑ moves to the band above and ↓ to the one below. The nodes are named:
+
+- **the summary:** the written `summary`, or the generated one, then "Press Enter to explore the series";
+- **a series:** "Revenue, 12 points, $61K to $104K, rising. 1 of 2.";
+- **a point:** "Mar 1, 2026, Revenue, $83K. Down 2% from Feb 1, 2026. 9 of 12." Stacks add "Total …"; a stacked `AreaChart` says the band's share instead ("34% of 3.2K").
+
+A focused point gets a 2px `accent-ink` ring on its mark (`Highlight` under forced colours) and opens the readout, so keyboard and pointer get the same feedback. A focused series draws the others receded. Chart types say where each of their marks sits (`chartPoint`); hand-drawn marks get a ring at `(xOf, y(value))`. The table view is #64.
+
+**Scales.** All in-house, no dependency:
+
+- `band` for categories, in data order, with `bandPadding` (default 0.2) between them;
+- `time` for ISO `'YYYY-MM-DD'` strings (read as UTC, as `DatePicker` writes them), timestamps or `Date`s, with ticks at whole days, weeks, months, quarters or years, as many as fit;
+- `linear` for other numbers;
+- y is always linear, with about five 1–2–5 ticks, made nice, and includes zero unless you pass `zero={false}`. Bars always need zero.
+
+x is inferred from the first value of `x`; set `xScale` to override it. Numbers and dates are formatted with `Intl`, in the reader's locale unless you pass `locale`.
+
+**Colour.** Series take slots in config order: the first is `data-1`, the seventh and later are `data-other`. Set `color: 'data-3'` to pin one. The order is fixed for the chart's life, so hiding or filtering a series never repaints the others. The figure also sets `--color-<key>` for each series, for your own CSS.
+
+**Focus.** A chart type's `focus` says what the chart is about: `focus={['eu']}` keeps those series' colours and draws the rest in `data-context`, one flat neutral, with their end labels and legend keys in `ink-muted`; on bars and dots, `focus={(d) => d.team === 'Cedar'}` does the same for records. It's said in words: "Highlighted: EU." leads the generated summary (and follows a written one), focused legend keys say "highlighted", and the readout and the keyboard path list focused series first. Changing it cross-fades the colours over `dur-travel-1`, at once under reduced motion. It's the author's statement of importance, not a reader's control; the reader's is `relevance`, which recedes misses to 35% without repainting, so the two never read alike. Your own marks get it from `encode(key, d).context` and its colour. Pair it with a `takeaway`: when the words and the colour pick out the same thing, that's what people remember (E102, E105).
+
+**Motion.** When the data changes, the frame moves its marks by the one engine every chart shares ([Motion](../../visual/Motion.md), "Charts"). Values glide at one level on `ease-glide`, after the axis has rescaled if its domain changed, never at the same time. Re-sorted bands are carried, and records and series entering or leaving cross-fade. First render, a change of x under a line, more than 500 marks and reduced motion all cross-fade instead. Resizing never animates. The plot's `data-stage` says where a change is (`rescale`, `values` or `fade`).
+
+**Loading, refetch and nothing.** Pass what you have (`data={query.data}`) and the frame does the rest, Suspense-native like `DataTable`:
+
+| `data` | What shows |
+|---|---|
+| `undefined`, or a pending promise | an imprint after `dur-grace`: the title, description and legend in place, the plot pressed into the page in the chart's shape (`surface-well` bars, a band, or an area), no labels, `aria-busy` and "Loading" |
+| arrives | the marks fade in place. Unlike `Await`'s content they never rise out of the imprint, because a rising bar would leave the ground line and misstate its value |
+| `null` or `[]` | an `EmptyState` at widget size in the plot's own box, with no axes; set its words and action with `empty={{ title, description, action }}` (on the container or the chart type). All-zero data is real data, and is drawn |
+| a new promise while data shows, or `refreshing` | the old chart stays; after `dur-grace` its marks drop to half strength, with `aria-busy` and "Updating". Nothing is imprinted over what someone is reading |
+| rejected | your error boundary (put an `Alert` there), as with `Await` |
+
+A `RevealGroup` around a row of charts and stats lands them together.
+
+**The table view.** `views` adds a segmented Chart | Table control beside the title: the same record as a sortable `DataTable`, x first (headed by `xLabel`), a column per series in its own format, and a Total for stacks. It sits in the chart's own box and scrolls there, so switching doesn't move the page; the two views cross-fade over `dur-travel-2`, and the hidden one is inert. `views="table"` starts on the table; `view` and `onViewChange` control it. It's opt-in so that small widget charts don't each grow a control; give it to any chart people may want to read, copy or check.
+
+**Not yet the record.** `BarChart`, `LineChart` and `AreaChart` take `status={(d) => 'partial' | 'projected' | undefined}`. The ground is the record, and a projection or an unfinished period isn't yet, so it's drawn hatched or dashed, never raised, and said in words: "So far" or "Projected" in point names ("Oct 1, 2026, Revenue, $61K, so far."), after the readout's heading, in a Status column in the table, and at the end of the generated summary, whose trend and extremes are read from the settled records. A 1px `line-control` rule named "Today" marks where the record ends. For your own marks, `useChart()` gives `status(d)`, `statusRanges` (the stretches of x that are pending, for `ChartStatusClip`) and `encode(key).pending`, `pendingOpacity` and `pendingDash`.
+
+**Marks you can select or drill into.** Give a chart type `onSelect` (with `selected`), or `drill` inside a `Drilldown`, and its marks act. Hover is a promise, so only then do they respond to the pointer:
+
+- **Hover:** a pointer cursor, a 2px `ink` outline on the record's marks (appearing over `dur-travel-1`), and the readout ends with the action: "Select to filter", "Select to clear", "Select to open". A mark can't lift without misstating its value, so the outline, cursor and readout carry the cue, and height stays with the readout. Without `onSelect` or `drill`, marks don't respond at all; only the crosshair and readout do.
+- **Selected:** the selected record keeps its full colour and the others recede to 35%, in the same language as a filter. The frame says "Filtered to EU" with a "Clear" ghost button, and so does the summary. Choosing it again, Clear or Escape clears it.
+- **Drilling:** `drill={(d) => d.q}` returns the id of the current `Drilldown` node's child to open. The child is laid on top as a sheet with a step added to the breadcrumb staircase, `Drilldown`'s own choreography, and focus moves to the new chart's summary. A node with `content` and `children` shows its content and lets the chart open the children (`useDrilldown().open(id)`).
+- **Keyboard and touch:** on a point, Enter or Space selects or drills, and points carry `aria-pressed` (or `aria-haspopup` for a drill) and say what Enter does. A tap selects; press and hold still shows the readout. Under forced colours the outline is `Highlight`.
+
+**Filtering in place.** `BarChart`, `LineChart` and `AreaChart` take `relevance={(d) => 'match' | 'miss' | undefined}`, to pair with a `FilterBar`, a legend or a selection in another chart. Filtered-out data stays where it was, so nothing you'd just read is reshuffled:
+
+- **Misses recede** to 35% opacity, keeping their place and their colour slot; their value labels turn `ink-muted`. A line or an area recedes around each missing record (each owns its stretch of x, to the midpoints with its neighbours), so its shape never changes. The change cross-fades over `dur-travel-1`.
+- **The axis holds** by default. `rescale` fits it to the matches, and the rescale is staged like any other.
+- **It's said in words.** The frame shows "4 of 12 match" (`countLabel` rewrites it: "4 of 12 services match"), and so does the summary. A miss says "Not matching." in its point name and readout.
+- **Contrast only.** Elsewhere relevance raises matches, but marks can't rise, so in a chart it's spent as contrast alone. Under forced colours misses are `GrayText`.
+
+`useChart()` gives `relevance(d)`, `hasRelevance` and `relevanceRegions`; wrap your own marks in `ChartRelevance`. `BarList` takes the same `relevance`, and there rows rise and sink as `TableRow`s do.
+
+**Since your last visit.** `since={{ data: snapshot, label: 'since Tuesday 09:00' }}` answers "what moved while I was away?", which the afterglow can't when the change came before the page did. Records are matched by the chart's id or by x; a new one counts as changed. A changed bar carries a 2px `ink` tick at its old value (the comparison's mark, as `compare` draws it), a changed line point a small hollow `ink-muted` ring. The frame says "3 changed since Tuesday 09:00" in a `Switch` that turns on a filter for the changed records, so the rest recede to 35% where they stand. On arrival, up to four changed marks take `live`'s afterglow; more, and the caption takes it instead. Point names ("Up 40% since Tuesday 09:00"), the readout, the table and the summary ("3 of 8 changed since Tuesday 09:00, most of all Webhooks, up 75%.") say what changed. Keeping what each person last saw, and when, is the application's job.
+
+**Live data.** `live` is for charts that update on their own (deploys, error rates, queue depth). People miss changes they weren't attending to, so, as elsewhere in Altitude, a change shows at once and leaves a fading trace:
+
+- **A changed mark glows.** A point or bar whose value is new or changed carries a 2px `ink` outline (an outline, not height), full for the first second and decaying over `dur-settle` on `ease-decay`, with its value beside it for that first second. Its point name says "Changed." until it fades. Afterglows share the page's attention budget (`riseDelay`), so no more than four begin in any 250ms.
+- **A whole refresh is one change.** If more than four marks change at once, none glows; the "Updated 12:04" caption under the plot gets a ground-level tint instead, as a table re-sort does.
+- **A window glides.** A chart type's `window` (`{ minutes: 15 }`) keeps the latest stretch of x. When it moves on, x glides one step on `ease-glide` over `dur-travel-2` and the marks ride with it, clipped to the plot. The motion is the passage of time. Under reduced motion it updates in place.
+- **It holds still while you read.** While the pointer or keyboard focus is in the plot, updates wait and the caption says "new data when you move away"; they land when you leave, so the readout never changes under you. `pausable` adds a "Pause updates" `Switch` (WCAG 2.2.2); `paused` and `onPausedChange` control it.
+- **It doesn't chatter.** Nothing is announced per tick. `announce={(data, previous) => …}` returns a sentence for what matters ("Error rate crossed 2%"), said politely.
+
+**References and annotations.** [`ChartReference`](../ChartReference/README.md) draws a target, a limit, a normal range or the mean as a flush 1px line or a flat band, and `ChartAnnotation` marks an event on x with a `Badge` plate and a leader. Place them inside the chart type or the container. The frame draws them, so their labels are laid out together and kept clear of each other, and they're read after the summary.
+
+**Charts that draw their own plot.** A [`Heatmap`](../Heatmap/README.md) has no value axis: its cells lie on two categories it names itself. The frame leaves out the gridlines, the ground line, the axes and the crosshair, makes the plot as tall as the cells need, puts the readout beside the cell, and goes from the summary straight to the cells, which the chart type moves between by row and column. A [`ScatterChart`](../ScatterChart/README.md) keeps the axes but both are measures: the frame finds the nearest dot in two dimensions, leaves out the crosshair, puts the readout beside the dot, and lets the chart type name each axis in room above and below the plot. Its series are its groups rather than the config's keys; the config names the two measures. Records are known by their own id rather than by x, for motion, the table, selection and live changes. Records without one cross-fade rather than glide.
+
+**Readout and legend.** Every chart has a readout ([`ChartTooltip`](../ChartTooltip/README.md)); add a [`ChartLegend`](../ChartLegend/README.md) to name series, or to let people hide and show them. Hidden series keep their slots and leave the scales. A [`ChartBrush`](../ChartBrush/README.md) inside a chart over time adds an overview under the plot to pick a window on.
+
+**Your own marks.** `useChart()` gives you the following, and children are drawn inside the plot, in its coordinates, under the ground line's rule:
+
+- `width` and `height`: the plot's size;
+- the `x` and `y` scales, and `xOf(datum)` (a band's centre, or a time or value);
+- `ground`: the y of the ground line;
+- `data`: the records as they're shown right now (gliding values, lingering leavers);
+- `alpha(datum, seriesKey)`: how present a mark is while it enters or leaves, to multiply into its opacity;
+- `series`, with their colours and formats, and `format`;
+- `encode(key)`: the series' `fill`, `stroke`, `dash`, `marker` and `edge` for the current mode. `ChartMarker` draws the marker shape;
+- `patterns`, `directLabels`, `strokeWidth` and `gap`;
+- `status(datum)`, `hasStatus` and `statusRanges`, for data that isn't yet the record.
+
+Draw with `encode()` rather than `series.color`, and forced colours, print and `contrast="more"` are handled for you.
+
+Draw from these and your marks move like every other chart's.
+
+```tsx
+function Target({ value }) {
+  const { y, width } = useChart();
+  return <line x1={0} x2={width} y1={y(value)} y2={y(value)} stroke="var(--ink-muted)" strokeDasharray="4 3" />;
+}
+```
+
+**You provide:** `config` (each data key: `label`, optionally `format` and `color`), the `data` and its `x` key (or a chart type inside that takes them), and a size: `aspect` (width ÷ height, default 2) or `height` in px. Usually a `summary`, and `aria-labelledby` or `title`; a `takeaway` when the chart makes a point.
+
+- Do give every chart a summary that says what it shows, not what it is.
+- Do put a chart on a dashboard in a `Card`: the card is raised because it's something you work with, not because its data is.
+- Do keep one y axis. Two measures of different scale are two charts.
+- Don't give marks a shadow, a wall, a sheen, a gradient or a lift.
+- Don't colour text with a series colour; labels and ticks wear `ink` and `ink-muted`.
+- Don't draw more than about 2,000 marks: SVG gets slow. Aggregate, or use a canvas library with Altitude's theme (#77).
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ChartContainer` as first used in its preview:
+
+```tsx
+import { ChartContainer } from 'altitude-design';
+
+<ChartContainer aria-labelledby="rc" data={months} x="month" aspect={1.7} summary="Revenue rose 44% while costs held flat."
+  config={{ revenue: { label: 'Revenue', format: usd.format }, costs: { label: 'Costs', format: usd.format } }}>
+  <Lines />
+</ChartContainer>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`charts` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, ChartMarker, useChart } from 'altitude-design';
+
+// Until the chart types land, these marks are drawn by hand with useChart(): the same scales the types will use.
+const usd = new Intl.NumberFormat('en', { style: 'currency', currency: 'USD', notation: 'compact' });
+const months = [
+  { month: '2026-01-01', revenue: 8200, costs: 5100 }, { month: '2026-02-01', revenue: 8900, costs: 5000 },
+  { month: '2026-03-01', revenue: 9400, costs: 5300 }, { month: '2026-04-01', revenue: 9100, costs: 5200 },
+  { month: '2026-05-01', revenue: 10600, costs: 5400 }, { month: '2026-06-01', revenue: 11800, costs: 5300 },
+];
+const regions = [
+  { region: 'North', q2: 42, q3: 51 }, { region: 'South', q2: 35, q3: 31 }, { region: 'East', q2: 28, q3: 37 }, { region: 'West', q2: 19, q3: 24 },
+];
+// encode() draws a series by its slot: colour, and a dash, marker or hatch whenever patterns are on (forced colours, print).
+function Lines() {
+  const { series, data, xOf, y, encode, patterns, strokeWidth } = useChart();
+  return series.map((s) => {
+    const e = encode(s.key);
+    return <g key={s.key}>
+      <polyline fill="none" stroke={e.stroke} strokeDasharray={e.dash} strokeWidth={strokeWidth} strokeLinejoin="round" strokeLinecap="round"
+        points={data.map((d) => `${xOf(d)},${y(d[s.key])}`).join(' ')} />
+      {patterns && data.map((d, i) => <ChartMarker key={i} shape={e.marker} x={xOf(d)} y={y(d[s.key])} color={e.stroke} />)}
+    </g>;
+  });
+}
+function Bars() {
+  const { series, data, x, y, xKey, ground, alpha, encode, gap } = useChart();
+  const w = (x.bandwidth - gap * (series.length - 1)) / series.length;
+  return data.map((d) => series.map((s, i) => {
+    const v = d[s.key], top = Math.min(y(v), ground), e = encode(s.key);
+    return <rect key={d[xKey] + s.key} x={x(d[xKey]) + i * (w + gap)} y={top} width={w} height={Math.abs(y(v) - ground)}
+      fill={e.fill} stroke={e.edge} strokeWidth={e.edge ? 1 : undefined} opacity={alpha(d, s.key)} />;
+  }));
+}
+export default function App() {
+  return (
+    <div className="charts">
+      <Card>
+        <CardHeader><CardTitle id="rc">Revenue and costs</CardTitle><CardDescription>Jan to Jun 2026</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="rc" data={months} x="month" aspect={1.7} summary="Revenue rose 44% while costs held flat."
+            config={{ revenue: { label: 'Revenue', format: usd.format }, costs: { label: 'Costs', format: usd.format } }}>
+            <Lines />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="dr">Deals closed by region</CardTitle><CardDescription>Q2 and Q3</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="dr" data={regions} x="region" aspect={1.7}
+            config={{ q2: { label: 'Q2' }, q3: { label: 'Q3' } }}>
+            <Bars />
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,78 @@
+# ChartLegend
+
+Names each series, and optionally lets people hide and show series. Every chart with two or more series needs one, unless its marks are labelled directly (a `LineChart` with up to four series names each line at its end). A single series doesn't need one: the title names it.
+
+**Why it's flat, or why it lifts.** A legend that only labels is settled: keys flush on the ground, each a swatch in its series colour (a block for bars, a short line for lines, the group's marker for a `ScatterChart`) and its name in `ink`. A legend you can toggle is a row of choices, and in most chart libraries those are invisible affordances: the key looks like a label and behaves like a button, which is the flat-UI failure Burmistrov et al. (2015) measured. So with `toggle` each key is built like a `Checkbox`. It's a ghost button that lifts one level when pointed at, because clicking it does something. It holds a trench (sunk, `surface-trench`) that the series colour pours into while the series is shown and drains out of when it's hidden. The fill is the series colour rather than `accent`, because the swatch *is* the key.
+
+**What toggling does.** The series fades out of (or into) the plot over `dur-travel-1`. If y has to rescale, that's staged first, as every change to a chart is ([Motion](../../visual/Motion.md), "Charts"). Hidden series keep their colour slots, so nothing else repaints. The last shown series can't be hidden; its key says "At least one series stays shown."
+
+**Without height.** Under forced colours, swatches take each series' pattern, hidden swatches are dashed, and a hovered key gets a 1px border. With `contrast="more"` the trench gets a solid inner top edge.
+
+**Accessibility.** A static legend is a list named "Series". A toggle legend is an APG toolbar named "Series" holding `aria-pressed` buttons, one per series, so a long legend is one Tab stop: ←/→ (or ↑/↓) move between keys, Home and End go to the ends, and Space or Enter toggles. Toggling is announced politely ("Costs hidden. 2 of 3 series shown.").
+
+**Props.** `ChartLegend` takes `content`: a `ChartLegendContent` with these options:
+
+- `toggle`: make the keys switches;
+- `hidden` and `onHiddenChange`, controlled; or `defaultHidden`, uncontrolled;
+- `label`: the toolbar's name, default "Series".
+
+**You provide:** a `ChartLegend` inside the chart type or the container.
+
+```tsx
+<ChartContainer config={config}>
+  <AreaChart data={usage} x="day" stack>
+    <ChartLegend content={<ChartLegendContent toggle />} />
+  </AreaChart>
+</ChartContainer>
+
+// controlled
+<ChartLegendContent toggle hidden={hidden} onHiddenChange={setHidden} />
+```
+
+- Do label lines directly when there are four or fewer, and keep the legend for toggling.
+- Do use `toggle` when people need to compare a few series out of many; otherwise a static legend is quieter.
+- Don't let colour be the only link between a key and its series: under forced colours the keys show each series' pattern.
+- Don't put the legend somewhere the chart's readout or summary can't be read alongside it.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ChartLegend` as first used in its preview:
+
+```tsx
+import { ChartLegend, ChartLegendContent } from 'altitude-design';
+
+<ChartLegend content={<ChartLegendContent />} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cl` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { BarChart, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, ChartLegend, ChartLegendContent, LineChart } from 'altitude-design';
+
+const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'].map((month, i) => ({ month, api: 20 + ((i * 7) % 11), web: 14 + ((i * 5) % 9), jobs: 6 + ((i * 3) % 7) }));
+const plans = ['2026-01-01', '2026-02-01', '2026-03-01', '2026-04-01', '2026-05-01', '2026-06-01'].map((month, i) => ({ month, free: 40 + i * 2, team: 34 + i * 3, business: 30 + i * 2.6, enterprise: 12 + i }));
+export default function App() {
+  return (
+    <div className="cl">
+      <Card>
+        <CardHeader><CardTitle id="g1">Requests, all services</CardTitle><CardDescription>A legend that only labels</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="g1" aspect={1.8} config={{ api: { label: 'API' }, web: { label: 'Web' }, jobs: { label: 'Jobs' } }}>
+            <BarChart data={months} x="month" stack><ChartLegend content={<ChartLegendContent />} /></BarChart>
+          </ChartContainer>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle id="g2">Seats by plan</CardTitle><CardDescription>toggle: each key is a switch; Enterprise starts hidden</CardDescription></CardHeader>
+        <CardContent>
+          <ChartContainer aria-labelledby="g2" aspect={1.8} config={{ free: { label: 'Free' }, team: { label: 'Team' }, business: { label: 'Business' }, enterprise: { label: 'Enterprise' } }}>
+            <LineChart data={plans} x="month"><ChartLegend content={<ChartLegendContent toggle defaultHidden={['enterprise']} />} /></LineChart>
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+<!-- /example -->