@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/motion.md

@@ -0,0 +1,93 @@
+# Motion
+
+Motion in TwoUX shows what changed and where it went: 120 to 260ms, eased by role, exits shorter than entrances, and nothing moves when people ask for reduced motion. It never decorates.
+
+Kind: foundation · Group: Visual foundation
+
+## Principles
+
+- Motion explains a change. Use it when people need to see what happened: a panel arriving, a section expanding, a value updating, a setting switching. If nothing would be lost without it, leave it out.
+- Productive, not expressive. Expressive motion suits rare, significant moments; a tool used all day has none worth the delay, so TwoUX has no expressive tier.
+- Ease by role. Something arriving or changing in place decelerates (--ease-entrance, --ease-standard), something moving between two places eases at both ends (--ease-move), something leaving accelerates and gets out of the way (--ease-exit). Only a changing count overshoots (--ease-pop).
+- Shortest that is not jarring. Most UI animation belongs between 100 and 500ms, and animations are far more often too long than too short; TwoUX stays between 120 and 260ms for anything people trigger.
+- Overlays keep shadcn's motion. Dialogs, menus, popovers and tooltips open with shadcn's fade and 95% zoom; the sheet slides 40px with a fade over 200ms. The push side panel matches it with --duration-move and --ease-move, so the list beside it eases aside.
+- Changes inside a screen use the motion helpers: Swap for a label or icon that changes state, Count for a number that changes, RollingNumber for a figure on a stat card, ShimmerText for a working status, StreamingText for AI text, AnimateHeight for a card that changes size. Nothing animates on first render.
+- Never the only signal. Motion never carries information alone; every change motion shows is also visible in its end state.
+
+## When to use
+
+- Panels, sheets and dialogs arriving, so people see where they came from and where they will go back to.
+- Sections expanding or collapsing, and cards changing height, so the content below doesn't jump.
+- State changes on a control people just used: a switch, a selected segment, Copy turning into Copied.
+- A value that updates while people watch, such as a stat card after a filter change or a count in a tab.
+- Toasts arriving and leaving, so a confirmation is noticed without taking focus.
+
+## When not to use
+
+- Hover on table rows, list items and menu items. These change many times a second as the pointer moves; a fill that lags reads as a slow app.
+- Rows loading, sorting or filtering in a table. People scan the result, not the transition.
+- Anything that blocks the next action: never make people wait for an animation to finish before they can click or type.
+- Decoration: entrance animations on page load, gradients that drift, icons that wiggle to get attention.
+- Showing that AI is working when the result is under about one second away; show the result.
+
+## Guidelines
+
+- Hover, press and colour changes: --duration-fast (120ms).
+- Tabs, menus, state swaps and small transforms such as a chevron turning: --duration-base (180ms).
+- Panels and layout that move, such as the side panel push or the sidebar collapsing: --duration-move (200ms) with --ease-move, matching shadcn's sheet.
+- Content swaps, height changes and progress fills: --duration-slow (260ms).
+- Figures rolling to a new value: --duration-long (480ms), only for values people read after the change, never for something they trigger many times a minute.
+- Exits are shorter than entrances and use --duration-exit with --ease-exit. Tooltips, hover cards and menus may disappear at once; nobody needs to watch them leave.
+- Match the exit to the entrance: what slid in from the right leaves to the right, what faded in fades out.
+- Direction follows the action. Going deeper (opening a record, the next step) moves forward; going back moves back.
+- Contextual UI grows from its trigger: a menu or popover opens from the button that opened it. Global UI such as the command palette and toasts has no trigger to connect to.
+- Loops (spinner 0.8s, thinking pulse 1.2s, skeleton shimmer 1.4s) always sit next to text such as 'Searching listings', and stop once content arrives. Theme tempo does not scale them.
+- Animate with the tokens, never with raw values, so a theme tempo change reaches every animation: duration-(--duration-base) ease-(--ease-standard) in a class, var(--duration-base) in CSS.
+- Tune motion for a whole product in the theme file: motion.tempo from 0.75 (quicker) to 1.25 (calmer) scales every duration token, and motion.character "crisp" removes the overshoot from pops. Never retime one component on one page.
+- Streamed text appears without a typing animation or cursor blink; under reduced motion it arrives in sentences or paragraphs rather than word by word.
+
+## Accessibility
+
+- Under prefers-reduced-motion: reduce, TwoUX sets every transition and animation to 0ms, so changes happen at once. Values that change in place, such as a progress fill, jump straight to the new value.
+- WCAG 2.3.3 (AAA) asks that interaction-triggered motion can be disabled; TwoUX meets it through the operating-system setting, with no extra control to find.
+- Because the reduced-motion rule also stops spinners, every loading state must have text that says what is happening.
+- Nothing flashes more than three times a second.
+- Test every view with reduced motion turned on, on a laptop and on a touch screen.
+
+## Do
+
+- Animate a spatial change, such as a panel sliding in, so people see where it came from.
+- Use the fast band for small interactions and the move or slow band for layout changes.
+- Leave faster than you arrive.
+- Change tempo in the theme file when the whole product should feel calmer or quicker.
+
+## Don't
+
+- Don't animate hover on rows or menu items, or make any frequent interaction lag.
+- Don't use bounce, spring or scale-up entrances; the only overshoot is a count that changes.
+- Don't go above 300ms for anything people trigger often, or make people wait for an animation before acting.
+- Don't move something in a way that contradicts where it came from or where it goes.
+
+## Tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `--duration-fast` | `120ms × tempo` | Hover, press, colour, small controls |
+| `--duration-base` | `180ms × tempo` | Tabs, menus, state swaps, small transforms |
+| `--duration-move` | `200ms × tempo` | Panels and layout that move (side panel, sidebar) |
+| `--duration-slow` | `260ms × tempo` | Content swaps, height changes, progress fills |
+| `--duration-long` | `480ms × tempo` | Figures rolling to a new value only |
+| `--duration-exit` | `= --duration-fast` | Anything leaving |
+| `--ease-standard` | `cubic-bezier(0.22, 1, 0.36, 1)` | State changes in place: swaps, numbers, heights, fills |
+| `--ease-entrance` | `cubic-bezier(0.22, 1, 0.36, 1)` | Something arriving |
+| `--ease-move` | `cubic-bezier(0.4, 0, 0.2, 1)` | Something moving between two places |
+| `--ease-exit` | `cubic-bezier(0.4, 0, 1, 1)` | Something leaving. Never overshoots |
+| `--ease-pop` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | A count that changes. Standard character only; crisp uses --ease-standard |
+| `--motion-tempo` | `1 (0.75 to 1.25)` | Set by motion.tempo in the theme file. Scales every duration token |
+| `--ease-out, --ease-in-out, --ease-soft, --ease-spring` | `aliases` | Earlier names for entrance, move, standard and pop. Kept for existing code |
+
+## Related
+
+- Accessibility
+- Shape and elevation
+- Design tokens

