altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,128 @@
+# Await
+
+Components that bring their own loading state. Pass your data the way you already do: while it's `undefined` (`user?.name` while a query loads), the component shows its own imprint at its own size, and when the data arrives the content rises out of it. You don't write skeletons or loading flags. `Await` is the Suspense boundary inside each of them, exported so your components can do the same.
+
+```tsx
+const { data: user } = useQuery(userQuery(id));   // useSWR, a loader, your own state: anything that's undefined until it isn't
+
+<Card>
+  <CardHeader>
+    <Avatar name={user?.name} size={44} />
+    <CardTitle>{user?.name}</CardTitle>
+    <CardDescription>{user?.role}</CardDescription>
+  </CardHeader>
+  <CardContent>{user?.bio}</CardContent>
+</Card>
+<DataTable columns={columns} rows={deploys} getRowId={(d) => d.id} />
+```
+
+**Elevation: loading is an imprint.** Content still to come is the shape of what's coming, pressed into the page (`surface-well`, `well`), as `Skeleton` draws it. The difference is who draws it. A component holds its own `<Suspense>` boundary, and its fallback is drawn from the same props and tokens as the component itself: an `Avatar` of `size={44}` leaves a 44px disc; a `CardTitle` leaves one line as tall as the title's line-height; a `Badge` leaves a plate; a `DataTable` keeps its real header over rows of cell imprints. So the imprint is the size of the content, and nothing moves when it lands.
+
+**What counts as "not here yet".** `undefined` is on its way; `null` is nothing, and renders empty at once. Required content waits whenever it's undefined. Optional content (a card's description, text passed straight into `CardContent`) waits only while its card's required parts do, so a field that's simply missing from your data never leaves an imprint behind.
+
+| Content | Waits while | Imprint |
+|---|---|---|
+| `Avatar` `name` | undefined | a disc of its `size` |
+| `CardTitle` children | undefined | one line of the title's type; `skeleton={{ width }}` |
+| `Badge` children | undefined | a plate (`width`, default 64px; a `count` is round) |
+| `DataTable` `rows` | undefined | the real header over `skeleton.lines` rows of imprinted cells (default 5) |
+| `CardDescription` children | undefined and the card's required parts are waiting | two lines of the description's type; `skeleton={{ lines, width }}` |
+| `CardContent` children | undefined and the card's required parts are waiting, or anything of yours inside suspends | `lines` lines (default 3) |
+| `Card` | anything of yours inside suspends | a title line over `lines` lines (default 3) |
+
+Every one of them also takes a promise in place of the value (from a server component, say) and waits for it the same way.
+
+**If a request fails** your data stays undefined, so the imprint stays. Render your error state in place of the content, as you would anyway, or pass `null`. `skeleton={false}` on any component renders exactly what you pass, with no imprint.
+
+**Motion.** An imprint waits `dur-grace` (300ms) before it fades in, so loads quicker than that show nothing and land without moving: Skeleton's rule, "don't show imprints for loads under about 300ms", is now kept for you. When content lands after its imprint showed, it rises 8px out of it (`dur-travel-3`, `ease-rise`) while the imprint fills in behind it. Rises share the attention budget (`riseDelay`): if many land at once, no more than four begin together. Containers (`Card`, `CardContent`, `DataTable`) leave no imprint behind; their content just rises. Under reduced motion it fades in place.
+
+**Landing together.** A page full of boundaries fills in piece by piece as each one's data arrives. Wrap related parts in `RevealGroup` and each part that lands early stays an imprint until the slowest one in the group has landed; then they rise together (still four at a time). Group things that load from the same place; a group waits for its slowest member.
+
+**Without height.** Every imprint carries a visually hidden "Loading" and `aria-busy`, and is otherwise hidden from assistive technology; the content that replaces it is announced as normal content. Under forced colours imprints have a dashed `CanvasText` outline, like every sunk surface.
+
+**How it works.** An undefined value becomes a suspension: the component's outer part (which stays mounted and re-renders when your data arrives) holds a promise that resolves once the value turns up (`useArrival`), and its inner part reads it, so the component's own boundary shows the imprint, and the reveal is the same one a real promise gets. Reading is React 19's `use()` when it's there; on React 18 the same contract is kept by hand (the promise is thrown to the boundary and its result remembered), so both work. A component that has never waited takes the old path exactly: no boundary, no extra element. Once it has, the wrapper stays, as `display: contents`, so it adds nothing to layout.
+
+**Limits.** Your own markup can't tell: `<p>{user?.bio}</p>` inside a card renders an empty paragraph while it loads; pass the text straight to `CardContent` or `CardDescription` instead. An optional part whose data comes from a different, slower request than its card's required parts is treated as missing once they land, and appears when its data does, without an imprint.
+
+```tsx
+// Promises work too: from a server component, start the request and pass it along.
+const user = getUser(id);
+<Avatar name={user.then((u) => u.name)} size={44} />
+
+// Your own component, the same way:
+<Await inline shape="circle" imprint={<Skeleton shape="circle" width={24} />}><Flag code={country} /></Await>
+```
+
+**Breath (experimental).** `<AltitudeProvider loading="breath">` changes how imprints wait and how content lands; nothing changes without it. Instead of light sweeping over them, imprints breathe in depth: the floor deepens to trench depth and releases (the back wall in Nightfall), once every `dur-breath` (4.8s), on one page clock, with a slow swell down the view. Ten seconds in, the breath calms. When content lands:
+
+| Content | `settle` | Lands |
+|---|---|---|
+| On its own surface (a card from one request) | `"raised"` | rises 8px to level 2 and settles to level 1 over `dur-arrive` |
+| On the ground (text, a badge, a row) | `"flush"` (default) | its floor comes up just past the ground and fills in flush |
+| Into a view already showing (Load more, a boundary that suspends again) | `late` | an untinted plate under it, gone in `dur-plate` |
+
+A `Card`'s parts land together, and a `RevealGroup` takes one place in the attention budget (its parts 16ms apart). A card's optional parts still don't wait: if its description is `undefined` once its title has landed, it renders empty, so pass a promise for a detail that's still coming. Chart, stat and meter imprints hold still, and a chart's marks still fade in place. Under reduced motion the breath stops and nothing travels.
+
+```tsx
+<AltitudeProvider scheme="daylight" loading="breath">
+  <Await settle="raised" imprint={<Skeleton height={103} radius="var(--radius-lg)" />}><DeployCard deploy={deploy} /></Await>
+  {older.map((e) => <Await key={e.id} late imprint={<Skeleton height={26} />}><Event event={e.promise} /></Await>)}
+</AltitudeProvider>
+```
+
+**You provide:** your data as it is, `undefined` until it arrives. Hints where the default shape won't match (`skeleton={{ lines: 3 }}`). If you pass promises, make them stable across renders: started in a server component, a loader, a cache or state, never created inline in a client component's render. `skeleton={false}` on any of them to opt out.
+
+- Do pass `user?.name` and friends straight in, and let each part land when its data does.
+- Do wrap parts that read better arriving together (a profile header) in `RevealGroup`.
+- Don't wrap Suspense-native components in your own `Skeleton`s; they already imprint themselves.
+- Don't use it for errors: a rejected promise throws to your nearest error boundary, where an `Alert` belongs.
+- Don't use `null` for "still loading"; it means there's nothing, and renders empty.
+- `Skeleton` with `loaded` is still the way for layouts of your own.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+The full preview, as rendered in Storybook and checked in CI (`card`, `who`, `id`, `col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Avatar, Badge, Card, CardContent, CardDescription, CardHeader, CardTitle } from 'altitude-design';
+
+const USER = { name: 'Mara Quist', role: 'Platform engineer, Lisbon', bio: 'Merged “Faster cold starts” into main. Cold starts are down 38% across all regions.' };
+// Stands in for useQuery or useSWR: undefined until the data arrives.
+function useLoaded(value, ms) {
+  const [data, setData] = React.useState(undefined);
+  React.useEffect(() => { const t = setTimeout(() => setData(value), ms); return () => clearTimeout(t); }, []);
+  return data;
+}
+function Member() {
+  const user = useLoaded(USER, 1200);
+  const status = useLoaded('On call', 1800);
+  return (
+    <Card className="card">
+      <CardHeader>
+        <div className="who">
+          <Avatar name={user?.name} size={44} status="active" />
+          <div className="id">
+            <CardTitle>{user?.name}</CardTitle>
+            <CardDescription skeleton={{ lines: 1, width: '70%' }}>{user?.role}</CardDescription>
+          </div>
+          <Badge tone="positive">{status}</Badge>
+        </div>
+      </CardHeader>
+      <CardContent skeleton={{ lines: 2 }}>{user?.bio}</CardContent>
+    </Card>
+  );
+}
+export default function App() {
+  const [round, setRound] = React.useState(0);
+  React.useEffect(() => { const t = setTimeout(() => setRound((r) => r + 1), 4400); return () => clearTimeout(t); }, [round]);
+  return (
+    <div className="col">
+      <Member key={round} />
+      <p className="cap">No skeleton code: while user is undefined, each part imprints itself at its own size, and rises out of it when the data arrives.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,66 @@
+# Badge
+
+Labels status or metadata. A badge is an **indicator plate**: part of the record, so it's set flush into the page (a shallow stamp, darker at its top edge with a light lip below) and never lifts.
+
+- **Lamp.** Status carries an indicator lamp: a flat 7px dot in its tone's own colour (`positive`, `caution`, `critical` or `accent`, the same colour the tone uses for text), with no gloss, socket or glow. It's printed on the plate rather than set into it, so it never competes with the plate's height. It's on by default for `positive`, `caution` and `critical`; `lamp` on a neutral badge shows an unlit lamp, an empty `ink-muted` ring ("Draft"); `lamp={false}` hides it. With a lamp, the label stays in `ink` and the colour lives in the lamp. Without one, a toned plate says its tone in its lettering.
+- **Relight and re-stamp.** When `tone` changes the lamp relights: it starts as an empty ring and fills in over `dur-travel-3`. When the label changes, the plate is re-stamped (it comes down 3px onto the page and settles). Neither happens on first render.
+- **Pulse.** `lamp="pulse"` fades the dot to a third and back over `dur-hover`, for something in progress ("Deploying"). It holds still under reduced motion.
+
+| `variant` | Looks like | Use |
+|---|---|---|
+| `plate` (default) | a neutral plate stamped into the ground | Most status and metadata. |
+| `tinted` | the plate takes its tone's `-soft` colour, lettering in the tone | When status needs to be seen from across the page. (`soft` is the old name.) |
+| `outline` | a `line-control` hairline only | Versions, IDs, counts of things that don't need attention. |
+| `count` | a number on a floating pill (`elev-2`) | Unread or waiting items: the one badge that rises, because it wants you. It pops up when the number changes. Solid `accent` or `critical`; neutral is `surface-floating`. Position it yourself (for example absolutely, over a Button's corner). |
+
+**Loading.** While the label is undefined (your data hasn't arrived) or a promise, the badge is a plate-shaped imprint (see `Await`).
+
+**You provide:** a short label (one or two words, sentence case) or a number for `count`, `tone`, optionally `variant` and `lamp`.
+
+- Do pair status colour with the word: "Outage", never a lamp alone.
+- Don't make badges clickable; if it filters or navigates, it's a ghost Button.
+- Don't use `count` for totals that aren't asking for attention; use a plate or plain text.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Badge` as first used in its preview:
+
+```tsx
+import { Badge } from 'altitude-design';
+
+<Badge lamp>Draft</Badge>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row`, `anchor`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, Button } from 'altitude-design';
+
+export default function App() {
+  const [deploying, setDeploying] = React.useState(true);
+  const [n, setN] = React.useState(3);
+  React.useEffect(() => { const t = setInterval(() => { setDeploying((d) => !d); setN((x) => (x % 5) + 1); }, 2400); return () => clearInterval(t); }, []);
+  return (
+    <div className="col">
+      <div className="row">
+        <Badge lamp>Draft</Badge>
+        <Badge tone="accent">Beta</Badge>
+        <Badge tone="positive">Operational</Badge>
+        <Badge tone="caution">Degraded</Badge>
+        <Badge tone="critical">Outage</Badge>
+        <Badge tone={deploying ? 'accent' : 'positive'} lamp={deploying ? 'pulse' : true}>{deploying ? 'Deploying' : 'Live'}</Badge>
+      </div>
+      <div className="row">
+        <Badge tone="positive" variant="tinted">Operational</Badge>
+        <Badge tone="critical" variant="tinted">Outage</Badge>
+        <Badge variant="outline">v2.4.0</Badge>
+        <span className="anchor"><Button>Inbox</Button><Badge variant="count" tone="critical">{n}</Badge></span>
+      </div>
+      <p className="cap">Labels are stamped into the record; status wears a lamp that relights when it changes. A count is the one badge that floats, because it wants you.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,109 @@
+# BarChart
+
+Amounts compared across categories or periods: deploys per team, signups per month, cost per region. One series, several side by side (grouped), or stacked into a total. Length on a common baseline is the most accurately read encoding there is (Cleveland & McGill, 1984), so this is the workhorse chart. It renders inside a [`ChartContainer`](../ChartContainer/README.md).
+
+**Why it's flat.** Bars are the record drawn as lengths, so they stand on the ground line: flat `data-*` fills, square where they meet the ground and rounded (`radius-xs`) only at the data end. Neighbours and stacked segments are parted by a real 2px gap, never a shadow or an outline. A bar never lifts, on hover or anywhere else: a lifted bar leaves the ground line or casts a shadow below its top, and both misstate its value. A negative bar hangs below the ground line. That's position, not depth: it has no inner wall and doesn't read as an opening. One series wears `data-1` throughout; bars are never coloured by their value.
+
+**Without colour.** Under forced colours and in print, and with `patterns` on the container, each series gets its hatch (the first stays solid) and filled bars a `CanvasText` edge. With `contrast="more"` bars get a 1px `ink` edge and 3px gaps. Value labels are `ink` text, never a series colour.
+
+**Motion.** Values glide at one level, re-sorts are carried, a rescale comes first, and nothing grows from the ground line on first render; a bar grows only when its value really goes from zero to something ([Motion](../../visual/Motion.md), "Charts").
+
+**Accessibility.** The container names the chart and summarises it; without a written `summary`, the generated one names the series and each one's lowest and highest category. The keyboard path through the bars and the readout are #63 and #52, and the table view is #64.
+
+**Props:**
+
+- `data` and `x`: the records and the key of each one's category;
+- `sort`: `'desc'` or `'asc'` by total;
+- `stack`: `true` for parts of a total, `'expand'` for shares of 100%;
+- `layout="horizontal"`: categories down the side, for long names or many of them. Names longer than 40% of the width are cut with an ellipsis; the full name stays in the summary;
+- `labels`: `'max'` labels the largest bar (or stack), `'last'` the last category's. Never every bar;
+- `status`: which categories aren't yet the record (`'partial'` or `'projected'`), and `boundary`, the rule's word. See below;
+- `window` and `onWindowChange`: for bars over time (a bar per week), a stretch of the categories by date, `{ start, end }` or the last `{ points }`. A `ChartBrush` inside the chart picks it on an overview.
+
+**Selecting and drilling.** `selected` and `onSelect` make the marks a selection that cross-filters the rest of a dashboard, and `drill` opens a level down inside a `Drilldown`. Hover only promises what a click does. See [ChartContainer](../ChartContainer/README.md), "Marks you can select or drill into".
+
+**Filtering in place.** `relevance={(d) => 'match' | 'miss' | undefined}` recedes misses to 35% and keeps everything in place; `rescale` fits the axis to the matches. See [ChartContainer](../ChartContainer/README.md), "Filtering in place".
+
+**Not yet the record.** `status={(d) => d.month === thisMonth ? 'partial' : undefined}` keeps this month so far from reading as a drop. A partial bar is its series colour hatched at 45° on the plot's own colour, with no solid fill; a projected one also keeps a 1.5px outline in its colour. Neither is lifted: a pending write hovers, but a bar that hovers misstates its value, so it says "not yet" with pattern and a word instead. A 1px `line-control` rule marks where the record ends, named "Today" (`boundary="…"` renames it, `boundary={false}` drops it). The bar's value label, readout, keyboard name and table row say "So far" or "Projected". When the period completes and its status goes, the hatching cross-fades to solid over `dur-travel-3`: it's been pressed into the record. Under forced colours the pending bar takes a dotted `CanvasText` outline, the same cue as a pending write.
+
+The y axis always includes zero, whatever the container's `zero` says: a truncated bar axis isn't offered.
+
+**Focus.** `focus={['web']}` keeps those series' colours and draws the rest in `data-context`; on a one-series chart, `focus={(d) => d.team === 'Cedar' || d.team === 'Delta'}` picks out records instead, the categories the takeaway names. See [ChartContainer](../ChartContainer/README.md), "Focus".
+
+**Against the record before.** `compare={{ key: 'lastQuarter', label: 'Q2' }}` (a field on each record) or `compare={{ data: lastWeek, label: 'Last week' }}` (records matched by position, before any sort) draws the earlier value as a 2px `ink` tick across each bar, 4px past it on each side: Few's comparative measure. A value that fell leaves its tick past the bar's end, the drop visible as empty space. Grouped bars compare one `series` (default the first); a stack compares its total; shares (`stack="expand"`) don't compare. The readout, point names ("Up 11% from Q2"), the table ("Q2" and "vs Q2" columns) and the summary ("Against Q2: 3 rose, 1 fell.") say the difference, and earlier values join the axis.
+
+**You provide:** a `ChartContainer` with a `config` naming each series, the `data` and `x`, and usually a `summary`.
+
+```tsx
+<ChartContainer config={{ deploys: { label: 'Deploys' } }} summary="Cedar deployed most, 51 times.">
+  <BarChart data={byTeam} x="team" sort="desc" labels="max" />
+</ChartContainer>
+```
+
+- Do sort categories that have no order of their own, so the comparison reads at a glance.
+- Do keep grouped bars to four series or fewer; past that, stack them or use small multiples.
+- Do use `stack="expand"` only when the shares matter more than the totals, and say so in the title.
+- Don't label every bar: label the one the chart is about, and leave the rest to the readout and the table.
+- Don't colour bars by their value or give them a gradient; for polarity, a diverging ramp on a separate chart says it better.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`BarChart` as first used in its preview:
+
+```tsx
+import { BarChart } from 'altitude-design';
+
+<BarChart data={teams} x="team" sort="desc" labels="max" focus={(d) => d.team === 'Cedar' || d.team === 'Delta'} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`bc` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { BarChart, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer } from 'altitude-design';
+
+const teams = [{ team: 'Atlas', deploys: 42 }, { team: 'Birch', deploys: 35 }, { team: 'Cedar', deploys: 51 }, { team: 'Delta', deploys: 19 }, { team: 'Ember', deploys: 28 }];
+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 net = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'].map((month, i) => ({ month, change: [12, -8, 5, -15, 9, 18][i] }));
+const regions = [{ region: 'North America', seats: 1240, before: 1120 }, { region: 'Europe, Middle East and Africa', seats: 980, before: 1040 }, { region: 'Asia Pacific', seats: 610, before: 470 }, { region: 'Latin America', seats: 270, before: 240 }];
+const stack3 = { api: { label: 'API' }, web: { label: 'Web' }, jobs: { label: 'Jobs' } };
+function Chart({ id, title, sub, children, ...props }) {
+  // With a takeaway the figure names itself: the title becomes the label over the takeaway, the heading.
+  if (props.takeaway) return (
+    <Card>
+      <CardContent style={{ paddingTop: 'var(--space-5)' }}><ChartContainer title={title} description={sub} aspect={1.45} {...props}>{children}</ChartContainer></CardContent>
+    </Card>
+  );
+  return (
+    <Card>
+      <CardHeader><CardTitle id={id}>{title}</CardTitle><CardDescription>{sub}</CardDescription></CardHeader>
+      <CardContent><ChartContainer aria-labelledby={id} aspect={1.45} {...props}>{children}</ChartContainer></CardContent>
+    </Card>
+  );
+}
+export default function App() {
+  return (
+    <div className="bc">
+      <Chart id="b1" title="Deploys by team" takeaway="Cedar deployed nearly three times as often as Delta" sub='One series, sorted, labels="max"' config={{ deploys: { label: 'Deploys' } }} summary="Cedar deployed most, 51 times; Delta least, 19.">
+        <BarChart data={teams} x="team" sort="desc" labels="max" focus={(d) => d.team === 'Cedar' || d.team === 'Delta'} />
+      </Chart>
+      <Chart id="b2" title="Requests by service" sub="Grouped: three series side by side" config={stack3}>
+        <BarChart data={months.slice(3)} x="month" />
+      </Chart>
+      <Chart id="b3" title="Requests, all services" sub='Stacked, labels="last", focus={["web"]}' config={stack3}>
+        <BarChart data={months} x="month" stack labels="last" focus={['web']} />
+      </Chart>
+      <Chart id="b4" title="Share of requests" sub='stack="expand": parts of 100%' config={stack3}>
+        <BarChart data={months} x="month" stack="expand" />
+      </Chart>
+      <Chart id="b5" title="Net new customers" sub="Negative bars hang below the ground line" config={{ change: { label: 'Net change', format: (v) => (v > 0 ? '+' : '') + v } }}>
+        <BarChart data={net} x="month" />
+      </Chart>
+      <Chart id="b6" title="Seats by region" sub='layout="horizontal", against last quarter' config={{ seats: { label: 'Seats', format: (v) => v.toLocaleString('en') } }}>
+        <BarChart data={regions} x="region" layout="horizontal" compare={{ key: 'before', label: 'Q2' }} labels="max" />
+      </Chart>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,87 @@
+# BarList
+
+Top pages, top referrers, top customers by spend: a ranked list where each row is its own bar, the label is readable at any length, and the exact value sits at the end. It sits between a `Table` (exact, no shape) and a horizontal `BarChart` (shape, but long labels squeeze the plot).
+
+**Why it's flat.** Rows are the record, so they lie flush on the ground with `line` dividers, like a table's rows. Each row's bar is a flat tint of `data-1` behind its label, as long as the row's value against the largest (the top row's bar fills its row), and faint enough that `ink` holds 4.5:1 over it in every scheme. It has a `radius-xs` corner and no shadow, wall or gradient. A long label wraps; it's never cut. The value sits at the row's end in tabular figures, and with `share` its percentage of the total sits beyond the bar in `ink-muted`.
+
+**Hover is a promise.** A row that does something (`href` makes it a link, `onSelect` a button) lifts one level when pointed at, exactly as `Table`'s interactive rows do, and drops back when pressed; its bar stays flat on it. A row that does nothing never moves.
+
+**Other and Show all.** With `limit`, the rows past it fold into one "Other (14 pages)" row in `data-other`, and a ghost "Show all 21 pages" button lists them all (and "Show fewer" folds them back). `noun` names what the rows are.
+
+**Filter in place.** `relevance` raises matches one level and sinks misses into a well, as `TableRow relevance` does; nothing is removed, and misses say "not matching" to screen readers. Under the list it says how many match: "2 of 5 pages match", using `noun`.
+
+**Motion.** When values change, rows are carried to their new ranks (FLIP, `dur-travel-3`, `ease-glide`), all at once, because a re-rank is one change; bars glide to their new lengths. Under reduced motion both change in place. While `data` is undefined the list is imprinted rows, which land like `Await` content.
+
+**Accessibility.** Plain HTML: an `ol` (rank is meaningful) of links, buttons or plain items, each reading "1. /pricing, 4,210, 23%". The bar is hidden from assistive technology; the value is text. Under forced colours bars are a light `Highlight` tint with a 1px `Highlight` border, matches are outlined and misses dashed. Under `contrast="more"` bars get a 1px `ink` edge.
+
+**Props:** `data` (`{ name, value, key?, href? }[]`); `format`; `limit`; `share`; `sort` (`'desc'`, the default, or `false` to keep your order); `noun`; `onSelect`; `relevance`; `locale`; and any `ol` attribute (name it with `aria-labelledby` or `aria-label`).
+
+**You provide:** the rows, a name for the list, and a `format` with the unit when it isn't a plain count.
+
+```tsx
+<BarList aria-labelledby="pages-title" data={pages} format={(n) => n.toLocaleString()} limit={8} share noun="pages" />
+```
+
+- Do use it for a ranked top-N with long labels; use a `BarChart` to compare a few categories across series.
+- Do give rows an `href` when they open a report, so they're real links.
+- Do fold a long tail into "Other" with `limit` rather than scrolling a hundred rows.
+- Don't colour bars by status or give each row its own colour: colour is identity, and these rows are one series.
+- Don't set the bars' lengths to share of total yourself; `share` says it in words, and the bars compare rows with each other.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`BarList` as first used in its preview:
+
+```tsx
+import { BarList } from 'altitude-design';
+
+<BarList aria-labelledby="bl-pages" data={pages.map((p) => ({ ...p, href: '#' + p.name }))} limit={7} share noun="pages" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`bl`, `bl-tools` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { BarList, Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Input } from 'altitude-design';
+
+const pages = [
+  { name: '/pricing', value: 4210 }, { name: '/', value: 3880 }, { name: '/docs/getting-started', value: 2410 }, { name: '/blog/height-is-the-interface-why-we-stopped-using-shadows-for-everything', value: 1630 },
+  { name: '/changelog', value: 1210 }, { name: '/docs/components/chart-container', value: 980 }, { name: '/careers', value: 610 },
+  ...Array.from({ length: 14 }, (_, i) => ({ name: `/docs/page-${i + 1}`, value: 420 - i * 25 })),
+];
+const referrers0 = [{ name: 'google.com', value: 5120 }, { name: 'github.com', value: 2310 }, { name: 'news.ycombinator.com', value: 1980 }, { name: 'x.com', value: 760 }, { name: 'Direct', value: 3400 }];
+const referrers1 = [{ name: 'google.com', value: 5240 }, { name: 'github.com', value: 2390 }, { name: 'news.ycombinator.com', value: 6120 }, { name: 'x.com', value: 1310 }, { name: 'Direct', value: 3460 }];
+export default function App() {
+  const [spike, setSpike] = React.useState(false);
+  const [q, setQ] = React.useState('');
+  const [later, setLater] = React.useState(undefined);
+  React.useEffect(() => { const t = setTimeout(() => setLater([{ name: 'Acme Corp', value: 48200 }, { name: 'Globex', value: 31900 }, { name: 'Initech', value: 22750 }, { name: 'Umbrella', value: 9400 }]), 2400); return () => clearTimeout(t); }, []);
+  const usd = new Intl.NumberFormat('en', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
+  return (
+    <div className="bl">
+      <Card>
+        <CardHeader><CardTitle id="bl-pages">Top pages</CardTitle><CardDescription>Last 7 days · views</CardDescription></CardHeader>
+        <CardContent><BarList aria-labelledby="bl-pages" data={pages.map((p) => ({ ...p, href: '#' + p.name }))} limit={7} share noun="pages" /></CardContent>
+      </Card>
+      <div style={{ display: 'grid', gap: 16, alignContent: 'start' }}>
+        <Card>
+          <CardHeader><CardTitle id="bl-ref">Top referrers</CardTitle><CardDescription>Static rows: nothing lifts</CardDescription></CardHeader>
+          <CardContent>
+            <div className="bl-tools">
+              <Button size="sm" variant="secondary" onClick={() => setSpike((s) => !s)}>{spike ? 'Yesterday' : 'Today'}</Button>
+              <Input size="sm" placeholder="Filter" aria-label="Filter referrers" value={q} onChange={(e) => setQ(e.target.value)} />
+            </div>
+            <BarList aria-labelledby="bl-ref" data={spike ? referrers1 : referrers0} relevance={q ? (d) => (d.name.includes(q) ? 'match' : 'miss') : undefined} />
+          </CardContent>
+        </Card>
+        <Card>
+          <CardHeader><CardTitle id="bl-cust">Top customers</CardTitle><CardDescription>Spend this quarter</CardDescription></CardHeader>
+          <CardContent><BarList aria-labelledby="bl-cust" data={later} format={usd.format} limit={4} /></CardContent>
+        </Card>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,98 @@
+# Board
+
+Columns of cards you move between, a kanban: columns are receptacles that open when you carry a card, and the card floats in your hand until it lands.
+
+**Elevation: receptacles and a hand.** At rest a board is just its cards: the columns lie flush on the ground, with only their titles and counts to mark them, and the cards are raised (level 1), lifting to level 2 under the pointer. The moment a card is carried, every column opens into a well (things you put something into are openings), and the column under the card deepens to a trench with an accent rim, as a DropZone does when it's ready to receive. The carried card floats at level 3, tilted 1.2° and 1.5% larger, and follows the pointer; the cards around it glide aside (`ease-settle`), and the slot it will land in opens as a trench. Let go and it's carried into the slot with a slight overshoot (`ease-settle`) while its shadow sinks back to `elev-1`, and the columns close up. A move to the column it came from, or nowhere, travels back the same way.
+
+- **A collapsed column is a Pile.** Its thickness (one, two or three sheets) and its count badge say how many cards it holds. It still takes drops: carried over it, it deepens and fans its sheets toward the card, and the card is added to the end.
+- **Someone else's hand.** A card a collaborator is holding (`heldBy`) is lifted to level 3, outlined in their presence colour and wears their name; you can't pick it up meanwhile.
+- **Afterglow.** `settle` makes a card arrive tinted and lifted, then settle: for cards moved by someone else.
+
+**Editing in place.** On a board the column you add to is the context, so cards are added and edited where they are, not in a Dialog.
+
+- **Add.** With `onCreate(title)` on a `BoardColumn`, the column ends in an add slot: a dashed well (an opening) named “Add a card to To do”, deepening to a trench under the pointer. Activating it raises it into a new card (static, level 1) holding a “Card title” field. Enter creates the card and leaves a fresh, empty field, so several can be added in a row; Escape, or Enter on an empty field, closes it and returns focus to the slot. A pending card hovers after `dur-grace`; a refused one drops to a trench with its title kept and Retry. Resolve `{ ok: true, value: { id } }` after the card is among the children, or `{ ok: false, error }`. A collapsed column shows no add slot. Announced: “Added Fix login to To do, position 4 of 4.”
+- **Rename.** With `onRename(draft)` (InlineEdit's contract) and a `label`, F2 or the card's visible Rename button turns the title into a field, selected. Enter saves, Escape cancels, a refusal keeps the draft with its error, and focus returns to the card. While the field is open, Space and Enter type into it and don't pick the card up; Space and Enter on the card itself still pick it up, so renaming has F2 and a button rather than Enter.
+- **Edit fields.** With `value`, `renderEditor(field)` and `onSave` (EditRegion's contract), the card's Edit button grows it into an `EditRegion` in place, and the cards below are pushed down. `onValueChange` publishes the saved record. A card being edited can't be picked up.
+
+**Keyboard and screen readers.** Each column is a `section` named by its title (an `h3`), with its card count. Cards are focusable buttons with `aria-roledescription="draggable card"` and instructions attached. Space or Enter picks a card up (`aria-pressed`); ↑ and ↓ move it within its column, ← and → carry it to the next open column; Space drops it; Escape puts it back where it started. Every step is announced in an assertive live region ("Review, position 2 of 3"). A card held by a collaborator says so instead of lifting. Moving focus away puts a held card down where it is. Under reduced motion cards don't travel or tilt; their levels still change. Forced colours dash the open columns and outline the target in Highlight.
+
+| Part | |
+|---|---|
+| `Board` | `onMove({ cardId, from, to })`, where `from` and `to` are `{ column, index }`; you update your data and the board carries the cards |
+| `BoardColumn` | `id`, `title`, `collapsible`, `collapsed`/`defaultCollapsed`/`onCollapsedChange`, `onCreate`, `addLabel` |
+| `BoardCard` | `id`, `label` (for announcements), `heldBy`, `settle`, `onRename`, `value`/`renderEditor`/`onSave`/`onValueChange`; anything inside it |
+
+**On touch.** A swipe scrolls the board; a press-and-hold picks a card up, then a drag moves it. The card tools are always shown where there's no hover.
+
+**You provide:** the data and an `onMove` that moves the card in it (splice it out of `from.column` at `from.index`, into `to.column` at `to.index`); card content (a title, then a `small` line of detail); short column titles.
+
+- Do keep buttons and links inside cards: pressing them doesn't pick the card up.
+- Do collapse finished columns rather than hiding them; the pile keeps their weight visible.
+- Don't use a board for a single list you reorder; that's SortableList.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Board` as first used in its preview:
+
+```tsx
+import { Board, BoardCard, BoardColumn, Field, Input } from 'altitude-design';
+
+<Board onMove={move} aria-label="Launch board">
+  {Object.keys(titles).map(k => <BoardColumn key={k} id={k} title={titles[k]} collapsible={k === "done"} defaultCollapsed={k === "done"} onCreate={k === "done" ? undefined : create(k)}>
+    {cols[k].map(c => <BoardCard key={c.id} id={c.id} label={c.t} heldBy={c.held} onRename={rename(k, c.id)}
+      {...(k === "review" ? { value: { title: c.t, meta: c.m }, onValueChange: update(k, c.id),
+        renderEditor: field => <><Field label="Title"><Input {...field("title")} size="sm" /></Field><Field label="Details"><Input {...field("meta")} size="sm" /></Field></>,
+        onSave: async draft => { await wait(200); return refuse(draft.title) || { ok: true, value: draft }; } } : {})}>
+      {c.t}<small>{c.m}</small>
+    </BoardCard>)}
+  </BoardColumn>)}
+</Board>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Board, BoardCard, BoardColumn, Field, Input } from 'altitude-design';
+
+const start = {
+  todo: [{ id: "c1", t: "Write release notes", m: "Docs \xB7 Jon" }, { id: "c2", t: "Fix cold-start regression", m: "Runtime \xB7 Lena" }, { id: "c3", t: "Plan Q1 roadmap", m: "Planning \xB7 Ada" }],
+  doing: [{ id: "c4", t: "Pricing page copy", m: "Marketing \xB7 Mara", held: { name: "Mara", presence: 1 } }, { id: "c5", t: "Support macros", m: "Support \xB7 Ivy" }],
+  review: [{ id: "c6", t: "Brand voice", m: "Design \xB7 Ada" }],
+  done: Array.from({ length: 12 }, (_, i) => ({ id: "d" + i, t: "Shipped item " + (i + 1), m: "Done" }))
+};
+const titles = { todo: "To do", doing: "In progress", review: "Review", done: "Done" };
+export default function App() {
+  const [cols, setCols] = React.useState(start);
+  const [last, setLast] = React.useState(null);
+  const seq = React.useRef(0);
+  const move = ({ cardId, from, to }) => setCols((c) => {
+    const next = Object.fromEntries(Object.entries(c).map(([k, v]) => [k, v.slice()]));
+    const [card] = next[from.column].splice(from.index, 1);
+    next[to.column].splice(to.index, 0, card);
+    setLast(`${card.t} \u2192 ${titles[to.column]}`);
+    return next;
+  });
+  const wait = ms => new Promise(r => setTimeout(r, ms));
+  // The demo service refuses titles with “TBD” in them.
+  const refuse = t => /tbd/i.test(t) ? { ok: false, error: "Write the task, not \u201cTBD\u201d." } : null;
+  const create = k => async t => { await wait(250); const no = refuse(t); if (no) return no; const card = { id: "n" + ++seq.current, t, m: "New" }; setCols(c => ({ ...c, [k]: [...c[k], card] })); return { ok: true, value: { id: card.id } }; };
+  const rename = (k, id) => async t => { await wait(200); const no = refuse(t); if (no) return no; setCols(c => ({ ...c, [k]: c[k].map(x => x.id === id ? { ...x, t } : x) })); return { ok: true, value: t }; };
+  const update = (k, id) => v => setCols(c => ({ ...c, [k]: c[k].map(x => x.id === id ? { ...x, t: v.title, m: v.meta } : x) }));
+  return <div className="col" style={{ gap: 4 }}>
+    <Board onMove={move} aria-label="Launch board">
+      {Object.keys(titles).map(k => <BoardColumn key={k} id={k} title={titles[k]} collapsible={k === "done"} defaultCollapsed={k === "done"} onCreate={k === "done" ? undefined : create(k)}>
+        {cols[k].map(c => <BoardCard key={c.id} id={c.id} label={c.t} heldBy={c.held} onRename={rename(k, c.id)}
+          {...(k === "review" ? { value: { title: c.t, meta: c.m }, onValueChange: update(k, c.id),
+            renderEditor: field => <><Field label="Title"><Input {...field("title")} size="sm" /></Field><Field label="Details"><Input {...field("meta")} size="sm" /></Field></>,
+            onSave: async draft => { await wait(200); return refuse(draft.title) || { ok: true, value: draft }; } } : {})}>
+          {c.t}<small>{c.m}</small>
+        </BoardCard>)}
+      </BoardColumn>)}
+    </Board>
+    <p className="cap">{last ? `Moved: ${last}.` : "Drag a card, or focus one and press Space, then the arrow keys. F2 renames a card; each column adds cards at its foot. Done is collapsed into a pile and still takes cards."}</p>
+  </div>;
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,66 @@
+# Breadcrumb
+
+Where you are in an app with routes: Settings › Members › Jane Doe, or Projects › Atlas › Issues.
+
+**Elevation: a staircase.** It's `Drilldown`'s breadcrumb, now available on its own, and the two share one implementation. Every step stands on the same ground line, outlined face and wall together, and **each deeper place is a taller step** (its wall 3px longer per level). Steps you can go back to are live: they lift one level when pointed at and press to the ground. The current page is the last and tallest step, in weight 600, and it doesn't press. A route-based app has no stack of views, so there's no pile under it, and **a route change re-renders it without motion**: a new route isn't an arrival.
+
+**Deep paths.** With `maxItems`, a longer path keeps its first step and its last `maxItems − 1`. The middle waits behind a "…" step that opens a `DropdownMenu`, which floats at level 3.
+
+**No separators.** Each step's height already says it's deeper than the one before, so there are no slashes or chevrons. `BreadcrumbSeparator` exists for code written for shadcn/ui and renders nothing.
+
+**Accessibility.** The [breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/): a `nav` labelled "Breadcrumb", an ordered list, and `aria-current="page"` on the last step. The "…" step is a menu button named "Show 3 more levels". Under forced colours steps keep a 1px outline and the current step a 2px one. Under `contrast="more"` each step's wall is `ink`.
+
+**Props.**
+- `items` (`{ label, href?, onClick? }[]`; the last entry is the current page).
+- `maxItems`.
+- `renderLink(item, props)` for a router's link: spread `props` onto it.
+- `onNavigate(item)` for steps chosen from the "…" menu (default: follow `href`).
+- **Composable parts:** `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage` and `BreadcrumbEllipsis` mirror shadcn/ui's for full control.
+
+**Fitting the width.** `fit="collapse"` (the default) keeps the trail on one line: when it doesn't fit, steps from the second onward move behind "…" until it does, keeping the first step and the current page, and they come back when there's room. `fit="wrap"` lets it wrap instead. `maxItems` still caps it by count.
+
+**You provide:** the path, from the top of the app to here.
+
+```tsx
+<Breadcrumb
+  items={[{ label: 'Settings', href: '/settings' }, { label: 'Members', href: '/settings/members' }, { label: 'Jane Doe' }]}
+  maxItems={4}
+  renderLink={(item, props) => <NextLink href={item.href!} {...props}>{item.label}</NextLink>}
+/>
+```
+
+- Do end with the current page, as plain text.
+- Do use it for location in a hierarchy, not for history ("back").
+- Don't add separators between steps.
+- Don't use it inside a `Drilldown`, which has its own.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Breadcrumb` as first used in its preview:
+
+```tsx
+import { Breadcrumb } from 'altitude-design';
+
+<Breadcrumb items={[{ label: 'Settings', href: '#/settings' }, { label: 'Members', href: '#/settings/members' }, { label: 'Jane Doe' }]} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Breadcrumb } from 'altitude-design';
+
+const RouterLink = React.forwardRef(({ to, ...rest }, ref) => <a ref={ref} href={'#' + to} {...rest} />);
+export default function App() {
+  return (
+    <div className="col">
+      <Breadcrumb items={[{ label: 'Settings', href: '#/settings' }, { label: 'Members', href: '#/settings/members' }, { label: 'Jane Doe' }]} />
+      <Breadcrumb maxItems={4} renderLink={(item, props) => <RouterLink to={item.href.slice(1)} {...props}>{item.label}</RouterLink>}
+        items={[{ label: 'Projects', href: '#/projects' }, { label: 'Atlas', href: '#/projects/atlas' }, { label: 'Q4 launch', href: '#/projects/atlas/q4' }, { label: 'Issues', href: '#/projects/atlas/q4/issues' }, { label: 'Billing page', href: '#/projects/atlas/q4/issues/212' }, { label: 'Comments' }]} />
+      <p className="cap">Each step you can go back to lifts when pointed at; the current page is the tallest step and doesn't press. A deep path keeps its first and last steps, with the middle behind "…".</p>
+    </div>
+  );
+}
+```
+<!-- /example -->