@logicplanes/kaeso-ui 0.4.3 → 0.4.5

package/ai/component-guides.md

@@ -1,10 +1,10 @@
 # @logicplanes/kaeso-ui component guides
 
-Version 0.4.3. Generated from the showcase's demo modules (apps/showcase/src/demos); do not edit. For each component: what it is for, its import, keyboard, accessibility, do and don't, and every example's code. Props and variants: `component-registry.md`.
+Version 0.4.5. Generated from the showcase's demo modules (apps/showcase/src/demos); do not edit. For each component: what it is for, its import, keyboard, accessibility, do and don't, and every example's code. Props and variants: `component-registry.md`.
 
 ## AgentAttribution
 
-A person's avatar with the agent that acted for them as a badge on its corner, for audit rows and activity.
+A person's avatar with the agent that acted for them as a small round badge on its corner, for audit rows and activity.
 
 `import { AgentAttribution } from "@logicplanes/kaeso-ui";`
 
@@ -39,7 +39,7 @@ A person's avatar with the agent that acted for them as a badge on its corner, f
 
 ## AgentAvatar
 
-An agent acting for a person: one bot face on an ink square, the same for every agent.
+An agent acting for a person: one bot face on a square, the same for every agent.
 
 `import { AgentAvatar, useModelName } from "@logicplanes/kaeso-ui";`
 
@@ -96,8 +96,9 @@ Confirms an irreversible action: names it, says the consequence, can ask for typ
 
 ### Accessibility
 
-- role=alertdialog; focus starts on Cancel.
+- role=alertdialog. The focus starts on the typed field when there is one; otherwise on Cancel, or on the confirm for an info confirmation.
 - The confirm names the verb and object (“Delete key”).
+- The Enter that finishes typing in an input method never confirms.
 
 ### Examples
 
@@ -136,8 +137,9 @@ The console frame: the sidebar on the grey chrome, content in an inset rounded p
 
 - The sidebar is a nav landmark and the panel is main.
 - The first Tab stop is Skip to content, shown only while it has focus; it moves the focus to the panel, so the next Tab reaches the page's first control without passing the navigation.