package/agent/docs-md/navigation.md

@@ -0,0 +1,76 @@
+# Navigation: what goes in the sidebar and the top bar
+
+The sidebar holds where you can go and the few things you always need; the top bar holds where you are and what this page does. Records never become sidebar items.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Without a rule, global links land in page headers, record pages add themselves to the sidebar, and every feature adds a top-level item. People lose track of where they are and the sidebar turns into a site map.
+
+**Solution:** One app shell. The sidebar has three parts: the workspace menu with Search (⌘K) and Inbox at the top, the main sections in the middle, and Settings and Help at the bottom. The top bar shows the breadcrumb and page-level controls only. One sidebar item is always active, including on record pages.
+
+**Built from:** App shell and sidebar navigation, Breadcrumb, Page header, Command palette (⌘K), Inbox (triage), Saved views, Keyboard shortcut hint
+
+## How it works
+
+1. Top of the sidebar: the workspace menu (switch workspace, your profile, Preferences, Sign out last), then Search (⌘K) and Inbox with its count.
+2. Middle: the main sections, ordered by how often a hiring team uses them: Home, Listings, Candidates, Interviews, Reports. Saved views sit under their section.
+3. Bottom: Settings and Help, set apart by space or a divider.
+4. Top bar: breadcrumb on the left, page-level controls such as the side panel toggle on the right. No global destinations.
+5. On a record page, the record's type stays active in the sidebar: viewing Priya Shah keeps Candidates active.
+
+## When to use
+
+- For every screen inside the product.
+- When adding a new area: add a sidebar item only if people go there on its own, not only through a record.
+- When placing account and workspace utilities such as profile, preferences, Search and Inbox.
+
+## When not to use
+
+- Not for sign-in, public careers pages or marketing pages. They have their own simple frame.
+- Don't use the sidebar for actions. Create listing lives in the Listings page header, not the sidebar.
+- Not for moving between records in a list. Use J and K with the side panel, as Record detail describes.
+
+## Guidelines
+
+- Organise by the team's tasks and the things they manage, not by a site map. Create, edit and settings pages for one record are reached from the record, never from the sidebar.
+- Two levels at most. Deeper pages are reached through links in the page, and the breadcrumb shows the way back.
+- Group only when it helps: no group with only two links, and don't mix headed groups with expandable items in one sidebar.
+- Sidebar labels, breadcrumb items and page titles use the same words.
+- Counts in the sidebar are for things that need action, like Inbox. Saved views may show their live row count. No decorative counts or static labels other than New or Beta.
+- The sidebar is either shown in full or hidden; TwoUX has no icon-only rail. When hidden, Inbox keeps a small button with its count in the top bar.
+- Every destination is also reachable from ⌘K, so the sidebar is never the only way.
+
+## Content
+
+- Section names are plural nouns for what they hold: "Listings", "Candidates". Not verbs or team jargon.
+- The workspace menu shows the workspace name and the person's name, so people with two workspaces know which one is open.
+- Breadcrumb items match sidebar labels: "Listings / Junior Product Designer".
+
+## Accessibility
+
+- The sidebar is a nav landmark named "Main"; the breadcrumb is a nav named "Breadcrumb".
+- The active item has aria-current="page"; its look does not rely on colour alone.
+- A skip link to the main content is the first focusable item on every page.
+- The order of sidebar items is the same on every page.
+
+## Do
+
+- Do keep one sidebar item active on every page.
+- Do order items from most to least used.
+- Do put profile, preferences and sign out in the workspace menu, with Sign out last.
+
+## Don't
+
+- Don't add a sidebar item when a record opens.
+- Don't put global links in the top bar or page header.
+- Don't add a top-level section for a feature people only reach from inside another one.
+
+## Related
+
+- App shell and sidebar navigation
+- Breadcrumb
+- Page header
+- Command palette (⌘K)
+- Keyboard-first navigation
+- Record detail: side panel, overlay or full page
+- Announcing new and beta features

