@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/clarifying-question.md

@@ -0,0 +1,92 @@
+# Clarifying question card
+
+A card docked above the message box that asks up to three questions with recommended defaults when the answer would change the result.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- When the request is ambiguous and the answer changes the result, for example which listings to rewrite.
+- Before high-impact changes or when confidence is low, collect details first.
+
+## When not to use
+
+- Information already in context or retrievable from the data. Do not re-ask; use the context chips (message-composer).
+- Suggesting what to ask next after an answer. Use Follow-ups (follow-ups-starters).
+- Approving a change. Use Suggested changes (suggested-changes).
+
+## Structure
+
+1. Counter ("1 / 2") and question
+2. Options (title and one line each, recommended first, number key)
+3. Other (free text, last)
+4. Footer (Previous, Skip, Next ↵)
+5. Thread line "Waiting for your answer" with timer
+
+## Guidelines
+
+- Ask only when the answer changes the result, at most three questions, one at a time.
+- Every question has a default, shown first and marked "(Recommended)". Skip uses the defaults for the rest.
+- Options first, free text last. Structured choices beat free text.
+- Dock the card above the message box so the thread does not fill with back and forth.
+- Stop ends the questions and says "Stopped. Nothing was changed."
+
+## Content
+
+- Questions are short and specific: "Which titles should I rewrite?"
+- Each option has a title and one line of consequence ("Leaves listings that are doing well alone").
+- Use "choose" or "select", not "click".
+
+## Accessibility
+
+- Options are a radiogroup labelled by the question; each option is role="radio" with aria-checked.
+- Arrow keys move and select within the group; Tab moves to Other and the footer buttons in order (SC 2.4.3).
+- Number keys 1 to 4 are single character shortcuts, so they must be active only while the card is open and focus is not in a text field, and must respect the setting that turns single-key shortcuts off (SC 2.1.4). The mock listens while the card is open but ignores that setting, which needs fixing.
+- The waiting timer must not limit time to answer (SC 2.2.1); it only shows elapsed time.
+- Announce the new question when Next is pressed (SC 4.1.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| 1 to 3 | Choose an option |
+| 4 | Move focus to Other |
+| Arrow keys | Move between options |
+| Enter | Next question, or run when it is the last |
+| Esc | Close the panel (Stop ends the questions) |
+
+## Examples
+
+### ask
+
+```tsx
+import { ClarifyingQuestion, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Ask only what changes the result", description: "One question at a time, at most three. The recommended option comes first; number keys choose; Other is last; Skip keeps the defaults.", order: 1 };
+
+export default function Example() {
+	const [k, setK] = useState(0);
+	return (
+		<div className="w-full max-w-lg">
+			<ClarifyingQuestion
+				key={k}
+				questions={[
+					{ question: "Which listings should I compare?", options: [{ id: "team", title: "Same team, last 90 days", detail: "22 listings" }, { id: "all", title: "All listings this year", detail: "141 listings" }] },
+					{ question: "How should I show the result?", options: [{ id: "table", title: "A short table" }, { id: "chart", title: "A chart by week" }] },
+				]}
+				onDone={(a) => { toast(`Continuing with: ${a.join(", ")}`); setK((x) => x + 1); }}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Assistant side panel
+- Message composer
+- Thinking and steps
+- Agent run timeline
+- Plan preview
+- Confidence note

package/agent/docs-md/code-block.md

@@ -0,0 +1,174 @@
+# Code block
+
+Shows code, commands, IDs or log output exactly as written, so people can read and copy it. Inline Code marks a token inside a sentence.
+
+Kind: component · Group: Content · Status: built, import from @twoux/ui
+
+## When to use
+
+- To let people copy a command, token, API key name or snippet exactly.
+- To show a change as a diff, with added and removed lines.
+- To show tool or agent output, such as a run log, using the small size.
+- Inline Code for a prop, token or file name inside a sentence: `bg-surface`, `jobs.json`.
+
+## When not to use
+
+- When people need to edit the text. Use a Text input or the Prompt editor.
+- For ordinary values in a table, such as an ID column. Use the mono table cell.
+- Inline Code across several lines. Use a code block.
+
+## Structure
+
+1. Header (optional): file name or label
+2. Actions: copy button, more if needed
+3. Content: lines, with optional numbers
+4. Line marks: highlighted, added (+), removed (−)
+5. Footer (optional): show more, captions
+
+## Guidelines
+
+- Long single-line commands scroll sideways rather than wrapping, so they stay copyable as one line. Use wrap for prose-like output.
+- Past about nine lines, cap the height and offer Show more in the footer.
+- Without a header, the copy button floats top right and appears on hover or focus, and always on touch screens.
+- Line numbers are optional, never copied and hidden from screen readers.
+- Use the destructive variant for errors and failed output.
+- Light border, grey fill: the block is read, not raised, so it takes no shadow.
+
+## Content
+
+- Label the header with the file name or what the code is: “twoux.css”, “Install”, “Run log”.
+- Show code exactly as it should be typed. No ellipses inside commands.
+
+## Accessibility
+
+- The scrolling area is focusable (tabindex 0) so keyboard users can scroll it.
+- Added and removed lines show + and − as well as colour.
+- Copying announces “Copied” through a status message without moving focus; focus stays on the button.
+- Wrapping is available so long output does not force two-dimensional scrolling at 320px.
+- Code text keeps 4.5:1 on the grey fill; line numbers use ink-3 (5.4:1 on surface-2).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the code area, then the copy button |
+| Arrow keys | Scroll the code area when it has focus |
+| Enter or Space | Copy, when the copy button has focus |
+
+## Examples
+
+### command
+
+```tsx
+import { CodeBlock, CodeBlockActions, CodeBlockContent, CodeBlockCopyButton } from "@twoux/ui";
+
+export const meta = { title: "Command", description: "One line, no header. Copy appears on hover or focus. Long commands scroll instead of wrapping.", order: 2 };
+
+const cmd = "pnpm add @twoux/ui && pnpm llm";
+
+export default function Example() {
+	return (
+		<CodeBlock className="w-full max-w-lg">
+			<CodeBlockActions floating>
+				<CodeBlockCopyButton value={cmd} />
+			</CodeBlockActions>
+			<CodeBlockContent code={`$ ${cmd}`} />
+		</CodeBlock>
+	);
+}
+```
+
+### diff
+
+```tsx
+import { CodeBlock, CodeBlockContent, CodeBlockHeader, CodeBlockTitle } from "@twoux/ui";
+
+export const meta = { title: "Diff", description: "Added and removed lines carry + and − as well as colour, so the change is clear without colour.", order: 3 };
+
+export default function Example() {
+	return (
+		<CodeBlock className="w-full max-w-lg">
+			<CodeBlockHeader>
+				<CodeBlockTitle>Suggested change · listing title</CodeBlockTitle>
+			</CodeBlockHeader>
+			<CodeBlockContent code={`title: "Operations Coordinator"\ntitle: "Junior Operations Coordinator"\nteam: "Operations"`} removed={[1]} added={[2]} />
+		</CodeBlock>
+	);
+}
+```
+
+### file
+
+```tsx
+import { CodeBlock, CodeBlockActions, CodeBlockContent, CodeBlockCopyButton, CodeBlockHeader, CodeBlockTitle } from "@twoux/ui";
+import { FileCode2 } from "lucide-react";
+// twoux-check-disable raw-colour: the colours are code sample text, not styles
+
+export const meta = { title: "With file name", description: "The header names what the code is. Copy sits at the end of the header.", order: 1 };
+
+const code = `@theme {
+  --color-primary: var(--color-indigo-600);
+  --color-line: var(--color-neutral-100);
+  --shadow-card: 0 1px 2px rgb(23 23 40 / 0.04);
+}`;
+
+export default function Example() {
+	return (
+		<CodeBlock className="w-full max-w-lg">
+			<CodeBlockHeader>
+				<CodeBlockTitle icon={<FileCode2 />}>twoux.css</CodeBlockTitle>
+				<CodeBlockActions>
+					<CodeBlockCopyButton value={code} />
+				</CodeBlockActions>
+			</CodeBlockHeader>
+			<CodeBlockContent code={code} lineNumbers highlight={[2]} />
+		</CodeBlock>
+	);
+}
+```
+
+### inline
+
+```tsx
+import { Code } from "@twoux/ui";
+
+export const meta = { title: "Inline", description: "For a token, prop or file inside a sentence. It never breaks mid-token.", order: 5 };
+
+export default function Example() {
+	return (
+		<p className="max-w-md text-base text-ink">
+			Style only with role tokens such as <Code>bg-surface</Code> and <Code>text-ink-2</Code>, defined in <Code>twoux.css</Code>.
+		</p>
+	);
+}
+```
+
+### output
+
+```tsx
+import { CodeBlock, CodeBlockContent, CodeBlockFooter, CodeBlockHeader, CodeBlockTitle } from "@twoux/ui";
+
+export const meta = { title: "Run output and errors", description: "Small size for agent and tool output. The destructive variant marks a failed run.", order: 4 };
+
+export default function Example() {
+	return (
+		<div className="grid w-full max-w-lg gap-3">
+			<CodeBlock size="sm">
+				<CodeBlockHeader>
+					<CodeBlockTitle>Run log · Rename low performers</CodeBlockTitle>
+				</CodeBlockHeader>
+				<CodeBlockContent code={"09:00:02  Found 2 listings under 3%\n09:00:05  Drafted 2 titles\n09:00:05  Waiting for approval"} />
+			</CodeBlock>
+			<CodeBlock size="sm" variant="destructive">
+				<CodeBlockContent code={"09:00:07  Could not reach twoux.co.uk/jobs (timeout after 10s)"} wrap />
+				<CodeBlockFooter>Try again from the run, or check the careers page link.</CodeBlockFooter>
+			</CodeBlock>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Text input
+- Toast

package/agent/docs-md/colours.md

@@ -0,0 +1,87 @@
+# Colours
+
+TwoUX is a mostly neutral interface, light by default with a dark theme people can choose. Colour is spent on two things only: the one accent that marks the main action and current selection, and three reserved status families. Every colour is applied through a role token, never a hex value.
+
+Kind: foundation · Group: Visual foundation
+
+## Principles
+
+- Neutral first. Surfaces, text and lines are cool greys with a slight violet bias, so data and status carry the colour. Most of the UI stays white and greyscale, and colour is kept for calls to action and status.
+- Light by default, dark by choice. Every role token holds a light and a dark value (CSS light-dark()), so components are written once and switch together when <html> gets data-theme="dark", or "system" to follow the device. Dark values are chosen for dark, not inverted: surfaces step lighter as they rise (page, surface, popover), status text moves to the 400 steps, status fills are mixed into the surface, and chart colours are a separate validated selection. Each pair is contrast-checked against its own theme's surface.
+- One accent with one job. --accent marks the primary action, the current selection and focus. It never means good, bad or anything else.
+- Status colours mean status. --ok, --warn and --bad (and --mute for neutral) describe the state of a record, such as a listing that is live, expiring or closed. They are never decoration and never a chart series.
+- Choose by role, not by look. Pick the token whose name matches the job, even when another token happens to render the same hex.
+- Colour is never the only cue. Every state that uses colour also has text, an icon or a shape change.
+
+## When to use
+
+- Use --accent for the single primary button in a view, the selected nav item, links and the focus ring.
+- Use a status family (text, -bg, -line together) for badges, banners, inline validation and row state.
+
+## When not to use
+
+- Do not use status colours to make something look important; use type weight or position instead.
+- Do not use --c1 to --c8 or --q1 to --q5 in UI chrome; those belong to charts only.
+
+## Guidelines
+
+- Text: --ink (17.8:1 on white) for primary text, --ink-2 (9.1:1) for secondary text and labels, --ink-3 (5.7:1) for metadata and placeholders. All three pass the 4.5:1 text minimum on both --surface and --bg.
+- Ground: --bg (#F5F5F8) is the app chrome; --surface (#FFFFFF) is the inset canvas where work happens; --surface-2 is a quiet well inside a surface. --hover and --selected are row and item states.
+- Lines: --line and --line-strong are separators for grouping. At 1.24:1 and 1.44:1 on white they are too faint to be the only thing that identifies a control, so inputs and buttons must also have a fill, label or text that meets 3:1 or 4.5:1.
+- Status families come in threes: text (--ok #1E7F47), background (--ok-bg) and border (--ok-line). Use the three together so the pairing is always the tested one: --ok on --ok-bg is 4.51:1, --warn on --warn-bg 5.30:1, --bad on --bad-bg 4.79:1.
+- Selected and active states pair colour with a second cue: a check, a filled background, a weight change or an underline.
+- --progress (#D9A118) is 2.32:1 on white. It may only fill a bar or dot that sits next to a text value; it must never carry meaning alone.
+- AI has no colour of its own. The origin mark and its text use the muted text colour; generated cells use the neutral generated tint.
+- No gradients, glows or animated fills on AI surfaces, avatars or loading. Progress is shown with words, a timer and the standard spinner or progress bar.
+- Form controls, links and the accent keep their usual colours inside the assistant.
+
+## Accessibility
+
+- Body text must reach 4.5:1 and large text 3:1 against its actual background; ratios are not rounded up, so 4.49:1 fails.
+- Control boundaries, icons that carry meaning and the focus ring must reach 3:1 against adjacent colours.
+- Disabled controls are exempt from contrast, but they must still be identifiable by label.
+- Never convey status by colour alone. A red row also says 'Closed'; a green dot also says 'Live'.
+
+## Do
+
+- Use one --accent button per view so the main action is obvious.
+- Pair every status colour with a word.
+- Reference tokens by name in code.
+
+## Don't
+
+- Do not write hex, rgb or named colours in component code.
+- Do not use --bad for anything that is not an error, a destructive action or a closed state.
+- Do not pick a token because its colour matches what you want; pick it because its name matches the job.
+
+## Tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `--bg` | `#F5F5F8` | App chrome behind the canvas |
+| `--surface` | `#FFFFFF` | Inset canvas, cards, panels, popovers |
+| `--surface-2` | `#FAFAFC` | Wells and quiet areas inside a surface |
+| `--hover` | `#ECECF2` | Row and item hover on a surface (tables, lists, menus) |
+| `--selected` | `#E6E6EC` | Hover on the app background (sidebar, top bar) and the cell under the pointer in a grid; the current nav item sits raised on --surface instead |
+| `--line` | `#E6E6EC` | Default separator |
+| `--line-strong` | `#D6D6DF` | Stronger separator, keycap border |
+| `--ink` | `#17171F` | Primary text (17.8:1 on white) |
+| `--ink-2` | `#474756` | Secondary text and labels (9.1:1) |
+| `--ink-3` | `#656574` | Metadata, placeholder (5.7:1) |
+| `--accent` | `#5753E0` | Primary action, selection, links (5.65:1) |
+| `--accent-hover` | `#4A46D1` | Primary action hover |
+| `--accent-soft` | `#EEEDFD` | Accent tint for selected and AI surfaces |
+| `--accent-ink` | `#4340C4` | Accent text on --accent-soft (6.56:1) |
+| `--on-accent` | `#FFFFFF` | Text on --accent |
+| `--ok / --ok-bg / --ok-line` | `#1E7F47 / #E8F6EE / #BFE3CD` | Positive status |
+| `--warn / --warn-bg / --warn-line` | `#965606 / #FDF4E3 / #F0D7A8` | Caution status |
+| `--bad / --bad-bg / --bad-line` | `#C2333B / #FCECED / #F1C3C6` | Error, destructive, closed |
+| `--mute / --mute-bg / --mute-line` | `#474756 / #F2F2F5 / #E1E1E8` | Neutral status such as Draft |
+| `--progress` | `#D9A118` | Progress fill only, always next to a text value |
+
+## Related
+
+- Data visualisation colours
+- Design tokens
+- Accessibility
+- Shape and elevation

package/agent/docs-md/columns-menu.md

@@ -0,0 +1,140 @@
+# Columns menu
+
+A menu that shows, hides and reorders the columns of a sheet or list table, with search, Show all and Hide all, type icons and eye toggles, plus wrapping and rows per page on list tables. Changes apply at once.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- On a sheet or list table where people change which columns they see while they work and expect the change at once.
+- A table has more columns than most people need at once; let each person show, hide and reorder them.
+- People choose page size or line wrapping for their own work on a list table.
+
+## When not to use
+
+- To change what a column holds. Use the column menu in the sheet.
+- For filtering rows. Use the TwoUX Filter bar.
+- For saving a full working setup with filters. Use TwoUX Saved views.
+- As the main way to make a table usable; most people never customise, so defaults must already work.
+
+## Structure
+
+1. Button: Columns
+2. Search field
+3. Count with Show all and Hide all
+4. Row per column: drag handle, type icon, name, Move up, Move down, eye toggle or lock
+5. List tables: Wrap long text and Rows per page (25, 50, 100)
+6. Where the choice is kept ("Saved for you on this table") and the help line for keyboard reordering
+
+## Guidelines
+
+- Apply each change at once; there is nothing to confirm. Changing it back is the undo.
+- Every drag has a keyboard path (Space to pick up, arrows, Space to drop, Esc to cancel) and Move up and Move down buttons.
+- The column that names the record is locked: always shown, marked with a lock and the words Always shown.
+- Show the type icon of each column so people recognise it among similar names.
+- List columns in the same order they appear in the table.
+- Store the choice per person and per table, restore it on return, and say so in the menu: "Saved for you on this table".
+- Rows per page is a radio group, not a select, so the menu never opens a second popover.
+
+## Content
+
+- Use sentence case and plain labels, for example "Wrap long text".
+- Zero results: No columns match "cost".
+
+## Accessibility
+
+- Eye toggles are buttons with aria-pressed and a name that says what they do: Hide Email.
+- Moves are announced: Email moved to position 3 of 10.
+- 2.5.7 Dragging movements: the Move buttons do the same as dragging.
+- Wrap long text is a labelled switch; Rows per page is a radio group named by its label.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Space / Enter on a handle | Pick up or drop |
+| ↑ ↓ (picked up) | Move the column |
+| Esc (picked up) | Cancel the move |
+| Esc | Close the menu; focus returns to Columns |
+
+## Examples
+
+### list-table
+
+```tsx
+import { ColumnsMenu, type ColumnsMenuItem, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@twoux/ui";
+import { useState } from "react";
+import { LISTINGS, type Listing, formatDate } from "../list-table/data";
+
+export const meta = { title: "On a list table", description: "The same menu on a list table, with Wrap long text and Rows per page. Role is locked so every row stays recognisable. Every change applies at once.", order: 2 };
+
+const CELL: Record<string, (l: Listing) => string | number> = { role: (l) => l.role, location: (l) => l.location, status: (l) => l.status, applicants: (l) => l.applicants, closes: (l) => formatDate(l.closes) };
+
+export default function Example() {
+	const [columns, setColumns] = useState<ColumnsMenuItem[]>([
+		{ id: "role", label: "Role", locked: true },
+		{ id: "location", label: "Location" },
+		{ id: "status", label: "Status" },
+		{ id: "applicants", label: "Applicants", hidden: true },
+		{ id: "closes", label: "Closes" },
+	]);
+	const [wrap, setWrap] = useState(false);
+	const [pageSize, setPageSize] = useState(25);
+	const cols = columns.filter((c) => !c.hidden);
+	return (
+		<div className="grid w-full max-w-2xl gap-2">
+			<div className="flex justify-end">
+				<ColumnsMenu columns={columns} onChange={setColumns} wrap={wrap} onWrapChange={setWrap} pageSize={pageSize} onPageSizeChange={setPageSize} note="Saved for you on this table" />
+			</div>
+			<div className="overflow-hidden rounded-sm border border-line bg-surface">
+				<Table aria-label="Listings">
+					<TableHeader>
+						<TableRow className="hover:bg-transparent">{cols.map((c) => <TableHead key={c.id}>{c.label}</TableHead>)}</TableRow>
+					</TableHeader>
+					<TableBody>
+						{LISTINGS.slice(0, 4).map((l) => (
+							<TableRow key={l.id}>{cols.map((c) => <TableCell key={c.id} className={wrap ? "whitespace-normal" : undefined}>{CELL[c.id](l)}</TableCell>)}</TableRow>
+						))}
+					</TableBody>
+				</Table>
+				<p className="tabular border-t border-line px-3 py-2 text-sm text-ink-2">Showing 1–4 of {LISTINGS.length} listings · {pageSize} per page</p>
+			</div>
+		</div>
+	);
+}
+```
+
+### sheet
+
+```tsx
+import { ColumnsMenu, type ColumnsMenuItem } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Show, hide and reorder columns", description: "Changes apply at once. Drag a handle, use Move up and Move down, or focus a handle, press Space, move with the arrow keys and press Space to drop.", order: 1 };
+
+export default function Example() {
+	const [columns, setColumns] = useState<ColumnsMenuItem[]>([
+		{ id: "name", label: "Name", type: "text", locked: true },
+		{ id: "title", label: "Job title", type: "text" },
+		{ id: "company", label: "Company", type: "text" },
+		{ id: "size", label: "Company size", type: "number" },
+		{ id: "added", label: "Added", type: "date", hidden: true },
+		{ id: "fit", label: "Fit score", type: "formula" },
+		{ id: "summary", label: "Summarise role", type: "ai" },
+		{ id: "email", label: "Work email", type: "enrichment", provider: "hubspot" },
+	]);
+	return (
+		<div className="grid justify-items-start gap-2">
+			<ColumnsMenu columns={columns} onChange={setColumns} align="start" />
+			<p className="text-sm text-ink-2">Shown, in order: {columns.filter((c) => !c.hidden).map((c) => c.label).join(", ")}</p>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Sheet grid
+- List table
+- Saved views
+- pagination-counts

package/agent/docs-md/combobox.md

@@ -0,0 +1,161 @@
+# Combobox
+
+Pick one or several values from a long list by typing a few letters, and add a missing one without leaving the form: a location, skills, an owner.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- One value from eight or more options, such as a location from 40 offices.
+- Several values from eight or more options, such as skills from a long list (multiple).
+- Options the server searches, such as people in a large company (filter={null} with onSearch).
+- When a missing option can be created on the spot: Create "Leeds office".
+
+## When not to use
+
+- Up to seven options. Show them all as Radio buttons (radio) or Checkboxes (checkbox).
+- Free values with no list, such as email addresses. Use Tag input (tag-input).
+- Narrowing a list or a table. Use Filter pills (filter-bar).
+- Running commands or jumping anywhere. Use the Command palette (command-palette).
+
+## Structure
+
+1. Label
+2. Trigger: the value, or chosen values as tags then +N more
+3. Popover: search field
+4. Options, grouped (optional), with a check for chosen ones and secondary text
+5. Status: searching, no match, or failed with Try again
+6. Create "…" (optional)
+7. Footer for several: count, limit and Clear
+
+## Guidelines
+
+- Matching ignores case and accents and looks at the label and the secondary text.
+- With several values, chosen options are listed first when the list opens and keep their place while people tick, so rows don't jump.
+- For server search, results replace the list in one go. "Searching…" shows only if the wait passes one second.
+- If options fail to load, say so inside the list with Try again; the rest of the form keeps working.
+- Offer Create only when nothing matches exactly. A name-only record is created and selected at once; anything more opens an overlay side panel and is selected when saved.
+- Up to three chosen values show as tags in the trigger, then +N more. The footer states the count and any limit.
+- A required combobox shows its error under the field on submit; the submit button is never disabled.
+
+## Content
+
+- The placeholder names the action and the thing: Choose a location. The search field says Search locations.
+- No match names the text: No locations match "lee".
+- Create repeats the text in quotes: Create "Leeds office".
+
+## Accessibility
+
+- The search field is a combobox controlling a listbox; options are named and the highlighted one is announced with aria-activedescendant.
+- The trigger is named by the label and the value: "Location, Leeds" or "Skills, 3 selected".
+- Result counts and the searching state are announced politely.
+- Each tag's remove button is named "Remove Python" and has a 24px target.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter, Space or ↓ (trigger) | Open the list |
+| A letter (trigger) | Open the list with that letter in the search |
+| ↑ ↓ | Move through options |
+| Enter | Choose the option; with several values it ticks and the list stays open |
+| Esc | Close without changing the value; focus returns to the trigger |
+| Backspace (trigger) | Move to the last chosen tag; Backspace again removes it |
+
+## Examples
+
+### location
+
+```tsx
+import { Combobox, type ComboboxOption } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "One value, with Create", description: "Type a few letters. When an office isn't listed, Create adds it and selects it in one step.", order: 1 };
+
+const START: ComboboxOption[] = [
+	["Aberdeen", "Scotland"], ["Belfast", "Northern Ireland"], ["Birmingham", "England"], ["Bristol", "England"], ["Cardiff", "Wales"], ["Edinburgh", "Scotland"],
+	["Glasgow", "Scotland"], ["Leeds", "England"], ["Liverpool", "England"], ["London", "England"], ["Manchester", "England"], ["Newcastle", "England"], ["Swansea", "Wales"],
+].map(([label, description]) => ({ value: label.toLowerCase(), label, description, group: description }));
+
+export default function Example() {
+	const [options, setOptions] = useState(START);
+	const [value, setValue] = useState<string | null>("leeds");
+	return (
+		<div className="w-72">
+			<Combobox
+				label="Location"
+				noun={{ one: "office", many: "offices" }}
+				options={options}
+				value={value}
+				onValueChange={setValue}
+				onCreate={(text) => {
+					const made = { value: text.toLowerCase(), label: text, description: "New office" };
+					setOptions((o) => [...o, made]);
+					return made;
+				}}
+				required
+			/>
+		</div>
+	);
+}
+```
+
+### server-search
+
+```tsx
+import { Combobox, type ComboboxOption, matchOption } from "@twoux/ui";
+import { useCallback, useState } from "react";
+
+export const meta = { title: "Server search and errors", description: "The app filters as people type. Nothing flickers for quick answers; a failure shows inside the list with Try again. Type \"fail\" to see it.", order: 3 };
+
+const PEOPLE: ComboboxOption[] = ["Amara Okafor", "Ben Hughes", "Chloé Martin", "Dev Patel", "Eilidh Ross", "Femi Adeyemi", "Grace Lin", "Harry Evans", "Isla Byrne", "Jonas Weber"].map((n, i) => ({ value: `u${i}`, label: n, description: ["Talent", "Engineering", "Design", "Finance"][i % 4] }));
+
+export default function Example() {
+	const [options, setOptions] = useState<ComboboxOption[]>(PEOPLE);
+	const [loading, setLoading] = useState(false);
+	const [loadError, setLoadError] = useState<string>();
+	const [value, setValue] = useState<string | null>(null);
+	const search = useCallback((text: string) => {
+		setLoading(true);
+		setLoadError(undefined);
+		setTimeout(() => {
+			setLoading(false);
+			if (text.trim().toLowerCase() === "fail") return setLoadError("People didn't load. Check your connection.");
+			setOptions(PEOPLE.filter((p) => matchOption(p, text)));
+		}, 1400);
+	}, []);
+	return (
+		<div className="w-72">
+			<Combobox label="Hiring manager" noun={{ one: "person", many: "people" }} options={options} value={value} onValueChange={setValue} filter={null} onSearch={search} loading={loading} loadError={loadError} onRetry={() => search("")} />
+		</div>
+	);
+}
+```
+
+### skills
+
+```tsx
+import { Combobox } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Several values", description: "Ticking keeps the list open. Up to three skills show in the field, then +N more; the footer counts them against the limit.", order: 2 };
+
+const SKILLS = ["Airflow", "AWS", "Azure", "dbt", "Docker", "Excel", "Figma", "GCP", "Go", "Java", "Kotlin", "Kubernetes", "Looker", "Power BI", "Python", "R", "React", "Rust", "Scala", "Snowflake", "Spark", "SQL", "Tableau", "Terraform", "TypeScript"].map((s) => ({ value: s, label: s }));
+
+export default function Example() {
+	const [value, setValue] = useState<string[]>(["Python", "SQL", "dbt", "Airflow"]);
+	return (
+		<div className="w-80">
+			<Combobox multiple label="Skills" noun={{ one: "skill", many: "skills" }} options={SKILLS} value={value} onValueChange={setValue} max={8} hint="Shown on the listing and used to match candidates." />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Checkbox
+- Radio
+- Tag input
+- Choosing a selection control
+- Creating a record: dialog, single page or steps