@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/timeline.md

@@ -0,0 +1,189 @@
+# Timeline
+
+Scheduled work across a few tracks on one time ruler, such as releases and maintenance per service or hiring campaigns per team. Spans and instants, a labelled Now line, four zoom levels; selecting an event opens it in the side panel.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- Seeing what runs in parallel across services, teams or resources, such as release and maintenance windows, and where it overlaps.
+- Planning or reviewing phases with a start and an end, such as hiring campaigns per team, with deadlines as instants.
+
+## When not to use
+
+- For what happened, one item after another, in one stream. Use the Agent activity log or a Grouped list.
+- For amounts over time. Use the Line chart card or a Bar chart.
+- For editing dates by dragging. The Timeline is read-only; change dates in the record's side panel.
+- For more than about 12 tracks or when people compare exact dates. Use a List table with start and end columns.
+
+## Structure
+
+1. Toolbar: period, Go to now, zoom
+2. Ruler with UK date ticks
+3. Sticky track label column
+4. Spans (start to end) and instants (diamond)
+5. Lanes for overlapping events in a track
+6. Now line labelled with the time
+7. Tooltip: track, status word, start, end, length
+
+## Guidelines
+
+- Keep to about 12 tracks and one period people plan in, such as two weeks or a quarter.
+- Give every event a status word with statusLabel (Done, At risk, Blocked); the tint repeats it, never replaces it.
+- Selecting an event opens its record in the SidePanel; pass its id back as selectedId so the timeline marks it.
+- Pass now for current and future periods; leave it out for past ones. Go to now appears only when Now is in the period.
+- Offer the zoom levels that fit the period with zooms: hour and day for a week, week and month for a quarter.
+- Wrap it in ChartFrame for the title, the Table view (timelineTable) and the loading, error and no match states.
+
+## Content
+
+- Dates are UK format, "Wed 11 Nov, 09:00"; the tooltip and table give the full date with zone, as Timestamp does.
+- Name tracks with nouns (Payments API, Engineering) and events by what happens (Release 4.13, Database upgrade).
+
+## Accessibility
+
+- 2.1.1 Keyboard and the APG grid: one tab stop, arrow keys move between events, Enter or Space opens one.
+- Each event is a gridcell named "Label, track, start to end, status"; each track is a row with a row header.
+- 1.4.1 Use of Color: status is a word in the tooltip, accessible name and table view, not the tint alone.
+- 1.4.10 Reflow: only the time area scrolls, inside its own box, with the track column sticky.
+- 2.1.4 Character Key Shortcuts: + and − zoom only while the timeline has focus.
+- 1.1.1 and complex images: a description gives tracks, events, period and current time, and the Table view lists every event.
+- 1.4.13 Content on Hover or Focus: the tooltip follows hover and focus and closes with Esc.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the timeline |
+| ← → | Previous or next event in the track |
+| ↑ ↓ | Nearest event in time on the track above or below |
+| Home End | First or last event in the track (with Ctrl, overall) |
+| Enter Space | Open the event in the side panel |
+| + − | Zoom in or out (off when single-key shortcuts are turned off) |
+| Esc | Clear the focused event and hide the tooltip |
+
+## Examples
+
+### hiring-campaigns
+
+```tsx
+import { ChartFrame, ChartStatus, Segment, SegmentedControl, Timeline, TimelineTrack, timelineTable } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Hiring campaign phases by team", description: "A quarter of hiring campaigns at month and week zoom, with closing dates as instants. The state control shows the frame's loading, empty and error states.", order: 2 };
+
+const TRACKS: TimelineTrack[] = [
+	{ id: "eng", label: "Engineering", events: [
+		{ id: "c1", label: "Sourcing: backend", start: "2026-10-05", end: "2026-10-30", status: "ok", statusLabel: "Done" },
+		{ id: "c2", label: "Interviews: backend", start: "2026-10-26", end: "2026-11-27", status: "warn", statusLabel: "Behind plan" },
+		{ id: "c3", label: "Offers close", start: "2026-12-04", status: "neutral", statusLabel: "Planned" },
+	] },
+	{ id: "sales", label: "Sales", events: [
+		{ id: "c4", label: "Account executives, London", start: "2026-10-12", end: "2026-12-11", status: "ok", statusLabel: "On track" },
+		{ id: "c5", label: "SDR graduate intake", start: "2026-11-16", end: "2026-12-18", status: "neutral", statusLabel: "Planned" },
+	] },
+	{ id: "support", label: "Customer support", events: [
+		{ id: "c6", label: "Weekend cover", start: "2026-10-19", end: "2026-11-13", status: "bad", statusLabel: "Paused" },
+		{ id: "c7", label: "Listing closes", start: "2026-11-13", status: "bad", statusLabel: "Paused" },
+	] },
+	{ id: "finance", label: "Finance", events: [
+		{ id: "c8", label: "Financial controller", start: "2026-11-02", end: "2026-12-23", status: "ok", statusLabel: "On track" },
+	] },
+];
+
+export default function Example() {
+	const [state, setState] = useState<ChartStatus>("ready");
+	return (
+		<div className="grid w-full gap-2">
+			<SegmentedControl size="sm" value={state} onValueChange={(v) => setState(v as ChartStatus)} aria-label="Example state" className="justify-self-start">
+				<Segment value="ready">Data</Segment><Segment value="loading">Loading</Segment><Segment value="error">Error</Segment>
+			</SegmentedControl>
+			<ChartFrame className="w-full" title="Hiring campaigns" description="Q4 2026, all teams" status={state} onRetry={() => setState("ready")} table={timelineTable(TRACKS)} height={200}>
+				<Timeline tracks={TRACKS} start="2026-10-01" end="2027-01-01" now="2026-11-11T09:00" defaultZoom="week" zooms={["week", "month"]} aria-label="Hiring campaigns" />
+			</ChartFrame>
+		</div>
+	);
+}
+```
+
+### release-schedule
+
+```tsx
+import { Badge, Button, ChartFrame, SidePanel, Timeline, TimelineEvent, TimelineTrack, timelineDate, timelineTable } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Releases and maintenance by service", description: "Two weeks of releases, maintenance windows and freezes across five services. Select an event, or press Enter on it, to open it in the side panel; + and − zoom.", order: 1 };
+
+const TRACKS: TimelineTrack[] = [
+	{ id: "payments", label: "Payments API", events: [
+		{ id: "REL-412", label: "Release 4.12", start: "2026-11-10T09:00", end: "2026-11-10T11:00", status: "ok", statusLabel: "Done" },
+		{ id: "MNT-88", label: "Database upgrade", start: "2026-11-12T22:00", end: "2026-11-13T02:00", status: "warn", statusLabel: "At risk" },
+		{ id: "REL-413", label: "Release 4.13", start: "2026-11-17T09:00", end: "2026-11-17T10:30", status: "neutral" },
+	] },
+	{ id: "billing", label: "Billing", events: [
+		{ id: "FRZ-11", label: "Month-end freeze", start: "2026-11-16T00:00", end: "2026-11-19T00:00", status: "neutral", statusLabel: "Scheduled" },
+		{ id: "REL-207", label: "Invoice PDF fix", start: "2026-11-11T13:00", status: "ok", statusLabel: "Deployed" },
+	] },
+	{ id: "auth", label: "Identity", events: [
+		{ id: "MNT-91", label: "Certificate rotation", start: "2026-11-11T06:00", end: "2026-11-11T08:00", status: "ok", statusLabel: "Done" },
+		{ id: "REL-330", label: "SSO for Okta", start: "2026-11-11T12:00", end: "2026-11-12T18:00", status: "bad", statusLabel: "Blocked" },
+	] },
+	{ id: "search", label: "Search", events: [
+		{ id: "MNT-93", label: "Index rebuild", start: "2026-11-14T01:00", end: "2026-11-14T07:00", status: "neutral" },
+		{ id: "REL-119", label: "Ranking change", start: "2026-11-18T10:00", status: "warn", statusLabel: "Needs review" },
+	] },
+	{ id: "web", label: "Web app", events: [
+		{ id: "REL-905", label: "Weekly release", start: "2026-11-12T10:00", end: "2026-11-12T12:00", status: "ok", statusLabel: "On track" },
+		{ id: "REL-906", label: "Weekly release", start: "2026-11-19T10:00", end: "2026-11-19T12:00", status: "neutral" },
+	] },
+];
+const VARIANT = { ok: "success", warn: "warning", bad: "destructive", neutral: "secondary" } as const;
+
+export default function Example() {
+	const [open, setOpen] = useState<{ e: TimelineEvent; track: string } | null>(null);
+	return (
+		<div className="flex w-full overflow-hidden rounded-sm border border-line bg-surface">
+			<div className="min-w-0 flex-1 p-3">
+				<ChartFrame className="w-full" title="Releases and maintenance" description="All services, 9 to 22 November" table={timelineTable(TRACKS)} height={260}>
+					<Timeline
+						tracks={TRACKS}
+						start="2026-11-09T00:00"
+						end="2026-11-23T00:00"
+						now="2026-11-11T14:30"
+						defaultZoom="day"
+						zooms={["hour", "day", "week"]}
+						selectedId={open?.e.id ?? null}
+						onSelect={(e, t) => setOpen({ e, track: t.label })}
+						aria-label="Releases and maintenance"
+					/>
+				</ChartFrame>
+			</div>
+			{open && (
+				<SidePanel
+					open
+					onOpenChange={(o) => !o && setOpen(null)}
+					label="Change details"
+					title={open.e.label}
+					meta={<span className="flex items-center gap-2"><span className="font-mono">{open.e.id}</span><Badge variant={VARIANT[open.e.status ?? "neutral"]}>{open.e.statusLabel ?? "Planned"}</Badge></span>}
+					footer={<Button size="sm">Edit change</Button>}
+				>
+					<dl className="grid grid-cols-2 gap-x-3 gap-y-2 text-base">
+						<dt className="text-ink-2">Service</dt><dd className="text-ink">{open.track}</dd>
+						<dt className="text-ink-2">Starts</dt><dd className="text-ink">{timelineDate(new Date(open.e.start))}</dd>
+						<dt className="text-ink-2">Ends</dt><dd className="text-ink">{open.e.end ? timelineDate(new Date(open.e.end)) : "Same time"}</dd>
+					</dl>
+				</SidePanel>
+			)}
+		</div>
+	);
+}
+```
+
+## Related
+
+- Side panel (drawer)
+- List table
+- Agent activity log
+- Timestamp
+- Segmented control
+- Line chart card