package/agent/docs-md/notification-channels.md

@@ -0,0 +1,65 @@
+# Notifications: inbox, bell, toast or email digest
+
+Route every message by one question: does it need this person to act? Things that need you go to the Inbox; your own results go in a toast; nothing gets a separate bell list.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Products grow a bell, an inbox, toasts, banners and emails that overlap, so people get the same news three times and miss the one that needed them.
+
+**Solution:** The Inbox is the one place for things that need you (agent approvals and questions, listings about to close, mentions, assignments). Toasts only confirm your own actions. Workspace-wide problems use a banner. Email sends a digest of open Inbox items to people who are away.
+
+**Built from:** Inbox (triage), Toast, Banner (inline alert), Notifications vs inbox vs toast, App shell and sidebar navigation, Agent run timeline
+
+## How it works
+
+1. Did this person just do it? Confirm with a toast, or with nothing if the change is already visible.
+2. Does it need this person to act or reply? Put it in the Inbox. It stays until marked done (E) or snoozed (⇧H).
+3. Does it affect everyone's use of the workspace, such as a broken connection? Show a banner on the affected pages until fixed.
+4. Is the person away from TwoUX and is something waiting on them? Send an email digest of open Inbox items, at the frequency they chose.
+5. Needs nothing from anyone? Record it in the record's activity only.
+
+## When to use
+
+- Whenever a feature wants to tell someone something. Pick the channel with the steps above before designing the message.
+
+## When not to use
+
+- For validation of what someone typed. Use field messages from Inline editing and validation.
+- For errors that need a retry. A toast disappears and cannot hold Retry reliably; use a banner or the error state.
+
+## Guidelines
+
+- No separate bell list. The Inbox count is the only unread count; when the sidebar is hidden, a small inbox button with the same count replaces it.
+- Toasts never carry critical warnings or errors and never auto-dismiss something the person must act on.
+- Don't resend notifications people have not acted on; let them set email frequency and channels.
+- Trivial updates go nowhere but activity. Notification fatigue makes people ignore the important ones.
+
+## Content
+
+- Toasts are past tense and short: "Listing published". Three lines at most.
+- Banners say what is affected and what to do: "Workable is disconnected. Reconnect to keep importing candidates."
+
+## Accessibility
+
+- Toasts and count changes are announced as status messages.
+- Toasts must not cover the focused element; they appear in an empty corner.
+- Anything shown only in a vanishing toast must also be findable elsewhere, such as activity or the Inbox.
+
+## Do
+
+- Do send everything that needs action to the Inbox.
+- Do give people control over email frequency.
+
+## Don't
+
+- Don't add a bell next to the Inbox.
+- Don't use a toast for errors that need a follow-up.
+
+## Related
+
+- Agents acting on your behalf
+- Undo and destructive actions
+- Empty, loading and error states
+- Inbox (triage)
+- Toast
+- Banner (inline alert)

