@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/drag-and-drop.md

@@ -0,0 +1,74 @@
+# Drag and drop
+
+Dragging is a shortcut, never the only way: every drag in TwoUX has a keyboard path and a menu path that do the same thing.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Dragging is quick for some people and impossible for others, including keyboard, switch and tremor users. Drags without a visible handle go unnoticed, and drops that land somewhere unexpected move a candidate to the wrong stage.
+
+**Solution:** Mark draggable things with a handle, show where the item will land while it moves, and send an invalid drop back to where it started. Offer the same move from the keyboard (pick up, arrows, drop) and from a menu item such as Move to stage.
+
+**Built from:** Board and board item, Columns menu, Grouped list, Dropdown menu, Confirmation dialog, Toast
+
+## How it works
+
+1. Decide whether the drag is a shortcut (reordering columns, uploading a CV by dropping it) or the main way to do the task (arranging a dashboard). Main-way drags need the strongest signifiers and alternatives.
+2. Give each draggable item a 16px grip handle in a 24px target, and change the cursor to grab on hover; resize handles use the matching resize cursor.
+3. While dragging, lift the item with a shadow and show a drop preview the size of the item where it will land.
+4. If the drop target is not allowed, show it as unavailable during the drag and return the item to its start on release.
+5. After a drop, confirm the result in place and in a toast with Undo, unless the move is irreversible (such as moving a candidate to Rejected, which emails them); that opens a confirmation dialog first.
+
+## When to use
+
+- Reordering things whose order matters: pipeline stages, columns in the Columns menu, dashboard items on a board.
+- Moving a candidate card between stages on a pipeline board, alongside the Move to stage menu.
+- Dropping files, such as a CV or a job description document, onto an upload area that also has a Choose file button.
+
+## When not to use
+
+- For sorting a table. Use sortable column headers; order there comes from the data, not from the person.
+- For bulk moves of many records. Select them and use the bulk action bar.
+- As the only way to do anything (WCAG 2.5.7).
+
+## Guidelines
+
+- Every drag has a single-pointer alternative: arrow buttons or menu items such as Move up, Move down, Move to stage.
+- Every drag has a keyboard path: Tab to the handle, Enter or Space to pick up, arrows to move, Enter to drop, Esc to cancel.
+- Items of equal size swap places; otherwise the moving item pushes the others along. Never let items overlap.
+- Moves save per person or per team as the context says, and the result is visible at once: no Save button for a reorder.
+- Scroll the list or board automatically when the dragged item nears its edge.
+- Respect reduced motion: drop items into place without the slide animation.
+- Show every stage of a drag. Ready: the grip darkens on hover and focus, with a grab cursor and a tooltip saying how to move it. Dragging: a lifted copy follows the pointer, the board tints to show where drops are allowed, and a dashed slot shows exactly where the item will land.
+- Other items glide to make room (180ms, off with reduced motion) instead of jumping. On drop, a short highlight settles on the moved item and the new position is announced. Esc cancels and puts it back.
+
+## Content
+
+- Handle accessible name: "Move Junior Product Designer", with a description of the keys.
+- Live announcements say position in words: "Picked up Interview. Stage 3 of 6." then "Interview moved to stage 2 of 6."
+- Upload area text names both paths: "Drop a CV here or choose a file".
+
+## Accessibility
+
+- Dragging is never the only way to move, reorder or resize (2.5.7 Dragging Movements).
+- Handles meet the 24 by 24px target size (2.5.8).
+- Pick-up, each move, drop and cancel are announced in a polite live region (4.1.3).
+- Esc cancels and returns the item and focus to where they started.
+
+## Do
+
+- Do show a drop preview where the item will land.
+- Do offer the same move as a menu item.
+- Do use the same handle icon for every drag in the product.
+
+## Don't
+
+- Don't make a whole row draggable with no handle; it fights text selection and click to open.
+- Don't drop silently into an invalid place; send the item back.
+- Don't trigger an email to a candidate from a drop without confirming first.
+
+## Related
+
+- Board and board item
+- Columns menu
+- Undo and destructive actions
+- Keyboard-first navigation

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

