altitude-design 0.3.2 → 0.4.1

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

@@ -0,0 +1,71 @@
+# Alert
+
+Tells the person something about the current context. An alert is **a sheet laid on the page**: it rests on the ground, you can see its paper edge and the contact shadow under it, and it never floats. When it asks the person to act it becomes a raised card.
+
+**Page banners.** `placement="page"` lays the alert edge to edge across the top of the app or page: "Your trial ends in 3 days", "Scheduled maintenance Sunday 02:00 UTC", "We're seeing delays in email delivery". It has no side rounding and no side edges, and its text wraps on narrow screens. The elevation rule is the same at page scope: one that informs is a flat sheet, and one that asks for action is raised. `sticky` keeps it at the top while the page scrolls. It sits in a `region` named by its title, so it can be found and skipped. `dismissLabel` gives the dismiss button words ("Remind me tomorrow"), and dismissing moves focus to the page's `main`. Several page banners go in `AlertStack placement="page"`, most severe first. Put a banner above `AppShell`, or at the top of the page.
+
+- `variant="flat"` (default): a thin sheet in the tone's `-soft` colour (neutral is `surface-raised`), with a tone-tinted hairline, a 1px paper edge and a contact shadow. It informs.
+- `variant="raised"`: a card at level 2 with the sheen of something you can act on, the icon in the tone colour. Use it when the alert has an `action` or blocks progress.
+- `onDismiss`: adds a dismiss button. Dismissing **lifts the sheet off the page**: it rises 8px as its shadow spreads, fades, and then the gap closes; `onDismiss` is called once it's gone.
+- `settle`: an afterglow when the alert first appears or changes.
+
+`critical` renders `role="alert"`; the others use `role="status"`.
+
+## AlertStack
+
+Several alerts as a **stack of sheets**, the same language as `Pile`. The first alert lies on top; up to two more peek out beneath it, each tinted by its own tone, so you can see what kind of news is waiting without reading it. A floating "+N more" sits on the stack's edge. Opening it fans the alerts out into a column, one after another; "Show less" tucks them back. Dismiss the top alert and it lifts off while the next one comes up from under it.
+
+**You provide:** for `Alert`, `tone`, `title`, optional body as children, optional `action` (a small Button), `variant`, `onDismiss`. For `AlertStack`, keyed `Alert` children in order of importance, and optionally `expanded`/`onExpandedChange`, `moreLabel`, `lessLabel`.
+
+- Keep it to a title and one sentence.
+- Generic action-completion messages belong in a Toast. When an action removes an item from a list (‘Brand guidelines.pdf archived’ with Undo), don't add an Alert below the list: show the result in the item's own slot with [RemovalReceipt](../RemovalReceipt/README.md), then hand Undo to a Toast. Keep a durable recovery destination such as Archived → Restore; a timed notification must not be the only recovery path. See [Actions in place](../../visual/ActionsInPlace.md).
+- An Alert still suits a failure or a changed record that can't be shown beside its item (it's outside the current view). Key it by its operation ID, and let its delayed `onDismiss` clear state only when that ID is still current. Dismissing an old Alert must not hide a newer action's feedback.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Alert` as first used in its preview:
+
+```tsx
+import { Alert, Button } from 'altitude-design';
+
+<Alert placement="page" tone="caution" variant="raised" title="Your trial ends in 3 days" action={<Button variant="primary" size="sm">Choose a plan</Button>}
+onDismiss={() => setTrial(false)} dismissLabel="Remind me tomorrow" />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `frame`, `cap`, `wrap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Alert, AlertStack, Button } from 'altitude-design';
+
+const queue = [
+  { id: 'b', tone: 'critical', title: 'Build failed', body: 'Missing environment variable DATABASE_URL.' },
+  { id: 'c', tone: 'caution', title: 'Certificate renews in 3 days', body: 'Renewal is automatic; nothing to do.' },
+  { id: 'd', tone: 'accent', title: 'New region available', body: 'Frankfurt (eu-central-2) is now open.' },
+];
+export default function App() {
+  const [items, setItems] = React.useState(queue);
+  React.useEffect(() => { if (!items.length) { const t = setTimeout(() => setItems(queue), 900); return () => clearTimeout(t); } }, [items]);
+  const [trial, setTrial] = React.useState(true);
+  return (
+    <div className="col">
+      <div className="frame">
+        {trial && <Alert placement="page" tone="caution" variant="raised" title="Your trial ends in 3 days" action={<Button variant="primary" size="sm">Choose a plan</Button>}
+          onDismiss={() => setTrial(false)} dismissLabel="Remind me tomorrow" />}
+        <Alert placement="page" title="We're seeing delays in email delivery">Messages may take up to 15 minutes to arrive.</Alert>
+        <main tabIndex={-1}><p className="cap">Page banners lie edge to edge across the top. One that asks for action is raised; one that informs is a flat sheet.</p></main>
+      </div>
+    <div className="col wrap">
+      <Alert title="Scheduled maintenance">The API will be read-only on Sunday from 02:00 to 02:30 UTC.</Alert>
+      <Alert tone="positive" title="Domain verified">acme.dev now points at this project.</Alert>
+      <Alert tone="caution" variant="raised" title="You're at 90% of your plan" action={<Button size="sm" variant="primary">Upgrade</Button>} />
+      <AlertStack>
+        {items.map((a) => <Alert key={a.id} tone={a.tone} title={a.title} onDismiss={() => setItems((xs) => xs.filter((x) => x.id !== a.id))}>{a.body}</Alert>)}
+      </AlertStack>
+    </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,111 @@
+# AltitudeProvider
+
+Sets the color scheme, accent and motion preference for everything inside it, and hosts the layers that rise above the page.
+
+Wrap the app once, near the root. It renders a themed root, a **stage** (your app, which recedes behind dialogs) and a **layer host** (where dialogs and toasts render, so they stay inside the theme but outside the receding stage).
+
+It also sets the high-contrast rendering: with `contrast="more"` (or the system's `prefers-contrast: more`), shadows become hard ink slabs whose thickness is the height.
+
+It runs the **approach** tracker too, which lets openings react to a pointer before it arrives: an empty field deepens to receive, and a bottom sheet's finger pull opens. Raised things (buttons, cards, piles, steps) never react before the pointer is on them and never follow it. It only follows a mouse or pen, never touch, and reduced motion turns every approach effect off. `approach={false}` turns it off for everything inside.
+
+**Your own scheme.** `scheme` also takes a custom scheme: `{ name, base, tokens }`, your colour and shadow tokens laid over a built-in scheme (`base`, which supplies anything you leave out and the light or dark handling). The provider scopes them to itself in a stylesheet, so they nest like the built-in schemes and still give way to high contrast. If the scheme breaks the invariants in [Theming](../../visual/Theming.md) (the surface ladder, contrast on every surface, the data palette's gates), it says which in a console warning; `checkScheme(el, { include: ['core', 'data'] })` runs the same test in your own tests. A plain string names your own `[data-theme="…"]` block instead.
+
+**You provide:** `scheme` (a built-in name, your own, a custom scheme, or nothing, to inherit `data-theme` from the page), optionally `accent` as a hex color, `motion`, `approach`, `loading="breath"` to try the experimental breathing imprints (see `Await`), and `recede={false}` if your layout can't tolerate a transform on the app root (for example a `position: fixed` header that must not scale).
+
+- Do nest a provider to theme a region differently: a `nightfall` sidebar in a `daylight` app.
+- Do pass your brand color as `accent`; legibility is derived for you, and the chart palette's first series and magnitude ramp follow it (the other series re-order so neighbours stay apart for colour-blind readers).
+- Do reach for a custom scheme only when the brand needs its own grounds and ink, and keep `checkScheme` passing in your tests.
+- Don't render `Dialog` or `Toaster` outside a provider unless you accept them portaling to `document.body` without the receding page.
+
+Modal ownership is coordinated privately per document. A nested themed Dialog keeps the nearest provider's portal host and blocks background branches throughout the document. Ancestors containing that portal are never transformed or made inert as a whole. Each provider's own `recede` setting remains independent. A stationary Dialog suppresses recession and blur on participating lower modal layers until it finishes closing.
+
+Isolation preserves application-owned inertness and restores the original inline scroll style after the last modal exits. Reopening during exit retains the same ownership; route/provider unmount releases it immediately. Applications do not need a competing inert wrapper. The legacy `useAltitude().pushLayer()` helper remains compatible as a visual recession vote with an idempotent release. It does not acquire modal isolation or focus ownership; use Dialog and modal Sheet for those behaviors. `useAltitude()` supplies the nearest portal `host`, and the ownership registry remains private.
+
+**Density.** `density` sets how large controls are. `'auto'` (default) uses the mouse sizes and steps up under a coarse pointer, so controls are big enough to hit with a finger; `'comfortable'` uses the larger sizes everywhere; `'compact'` keeps the mouse sizes on touch. Hit areas reach 44px under a coarse pointer either way. See [Theming](../../visual/Theming.md), "Density and target size".
+
+## App modes
+
+`mode` marks the whole app as being in a state people must never mistake for the normal app: Stripe-style **test mode**, a support agent **viewing as a customer**, a **read-only** workspace, a **preview** of unpublished content.
+
+```tsx
+<AltitudeProvider mode={{ tone: 'caution', label: 'Test mode', description: 'Payments are simulated.',
+  action: <Button size="sm" onClick={exit}>Leave test mode</Button> }}>
+```
+
+**Elevation: a word and a border.** The page is the ground, so height can't say "this whole ground is different". The mode is carried by the non-height cues instead (law 7 as the primary channel):
+- **A flush strip** at the top, on the tone's soft colour, naming the mode, with your way out. It can't be dismissed.
+- **A 2px frame around the viewport** in the mode's tone. It stays while scrolling, and above dialogs and sheets.
+- **A plate in every `Dialog` and `Sheet` header** naming the mode, so a refund confirmed in test mode says so.
+
+Nothing moves: a mode is there from load. Entering it is announced once, politely ("Test mode on"). The strip is a region named by the mode, first in the tab order. Under forced colours the frame is a 4px double `CanvasText` border. Under `contrast="more"` it's 3px. `ModeContext` gives your own floating parts the mode.
+
+- Do use a mode for anything that changes what actions do (simulated payments, acting as someone else).
+- Don't use a page banner for a mode; a banner can be dismissed and scrolls away.
+
+## One primary per view
+
+Law 1 says the primary action rests at level 2, one per view. With `devChecks` (on by default when `process.env.NODE_ENV` isn't `'production'`), a `Button variant="primary"` registers with the provider while it's mounted. When more than one *visible* primary sits in the same view, one grouped warning names them and law 1. The page is one view, and each `Dialog`, `Sheet` and `Popover` is its own. Wrap independent parts (cards on a dashboard, each with its own task) in `<PrimaryScope>` to make them views of their own. The check is a warning only, it's gone from production builds, and the rule is `ALT-VISUAL-002` (`altitude explain ALT-VISUAL-002`). `PageHeader`'s `primary` slot is where a page's one primary belongs.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AltitudeProvider` as first used in its preview:
+
+```tsx
+import { AltitudeProvider, Badge, Button, Input, Switch } from 'altitude-design';
+
+<AltitudeProvider key={i} scheme={s} accent={accent} className="shell"><div className="scheme">
+  <h4>{typeof s === 'string' ? s[0].toUpperCase() + s.slice(1) : 'Custom'}</h4>
+  <small>{accent ? 'accent="' + accent + '"' : typeof s === 'string' ? 'scheme="' + s + '"' : 'scheme={paper}'}</small>
+  <Button variant="primary" size="sm">Publish</Button>
+  <Input size="sm" placeholder="Search" aria-label="Search" />
+  <div style={{ display: 'flex', gap: 10, alignItems: 'center' }}><Switch defaultChecked aria-label="Enabled" /><Badge tone="accent">Beta</Badge></div>
+  <div className="series">{[1, 2, 3, 4, 5, 6].map((n) => <span key={n} style={{ background: `var(--data-${n})` }} />)}<small>{accent ? 'data-1…6, led by the accent' : 'data-1…6'}</small></div>
+</div></AltitudeProvider>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`schemes`, `shell`, `scheme`, `series`, `density` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { AltitudeProvider, Badge, Button, Input, Switch, Tabs, TabsList, TabsTrigger } from 'altitude-design';
+
+// A custom scheme: warm paper grounds and green ink laid over daylight. checkScheme() passes it.
+const paper = { name: 'paper', base: 'daylight', tokens: {
+  'surface-trench': '#e5e1d2', 'surface-well': '#edeadf', 'surface-ground': '#f5f3ea', 'surface-raised': '#fffdf7',
+  'surface-lifted': '#fffdf8', 'surface-floating': '#fffefa', 'surface-overlay': '#fffefb', 'surface-modal': '#fffefc',
+  ink: '#1f3329', 'ink-muted': '#4b5d53', 'ink-faint': '#949b8e', line: '#e2ded0', 'line-control': '#76806f',
+  accent: '#284d39', 'on-accent': '#ffffff', 'accent-ink': '#284d39', 'accent-soft': '#e1e9dc', positive: '#2c6e3f',
+} };
+const list = [['daylight'], ['nightfall'], ['daylight', '#0f8a6b'], [paper]];
+export default function App() {
+  return (
+    <>
+      <div className="schemes">
+      {list.map(([s, accent], i) => (
+        <AltitudeProvider key={i} scheme={s} accent={accent} className="shell"><div className="scheme">
+          <h4>{typeof s === 'string' ? s[0].toUpperCase() + s.slice(1) : 'Custom'}</h4>
+          <small>{accent ? 'accent="' + accent + '"' : typeof s === 'string' ? 'scheme="' + s + '"' : 'scheme={paper}'}</small>
+          <Button variant="primary" size="sm">Publish</Button>
+          <Input size="sm" placeholder="Search" aria-label="Search" />
+          <div style={{ display: 'flex', gap: 10, alignItems: 'center' }}><Switch defaultChecked aria-label="Enabled" /><Badge tone="accent">Beta</Badge></div>
+          <div className="series">{[1, 2, 3, 4, 5, 6].map((n) => <span key={n} style={{ background: `var(--data-${n})` }} />)}<small>{accent ? 'data-1…6, led by the accent' : 'data-1…6'}</small></div>
+        </div></AltitudeProvider>
+      ))}
+      </div>
+      {/* Density (#245): 'auto' follows the pointer; 'compact' pins the mouse sizes, 'comfortable' the touch sizes. */}
+      <div className="density">
+        {['compact', 'comfortable'].map((d) => (
+          <AltitudeProvider key={d} density={d} className="shell"><div className="scheme">
+            <h4>{d === 'compact' ? 'Compact' : 'Comfortable'}</h4>
+            <small>density="{d}"</small>
+            <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}><Button variant="primary">Save</Button><Button>Cancel</Button></div>
+            <Input placeholder="Search" aria-label="Search" />
+            <Tabs defaultValue="a"><TabsList aria-label={'Sections, ' + d}><TabsTrigger value="a">General</TabsTrigger><TabsTrigger value="b">Members</TabsTrigger></TabsList></Tabs>
+          </div></AltitudeProvider>
+        ))}
+      </div>
+    </>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,121 @@
+# AppShell and Sidebar
+
+The frame of an app: a sidebar of destinations (grouped, collapsible), a top bar with search and the user's menu, and the page.
+
+**Elevation: the frame lies on the ground.** Where you are is part of the record, so the sidebar, top bar and page are all `surface-ground`, divided by `line`. Don't float the sidebar as a raised card. Only the things in it that act are live:
+- **A destination** lifts one level when pointed at, because it navigates.
+- **The current one** sits on a raised pill (segmented `Tabs`' build) that glides from destination to destination as you move.
+- **Only a count floats** (`Badge variant="count"`). A status ("Beta") would be a flush plate.
+- **Collapsing to a rail** changes width on `ease-glide`, not level. In the rail, each destination is an icon with its name in a tooltip to the right.
+- **The top bar** rises one level while content passes under it, as `ScrollArea`'s header does.
+- **On narrow screens** (below `mobileBreakpoint`, default 640px, the compact breakpoint) the sidebar moves into a `Sheet` drawer from the left (level 4), titled "Navigation". Choosing a destination closes it.
+
+**Parts** (shadcn/ui's names):
+- `AppShell`: `sidebar`, `topBar` and the page. It includes a `SidebarProvider`, a skip link, and a `SidebarTrigger` at the start of the top bar.
+- `SidebarProvider`: `collapsed`, `defaultCollapsed`, `onCollapsedChange`, `mobileBreakpoint`. ⌘B or Ctrl+B toggles. `useSidebar()` reads and changes the state.
+- `Sidebar`: a `nav` (`aria-label`, default "Main") with `collapsible` (`'icon' | 'none'`). Inside it go `SidebarHeader`, `SidebarContent` (scrolls, and holds the pill), `SidebarFooter`.
+- `SidebarGroup`: `label`; `collapsible` makes the label a disclosure button. Also `SidebarGroupLabel`.
+- `SidebarMenu` › `SidebarMenuItem` › `SidebarMenuButton` (`href`, `current`, `icon`, `asChild` for a router's link) and `SidebarMenuBadge` (`label`, such as "4 unread").
+- `SidebarTrigger`, and `SidebarInset` (the `main` landmark; it sets `--alt-page-pad` for `PageHeader`).
+
+**Open questions, answered.** Persisting the collapsed state is up to your app (use `collapsed` and `onCollapsedChange` with a cookie or `localStorage`). The workspace switcher is a recipe, a `DropdownMenu` whose trigger is an `Avatar` and a name, not a part (see the preview).
+
+**Accessibility.** [Landmarks](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/): `nav` with a label, `header`, `main`. A skip link ("Skip to content") comes first. The current destination has `aria-current="page"`. **A count is part of the destination's name** ("Inbox, 4 unread"). In the rail, each destination keeps its name as `aria-label` and in a tooltip. Collapsible groups use the disclosure pattern. `SidebarTrigger` says what it will do ("Collapse sidebar", "Open navigation") and carries `aria-keyshortcuts`. Under forced colours the pill gets a 1px border. Under `contrast="more"` it gets a 2px slab and the dividers are `line-control`. Under reduced motion the pill appears in place and the rail changes width at once.
+
+```tsx
+<AppShell
+  sidebar={
+    <Sidebar>
+      <SidebarHeader><WorkspaceMenu /></SidebarHeader>
+      <SidebarContent>
+        <SidebarGroup label="Workspace">
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton href="/inbox" current icon={<Inbox />}>Inbox</SidebarMenuButton>
+              <SidebarMenuBadge label="4 unread">4</SidebarMenuBadge>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarGroup>
+      </SidebarContent>
+      <SidebarFooter><UserMenu /></SidebarFooter>
+    </Sidebar>
+  }
+  topBar={<SearchEntry />}>
+  {page}
+</AppShell>
+```
+
+- Do give every destination an icon if the sidebar can collapse to a rail.
+- Do say what a count counts (`label="4 unread"`).
+- Don't raise the sidebar into a card or give it a shadow.
+- Don't put actions in the sidebar's destinations; they navigate.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AppShell` as first used in its preview:
+
+```tsx
+import { AppShell, Avatar, Button, DropdownMenu, Kbd, PageHeader, PageHeaderDescription, PageHeaderTitle, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarHeader, SidebarMenu, SidebarMenuButton, SidebarMenuItem } from 'altitude-design';
+
+<AppShell
+  sidebar={
+    <Sidebar>
+      <SidebarHeader>
+        <DropdownMenu items={[{ label: 'Acme Inc.' }, { label: 'Northwind' }, { type: 'separator' }, { label: 'Create workspace' }]}
+          trigger={<button className="as-ws"><Avatar name="Acme Inc." size={24} /><span className="alt-sidebar-text">Acme Inc.</span></button>} />
+      </SidebarHeader>
+      <SidebarContent>
+        <SidebarGroup label="Workspace"><SidebarMenu>{item('inbox', 'Inbox', 4)}{item('projects', 'Projects')}{item('reports', 'Reports')}</SidebarMenu></SidebarGroup>
+        <SidebarGroup label="Admin" collapsible><SidebarMenu>{item('members', 'Members')}{item('billing', 'Billing')}{item('settings', 'Settings')}</SidebarMenu></SidebarGroup>
+      </SidebarContent>
+      <SidebarFooter><SidebarMenu><SidebarMenuItem><SidebarMenuButton href="#/me" icon={<Avatar name="Maya Chen" size={20} />}>Maya Chen</SidebarMenuButton></SidebarMenuItem></SidebarMenu></SidebarFooter>
+    </Sidebar>
+  }
+  topBar={<Button variant="secondary" size="sm" className="search">Search… <Kbd>⌘K</Kbd></Button>}>
+  <PageHeader primary={<Button variant="primary">New message</Button>}><PageHeaderTitle>{at[0].toUpperCase() + at.slice(1)}</PageHeaderTitle><PageHeaderDescription>The sidebar's current destination sits on a raised pill that glides as you move. ⌘B collapses it to a rail.</PageHeaderDescription></PageHeader>
+  <div className="rows">{Array.from({ length: 8 }, (_, i) => <div key={i} />)}</div>
+</AppShell>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`as`, `as-ws`, `search`, `rows` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AppShell, Avatar, Button, DropdownMenu, Kbd, PageHeader, PageHeaderDescription, PageHeaderTitle, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarHeader, SidebarMenu, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem } from 'altitude-design';
+
+const I = ({ d }) => <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round"><path d={d} /></svg>;
+const icons = { inbox: 'M3 13h5l2 3h4l2-3h5M5 5h14l2 8v6H3v-6z', projects: 'M3 7h7l2 2h9v10H3z', reports: 'M5 20V10M12 20V4M19 20v-7', members: 'M16 19v-1a4 4 0 0 0-8 0v1M12 11a3 3 0 1 0 0-6 3 3 0 0 0 0 6', billing: 'M3 7h18v10H3zM3 11h18', settings: 'M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6M19 12l2-1-2-4-2 1-2-1-1-2h-4l-1 2-2 1-2-1-2 4 2 1v0l-2 1 2 4 2-1 2 1 1 2h4l1-2 2-1 2 1 2-4z' };
+export default function App() {
+  const [at, setAt] = React.useState('inbox');
+  const item = (key, label, badge) => (
+    <SidebarMenuItem key={key}>
+      <SidebarMenuButton href={'#/' + key} current={at === key} icon={<I d={icons[key]} />} onClick={(e) => { e.preventDefault(); setAt(key); }}>{label}</SidebarMenuButton>
+      {badge && <SidebarMenuBadge label={`${badge} unread`}>{badge}</SidebarMenuBadge>}
+    </SidebarMenuItem>
+  );
+  return (
+    <div className="as">
+      <AppShell
+        sidebar={
+          <Sidebar>
+            <SidebarHeader>
+              <DropdownMenu items={[{ label: 'Acme Inc.' }, { label: 'Northwind' }, { type: 'separator' }, { label: 'Create workspace' }]}
+                trigger={<button className="as-ws"><Avatar name="Acme Inc." size={24} /><span className="alt-sidebar-text">Acme Inc.</span></button>} />
+            </SidebarHeader>
+            <SidebarContent>
+              <SidebarGroup label="Workspace"><SidebarMenu>{item('inbox', 'Inbox', 4)}{item('projects', 'Projects')}{item('reports', 'Reports')}</SidebarMenu></SidebarGroup>
+              <SidebarGroup label="Admin" collapsible><SidebarMenu>{item('members', 'Members')}{item('billing', 'Billing')}{item('settings', 'Settings')}</SidebarMenu></SidebarGroup>
+            </SidebarContent>
+            <SidebarFooter><SidebarMenu><SidebarMenuItem><SidebarMenuButton href="#/me" icon={<Avatar name="Maya Chen" size={20} />}>Maya Chen</SidebarMenuButton></SidebarMenuItem></SidebarMenu></SidebarFooter>
+          </Sidebar>
+        }
+        topBar={<Button variant="secondary" size="sm" className="search">Search… <Kbd>⌘K</Kbd></Button>}>
+        <PageHeader primary={<Button variant="primary">New message</Button>}><PageHeaderTitle>{at[0].toUpperCase() + at.slice(1)}</PageHeaderTitle><PageHeaderDescription>The sidebar's current destination sits on a raised pill that glides as you move. ⌘B collapses it to a rail.</PageHeaderDescription></PageHeader>
+        <div className="rows">{Array.from({ length: 8 }, (_, i) => <div key={i} />)}</div>
+      </AppShell>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,101 @@
+# AreaChart
+
+A total over time and the parts that make it up (requests by region, storage by type), or a single volume over time. Stacked areas answer "how big, and from where"; `stack="expand"` answers "what share". It renders inside a [`ChartContainer`](../ChartContainer/README.md).
+
+**Why it's flat.** Bands are the record. Each is a flat `data-*` fill, stacked on the ground line in config order from the bottom, and parted from the band above by a 2px line in the plot's own colour, the same gap a stacked bar's segments have. The topmost band carries a 2px top line in its colour. A single area is a flat `data-1` fill at reduced opacity under a 2px `data-1` line.
+
+**No gradient fill.** Most libraries fade an area to transparent by default. Altitude's only face gradient is `--alt-sheen`, and it means "press it" (E4), so an area never has one.
+
+**Stack order never changes.** Bands stack in config order, so a band never jumps to a new position when values change, and its colour stays its own. In a stack a missing value adds nothing (the bands above rest on the one below); in a single area it's a gap, as in a line.
+
+**Named in place.** Stacked bands are labelled inside themselves in `ink`, on a halo of the plot's colour, at their thickest point, where they're at least 20px tall; thin bands rely on the legend and the readout. `labels={false}` turns this off.
+
+**Without colour.** Under forced colours and in print, and with `patterns` on the container, each band takes its slot's hatch (the first band is solid). With `contrast="more"` the separators are 3px `ink`.
+
+**Motion.** As `LineChart`: when the x values are the same, bands glide to their new values on `ease-glide`, after any rescale; when they differ, the old chart and the new one cross-fade. Nothing grows from the ground on first render ([Motion](../../visual/Motion.md), "Charts"). While data loads, the imprint is an area pressed into the page.
+
+**Accessibility.** The keyboard path is the container's (#63): ←/→ along x and, in a stack, ↑/↓ through the bands at that x, from the bottom up, so ↑ goes to the band above. Each point names its band's value and its share of the total: "Oct 1, 2026, EU, 1.1K. 34% of 3.2K. 1 of 14." The table view (`views`) has a column per band and a Total.
+
+**Not yet the record.** `status` marks partial or projected records. From the last settled point on, every band is hatched in its colour on the plot's own, with no solid fill, and the top line is dashed. A 1px `line-control` rule named "Today" (`boundary`) marks where the record ends, and the readout, point names and table say "Projected" or "So far". While patterns are on, a band with its own hatch keeps it there, faded, so bands stay told apart.
+
+**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` recedes the bands to 35% around each missing record, so the stack keeps its shape; `rescale` fits the axis to the matches. See [ChartContainer](../ChartContainer/README.md), "Filtering in place".
+
+**A sliding window.** `window` works as `LineChart`'s: the latest stretch of x, gliding one step in a `live` container, or a chosen `{ start, end }`, which a `ChartBrush` sets (`onWindowChange`).
+
+**Props:** `data` and `x`; `window` and `onWindowChange`; `stack` (`true` or `'expand'`); `curve` (`'linear'` or `'monotone'`); `y={{ format }}`; `labels`; `tooltip`; `status` and `boundary`; and a `ChartTooltip` or `ChartLegend` as children.
+
+**Focus.** `focus={['team']}` keeps those bands' colours and draws the rest in `data-context`, their labels in `ink-muted`. The stack's order doesn't change. See [ChartContainer](../ChartContainer/README.md), "Focus".
+
+**You provide:** a `ChartContainer` whose `config` names each band in stacking order (the base first), the `data` in x order, and usually a `summary`.
+
+```tsx
+<ChartContainer config={{ us: { label: 'US' }, eu: { label: 'EU' }, apac: { label: 'APAC' } }}>
+  <AreaChart data={requests} x="day" stack />          {/* stack="expand" for 100% */}
+</ChartContainer>
+```
+
+- Do put the largest or steadiest part at the bottom, where it stands on the ground line and reads most accurately.
+- Do use `stack="expand"` only when the share is the point; the totals disappear.
+- Do keep to six bands or fewer; fold the rest into one "Other" series.
+- Don't overlay several unstacked areas; compare trends with a `LineChart`.
+- Don't add a gradient, a glow or a shadow to make it look richer.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AreaChart` as first used in its preview:
+
+```tsx
+import { AreaChart, ChartLegend, ChartLegendContent } from 'altitude-design';
+
+<AreaChart data={week ? reqB : reqA} x="day" stack curve="monotone">
+  <ChartLegend content={<ChartLegendContent toggle />} />
+</AreaChart>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`ac`, `wide` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AreaChart, Button, Card, CardContent, CardDescription, CardHeader, CardTitle, ChartContainer, ChartLegend, ChartLegendContent } from 'altitude-design';
+
+const acDays = Array.from({ length: 14 }, (_, i) => `2026-10-${String(i + 1).padStart(2, '0')}`);
+const reqA = acDays.map((day, i) => ({ day, us: 1600 + i * 40 + (i % 3) * 90, eu: 1100 + Math.round(180 * Math.sin(i / 2)), apac: 520 + i * 35 }));
+const reqB = acDays.map((day, i) => ({ day, us: 1500 + i * 55 + (i % 4) * 70, eu: 1250 + Math.round(140 * Math.cos(i / 2)), apac: 700 + i * 20 }));
+const plans = ['2026-01-01', '2026-02-01', '2026-03-01', '2026-04-01', '2026-05-01', '2026-06-01', '2026-07-01', '2026-08-01']
+  .map((month, i) => ({ month, free: 620 - i * 30, team: 210 + i * 22, business: 90 + i * 15, enterprise: 20 + i * 6 }));
+const storage = acDays.map((day, i) => ({ day, used: [41, 42, 42.5, 44, 45, 45.2, 47, 49, 50, 50.4, 53, 55, 56, 58][i] }));
+const k = new Intl.NumberFormat('en', { notation: 'compact', maximumFractionDigits: 1 });
+function Chart({ id, title, sub, children, className, ...props }) {
+  return (
+    <Card className={className}>
+      <CardHeader><CardTitle id={id}>{title}</CardTitle><CardDescription>{sub}</CardDescription></CardHeader>
+      <CardContent><ChartContainer aria-labelledby={id} {...props}>{children}</ChartContainer></CardContent>
+    </Card>
+  );
+}
+export default function App() {
+  const [week, setWeek] = React.useState(0);
+  return (
+    <div className="ac">
+      <Chart className="wide" id="a1" title="Requests by region" sub={<>Stacked: the total and where it came from · <Button size="sm" variant="ghost" onClick={() => setWeek((w) => 1 - w)}>{week ? 'First week' : 'Second week'}</Button></>}
+        config={{ us: { label: 'US', format: k.format }, eu: { label: 'EU', format: k.format }, apac: { label: 'APAC', format: k.format } }} aspect={3.2} views>
+        <AreaChart data={week ? reqB : reqA} x="day" stack curve="monotone">
+          <ChartLegend content={<ChartLegendContent toggle />} />
+        </AreaChart>
+      </Chart>
+      <Chart id="a2" title="Accounts by plan" sub='stack="expand", focus on Team'
+        config={{ free: { label: 'Free' }, team: { label: 'Team' }, business: { label: 'Business' }, enterprise: { label: 'Enterprise' } }} aspect={1.7}>
+        <AreaChart data={plans} x="month" stack="expand" focus={['team']} />
+      </Chart>
+      <Chart id="a3" title="Storage used" sub="One area: a flat fill under its line" config={{ used: { label: 'Used', format: (v) => `${v} GB` } }} aspect={1.7}
+        summary="Storage use rose from 41 GB to 58 GB over two weeks, fastest in the second.">
+        <AreaChart data={storage} x="day" />
+      </Chart>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,99 @@
+# Artifact
+
+What an agent is making (a document, a component, a page, a chart, a config) in its own pane beside the conversation, with its versions. Claude's artifacts, ChatGPT's canvas and v0's preview work this way: the latest version as it's written, preview and source, earlier versions to go back to, what changed.
+
+**Elevation: the current version is the record.**
+- **The pane** lies on the ground beside the conversation (put it in a `ResizablePanel`), named by its title.
+- **Being written** isn't the record yet: a dashed `line-control` rule at the pane's edge and "Writing… version 3" (`aria-busy`).
+- **Complete**: the rule goes solid with one afterglow, and "Version 3" (announced once: "Pricing page, version 3, complete").
+- **Failed**: "Couldn't finish version 3" with a critical mark and Retry; keep the last whole version on show. The edge stays solid and neutral: a coloured stripe is a tell of generated interfaces (Distinctiveness, CM3), and the words already say it.
+- **Viewing an earlier version** is a mode, and a mode isn't a height: a flush strip across the top with a `line-control` border, "Viewing version 1 of 3", Return to latest and Restore this version.
+- **Header tools** are ghost buttons named for the artifact. **Preview / Source / Changes** is segmented `Tabs`.
+- **The reference** in a message is a plate that acts, lifting one level when pointed at.
+
+**Accessibility.** A region named by its title. The reference is a button with `aria-controls` on the pane: it opens the pane and moves focus to the pane's heading, and Escape in the pane goes back to it. Give an iframe preview a `title`, and keep the source view as its alternative. Writing isn't announced again and again; completion is said once.
+
+**Parts:** `Artifact` (`title`, `status`: `'writing' | 'complete' | 'failed'`, `version`, `onRetry`, `id`); `ArtifactHeader` (`onCopy`, `onDownload`, `onOpen`, `onClose`, extra tools as children); `ArtifactVersions` (`versions`, `current`, `onChange`, `onRestore`); `ArtifactContent` (`views`: `{ preview?, source?, changes? }`, `defaultView`); `ArtifactReference` (`title`, `version`, `status`, `controls`, `onOpen`).
+
+**You provide:** the versions and their content (a sandboxed iframe for previews, `CodeBlock` for source, `DiffView` for changes), and where the pane sits. On a phone, a `ResizablePanelGroup` with `narrow="stack"` shows the conversation or the pane, one at a time; set `narrowPanel` to the pane when it opens.
+
+```tsx
+<Artifact id="pricing" title="Pricing page" status={a.status} version={a.versions.length} onRetry={retry}>
+  <ArtifactHeader onCopy onDownload={download} onClose={close} />
+  <ArtifactVersions versions={a.versions.length} current={v} onChange={setV} onRestore={restore} />
+  <ArtifactContent views={{ preview: <iframe sandbox="allow-scripts" srcDoc={html} title="Pricing page preview" />, source: <CodeBlock language="tsx" code={code} /> }} />
+</Artifact>
+```
+
+- Do sandbox preview iframes; the frame's permissions are yours.
+- Do keep the last whole version visible when a new one fails.
+- Don't lift the pane or tint it for an earlier version; say it in the strip.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Artifact` as first used in its preview:
+
+```tsx
+import { Artifact, ArtifactContent, ArtifactHeader, ArtifactVersions, CodeBlock, DiffView } from 'altitude-design';
+
+<Artifact id="pricing-artifact" title="Pricing page" status={status} version={3}>
+  <ArtifactHeader onCopy={() => versions[v - 1].code} onDownload={() => {}} onClose={() => setOpen(false)} />
+  <ArtifactVersions versions={3} current={v} onChange={setV} onRestore={() => setV(3)} />
+  <ArtifactContent views={{
+    preview: <iframe sandbox="" srcDoc={html(v)} title={`Pricing page preview, version ${v}`} />,
+    source: <CodeBlock language="tsx" code={versions[v - 1].code} streaming={status === 'writing' && v === 3} />,
+    changes: v > 1 ? <DiffView caption={`Version ${v - 1} → ${v}`} before={versions[v - 2].code} after={versions[v - 1].code} /> : undefined,
+  }} />
+</Artifact>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`af`, `chat` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Artifact, ArtifactContent, ArtifactHeader, ArtifactReference, ArtifactVersions, CodeBlock, DiffView, Message, MessageContent, ResizableHandle, ResizablePanel, ResizablePanelGroup } from 'altitude-design';
+
+const versions = [
+  { code: `export function Pricing() {\n  return <h1>Pricing</h1>;\n}` },
+  { code: `export function Pricing() {\n  return (\n    <section>\n      <h1>Pricing</h1>\n      <p>Start free, upgrade when you grow.</p>\n    </section>\n  );\n}` },
+  { code: `export function Pricing() {\n  return (\n    <section>\n      <h1>Pricing</h1>\n      <p>Start free, upgrade when you grow.</p>\n      <Plans tiers={['Starter', 'Pro', 'Business']} />\n    </section>\n  );\n}` },
+];
+const html = (v) => `<body style="font:15px system-ui;margin:24px;color:#1b2230"><h1 style="font-size:22px">Pricing</h1>${v >= 2 ? '<p>Start free, upgrade when you grow.</p>' : ''}${v >= 3 ? '<div style="display:flex;gap:8px">' + ['Starter', 'Pro', 'Business'].map((t) => `<div style="flex:1;padding:12px;border:1px solid #d5dae3;border-radius:8px">${t}</div>`).join('') + '</div>' : ''}</body>`;
+export default function App() {
+  const [open, setOpen] = React.useState(true);
+  const [status, setStatus] = React.useState('writing');
+  const [v, setV] = React.useState(3);
+  React.useEffect(() => { const t = setTimeout(() => setStatus('complete'), 2500); return () => clearTimeout(t); }, []);
+  return (
+    <div className="af">
+      <ResizablePanelGroup direction="horizontal" narrow="stack" narrowPanel={open ? 1 : 0}>
+        <ResizablePanel defaultSize={42} aria-label="Conversation">
+          <div className="chat">
+            <Message from="user"><MessageContent>Make a pricing page with three plans.</MessageContent></Message>
+            <Message from="assistant">
+              <MessageContent>Here's the page, with the three plans in a row.</MessageContent>
+              <ArtifactReference title="Pricing page" version={3} status={status} controls="pricing-artifact" onOpen={() => setOpen(true)} />
+            </Message>
+          </div>
+        </ResizablePanel>
+        <ResizableHandle />
+        <ResizablePanel defaultSize={58} aria-label="Pricing page">
+          {open && (
+            <Artifact id="pricing-artifact" title="Pricing page" status={status} version={3}>
+              <ArtifactHeader onCopy={() => versions[v - 1].code} onDownload={() => {}} onClose={() => setOpen(false)} />
+              <ArtifactVersions versions={3} current={v} onChange={setV} onRestore={() => setV(3)} />
+              <ArtifactContent views={{
+                preview: <iframe sandbox="" srcDoc={html(v)} title={`Pricing page preview, version ${v}`} />,
+                source: <CodeBlock language="tsx" code={versions[v - 1].code} streaming={status === 'writing' && v === 3} />,
+                changes: v > 1 ? <DiffView caption={`Version ${v - 1} → ${v}`} before={versions[v - 2].code} after={versions[v - 1].code} /> : undefined,
+              }} />
+            </Artifact>
+          )}
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -0,0 +1,75 @@
+# Avatar
+
+Represents a person. A face is a disc on the page, built from the same pieces as everything around it: while the person is here it rests on the page like a card, and while they're not it's part of the record, a plate set flush into the page. Only someone live leaves the ground.
+
+| State | Height | Face | Lamp |
+|---|---|---|---|
+| `active` | resting: level 1, a contact shadow | `surface-raised` | filled `positive` |
+| `idle` | resting: level 1, a contact shadow | `surface-raised` | an empty ring in `caution` |
+| `offline` | flush in the page (ground), photo greyscale | a badge plate, `ink-muted` initials | none |
+| `live` | lifted off the page, drifting over `dur-hover`; its shadow appears on the page beneath it | `surface-raised` at level 2 | as its status |
+
+Faces are neutral. Status colours never stand for a person, so an initial on a pink disc can't read as an error; colour lives in the lamp, as it does on a `Badge`. Active and idle differ in the lamp's shape (filled or an empty ring), not only its colour, and not in height: they're one tier, because both people are here.
+
+`live` (speaking, typing, presenting right now) lifts the face: the shadow beneath it appears on the page and gets smaller and fainter as the face rises, the cue people read as an object floating rather than resting. Under reduced motion it holds a little above the page instead of drifting. Height is animated through a registered `--hr` property, so face and shadow move together on `ease-settle`. `presence={1|2|3}` rings the face in that person's presence colour, a 2px ring drawn tight around it.
+
+The lamp is cut out of the face by a 2px ring of ground. It shows at 24px and larger (`lamp={false}` hides it) and is never shown inside a group. With `onClick` the avatar becomes a button: hovering or focusing lifts it off the page, and pressing returns it to the ground, the same promise as everything else that lifts. Avatars without `onClick` never lift on hover.
+
+**Teams, organisations, bots and agents** are `shape="square"`: a tile whose corners grow with its size (`radius-xs` up to 24px, `radius-sm` to 36, `radius-md` to 48, `radius-lg` above), with the same states, lamp and shadow as a person. Keep circles for people, so a glance tells you whether a person did something.
+
+**Faces.** With `src` the photo fills the face; if it fails to load, the initials show instead. Initials are the first letter of the first and last words, skipping punctuation and emoji ("Mara de Quist" is MQ, "Jean-Luc Picard" JP, "李小龙" 李); below 28px, one letter, drawn larger. Names that no rule abbreviates well are better given a photo.
+
+**Sizes.** 24px in dense rows and tables, 28–32px in lists and groups, 36px (the default) beside a name, 44px on cards, 64px in a profile header.
+
+In an `AvatarGroup`, every face stands on one ground line, each cut out of the one before it by a ring of ground, overlapping by 12% so the initials beneath stay whole. Offline faces are flush plates in the row; a live face lifts in front of its neighbours. `max` caps the faces shown and the rest become a flush "+N" plate whose label names them ("2 more: Eli Ward, Kai Ito"); `size` sizes every face that doesn't set its own. The group is a `role="group"` labelled with how many people it holds ("7 people"); pass your own `aria-label` for something more specific ("Editing now").
+
+**Loading.** While `name` is undefined (`user?.name` while your data loads), or a promise, the avatar is an imprint of its `size` and `shape`; it rises out of it when the name arrives (see `Await`).
+
+**Forced colours and high contrast.** Faces get a `CanvasText` rim (`GrayText` when offline, 2px when live), and the active lamp is filled while the idle one stays a ring. Under `contrast="more"` a resting face sits on the same ink slab as a card.
+
+**Right to left.** The lamp sits at the inline end and a group overlaps from the inline start, so both mirror with `dir="rtl"`.
+
+**You provide:** `name` (always: it's the accessible label, with the status appended), optional `src`, `size` in pixels (default 36), `shape`, `status`, `live`, `presence`, `lamp`, `onClick`. On `AvatarGroup`: `max`, `size`.
+
+- Leave about a fifth of the avatar's size free above a live or pressable avatar for it to rise into, and a quarter above a group.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Avatar` as first used in its preview:
+
+```tsx
+import { Avatar } from 'altitude-design';
+
+<Avatar name="Mara Quist" size={44} status="active" live presence={1} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `people`, `who`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { Avatar, AvatarGroup } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="col" style={{ gap: 22 }}>
+      <div className="people">
+        <div className="who"><Avatar name="Mara Quist" size={44} status="active" live presence={1} /><span className="cap">live</span></div>
+        <div className="who"><Avatar name="Jon Reyes" size={44} status="active" /><span className="cap">active</span></div>
+        <div className="who"><Avatar name="Lena Park" size={44} status="idle" /><span className="cap">idle</span></div>
+        <div className="who"><Avatar name="Sam Okafor" size={44} status="offline" /><span className="cap">offline</span></div>
+        <div className="who"><Avatar name="Noa Levi" size={44} status="active" onClick={() => {}} /><span className="cap">pressable</span></div>
+        <div className="who"><Avatar name="Northwind Studio" size={44} shape="square" /><span className="cap">team</span></div>
+        <div className="who"><Avatar name="Deploy bot" size={44} shape="square" status="active" /><span className="cap">bot</span></div>
+      </div>
+      <div className="people" style={{ alignItems: 'center' }}>
+        <AvatarGroup max={5} size={32}>
+          {[['Ada Obi', 'active', true], ['Ivy Chen', 'idle'], ['Theo Marsh', 'active'], ['Rui Costa', 'idle'], ['Noa Levi', 'offline'], ['Eli Ward', 'offline'], ['Kai Ito', 'offline']].map(([n, st, live]) => <Avatar key={n} name={n} status={st} live={live} />)}
+        </AvatarGroup>
+        {[24, 36, 64].map((s) => <Avatar key={s} name="Ines Park" size={s} status="active" />)}
+      </div>
+      <p className="cap">People who are here rest on the page: a filled lamp when they're active, an empty one when they're away. Offline people lie flush and grey. Mara is speaking, so she lifts off her shadow, ringed in her presence colour. Teams and bots are square. Hover Noa: an avatar you can press rises like everything else that acts.</p>
+    </div>
+  );
+}
+```
+<!-- /example -->