package/agent/docs-md/timestamp.md

@@ -0,0 +1,84 @@
+# Timestamp
+
+One component for every date and time in the product: relative or absolute display, the exact value on hover and focus, and an optional "by" source.
+
+Kind: component · Group: Content · Status: built, import from @twoux/ui
+
+## When to use
+
+- Every time a date or time appears: table columns, side panel details, activity, Inbox items, "Last updated" after a refresh.
+- format="relative" for recent past events in lists; format="absolute" for details and deadlines; format="iso" for code and exports.
+- source="Priya Shah" when it matters who made the change, such as Last edited on a listing.
+
+## When not to use
+
+- For date entry. Use a date input.
+- For durations, such as "Time to hire: 18 days"; that is a number with a unit, not a timestamp.
+- For a date with no time that is a property of the record, such as a start date. Show it as an absolute date.
+
+## Structure
+
+1. Optional label, when not given by a column header or key: "Last edited"
+2. Value: relative ("3 hours ago") or absolute ("6 November 2026, 14:32 GMT")
+3. Optional source: "by Priya Shah", linked to the profile, with "via Assistant" when applied from a proposal
+4. Tooltip with the absolute value on hover and focus
+
+## Guidelines
+
+- Renders a <time> element with the ISO 8601 value in datetime.
+- Relative values tick over once a minute; they never animate or announce.
+- Time zone is the viewer's own and is always shown on absolute values.
+- In compact table cells, `short` shows "3h ago" or "20 Nov"; the tooltip and accessible name keep the full form.
+- Future deadlines use absolute dates, optionally followed by relative time in muted text.
+- Give deadlines, start dates and due dates as a date with no time (2026-12-07). They show as 7 December 2026, with no time or zone, and fall on the same day in every time zone.
+
+## Content
+
+- Relative: "Just now", "5 minutes ago", "3 hours ago", "2 days ago", "In 3 days".
+- Absolute: day, month in full, year, 24-hour time, zone: "6 November 2026, 14:32 GMT".
+- Source: "Edited 6 hours ago by Priya Shah".
+
+## Accessibility
+
+- The accessible description carries the absolute value, so screen reader users don't need the tooltip.
+- The tooltip appears on focus of the cell or link that contains the timestamp, without adding a separate tab stop.
+- Never put a ticking relative time in a live region.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab or arrows (to the containing cell or link) | Show the absolute time tooltip |
+| Esc | Hide the tooltip |
+| Tab (to a source link) | Move to the person's profile link |
+
+## Examples
+
+### times
+
+```tsx
+import { Timestamp } from "@twoux/ui";
+
+export const meta = { title: "Relative, short and absolute", description: "Relative in lists, with the full date and time zone on hover or focus. Short units in compact cells. Deadlines are always absolute.", order: 1 };
+
+const ago = (m: number) => new Date(Date.now() - m * 60000);
+
+export default function Example() {
+	return (
+		<dl className="grid grid-cols-[160px_1fr] gap-x-4 gap-y-2 text-base">
+			<dt className="text-ink-2">Last edited</dt><dd><Timestamp value={ago(180)} by={<a href="#priya" className="font-medium text-primary-ink hover:underline">Priya Shah</a>} /></dd>
+			<dt className="text-ink-2">In a table cell</dt><dd><Timestamp value={ago(60 * 26)} short /></dd>
+			<dt className="text-ink-2">Closing date</dt><dd><Timestamp value="2026-12-04T17:00:00Z" format="absolute" /></dd>
+			<dt className="text-ink-2">Applied via Assistant</dt><dd><Timestamp value={ago(12)} by={<span>Tom Becker via Assistant</span>} /></dd>
+		</dl>
+	);
+}
+```
+
+## Related
+
+- Timestamps
+- List table
+- Side panel (drawer)
+- Tooltip
+- Unsaved changes