-- Below 1024px a bar above the panel shows the wordmark alone at the top left, 28px in and 28px down, and the navigation toggle at the right; the toggle is named Open navigation, says whether the sheet is open (aria-expanded), and takes the focus back when the sheet closes.
-- A collapsed sidebar peeks when its expand button is held under the pointer for 750ms.
+- Below 1024px a bar above the panel shows the wordmark alone at the top left, on the page's 24px gutter and 28px down, and the navigation toggle at the right; the toggle is named Open navigation, says whether the sheet is open (aria-expanded), and takes the focus back when the sheet closes.
+- A collapsed sidebar peeks when its expand button is held under the pointer for 750ms; the peek closes when the pointer leaves for the page, never dims it, and stays inside an embedded frame.
+- Expanding the sidebar with the button or [ gives the focus back to the item that collapsed it, or to its collapse button.
 
 ### Examples
 
@@ -602,11 +604,14 @@ Related actions side by side: connected pills, or spaced.
 | Key | Action |
 |---|---|
 | Tab | Moves between the buttons |
+| Enter | Activates the focused button |
+| Space | Activates the focused button |
 
 ### Accessibility
 
 - The group has role=group; give it an aria-label when the buttons alone do not explain it.
 - Icon-only items need an aria-label and show it as a tooltip.
+- Items with pressed are toggles: aria-pressed says which is selected, and the selected item turns ink, well above 3:1 in both themes, so the choice never rests on a faint fill.
 
 ### Examples
 
@@ -639,6 +644,29 @@ Related actions side by side: connected pills, or spaced.
 </ButtonGroup>
 ```
 
+#### Toggle
+
+Pass pressed to make items toggles, such as display options in a log view; selected items turn ink. Choosing one view among a few is Segmented.
+
+```tsx
+function Toggle() {
+  const [on, setOn] = useState<Record<string, boolean>>({ wrap: true, time: false, ids: true });
+  return (
+    <ButtonGroup size="sm" aria-label="Log display">
+      {[
+        ["wrap", "Wrap lines"],
+        ["time", "Timestamps"],
+        ["ids", "Request IDs"],
+      ].map(([id = "", label]) => (
+        <ButtonGroup.Item key={id} pressed={!!on[id]} onClick={() => setOn((o) => ({ ...o, [id]: !o[id] }))}>
+          {label}
+        </ButtonGroup.Item>
+      ))}
+    </ButtonGroup>
+  );
+}
+```
+
 ## Checkbox
 
 An 18px box: raised and ringed, ink when checked, with a check that draws itself.
@@ -676,13 +704,14 @@ An 18px box: raised and ringed, ink when checked, with a check that draws itself
 
 ## ClientButton
 
-An agent client's mark on a raised tile, such as Claude, Cursor or GitHub Copilot, that opens how to connect it.
+An agent client's mark in a raised circle, such as Claude, Cursor or GitHub Copilot, that opens how to connect it.
 
 `import { ClientButton } from "@logicplanes/kaeso-ui";`
 
 ### Accessibility
 
 - A button named by `aria-label`, which is also its tooltip; the mark is decorative.
+- A 32px circle with a 44px hit area on touch screens.
 
 ### Examples
 
@@ -712,6 +741,7 @@ Copy a value: a read-only pill field, a copy circle, or inline text that copies
 ### Accessibility
 
 - The copy circle's name changes to “Copied” for 1.2 seconds and the tooltip says it.
+- A value too long for its pill ends in an ellipsis; the text then becomes focusable and shows the whole value in a tooltip.
 - InlineCopyText announces “Copied” through a polite live region.
 - Nothing changes size when the state changes.
 
@@ -746,7 +776,7 @@ A read-only pill with the value in mono and a copy circle inside.
 
 ## Code
 
-Inline code: Geist Mono 13 on a soft fill. A pill for one word.
+Inline code: Geist Mono 13 on a soft fill, radius 6 in running text.
 
 `import { Code } from "@logicplanes/kaeso-ui";`
 
@@ -766,13 +796,14 @@ Inline code: Geist Mono 13 on a soft fill. A pill for one word.
 
 ## CodeBlock
 
-Highlighted code on a well in Kaeso's monochrome theme: copy on hover, tabs, line numbers, collapse.
+Highlighted code on a well in Kaeso's monochrome theme: copy in the header or on hover, tabs, line numbers, collapse.
 
 `import { CodeBlock } from "@logicplanes/kaeso-ui";`
 
 ### Accessibility
 
-- The copy circle is named “Copy code” and confirms with “Copied”.
+- The copy circle is named “Copy code” and confirms with “Copied”; with a title or tabs it stays in the header.
+- The code is one tab stop, named after its title, and scrolls sideways with the arrow keys.
 
 ### Examples
 
@@ -808,7 +839,7 @@ Highlighted code on a well in Kaeso's monochrome theme: copy on hover, tabs, lin
 
 ## Collapsible
 
-Disclosure rows with a chevron that turns in 180ms and a measured height animation; Accordion groups them.
+Disclosure rows: a pill row with the title 12px in, a chevron at its end that turns in 200ms, and a measured height animation; Accordion groups them.
 
 `import { Collapsible, Accordion } from "@logicplanes/kaeso-ui";`
 
@@ -818,6 +849,11 @@ Disclosure rows with a chevron that turns in 180ms and a measured height animati
 |---|---|
 | Enter Space | Opens and closes |
 
+### Accessibility
+
+- The title is a button with aria-expanded; its content follows it in the reading order.
+- The same row recipe as the sidebar's groups: a pill that fills on hover, a focus ring inside it, 44px tall with a coarse pointer.
+
 ### Examples
 
 #### Collapsible
@@ -914,6 +950,7 @@ A search field over a long list that stays fast with thousands of rows, grouped
 
 ### Accessibility
 
+- After typing pauses, a screen reader hears how many rows match, or that none do.
 - The search field is a combobox that points at the active row; the list is a listbox with one group per caption.
 - Each row says its position in the whole list, so a screen reader counts every row, not just those drawn.
 
@@ -993,11 +1030,14 @@ function Thousands() {
 | Up Down | Moves |
 | Enter | Opens the item or its page |
 | Backspace | Goes back a page when the search is empty |
-| Escape | Closes |
+| Escape | Closes; on a nested page, clears the search, then goes back a page |
 
 ### Accessibility
 
 - The input is a combobox controlling the results listbox; the active result is announced.
+- A result is named by its label, with its hint and shortcut after a pause.
+- On a nested page, the chip before the search goes back a page.
+- After typing pauses, a screen reader hears how many results match.
 
 ### Examples
 
@@ -1032,7 +1072,8 @@ Models side by side: one to four equal columns, each with a header, a thread tha
 ### Accessibility
 
 - The grid is a named group; each column is a region named after its model, and its thread a region of its own.
-- On a phone, Previous column and Next column move between columns, and “2 of 3” is announced.
+- On a phone, or when the columns don't fit, Previous column and Next column move between columns, and “Claude Sonnet 4.5, 2 of 3” is announced.
+- Adding a column moves the focus to its header; removing one moves it to the column that takes its place.
 - A thread stays at its end while a response grows, unless the person scrolled up to read.
 
 ### Examples
@@ -1073,6 +1114,8 @@ The prompt box: grows with what is written, then scrolls; Send, which becomes St
 - Enter never sends while an input method is composing (Chinese, Japanese, Korean): the Enter that picks a candidate stays the input method's.
 - On a touch screen Enter adds a line and the Send button sends, as in the messaging apps there; elsewhere the on-screen keyboard's Enter key reads Send (enterkeyhint).
 - Send and Stop are one button that keeps its place and width, so the focus stays on it when a response starts or ends.
+- While a response arrives, the text box's description says to stop it to send the next prompt.
+- A click anywhere in the box, the button row included, puts the cursor in the text box.
 
 ### Examples
 
@@ -1130,11 +1173,13 @@ The same menu on right-click and the context-menu key.
 
 | Key | Action |
 |---|---|
-| Shift F10 | Opens the menu for the focused element |
+| Shift F10 | Opens the menu for the focused row |
+| Escape | Closes and returns focus to the row |
 
 ### Accessibility
 
 - Every action in a context menu must also be reachable another way.
+- An area with nothing focusable in it becomes a focus stop, so the keyboard can open its menu.
 
 ### Examples
 
@@ -1142,9 +1187,7 @@ The same menu on right-click and the context-menu key.
 
 ```tsx
 <ContextMenu>
-  <ContextMenu.Trigger className="flex h-44 w-400 items-center rounded-item bg-fill-1 px-16 text-body text-fg">
-    Right-click this request
-  </ContextMenu.Trigger>
+  <ContextMenu.Trigger className={ROW}>Right-click this request</ContextMenu.Trigger>
   <ContextMenu.Content>
     <ContextMenu.Item icon={icons.openExternal}>Open in a sheet</ContextMenu.Item>
     <ContextMenu.Item icon={icons.copy}>Copy request id</ContextMenu.Item>
@@ -1196,18 +1239,24 @@ The console's table: a 36px header, 40px rows without lines, numbers right, sort
 
 | Key | Action |
 |---|---|
-| Tab | Moves into the table, to the row last in focus, and out again |
-| Up Down | Move between rows |
-| Home End | First and last row |
+| Tab | Moves into the table, to the row or header last in focus, and out again: the table is one tab stop |
+| Up Down | Move between rows; Up from the first row reaches the header |
+| Left Right | Move between the header's sort buttons; on a row, Right reaches the row's controls and Left comes back |
+| shift Left Right | Resize the column, on its header |
+| Home End | First and last row, or first and last header |
 | Page Up Page Down | A screen of rows up or down |
 | Enter | Opens the row |
-| Space | Selects the row, in a selectable table |
-| Left Right | Resize a column, on its handle |
-| shift F10 | Opens the row menu |
+| Space | Selects the row, in a selectable table (also x) |
+| shift Up Down | Extends the selection |
+| mod A | Selects every row |
+| Escape | Returns from a row's control to its row; on a row, clears the selection |
+| shift F10 | Opens the row menu, or the column's width menu on its header |
 
 ### Accessibility
 
-- role=table with column headers; sorted columns carry aria-sort.
+- An ARIA table whose rows are one tab stop, moved through with the arrow keys; sorted columns carry aria-sort, the open row aria-current.
+- One tab stop: checkboxes, row controls and resize handles stay out of the tab order and are reached with the arrow keys.
+- A column's width changes by dragging its handle, with Shift and the arrow keys on its header, or from the header's context menu (Widen, Narrow, Reset width), so no drag is required.
 - Columns declare a priority; low-priority columns hide first when space is short. A growing column then shrinks to its readable minimum (minWidth, 136px by default) and truncates. On a screen narrower still, the other priority 1 columns give way from the row's end backwards, keeping its last column (the actions) and the selection boxes; only a row with nothing left to give way scrolls sideways, its last column pinned at the end.
 - Over 100 rows render virtually; the row count is in aria-rowcount and each row's place in aria-rowindex.
 
@@ -1359,16 +1408,28 @@ The destructive flow: the object and the consequence, typed confirmation, a dang
 
 ### Examples
 
-#### Archive a project
+#### Delete a project
 
 ```tsx
 <DeleteResource
   kind="project"
-  verb="Archive"
   name="Checkout assistant"
-  consequence="Its keys stop working. Logs stay for 30 days, then they are deleted."
+  consequence="Its keys stop working at once, and its request logs are deleted. This can't be undone."
+  onConfirm={() => new Promise((r) => setTimeout(r, 900))}
+  trigger={<Button variant="danger-secondary">Delete project</Button>}
+/>
+```
+
+#### Delete a key
+
+```tsx
+<DeleteResource
+  kind="key"
+  name="checkout-web"
+  confirm="simple"
+  consequence="Applications using it stop authenticating with the gateway."
   onConfirm={() => new Promise((r) => setTimeout(r, 900))}
-  trigger={<Button variant="danger-secondary">Archive project</Button>}
+  trigger={<Button variant="danger-secondary">Delete key</Button>}
 />
 ```
 
@@ -1635,19 +1696,14 @@ function Changing() {
 #### Sizes
 
 ```tsx
-<div className="flex gap-12">
-  {(["sm", "md", "lg"] as const).map((s) => (
+<div className="flex flex-wrap gap-12">
+  {sizes.map((s) => (
     <Dialog
-      key={s}
-      size={s}
-      trigger={<Button>{s}</Button>}
-      title={`A ${s} dialog`}
+      key={s.size}
+      size={s.size}
+      trigger={<Button>{s.open}</Button>}
+      title={`${s.width} pixels wide`}
       description="Sizes are 440, 560 and 720 pixels."
-      footer={
-        <Dialog.Close>
-          <Button>Close</Button>
-        </Dialog.Close>
-      }
     />
   ))}
 </div>
@@ -1686,6 +1742,35 @@ function CreateKey() {
 }
 ```
 
+## DiffView
+
+Two versions in one column: removed lines on red, added on green, changed words marked, unchanged runs folded.
+
+`import { DiffView } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- Each changed line starts with “Added” or “Removed” for screen readers; the + and − marks and the colour are only for sight.
+- The title bar says how many lines were added and removed, and each folded run is a button that names how many lines it shows.
+
+### Examples
+
+#### An audit event
+
+```tsx
+<div className="w-560 max-w-full">
+  <DiffView title="Before → after" lang="json" before={json(credential)} after={json(moved)} wrap />
+</div>
+```
+
+#### With line numbers
+
+```tsx
+<div className="w-560 max-w-full">
+  <DiffView title="limit.json" lang="json" before={json(limit)} after={json(raised)} lineNumbers />
+</div>
+```
+
 ## DisplayOptions
 
 View, grouping and ordering, toggles, and the properties to show, behind one circle at the end of a toolbar.
@@ -1762,7 +1847,7 @@ What someone can do at a glance: a row per group, in words, under the roles it c
 
 ## Empty
 
-What is absent and the next step: an icon circle, a title, one sentence, one or two actions.
+What is absent and the next step: a title, one sentence, one action.
 
 `import { Empty } from "@logicplanes/kaeso-ui";`
 
@@ -1773,13 +1858,12 @@ What is absent and the next step: an icon circle, a title, one sentence, one or
 ```tsx
 <Empty
   title="No keys yet"
-  description="Create a key so an application can call the gateway."
-  actions={
+  description={
     <>
-      <Button variant="primary">Create key</Button>
-      <Button>Read about keys</Button>
+      Create a key so an application can call the gateway. <Link href="https://docs.kaeso.app">Read about keys</Link>
     </>
   }
+  actions={<Button variant="primary">Create key</Button>}
 />
 ```
 
@@ -1800,6 +1884,8 @@ A label, a control and its help, wired together; an error shows under the contro
 - The label points at the control; help is in aria-describedby.
 - invalid sets aria-invalid and the danger ring; error shows what is wrong under the control and is its description for a screen reader.
 - Optional fields are marked, not required ones.
+- Fieldset's legend names the group, so each field inside is heard with it; its description describes the group.
+- After a failed submit, move focus to the first invalid field: its error is then read with it.
 
 ### Examples
 
@@ -1830,8 +1916,8 @@ A label, a control and its help, wired together; an error shows under the contro
   <Field label="Name" layout="horizontal" description="Shown in logs.">
     <Input defaultValue="checkout-web" />
   </Field>
-  <Field label="Monthly budget" layout="horizontal" invalid>
-    <Input defaultValue="-20" suffix="USD" />
+  <Field label="Monthly budget" layout="horizontal" error="Enter an amount of 0 or more.">
+    <Input defaultValue="-20" suffix="USD" align="end" />
   </Field>
 </div>
 ```
@@ -2011,6 +2097,33 @@ A node-and-connector diagram for the route: app → Kaeso → provider and model
 <Flow columns={columns} edges={edges} aria-label="Requests go from your app through the Kaeso gateway to gpt-5 or claude-sonnet-4-5" />
 ```
 
+#### A route that changes
+
+With animated, a dot runs once along each connector when the route changes; never on load and never with reduced motion.
+
+```tsx
+function Changes() {
+  const [fallback, setFallback] = useState(false);
+  const target = fallback ? "anthropic" : "openai";
+  return (
+    <div className="flex flex-col items-start gap-16">
+      <Flow
+        animated
+        columns={columns}
+        edges={[
+          ["app", "kaeso"],
+          ["kaeso", target],
+        ]}
+        aria-label={`Requests go from your app through the Kaeso gateway to ${fallback ? "claude-sonnet-4-5" : "gpt-5"}`}
+      />
+      <Button variant="secondary" size="sm" onClick={() => setFallback(!fallback)}>
+        {fallback ? "Route to gpt-5" : "Route to claude-sonnet-4-5"}
+      </Button>
+    </div>
+  );
+}
+```
+
 ## Gauge
 
 A semicircle for “budget used”; thresholds as ticks.
@@ -2142,11 +2255,11 @@ Hugeicons free, Stroke Rounded, in currentColor. One icon per Kaeso concept.
 #### Vocabulary
 
 ```tsx
-<div className="grid w-full grid-cols-2 gap-x-16 gap-y-4 sm:grid-cols-4">
+<div className="grid w-full grid-cols-2 gap-x-8 gap-y-4 sm:grid-cols-4 sm:gap-x-16">
   {(Object.keys(icons) as IconName[]).map((n) => (
-    <div key={n} className="flex h-32 items-center gap-8 text-small text-fg-secondary">
+    <div key={n} className="flex min-h-32 items-center gap-8 text-small text-fg-secondary">
       <Icon icon={icons[n]} size="sm" className="text-fg" />
-      <span className="mono truncate">{n}</span>
+      <span className="mono min-w-0 text-caption wrap-anywhere sm:text-small">{n}</span>
     </div>
   ))}
 </div>
@@ -2169,7 +2282,7 @@ A circle with an icon, a required name, and a tooltip that says it.
 
 - aria-label is required by the types; it is also the tooltip, so sighted and screen-reader users get the same name.
 - Shortcuts appear in the tooltip as key caps.
-- Disabled icon buttons have no tooltip unless they carry a disabledReason.
+- Disabled icon buttons have no tooltip unless they carry a disabledReason, which the tooltip shows and screen readers read as the description.
 
 ### Examples
 
@@ -2239,12 +2352,12 @@ A pill text field with the secondary material and a soft focus halo.
 
 #### With label and help
 
-An invalid value gets the danger ring; what is wrong goes in a toast.
+An invalid value gets the danger ring and a message under the field that says what to enter.
 
 ```tsx
 <div className="flex w-360 flex-col gap-24">
   <Input label="Key name" description="Shown in logs and the audit log." placeholder="checkout-web" />
-  <Input label="Monthly budget" defaultValue="-20" suffix="USD" invalid />
+  <Input label="Monthly budget" defaultValue="-20" suffix="USD" align="end" error="Enter an amount of 0 or more." />
 </div>
 ```
 
@@ -2286,6 +2399,7 @@ Addons inside the pill: text, icons, a ghost circle or a key cap, sharing one fo
 ### Accessibility
 
 - Addons are text the input's label should not repeat; buttons inside need their own names.
+- invalid on the group also marks the input aria-invalid, and disabled turns off its input and buttons.
 
 ### Examples
 
@@ -2294,12 +2408,12 @@ Addons inside the pill: text, icons, a ghost circle or a key cap, sharing one fo
 ```tsx
 <div className="flex w-400 flex-col gap-12">
   <InputGroup>
-    <InputGroup.Addon>https://</InputGroup.Addon>
+    <InputGroup.Addon data-join>https://</InputGroup.Addon>
     <InputGroup.Input aria-label="Host" placeholder="kaeso.example.com" />
     <InputGroup.Addon>/v1</InputGroup.Addon>
   </InputGroup>
   <InputGroup trailingButton>
-    <InputGroup.Input aria-label="Token" defaultValue="sk-kso-AbC123…wxyz" className="mono text-small" />
+    <InputGroup.Input aria-label="Token" defaultValue="sk-kso-AbC123…wxyz" data-mono />
     <InputGroup.Button icon={icons.copy} aria-label="Copy" />
   </InputGroup>
   <InputGroup leadingIcon>
@@ -2315,6 +2429,20 @@ A folding JSON tree: copy any path, highlight a search.
 
 `import { JsonView } from "@logicplanes/kaeso-ui";`
 
+### Keyboard
+
+| Key | Action |
+|---|---|
+| Tab | Moves into the tree, then out of it: the tree is one tab stop |
+| ↑ ↓ | Moves between rows |
+| → ← | Opens and closes an object or array, or moves into it and back to its parent |
+| Enter Space | Opens or closes an object or array |
+| ⌘C Ctrl C | Copies the row's path |
+
+### Accessibility
+
+- The tree is a tree of rows with their level and open state; a copied path is announced.
+
 ### Examples
 
 #### Request body
@@ -2339,7 +2467,8 @@ Key caps and shortcuts: ⌘ ⌥ ⇧ ⌃ on macOS, words elsewhere; sequences lik
 
 ### Accessibility
 
-- Modifier symbols carry an aria-label with the key's name.
+- A symbol such as ⌘ is hidden from screen readers and its name (“Command”) is read instead; letters need no extra name.
+- Inside a button, the shortcut stays out of the button's name, which is its visible label.
 
 ### Examples
 
@@ -2490,6 +2619,7 @@ The name of a field: 14/500, with an optional “Optional”.
 ### Accessibility
 
 - Connect it to its control with htmlFor; Field does this for you.
+- Beside a disabled control, pass data-disabled so the label dims with it.
 
 ### Examples
 
@@ -2518,7 +2648,7 @@ A second layer slides over the first (add model → review values); Back returns
 
 | Key | Action |
 |---|---|
-| Escape | Closes and returns focus to the trigger |
+| Escape | Closes the dialog from any layer and returns focus to the trigger |
 | Tab | Moves within the layer shown |
 | mod Enter | Calls onSubmit, on every layer |
 
@@ -2636,7 +2766,7 @@ function Wizard() {
 
 ## Link
 
-Links look like links: text color with a quiet underline that turns solid on hover.
+Links look like links: text color with a grey underline that takes the text color on hover.
 
 `import { Link } from "@logicplanes/kaeso-ui";`
 
@@ -2650,6 +2780,7 @@ Links look like links: text color with a quiet underline that turns solid on hov
 
 - External links open in a new tab, add rel="noopener noreferrer" and say so to screen readers.
 - Router links come from LinkProvider.
+- The underline is the cue that text is a link, so it stays visible at rest; color alone never marks a link.
 
 ### Examples
 
@@ -2954,6 +3085,7 @@ A rounded dropdown: 16px radius, 34px rows, icons that wake on highlight.
 - role=menu with menuitem, menuitemcheckbox and menuitemradio.
 - Groups of more than seven items get a caption or a separator.
 - Danger items name the action: “Delete key”.
+- An item's shortcut and hint describe it; its name is the label alone.
 
 ### Examples
 
@@ -2970,9 +3102,7 @@ A rounded dropdown: 16px radius, 34px rows, icons that wake on highlight.
     <Menu.Item icon={icons.limit}>Edit limits</Menu.Item>
     <Menu.Separator />
     <Menu.Item icon={icons.hide}>Disable</Menu.Item>
-    <Menu.Item icon={icons.delete} variant="danger">
-      Archive key
-    </Menu.Item>
+    <Menu.Item variant="danger">Archive key</Menu.Item>
   </Menu.Content>
 </Menu>
 ```
@@ -3174,7 +3304,7 @@ function Catalogue() {
 
 ## NumberInput
 
-Exact numbers: right-aligned tabular digits, a unit, steppers on hover, a decimal string value.
+Exact numbers: end-aligned tabular digits, a unit, quiet steppers, a decimal string value.
 
 `import { NumberInput } from "@logicplanes/kaeso-ui";`
 
@@ -3184,11 +3314,14 @@ Exact numbers: right-aligned tabular digits, a unit, steppers on hover, a decima
 |---|---|
 | Up | Increases by the step |
 | Down | Decreases by the step |
+| Tab | Moves past the field; the steppers are not tab stops, since the arrows do the same |
 
 ### Accessibility
 
 - The value is a decimal string, so money never passes through a float.
 - Thousands separators appear on blur and are removed while editing.
+- The input is a spin button: screen readers hear its value with the unit, its limits, and that the arrow keys change it.
+- A stepper turns off at the minimum or maximum.
 
 ### Examples
 
@@ -3220,10 +3353,21 @@ Six cells for a TOTP code over one accessible input: paste fills, Backspace move
 
 `import { OTPInput } from "@logicplanes/kaeso-ui";`
 
+### Keyboard
+
+| Key | Action |
+|---|---|
+| 0–9 | Types a digit into the focused cell and moves to the next |
+| Backspace | Clears the focused digit |
+| ← → | Moves between cells |
+| Home, End | Moves to the first cell, or the next empty one |
+
 ### Accessibility
 
 - One real input with autocomplete="one-time-code", so the browser can offer the code.
 - Cells are decorative; the input carries the label.
+- A pasted code fills every cell even when it is shown with spaces or dashes, such as 418 207.
+- Clicking a cell puts the caret there, so one wrong digit can be fixed without retyping the code.
 
 ### Examples
 
@@ -3384,7 +3528,7 @@ A request's parameters: system instructions, temperature, top P, max output toke
 
 ### Accessibility
 
-- Every control has a visible label that names it; the popover holds a form and traps the focus until it closes.
+- Every control has a visible label that names it; the popover holds a form, keeps the focus inside until it closes and has a Close button; Escape closes it too.
 
 ### Examples
 
@@ -3444,6 +3588,8 @@ A floating panel next to its trigger; HoverCard previews on hover, never as the
 ### Accessibility
 
 - Popovers with a form trap focus (trapFocus); others do not.
+- The title names the popover's dialog; without a title, give the content an aria-label.
+- A popover and a hover card are never wider than the screen.
 
 ### Examples
 
@@ -3475,9 +3621,9 @@ A floating panel next to its trigger; HoverCard previews on hover, never as the
 ```tsx
 <HoverCard>
   <HoverCard.Trigger>
-    <a href="#" className="mono text-small text-fg underline decoration-line-strong underline-offset-3">
+    <Link href="#models/claude-sonnet-4-5" className="mono text-small">
       claude-sonnet-4-5
-    </a>
+    </Link>
   </HoverCard.Trigger>
   <HoverCard.Content>
     <div className="flex flex-col gap-12">
@@ -3496,13 +3642,14 @@ A floating panel next to its trigger; HoverCard previews on hover, never as the
 
 ## PromptSuggestions
 
-Example prompts before a thread starts: up to three quiet lines that take a fill on hover and go once a prompt is sent.
+Example prompts before a thread starts: up to three quiet rows that take a fill on hover and go once a prompt is sent.
 
 `import { PromptSuggestions } from "@logicplanes/kaeso-ui/playground";`
 
 ### Accessibility
 
 - A list named “Example prompts”; each suggestion is a button that reads its prompt.
+- Choosing one puts it in the composer and moves the focus there.
 
 ### Examples
 
@@ -3511,10 +3658,19 @@ Example prompts before a thread starts: up to three quiet lines that take a fill
 ```tsx
 function Basic() {
   const [draft, setDraft] = useState("");
+  const composer = useRef<HTMLTextAreaElement | null>(null);
   return (
     <div className="flex w-full max-w-640 flex-col gap-12">
-      {draft === "" && <PromptSuggestions suggestions={suggestions} onSelect={setDraft} />}
-      <Composer value={draft} onValueChange={setDraft} aria-label="Message all models" placeholder="Message 3 models" />
+      {draft === "" && (
+        <PromptSuggestions
+          suggestions={suggestions}
+          onSelect={(p) => {
+            setDraft(p);
+            composer.current?.focus();
+          }}
+        />
+      )}
+      <Composer ref={composer} value={draft} onValueChange={setDraft} aria-label="Message all models" placeholder="Message 3 models" />
     </div>
   );
 }
@@ -3745,7 +3901,7 @@ A response's numbers on one line: time to first token, total time, tokens in and
 
 ## ResponseView
 
-A model's response as it arrives: Markdown with a quiet caret, reasoning in a Thinking disclosure, and calm stopped, cut-off and failed states.
+A model's response as it arrives: a quiet caret until the first token, Markdown as it streams, reasoning in a Thinking disclosure, and calm stopped, cut-off and failed states.
 
 `import { ResponseView, UserMessage, Thread } from "@logicplanes/kaeso-ui/playground";`
 
@@ -3760,6 +3916,7 @@ A model's response as it arrives: Markdown with a quiet caret, reasoning in a Th
 - Each response is an article named by aria-label (“GPT-5 response” in a comparison) and is aria-busy while it streams, so its words aren't read out one by one.
 - Thinking is a disclosure button; closed, its row shows the latest line of the summary, hidden from screen readers, which read the summary when opened.
 - A failure is an alert in place of the response: “No response”, then the error.
+- When a response finishes, stops or is cut off, a status message says so once, by name: “GPT-5 response finished”.
 
 ### Examples
 
@@ -3989,13 +4146,14 @@ Requests from keys to models to providers; hover a node to follow its path.
 
 ## ScrollArea
 
-A scroll container with thin scrollbars that appear on hover.
+A scroll container with thin scrollbars that appear on hover, fading at every edge with more to scroll to.
 
 `import { ScrollArea } from "@logicplanes/kaeso-ui";`
 
 ### Accessibility
 
 - Give a focusable scroll region an aria-label so keyboard users know what they scroll.
+- The focus ring is drawn above the fade, so all four sides show while the content scrolls.
 
 ### Examples
 
@@ -4029,6 +4187,7 @@ Search with a leading icon, a clear circle when filled, and a shortcut hint wher
 
 - The clear button is named “Clear search”.
 - type=search lets assistive technology announce it as a search field.
+- A shortcut hint hides while the field has focus, where it no longer applies; its room stays, so nothing moves.
 
 ### Examples
 
@@ -4036,7 +4195,7 @@ Search with a leading icon, a clear circle when filled, and a shortcut hint wher
 
 ```tsx
 <div className="w-240">
-  <SearchInput aria-label="Search logs" placeholder="Search logs" />
+  <SearchInput aria-label="Search logs" placeholder="gpt-5, req_01…" shortcut={["mod", "k"]} />
 </div>
 ```
 
@@ -4044,21 +4203,22 @@ Search with a leading icon, a clear circle when filled, and a shortcut hint wher
 
 ```tsx
 <div className="w-240">
-  <SearchInput size="md" aria-label="Search settings" placeholder="Search…" />
+  <SearchInput size="md" aria-label="Search settings" placeholder="Rate limit, budget" />
 </div>
 ```
 
 ## SecretReveal
 
-The one-time secret: calm, centered, certain. Copy it, store it, see how to use it.
+The one-time key: calm, centered, certain. Copy it, store it, see how to use it.
 
 `import { SecretReveal, EnvironmentSnippet } from "@logicplanes/kaeso-ui";`
 
 ### Accessibility
 
-- The secret is a read-only text box; a click selects all of it.
-- “Copy key” becomes “Copied” without changing size.
-- The warning is text, not only color.
+- The key is a read-only text box named “Key for …”; a click selects all of it.
+- “Copy key” becomes “Key copied” without changing size.
+- The warning comes before the button, so it is read before the key is copied; it is text, not only color.
+- The snippets start with a .env line and read the key from the environment, so no code example hard-codes it.
 
 ### Examples
 
@@ -4279,8 +4439,9 @@ Secrets masked by default, an eye to reveal, mono when revealed, never autocompl
 
 ### Accessibility
 
-- The reveal circle is named Show or Hide.
-- Passwords show “Caps Lock is on.” in the field's description.
+- The reveal circle is named “Show key” or “Hide key” (“Show password” for passwords).
+- With Caps Lock on, a password field shows “Caps Lock” beside the reveal circle and announces it once; the field's own description stays.
+- A revealed key is set in mono at the same size as every other id.
 
 ### Examples
 
@@ -4346,7 +4507,7 @@ Settings rows in a rounded group, title and description left, the control right.
 #### Preferences
 
 ```tsx
-<div className="w-720">
+<div className="w-560">
   <SettingsSection title="General">
     <SettingsGroup>
       <SettingsRow
@@ -4408,7 +4569,7 @@ Settings rows in a rounded group, title and description left, the control right.
 #### Navigation rows
 
 ```tsx
-<div className="w-720">
+<div className="w-560">
   <SettingsGroup>
     <SettingsRow icon={icons.members} title="Members" description="Who can use this organization." value="5 members" href="#" />
     <SettingsRow icon={icons.providerKey} title="Provider keys" description="Credentials the gateway uses upstream." value="2" href="#" />
@@ -4461,6 +4622,7 @@ A panel from the edge that keeps the list behind it readable: the request inspec
 
 - A dialog; the title names it, the subtitle carries the id.
 - Apps make it URL-addressable so links can open it.
+- A sheet that isn't modal stays open when the page behind it is pressed, so the next row can fill it.
 
 ### Examples
 
@@ -4902,10 +5064,15 @@ A reference table of five or more columns puts 8px between them, so it fits the
 
 ## TableOfContents
 
-“On this page”: the heading in view in text color with a 2px ink bar.
+“On this page”: the heading in view in text color with a 2px ink bar on the rail.
 
 `import { TableOfContents } from "@logicplanes/kaeso-ui";`
 
+### Accessibility
+
+- A navigation landmark named by its title; the heading in view has aria-current=location.
+- Links are 32px tall, 44px with a coarse pointer; the rail and the bar sit on the start side, so they move to the right in right-to-left pages.
+
 ### Examples
 
 #### Basic
@@ -4924,12 +5091,14 @@ Underline tabs for detail pages and pill tabs for page headers.
 
 | Key | Action |
 |---|---|
-| Left Right | Moves between tabs |
-| Home End | First and last tab |
+| Left Right | Moves focus between tabs |
+| Home End | Moves focus to the first or last tab |
+| Enter Space | Opens the focused tab |
 
 ### Accessibility
 
-- role=tablist with tabs and panels wired by Base UI.
+- role=tablist with tabs and panels wired by Base UI; arrows move focus and Enter or Space opens the tab, so a slow panel never loads on the way past.
+- Focus rings sit inside the pill, so a scrolling tab list never cuts them; in forced colours the selected tab keeps a Highlight outline and the indicator a solid line.
 
 ### Examples
 
@@ -5018,7 +5187,7 @@ function Toggle() {
 
 ## TagInput
 
-Removable tags in a field: Enter, comma and paste split them; Backspace removes the last.
+Removable tags in a field: Enter, comma and paste split them; Backspace selects the last, a second press removes it.
 
 `import { TagInput } from "@logicplanes/kaeso-ui";`
 
@@ -5028,11 +5197,15 @@ Removable tags in a field: Enter, comma and paste split them; Backspace removes
 |---|---|
 | Enter | Adds the typed tag |
 | , | Adds the typed tag |
-| Backspace | Removes the last tag when the field is empty |
+| Backspace | Selects the last tag from the start of the field; a second press removes it |
+| ← → | Moves the selection between tags from the start of the field |
+| Delete | Removes the selected tag |
+| Escape | Lets go of the selected tag |
 
 ### Accessibility
 
-- Each tag's remove circle is named “Remove …”.
+- Each tag's remove circle is named “Remove …”; after it, focus goes back to the field.
+- Selecting and removing a tag is announced through a polite live region, so nothing goes silently.
 - Invalid tags stay, marked with the danger ring; each says what is wrong in its tooltip, and the first problem shows under the field.
 
 ### Examples
@@ -5055,7 +5228,7 @@ Text in the type scale: one scale, used the same way everywhere.
 
 - Text renders a span by default; pass as="p" for paragraphs.
 - Truncated text gets a tooltip with the full string and becomes focusable so keyboard users can read it.
-- Tertiary never carries meaning alone (3.23:1 on white).
+- Tertiary measures at least 4.5:1 on every surface, and still never carries meaning alone.
 
 ### Examples
 
@@ -5368,8 +5541,9 @@ An ink capsule at the bottom center: brief, calm, at most three.
 ### Accessibility
 
 - role=status; errors are alerts.
-- Five seconds, paused on hover and focus; swipe to dismiss.
-- Undo lives in the toast, so reversible actions need no confirmation.
+- Five seconds, paused on hover and focus; swipe, Escape or the close button dismisses.
+- An error, or a toast with Undo, stays until it is dismissed, so nobody has to race it.
+- F6 moves the focus to the toasts.
 
 ### Examples
 
@@ -5378,16 +5552,16 @@ An ink capsule at the bottom center: brief, calm, at most three.
 ```tsx
 <>
   <Inline gap={8}>
-    <Button onClick={() => toast("Key copied")}>Neutral</Button>
-    <Button onClick={() => toast.success("Provider saved")}>Success</Button>
-    <Button onClick={() => toast.error("Couldn't reach the provider.", { description: "Check the provider key, then try again." })}>Error</Button>
-    <Button onClick={() => toast("Key disabled", { action: { label: "Undo", onClick: () => toast("Key enabled") } })}>With undo</Button>
+    <Button onClick={() => toast("Key copied")}>Copy key</Button>
+    <Button onClick={() => toast.success("Provider saved")}>Save provider</Button>
+    <Button onClick={() => toast.error("Couldn't reach the provider.", { description: "Check the provider key, then try again." })}>Test provider</Button>
+    <Button onClick={() => toast("Key disabled", { action: { label: "Undo", onClick: () => toast("Key enabled") } })}>Disable key</Button>
     <Button
       onClick={() =>
         void toast.promise(new Promise((r) => setTimeout(r, 1600)), { loading: "Syncing models…", success: "Models synced", error: "Couldn't sync models" })
       }
     >
-      Promise
+      Sync models
     </Button>
   </Inline>
 </>
@@ -5403,7 +5577,12 @@ Filters, search and display options on one 48px row, with arrow-key focus across
 
 | Key | Action |
 |---|---|
-| Left Right | Moves between controls |
+| Tab | Enters the toolbar on the control used last, and leaves it |
+| Left Right | Moves between controls, wrapping at the ends |
+
+### Accessibility
+
+- One tab stop: arrows move inside, skipping the parts of a filter chip that aren't controls; a filled search keeps the arrows for its caret.
 
 ### Examples
 
@@ -5421,7 +5600,7 @@ function Logs() {
           Add filter
         </Button>
         <Toolbar.Spacer />
-        <div className="w-240">
+        <div className="order-last basis-full sm:order-none sm:basis-auto sm:w-240">
           <SearchInput aria-label="Search logs" placeholder="Search logs" />
         </div>
         <DisplayOptions {...display} />
@@ -5449,6 +5628,8 @@ A short label on hover and focus: a pill, with a shortcut when there is one.
 - Opens after 500ms, instantly when moving between tooltipped siblings.
 - Never the only place for essential information.
 - Disabled controls show a tooltip only with a disabledReason.
+- role=tooltip. When it says more than the control's name, it is also the control's accessible description.
+- A single-line tooltip too long for the screen wraps into the box of several lines.
 
 ### Examples
 
@@ -5486,8 +5667,8 @@ Token kinds in their fixed colors, and limits with their scope, window, kind and
 
 ### Accessibility
 
-- Token kinds always map to the same series: input 1, cache read 6, cache write 2, output 3, reasoning 5.
-- Limits say hard or soft in words.
+- Token kinds always map to the same series: input blue, cache read a soft blue edged in blue, cache write amber, output emerald, reasoning violet.
+- Limits say hard or soft in words, and say so when they are over.
 
 ### Examples