altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,67 @@
+# NotificationCenter and NotificationList
+
+An inbox of what happened: mentions, assignments, approvals waiting, failed jobs, billing notices. A bell with a count opens the list, grouped by day, with Mark all as read, actions on each item, and a link to preferences.
+
+**Elevation.**
+- **The bell** is live: a ghost button. **Only its count floats** (`Badge variant="count"`), because a count wants you.
+- **The panel** floats at level 3 (a `Popover`), or at level 4 as a bottom `Sheet` on narrow screens.
+- **The list in it** lies on the ground: it's a record of what happened.
+- **Unread is a mark, not a height**: an `accent` dot, weight 600, and "Unread" in the item's name. Keeping unread items raised or tinted would make height mean "unread", which breaks "tiers carry meaning" (see Elevation, "States that don't rise").
+- **A new notification** arrives lifted and settles, as anything new does. An item that links lifts when pointed at. Mark all as read removes the dots with a cross-fade, and nothing travels.
+
+**Toasts are momentary; this is the record.** Use `toast` for "Saved". Use the notification center for things that wait for someone.
+
+**Accessibility.** The bell's name includes the unread count ("Notifications, 2 unread"). New notifications are announced politely and batched ("2 new notifications"), whether or not the panel is open. Mark all as read comes first in the panel. Items that link are links, and opening one marks it read and closes the panel. Item actions are buttons, and an unread item without a link gets "Mark as read". Under forced colours the dot keeps its colour (`forced-color-adjust: none`), and the word carries it too.
+
+**Props.** `NotificationCenter`: `items` (`{ id, title, body?, createdAt, read, href?, actions? }[]`), `onMarkRead(ids)`, `onMarkAllRead`, `preferencesHref`, `groupBy` (`'day' | 'none'`), `onOpen`, `mobileBreakpoint` (default 640). `NotificationList` is the same list without the bell, for a page of its own.
+
+**You provide:** the notifications and whether each is read, and what reading one does.
+
+```tsx
+<NotificationCenter items={notifications} onMarkRead={(ids) => markRead(ids)} onMarkAllRead={markAllRead}
+  preferencesHref="/settings/notifications" />
+```
+
+- Do let each notification lead to its subject (`href`).
+- Do keep an action on the item when it's waiting for someone ("Approve").
+- Don't raise or tint unread items.
+- Don't put momentary confirmations here; that's a toast.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`NotificationCenter` as first used in its preview:
+
+```tsx
+import { NotificationCenter } from 'altitude-design';
+
+<NotificationCenter items={items} onMarkRead={markRead} onMarkAllRead={() => setItems((xs) => xs.map((x) => ({ ...x, read: true })))} preferencesHref="#/settings/notifications" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `nc`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, NotificationCenter } from 'altitude-design';
+
+const ago = (m) => new Date(Date.now() - m * 60000);
+export default function App() {
+  const [items, setItems] = React.useState([
+    { id: 'n1', title: 'Maya mentioned you in Q4 planning', body: '“@you can you take the pricing section?”', createdAt: ago(5), read: false, href: '#/docs/q4' },
+    { id: 'n2', title: 'Theo asked to approve an expense', body: '€1,240 · Conference travel', createdAt: ago(48), read: false, actions: <Button size="sm" variant="secondary">Approve</Button> },
+    { id: 'n3', title: 'Export of 812 invoices is ready', createdAt: ago(60 * 3), read: true, href: '#/exports/7' },
+    { id: 'n4', title: 'Nightly sync failed for Salesforce', body: 'The token expired. Reconnect to resume.', createdAt: ago(60 * 27), read: true, href: '#/integrations' },
+  ]);
+  const markRead = (ids) => setItems((xs) => xs.map((x) => (ids.includes(x.id) ? { ...x, read: true } : x)));
+  return (
+    <div className="col">
+      <div className="nc">
+        <Button size="sm" variant="secondary" onClick={() => setItems((xs) => [{ id: 'n' + Date.now(), title: 'Ada assigned you “Billing page”', createdAt: new Date(), read: false, href: '#/issues/212' }, ...xs])}>Simulate a new notification</Button>
+        <NotificationCenter items={items} onMarkRead={markRead} onMarkAllRead={() => setItems((xs) => xs.map((x) => ({ ...x, read: true })))} preferencesHref="#/settings/notifications" />
+      </div>
+      <p className="cap">Unread is a dot and a bolder title, never a height. A new notification arrives lifted and settles, and is announced even while the panel is closed.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,66 @@
+# NumberInput
+
+A number field: seats on a plan, rate limits, retention days, prices, quantities. `parseNumber()` reads text the same way.
+
+**Elevation.** It's an opening, like `Input`: a well that shows its back wall while it's empty and whose floor rises flush once it holds a value. Invalid drops it to a trench on `critical-soft`. **The steppers are small raised slabs inside the well's end cap**, because you press them (push up, fill down). They're level 1 with a 1px wall, lift to 2 when pointed at, press flat, and lie flush in `ink-faint` at a limit. The unit ("days", "€", "%") sits beside the number in `ink-muted`. Editing isn't a change to the record, so nothing glows while you type or step.
+
+**Parsing.** What you type is read in the locale's own way: in `de-DE`, "1.250,50" is 1250.5 and "1,5" is 1.5. Arabic-Indic, Persian, Devanagari, Bengali and full-width digits are read too. The value is committed on blur, on Enter and on every step, and it's clamped to `min` and `max` when committed, so it can't leave its range. Nonsense ("abc") keeps the last good value. Steps land on the grid that starts at `min` (or 0), without binary-fraction drift (0.1 + 0.2 is 0.3).
+
+**Formats.** `format` takes `Intl.NumberFormat` options. `{ style: 'unit', unit: 'day' }` puts "days" beside the number. `{ style: 'currency', currency: 'EUR' }` puts the currency where the locale puts it. With `{ style: 'percent' }` the value is a fraction (0.1 is shown as "10 %").
+
+**Accessibility.** The [spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/): `role="spinbutton"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and an `aria-valuetext` that includes the unit ("30 days"). Up and Down step, Shift+Up/Down and PageUp/PageDown move ten steps, and Home and End go to `min` and `max`. The steppers aren't tab stops (`tabIndex={-1}`, as the APG says), so name them for what they change (`incrementLabel="Increase seats"`). The scroll wheel never changes the value unless you set `wheel`, and then only while the field is focused. Under forced colours the steppers have a 1px border. Under `contrast="more"` their wall is `ink`.
+
+**Props:** `value`, `defaultValue` (`number | null`), `onValueChange`; `min`, `max`, `step` (default 1); `format`; `locale`; `invalid`; `size`; `wheel`; `incrementLabel`, `decrementLabel`; and the input's own attributes.
+
+**Target size.** The two steppers sit side by side, down then up, each 24×24 (WCAG 2.5.8): stacked, two 15px steppers could never each reach 24px. Under a coarse pointer each reaches 44px tall through a transparent hit area. The arrow keys still step, and Page Up and Page Down step by ten.
+
+**You provide:** the range, the step, the unit (in `format`) and a label (with `Field`).
+
+```tsx
+<Field label="Seats">
+  <NumberInput value={seats} onValueChange={setSeats} min={1} max={500} incrementLabel="Increase seats" decrementLabel="Decrease seats" />
+</Field>
+<NumberInput value={days} onValueChange={setDays} format={{ style: 'unit', unit: 'day', unitDisplay: 'long' }} />
+```
+
+- Do give it `min` and `max` whenever the value has limits, and say them in the hint.
+- Do put the unit in `format`, not in the label, so it's spoken with the value.
+- Don't use it for identifiers that happen to be digits (a ZIP code, a card number); that's an `Input`.
+- Don't use it to choose roughly within a range; that's a `Slider`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`NumberInput` as first used in its preview:
+
+```tsx
+import { NumberInput } from 'altitude-design';
+
+<NumberInput value={seats} onValueChange={setSeats} min={1} max={500} incrementLabel="Increase seats" decrementLabel="Decrease seats" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `ni`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Field, NumberInput } from 'altitude-design';
+
+export default function App() {
+  const [seats, setSeats] = React.useState(12);
+  const [days, setDays] = React.useState(30);
+  const [price, setPrice] = React.useState(1250.5);
+  const [rate, setRate] = React.useState(null);
+  return (
+    <div className="col">
+      <div className="ni">
+        <Field label="Seats" hint="1 to 500"><NumberInput value={seats} onValueChange={setSeats} min={1} max={500} incrementLabel="Increase seats" decrementLabel="Decrease seats" /></Field>
+        <Field label="Keep logs for"><NumberInput value={days} onValueChange={setDays} min={1} max={365} format={{ style: 'unit', unit: 'day', unitDisplay: 'long' }} /></Field>
+        <Field label="Preis pro Monat" hint="German: type 1.250,50"><NumberInput value={price} onValueChange={setPrice} min={0} step={0.5} locale="de-DE" format={{ style: 'currency', currency: 'EUR' }} /></Field>
+        <Field label="Sampling rate"><NumberInput value={rate} onValueChange={setRate} min={0} max={1} step={0.05} format={{ style: 'percent' }} placeholder="10" /></Field>
+      </div>
+      <p className="cap">Arrow keys step (Shift for ten); Home and End go to the limits; a stepper at its limit lies flat. Values clamp to their range when you leave the field.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,74 @@
+# PageHeader
+
+The block every page opens with: breadcrumb, title, a line of description, the page's actions, and sometimes tabs.
+
+**Elevation.** The page's name is the record, so the block lies on the ground. Only its actions are live: secondaries at level 1, ghosts at 0, and **one primary at level 2, in its own slot**. "The primary action rests at level 2" (law 1) becomes structural: `primary` takes one element, and a `variant="primary"` button put in `actions` logs a development warning naming law 1. Actions that don't need to be seen go in `overflow`, a "More actions" menu (`DropdownMenu`, level 3). With `sticky`, the header stays at the top and **rises one level when content passes under it** (`surface-raised`, `elev-1`), as `ScrollArea`'s header does.
+
+**Layout.** The breadcrumb sits above, the title and description on the left, and the actions on the right (the primary last, nearest the reading edge). Tabs go underneath. Everything wraps on narrow screens. Set `--alt-page-pad` to the page's side padding (`AppShell` does) and the header reaches through it, so a sticky header's rise spans the page.
+
+**Accessibility.** A `<header>` with the page's `h1` (`PageHeaderTitle`). The tab order is breadcrumb, actions, tabs. "More actions" is a [menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/). Under forced colours a risen sticky header gets a bottom border.
+
+**Props.** `PageHeader`: `breadcrumb`, `primary`, `actions`, `overflow` (`DropdownMenu` entries), `tabs`, `sticky`. Inside it go `PageHeaderTitle` (an `h1`) and `PageHeaderDescription`.
+
+**You provide:** the page's name, what it's for in one line, and its actions, with the one that matters most as `primary`.
+
+```tsx
+<PageHeader sticky
+  breadcrumb={<Breadcrumb items={[{ label: 'Settings', href: '/settings' }, { label: 'Members' }]} />}
+  primary={<Button variant="primary">Invite members</Button>}
+  actions={<Button variant="secondary">Export list</Button>}
+  overflow={[{ label: 'Download audit log', onSelect: download }]}>
+  <PageHeaderTitle>Members</PageHeaderTitle>
+  <PageHeaderDescription>People who can see and edit this workspace.</PageHeaderDescription>
+</PageHeader>
+```
+
+- Do give a page at most one primary action; put the rest in `actions` or `overflow`.
+- Do keep the description to one line about what the page is for.
+- Don't put a PageHeader inside a `Card`; that's `CardHeader`.
+- Don't make the whole header a raised card. It lies on the ground, and only rises while content passes under it.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`PageHeader` as first used in its preview:
+
+```tsx
+import { Breadcrumb, Button, PageHeader, PageHeaderDescription, PageHeaderTitle, Tabs, TabsList, TabsTrigger } from 'altitude-design';
+
+<PageHeader sticky
+  breadcrumb={<Breadcrumb items={[{ label: 'Settings', href: '#/settings' }, { label: 'Members' }]} />}
+  primary={<Button variant="primary">Invite members</Button>}
+  actions={<Button variant="secondary">Export list</Button>}
+  overflow={[{ label: 'Download audit log' }, { label: 'Members settings' }]}
+  tabs={<Tabs variant="segmented" value={tab} onValueChange={setTab}><TabsList aria-label="Members sections"><TabsTrigger value="members">Members</TabsTrigger><TabsTrigger value="invites">Invitations</TabsTrigger><TabsTrigger value="roles">Roles</TabsTrigger></TabsList></Tabs>}>
+  <PageHeaderTitle>Members</PageHeaderTitle>
+  <PageHeaderDescription>People who can see and edit this workspace.</PageHeaderDescription>
+</PageHeader>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`ph`, `rows` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Breadcrumb, Button, PageHeader, PageHeaderDescription, PageHeaderTitle, Tabs, TabsList, TabsTrigger } from 'altitude-design';
+
+export default function App() {
+  const [tab, setTab] = React.useState('members');
+  return (
+    <div className="ph">
+      <PageHeader sticky
+        breadcrumb={<Breadcrumb items={[{ label: 'Settings', href: '#/settings' }, { label: 'Members' }]} />}
+        primary={<Button variant="primary">Invite members</Button>}
+        actions={<Button variant="secondary">Export list</Button>}
+        overflow={[{ label: 'Download audit log' }, { label: 'Members settings' }]}
+        tabs={<Tabs variant="segmented" value={tab} onValueChange={setTab}><TabsList aria-label="Members sections"><TabsTrigger value="members">Members</TabsTrigger><TabsTrigger value="invites">Invitations</TabsTrigger><TabsTrigger value="roles">Roles</TabsTrigger></TabsList></Tabs>}>
+        <PageHeaderTitle>Members</PageHeaderTitle>
+        <PageHeaderDescription>People who can see and edit this workspace.</PageHeaderDescription>
+      </PageHeader>
+      <div className="rows">{Array.from({ length: 10 }, (_, i) => <div key={i} />)}</div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,58 @@
+# Pagination
+
+Moves through pages of a collection the server pages: invoices, members, audit events.
+
+**Elevation: one thumb that travels.** The page numbers sit in a trench (`surface-well`), and **the current page is one raised thumb that travels to it** on `ease-glide`, as `RadioGroup`'s does. That reads as "you are here, among these", where a row of buttons reads as "any of these does something". Pointing at another page shows a ghost of the thumb there (feedforward). While the next page loads (`loading`), the thumb is held pressed until the rows arrive. Previous and Next are ghost buttons, flush and `ink-faint` at the ends.
+
+**Pages.** It shows the first page, the last, and the current one with `siblings` either side, with "…" where pages are skipped. A gap of a single page shows that page instead, because "…" would take as much room. `pageRange()` gives the same list. **Cursor paging:** leave out `pageCount` and you get Previous, Next (disabled once `hasNext` is false) and "Page 3".
+
+**Summary.** With `total` and `pageSize` it says "41–60 of 214 invoices" (`noun`) in a polite live region, so the change is announced after a page change.
+
+**Accessibility.** A `nav` labelled "Pagination", with links when `hrefFor` gives pages URLs, or buttons otherwise. **They stay in plain Tab order:** these are links drawn like a radio group, not a radio group, so there's no roving focus. The current page has `aria-current="page"`. Pages are named "Page 3", and the steps "Previous page" and "Next page", with `aria-disabled` at the ends. Below 480px the steps show only their chevrons. Under forced colours the trench is dashed and the thumb has a 1px border. Under `contrast="more"` the thumb gets a 2px slab. Under reduced motion the thumb appears in place.
+
+**Props:** `page` (from 1); `pageCount`; `onPageChange`; `total`, `pageSize`, `noun`; `hrefFor`; `hasNext`; `siblings` (default 1); `loading`; `locale`; `aria-label`.
+
+**You provide:** the current page, how many there are (or whether there's a next one), and what happens on a change.
+
+```tsx
+<Pagination page={page} pageCount={11} onPageChange={setPage} total={214} pageSize={20} noun="invoices" />
+<Pagination page={page} onPageChange={setPage} hasNext={!!cursor.next} />   // cursor paging
+```
+
+- Do use `hrefFor` when pages have URLs, so they can be opened in a new tab.
+- Do show the summary; "Page 3 of 11" says less than "41–60 of 214".
+- Don't page short lists; show them whole.
+- Don't use it for steps in a process; that's a `Stepper`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Pagination` as first used in its preview:
+
+```tsx
+import { Pagination } from 'altitude-design';
+
+<Pagination page={page} pageCount={11} onPageChange={go} total={214} pageSize={20} noun="invoices" loading={loading} />
+```
+
+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 { Pagination } from 'altitude-design';
+
+export default function App() {
+  const [page, setPage] = React.useState(3);
+  const [loading, setLoading] = React.useState(false);
+  const [cursor, setCursor] = React.useState(1);
+  const go = (p) => { setPage(p); setLoading(true); setTimeout(() => setLoading(false), 500); };
+  return (
+    <div className="col">
+      <Pagination page={page} pageCount={11} onPageChange={go} total={214} pageSize={20} noun="invoices" loading={loading} />
+      <Pagination page={cursor} onPageChange={setCursor} hasNext={cursor < 4} aria-label="Audit log pages" />
+      <p className="cap">The current page is a raised thumb in the trench; it's held pressed while the next page loads. Without a page count it's Previous, Next and "Page 3".</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,70 @@
+# PasswordInput
+
+A password field: signing in, signing up, a reset, "change password" in settings.
+
+**Elevation.** It's an `Input`, so it's an opening that fills. In its end cap sits a reveal `Toggle`. While the password shows, the toggle is on: sunk and filled, as every Toggle is. Its name ("Show password") never changes; `aria-pressed` says whether it's on.
+
+**Strength is a reading.** When you pass `strength`, the score (0–4, from your scoring: zxcvbn or your own rules) is shown as a `Meter`: a flush track with flat ink, never `Progress`'s raised fill, because a password's strength is a reading, not a task moving toward done (see [Charts](../../visual/Charts.md)). The word ("Weak", "Good", "Strong") sits beside the label and carries the meaning. The fill stays the meter's own colour: Meter's thresholds mean "higher is worse", which is backwards for strength.
+
+**Requirements** are stamped as they're met, like a done `Checklist` item: muted, with a check pressed into a small well. Unmet ones keep an empty ring.
+
+**Caps Lock.** While the field is focused and Caps Lock is on, a caption with an icon says "Caps Lock is on".
+
+**Accessibility.** A plain `<input type="password">`, with `autocomplete="new-password"` when there's a strength meter or requirements, and `"current-password"` otherwise (pass `autoComplete` to say otherwise). The reveal toggle is a separate tab stop after the field, and revealing doesn't move focus. Strength, requirements and the caps-lock notice describe the field (`aria-describedby`). Strength and unmet requirements are announced politely once typing pauses (0.9s), not on every key. The meter's value text is the word. Under forced colours the requirement stamps and the caps-lock icon are `CanvasText`.
+
+**Props:** `strength` (`(value) => 0–4`); `strengthLabels`; `requirements` (`{ label, test }[]`); `revealLabel` (default "Show password"); and every `Input` prop except `type` and `trailing`.
+
+**You provide:** the scoring and the rules, when people are creating a password. For signing in, nothing more than a label.
+
+```tsx
+<Field label="New password">
+  <PasswordInput
+    strength={(v) => zxcvbn(v).score}
+    requirements={[
+      { label: 'At least 12 characters', test: (v) => v.length >= 12 },
+      { label: 'Not a common password', test: notCommon },
+    ]}
+  />
+</Field>
+```
+
+- Do let people reveal what they typed; masking alone causes errors.
+- Do say your rules before someone breaks them, as requirements.
+- Don't draw strength as a progress bar.
+- Don't show a strength meter when signing in; it's for creating a password.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`PasswordInput` as first used in its preview:
+
+```tsx
+import { PasswordInput } from 'altitude-design';
+
+<PasswordInput defaultValue="correct horse" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`pw` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Field, PasswordInput } from 'altitude-design';
+
+// A stand-in score: in an app this would be zxcvbn or your own rules.
+const score = (v) => Math.min(4, [v.length >= 8, v.length >= 12, /[A-Z]/.test(v) && /[a-z]/.test(v), /\d/.test(v), /[^\w\s]/.test(v)].filter(Boolean).length - (v.length < 8 ? 1 : 0));
+const common = ['password', 'password1', '12345678', 'qwerty123'];
+export default function App() {
+  return (
+    <div className="pw">
+      <Field label="Password"><PasswordInput defaultValue="correct horse" /></Field>
+      <Field label="New password">
+        <PasswordInput defaultValue="Glacier7" strength={score}
+          requirements={[
+            { label: 'At least 12 characters', test: (v) => v.length >= 12 },
+            { label: 'Not a common password', test: (v) => v.length > 0 && !common.includes(v.toLowerCase()) },
+          ]} />
+      </Field>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,68 @@
+# PermissionMatrix
+
+Roles against permissions: "Admins can manage billing, Members can invite, Viewers can only read". The same grid serves notification preferences (events against channels).
+
+**Elevation.** The grid is settled: the record of who can do what, on the ground with `line` dividers.
+- **An editable grant is a choice**, built like a `Checkbox`: an empty trench that the accent pours into when granted.
+- **An inherited or fixed grant is already decided**, so it's a flush stamped check (or a dash when not granted), muted, like a done `Checklist` item. It's pressed into the record, not drawn as a disabled checkbox, because it isn't unavailable. A `locked` role (an owner) has every permission, stamped.
+- **The active cell** is a 2px `accent-ink` ring, never a height, as in `DataGrid`.
+- **Saving:** a toggled cell whose `onChange` returns a promise hovers as pending until it settles, then takes the afterglow. A rejection reverts it.
+
+**Accessibility.** The [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) with checkbox cells. Arrow keys move, Home and End go along the row, Ctrl+Home and Ctrl+End go to the corners, and Space or Enter toggles. Each cell reads "Manage billing, Admin, checked". A stamped cell is `aria-readonly` and says why ("Granted, inherited from Everyone", "Always granted to Owner"): it's reachable, and toggling it says it can't be changed here. Changes are announced ("Create projects granted to Viewer"). Group headings head their rows. Under forced colours the ring is `Highlight` and stamped cells keep their glyph. Under `contrast="more"` the ring is 3px.
+
+**Props:** `roles` (`{ id, name, locked? }[]`); `permissions` (`{ id, name, group? }[]`); `value` (`{ [roleId]: { [permissionId]: boolean } }`); `inherited(roleId, permissionId)` (→ `{ granted, from }` or undefined); `onChange(roleId, permissionId, granted)` (may return a promise); `aria-label`.
+
+**You provide:** the roles, the permissions, who has what, and where inherited grants come from.
+
+```tsx
+<PermissionMatrix aria-label="Role permissions"
+  roles={[{ id: 'owner', name: 'Owner', locked: true }, { id: 'admin', name: 'Admin' }]}
+  permissions={[{ id: 'billing.manage', name: 'Manage billing', group: 'Billing' }]}
+  value={grants} inherited={(role, perm) => inheritFrom(role, perm)}
+  onChange={(role, perm, granted) => saveGrant(role, perm, granted)} />
+```
+
+- Do say where an inherited grant comes from.
+- Do return a promise from `onChange` so a cell shows it's saving.
+- Don't draw inherited grants as disabled checkboxes.
+- Don't lift the active cell; it's a ring.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`PermissionMatrix` as first used in its preview:
+
+```tsx
+import { PermissionMatrix } from 'altitude-design';
+
+<PermissionMatrix aria-label="Role permissions" roles={roles} permissions={perms} value={grants} inherited={inherited}
+  onChange={(role, perm, on) => new Promise((r) => setTimeout(() => { setGrants((g) => ({ ...g, [role]: { ...g[role], [perm]: on } })); r(); }, 600))} />
+```
+
+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 { PermissionMatrix } from 'altitude-design';
+
+const roles = [{ id: 'owner', name: 'Owner', locked: true }, { id: 'admin', name: 'Admin' }, { id: 'member', name: 'Member' }, { id: 'viewer', name: 'Viewer' }];
+const perms = [
+  { id: 'billing.view', name: 'View invoices', group: 'Billing' }, { id: 'billing.manage', name: 'Manage billing', group: 'Billing' },
+  { id: 'members.invite', name: 'Invite members', group: 'Members' }, { id: 'members.remove', name: 'Remove members', group: 'Members' },
+  { id: 'projects.create', name: 'Create projects', group: 'Projects' }, { id: 'projects.view', name: 'View projects', group: 'Projects' },
+];
+export default function App() {
+  const [grants, setGrants] = React.useState({ admin: { 'billing.view': true, 'billing.manage': true, 'members.invite': true, 'members.remove': true, 'projects.create': true },
+    member: { 'members.invite': true, 'projects.create': true }, viewer: {} });
+  // Everyone can view projects; admins inherit invoices from Billing admins in this example.
+  const inherited = (role, perm) => (perm === 'projects.view' ? { granted: true, from: 'Everyone' } : role === 'viewer' && perm.startsWith('billing') ? { granted: false, from: 'Guest policy' } : undefined);
+  return (
+    <div className="col">
+      <PermissionMatrix aria-label="Role permissions" roles={roles} permissions={perms} value={grants} inherited={inherited}
+        onChange={(role, perm, on) => new Promise((r) => setTimeout(() => { setGrants((g) => ({ ...g, [role]: { ...g[role], [perm]: on } })); r(); }, 600))} />
+      <p className="cap">Editable grants are checkboxes. Owner's and inherited grants are stamped into the record: they're decided, not unavailable. Arrow keys move; Space toggles.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,54 @@
+# Pile
+
+Shows a group of items as a stack. Its thickness says roughly how many; click it and the items fan out over the page.
+
+**Closed.** The top card is raised (level 1). Beneath it sit 0–3 sheets: none for one item, one for 2–3, two for 4–9, three for 10 or more. Thickness is read in bins, so the count badge carries the number. On hover or focus the top lifts and the sheets beneath fan a little, a preview of what's underneath; nothing moves before the pointer is on it.
+
+**Open.** Give the pile `items` and `renderItem` and its top card becomes a toggle. Clicking it (or Enter/Space) slides the items out from under the top card, one after another, into a column that **floats over the page below**: nothing on the page moves. Each item is its own card with its own shadow (`elev-2`, `elev-3` under the pointer); the scroll area itself has none, and its top and bottom edges fade out rather than cutting the shadows off. Click an item to choose it (`onSelect`). Click the top again, press Escape or click anywhere else and the items slide back under. Long piles scroll after `maxHeight`.
+
+**You provide:** `items`, `renderItem(item, { index })`, `onSelect`, the top card's content as children, optionally `getKey`, `maxHeight` and `open`/`onOpenChange` (for example, to close it after a choice). For a pile that only shows quantity, pass `count` instead of `items`.
+
+- Leave room below a pile, or near the bottom of the viewport the list may run off-screen.
+- Use piles for collections people triage: review queues, inboxes, stacks of drafts.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Pile` as first used in its preview:
+
+```tsx
+import { Pile } from 'altitude-design';
+
+<Pile count={1} className="p"><div className="face"><b>Drafts</b><span>1 document</span></div></Pile>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `piles`, `p`, `face`, `wide`, `doc`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Pile } from 'altitude-design';
+
+const docs = [
+  ['Pricing page copy', 'Three tiers, annual toggle, FAQ.', 'Mara · 2h'], ['Onboarding emails', 'Five-step drip for new workspaces.', 'Jon · yesterday'],
+  ['Q4 launch plan', 'Milestones, owners and risks.', 'Lena · Mon'], ['Release notes 2.4', 'Faster cold starts, new regions.', 'Sam · Mon'],
+  ['Support macros', 'Twelve canned replies, reviewed.', 'Ivy · last week'], ['Brand voice', 'How we sound, with examples.', 'Ada · last week'],
+  ['Security review', 'Findings from the October audit.', 'Theo · Oct 2'],
+];
+export default function App() {
+  const [picked, setPicked] = React.useState(null);
+  return (
+    <div className="col">
+      <div className="piles">
+        <Pile count={1} className="p"><div className="face"><b>Drafts</b><span>1 document</span></div></Pile>
+        <Pile count={3} interactive className="p"><div className="face"><b>Approved</b><span>3 documents</span></div></Pile>
+        <Pile items={docs} className="p wide" onSelect={(d) => setPicked(d[0])} defaultOpen maxHeight={300}
+          renderItem={([t, d, m]) => <div className="doc"><b>{t}</b><span>{d}</span><small>{m}</small></div>}>
+          <div className="face"><b>In review</b><span>{docs.length} documents · click to fan out</span></div>
+        </Pile>
+      </div>
+      <p className="cap">{picked ? `Opened “${picked}”.` : 'One sheet for 2–3 items, two for 4–9, three for 10+; the badge carries the number. Click a pile with items and they fan out over the page below it.'}</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,62 @@
+# PlanPicker
+
+Choose a plan (Free, Pro, Business) in sign-up, upgrade and downgrade flows, with a Monthly / Annually switch, prices, and what each plan includes.
+
+**Elevation: one choice, one mark.** "A radio group is one switch with several positions, so its single thumb slides to the chosen option." The plan cards are positions in one group: they lie flush on the ground with a `line` rim, and **one raised mark travels to the chosen card's corner** on `ease-glide`. The chosen card also takes an `accent` rim. Pointing at another card shows a ghost of the mark there.
+
+**No lifted "most popular" card.** Pricing pages usually raise and glow the plan they want you to pick. Marketing emphasis isn't importance *right now*, so it isn't height. **"Recommended" and "Current plan" are flush `Badge` plates.** The only level-2 slab is your Continue button beside the picker (law 1), and its label should name the outcome ("Continue to Pro").
+
+**Prices** come in minor units and are formatted by `FormattedNumber`, so changing the period cross-fades them and never counts. Annual prices are shown per month, "billed annually". A plan with `price: null` says "Contact sales". A plan with `unavailable` can't be chosen and says why.
+
+**Accessibility.** A [radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/): one tab stop, and arrows move and choose (skipping unavailable plans). Each plan reads its name, price and period ("Pro, €20.00 per seat per month, billed annually, recommended"), with its features as the description. The period switch is a single-choice `ToggleGroup`. Under forced colours the chosen card has a 2px border and the mark keeps a `CanvasText` outline. Under `contrast="more"` the mark gets a hard slab. Under reduced motion the mark appears in place.
+
+**Props:** `plans` (`{ id, name, description?, price ({ month, year } | number | null), currency?, unit?, features?, unavailable? }[]`); `value`, `defaultValue`, `onValueChange`; `current`; `recommended`; `period`, `onPeriodChange`; `locale`; `aria-label`.
+
+**You provide:** the plans and their prices, the current plan, and the Continue button. The flow around it (proration, downgrade consequences) is the billing pattern.
+
+```tsx
+<PlanPicker plans={plans} value={plan} onValueChange={setPlan} current="free" recommended="pro" period={period} onPeriodChange={setPeriod} />
+<Button variant="primary" onClick={next}>Continue to {planName}</Button>
+```
+
+- Do name the outcome on the Continue button.
+- Do say why a plan can't be chosen.
+- Don't lift or glow a recommended plan.
+- Don't animate prices counting up when the period changes.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`PlanPicker` as first used in its preview:
+
+```tsx
+import { PlanPicker } from 'altitude-design';
+
+<PlanPicker plans={plans} value={plan} onValueChange={setPlan} current="free" recommended="pro" period={period} onPeriodChange={setPeriod} locale="en-IE" aria-label="Choose a plan" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, PlanPicker } from 'altitude-design';
+
+const plans = [
+  { id: 'free', name: 'Free', price: 0, currency: 'EUR', unit: 'per seat', features: ['3 projects', 'Community support'] },
+  { id: 'pro', name: 'Pro', price: { month: 2400, year: 2000 }, currency: 'EUR', unit: 'per seat', features: ['Unlimited projects', 'SAML SSO', 'Audit log'] },
+  { id: 'business', name: 'Business', price: { month: 4800, year: 4000 }, currency: 'EUR', unit: 'per seat', features: ['Everything in Pro', 'Custom roles', '99.9% uptime SLA'] },
+  { id: 'enterprise', name: 'Enterprise', price: null, unavailable: 'Contact sales for more than 500 seats.' },
+];
+export default function App() {
+  const [plan, setPlan] = React.useState('free');
+  const [period, setPeriod] = React.useState('year');
+  const name = plans.find((p) => p.id === plan).name;
+  return (
+    <div className="col">
+      <PlanPicker plans={plans} value={plan} onValueChange={setPlan} current="free" recommended="pro" period={period} onPeriodChange={setPeriod} locale="en-IE" aria-label="Choose a plan" />
+      <div className="row"><Button variant="primary" disabled={plan === 'free'}>{plan === 'free' ? 'You\'re on Free' : `Continue to ${name}`}</Button></div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,48 @@
+# Popover
+
+Shows rich, interactive content anchored to a trigger, floating at level 3.
+
+It grows from the trigger's edge (`transform-origin` on that side), rising 6px from 96% scale while its shadow climbs to `elev-3`. Focus moves to the first control inside; Escape or a click outside closes it and returns focus to the trigger.
+
+**On a narrow screen.** It opens where its `side` and `align` put it, then shifts sideways to stay 8px inside the screen, and it's never wider than the screen less 16px.
+
+**You provide:** `trigger` (a Button), children (padding is `space-4`), `side`, `align`, an `aria-label`, and `open`/`onOpenChange` if you need control.
+
+- Do use it for small forms and pickers that belong to one control.
+- Don't use it for a decision that blocks the page; that's a Dialog.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Popover` as first used in its preview:
+
+```tsx
+import { Button, Field, Input, Popover } from 'altitude-design';
+
+<Popover defaultOpen aria-label="Share" trigger={<Button>Share</Button>}>
+  <div className="col" style={{ width: 280, gap: 12 }}>
+    <b style={{ font: '600 14px/20px var(--font-sans)' }}>Invite to project</b>
+    <Field label="Email address"><Input size="sm" type="email" placeholder="name@company.com" /></Field>
+    <div className="row" style={{ justifyContent: 'flex-end', gap: 8 }}><Button size="sm" variant="primary">Send invite</Button></div>
+  </div>
+</Popover>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Button, Field, Input, Popover } from 'altitude-design';
+
+export default function App() {
+  return (
+    <Popover defaultOpen aria-label="Share" trigger={<Button>Share</Button>}>
+      <div className="col" style={{ width: 280, gap: 12 }}>
+        <b style={{ font: '600 14px/20px var(--font-sans)' }}>Invite to project</b>
+        <Field label="Email address"><Input size="sm" type="email" placeholder="name@company.com" /></Field>
+        <div className="row" style={{ justifyContent: 'flex-end', gap: 8 }}><Button size="sm" variant="primary">Send invite</Button></div>
+      </div>
+    </Popover>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,41 @@
+# Progress
+
+Shows how far along a task is: a raised fill rising out of a trench.
+
+Determinate progress glides between values on `ease-glide` (`dur-travel-3`). Without a `value` it's indeterminate: a third-width fill travels across the track every `dur-sweep`, and stops under reduced motion.
+
+**You provide:** `value` (0–`max`) or nothing, and an `aria-label` or a visible label nearby.
+
+- Do switch from indeterminate to determinate as soon as you know the total.
+- Don't use it for a reading such as storage used of a quota: that's the record, not a task, so it's a [`Meter`](../Meter/README.md).
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Progress` as first used in its preview:
+
+```tsx
+import { Progress } from 'altitude-design';
+
+<Progress value={v} aria-label="Upload" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `wrap`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Progress } from 'altitude-design';
+
+export default function App() {
+  const [v, setV] = React.useState(20);
+  React.useEffect(() => { const t = setInterval(() => setV((x) => (x >= 100 ? 8 : x + 23)), 1100); return () => clearInterval(t); }, []);
+  return (
+    <div className="col wrap">
+      <Progress value={v} aria-label="Upload" />
+      <Progress aria-label="Loading" />
+      <p className="cap">Determinate glides between values; indeterminate travels.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->