altitude-design 0.4.0 → 0.4.2

package/README.md

@@ -3,6 +3,7 @@
 A design and HCI framework for agent-built React web applications, with a component foundation where **height is the interface**. Its one idea: the ground is the record. Settled content sits on the ground; anything live rises above it; anything waiting to receive sinks below it.
 
 - **Site:** https://richlaconte.github.io/altitude/
+- **For agents:** https://richlaconte.github.io/altitude/llms.txt, an index of the guides, task patterns and every component's guide as plain Markdown ([llmstxt.org](https://llmstxt.org)), and `llms-full.txt` beside it with every guide in one file
 - **Storybook:** every component, with its guidelines and a live preview in both schemes: https://richlaconte.github.io/altitude/storybook/
 - **The design guide:** [`project/README.md`](https://github.com/richlaconte/altitude/blob/main/project/README.md), then [Elevation](https://github.com/richlaconte/altitude/blob/main/project/Elevation.md), [Motion](https://github.com/richlaconte/altitude/blob/main/project/Motion.md), [Charts](https://github.com/richlaconte/altitude/blob/main/project/Charts.md), [Theming](https://github.com/richlaconte/altitude/blob/main/project/Theming.md), [Fundamentals](https://github.com/richlaconte/altitude/blob/main/project/Fundamentals.md), [Distinctiveness](https://github.com/richlaconte/altitude/blob/main/project/Distinctiveness.md) and [Research](https://github.com/richlaconte/altitude/blob/main/project/Research.md)
 

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

@@ -23,3 +23,38 @@ Says when content was generated or changed by AI, and explains how when asked: f
 - Do say confidence in words.
 - Don't decorate AI content with gradients, glows or shimmer.
 - Don't use the label as the only place AI involvement is disclosed when your rules require more.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AILabel` as first used in its preview:
+
+```tsx
+import { AILabel } from 'altitude-design';
+
+<AILabel subject="Summary" model="Opus 5.5" generatedAt={new Date(Date.now() - 4 * 60000)} confidence="Medium: two sources disagreed about the renewal date"
+sources={[{ title: 'Call with Jamie Lee, 28 Oct', url: '#/calls/28' }, { title: 'Contract v3.pdf', url: '#/files/contract' }]} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `al`, `ttl` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import { AILabel } from 'altitude-design';
+
+export default function App() {
+  return (
+    <div className="col al">
+      <div>
+        <h3 className="ttl">Summary <AILabel subject="Summary" model="Opus 5.5" generatedAt={new Date(Date.now() - 4 * 60000)} confidence="Medium: two sources disagreed about the renewal date"
+          sources={[{ title: 'Call with Jamie Lee, 28 Oct', url: '#/calls/28' }, { title: 'Contract v3.pdf', url: '#/files/contract' }]} /></h3>
+        <p>Jamie wants to move to annual billing in November and asked whether the 30-day refund applies to the remaining monthly period.</p>
+      </div>
+      <div>
+        <h3 className="ttl">Reply <AILabel subject="Reply" model="Opus 5.5" generatedAt={new Date(Date.now() - 3 * 3600000)} reviewedBy="Maya Chen" editedBy="Maya Chen" /></h3>
+        <p>Hi Jamie, thanks for getting in touch. Your full refund of €240 is on its way.</p>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -5,3 +5,28 @@ Reveals sections one at a time. Closed items are **lids** lying flush on the pag
 Closed rows sit on the ground divided by `line` hairlines. Hovering one raises a ghost of its lid (a faint raised tint with a hairline), so you can see what will open. Opening raises the item to level 2 (`surface-raised`, `elev-2`), opens a gap around it and hides the neighbouring dividers. Inside, the content sits in a compartment: an opening sunk into the lid (`surface-well`) with its back wall showing just below the rim, the same camera as an empty `Input`. The panel grows on `ease-glide`, the content emerges 60ms later, and the chevron turns on `ease-settle`. Closed panels are inert to keyboard and assistive tech.
 
 **You provide:** `items` (`value`, `title`, `content`), `type` (`single` closes the others; `multiple` doesn't), `defaultValue` as an array of open values.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Accordion` as first used in its preview:
+
+```tsx
+import { Accordion } from 'altitude-design';
+
+<Accordion items={items} defaultValue={['b']} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`wrap` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import { Accordion } from 'altitude-design';
+
+const items = [
+  { value: 'a', title: 'What does elevation mean here?', content: 'Height says how much something matters right now and what you can do with it: raised things are pushed, sunk things are filled.' },
+  { value: 'b', title: 'Can I bring my own colour?', content: 'Pass any hex as accent to AltitudeProvider. The accent text and soft tints are derived to stay legible on every surface.' },
+  { value: 'c', title: 'Does it respect reduced motion?', content: 'Yes. Surfaces still change level, tint and shadow, but nothing travels or scales.' },
+];
+export default function App() { return <div className="wrap"><Accordion items={items} defaultValue={['b']} /></div>; }
+```
+<!-- /example -->

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

@@ -1,6 +1,6 @@
 # AgentFleet
 
-Every agent working on one job, as a roster: grouped by what they need from you (needs you, working, done), each row saying the agent's state in words, what it's doing in one line, how long it has waited or run, where it is in its plan and what it has spent, with warnings for trouble that's coming (two agents changing one file, an agent making no progress). For supervising several agents at once; see [the research](https://github.com/richlaconte/altitude/blob/v0.4.0/docs/research/agent-orchestration/README.md).
+Every agent working on one job, as a roster: grouped by what they need from you (needs you, working, done), each row saying the agent's state in words, what it's doing in one line, how long it has waited or run, where it is in its plan and what it has spent, with warnings for trouble that's coming (two agents changing one file, an agent making no progress). For supervising several agents at once; see [the research](https://github.com/richlaconte/altitude/blob/v0.4.2/docs/research/agent-orchestration/README.md).
 
 **Elevation: a record of agents, with live rows.**
 - **Rows** are the record: flush at rest, lifting one level when pointed at because selecting one opens it. The open agent is selected, as a table's row is: `accent-soft`, raised one level, `aria-current`.
@@ -32,3 +32,50 @@ const row = (a) => <AgentFleetItem key={a.id} {...a} selected={a.id === open} on
 - Do say every state in words; the lamp and mark only repeat it.
 - Don't show a spinner, a ticking counter or make a working row hover.
 - Don't lay agents out as a grid of equal cards: the one that needs you gets lost among the ones that don't.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AgentFleet` as first used in its preview:
+
+```tsx
+import { AgentFleet, AgentFleetGroup, summarizeFleet } from 'altitude-design';
+
+<AgentFleet now={now} summary={summarizeFleet(seed.map((a) => a.state))}>
+  <AgentFleetGroup label="Needs you" empty="Nothing needs you.">{g.needsYou.map(row)}</AgentFleetGroup>
+  <AgentFleetGroup label="Working">{g.working.map(row)}</AgentFleetGroup>
+  <AgentFleetGroup label="Done" collapsible>{g.finished.map(row)}</AgentFleetGroup>
+</AgentFleet>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`af` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AgentFleet, AgentFleetGroup, AgentFleetItem, groupAgents, summarizeFleet } from 'altitude-design';
+
+const now = Date.UTC(2026, 9, 31, 14, 20), min = 60000;
+const seed = [
+  { id: 'api', name: 'Billing API', state: 'needs-input', needs: 'approval', activity: 'Wants to run the migration on staging', since: now - 6 * min, startedAt: now - 17 * min, step: { current: 3, total: 4 }, cost: '$0.38' },
+  { id: 'qa', name: 'QA', state: 'failed', activity: '2 of 14 checkout tests failed', since: now - 2 * min, startedAt: now - 5 * min, cost: '$0.11' },
+  { id: 'docs', name: 'Docs', state: 'stalled', stalledReason: 'Retried the same step 3 times', activity: 'Link check timed out on /enterprise; retrying', since: now - 5 * min, startedAt: now - 17 * min, step: { current: 3, total: 3 }, cost: '$0.31' },
+  { id: 'pricing', name: 'Pricing page', state: 'working', activity: 'Writing the annual toggle in Pricing.tsx', startedAt: now - 17 * min, step: { current: 2, total: 4 }, cost: '$0.41', conflict: { file: 'src/content/pricing.ts', with: 'Docs' } },
+  { id: 'changelog', name: 'Changelog', state: 'blocked', blockedBy: 'Pricing page' },
+  { id: 'emails', name: 'Renewal emails', state: 'done', activity: 'Scheduled for Tuesday 9:00 to 1,240 customers', startedAt: now - 17 * min, endedAt: now - 3 * min, cost: '$0.29' },
+];
+export default function App() {
+  const [open, setOpen] = React.useState('pricing');
+  const g = groupAgents(seed, (a) => a);
+  const row = (a) => <AgentFleetItem key={a.id} {...a} selected={a.id === open} onSelect={() => setOpen(a.id)} />;
+  return (
+    <div className="af">
+      <AgentFleet now={now} summary={summarizeFleet(seed.map((a) => a.state))}>
+        <AgentFleetGroup label="Needs you" empty="Nothing needs you.">{g.needsYou.map(row)}</AgentFleetGroup>
+        <AgentFleetGroup label="Working">{g.working.map(row)}</AgentFleetGroup>
+        <AgentFleetGroup label="Done" collapsible>{g.finished.map(row)}</AgentFleetGroup>
+      </AgentFleet>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -19,3 +19,35 @@ Where each agent's time went, one lane per agent on a shared clock: working, wai
 
 - Do keep it below the roster: it explains the past, the roster and requests are for now.
 - Don't draw dependencies as arrows between lanes; say them on the waiting agent ("Waiting on Billing API").
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AgentLanes` as first used in its preview:
+
+```tsx
+import { AgentLanes } from 'altitude-design';
+
+<AgentLanes lanes={lanes} start={t0} now={m(31)} selected={sel} onSelect={setSel} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`al` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AgentLanes } from 'altitude-design';
+
+const t0 = Date.UTC(2026, 9, 31, 14, 0), m = (n) => t0 + n * 60000;
+const lanes = [
+  { id: 'pricing', name: 'Pricing page', segments: [{ from: m(3), to: m(20), state: 'working' }, { from: m(20), to: m(25), state: 'waiting' }] },
+  { id: 'api', name: 'Billing API', segments: [{ from: m(3), to: m(7), state: 'working' }, { from: m(7), to: m(10), state: 'waiting' }, { from: m(10), to: m(19), state: 'working' }] },
+  { id: 'emails', name: 'Renewal emails', segments: [{ from: m(3), to: m(8), state: 'working' }, { from: m(8), to: m(13), state: 'waiting' }, { from: m(13), to: m(25), state: 'working' }] },
+  { id: 'qa', name: 'QA', segments: [{ from: m(3), to: m(19), state: 'blocked' }, { from: m(19), to: m(21), state: 'working' }, { from: m(21), to: m(23), state: 'failed' }, { from: m(23), to: m(29), state: 'working' }] },
+  { id: 'changelog', name: 'Changelog', segments: [{ from: m(27), to: m(30), state: 'working' }] },
+];
+export default function App() {
+  const [sel, setSel] = React.useState('qa');
+  return <div className="al"><AgentLanes lanes={lanes} start={t0} now={m(31)} selected={sel} onSelect={setSel} /></div>;
+}
+```
+<!-- /example -->

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

@@ -27,3 +27,50 @@ Every decision your agents are waiting on, in one queue: approvals, questions, r
 - Do say the consequence of an approval in `detail`.
 - Don't offer "approve all": answer each with its consequence in view.
 - Don't make an answer primary; the view's one primary stays where it is.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`AgentRequests` as first used in its preview:
+
+```tsx
+import { AgentRequest, AgentRequests, Button } from 'altitude-design';
+
+<AgentRequests now={now}>
+  {left.map((r) => (
+    <AgentRequest key={r.id} agent={r.agent} kind={r.kind} since={r.since} title={r.title} detail={r.detail} onOpen={() => {}}
+      actions={<>{r.answers.map((a) => <Button key={a} size="sm" variant="secondary" onClick={() => done(r.id)}>{a}</Button>)}
+        {r.decline && <Button size="sm" variant="ghost" onClick={() => done(r.id)}>{r.decline}</Button>}</>} />
+  ))}
+</AgentRequests>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`ar` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { AgentRequest, AgentRequests, Button } from 'altitude-design';
+
+const now = Date.UTC(2026, 9, 31, 14, 20), min = 60000;
+const seed = [
+  { id: 'emails', agent: 'Renewal emails', kind: 'question', since: now - 4 * min, title: 'Send the offer to every monthly customer, or only the active ones?', answers: ['Active only', 'Everyone'] },
+  { id: 'api', agent: 'Billing API', kind: 'approval', since: now - 9 * min, title: 'Run the plans-table migration on staging?', detail: 'Adds annual price columns to 4 plans on staging. Production isn\'t touched.', answers: ['Run migration'], decline: "Don't run" },
+  { id: 'qa', agent: 'QA', kind: 'failed', since: now - 1 * min, title: 'Checkout tests failed', detail: '2 of 14 failed: the annual total shows $290/yr, expected $290/year.', answers: ['Retry'] },
+];
+export default function App() {
+  const [left, setLeft] = React.useState(seed);
+  const done = (id) => setLeft((l) => l.filter((r) => r.id !== id));
+  return (
+    <div className="ar">
+      <AgentRequests now={now}>
+        {left.map((r) => (
+          <AgentRequest key={r.id} agent={r.agent} kind={r.kind} since={r.since} title={r.title} detail={r.detail} onOpen={() => {}}
+            actions={<>{r.answers.map((a) => <Button key={a} size="sm" variant="secondary" onClick={() => done(r.id)}>{a}</Button>)}
+              {r.decline && <Button size="sm" variant="ghost" onClick={() => done(r.id)}>{r.decline}</Button>}</>} />
+        ))}
+      </AgentRequests>
+    </div>
+  );
+}
+```
+<!-- /example -->

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

@@ -20,3 +20,52 @@ Several alerts as a **stack of sheets**, the same language as `Pile`. The first
 - 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

@@ -46,3 +46,66 @@ Nothing moves: a mode is there from load. Entering it is announced once, politel
 
 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

@@ -49,3 +49,73 @@ The frame of an app: a sidebar of destinations (grouped, collapsible), a top bar
 - 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

@@ -41,3 +41,61 @@ A total over time and the parts that make it up (requests by region, storage by
 - 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

@@ -28,3 +28,72 @@ What an agent is making (a document, a component, a page, a chart, a config) in
 - 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

@@ -32,3 +32,44 @@ In an `AvatarGroup`, every face stands on one ground line, each cut out of the o
 **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 -->