altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,97 @@
+# Select
+
+Chooses one value from a list: an opening you fill by choosing, with the list rising from its edge at level 3.
+
+**Why an opening.** In Altitude, things you press are raised and things you fill are sunk. Choosing a value fills a field, so a Select is built like `Input`, not like a button. While nothing is chosen it's a well with its back wall showing (`--alt-wall-in`) and its placeholder sitting on the floor; as the pointer approaches, the wall deepens. Once a value is chosen the floor rises flush (`surface-raised`, no wall), so a form's unanswered selects read as holes at a glance, exactly like its empty inputs. When it's invalid it drops to trench depth on `critical-soft`. A chevron says it opens.
+
+**The list.** It rises from the field's edge to level 3 like Popover and DropdownMenu (6px from 96% scale, its shadow growing to `elev-3`), opening upward instead when there's more room above. One `accent-soft` highlight is carried between options on `ease-settle`. The chosen option wears the Checkbox family's tick (the same path and stroke, in `accent-ink`), drawn in as the list opens. Choosing sinks the list back, raises the floor flush and lets the new value settle in with a brief `accent-soft` afterglow (a fifth of `dur-settle`).
+
+| State | Looks like |
+|---|---|
+| Empty | a well with its back wall showing; the placeholder in `ink-muted` |
+| Chosen | flush with the page; the value in `ink` |
+| Open or focused | the lit floor of a focused Input; reached by keyboard, also its 2px neutral rim (kept while the list has focus); an empty field holds its approached depth; the list at level 3 |
+| Invalid | trench depth on `critical-soft` with a `critical` rim |
+| Disabled | flat on the ground, `ink-faint` |
+
+**Keyboard and screen readers.** The WAI-ARIA listbox pattern with a button trigger. The trigger is a `button` with `aria-haspopup="listbox"` and `aria-expanded`; ↓, ↑, Enter or Space open the list and focus moves into it, where `aria-activedescendant` names the highlighted option and `aria-selected` the chosen one. ↑ and ↓ move, Home and End jump to the ends, typing letters jumps to the next option that starts with them (also on the closed trigger, which opens at the match), Enter or Space chooses, and Escape closes without changing the value. Disabled options are skipped. The list is named by the field's label. In forced colours the highlighted option has a Highlight rim, empty fields a dashed rim and chosen ones a solid rim.
+
+**As a sheet.** `presentation="auto"` (the default) opens the list as a sheet at the bottom edge on a narrow touch screen, titled by the field's label, with Close and 44px rows; a tap outside closes it too. `"anchored"` or `"sheet"` forces one.
+
+**You provide:** options as `items` (`{ value, label, description?, icon?, disabled? }`) or `SelectItem` children; `value`/`onValueChange` or `defaultValue`; a `placeholder` that says what to choose ("Choose a region"); `name` to submit it with a form (a hidden native select carries the value and participates in constraint validation). Wrap it in `Field` for a label, hint and error: Field passes the id, the description and `invalid` through.
+
+`required` rejects an empty value through native form validation, including without a `name`; invalid submission focuses the visible trigger, marks it invalid and associates a visible “Choose an option.” alert. Set `requiredMessage` to localize or clarify that instruction. A supplied `Field` error takes precedence so the same issue is not announced twice. Valid selection and form reset clear this native-validation feedback. Disabled selects are excluded from validation and form data. Form reset restores `defaultValue` for uncontrolled selects and calls `onValueChange` with that reset value. Controlled selects retain their application-owned value; reset that state in the form’s reset handler if desired. A cancelled form reset leaves the selection untouched.
+
+- Do use a RadioGroup instead when there are five options or fewer: people can see and compare them without opening anything.
+- Do give a non-string `label` a `textValue`, so typeahead can find it.
+- Don't use it for actions; that's a DropdownMenu.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Select` as first used in its preview:
+
+```tsx
+import { Select } from 'altitude-design';
+
+<Select items={regions} placeholder="Choose a region" name="region" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `grid`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Field, Select, SelectItem } from 'altitude-design';
+
+const regions = [
+  { value: "iad", label: "Virginia", description: "us-east-1" },
+  { value: "fra", label: "Frankfurt", description: "eu-central-2" },
+  { value: "sin", label: "Singapore", description: "ap-southeast-1" },
+  { value: "gru", label: "S\xE3o Paulo", description: "sa-east-1" },
+  { value: "syd", label: "Sydney", description: "Opens in March", disabled: true }
+];
+export default function App() {
+  const [plan, setPlan] = React.useState("team");
+  const [tz, setTz] = React.useState("");
+  return <div className="col">
+  <div className="grid">
+    <Field label="Region" hint="Where your deployments run.">
+      <Select items={regions} placeholder="Choose a region" name="region" />
+    </Field>
+    <Field label="Plan">
+      <Select value={plan} onValueChange={setPlan}>
+        <SelectItem value="solo">Solo</SelectItem>
+        <SelectItem value="team">Team</SelectItem>
+        <SelectItem value="org">Organization</SelectItem>
+      </Select>
+    </Field>
+    <Field label="Timezone" required={true} error={tz ? null : "Choose a timezone."}>
+      <Select
+        value={tz}
+        onValueChange={setTz}
+        placeholder="Choose a timezone"
+        items={[{ value: "utc", label: "UTC" }, { value: "lis", label: "Europe/Lisbon" }, { value: "nyc", label: "America/New_York" }]}
+      />
+    </Field>
+    <Field label="Runtime">
+      <Select
+        defaultValue="node"
+        defaultOpen={true}
+        items={[{ value: "node", label: "Node.js 22" }, { value: "bun", label: "Bun 1.2" }, { value: "deno", label: "Deno 2" }, { value: "edge", label: "Edge (V8 isolates)" }]}
+      />
+    </Field>
+    <Field label="Owner">
+      <Select
+        disabled={true}
+        defaultValue="mara"
+        items={[{ value: "mara", label: "Mara Quist" }]}
+      />
+    </Field>
+  </div>
+  <p className="cap" style={{ marginTop: 150 }}>
+    Empty fields are holes with their back wall showing; choosing raises the floor flush. Type a letter on a focused field to jump to it.
+  </p>
+</div>;
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,70 @@
+# Separator
+
+A divider: between sections in a card, groups in a toolbar, items in a sidebar, or "or" between two ways to sign in.
+
+**Elevation.** A divider is part of the page, so it lies on the ground: 1px of `line`, with no shadow and no wall. `line` is for decorative dividers. `line-control` is for the edges of controls, so a separator never uses it except under `contrast="more"`. Don't draw an `<hr>` with your own border colour: "never invent an in-between gray".
+
+**Semantics.** By default it's `role="separator"` with `aria-orientation`, so a screen reader knows the content is parted. Set `decorative` when the layout already says it (a line between groups of toolbar buttons): it becomes `role="none"` and is skipped. A labelled separator (`label="or"`) is the word in `ink-muted` between two drawn lines, and it's read as plain text. `role="separator"` would make its children presentational and lose the word.
+
+**Orientation.** `horizontal` fills its container's width. `vertical` stretches to the height of the row it's in (at least 1em), so put it in a flex row.
+
+**Accessibility.** Under forced colours it's 1px of `CanvasText`. Under `contrast="more"` the lines are `line-control`.
+
+**Props:** `orientation` (`'horizontal' | 'vertical'`, default horizontal); `decorative`; `label`.
+
+**You provide:** where it goes, and whether it says something (leave `decorative` off) or only decorates.
+
+```tsx
+<Separator />
+<Separator orientation="vertical" decorative />
+<Separator label="or" />
+```
+
+- Do use it instead of a border on one side of a section.
+- Do make a separator between groups of toolbar buttons `decorative`.
+- Don't use it to fake a table's row lines; `Table` and `ItemGroup` draw their own (`ItemSeparator`).
+- Don't give it a colour, a thickness or a shadow.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Separator` as first used in its preview:
+
+```tsx
+import { Separator } from 'altitude-design';
+
+<Separator />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`sp`, `cap`, `col`, `bar`, `signin` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Input, Separator } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="sp">
+      <Card>
+        <CardHeader><CardTitle>Workspace</CardTitle><CardDescription>Name, URL and region</CardDescription></CardHeader>
+        <Separator />
+        <CardContent><p className="cap">Sections in a card are parted by a horizontal separator: role="separator", 1px of line.</p></CardContent>
+      </Card>
+      <div className="col">
+        <div className="bar">
+          <Button size="sm" variant="ghost">Bold</Button>
+          <Button size="sm" variant="ghost">Italic</Button>
+          <Separator orientation="vertical" decorative />
+          <Button size="sm" variant="ghost">Link</Button>
+        </div>
+        <div className="signin">
+          <Button variant="secondary">Continue with SSO</Button>
+          <Separator label="or" />
+          <Input placeholder="Email address" aria-label="Email address" />
+        </div>
+        <p className="cap">A vertical one between groups of buttons is decorative. "or" is read as a word; its lines are drawn.</p>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,126 @@
+# Sheet
+
+A large panel laid over the page at level 4, anchored to an edge, for a task that needs more room than a popover and less commitment than a page.
+
+**Why level 4.** A sheet is a whole working surface above the page: higher than menus and popovers (level 3), because it holds a task rather than one choice, and below the summit (level 5), because it doesn't demand an answer. It's drawn with `surface-overlay` and `elev-4`, the toasts' tier.
+
+**Risen at its edge, not slid in.** Nothing in Altitude slides in from the side. A sheet appears where it's anchored: it travels 16px out of its edge as it fades in, while its shadow grows from `elev-1` to `elev-4` (`dur-travel-4`, `ease-rise`). It stands 8px clear of the edge with `radius-xl` corners, so its own edges, and the shadow it casts below them, read as height. A modal sheet recedes the page behind it, as a dialog does. Closing lifts it off: it rises 8px and grows 1% as its shadow spreads and it fades, in 70% of the time it took to arrive.
+
+**Inside.** The sheet scrolls as one column. `SheetHeader` stays at the top and rises to `elev-2` once content passes under it; `SheetFooter` stays at the bottom, and while there's more below, its top edge curves away (`lip-bottom`), as in ScrollArea.
+
+**Bottom sheets** have a finger pull at the top: a small recess, because everything you put something into is an opening in Altitude, and this is where your finger goes. It deepens as the pointer approaches. Drag it and the sheet follows; past a third of its height, or with a flick, it goes; otherwise it springs back. The pull is a convenience: Escape, the close button and the scrim still close it.
+
+**Modal or not.** By default a sheet is modal (the WAI-ARIA dialog pattern): the scrim blocks the page, Tab is trapped, Escape closes it and focus returns to what opened it. `modal={false}` makes a side panel that leaves the page usable: no scrim, no receding page, no trap; focus still moves into it, and Escape closes it from inside.
+
+| Prop | Default | |
+|---|---|---|
+| `side` | `right` | `right`, `left` or `bottom` |
+| `size` | `md` | width: `sm` 360, `md` 440, `lg` 560px; a bottom sheet 480, 720, 960px |
+| `modal` | `true` | `false`: a non-blocking panel |
+| `dismissible` | `true` | `false`: only your own buttons close it |
+
+**On a phone.** It sizes to the visible viewport, not the largest one: with the on-screen keyboard open it shrinks to the part you can see, so its footer and the focused field stay in reach.
+
+**You provide:** `open`/`onOpenChange` or a `trigger`, and the content: `SheetHeader` with `SheetTitle` (it names the sheet) and `SheetDescription`, the body, and `SheetFooter` with the actions (cancel as ghost first, the action last).
+
+- Do use a sheet to edit an item without leaving the list it's in, and for filters, details and settings.
+- Don't open a sheet from a Dialog or the CommandPalette. A level-4 surface can't sit on the summit: if it's opened under one, it paints beneath it and leaves focus where it is. A Dialog may open from a sheet, to confirm something.
+- Don't stack a sheet on a sheet; replace its content instead.
+
+A modal Sheet shares document-scoped isolation, scroll ownership and eligible-focus containment with Dialog. Its locks remain through exit. Opening a Dialog from a Sheet suspends the Sheet, then resumes its focus and existing background policy after the Dialog closes. A Sheet requested beneath a summit cannot take its focus or `aria-modal` ownership. A stationary Dialog also removes the lower Sheet's scrim blur until it closes.
+
+`modal={false}` keeps the page interactive and scrollable: no scrim, recession or focus trap. Closing that Sheet does not restore focus over a newer modal.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Sheet` as first used in its preview:
+
+```tsx
+import { Button, Input, Sheet, SheetDescription, SheetFooter, SheetHeader, SheetTitle } from 'altitude-design';
+
+<Sheet side="bottom" size="sm" trigger={<Button>Share</Button>}>
+  <SheetHeader>
+    <SheetTitle>Share Northwind</SheetTitle>
+    <SheetDescription>
+      Anyone with the link can view the latest deployment.
+    </SheetDescription>
+  </SheetHeader>
+  <Input
+    defaultValue="https://acme.dev/n/8dc01b2"
+    readOnly={true}
+    aria-label="Share link"
+  />
+  <SheetFooter><Button variant="primary">Copy link</Button></SheetFooter>
+</Sheet>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`page`, `row`, `grid`, `form` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, Card, Checkbox, Field, Input, Sheet, SheetDescription, SheetFooter, SheetHeader, SheetTitle, Switch, Textarea } from 'altitude-design';
+
+export default function App() {
+  const [edit, setEdit] = React.useState(true);
+  return <div className="page">
+  <div className="row">
+    <Button variant="primary" onClick={() => setEdit(true)}>Edit project</Button>
+    <Sheet side="bottom" size="sm" trigger={<Button>Share</Button>}>
+      <SheetHeader>
+        <SheetTitle>Share Northwind</SheetTitle>
+        <SheetDescription>
+          Anyone with the link can view the latest deployment.
+        </SheetDescription>
+      </SheetHeader>
+      <Input
+        defaultValue="https://acme.dev/n/8dc01b2"
+        readOnly={true}
+        aria-label="Share link"
+      />
+      <SheetFooter><Button variant="primary">Copy link</Button></SheetFooter>
+    </Sheet>
+    <Sheet
+      side="left"
+      size="sm"
+      modal={false}
+      trigger={<Button variant="ghost">Filters</Button>}
+    >
+      <SheetHeader>
+        <SheetTitle>Filters</SheetTitle>
+        <SheetDescription>The page stays usable while this is open.</SheetDescription>
+      </SheetHeader>
+      <Checkbox label="Production" defaultChecked={true} />
+      <Checkbox label="Preview" />
+      <Checkbox label="Failed builds only" />
+    </Sheet>
+  </div>
+  <div className="grid" data-tells-ignore="LA4 placeholder page behind the overlay">
+    <Card />
+    <Card />
+    <Card />
+    <Card />
+    <Card />
+    <Card />
+  </div>
+  <Sheet open={edit} onOpenChange={setEdit}>
+    <SheetHeader>
+      <SheetTitle>Edit project</SheetTitle>
+      <SheetDescription>Changes apply to every environment.</SheetDescription>
+    </SheetHeader>
+    <div className="form">
+      <Field label="Project name"><Input defaultValue="Northwind" /></Field>
+      <Field label="Description" hint="Shown on the project's card.">
+        <Textarea placeholder="What is this project for?" />
+      </Field>
+      <Switch label="Deploy previews for every branch" defaultChecked={true} />
+    </div>
+    <SheetFooter>
+      <Button variant="ghost" onClick={() => setEdit(false)}>Cancel</Button>
+      <Button variant="primary" onClick={() => setEdit(false)}>Save changes</Button>
+    </SheetFooter>
+  </Sheet>
+</div>;
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,50 @@
+# Skeleton
+
+Stands in for loading content as an **imprint**: the shape of what's coming, pressed into the page. When the content arrives it rises out of its imprint and the imprint fills in behind it.
+
+Imprints are wells (`surface-well`, inset shadow) because they're openings waiting to receive something. While waiting, a soft band of light passes over them every `dur-sweep`, staggered line by line; it stops under reduced motion. When `loaded` turns true, the children rise from the bottom of the imprint over `dur-travel-3` while the well fades out. Reveals share the attention budget, so if many land at once, no more than four begin together and the rest follow in order.
+
+**Or don't.** `Avatar`, `Badge`, `CardTitle`, `CardDescription`, `CardContent` and `DataTable` draw their own imprint while your data is still undefined; see `Await`. Use Skeleton for layouts of your own.
+
+**You provide:** the real content as children, `loaded`, and a shape that matches it: `shape="circle"` with a `width`, `shape="text"` with `lines`, or a block with `width` and `height`.
+
+- Match the real layout so nothing jumps when content arrives.
+- Don't show imprints for loads under about 300ms; show nothing.
+
+Under `AltitudeProvider loading="breath"` (experimental) a Skeleton breathes in depth instead of being swept by light, on the same page clock as every other imprint, and its content fills past the ground when `loaded` turns true. See `Await`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Skeleton` as first used in its preview:
+
+```tsx
+import { Avatar, Skeleton } from 'altitude-design';
+
+<Skeleton loaded={loaded} shape="circle" width={44}><Avatar name="Mara Quist" size={44} status="active" /></Skeleton>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `card`, `lines`, `txt`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Avatar, Skeleton, Surface } from 'altitude-design';
+
+export default function App() {
+  const [loaded, setLoaded] = React.useState(false);
+  React.useEffect(() => { const t = setInterval(() => setLoaded((l) => !l), 2600); return () => clearInterval(t); }, []);
+  return (
+    <div className="col">
+      <Surface level={1} className="card">
+        <Skeleton loaded={loaded} shape="circle" width={44}><Avatar name="Mara Quist" size={44} status="active" /></Skeleton>
+        <div className="lines">
+          <Skeleton loaded={loaded} width="45%" height={14}><b style={{ font: '600 14px/20px var(--font-sans)' }}>Mara Quist</b></Skeleton>
+          <Skeleton loaded={loaded} shape="text" lines={2}><p className="txt">Merged “Faster cold starts” into main. Cold starts are down 38% across all regions.</p></Skeleton>
+        </div>
+      </Surface>
+      <p className="cap">While it loads, the layout is pressed into the page; when content lands it rises out of its imprint, four at a time at most.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,60 @@
+# Slider
+
+Picks a number from a range by dragging a raised thumb along a trench.
+
+The track is level −2 and the filled part is a raised `accent` bar inside it. The thumb is level 1 with an `accent` rim, level 2 on hover, and floats to level 3 (scaled 12%) while held, with its value floating above it in a bubble at the same height as a tooltip. Keyboard: arrows step, Page Up/Down jump a tenth, Home/End go to the ends.
+
+**You provide:** `value`/`onValueChange` or `defaultValue`, `min`, `max`, `step`, an `aria-label`, and `format` for the bubble (`n => n + '%'`).
+
+## A range
+
+Pass `value` (or `defaultValue`) as `[low, high]` and the Slider has two thumbs, with the raised `accent` fill running between them in the same trench: a price filter, a latency window.
+
+```tsx
+<Slider value={[lo, hi]} onValueChange={([a, b]) => setRange([a, b])} min={0} max={500} step={5}
+        minStepsBetween={2} aria-label={['Minimum price', 'Maximum price']} format={(n) => `$${n}`} />
+```
+
+- **Thumbs can't cross.** A thumb pushed against the other stops there, with no overshoot; `minStepsBetween` keeps them that many steps apart. Two thumbs that meet (with no gap) part in the direction of the first drag.
+- **Drag the fill** to move both thumbs together; the window keeps its width and stops at the ends. The fill lifts to level 2 on hover and shows a grab cursor, because dragging it does something.
+- **Press the track** outside the thumbs and the nearer one moves there and takes focus. Pressing the fill moves neither.
+- **Only the thumb in hand floats** to level 3 with its bubble; the other stays at rest. Panning holds both.
+- **Keyboard**, after the [APG multi-thumb slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/): each thumb is its own Tab stop and `role="slider"`, with `aria-valuemin` and `aria-valuemax` bounded by the other thumb (less the gap). Arrows step, Page Up/Down jump a tenth, Home/End go to that thumb's own bounds. When `format` returns text, it's each thumb's `aria-valuetext` too.
+- **Names.** Give each thumb its own name (`['Minimum price', 'Maximum price']`), or one name for the pair: the thumbs are then "Price, minimum" and "Price, maximum", in a `role="group"` named "Price".
+
+- Do show the current value in text near the slider when it matters precisely; the bubble only shows while dragging or focused.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Slider` as first used in its preview:
+
+```tsx
+import { Slider } from 'altitude-design';
+
+<Slider value={v} onValueChange={setV} aria-label="Volume" format={(n) => n + '%'} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `wrap`, `cap`, `gap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Slider } from 'altitude-design';
+
+export default function App() {
+  const [v, setV] = React.useState(64);
+  const [price, setPrice] = React.useState([20, 80]);
+  return (
+    <div className="col wrap">
+      <Slider value={v} onValueChange={setV} aria-label="Volume" format={(n) => n + '%'} />
+      <Slider defaultValue={30} disabled aria-label="Disabled" />
+      <p className="cap">Volume {v}% — drag, or focus and use the arrow keys.</p>
+      <div className="gap" />
+      <Slider value={price} onValueChange={setPrice} min={0} max={200} step={5} minStepsBetween={2}
+        aria-label={['Minimum price', 'Maximum price']} format={(n) => '$' + n} />
+      <p className="cap">Price ${price[0]}–${price[1]} — drag either thumb, or the fill to move both.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,45 @@
+# SortableList
+
+Reorders a list by picking items up: the item you hold floats in your hand, the slot it will land in opens, and it lands.
+
+Pressing and dragging an item lifts it to level 3 (floating surface, `elev-3`), scales it 1.5% and tilts it half a degree; the others glide aside on `ease-settle`, and a well opens where it will land. Releasing animates it into place (FLIP) while its shadow falls back to `elev-1`. Keyboard: focus an item, press Space to pick it up, arrow keys to move it, Space to drop, Escape to cancel; every move is announced.
+
+**On touch.** A swipe on a row scrolls; a press-and-hold picks it up, and the grip picks it up at once. A mouse drag needs no hold.
+
+**You provide:** `items`, `getKey`, `onReorder` (receives the new array), `renderItem` (the row content; the row itself and its grip are drawn for you), `getLabel` for announcements, `aria-label`.
+
+- Do keep rows short and uniform; the slot is sized to the item being moved.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`SortableList` as first used in its preview:
+
+```tsx
+import { Badge, SortableList } from 'altitude-design';
+
+<SortableList aria-label="Priorities" items={items} getKey={(i) => i.id} getLabel={(i) => i.t} onReorder={setItems}
+  renderItem={(i) => <div className="it">{i.t}<Badge tone={i.p === 'High' ? 'critical' : i.p === 'Med' ? 'caution' : 'neutral'}>{i.p}</Badge></div>} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `wrap`, `it`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, SortableList } from 'altitude-design';
+
+export default function App() {
+  const [items, setItems] = React.useState([
+    { id: 'a', t: 'Write release notes', p: 'High' }, { id: 'b', t: 'Review pricing copy', p: 'Med' },
+    { id: 'c', t: 'Fix cold-start regression', p: 'High' }, { id: 'd', t: 'Update onboarding emails', p: 'Low' }, { id: 'e', t: 'Plan Q1 roadmap', p: 'Med' },
+  ]);
+  return (
+    <div className="col wrap">
+      <SortableList aria-label="Priorities" items={items} getKey={(i) => i.id} getLabel={(i) => i.t} onReorder={setItems}
+        renderItem={(i) => <div className="it">{i.t}<Badge tone={i.p === 'High' ? 'critical' : i.p === 'Med' ? 'caution' : 'neutral'}>{i.p}</Badge></div>} />
+      <p className="cap">Drag, or focus a row and press Space, then the arrow keys.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,87 @@
+# Sparkline
+
+A trend the size of a word: the last 30 days of a metric in a `DataTable` cell, a `PropertyList` value, a `Stat`, or a sentence. It says rising, falling, spiky or flat at a glance, beside the number that gives the detail (after Tufte's sparklines).
+
+**Why it's flat.** A sparkline is part of the record in the row it sits in, so it lies on the ground like every mark a chart draws: a 1.5px stroke with round joins, no fill under it, no shadow, no glow. There are no axes, gridlines or readout; the text beside it carries the numbers. The last point wears a 4px marker, so you can see where "now" is. `kind="bar"` draws flat bars 1px apart, standing on zero, for counts. A missing value (`null`) is a gap, never bridged. A normal range (`band`) is a flat band of `line` behind the marks.
+
+**Its size.** Its height is the line height of the text it sits beside (`1lh`), and it sits in that line. Its width is `5em` unless you give one.
+
+**Colour does one job.** By default it's `ink-muted`: context for the number beside it. `tone="data"` makes it `data-1`, when the sparkline *is* the series. `positive`, `caution` or `critical` only when the series means good or bad, and then the text beside it says so too ("Rising"), because colour never travels alone.
+
+**Accessibility.** It's `role="img"` with a generated label that says the trend in words: "Up 17% over 30 days, from 1.2K to 1.4K. Low 1.2K, high 1.5K." With `x` naming daily dates it says "days"; otherwise "values". With a `band` it counts the values outside it. An `aria-label` you pass goes first ("Signups, last 30 days. Up 17%…"); `summary` replaces the generated text. When the row already says it, pass `decorative` and it's hidden from assistive technology. It's never focusable. Under forced colours it's drawn in `CanvasText` and the band is a dashed outline; under `contrast="more"` the line is 2px.
+
+**Loading.** Pass `data` as it is: `undefined` while it loads, or a promise, and it's an imprint one line high and its own width (`Await`), which lands within the attention budget. A value that changes in a live table gets the row's afterglow, not a sparkline animation.
+
+**Props:** `data` (numbers, or records with `y`); `y`; `x` (a date key, for the label); `kind` (`'line'` or `'bar'`); `tone` (`'neutral'`, `'data'`, `'positive'`, `'caution'`, `'critical'`); `band` (`[low, high]`); `width`; `format` (for the label; default compact); `summary`; `decorative`; `locale`.
+
+**You provide:** the values, oldest first; the number they explain, beside them; and either an `aria-label` naming the measure or `decorative` when the row already says it all.
+
+```tsx
+<Sparkline data={daily} x="day" y="signups" aria-label="Signups, last 30 days" />
+<DataTable columns={[…, { key: 'trend', header: 'Last 30 days', cell: (r) => <Sparkline data={r.daily} decorative /> }]} rows={teams} />
+```
+
+- Do put the number it explains right beside it; a sparkline alone has no scale.
+- Do use `kind="bar"` for discrete counts (deploys per day), and the line for measures.
+- Do leave missing values as `null`.
+- Don't give it axes, a tooltip or a legend; when someone needs to read values, that's a `LineChart`.
+- Don't colour it with a status hue unless the series means good or bad, and say so in words beside it.
+- Don't compare sparklines in different rows as if they shared a scale: each is scaled to its own values.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Sparkline` as first used in its preview:
+
+```tsx
+import { Sparkline } from 'altitude-design';
+
+<Sparkline data={signups} x="day" y="signups" tone="data" width={120} aria-label="Signups, last 30 days" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`sp`, `row`, `big`, `note` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, DataTable, Sparkline } from 'altitude-design';
+
+const spDays = (vals) => vals.map((v, i) => ({ day: `2026-10-${String(i + 1).padStart(2, '0')}`, signups: v }));
+const signups = spDays([1200, 1180, 1230, 1260, 1210, 1290, 1310, 1280, 1300, 1350, 1330, 1290, 1340, 1370, 1360, 1320, 1380, 1400, 1390, 1360, 1410, 1430, 1390, 1420, 1450, 1410, 1380, 1420, 1440, 1400]);
+const teams = [
+  { id: 'core', name: 'Core', builds: [12, 14, 13, 15, 16, 18, 17, 19, 21, 20, 22, 24, 23, 25], errors: [0.4, 0.5, 0.4, 0.6, 0.5, 0.7, 0.9, 1.1, 1.0, 1.3, 1.5, 1.4, 1.8, 2.1] },
+  { id: 'web', name: 'Web', builds: [30, 28, 31, 27, 29, 26, 25, 27, 24, 23, 25, 22, 21, 20], errors: [1.2, 1.1, 1.3, 1.2, 1.1, 1.2, 1.0, 1.1, 1.2, 1.1, 1.0, 1.1, 1.2, 1.1] },
+  { id: 'data', name: 'Data', builds: [8, 9, null, null, 11, 10, 12, 14, 13, 15, 14, 16, 18, 17], errors: [2.0, 1.8, null, null, 1.6, 1.5, 1.6, 1.4, 1.3, 1.2, 1.3, 1.1, 1.0, 0.9] },
+];
+const latency = [182, 176, 190, 240, 178, 184, 171, 169, 175, 260, 181, 177, 174, 172, 179, 185, 176, 173];
+export default function App() {
+  const [slow, setSlow] = React.useState(undefined);
+  React.useEffect(() => { const t = setTimeout(() => setSlow([4, 6, 5, 8, 7, 9, 12, 11, 13, 12]), 2600); return () => clearTimeout(t); }, []);
+  return (
+    <div className="sp">
+      <section>
+        <h3>Beside a number</h3>
+        <div className="row"><span className="big">1,400</span><Sparkline data={signups} x="day" y="signups" tone="data" width={120} aria-label="Signups, last 30 days" /></div>
+        <p className="note">Signups, last 30 days. Up 17% from 1,200.</p>
+      </section>
+      <section>
+        <h3>In running text</h3>
+        <p>p95 latency <Sparkline data={latency} band={[160, 200]} format={(ms) => `${ms} ms`} aria-label="p95 latency, last 18 hours" /> spiked twice outside its normal range.</p>
+        <p>Deploys this week <Sparkline data={[3, 5, 2, 6, 4, 0, 1]} kind="bar" aria-label="Deploys per day" /> peaked on Thursday.</p>
+        <p className="note">Loading: <Sparkline data={slow} aria-label="Queue depth" /></p>
+      </section>
+      <section style={{ gridColumn: '1 / -1' }}>
+        <h3 id="sp-teams">In a table</h3>
+        <DataTable aria-labelledby="sp-teams" getRowId={(r) => r.id} rows={teams} columns={[
+          { key: 'name', header: 'Team' },
+          { key: 'builds', header: 'Builds per day', cell: (r) => <span className="row">{r.builds[r.builds.length - 1]}<Sparkline data={r.builds} decorative /></span> },
+          { key: 'errors', header: 'Error rate, 14 days', cell: (r) => {
+            const rising = r.errors[r.errors.length - 1] > r.errors[0] * 1.5;
+            return <span className="row">{r.errors[r.errors.length - 1]}%<Sparkline data={r.errors} tone={rising ? 'critical' : 'neutral'} format={(v) => `${v}%`} aria-label={`${r.name} error rate`} />{rising && <Badge tone="critical">Rising</Badge>}</span>;
+          } },
+        ]} />
+      </section>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,65 @@
+# SplitButton
+
+One action with its alternatives: "Save changes ▾" (Save as draft, Save and close), "Merge ▾" (squash, rebase), "Deploy ▾" (to staging, to production).
+
+**Elevation.** It's one pressable action, so it's one slab: **two faces sharing one wall**, parted by a 1px notch (`line-control`, or a mix of `on-accent` into the accent on a primary slab). Being one slab, it moves as one: pointing at either face lifts the whole slab, and pressing either presses it all, so the faces never stand at two heights with a step between them. Which face you're on, and so what a click does, is a tint on that face alone. Each face has its own focus ring around its face and wall. The menu floats at level 3 (`DropdownMenu`). Placing a `Button` and a `DropdownMenu` side by side reads as two slabs of different importance. A SplitButton reads as one action with options.
+
+**Loading.** `loading` holds the action face pressed with its label kept, as a `Button` does. The chevron stays usable.
+
+**Accessibility.** A [button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) and a [menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) in a `role="group"` named by the action ("Save changes"). There are two tab stops. Enter or Space on the chevron, or Alt+Down on the action, opens the menu. Name the chevron for what it offers (`menuLabel="More save options"`). Under forced colours each face has a 1px border, and the notch is `CanvasText`.
+
+**Props:** `label`; `variant` (`'primary' | 'secondary'`); `items` (`DropdownMenu` entries); `menuLabel` (default "More options"); `groupLabel` (when `label` isn't plain text); `onClick`, `loading`, `disabled`, `size` and the other `Button` props, which go to the action face.
+
+**You provide:** the default action and its alternatives. The default is what most people want most of the time.
+
+```tsx
+<SplitButton variant="primary" label="Save changes" onClick={save} menuLabel="More save options"
+  items={[
+    { label: 'Save as draft', onSelect: saveDraft },
+    { label: 'Save and close', onSelect: saveClose },
+  ]} />
+```
+
+- Do put the common case on the face and the rest in the menu.
+- Do mark a destructive alternative with `tone: 'critical'`.
+- Don't hide the default inside the menu, or offer only one alternative (use two buttons).
+- Don't nest a SplitButton in a `Toolbar`; its tools are ghosts.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`SplitButton` as first used in its preview:
+
+```tsx
+import { SplitButton } from 'altitude-design';
+
+<SplitButton label="Save changes" menuLabel="More save options" onClick={() => setSaid('Saved.')}
+  items={[{ label: 'Save as draft', onSelect: () => setSaid('Saved as a draft.') }, { label: 'Save and close', onSelect: () => setSaid('Saved and closed.') }]} />
+```
+
+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 { SplitButton } from 'altitude-design';
+
+export default function App() {
+  const [said, setSaid] = React.useState('');
+  const [deploying, setDeploying] = React.useState(false);
+  const deploy = (where) => { setSaid(`Deploying to ${where}…`); setDeploying(true); setTimeout(() => { setDeploying(false); setSaid(`Deployed to ${where}.`); }, 1600); };
+  return (
+    <div className="col">
+      <div className="row">
+        <SplitButton label="Save changes" menuLabel="More save options" onClick={() => setSaid('Saved.')}
+          items={[{ label: 'Save as draft', onSelect: () => setSaid('Saved as a draft.') }, { label: 'Save and close', onSelect: () => setSaid('Saved and closed.') }]} />
+        <SplitButton variant="secondary" label="Merge" menuLabel="More merge options" onClick={() => setSaid('Merged.')}
+          items={[{ label: 'Squash and merge', onSelect: () => setSaid('Squashed and merged.') }, { label: 'Rebase and merge', onSelect: () => setSaid('Rebased and merged.') }]} />
+        <SplitButton variant="secondary" label="Deploy" menuLabel="More deploy options" loading={deploying} onClick={() => deploy('staging')}
+          items={[{ label: 'Deploy to staging', onSelect: () => deploy('staging') }, { label: 'Deploy to production', onSelect: () => deploy('production'), tone: 'critical' }]} />
+      </div>
+      <p className="cap" role="status">{said || 'Each face lifts on its own. Alt+Down on an action opens its menu. While Deploy is loading, its chevron still works.'}</p>
+    </div>
+  );
+}
+```
+<!-- /example -->