@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/guide-cue.md

@@ -0,0 +1,170 @@
+# Guide cue
+
+A short guide of one to three popovers that point at the real controls for a task, opened only when the person asks to be shown.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing where the parts of a task live after the person chose it, from a setup checklist Start, a Help menu entry, a help panel link or a feature label's Show me.
+- A task spread over two or three controls in a dense toolbar, such as filter, change the layout, then save a view.
+
+## When not to use
+
+- On page load, first login, a timer or hover. TwoUX has no push tours; use a setup checklist (setup-checklist) and let people start the guide.
+- Announcing a feature. Use a feature label (feature-label) and its popover; offer Show me inside it only if the feature spans several controls.
+- Explaining a field or concept. Use contextual help (help-system) and the help panel (help-panel).
+- More than three steps, or steps that depend on what was entered. Use a help article, or a stepper (stepper) for the task itself.
+- Explaining an icon-only button. Use a tooltip (tooltip).
+
+## Structure
+
+1. Target highlight (the focus ring round the real control)
+2. Popover anchored to the target
+3. Heading (what the person does here)
+4. Body (one or two sentences)
+5. Step count as text ("Step 2 of 3")
+6. Back, then Next or Done (the one primary in the cue)
+7. Close ("Close guide", Esc)
+
+## Guidelines
+
+- Open the guide only from something the person pressed, and return focus there when it closes.
+- Keep it to one to three steps, each on a real control people will use for the task.
+- Point at elements by ref or a data attribute. A step whose target is missing or hidden is skipped, and the count counts only the steps shown; with no targets the guide does not open.
+- Leave the page usable: no dimmed overlay or spotlight. Clicking the page keeps the cue open so people can try the control.
+- Show one guide cue at a time, and close any other popover first.
+- Offer Show me only where the guide can point at something; check with isGuideTargetAvailable.
+
+## Content
+
+- Heading names what the person does, sentence case: "Filter the list", "Save it as a view". Not "Step 1" or "Welcome".
+- Body is one or two sentences on what the control does for them.
+- Progress is text: "Step 2 of 3". Buttons are Back, Next and Done; the close button is named "Close guide".
+
+## Accessibility
+
+- The cue is a non-modal dialog: role="dialog", aria-modal="false", named by its heading and described by its body (SC 4.1.2).
+- Focus moves to the heading on open and returns to the control that started the guide on close (SC 2.4.3).
+- Each step change is announced in a polite live region: "Saved views guide, step 2 of 3: Choose a layout" (SC 4.1.3).
+- It never opens unrequested (SC 2.2.4). Nothing pulses; the popover's entrance stops under reduced motion (SC 2.3.3).
+- The highlight uses the focus colour, 3:1 or more against the page, and the cue sits beside the target so it never covers it (SC 1.4.11, 2.4.11).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter or Space | Press Next, Back, Done or Close |
+| Tab, Shift+Tab | Move between the cue's buttons and on to the page; focus is not trapped |
+| Esc | Close the guide and return focus to what started it |
+
+## Examples
+
+### saved-view-guide
+
+```tsx
+import { FilterBar, FilterPill, GuideCue, SavedViews, Segment, SegmentedControl, SetupChecklist, toast, useGuide, type GuideStep, type SetupItem } from "@twoux/ui";
+import { useMemo, useRef, useState } from "react";
+
+export const meta = {
+	title: "Show me from the setup checklist",
+	description: "A three-step guide over the real toolbar, shown open here as a preview. In a product it opens only from Start on “Create your first saved view”; Esc or Close ends it and Start brings it back.",
+	order: 1,
+};
+
+const LISTINGS = [
+	{ status: "Open", location: "London" },
+	{ status: "Open", location: "Leeds" },
+	{ status: "Open", location: "Remote" },
+	{ status: "Closing soon", location: "London" },
+	{ status: "Closing soon", location: "Manchester" },
+	{ status: "Draft", location: "Leeds" },
+	{ status: "Closed", location: "London" },
+	{ status: "Closed", location: "Remote" },
+];
+const STATUS = ["Open", "Closing soon", "Draft", "Closed"].map((v) => ({ value: v, label: v, count: LISTINGS.filter((l) => l.status === v).length }));
+const LOCATION = ["London", "Leeds", "Manchester", "Remote"].map((v) => ({ value: v, label: v, count: LISTINGS.filter((l) => l.location === v).length }));
+
+export default function Example() {
+	const root = useRef<HTMLElement>(null);
+	const filtersRef = useRef<HTMLDivElement>(null);
+	const layoutRef = useRef<HTMLDivElement>(null);
+	const [views, setViews] = useState([{ id: "all", name: "All listings", count: LISTINGS.length }]);
+	const [view, setView] = useState("all");
+	const [status, setStatus] = useState<string[]>([]);
+	const [location, setLocation] = useState<string[]>([]);
+	const [layout, setLayout] = useState("table");
+	const [savedOne, setSavedOne] = useState(false);
+
+	const shown = LISTINGS.filter((l) => (status.length === 0 || status.includes(l.status)) && (location.length === 0 || location.includes(l.location))).length;
+
+	const steps: GuideStep[] = useMemo(() => [
+		{ target: filtersRef, title: "Filter the list", body: "Pick a status or a location. The count updates as you tick, and the filters stay when you save." },
+		{ target: layoutRef, title: "Choose a layout", body: "Table suits scanning many listings; Board groups them by status. The view remembers which you chose.", align: "end" },
+		{
+			// A function target: the Save view button inside SavedViews. If it isn't on screen, this step is skipped.
+			target: () => root.current?.querySelector<HTMLElement>("[data-slot='saved-views'] [aria-haspopup='dialog']"),
+			title: "Save it as a view",
+			body: "Save view keeps these filters and the layout under a name, so you and your team return to them in one click.",
+			align: "end",
+		},
+	], []);
+
+	// Shown open here so you can see the cue straight away. In a product, never pass `preview`: the guide opens only from Start.
+	const guide = useGuide(steps, { label: "Saved views guide", preview: true });
+
+	const items: SetupItem[] = [
+		{ id: "slack", label: "Connect Slack", done: true },
+		{ id: "view", label: "Create your first saved view", done: savedOne, onStart: guide.start },
+		{ id: "invite", label: "Invite a teammate", done: false },
+	];
+
+	return (
+		<div className="flex w-full flex-wrap items-start gap-4">
+			<SetupChecklist items={items} className="w-full max-w-64" />
+			<section ref={root} aria-label="Listings" className="grid min-w-0 flex-1 basis-80 gap-3 rounded-sm border border-line bg-surface p-3">
+				<SavedViews
+					views={views}
+					value={view}
+					onValueChange={setView}
+					dirty={status.length + location.length > 0 && view === "all"}
+					onSaveAs={(name) => {
+						const id = name.toLowerCase().replace(/\W+/g, "-");
+						setViews((v) => [...v, { id, name, count: shown }]);
+						setView(id);
+						setSavedOne(true);
+						toast.success(`Saved “${name}”`);
+					}}
+				/>
+				<div className="flex flex-wrap items-center gap-2">
+					<div ref={filtersRef} className="min-w-0 rounded-sm">
+						<FilterBar>
+							<FilterPill field="Status" options={STATUS} selected={status} onChange={setStatus} />
+							<FilterPill field="Location" options={LOCATION} selected={location} onChange={setLocation} />
+						</FilterBar>
+					</div>
+					<span className="flex-1" />
+					<div ref={layoutRef} className="rounded-sm">
+						<SegmentedControl value={layout} onValueChange={setLayout} size="sm" aria-label="Layout">
+							<Segment value="table">Table</Segment>
+							<Segment value="board">Board</Segment>
+						</SegmentedControl>
+					</div>
+				</div>
+				<p className="tabular text-sm text-ink-2" aria-live="polite">{shown} of {LISTINGS.length} listings</p>
+			</section>
+			<GuideCue {...guide.cueProps} />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Setup checklist
+- feature-label
+- Help panel
+- Contextual help
+- Announcing new and beta features
+- Onboarding to an empty workspace
+- Popover rules

package/agent/docs-md/help-panel.md

@@ -0,0 +1,103 @@
+# Help panel
+
+Read-only help in the right-hand panel slot, opened from an Info link next to a heading or label, with the topic heading, short guidance and Learn more links.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- To explain a page, section or field whose meaning or consequences aren't obvious from its label, opened from an Info link.
+- On each step of a multi-step create flow, such as Create listing.
+- As the page-level help for any page with decisions, opened from the Help button when no Info link was used.
+
+## When not to use
+
+- To name an icon or show a shortcut. Use a tooltip.
+- For forms or actions. Use the side panel or the page.
+- For questions about the person's data. Use the assistant panel (⌘J).
+
+## Structure
+
+1. Header: topic heading (matches the heading or label it opened from) and close button
+2. Body: two to five short paragraphs or lists answering what this is, why it matters and how to choose
+3. Optional: a short example, such as a well-written job title
+4. Learn more: up to three help centre links, each opening in a new tab
+5. Feedback prompt: "Was this helpful?" at the foot
+
+## Guidelines
+
+- Opens in TwoUX's single right-hand slot at 440px, or the width the person last chose, replacing any open panel, and restores it on close.
+- Without an Info link pressed, shows the page topic. After an Info link, shows that topic until another is chosen or the page changes.
+- Reopening on the same page shows the last topic, not the page default.
+- Never opens empty: pages with no help content don't show the Help trigger.
+- Below 860px it takes the full width of the canvas.
+
+## Content
+
+- Heading matches the on-screen heading or label exactly: "Visa sponsorship".
+- Plain UK English, short paragraphs, no marketing. Explain consequences: "Candidates who need sponsorship can apply only if this is on."
+- Learn more links say what the reader will learn: "How closing dates affect applications".
+
+## Accessibility
+
+- A complementary landmark labelled "Help"; it does not trap focus.
+- Opening from an Info link moves focus to the topic heading; Esc or close returns focus to that Info link.
+- New-tab links say so in their accessible name.
+- Content reflows to 320px wide without horizontal scrolling.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter / Space (Info link) | Open the help panel at that topic |
+| Tab | Move through links in the panel, then back to the page |
+| Esc | Close the panel and return focus to the Info link |
+
+## Examples
+
+### salary
+
+```tsx
+import { FeedbackPrompt, HelpPanel, type HelpTopic, InfoLink, TextField } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Help for one field", description: "The Info link opens written help for that topic in the right-hand slot. Esc closes it and focus returns to the link. It ends with up to three Learn more links and a feedback prompt.", order: 1 };
+
+const TOPICS: Record<string, HelpTopic> = {
+	salary: {
+		id: "salary",
+		title: "Salary range",
+		body: (
+			<>
+				<p>Listings with a salary range get more applicants, and UK job boards rank them higher.</p>
+				<p><strong>Show a real range.</strong> Use the band you would actually pay, not a range so wide it says nothing. For example £30,000 to £36,000.</p>
+				<p><strong>Check the minimum.</strong> Full-time roles must pay at least the National Living Wage for the hours worked.</p>
+			</>
+		),
+		links: [{ label: "National Minimum Wage and Living Wage rates (GOV.UK)", href: "https://www.gov.uk/national-minimum-wage-rates" }],
+	},
+};
+
+export default function Example() {
+	const [open, setOpen] = useState(false);
+	const [topic, setTopic] = useState<HelpTopic | null>(null);
+	return (
+		<div className="flex h-96 w-full overflow-hidden rounded-sm border border-line bg-surface">
+			<div className="grid min-w-0 flex-1 content-start gap-1.5 p-5">
+				<div className="flex items-center gap-2"><span className="text-base font-medium text-ink">Salary</span><InfoLink topic="salary" onOpen={(t) => { setTopic(TOPICS[t]); setOpen(true); }} /></div>
+				<TextField id="help-salary" label="Salary from" prefix="£" placeholder="30,000" />
+			</div>
+			<HelpPanel open={open} onOpenChange={setOpen} topic={topic} footer={<FeedbackPrompt onVote={() => new Promise((r) => setTimeout(r, 500))} />} />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Contextual help
+- Secondary panels: which right-hand panel
+- Side panel (drawer)
+- Assistant side panel
+- Feedback prompt
+- Tooltip

package/agent/docs-md/help-system.md

@@ -0,0 +1,74 @@
+# Contextual help
+
+Answer "what is this, why does it matter, how do I choose" in three steps of depth: the words on the screen, a help panel opened from an Info link, and a help centre article in a new tab.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Help that lives only in a separate help centre isn't found at the moment of need, and help crammed into the page as long descriptions slows everyone down. Tooltips stuffed with paragraphs disappear before they are read.
+
+**Solution:** Write the screen first: clear headings, labels and short descriptions. For anything that needs more, put an Info link next to the heading or label that opens the help panel on the right with page, section or field help. Each help topic ends with links to the full article.
+
+**Built from:** Help panel, Page header, Text input, Tooltip, Side panel (drawer), Shortcut sheet (?)
+
+## How it works
+
+1. Small: headings, labels, one or two lines of description, and constraint text under fields. Most questions end here.
+2. Medium: an Info link beside a page heading, section heading or field label opens the help panel at that topic.
+3. With no Info link pressed, the help panel shows help for the whole page.
+4. Large: the panel's Learn more list links to help centre articles, which open in a new tab so the task is not lost.
+5. Closing and reopening the panel on the same page shows the last topic read, not the page default.
+
+## When to use
+
+- Decisions with consequences people may not know, such as what Visa sponsorship does to who can apply, or what Closing date means for applications in progress.
+- Concepts specific to the product, such as how pipeline stages map to candidate emails.
+- Every step of a multi-step create flow, such as Create listing.
+
+## When not to use
+
+- To name an icon button or show its shortcut. Use a tooltip.
+- For questions about the records on screen, such as "which listings close this week". Use the assistant (⌘J).
+- On the home page or any page with nothing to explain. Never show an empty help panel.
+
+## Guidelines
+
+- Place Info links next to headings and field labels only, never inside descriptions or body text.
+- The help topic's heading matches the heading or label it was opened from, word for word.
+- Help panel content is read-only reference. Forms and actions belong in the page or the side panel.
+- Requirements go in constraint text under the field before any error, not only in the help panel and never only in a placeholder.
+- Don't add standalone Learn more links on a page that has help panel content, except inside a banner or dialog.
+- Keep descriptions to one or two lines; longer explanation moves to the help panel.
+
+## Content
+
+- Answer three questions in order: what is this, why does it matter, how do I choose.
+- Page headings start with a noun for views ("Listings") and a verb for tasks ("Create listing").
+- Info link text is "Info"; its accessible name adds the topic: "Info about Visa sponsorship".
+- Help centre links say where they go: "Learn how pipeline stages work", not "Click here".
+
+## Accessibility
+
+- The help panel is a labelled complementary region; opening it from an Info link moves focus to the topic heading, and closing it returns focus to the link.
+- Info links are buttons (they open a panel), not links, and say which topic they open.
+- External help links are marked as opening in a new tab, in text and in the accessible name.
+
+## Do
+
+- Do write the label and description first; add help only for what they can't carry.
+- Do give every page that has decisions a page-level help topic.
+- Do open help centre articles in a new tab.
+
+## Don't
+
+- Don't put paragraphs in tooltips.
+- Don't switch the panel back to the default topic when it is reopened.
+- Don't use the help panel as a form.
+
+## Related
+
+- Secondary panels: which right-hand panel
+- Onboarding to an empty workspace
+- Help panel
+- Tooltip
+- Shortcut sheet (?)
+- Collecting product feedback

package/agent/docs-md/iconography.md

@@ -0,0 +1,49 @@
+# Iconography
+
+One line icon set, 16px with a 1.7 stroke in currentColor, and a fixed meaning for every icon. An icon that means one thing in one place means that thing everywhere.
+
+Kind: foundation · Group: Visual foundation
+
+## Principles
+
+- One meaning per icon. WCAG requires components with the same function to be identified consistently, and people cannot rely on icons whose function varies.
+- Words first. Few icons are universally understood, so icons sit beside a text label; icon-only buttons are kept to well-known actions and always have an accessible name and tooltip.
+- Reuse before you draw. Use existing icons rather than making new ones.
+
+## Guidelines
+
+- ↗ external (i-ext): the link leaves TwoUX, for example 'View public page' on the job board. Never used for in-app navigation.
+- ↳ follow-up (i-reply): a suggested follow-up question that continues an AI answer, under a 'Follow-ups' label.
+- Bulb (i-bulb): a starter idea, a suggested first prompt in an empty assistant. Starters can be hidden.
+- Expand (i-expand): open this record or conversation as a full page. Not used for 'show more'; that is a chevron.
+- Panel (i-panel): show the side panel side by side (push).
+- Origin mark (AiMark, a small speech bubble): content the assistant wrote, beside that content, and the type icon of AI columns in a sheet.
+- Sizes: 16px default, 14px (.sm) inside small controls and tabs, the smaller size mainly for chevrons and badges.
+- Colour: icons inherit text colour. Status icons take the status text token; the origin mark is muted (text-ink-3) like any supporting icon, never an accent or AI colour.
+- AI is marked in one place only: the origin mark next to generated output. Buttons that start AI work (Ask, Suggest titles) use their normal icon or none.
+- The origin mark is not a sparkle and is never added to other icons to mean "AI-enhanced". Search that uses a model is still Search.
+- The assistant's identity is its name, "Assistant", in text. If several agents speak in one thread, each has its own avatar and name; the origin mark is never used as an avatar.
+- Match the strength of the marking to the stage: the entry point looks like any button, work in progress shows step text and a timer, finished output carries the small mark and "Assistant · from …".
+
+## Accessibility
+
+- Icons that carry meaning reach 3:1 against their background.
+- Decorative icons beside a text label are hidden from assistive technology; icon-only buttons get an aria-label that matches the tooltip.
+- Never use an icon as the only signal of status; pair it with text.
+
+## Do
+
+- Use the origin mark only beside output the assistant produced, and as the AI column type in sheets.
+- Keep the same icon and the same accessible name for Save, Close or Share everywhere.
+
+## Don't
+
+- Do not use ↗ for links that stay inside TwoUX.
+- Do not use a sparkle for AI anywhere, and do not put the origin mark on buttons, menu items or sidebar items that start AI work.
+- Do not draw a new icon when an existing one already has that meaning.
+
+## Related
+
+- Writing
+- Consistency
+- Accessibility

package/agent/docs-md/inbox.md

@@ -0,0 +1,108 @@
+# Inbox (triage)
+
+The one place for things that need the person, shown as a list beside the selected item's detail, cleared by doing, marking done or snoozing.
+
+Kind: component · Group: Navigation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Agent approvals and questions that block a run.
+- Things about to need action, such as listings closing soon, mentions and new assignments.
+- Anything the person may need to come back to later, so it must persist rather than flash past.
+
+## When not to use
+
+- Confirming the person's own action. Use a Toast.
+- Events that need nothing from anyone. Record them in the record's Activity tab.
+- A condition on the page being viewed. Use a Banner.
+
+## Structure
+
+1. Header with key hints (J K, E done, ⇧H snooze)
+2. Tabs: Inbox, Snoozed, Done, each with a count
+3. List (listbox): items that block an agent first, marked "Needs you", then by time
+4. Detail: the item with its actions in place (approve, extend, reply, answer 1 to 3)
+5. Snooze menu: quick times plus a typed time
+6. Empty state per tab
+
+## Guidelines
+
+- List and detail side by side; acting in the detail never leaves the Inbox, and the next item opens after Done.
+- Items that block an agent sort first and carry a "Needs you" badge with a word, not only a colour.
+- Items stay until done or snoozed; snoozed items return at the chosen time.
+- Snooze offers four quick times (an hour from now, tomorrow, next week, a month from now) and a typed time such as "4 pm" or "2 days"; an unparseable time shows an error and keeps the menu open.
+- Every action (done, snooze, approve, reply) shows a toast with Undo.
+- Only things that matter reach the Inbox; filter for significance so the count stays trustworthy.
+- The unread count shows on the sidebar item; below 860px, when the sidebar hides, an inbox button with the same count appears in the top bar.
+
+## Content
+
+- Item titles say what needs doing and to what: "Approve 3 rejections for Graduate Data Analyst".
+- Empty tabs say the state and what happens next: "All caught up. New items appear here when something needs you."
+- Snooze placeholder shows examples: "Try 4 pm, tomorrow, 2 days or in 5 weeks."
+- Snoozed items show when they come back: "Until Mon 9:00".
+
+## Accessibility
+
+- The list is a listbox with aria-selected on the current item; arrow keys and J/K move through it.
+- Tabs follow the APG tabs pattern and expose their counts in the accessible name.
+- The detail region is a polite live region, so the newly opened item is announced (4.1.3).
+- The compact inbox button's label includes the count: "Inbox, 3 unread" (4.1.2).
+- Single-key triage keys (E, ⇧H, 1 to 3) follow the global single-key switch (2.1.4).
+- New items never interrupt; they appear in the list and count, and the person reads them when ready (2.2.4).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| G I | Go to Inbox |
+| J / K | Next or previous item |
+| E | Mark done |
+| ⇧H | Snooze (quick times or type a time, Enter to apply) |
+| 1 to 3 | Answer an agent's question |
+| ⌘↵ | Send a reply from the detail |
+| Esc | Close the snooze menu |
+
+## Examples
+
+### inbox
+
+```tsx
+import { Button, Inbox, type InboxItem, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Things that need you", description: "Items that block an agent come first, marked Needs you in words. Focus the list: J and K move, E marks done and the next item opens, ⇧H snoozes. Every action offers Undo.", order: 1 };
+
+const START: InboxItem[] = [
+	{ id: "1", title: "Approve: extend 3 listings by 30 days", source: "Agent · Weekly listing check", time: "09:12", needsYou: true, state: "inbox" },
+	{ id: "2", title: "Priya Shah mentioned you on Frontend Engineer", source: "Comment", time: "Yesterday", state: "inbox" },
+	{ id: "3", title: "Data Analyst closes in 2 days with 4 applicants", source: "Listing alert", time: "Mon", state: "inbox" },
+	{ id: "4", title: "Export of 1,262 listings is ready", source: "Export", time: "Sun", state: "done" },
+];
+
+export default function Example() {
+	const [items, setItems] = useState(START);
+	const set = (id: string, patch: Partial<InboxItem>) => setItems((x) => x.map((i) => (i.id === id ? { ...i, ...patch } : i)));
+	return (
+		<Inbox
+			className="h-96 w-full"
+			items={items}
+			onDone={(id) => { set(id, { state: "done" }); toast.success("Marked done", { action: { label: "Undo", onClick: () => set(id, { state: "inbox" }) } }); }}
+			onSnooze={(id, until) => { set(id, { state: "snoozed", snoozedUntil: until }); toast.success(`Snoozed until ${until.toLowerCase()}`, { action: { label: "Undo", onClick: () => set(id, { state: "inbox" }) } }); }}
+			renderDetail={(it) => (
+				<div className="grid gap-3 text-base text-ink-2">
+					<p>{it.source} · {it.time}</p>
+					{it.needsYou && <div className="flex gap-2"><Button size="sm">Review changes</Button><Button size="sm" variant="outline">Reject</Button></div>}
+				</div>
+			)}
+		/>
+	);
+}
+```
+
+## Related
+
+- Notifications vs inbox vs toast
+- Toast
+- App shell and sidebar navigation
+- Empty state

package/agent/docs-md/inline-editing-validation.md

@@ -0,0 +1,80 @@
+# Inline editing and validation
+
+Edit values where they are shown, check each field when the person leaves it, and summarise every problem on submit.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Errors that appear while typing feel like nagging, and errors that only appear after submit are hard to find. Each form in a product tends to validate at a different moment.
+
+**Solution:** Validate a field when the person leaves it. In the data grid, Enter edits, Enter saves and Esc cancels, and invalid values stay in edit. On submit, a summary counts the problems and moves focus to the first.
+
+**Built from:** Data grid, Text input, Form validation, Banner (inline alert), Side panel (drawer), Toast
+
+## How it works
+
+1. Show which values are editable: an edit affordance on hover in the side panel, cell focus in the data grid.
+2. Enter starts editing; Enter saves and Esc cancels.
+3. Check the value when the person leaves the field, never on the first keystroke.
+4. If invalid, keep the cell or field in edit with a red outline, an icon and a message under it that says how to fix it.
+5. Once the person is fixing an error, re-check on each keystroke so the message clears as soon as the value is valid.
+6. On submit of a longer form, show a summary at the top that counts the problems and links to each, and move focus to the first field in error.
+
+## When to use
+
+- For values people change often, one at a time, such as a listing's closing date or owner.
+- Across many rows in the data grid, where the same property is edited on many records.
+
+## When not to use
+
+- For creating a record or changing several dependent fields at once. Use a form in the side panel or a full page.
+- In the list table. Only the data grid supports cell editing.
+
+## Guidelines
+
+- Read and edit states use the same type size and weight so text does not jump.
+- In a filtered or sorted table, keep an edited row in place until the person refreshes, so it does not vanish under their cursor.
+- Keep the submit button enabled on longer forms; pressing it runs validation and shows the summary.
+- Mark required fields. If most fields are required, mark the optional ones instead.
+- Server errors that belong to a field appear on that field; errors that belong to no field appear in a banner above the form actions.
+- The error summary is in addition to field messages, never instead of them.
+- Show requirements before anyone gets them wrong: constraint text under the field ("3 to 80 characters") and a format example. An error should never be the first time people see a rule.
+- Warnings are not errors: a field warning ("Salary is below the range for similar roles") is shown in amber text and does not block saving.
+- After submit, stay on the form until the server answers, with a spinner in the Save button. Never redirect first and lose the input.
+- If a slow submit must leave the page, the result message links back to the form with the values and errors restored.
+- A server error that belongs to a field, such as "A listing with this reference already exists", goes on that field, not in the banner.
+
+## Content
+
+- Required message: "[Field] is required", for example "Closing date is required".
+- Say what is wrong and how to fix it in one sentence: "Salary must be a number, like 32000".
+- Summary heading: "2 problems to fix", each a link to its field.
+- Format errors start with Enter: "Enter a valid email address, like name@example.co.uk".
+- Length errors give the count: "Job title has too many characters. 92 of 80." Counters read "Character count: 12/80".
+- Don't use a generic top message such as "Fix the errors on this page"; the summary lists each problem.
+
+## Accessibility
+
+- Errors are text, not just a red border; colour is a second cue.
+- Link each message to its field with aria-describedby and set aria-invalid on the field.
+- On submit, move focus to the first field in error.
+- In the grid, Enter or F2 enters edit, Esc restores grid navigation and may undo the edit.
+- Placeholders are examples only; labels and constraint text carry the instructions, because placeholder text disappears and often fails contrast.
+
+## Do
+
+- Do validate on blur and clear the error as soon as it is fixed.
+- Do keep save and cancel visible while editing.
+
+## Don't
+
+- Don't show errors on fields the person hasn't reached yet.
+- Don't rely on a top summary alone.
+- Don't report a failed save in a toast; keep the field in error with Retry.
+
+## Related
+
+- Empty, loading and error states
+- Undo and destructive actions
+- Record detail: side panel, overlay or full page
+- Form validation
+- Data grid

package/agent/docs-md/inline-input-in-answer.md

@@ -0,0 +1,70 @@
+# Asking for details inside the answer
+
+When the assistant knows what to do but needs a few values to do it, it asks with a short form card in the thread, prefilled from context. Submitting the form produces a proposal, not a change.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** Some requests need specific values before anything can be prepared: "Draft a new listing like LST-1044 for Manchester" needs a salary band and a closing date. Asking in prose makes people type values in free text, which the assistant then has to parse and may get wrong.
+
+**Solution:** Show an input card in the conversation with only the required fields, at most five, prefilled with what can be inferred and a line saying why the values are needed. Completed cards collapse to a read-only summary with Edit. The result is a Suggested changes card the person applies.
+
+**Built from:** Card, Text input, Form validation, Suggested changes, Clarifying question card, Assistant side panel
+
+## How it works
+
+1. Ask only once the intent is clear. If it isn't, use the clarifying question card first.
+2. Show one card per thing being set up, titled after it: "Closing date and salary for the Manchester listing".
+3. Prefill from context: location from the request, salary band from the team file, closing date from the usual 30 days. Mark what was prefilled and from where.
+4. Steps that depend on each other appear one at a time; independent ones appear together as separate cards that can be done in any order.
+5. On Continue, the card collapses to a summary line with Edit, and the assistant prepares the proposal from the values.
+
+## When to use
+
+- When an action needs values with a known shape: dates, locations, salary bands, a choice of listing.
+- When the person must check a value the assistant chose before it is used, shown as an editable field with an edit icon.
+- When an agent run reaches a step that needs one value from the person, such as which listings to include.
+
+## When not to use
+
+- To find out what the person means. Use the clarifying question card with options.
+- For long setup with many fields, such as creating a listing from scratch. Open the listing form instead.
+- For decisions about candidates. The assistant does not collect inputs to decide on people.
+
+## Guidelines
+
+- Five fields at most, all required. If a field is optional, leave it out.
+- Say why the values are needed in one line above the fields.
+- Use the same inputs as the rest of TwoUX: date picker for dates, select for known lists. Validate on Continue like any form.
+- Never ask for something the workspace already holds; prefill it instead.
+- A card left unanswered doesn't block the thread: the composer stays usable and the card can be dismissed.
+
+## Content
+
+- Card titles name the thing, not the need: "Closing date for LST-1061", not "Information required".
+- Prefill note: "From team file Salary bands 2026".
+- Collapsed summary: "Manchester · £28,000 to £32,000 · closes 6 Dec" then Edit.
+
+## Accessibility
+
+- When the card appears, announce it and move focus to its heading, not to the first field or Continue.
+- The card is not a dialog and doesn't trap focus; the thread and composer stay reachable.
+- Each field has a visible label; prefilled values are announced with their source.
+
+## Do
+
+- Do prefill from context and say where values came from.
+- Do collapse completed cards to a summary with Edit.
+- Do turn the values into a proposal the person applies.
+
+## Don't
+
+- Don't ask for optional fields.
+- Don't use a form to clarify intent.
+- Don't show several dependent steps at once.
+
+## Related
+
+- Clarifying before acting
+- Propose, then apply
+- Ask about what's on screen
+- Clarifying question card