package/agent/docs-md/timestamps.md

@@ -0,0 +1,70 @@
+# Timestamps
+
+Show when things happened as relative time in lists ("3 hours ago"), the exact date and time on hover and in record details, and always say what the time refers to and who caused it.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** "12/03" means different days to different readers, times without a zone mislead remote teams, and a bare date in a column says nothing about whether it is when the listing was posted, edited or closes.
+
+**Solution:** Use the timestamp component everywhere. It renders relative time for past events in lists, absolute time in UK format in details and tooltips, and ISO 8601 in exports and code. Every timestamp has a label of noun and verb, and the person or system that made the change when it matters.
+
+**Built from:** Timestamp, List table, Side panel (drawer), Tooltip, Export menu
+
+## How it works
+
+1. Choose the format by the reader's need: how long ago (relative), exactly when (absolute), or a machine (ISO 8601).
+2. Label it with what happened: "Posted", "Last edited", "Applied". In a table the label is the column header.
+3. Add the source when it matters: "Edited 6 hours ago by Priya Shah", linked to their profile.
+4. Give every relative time its absolute value on hover and focus, and in the accessible name.
+
+## When to use
+
+- Relative: activity feeds, Applied and Last edited columns, the Inbox, "Last updated" after a refresh.
+- Absolute: the Details section of a record, audit history, and deadlines such as a listing's closing date.
+- ISO 8601: CSV exports, API responses and anything people paste into code.
+
+## When not to use
+
+- Relative time for deadlines. "Closes in 2 weeks" hides the actual day; show "Closes 20 November 2026", with "in 14 days" in muted text if useful.
+- Relative time for billing or usage periods; use the unit being counted, such as hours.
+- Durations such as time to hire. Show a number and unit ("18 days"), not a timestamp.
+
+## Guidelines
+
+- Relative units: "Just now" under a minute, then minutes, hours, days, weeks, months and years ago, in the largest whole unit.
+- Absolute format in the UK: "6 November 2026, 14:32 GMT" (BST in summer). Teammates in other time zones see their own zone, and the zone is always shown.
+- Spell months and units in full in details and tooltips: "November", "minutes". Omit the year in tables when it is the current year.
+- Relative times refresh about once a minute without announcing each change.
+- When the change came from an applied assistant proposal, the source is the person, with "via Assistant": "Edited 2 minutes ago by Priya Shah via Assistant".
+
+## Content
+
+- Labels are noun and verb, with no "date" or "time": "Listing posted", not "Posted date".
+- Past tense for things that happened ("Closed"), present or future for things to come ("Closes").
+- Add "Last" only for events that repeat: "Last edited", "Last updated".
+- In tables where rows start and end at different times, "[noun] [verb] time" is allowed: "Interview start time".
+
+## Accessibility
+
+- Render with <time datetime="2026-11-06T14:32:00Z"> using the ISO value, and the absolute human date in the tooltip and accessible description.
+- Don't rely on the title attribute for the absolute time; it is not available to keyboard or touch users. Use TwoUX's tooltip on focus and hover.
+- Relative times that update do not sit inside a live region.
+
+## Do
+
+- Do label every timestamp with its event.
+- Do show the time zone on every absolute time.
+- Do use ISO 8601 in exports.
+
+## Don't
+
+- Don't write numeric dates such as 06/11/2026; they read differently in the UK and US.
+- Don't abbreviate units: "5 minutes ago", not "5m ago", outside dense tables.
+- Don't show a relative deadline without the date.
+
+## Related
+
+- Empty, loading and error states
+- Record detail: side panel, overlay or full page
+- Data export
+- Timestamp