@@ -0,0 +1,137 @@
+# Dropdown menu
+
+Opens a short list of actions or options from a button, with optional groups and one level of submenus.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- To group related actions behind one button: Export, row actions, Add context.
+- For about 5 to 15 commands, ordered by how often they are used.
+- For settings with a current value, shown on the right and changed in a one-level submenu: Writing style Concise.
+
+## When not to use
+
+- For one or two actions. Show them as Buttons.
+- When people must search or pick from a long list of values. Use a select or combobox.
+- For the main action in a view. Use a primary Button.
+- For rich content or forms. Use a popover or dialog.
+
+## Structure
+
+1. Trigger button with chevron
+2. Menu panel
+3. Group label (optional)
+4. Menu item: icon, label, shortcut or current value
+5. Separator
+6. Submenu caret
+7. Destructive item (last)
+
+## Guidelines
+
+- Panel 200px minimum, 10px radius, 4px padding, shadow. Items 30px high, 6px radius, hover in grey.
+- Group with uppercase group labels and separators; put destructive items last, in red, after a separator.
+- At most one level of submenu. Submenus open on hover, focus or Right arrow, and flip to the side with room.
+- Icons on items: none by default. Add them only when every item in a group has a well-known icon from the icon meaning table, and then on all items in that group; never on one item alone. The label always stays, and the icon is 14px and muted.
+- Show each item's shortcut on the right.
+- Disable items that do not apply rather than hide them, so people can still find them.
+- Keep the list under about 12 items.
+
+## Content
+
+- Action items start with a verb; navigation items are nouns.
+- Sentence case, one line, no articles: Duplicate listing.
+- Front-load the key word so the list scans: Export CSV, Export PDF.
+- Ellipsis for items that open more input: Extend to a date…
+
+## Accessibility
+
+- Trigger has aria-haspopup="menu" and aria-expanded. Enter, Space or Down opens and focuses the first item.
+- role="menu" with menuitem, menuitemcheckbox or menuitemradio; checked items use aria-checked.
+- Up and Down move, Right opens a submenu, Left closes it, Esc closes and returns focus to the trigger.
+- Items are 30px high, above the 24px target minimum.
+- Focus returns to the trigger on close, so the person is not lost.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter / Space / Down | Open the menu and focus the first item |
+| Up / Down | Move between items |
+| Right | Open a submenu |
+| Left | Close a submenu |
+| Home / End | First or last item |
+| Type a letter | Jump to the next item starting with it |
+| Esc | Close and return focus to the trigger |
+
+## Examples
+
+### actions
+
+```tsx
+import { Button, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Kbd } from "@twoux/ui";
+import { Copy, ExternalLink, MoreHorizontal, Pencil, Trash2, UserRound } from "lucide-react";
+export const meta = {"title": "Actions on a record", "description": "Shortcuts on the right, destructive last and separated. Submenus open on the side with room. Arrow keys and typeahead work.", "order": 1};
+
+export default function Example() {
+	return (
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild>
+				<Button variant="outline" aria-label="Actions for Junior Product Designer" size="icon"><MoreHorizontal /></Button>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="start">
+				<DropdownMenuLabel>Listing</DropdownMenuLabel>
+				<DropdownMenuItem><Pencil />Edit<DropdownMenuShortcut><Kbd>E</Kbd></DropdownMenuShortcut></DropdownMenuItem>
+				<DropdownMenuItem><Copy />Duplicate<DropdownMenuShortcut><Kbd>D</Kbd></DropdownMenuShortcut></DropdownMenuItem>
+				<DropdownMenuSub>
+					<DropdownMenuSubTrigger><UserRound />Change owner</DropdownMenuSubTrigger>
+					<DropdownMenuSubContent>
+						<DropdownMenuItem>Grace L.</DropdownMenuItem>
+						<DropdownMenuItem>Rahul S.</DropdownMenuItem>
+						<DropdownMenuItem>Jess M.</DropdownMenuItem>
+					</DropdownMenuSubContent>
+				</DropdownMenuSub>
+				<DropdownMenuItem><ExternalLink />View public page</DropdownMenuItem>
+				<DropdownMenuSeparator />
+				<DropdownMenuItem variant="destructive"><Trash2 />Delete listing</DropdownMenuItem>
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}
+```
+
+### options
+
+```tsx
+import { Button, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuTrigger } from "@twoux/ui";
+import { ChevronDown } from "lucide-react";
+import { useState } from "react";
+export const meta = {"title": "Options with a check", "description": "Radio items for one choice, checkbox items for several. The menu stays a menu: it does not replace a form.", "order": 2};
+
+export default function Example() {
+	const [sort, setSort] = useState("posted");
+	const [cols, setCols] = useState({ salary: true, owner: false });
+	return (
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild><Button variant="outline">Display<ChevronDown /></Button></DropdownMenuTrigger>
+			<DropdownMenuContent align="start">
+				<DropdownMenuLabel>Sort by</DropdownMenuLabel>
+				<DropdownMenuRadioGroup value={sort} onValueChange={setSort}>
+					<DropdownMenuRadioItem value="posted">Posted date</DropdownMenuRadioItem>
+					<DropdownMenuRadioItem value="applies">Applies</DropdownMenuRadioItem>
+				</DropdownMenuRadioGroup>
+				<DropdownMenuSeparator />
+				<DropdownMenuLabel>Columns</DropdownMenuLabel>
+				<DropdownMenuCheckboxItem checked={cols.salary} onCheckedChange={(v) => setCols({ ...cols, salary: v })}>Salary</DropdownMenuCheckboxItem>
+				<DropdownMenuCheckboxItem checked={cols.owner} onCheckedChange={(v) => setCols({ ...cols, owner: v })}>Owner</DropdownMenuCheckboxItem>
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}
+```
+
+## Related
+
+- Button
+- Popover rules
+- Keyboard shortcut hint