package/agent/docs-md/notifications-decision.md

@@ -0,0 +1,100 @@
+# Notifications vs inbox vs toast
+
+The rule for where a message goes: toast for your own action, banner for a condition on this page, inbox for anything that needs you later, activity for the rest.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- Designing any new message, to choose its component before writing it.
+- Reviewing a screen that shows several messages at once, to remove the ones that belong elsewhere.
+
+## When not to use
+
+- Field-level validation, which always sits next to the field. Use inline field errors and the Banner strip.
+- Loading feedback. Use the Loading skeleton or an inline spinner.
+
+## Structure
+
+1. Question 1: did the person just do this, here? Toast
+2. Question 2: is it a condition on the page in view? Banner
+3. Question 3: does it need someone to act, now or later? Inbox
+4. Question 4: must it stop the task before it continues? Confirmation dialog
+5. Otherwise: the record's Activity tab, no message
+
+## Guidelines
+
+- Toast: passive confirmation of the person's own action in the current view; disappears; may carry Undo.
+- Banner: a condition in context that persists until resolved; may carry one action.
+- Inbox: events the person did not trigger, or that complete later, that need a response; persists until done or snoozed.
+- Confirmation dialog: only when the task must stop for a decision that cannot be undone.
+- Activity: events that need nothing. Logging them instead of notifying prevents alert fatigue.
+- Errors never go in a toast.
+- Keep event notifications people didn't trigger (reminders, assignments) apart from toasts. Notifications get their own component, which comes in at the top right and can stack, separate from toasts.
+
+## Content
+
+- Whatever the component, say what happened and what to do next, in sentence case, without apologies.
+- Use the same name for the same record across toast, inbox and activity.
+
+## Accessibility
+
+- Toasts use role="status"; blocking errors use role="alert"; the dialog uses role="alertdialog" (4.1.3).
+- Only dialogs take focus; everything else is announced without moving focus.
+- Nothing important is only in a timed message (2.2.1); the Inbox and Activity keep a permanent record.
+- Non-urgent updates can be postponed by the person (snooze), which supports 2.2.4 Interruptions.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ⌘Z | Undo after a toast |
+| G I | Open the Inbox |
+
+## Examples
+
+### choose
+
+```tsx
+import { Badge, RadioField, RadioGroup } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Where should this message go?", description: "Answer in order. The first yes decides: toast, banner, Inbox or confirmation dialog. If none apply, log it in the record's Activity and send nothing.", order: 1 };
+
+const Q = [
+	{ id: "own", q: "Did the person just do this, here?", yes: "Toast", why: "Confirms their own action and disappears; can carry Undo." },
+	{ id: "cond", q: "Is it a condition on the page in view?", yes: "Banner", why: "Stays in context until resolved; at most one action." },
+	{ id: "act", q: "Does it need someone to act, now or later?", yes: "Inbox", why: "Persists until done or snoozed, even if they weren't here." },
+	{ id: "stop", q: "Must it stop the task before it continues?", yes: "Confirmation dialog", why: "Only when the decision can't be undone." },
+];
+
+export default function Example() {
+	const [answers, setAnswers] = useState<Record<string, string>>({});
+	const first = Q.find((q) => answers[q.id] === "yes");
+	const allNo = Q.every((q) => answers[q.id] === "no");
+	return (
+		<div className="grid w-full max-w-xl gap-3">
+			{Q.map((q, i) => (
+				<fieldset key={q.id} className="grid gap-1.5 rounded-sm border border-line bg-surface p-3" disabled={i > 0 && answers[Q[i - 1].id] !== "no"}>
+					<legend className="sr-only">{q.q}</legend>
+					<span className="text-base font-medium text-ink">{i + 1}. {q.q}</span>
+					<RadioGroup value={answers[q.id] ?? ""} onValueChange={(v) => setAnswers((a) => ({ ...Object.fromEntries(Object.entries(a).filter(([k]) => Q.findIndex((x) => x.id === k) < i)), [q.id]: v }))} className="flex gap-4">
+						<RadioField id={`${q.id}-y`} value="yes" label="Yes" />
+						<RadioField id={`${q.id}-n`} value="no" label="No" />
+					</RadioGroup>
+				</fieldset>
+			))}
+			<p role="status" className="flex items-center gap-2 text-base text-ink-2">
+				{first ? <><Badge>{first.yes}</Badge>{first.why}</> : allNo ? <><Badge variant="secondary">Activity only</Badge>Log it on the record; don't notify anyone.</> : "Answer the questions in order."}
+			</p>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Toast
+- Banner (inline alert)
+- Inbox (triage)
+- Confirmation dialog

package/agent/docs-md/onboarding-step.md

@@ -0,0 +1,114 @@
+# Onboarding step
+
+One step of first-run setup on a plain page: why we ask, the fields, which step this is, and Back, Skip and Continue.
+
+Kind: component · Group: Navigation · Status: built, import from @twoux/ui
+
+## When to use
+
+- A few setup steps that the product cannot guess, such as workspace name and who to invite.
+- Steps that depend on each other, where each answer shapes the next.
+
+## When not to use
+
+- Teaching the product with a tour or video. Show it in the product and use contextual help (workspace-onboarding).
+- A long form. Ask only what is needed to start and let people finish the rest later in Settings.
+
+## Structure
+
+1. "Step n of N" text (with Optional when it is)
+2. Heading (receives focus)
+3. Why we ask, in one line
+4. Fields
+5. Back, Skip (optional steps), Continue
+6. Progress dots (decoration only)
+7. Aside panel (optional, wide screens)
+
+## Guidelines
+
+- Keep it to a few steps. Each step says why it asks.
+- Optional steps say Optional and offer Skip. Required steps do not offer it.
+- Never disable Continue. Validate when it is pressed and put the error under the field.
+- Say "Step 2 of 5" in text. Dots alone do not tell people how much is left.
+- Move focus to the heading when the step changes, so a screen reader says where the person is.
+- Use a plain background. No gradients, no illustration, no auto-playing video.
+- Keep what was entered when going Back. Never ask for the same thing twice.
+
+## Content
+
+- Heading: a short question or task, such as "Name your workspace".
+- Why line: "Teammates see this name when you invite them."
+- Skip, not "Do this later" or "Not now", on optional steps.
+
+## Accessibility
+
+- The "Step n of N" text is real text; the dots are hidden from assistive technology (SC 1.4.1).
+- The heading has tabindex -1 and receives focus on each step; the section is labelled by it (SC 2.4.3, 2.4.6).
+- Errors are shown under the field and linked to it (SC 3.3.1).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move through the fields, Back, Skip and Continue in order |
+| Enter | In a text field, press Continue |
+| Shift+Tab | Move back, starting from the heading on a new step |
+
+## Examples
+
+### workspace-setup
+
+```tsx
+import { Field, FieldDescription, FieldError, FieldLabel, Input, OnboardingStep } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Set up a workspace", description: "Three steps. The name is required, inviting is optional. What was typed stays when you go Back.", order: 1 };
+
+export default function Example() {
+	const [step, setStep] = useState(1);
+	const [name, setName] = useState("");
+	const [invites, setInvites] = useState("");
+	const [error, setError] = useState("");
+	const next = () => {
+		if (step === 1 && !name.trim()) { setError("Enter a name for your workspace, for example TwoUX."); return; }
+		setError("");
+		setStep((s) => Math.min(3, s + 1));
+	};
+	return (
+		<div className="flex w-full justify-center">
+			{step === 1 && (
+				<OnboardingStep step={1} total={3} title="Name your workspace" description="Teammates see this name when you invite them." onContinue={next}>
+					<Field data-invalid={!!error || undefined}>
+						<FieldLabel htmlFor="ws-name">Workspace name</FieldLabel>
+						<Input id="ws-name" value={name} aria-invalid={!!error || undefined} autoComplete="organization" onChange={(e) => { setName(e.target.value); setError(""); }} />
+						{error && <FieldError>{error}</FieldError>}
+					</Field>
+				</OnboardingStep>
+			)}
+			{step === 2 && (
+				<OnboardingStep step={2} total={3} title="Invite your team" description="They get an email with a link. You can also do this later in Settings." optional onBack={() => setStep(1)} onSkip={() => setStep(3)} onContinue={next}>
+					<Field>
+						<FieldLabel htmlFor="ws-invites">Email addresses</FieldLabel>
+						<Input id="ws-invites" type="email" value={invites} placeholder="sam@twoux.example" onChange={(e) => setInvites(e.target.value)} />
+						<FieldDescription>Separate several addresses with commas.</FieldDescription>
+					</Field>
+				</OnboardingStep>
+			)}
+			{step === 3 && (
+				<OnboardingStep step={3} total={3} title="You are ready" description={`${name || "Your workspace"} is set up.`} continueLabel="Open workspace" onBack={() => setStep(2)} onContinue={() => setStep(1)}>
+					<p className="text-base text-ink-2">{invites ? `An invitation will go to ${invites}.` : "You have not invited anyone yet."}</p>
+				</OnboardingStep>
+			)}
+		</div>
+	);
+}
+```
+
+## Related
+
+- Onboarding to an empty workspace
+- Stepper
+- Text input
+- Form validation
+- Setup checklist
+- Sign in

package/agent/docs-md/order-book.md

@@ -0,0 +1,108 @@
+# Order book
+
+Resting sell and buy orders either side of the spread, each with a bar for the running total, so people see where the price is likely to meet resistance and can pick a price to trade at.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- A trading screen where people place limit orders and need the prices other people are offering.
+- Showing how much can be bought or sold before the price moves, through the running totals.
+
+## When not to use
+
+- For a price over time. Use the TwoUX Candlestick chart or Price chart.
+- For a short list of prices with today's change. Use the TwoUX Change list.
+
+## Structure
+
+1. Group by: − and + to widen or narrow price groups
+2. Column headings with units: Price, Amount, Total
+3. Sell orders above, best (lowest) price next to the spread
+4. Middle line: last price with its direction, and the spread
+5. Buy orders below, best (highest) price next to the spread
+6. Depth bar behind each row: running total against the deeper side
+
+## Guidelines
+
+- Sells above, buys below, best prices next to the spread; side is carried by position, the row's name and colour together.
+- Sell prices are red and buy prices green, the way depth charts draw asks and bids.
+- Bars show the running total against the deeper side, so walls stand out.
+- Choosing a row puts its price in the order form; it never places an order.
+- Rows keep their place as prices update and never flash; only the values change.
+- Group sell prices up and buy prices down, so a group never shows a better price than its orders.
+
+## Content
+
+- Put the unit in each heading: Price (USDC), Amount (BTC).
+- Say Spread, not a symbol, and give it in the price's unit.
+
+## Accessibility
+
+- 1.4.1 Use of Color: each row is named Sell or Buy with its amount, price and total, and the two sides are separate lists.
+- 2.1.1 Keyboard: the book is one tab stop; arrow keys move between rows and Enter uses the price.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the book |
+| ↑ ↓ | Move to the previous or next price |
+| Page Up Page Down | Move five prices |
+| Home End | Jump to the first or last price |
+| Enter Space | Use the price in the order form |
+
+## Examples
+
+### live
+
+```tsx
+import { OrderBook, type OrderLevel, TextField } from "@twoux/ui";
+import { useMemo, useState } from "react";
+
+export const meta = { title: "Pick a price for the order form", description: "Sells above and buys below the spread, each row's bar showing the running total. Choose a row, by click or with the arrow keys and Enter, to put its price in the limit price field. The − and + buttons group prices.", order: 1 };
+
+// Levels from a seeded random sequence, so the book looks real and stays the same on every load.
+function levels(mid: number, dir: 1 | -1, seed: number): OrderLevel[] {
+	const rand = () => ((seed = (seed * 16807) % 2147483647) / 2147483647);
+	return Array.from({ length: 40 }, (_, i) => ({ price: mid + dir * 0.4 * (i + 1) * (1 + rand()), amount: Number((rand() ** 3 * 0.9 + 0.0002).toFixed(5)) }));
+}
+const money = (n: number) => n.toLocaleString("en-GB", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+const coin = (n: number) => n.toLocaleString("en-GB", { minimumFractionDigits: 5, maximumFractionDigits: 5 });
+const STEPS = [0.01, 0.1, 1, 10];
+
+export default function Example() {
+	const asks = useMemo(() => levels(70_237.17, 1, 11), []);
+	const bids = useMemo(() => levels(70_237.17, -1, 29), []);
+	const [step, setStep] = useState(0.01);
+	const [limit, setLimit] = useState("");
+	return (
+		<div className="grid w-full max-w-3xl gap-6 sm:grid-cols-[18rem_1fr]">
+			<OrderBook
+				aria-label="BTC-USDC order book"
+				asks={asks}
+				bids={bids}
+				rows={8}
+				format={money}
+				formatAmount={coin}
+				priceLabel="Price (USDC)"
+				amountLabel="Amount (BTC)"
+				step={step}
+				steps={STEPS}
+				onStepChange={setStep}
+				last={{ price: 70_237.17, direction: "up" }}
+				onSelectPrice={(p) => setLimit(p.toFixed(2))}
+			/>
+			<div className="grid content-start">
+				<TextField label="Limit price" suffix="USDC" inputMode="decimal" value={limit} onChange={(e) => setLimit(e.target.value)} hint="Choose a row in the order book to use its price." />
+			</div>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Candlestick chart
+- Change list
+- Price chart

package/agent/docs-md/page-header.md

@@ -0,0 +1,96 @@
+# Page header
+
+The page title on the left and its actions on the right, with exactly one primary action per view.
+
+Kind: component · Group: Navigation · Status: built, import from @twoux/ui
+
+## When to use
+
+- At the top of every page in the canvas, to name the page and hold actions that affect the whole page.
+- When a page has a main next step, such as creating a listing.
+
+## When not to use
+
+- Actions on selected rows. Use the bulk action bar.
+- Actions on one record shown in the side panel. Use the panel's footer.
+- Global tools such as search or Ask. Those live in the top bar of the App shell.
+
+## Structure
+
+1. Title (h1)
+2. Actions, right-aligned: secondary actions ("Export ⇧E") then the one primary action ("New listing C")
+3. Optional: view tabs below (All 24, Live 14, Drafts 3, Closed 7)
+
+## Guidelines
+
+- One primary button per view; every other action is secondary or in a menu.
+- The primary action sits rightmost, nearest the content edge, with secondary actions to its left.
+- Each button shows its shortcut (C, ⇧E) so people learn it by using it.
+- Three actions at most in the header; more go into a menu.
+- Title and actions wrap to two lines on narrow widths rather than truncating.
+- View tabs (segmented counts) sit under the title and filter the same data; they are not navigation.
+
+## Content
+
+- Title is a short noun in sentence case that matches the sidebar item: "Listings".
+- Action labels start with a verb and name the object: "New listing", "Export".
+- Tab labels are one or two words with a count.
+
+## Accessibility
+
+- The title is the page's only h1 and matches the document title (2.4.2, 2.4.6).
+- Shortcut hints are part of the button's accessible description, not its name, so voice users can say the label (4.1.2).
+- Buttons are at least 24px tall (28 to 32px in TwoUX) (2.5.8).
+- After navigation, focus can be moved to the title so screen reader users start at the page (2.4.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| C | Primary create action (New listing) |
+| ⇧E | Export |
+| Tab | Move from title area to actions, left to right |
+
+## Examples
+
+### listings
+
+```tsx
+import { Button, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, PageHeader, Tabs, TabsList, TabsTrigger } from "@twoux/ui";
+import { Download, Ellipsis, Plus } from "lucide-react";
+
+export const meta = { title: "Title, actions and view tabs", description: "The one primary action sits rightmost with its shortcut; secondary actions to its left; anything beyond three goes in a menu. Title and actions wrap rather than truncate.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="w-full rounded-sm border border-line bg-surface">
+			<PageHeader
+				title="Listings"
+				description="24 listings across 6 teams"
+				actions={
+					<>
+						<DropdownMenu>
+							<DropdownMenuTrigger asChild><Button variant="ghost" size="icon" aria-label="More actions"><Ellipsis /></Button></DropdownMenuTrigger>
+							<DropdownMenuContent align="end"><DropdownMenuItem>Import from CSV</DropdownMenuItem><DropdownMenuItem>Archive closed listings</DropdownMenuItem></DropdownMenuContent>
+						</DropdownMenu>
+						<Button variant="outline" shortcut="⇧E"><Download />Export</Button>
+						<Button shortcut="C"><Plus />New listing</Button>
+					</>
+				}
+				tabs={
+					<Tabs defaultValue="all">
+						<TabsList aria-label="Views"><TabsTrigger value="all" count={24}>All</TabsTrigger><TabsTrigger value="live" count={14}>Live</TabsTrigger><TabsTrigger value="drafts" count={3}>Drafts</TabsTrigger><TabsTrigger value="closed" count={7}>Closed</TabsTrigger></TabsList>
+					</Tabs>
+				}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- App shell and sidebar navigation
+- Breadcrumb
+- Command palette (⌘K)
+- Shortcut sheet (?)