package/agent/docs-md/toast.md

@@ -0,0 +1,117 @@
+# Toast
+
+A short, non-blocking confirmation of something the person just did, with Undo when the action can be reversed.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- Confirm an action the person just took in the current view, such as publishing, extending or closing a listing.
+- Offer Undo right after a reversible change, so the change can go ahead without a confirmation dialog.
+- Confirm accelerated actions done by keyboard (T, D, E, ⇧C), where the person has no other visual cue that the key worked.
+
+## When not to use
+
+- Errors and anything the person must act on. Use an Error state in place, or a Banner on the page.
+- Events the person did not cause, such as an agent finishing or a listing about to close. Send them to the Inbox.
+- When the result is already visible on screen and there is nothing else to know, show nothing.
+- Irreversible, high-impact actions. Ask first with a Confirmation dialog.
+
+## Structure
+
+1. Status icon (check for success)
+2. Title: what happened, past tense
+3. Optional body: which record, one line
+4. Undo button (ghost, small)
+5. Live region container (role="status")
+
+## Guidelines
+
+- Place the toast at the bottom right, 16px from the edges, at most 340px wide, on a solid white surface. It rises above the focused element and anything marked data-toast-avoid, such as a sticky footer, so it never covers them.
+- Show one toast at a time. A new toast replaces the one on screen rather than stacking.
+- Hide it after 6 seconds. Pause the timer while the pointer is over the toast or focus is inside it.
+- Allow one action only, and only Undo. Never put a Close or Cancel button next to it.
+- Undo must also be reachable without the toast: ⌘Z undoes the last action for as long as the record allows.
+- Never move focus to the toast. The person keeps working where they were.
+
+## Content
+
+- Title in past tense saying what happened: "Listing published", "Snoozed until Mon 9:00".
+- Name the record in the body when the title alone is ambiguous: "Junior Product Designer is now live."
+- Sentence case, UK spelling, one short sentence, no exclamation marks and no "successfully".
+- Do not apologise or thank. Say the outcome and stop.
+
+## Accessibility
+
+- Render toasts into a role="status" live region that already exists in the DOM, so screen readers announce them without moving focus (4.1.3).
+- Because Undo disappears with the toast, the same undo is available through ⌘Z and the record's activity, which meets the intent of 2.2.1 Timing Adjustable.
+- The toast must not hide the focused element: TwoUX's Toaster measures the focused element and any data-toast-avoid element in its corner and moves up above them (2.4.11).
+- Do not rely on the green check alone: the title says the outcome in words (1.4.1).
+- Respect prefers-reduced-motion: the toast appears without sliding when motion is reduced (2.3.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ⌘Z | Undo the last action, whether or not the toast is still visible |
+| Tab | Reaches the Undo button while the toast is shown; the timer pauses while focus is inside |
+
+## Examples
+
+### undo
+
+```tsx
+import { Button, toast } from "@twoux/ui";
+import { useEffect, useState } from "react";
+
+export const meta = { title: "Confirm with Undo", description: "Close a listing. The toast says what happened, offers Undo, and leaves in 6 seconds. ⌘Z undoes it too, even after the toast has gone.", order: 1 };
+
+export default function Example() {
+	const [open, setOpen] = useState(true);
+
+	const reopen = () => {
+		setOpen(true);
+		toast.success("Listing reopened", { description: "Senior Product Designer, Leeds" });
+	};
+
+	const close = () => {
+		setOpen(false);
+		toast.success("Listing closed", {
+			description: "Senior Product Designer, Leeds",
+			action: { label: "Undo", onClick: reopen },
+		});
+	};
+
+	// Undo stays reachable without the toast
+	useEffect(() => {
+		const onKey = (e: KeyboardEvent) => {
+			if ((e.metaKey || e.ctrlKey) && e.key === "z" && !open) {
+				e.preventDefault();
+				reopen();
+			}
+		};
+		window.addEventListener("keydown", onKey);
+		return () => window.removeEventListener("keydown", onKey);
+	});
+
+	return (
+		<div className="flex w-full max-w-md items-center justify-between rounded-sm border border-line bg-surface px-3 py-2.5">
+			<div className="grid">
+				<span className="text-base font-medium text-ink">Senior Product Designer</span>
+				<span className="text-sm text-ink-3">Leeds · {open ? "Open" : "Closed"}</span>
+			</div>
+			<Button variant="outline" size="sm" onClick={open ? close : reopen}>
+				{open ? "Close listing" : "Reopen"}
+			</Button>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Banner (inline alert)
+- Confirmation dialog
+- Inbox (triage)
+- Notifications vs inbox vs toast
+- Error state (failed to load)

package/agent/docs-md/tooltip.md

@@ -0,0 +1,90 @@
+# Tooltip
+
+Shows a short, non-essential label or hint on hover or focus, such as an icon button's name and its shortcut.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- To name an icon-only button: More, Add to Interviewing.
+- To show the shortcut for a control: Search listings /.
+- To show the full text of a truncated value, or the exact date behind a relative date.
+- To give a short reason why a control is disabled.
+
+## When not to use
+
+- For anything needed to finish the task, such as format rules. Use hint text under the field.
+- For links, buttons or more than a sentence. Use a popover.
+- On labelled buttons, repeating the label.
+- On status badges or other non-interactive elements.
+
+## Structure
+
+1. Dark container (6px radius)
+2. Text
+3. Shortcut hint (optional)
+
+## Guidelines
+
+- Dark ink background, white 12px medium text, 5 x 8px padding, 6px radius.
+- Appears after a short delay (about 500ms) on hover or keyboard focus, so it does not flicker.
+- Stays while the pointer is over the trigger or the tooltip, until Esc or blur.
+- Placed so it never covers the thing it describes, and flips to stay on screen.
+- One line; never truncated.
+
+## Content
+
+- A few words, no full stop: Search listings.
+- For icon buttons, name the action in one or two words.
+- Use the same words as the accessible name.
+
+## Accessibility
+
+- role="tooltip", referenced by the trigger's aria-describedby. Focus stays on the trigger.
+- Esc dismisses it without moving focus; the pointer can move onto it; it does not time out.
+- A tooltip does not give an icon button its name; the button also needs aria-label.
+- Only on focusable triggers, so keyboard users see it too.
+- Shortcuts in tooltips are hidden from assistive technology; list them in the shortcut sheet as well.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab to trigger | Show the tooltip |
+| Esc | Hide the tooltip |
+
+## Examples
+
+### icon-buttons
+
+```tsx
+import { Button, Kbd, Tooltip, TooltipContent, TooltipTrigger } from "@twoux/ui";
+import { Bell, Pencil, X } from "lucide-react";
+
+export const meta = { title: "Name an icon button", description: "Hover or Tab to a button. The tooltip repeats the accessible name and its shortcut. It never holds information found nowhere else.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="flex items-center gap-2">
+			<Tooltip>
+				<TooltipTrigger asChild><Button variant="ghost" size="icon" aria-label="Edit listing"><Pencil /></Button></TooltipTrigger>
+				<TooltipContent>Edit listing <Kbd>E</Kbd></TooltipContent>
+			</Tooltip>
+			<Tooltip>
+				<TooltipTrigger asChild><Button variant="ghost" size="icon" aria-label="Inbox"><Bell /></Button></TooltipTrigger>
+				<TooltipContent>Inbox</TooltipContent>
+			</Tooltip>
+			<Tooltip>
+				<TooltipTrigger asChild><Button variant="ghost" size="icon" aria-label="Close details"><X /></Button></TooltipTrigger>
+				<TooltipContent side="bottom">Close details <Kbd>Esc</Kbd></TooltipContent>
+			</Tooltip>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Button
+- Keyboard shortcut hint
+- Popover rules

package/agent/docs-md/typography.md

@@ -0,0 +1,62 @@
+# Typography
+
+Geist for interface text, Geist Mono for IDs, keys and code. A seven-step scale from 11px to 24px with 13px as the default, tuned for dense tables. Numbers in columns use tabular figures.
+
+Kind: foundation · Group: Visual foundation
+
+## Principles
+
+- 13px is the working size. Tables, forms and panels set at --t-base so a row of 36px holds one line with air. Body larger than this is for reading, not scanning.
+- Hierarchy by size and weight, not by colour. Headings use the heading scale; never fake a heading with bold body text.
+- Mono for values, not for style. Geist Mono marks IDs, keyboard keys and code: dedicated value types only.
+- Sentence case everywhere, including headings, buttons and menu items.
+
+## Guidelines
+
+- Scale: --t-xs 11px (keycaps, counters, chart ticks), --t-sm 12px (metadata, table headers, helper text), --t-base 13px (default UI and table cells), --t-md 14px (reading text in panels and AI answers), --t-lg 16px (section titles), --t-xl 20px (panel titles), --t-2xl 24px (page title).
+- No sentence text below 12px. TwoUX allows 11px only for non-sentence content (a keycap, a count, an axis tick). Never set a sentence at --t-xs.
+- Line height between 1.2 and 1.45 of the size: tight for headings, about 1.4 for body.
+- Line length for reading text (AI answers, descriptions) is capped near 80 characters, inside the comfortable range of 45 to 90.
+- Weights: 400 for body, 500 for labels and controls, 600 for headings. Medium weight carries most component text and bold stays rare.
+- Numbers that line up in columns (counts, salaries, dates) use font-variant-numeric: tabular-nums, the .num utility. Tabular figures keep vertically aligned columns readable.
+- Avoid all caps. If a short label must be in caps, letterspace it, and keep caps to short labels.
+- Text is left aligned, ragged right. Centred and justified text is atypical for product UI.
+
+## Accessibility
+
+- Text colour must reach 4.5:1; --ink-3 at 5.7:1 is the lightest allowed for text.
+- Text must reflow at 320 CSS px wide without horizontal scrolling, except inside data tables.
+- Use real heading elements in order; heading structure matters for accessibility, not just bold or size.
+
+## Do
+
+- Set listing IDs like JOB-1042 in --font-mono at --t-sm.
+- Use tabular figures in every numeric column.
+- Write headings in sentence case: 'Open listings', not 'Open Listings'.
+
+## Don't
+
+- Do not set font-size in px, rem or em directly; use a --t-* token.
+- Do not use mono for emphasis or decoration.
+- Do not set paragraphs in all caps.
+
+## Tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `--font-ui` | `"Geist", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif` | All interface text |
+| `--font-mono` | `"Geist Mono", ui-monospace, "SF Mono", Menlo, monospace` | IDs, keycaps, code |
+| `--t-xs` | `11px` | Keycaps, counters, chart ticks only |
+| `--t-sm` | `12px` | Metadata, table headers, helper text |
+| `--t-base` | `13px` | Default UI text and table cells |
+| `--t-md` | `14px` | Reading text in panels and AI answers |
+| `--t-lg` | `16px` | Section titles |
+| `--t-xl` | `20px` | Panel and dialog titles |
+| `--t-2xl` | `24px` | Page title (h1) |
+
+## Related
+
+- Spacing
+- Content density
+- Writing
+- Design tokens