package/agent/docs-md/edit-record.md

@@ -0,0 +1,73 @@
+# Editing a record: inline, section or whole page
+
+Change one value where it is shown, one section in place, or many linked settings on an edit page that mirrors the create form. Every saved edit can be undone.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Some screens open a full form to change a closing date; others edit linked settings one cell at a time and leave the record half changed. Edit forms drift away from the create form, so people meet the same field in two shapes.
+
+**Solution:** Edit one value inline. Edit one section in place: it turns into a form with Save and Cancel. Use an edit page only when several settings depend on each other, and build it from the create form with the same fields in the same order. Saving shows a toast with Undo.
+
+**Built from:** List table, Data grid, Card, Text input, Form validation, Page header, Breadcrumb, Button, Toast, Side panel (drawer)
+
+## How it works
+
+1. Ask what is changing. One value on one or many records: inline. Several values in one section of a record: section edit. Settings that depend on each other across sections: edit page.
+2. Inline: follow Inline editing and validation. Enter edits, Enter saves, Esc cancels.
+3. Section edit: an Edit button in the section header turns that section into a form with Save and Cancel at its end. Other sections stay read-only.
+4. Edit page: title "Edit Junior Product Designer", breadcrumb ending in "Edit", the create form's fields and sections in the same order, Save changes and Cancel at the end.
+5. On save, return to where the edit started and show "Listing updated. Undo". With no changes, return and show "No changes made".
+
+## When to use
+
+- Inline: values people change often or across many rows, such as stage, owner or closing date.
+- Section edit: a group that belongs together, such as Location and pay on a listing.
+- Edit page: changes where one setting limits another, such as switching a listing from Internal to Public, which adds job board and salary rules.
+
+## When not to use
+
+- Don't open an edit page to change one value.
+- Don't mix create and edit in one view, such as adding a new listing from inside the edit page of another.
+- Don't use edit for actions with their own consequence, such as Close listing or Reject candidate. They are actions with their own button and, where needed, confirmation.
+
+## Guidelines
+
+- The edit page reuses the create form component, so labels, order, hints and validation never drift apart.
+- Save changes stays enabled. Validate on submit, keep the person's input, and show server errors above the buttons so nothing has to be typed again.
+- An edited row that no longer matches the filters or sort stays in place, marked, until the list refreshes, so it doesn't vanish under the cursor.
+- Lists of repeated values, such as screening questions or interview stages, use rows with Add and Remove. Removing a row takes effect on save and says so: "Removed when you save".
+- Leaving an edit with unsaved changes asks "Discard changes?" with Keep editing focused.
+- Every saved edit is reversible with Undo in the toast, ⌘Z and the record's activity.
+
+## Content
+
+- Edit page title: "Edit" plus the record name. Submit button: "Save changes".
+- Section headings match the create form word for word.
+- Limits on repeated rows say what is left: "You can add 3 more questions."
+
+## Accessibility
+
+- When a section switches to edit, focus moves to its first field; on Save or Cancel it returns to the section's Edit button.
+- Each Edit button names its section: aria-label "Edit location and pay".
+- When a repeated row is added, focus moves to its first input; when removed, focus moves to the next row or the Add button.
+
+## Do
+
+- Do edit in place when the change is small.
+- Do mirror the create form exactly on the edit page.
+- Do offer Undo after every saved edit.
+
+## Don't
+
+- Don't disable Save changes until something changes.
+- Don't put two Edit modes on the screen at once; one section edits at a time.
+- Don't open a dialog to edit a section of a record that is already in a side panel.
+
+## Related
+
+- Creating a record: dialog, single page or steps
+- Inline editing and validation
+- Undo and destructive actions
+- Record detail: side panel, overlay or full page
+- Form validation
+- Data grid

package/agent/docs-md/empty-loading-error.md

@@ -0,0 +1,78 @@
+# Empty, loading and error states
+
+One rule set for the three states every view has before or instead of data: loading, nothing to show, and failed.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** A blank table can mean loading, no data, no matches or a failure. When screens handle these differently, people wait for data that never comes or give up on data that was about to arrive.
+
+**Solution:** Skeleton rows while loading, an empty state with one next step when there is nothing, a zero results state when filters match nothing, and an error state that keeps the filters and offers Try again.
+
+**Built from:** Loading skeleton, Empty state, Error state (failed to load), Banner (inline alert), List table, Data grid
+
+## How it works
+
+1. Under about one second, show nothing extra. Beyond that, keep the table's shape with skeleton rows.
+2. If the load succeeds with no records, replace the table with an empty state: what goes here, and one action to add it.
+3. If records exist but filters match none, show the zero results state with Clear filters.
+4. If the load fails, replace the table with an error state that says what failed, keeps the filters and offers Try again (R).
+5. When a refresh fails after data has loaded, keep the old data on screen and show a warning beside the refresh time.
+
+## When to use
+
+- On every table, grid, chart card, panel and assistant answer that loads data.
+
+## When not to use
+
+- For a brand new workspace with nothing set up. Use Onboarding to an empty workspace with the setup checklist.
+
+## Guidelines
+
+- Never show "No listings" before loading has finished; people stop waiting and miss the data.
+- Skeletons for structured content (tables, cards); a spinner for a single element such as a button or expanding row; a progress bar beyond about ten seconds.
+- Empty and zero results states replace the table and its headers, so screen readers don't meet an empty table.
+- Every state offers a next step. No dead ends.
+- Errors never use the empty state component; they use the error state or a banner.
+- Show when data was last updated after each refresh.
+- Charts follow the same states with chart-specific shapes: the plot skeleton while loading, an empty state for no data, a no match state with Clear filters after filtering, and an error state with Try again, each inside the chart card so the title and controls stay.
+- Manual refresh lives in the table header as an icon button labelled "Refresh listings", next to "Last updated 2 minutes ago". Add a refresh button only where data changes while people watch; other views refresh on load.
+- During a refresh keep the current rows on screen and usable; only the refresh button shows a spinner.
+- If a refresh takes longer than about ten seconds, show a "Taking longer than usual" status beside the refresh time; if it partly fails, show a warning status there with what failed and Try again.
+- Wrap each region (table, chart card, side panel) in its own error boundary, so a crash shows an error state in that region and the rest of the page still works.
+- Inside a table or read-only details, an empty value shows a muted hyphen (-) with the accessible name "Not set". Never use a dash for a real zero; show 0.
+- Keep the count in the table heading even when empty: "Listings (0)".
+
+## Content
+
+- Empty: "No listings yet" plus "Create listing". Zero results: "No listings match these filters" plus "Clear filters".
+- Error: "Couldn't load listings", then the likeliest cause, then "Your filters are kept." Avoid "sorry" and error codes.
+- Loading text names the thing without articles or end punctuation: "Loading listings".
+- The empty state's action uses the same label as the header button it mirrors ("Create listing") and is a secondary button, since the header already has the primary.
+- An empty state description explains why it is empty and never repeats the heading or button text.
+
+## Accessibility
+
+- Announce loading, loaded counts and failures as status messages without moving focus.
+- Hide decorative empty state illustrations from screen readers with empty alt text.
+- Error states are identified in text, not only with a red icon.
+- The refresh button has loading text ("Refreshing listings"), and the new "Last updated" time is announced politely.
+
+## Do
+
+- Do keep the layout stable from skeleton to data.
+- Do keep filters when a load fails.
+
+## Don't
+
+- Don't use a full-page spinner for a table load.
+- Don't show a frame-only skeleton with no placeholder rows.
+- Don't write jokes into error messages.
+
+## Related
+
+- Filtering and search
+- Onboarding to an empty workspace
+- Generated table columns and enrichment
+- Empty state
+- Loading skeleton
+- Error state (failed to load)

package/agent/docs-md/empty-state.md

@@ -0,0 +1,128 @@
+# Empty state
+
+What a list, table or panel shows when it loaded correctly but has nothing to show, with the next step.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- Filters or search match nothing: "No listings match these filters".
+- Nothing has been created yet, such as a team with no listings.
+- A queue is cleared, such as the Inbox: "All caught up".
+
+## When not to use
+
+- Data is still loading. Use the Loading skeleton.
+- Loading failed. Use the Error state, never an empty message.
+- Only part of a record is missing, such as one field. Show "Add" in the field itself.
+
+## Structure
+
+1. Icon tile (32px, neutral)
+2. Title: the state, sentence case, no full stop
+3. Description: why, and what to try (max 36 characters wide per line block)
+4. One action (secondary button), or none for a finished state
+5. Dashed container sized to the region it replaces
+
+## Guidelines
+
+- Replace the region that would hold the data, inside the same container, so filters and the result count stay in place.
+- Distinguish no data (nothing created) from no results (filters too narrow); they need different actions.
+- Give one next step: Clear filters for no results, the create action for no data. Never leave a dead end.
+- Keep the result count visible ("0 of 24") so the person sees the filters, not the data, caused the empty view.
+- Show the empty state only after loading finishes; never as placeholder text that is later replaced.
+
+## Content
+
+- Title names the state plainly and briefly: "No listings match these filters".
+- Description says why and what to try, without repeating the title: "Try a wider date range, or clear the location filter."
+- Button label starts with a verb and matches the next step: "Clear filters", "New listing".
+- Neutral tone for no results; a short positive line for a finished queue. No jokes, no apologies.
+
+## Accessibility
+
+- Replace the whole table, headers included, so screen readers do not read an empty structure first (1.3.1).
+- When filtering produces zero results, announce the new count through a polite live region (4.1.3).
+- The icon is decorative and has empty alt text.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Reaches the single action |
+| F | Opens the filter picker to change filters instead of clearing them |
+
+## Examples
+
+### no-data
+
+```tsx
+import { Button, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "@twoux/ui";
+import { BriefcaseBusiness, Plus } from "lucide-react";
+
+export const meta = { title: "No data yet", description: "Nothing has been created. The one action is the create action, not Clear filters.", order: 2 };
+
+export default function Example() {
+	return (
+		<Empty className="w-full max-w-xl">
+			<EmptyHeader>
+				<EmptyMedia variant="icon"><BriefcaseBusiness /></EmptyMedia>
+				<EmptyTitle>No listings yet</EmptyTitle>
+				<EmptyDescription>Listings you publish appear here, with their applicants.</EmptyDescription>
+			</EmptyHeader>
+			<EmptyContent>
+				<Button variant="outline" size="sm"><Plus />New listing</Button>
+			</EmptyContent>
+		</Empty>
+	);
+}
+```
+
+### no-results
+
+```tsx
+import { Badge, Button, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "@twoux/ui";
+import { SearchX, X } from "lucide-react";
+import { useState } from "react";
+
+export const meta = { title: "No results", description: "Filters are too narrow. The empty state replaces the table only; the filters and the count stay, so it is clear the filters caused it. One action: Clear filters.", order: 1 };
+
+export default function Example() {
+	const [filtered, setFiltered] = useState(true);
+	return (
+		<div className="grid w-full max-w-xl gap-2">
+			<div className="flex items-center gap-2">
+				<span className="text-base font-medium text-ink">Listings</span>
+				{filtered && (
+					<Badge variant="secondary" className="gap-1">
+						Location: Inverness
+						<Button variant="ghost" size="icon-xs" aria-label="Remove filter Location: Inverness" onClick={() => setFiltered(false)} className="-mr-1 size-4"><X className="size-3" /></Button>
+					</Badge>
+				)}
+				<span className="ml-auto text-sm text-ink-3 tabular">{filtered ? "0 of 24" : "24 of 24"}</span>
+			</div>
+			{filtered ? (
+				<Empty className="min-h-56">
+					<EmptyHeader>
+						<EmptyMedia variant="icon"><SearchX /></EmptyMedia>
+						<EmptyTitle>No listings match these filters</EmptyTitle>
+						<EmptyDescription>Try another location, or clear the filters to see all 24.</EmptyDescription>
+					</EmptyHeader>
+					<EmptyContent>
+						<Button variant="outline" size="sm" onClick={() => setFiltered(false)}>Clear filters</Button>
+					</EmptyContent>
+				</Empty>
+			) : (
+				<div className="grid min-h-56 place-items-center rounded-sm border border-line text-base text-ink-2">24 listings</div>
+			)}
+		</div>
+	);
+}
+```
+
+## Related
+
+- Loading skeleton
+- Error state (failed to load)
+- Inbox (triage)
+- Setup checklist

package/agent/docs-md/error-messages.md

@@ -0,0 +1,75 @@
+# Error messages
+
+Put every error where it happened, at the smallest scope that contains it, and say what went wrong and what to do next in plain words.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Errors shown far from their cause, raw API text, and messages that blame the person or promise help that never comes all erode trust. When one chart fails and the whole page goes blank, people lose work they could have kept doing.
+
+**Solution:** Match the place to the scope: a field error under the field, a form error in a banner above the form actions, a failed region in an error state that replaces only that region, a failed page in a page-level error state. Every message has a cause if known and a next step.
+
+**Built from:** Form validation, Banner (inline alert), Error state (failed to load), Toast, Text input, Code block
+
+## How it works
+
+1. Find the smallest scope that contains the failure: one field, one form, one region (a chart card, the side panel, a table), or the whole page.
+2. Field: message under the field. Form or server error with no field: banner above the form's buttons. Region: error state in place of that region only. Page: error state in place of the page content.
+3. For an action that failed after the person left the screen, such as an export or a bulk close, put a banner on the page they are on and an Inbox item; never a toast that fades.
+4. Write the message: what happened, why if known, what to do now. Add Try again when retrying could work.
+5. Put technical detail (request ID, error code) in a collapsed Details section the person can copy into a support request.
+
+## When to use
+
+- Any time something failed and the person needs to know: a value is invalid, a save failed, data didn't load, an action was refused.
+- Unexpected crashes in one part of the page: wrap each region in an error boundary so the rest stays usable.
+- When an action partly worked, such as a bulk close where some listings were already closed by someone else.
+
+## When not to use
+
+- For warnings or advice, such as a salary below the advertised range for similar roles. Use a warning banner or field warning; errors mean something must be fixed now.
+- For a list that loaded fine and is empty. Use the empty state.
+- For a reversible action that worked. Use a toast.
+
+## Guidelines
+
+- Use the built-in error state of a component (a combobox that failed to load options, a chart that failed to fetch) before inventing a new one.
+- Errors never auto-dismiss. A failed save stays visible until it succeeds or the person dismisses it.
+- Keep what the person entered. A failed submit leaves every field filled and stays on the page until the result is known.
+- Show the count when it helps: "3 of 12 listings couldn't be closed", with a link that filters to those three.
+- Never claim the team has been told unless errors really are reported automatically.
+- Report unexpected errors to the error tracker with the request ID shown in Details, so a support request can be matched.
+
+## Content
+
+- Pattern: what happened, then what to do. "Couldn't save the closing date. Check your connection and try again."
+- Don't blame: "Enter a closing date after today", not "You entered an invalid date".
+- Plain words over codes: "This listing was changed by Tom Reid while you were editing" rather than "409 Conflict".
+- No "Oops", no jokes, no exclamation marks, no "sorry" in every message.
+
+## Accessibility
+
+- Errors are text and an icon, never colour alone.
+- Field errors link to their field with aria-describedby and set aria-invalid.
+- A banner that appears after submit moves focus to itself, or to the first field in error; a region error is announced as a status without stealing focus.
+- Suggest the fix when it is known (3.3.3).
+
+## Do
+
+- Do keep the failure inside the region that failed.
+- Do offer Try again when a retry could work.
+- Do keep the person's input after any failure.
+
+## Don't
+
+- Don't show raw API or stack trace text as the main message.
+- Don't report a failure in a toast that disappears after 6 seconds.
+- Don't use red error styling for a warning.
+
+## Related
+
+- Inline editing and validation
+- Empty, loading and error states
+- Notifications: inbox, bell, toast or email digest
+- Banner (inline alert)
+- Error state (failed to load)
+- Form validation