@logicplanes/kaeso-ui 0.4.4 → 0.4.6

package/ai/component-registry.md

@@ -1,29 +1,29 @@
 # @logicplanes/kaeso-ui component registry
 
-Version 0.4.4. Generated from the component types, their descriptions and variants; do not edit.
+Version 0.4.6. Generated from the component types, their descriptions and variants; do not edit.
 
 ## agent-avatar
 
 `import { AgentAttribution, AgentAvatar } from "@logicplanes/kaeso-ui/agent-avatar";`
 
-- **size** (agent_attribution): `20` — 20px person, 10px agent badge; `24` (default) — 24px person, 12px agent badge (default); `28` — 28px person, 14px agent badge; `32` — 32px person, 16px agent badge; `40` — 40px person, 20px agent badge
+- **size** (agent_attribution): `20` — 20px person, 8px agent badge; `24` (default) — 24px person, 10px agent badge (default); `28` — 28px person, 12px agent badge; `32` — 32px person, 12px agent badge; `40` — 40px person, 16px agent badge
 - **size** (agent_avatar): `20` — 20px; `24` (default) — 24px: rows and lists (default); `28` — 28px; `32` — 32px; `40` — 40px: an agent's own page, menus
 
 ### AgentAttribution
 
-A person's avatar with the agent that acted for them as a small badge on its corner, for audit rows and activity; it reads as one picture named after both. The badge stays inside the avatar's square, so a table cell never cuts it off.
+A person's avatar with the agent that acted for them as a small round ink badge on its corner, for audit rows and activity; it reads as one picture named after both, and a tooltip says the same to the pointer. The badge is about 40% of the avatar and a 2px gap cut out of the face separates it on any surface; it stays inside the avatar's square, so a table cell never cuts it off.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `agent` * | `{ name: string; model: string; }` |  | The agent that acted, with its name and model family id from the API; the family is named in the accessible name only. |
 | `name` * | `string` |  | The name of the person the agent acted for; it starts the accessible name, such as `Ada Okafor via Release helper (Claude)`. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `size` | `24 \| 20 \| 28 \| 32 \| 40` | `24` | The diameter of the person's avatar in pixels; the agent badge is half of it. |
+| `size` | `24 \| 20 \| 28 \| 32 \| 40` | `24` | The diameter of the person's avatar in pixels; the agent badge is about 40% of it (8 to 16px). |
 | `src` | `string` |  | The person's picture; without one, or when it fails to load, their initials show. |
 
 ### AgentAvatar
 
-An agent acting for a person: one bot face on an ink square, the same for every agent; write its model family beside it with useModelName where it matters.
+An agent acting for a person: one bot face on a `fill-3` square, the same for every agent (people are round, agents square); write its model family beside it with useModelName where it matters.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -63,7 +63,7 @@ The sidebar as a floating panel from the left edge (a peek): the mobile navigati
 | `children` * | `ReactNode` |  | The navigation, usually the app's `Sidebar`. |
 | `onOpenChange` * | `(open: boolean) => void` |  | Called when the navigation opens or closes. |
 | `open` * | `boolean` |  | Whether the navigation is shown on phones. |
-| `peek` | `boolean` | `false` | Slides the sheet in a little, to hint that it can be opened. |
+| `peek` | `boolean` | `false` | Shows the sheet as a preview that doesn't trap focus or dim the page, and closes when the pointer leaves it. |
 | `returnFocus` | `RefObject<HTMLElement \| null>` |  | The element that gets focus back when the sheet closes. |
 
 ## avatar
@@ -75,7 +75,7 @@ The sidebar as a floating panel from the left edge (a peek): the mobile navigati
 
 ### Avatar
 
-The first letters of the first and last word; `max` 1 keeps only the first.
+The first letters of the first and last word; `max` 1 keeps only the first. A photo gets a hairline so a light picture keeps its edge.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -88,25 +88,25 @@ The first letters of the first and last word; `max` 1 keeps only the first.
 
 ### AvatarGroup
 
-Overlapping avatars with a 2px panel ring and a "+3".
+Overlapping avatars, each separated from the one under it by a 2px gap cut out of that avatar, so the gap shows whatever surface the group sits on (a hovered row, a card); then a "+3".
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `people` * | `{ name: string; src?: string \| undefined; }[]` |  | The people to show, in order. |
 | `children` | `ReactNode` |  | Content after the avatars, such as a button to invite more people. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `max` | `number` | `4` | Show at most this many; the rest become "+3". |
+| `max` | `number` | `4` | Show at most this many; the rest become "+3", which names them in a tooltip. |
 | `size` | `24 \| 20 \| 28 \| 32 \| 40` | `24` | The diameter of each avatar in pixels. |
 
 ## badge
 
 `import { Badge } from "@logicplanes/kaeso-ui/badge";`
 
-- **tone** (badge): `neutral` (default) — Neutral (default); `success` — Success; `warning` — Warning; `danger` — Danger; `info` — Information; `outline` — A ring only; `ink` — Inverted, for the one thing that must stand out
+- **tone** (badge): `neutral` (default) — Neutral (default): fill-2, or the control fill on a hovered or selected row; `success` — Success; `warning` — Warning; `danger` — Danger; `info` — Information; `outline` — A ring only; `ink` — Inverted: at most one on a view, for the one thing that must stand out
 
 ### Badge
 
-A small pill label: 22px, 12/500. Words carry meaning; color supports them.
+A small read-only pill label: 22px, 12/500, smaller than a Tag (24 or 28px) so a mark never looks like a control. Words carry meaning; color supports them. A label longer than its room ends in an ellipsis and shows in full in a tooltip. `ink` is for at most one badge on a view.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -118,20 +118,20 @@ A small pill label: 22px, 12/500. Words carry meaning; color supports them.
 `import { Banner } from "@logicplanes/kaeso-ui/banner";`
 
 - **tone** (banner): `neutral` (default) — A neutral notice (default); `info` — Information; `success` — Something worked; `warning` — Attention needed soon; `danger` — Something failed or will fail
-- **layout** (banner): `inline` (default) — Inside content: radius 14 (default); `full` — Across the top of the panel for global notices
+- **layout** (banner): `inline` (default) — Inside content: radius 14, its icon 12px in, at least 56px tall with or without actions (default); `full` — Across the top of the panel for global notices: its icon on the 24px gutter
 
 ### Banner
 
-An inline notice: a tint, an icon, an optional title, the text, actions at the end. The banner is its own size container. From 480px inside its padding (the `banner` container size, `@banner:`) the actions sit on the right, centered on the title and text together, and the icon stays on the first line. Narrower (a phone) the actions go under the text, starting where the text starts: their 24px inset is the icon's 16px column and its 8px gap, which in the row is the gap before them.
+An inline notice: a tint, an icon (none for a neutral notice, so it never looks like information), an optional title, the text, actions at the end. Inline, the icon sits 12px in and the banner is at least 56px tall, so banners with and without actions stack evenly; full width, the icon sits on the 24px gutter and the text 24px further in. The banner is its own size container. From 480px inside its padding (the `banner` container size, `@banner:`) the actions sit on the right, centered on the title and text together, and the icon stays on the first line. Narrower (a phone) the actions go under the text, starting where the text starts: their 24px inset is the icon's 16px column and its 8px gap, which in the row is the gap before them.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `actions` | `ReactNode` |  | sm pills: on the right, centered on the title and text; under the text when the banner is narrow. |
 | `children` | `ReactNode` |  | The message, with actions if it needs them. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `icon` | `IconSvgElement` |  | An icon in place of the tone's own. |
+| `icon` | `IconSvgElement` |  | An icon in place of the tone's own; a neutral banner has none unless you pass one. |
 | `layout` | `"inline" \| "full"` | `inline` | Inside the content (`inline`) or across the full width of the panel (`full`). |
-| `onDismiss` | `(() => void)` |  | Only informational banners can be dismissed. |
+| `onDismiss` | `(() => void)` |  | Shows a dismiss button on `neutral` and `info` banners. Success, warning and danger banners stay until their cause changes, so they ignore it and warn in development. |
 | `title` | `ReactNode` |  | The banner's heading. |
 | `tone` | `"neutral" \| "success" \| "warning" \| "danger" \| "info"` | `neutral` | The kind of message, from neutral information to a danger warning. |
 
@@ -150,10 +150,10 @@ The button. Every one is a pill; icon-only buttons are circles (see `IconButton`
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `icon` * | `IconSvgElement` |  | The only content of an icon button; give it an `aria-label`. |
-| `children` | `ReactNode` |  | The button's label: a verb first, in sentence case. |
+| `children` | `ReactNode` |  | The button's label: a verb first, in sentence case. A label wider than its container is cut with an ellipsis and shown whole in a tooltip. |
 | `count` | `number` |  | A count after the label. |
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
-| `disabledReason` | `string` |  | Why the button is disabled, shown as a tooltip. The button stays focusable so people can read it. |
+| `disabledReason` | `string` |  | Why the button is disabled, shown as a tooltip and read out as the button's description. The button stays focusable so people can reach it. |
 | `fullWidth` | `boolean` |  | Fills the width of its container. |
 | `href` | `string` |  | Renders a link that looks like the button. |
 | `leadingIcon` | `IconSvgElement` |  | An icon before the text. |
@@ -162,7 +162,7 @@ The button. Every one is a pill; icon-only buttons are circles (see `IconButton`
 | `reserveLabels` | `ReactNode[]` |  | Every label this button can show ("Copy key", "Copied"). The button keeps the width of the widest, so a state change never resizes it. |
 | `shape` | `"pill" \| "circle"` |  | Icon-only buttons are circles and need an accessible name. |
 | `shortcut` | `string[] \| string[][]` |  | A shortcut hint after the label (lg and xl, and in menus). |
-| `size` | `"md" \| "xs" \| "sm" \| "lg" \| "xl"` |  | The height, from `xs` (24px) to `xl` (44px). |
+| `size` | `"md" \| "xs" \| "sm" \| "lg" \| "xl"` |  | The height, from `xs` (24px) to `xl` (48px). |
 | `target` | `string` |  | Where the link opens, as on an `a` element. |
 | `trailingIcon` | `IconSvgElement` |  | An icon after the text. |
 | `variant` | `"danger" \| "link" \| "secondary" \| "primary" \| "ghost" \| "quiet" \| "soft" \| "danger-secondary"` |  | `primary` for the one main action of a view, `secondary` for others, `ghost` and `quiet` for toolbars and rows, `danger` for destructive actions. A ghost or quiet button at the end of a settings row's control pulls its padding past the row's edge, so its label ends where an outlined button's ring does. |
@@ -176,7 +176,7 @@ The button. Every one is a pill; icon-only buttons are circles (see `IconButton`
 
 ### ButtonGroup
 
-Related actions side by side: connected pills, or spaced with `attached={false}`.
+Related actions side by side: connected pills, or spaced with `attached={false}`. An item with `pressed` is a toggle; pass `false` while it is off, and the selected item turns ink.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -224,31 +224,31 @@ The calendar: 36px day circles, today ringed, ranges as a continuous strip with
 
 ### BarChart
 
-Bars for comparing values across categories: grouped, stacked, or horizontal for rankings. The category under the pointer, or reached with the arrow keys, shows its tooltip.
+Bars for comparing values across categories: grouped, stacked, or horizontal for rankings. The category under the pointer, or reached with the arrow keys, shows its tooltip; the legend pills show and hide series.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The chart's accessible name ("Requests by model"). |
 | `categories` * | `string[]` |  | The names along the category axis, one per bar group, in order. They also head the tooltip and the data table. |
-| `series` * | `BarSeries[]` |  | The bars' series, each with an `id`, a `label`, one value per category and an optional `color`. Colors otherwise come from the series order by `id`. |
+| `series` * | `BarSeries[]` |  | The bars' series, each with an `id`, a `label`, one value per category and an optional `color`. Colors otherwise come from the series order by `id`; one series takes series 1. Negative values grow down from the zero line. With two or more, the legend shows and hides them. |
 | `axisLabels` | `string[]` |  | Shorter names under the bars, one per category ("3 Aug" for "Week of 3 Aug"); the tooltip, the table and screen readers keep the categories. Name the year where one begins ("Aug", "Dec", "2026", "Feb"), and pass `dates`: where the labels don't all fit, the axis keeps every nth, and keeps that one before the newest (`axisLabelIndexes`). |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `dates` | `readonly AxisDate[]` |  | The day each category begins, one per category: a `Date`, or an ISO day ("2026-01-05"). Where the axis thins its labels, it keeps the ones where a year begins (the month after December, the first week in January), read from these, so every language keeps the same labels. |
-| `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the data. Pass it when the period has no data. |
+| `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the data, over the baseline and the category axis. By default it shows when there is no value at all; zeros are data. |
 | `emptyText` | `ReactNode` |  | What the empty state says. Defaults to "No data for this period" in the provider's language. |
-| `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails. |
-| `formatValue` | `((v: number) => string)` | `(v) => formatNumber(v)` | Formats values on the axis and in the tooltip. |
+| `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, hides its legend and table toggle, and says so quietly, with Try again when there is `onRetry` and otherwise a hint to reload the page. Errors are toasts, so the value isn't shown; pass `true` and toast the message where the request fails. |
+| `formatValue` | `((v: number) => string)` |  | Formats values in the tooltip, the table and beside horizontal bars. Without it, values are written in full and the axis in short form (1.2M); the axis takes the room its widest label needs, and long category names in a ranking end in an ellipsis with the full name on hover. |
 | `height` | `number` | `240` | The plot's height in px (240 by default). |
 | `highlight` | `number` |  | Highlight a category as the pointer does, with its tooltip: a linked view, or the states pages. |
 | `layout` | `"horizontal" \| "grouped" \| "stacked"` | `grouped` | `grouped` puts each category's bars side by side (default), `stacked` stacks them, and `horizontal` draws bars across for rankings. |
-| `loading` | `boolean` |  | The data is loading: the chart keeps its height and shows a quiet loading bar. |
+| `loading` | `boolean` |  | The data is loading: the chart keeps its height and is marked busy; data already on screen dims and breathes, and with none yet the plot is a skeleton. |
 | `onRetry` | `(() => void)` |  | Called when Try again is pressed after `error`; without it, the button doesn't show. |
-| `partial` | `{ first?: boolean; last?: boolean; ongoing?: boolean \| undefined; } \| undefined` |  | Marks the `first` or `last` category as covering only part of its span: its bars are drawn lighter and its tooltip says "partial". `ongoing` marks the last one as still counting, such as today, and says "so far". |
+| `partial` | `{ first?: boolean; last?: boolean; ongoing?: boolean \| undefined; } \| undefined` |  | Marks the `first` or `last` category as covering only part of its span: its bars are drawn faint with a dashed edge, like a partial line, and its tooltip says "partial". `ongoing` marks the last one as still counting, such as today, and says "so far". |
 | `shares` | `boolean` | `true` | Shows each series' share of the category's total in the tooltip (on by default). Turn it off when one series is part of another, such as errors within requests. |
 
 ### ChartFrame
 
-The frame every chart draws in: a hidden data table for assistive technology, a "View as table" toggle, and the empty, loading and error states. The toggle sits at the right end of the last line of the legend; when the frame is narrower than 480px (the `chart-legend` container size, a phone), it moves to its own line under the legend, so it never reads as one of the series. Use it to build a chart of your own that behaves like the others.
+The frame every chart draws in: a hidden data table for assistive technology, a "View as table" toggle that shows the table at the chart's height, scrolling inside, and the empty, loading and error states. The toggle sits at the right end of the last line of the legend; when the frame is narrower than 480px (the `chart-legend` container size, a phone), it moves to its own line under the legend, so it never reads as one of the series. Use it to build a chart of your own that behaves like the others.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -290,44 +290,44 @@ A ring of shares with the total in the center and a legend beside it, or under i
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The chart's accessible name ("Requests by model"). |
-| `slices` * | `Slice[]` |  | The parts of the whole, each with an `id`, a `label`, a `value` and an optional `color`. Slices under 2% are grouped as Other when there are two or more. |
+| `slices` * | `Slice[]` |  | The parts of the whole, each with an `id`, a `label`, a `value` and an optional `color`. Slices under 2% are grouped as Other when there are two or more, and past the eighth slice the rest are grouped too, so no two slices share a color. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the data. By default it shows when every value is 0. |
+| `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the ring and legend. By default it shows when every value is 0, since a ring of nothing has no shares. |
 | `emptyText` | `ReactNode` |  | What the empty state says. Defaults to "No data for this period" in the provider's language. |
-| `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails. |
+| `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, hides its legend and table toggle, and says so quietly, with Try again when there is `onRetry` and otherwise a hint to reload the page. Errors are toasts, so the value isn't shown; pass `true` and toast the message where the request fails. |
 | `formatValue` | `((v: number) => string)` | `(v) => formatNumber(v)` | Formats the total in the center and the values in the legend. Defaults to `formatNumber`. |
-| `loading` | `boolean` |  | The data is loading: the chart keeps its height and shows a quiet loading bar. |
+| `loading` | `boolean` |  | The data is loading: the chart keeps its height and is marked busy; data already on screen dims and breathes, and with none yet the plot is a skeleton. |
 | `onRetry` | `(() => void)` |  | Called when Try again is pressed after `error`; without it, the button doesn't show. |
 | `size` | `"md" \| "sm" \| "lg"` | `md` | The ring's diameter: `sm` 140px, `md` 160px (default) or `lg` 180px. |
-| `total` | `ReactNode` |  | Replaces the total in the center, which is otherwise the sum of the slices written with `formatValue`. |
+| `total` | `ReactNode` |  | Replaces the total in the center, which is otherwise the sum of the slices written with `formatValue`. A long total steps down a size to fit the ring. |
 | `totalLabel` | `ReactNode` |  | The word under the total. Defaults to "Total" in the provider's language. |
 
 ### Gauge
 
-A semicircle meter for one share of a limit, such as "budget used". It turns to warning at the first threshold and to danger at 100%.
+A semicircle meter for one share of a limit, such as "budget used". At the first threshold it says "Near the limit" and turns to warning; at 100% it says "Over the limit" and turns to danger.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The chart's accessible name ("Requests by model"). |
-| `value` * | `number` |  | The share used, from 0 to 1. Values above 1 fill the arc and turn it to danger. |
+| `value` * | `number` |  | The share used, from 0 to 1. Values above 1 fill the arc and turn it to danger; a missing value (NaN) shows a dash and no arc. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `label` | `ReactNode` |  | A caption under the value ("of $500.00 budget"). |
+| `label` | `ReactNode` |  | A caption under the arc ("of $500.00 budget"); it wraps when long. |
 | `thresholds` | `number[]` | `[0.8]` | Fractions marked as ticks on the arc (`[0.8]` by default). From the lowest one, the arc turns to warning. |
-| `valueLabel` | `ReactNode` |  | Replaces the value in the center, which is otherwise the percentage. |
+| `valueLabel` | `ReactNode` |  | Replaces the value in the center, which is otherwise the percentage. Pass a string so screen readers hear it with the unit. |
 
 ### Heatmap
 
-A grid of cells shaded on a five-step ramp, for one value across two dimensions such as hour by weekday.
+A grid of cells shaded on a five-step ramp, for one value across two dimensions such as hour by weekday. One tab stop: the arrow keys move between cells and show each value, the table toggle lists them all, and a grid wider than its column scrolls with a fade at the edge.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The chart's accessible name ("Requests by model"). |
 | `columns` * | `string[]` |  | The column labels, left to right (hours, or weeks). |
-| `rows` * | `string[]` |  | The row labels, top to bottom (weekdays). |
+| `rows` * | `string[]` |  | The row labels, top to bottom (weekdays). With no rows or columns the chart shows its empty state. |
 | `values` * | `number[][]` |  | The values by row, then column: `values[row][column]`. The darkest step is the largest value. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `columnLabelEvery` | `number` | `3` | Labels every nth column, starting with the first (3 by default), so dense columns stay readable. |
-| `formatValue` | `((v: number) => string)` | `(v) => formatNumber(v)` | Formats a cell's value for its tooltip and screen readers. Defaults to `formatNumber`. |
+| `formatValue` | `((v: number) => string)` | `(v) => formatNumber(v)` | Formats a cell's value for its tooltip, the table and screen readers. Defaults to `formatNumber`. |
 
 ### Legend
 
@@ -348,21 +348,21 @@ The same component as `Donut` under another name, with the same props.
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The chart's accessible name ("Requests by model"). |
-| `slices` * | `Slice[]` |  | The parts of the whole, each with an `id`, a `label`, a `value` and an optional `color`. Slices under 2% are grouped as Other when there are two or more. |
+| `slices` * | `Slice[]` |  | The parts of the whole, each with an `id`, a `label`, a `value` and an optional `color`. Slices under 2% are grouped as Other when there are two or more, and past the eighth slice the rest are grouped too, so no two slices share a color. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the data. By default it shows when every value is 0. |
+| `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the ring and legend. By default it shows when every value is 0, since a ring of nothing has no shares. |
 | `emptyText` | `ReactNode` |  | What the empty state says. Defaults to "No data for this period" in the provider's language. |
-| `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails. |
+| `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, hides its legend and table toggle, and says so quietly, with Try again when there is `onRetry` and otherwise a hint to reload the page. Errors are toasts, so the value isn't shown; pass `true` and toast the message where the request fails. |
 | `formatValue` | `((v: number) => string)` | `(v) => formatNumber(v)` | Formats the total in the center and the values in the legend. Defaults to `formatNumber`. |
-| `loading` | `boolean` |  | The data is loading: the chart keeps its height and shows a quiet loading bar. |
+| `loading` | `boolean` |  | The data is loading: the chart keeps its height and is marked busy; data already on screen dims and breathes, and with none yet the plot is a skeleton. |
 | `onRetry` | `(() => void)` |  | Called when Try again is pressed after `error`; without it, the button doesn't show. |
 | `size` | `"md" \| "sm" \| "lg"` | `md` | The ring's diameter: `sm` 140px, `md` 160px (default) or `lg` 180px. |
-| `total` | `ReactNode` |  | Replaces the total in the center, which is otherwise the sum of the slices written with `formatValue`. |
+| `total` | `ReactNode` |  | Replaces the total in the center, which is otherwise the sum of the slices written with `formatValue`. A long total steps down a size to fit the ring. |
 | `totalLabel` | `ReactNode` |  | The word under the total. Defaults to "Total" in the provider's language. |
 
 ### Sankey
 
-A flow diagram, such as requests from keys to models to providers, with ribbons as wide as each flow. Hovering a node highlights its paths.
+A flow diagram, such as requests from keys to models to providers, with ribbons as wide as each flow. Hovering a node, or reaching it with the arrow keys, highlights its paths. Each column keeps room for its labels; when narrow, the values go first, then long names end in an ellipsis.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -370,12 +370,12 @@ A flow diagram, such as requests from keys to models to providers, with ribbons
 | `links` * | `SankeyLinkIn[]` |  | The flows, each with a `source` and a `target` node `id` and a `value`. |
 | `nodes` * | `SankeyNodeIn[]` |  | The nodes, each with an `id` and a `label`. Columns follow from the links. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the data. Pass it when the period has no data. |
+| `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the data. By default it shows when no link carries a value. |
 | `emptyText` | `ReactNode` |  | What the empty state says. Defaults to "No data for this period" in the provider's language. |
-| `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails. |
+| `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, hides its legend and table toggle, and says so quietly, with Try again when there is `onRetry` and otherwise a hint to reload the page. Errors are toasts, so the value isn't shown; pass `true` and toast the message where the request fails. |
 | `formatValue` | `((v: number) => string)` | `(v) => formatNumber(v)` | Formats the values beside the nodes and in the data table. Defaults to `formatNumber`. |
 | `height` | `number` | `320` | The diagram's height in px (320 by default). |
-| `loading` | `boolean` |  | The data is loading: the chart keeps its height and shows a quiet loading bar. |
+| `loading` | `boolean` |  | The data is loading: the chart keeps its height and is marked busy; data already on screen dims and breathes, and with none yet the plot is a skeleton. |
 | `onRetry` | `(() => void)` |  | Called when Try again is pressed after `error`; without it, the button doesn't show. |
 
 ### ShareBar
@@ -387,7 +387,7 @@ One pill split into segments by share, with a legend under it. Use it for a comp
 | `aria-label` * | `string` |  | The chart's accessible name ("Requests by model"). |
 | `slices` * | `Slice[]` |  | The parts of the whole, each with an `id`, a `label`, a `value` and an optional `color`. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `formatValue` | `((v: number) => string)` | `(v) => formatNumber(v)` | Formats a segment's value in its tooltip. Defaults to `formatNumber`. |
+| `formatValue` | `((v: number) => string)` | `(v) => formatNumber(v)` | Formats each segment's value for screen readers, beside its share. Defaults to `formatNumber`. |
 | `legend` | `boolean` | `true` | Shows the legend with each share under the bar (on by default). |
 
 ### Sparkline
@@ -397,7 +397,7 @@ A small line chart of one series, inline beside a value, with its last point mar
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The chart's accessible name ("Requests by model"). |
-| `values` * | `number[]` |  | The values in order, oldest first. |
+| `values` * | `number[]` |  | The values in order, oldest first. One value is a dot at the newest end; none is a quiet flat line. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `color` | `string` | `var(--k-viz-1)` | The line's color (`var(--k-viz-1)` by default). Pass `seriesColor(id)` to match the series elsewhere. |
 | `fluid` | `boolean` |  | Fills the container's width at 32px high, without the last point's dot, as in a stat tile. Otherwise it is 80×24. |
@@ -409,7 +409,7 @@ The mark that keys a series: a short stroke for lines, a small rounded square fo
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `color` * | `string` |  | The series color. |
-| `off` | `boolean` |  | Draws the swatch as off, for a hidden series. |
+| `off` | `boolean` |  | Draws the swatch as an outline in the series color, for a hidden series. |
 | `shape` | `"square" \| "line"` | `square` | `square` for filled marks (default) or `line` for lines. |
 
 ### TimeseriesChart
@@ -421,17 +421,17 @@ A line or area chart of values over time, such as usage, with a crosshair and to
 | `aria-label` * | `string` |  | The chart's accessible name ("Requests by model"). |
 | `series` * | `TimeSeries[]` |  | The series, each with an `id`, a `label`, `points` of `t` (a time) and `v`, and an optional `color`. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the data. By default it shows when every value is 0. |
+| `empty` | `boolean` |  | Shows the empty state (`emptyText`) in place of the data, over the baseline and the time axis. By default it shows when there are no points; zeros are data and draw a flat line on the baseline. |
 | `emptyText` | `ReactNode` |  | What the empty state says. Defaults to "No data for this period" in the provider's language. |
-| `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, says so quietly and offers Try again. Errors are toasts, so the value isn't shown; toast the message where the request fails. |
+| `error` | `ReactNode` |  | The data failed to load: the chart keeps its height, hides its legend and table toggle, and says so quietly, with Try again when there is `onRetry` and otherwise a hint to reload the page. Errors are toasts, so the value isn't shown; pass `true` and toast the message where the request fails. |
 | `formatTick` | `((t: Date) => string)` |  | Names the times under the axis ("3 Aug", "2026"). Defaults to calendar ticks in `timeZone`; pass it with `tickAt="points"` for buckets. |
 | `formatTime` | `((t: Date) => string)` |  | Names a point's time in the tooltip, the table and for screen readers, where a point stands for more than its instant: "Week of 3 Aug", "Aug 2026". |
-| `formatValue` | `((v: number) => string)` | `(v) => formatNumber(v)` | Formats values on the axis and in the tooltip. |
+| `formatValue` | `((v: number) => string)` |  | Formats values in the tooltip, the table and on the axis. Without it, values are written in full and the axis in short form (1.2M), and the axis takes the room its widest label needs. |
 | `height` | `number` | `240` | The plot's height in px (240 by default). |
 | `hideLegend` | `boolean` |  | Hide the legend (one series). |
 | `highlight` | `number` |  | Highlight a point in time as the pointer does, with the crosshair and tooltip: a linked view, or the states pages. |
 | `kind` | `"stacked" \| "line" \| "area"` | `line` | `line` draws lines (default), `area` adds a light fill under each line, and `stacked` stacks the areas. |
-| `loading` | `boolean` |  | The data is loading: the chart keeps its height and shows a quiet loading bar. |
+| `loading` | `boolean` |  | The data is loading: the chart keeps its height and is marked busy; data already on screen dims and breathes, and with none yet the plot is a skeleton. |
 | `onRetry` | `(() => void)` |  | Called when Try again is pressed after `error`; without it, the button doesn't show. |
 | `partial` | `{ first?: boolean; last?: boolean; ongoing?: boolean \| undefined; } \| undefined` |  | Marks the `first` or `last` point as covering only part of its span: the line to it is dashed and its tooltip says "partial". `ongoing` marks the last one as still counting, such as today, and says "so far". |
 | `shares` | `boolean` | `true` | Shows each series' share of the point's total in the tooltip (on by default). Turn it off when one series is part of another, such as errors within requests. |
@@ -462,7 +462,7 @@ A checkbox with its label and description; with a `parent`, it checks or uncheck
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
 | `indeterminate` | `boolean` |  | Shows a dash: some, but not all, of a group is checked. |
-| `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
+| `invalid` | `boolean` |  | Shows it as invalid; inside a `Field` with `error`, it is invalid on its own and reads the message with it. |
 | `label` | `ReactNode` |  | The label; the whole row becomes the target. |
 | `name` | `string` |  | The field name the value is sent under in a form. |
 | `onCheckedChange` | `((checked: boolean) => void)` |  | Called with the new state when it is checked or unchecked. |
@@ -487,7 +487,7 @@ The box alone: 18px, raised and ringed; ink when checked with a check that draws
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
 | `indeterminate` | `boolean` |  | Shows a dash: some, but not all, of a group is checked. |
-| `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
+| `invalid` | `boolean` |  | Shows it as invalid; inside a `Field` with `error`, it is invalid on its own and reads the message with it. |
 | `label` | `ReactNode` |  | The label; the whole row becomes the target. |
 | `name` | `string` |  | The field name the value is sent under in a form. |
 | `onCheckedChange` | `((checked: boolean) => void)` |  | Called with the new state when it is checked or unchecked. |
@@ -516,7 +516,7 @@ Checkboxes that share one value, a list of the checked values.
 
 `import { Code } from "@logicplanes/kaeso-ui/code";`
 
-- **shape** (code): `auto` (default) — Pill for a single word, radius 6 for anything longer (default); `pill` — Always a pill; `rounded` — Always radius 6
+- **shape** (code): `auto` (default) — Radius 6, like every inline code in running text (default); `pill` — Always a pill; `rounded` — Always radius 6
 - **flow** (code): `box` (default) — One box: it moves to the next line whole and wraps inside itself (default); `text` — Breaks with the sentence around it, each line keeping its fill and corners; for long code in running text; `cell` — Breaks with the text around it and ends square at a break, so no padding hangs past a narrow table cell; for long code in a table
 
 ### Code
@@ -525,8 +525,8 @@ Inline code: Geist Mono 13 on fill-1.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `flow` | `"cell" \| "text" \| "box"` | `box` | `text` for long code in running text, so it breaks with the sentence instead of jumping to its own line as one box; `cell` for the same in a table cell. |
-| `shape` | `"auto" \| "pill" \| "rounded"` | `auto` | A pill on one line, rounded corners when it wraps, or `auto` to choose by length. |
+| `flow` | `"cell" \| "text" \| "box"` | `box` | `text` for long code in running text, so it breaks with the sentence instead of jumping to its own line as one box; `cell` for the same in a table cell. The default box wraps inside itself when it is wider than its line. |
+| `shape` | `"auto" \| "pill" \| "rounded"` | `auto` | `auto` (default) and `rounded` keep radius 6, so code in a sentence never mixes shapes; pass `pill` for one word standing alone, such as a model name in a table cell. |
 
 ## code-block
 
@@ -538,7 +538,7 @@ Inline code: Geist Mono 13 on fill-1.
 
 ### CodeBlock
 
-Highlighted code on a well: Kaeso's monochrome theme, copy on hover, tabs, line numbers, collapse. Long lines scroll sideways inside 16px of padding at both ends, and the code fades out at an edge with more to scroll to.
+Highlighted code on a well: Kaeso's monochrome theme, copy in the header with a title or tabs and on hover without, tabs, line numbers, collapse with a fade at the cut. Long lines scroll sideways inside 16px of padding at both ends, and the code fades out at an edge with more to scroll to.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -595,7 +595,7 @@ Two versions of a text side by side in one column: removed lines on red, added l
 
 ### JsonView
 
-A folding JSON tree: copy any path, highlight a search. For request and response bodies.
+A folding JSON tree: copy any path, highlight a search. For request and response bodies. It is one tab stop: the arrow keys move between rows and open and close them, and ⌘C or Ctrl C copies the row's path.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -609,11 +609,11 @@ A folding JSON tree: copy any path, highlight a search. For request and response
 
 `import { Accordion, Collapsible } from "@logicplanes/kaeso-ui/collapsible";`
 
-- **state** (collapsible): `closed` (default) — Closed: the chevron points to the row (default); `open` — Open: the chevron turns down and the content shows
+- **state** (collapsible): `closed` (default) — Closed: a pill row with the title 12px in and a chevron at its end pointing right (default); `open` — Open: the chevron turns down in 200ms and the content shows under the title
 
 ### Accordion
 
-Collapsible rows separated by hairlines.
+Collapsible rows separated by hairlines, each the same pill row as Collapsible.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -624,7 +624,7 @@ Collapsible rows separated by hairlines.
 
 ### Collapsible
 
-A disclosure row: a chevron that rotates in 180ms, a measured height animation.
+A disclosure row: a pill with the title 12px in and a chevron at its end that turns in 200ms, the content on the title's line, a measured height animation.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -683,13 +683,13 @@ A pill input with a filtered list: matched characters highlighted, async, chips
 | `defaultValue` | `string \| string[] \| null` |  | The value on first render, when the component keeps its own value. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
-| `emptyText` | `ReactNode` |  | What the empty list says: "No models match". Defaults to "No results" in the provider's language. |
+| `emptyText` | `ReactNode` |  | What the empty list says: "No models match". Defaults to "No matches for" and the typed text, in the provider's language. |
 | `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
 | `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
 | `label` | `ReactNode` |  | The visible label. |
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
-| `loading` | `boolean` |  | Shows a quiet progress line at the top of the list (async results). |
+| `loading` | `boolean` |  | Shows a quiet progress line at the top of the list (async results) once loading takes 300ms; with reduced motion, only the words. |
 | `multiple` | `boolean` |  | Allows choosing more than one option; `value` is then a list. |
 | `name` | `string` |  | The field name the value is sent under in a form. |
 | `onCreate` | `((label: string) => void)` |  | Offers "Add “…”" when nothing matches exactly. |
@@ -726,18 +726,18 @@ A search field over a long list that stays fast with thousands of rows: fuzzy ma
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The list's accessible name. |
-| `groups` * | `CommandListGroup[]` |  | The rows, in groups; a group with a label gets a sticky caption with its mark and count, and a loading group keeps its caption while it has no rows yet. |
+| `groups` * | `CommandListGroup[]` |  | The rows, in groups; a group with a label gets a sticky caption with its mark and count, and a loading group keeps its caption, without a count, over a Loading… row while it has no rows yet. |
 | `autoFocus` | `boolean` |  | Focuses the search field when it appears, as in a popover or a dialog step. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `counts` | `boolean` | `true` | Shows each group's count beside its caption; false leaves them out, for a site whose house style has no result counters. |
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `defaultQuery` | `string` |  | The search text on first render. |
-| `emptyText` | `ReactNode` |  | What the list says when nothing matches: "No models match". |
+| `emptyText` | `ReactNode` |  | What the list says when nothing matches: "No models match". Defaults to "No results for “claude”", naming the query, in the provider's language. |
 | `escapeClears` | `boolean` | `true` | Escape first clears the search, and only an empty search lets Escape close what holds the list (true by default). |
 | `footer` | `ReactNode` |  | A line under the list, such as key hints. |
 | `height` | `"fill" \| "popover" \| "inline"` |  | How tall it is: bounded in a popover, a fixed raised frame in a dialog, or filling a phone sheet. Inside `PickerPopover` it follows the popover. |
 | `inputProps` | `{ [attribute: `data-${string}`]: string; }` |  | Data attributes for the search field, such as a marker other code looks for. |
-| `loading` | `boolean` |  | Shows a quiet progress line at the top while more rows load. |
+| `loading` | `boolean` |  | Shows a quiet progress line at the top while more rows load; with reduced motion it breathes instead of moving. |
 | `match` | `((item: CommandListItem, query: string) => number)` | `(item: CommandListItem, query: string) => commandMatch(query, [item.label, ...(item.keywords ?? [])])` | Scores a row against the search: above 0 keeps it, and higher scores come first. Fuzzy matching on the label and keywords by default. |
 | `multiple` | `boolean` |  | Rows toggle with a checkbox instead of choosing one. |
 | `onEscape` | `(() => void)` |  | Called on Escape when the search field is already empty. |
@@ -788,14 +788,14 @@ The pill that opens a picker and shows its value, in the same looks and sizes as
 
 ### CommandPalette
 
-⌘K: search every page and action; nested pages; async groups with a quiet progress line.
+⌘K: search every page and action; nested pages with a chip that goes back; async groups with a quiet progress line. Escape closes; on a nested page it clears the search, then goes back a page. ⌘K does nothing while another dialog is open.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `groups` * | `CommandGroup[]` |  | The commands, in groups with a heading each. |
 | `counts` | `boolean` |  | Shows each group's count beside its caption; false leaves them out, for a site whose house style has no result counters. |
 | `defaultQuery` | `string` |  | Start with this query (documentation). |
-| `emptyText` | `ReactNode` |  | Defaults to "No results" in the provider's language. |
+| `emptyText` | `ReactNode` |  | Defaults to "No results for “claude”" (naming the query) in the provider's language. |
 | `hotkey` | `boolean` |  | Open with ⌘K / Ctrl+K anywhere (default true). |
 | `inline` | `boolean` |  | Render without a portal, for documentation and state matrices. |
 | `keyHints` | `boolean` |  | A footer with the keys (↑ ↓ to navigate, ↵ to open, esc to close). Off by default: key hints only where asked for. |
@@ -854,23 +854,24 @@ Inline mono text that copies itself on click. On hover and keyboard focus a copy
 
 `import { DataTable } from "@logicplanes/kaeso-ui/data-table";`
 
-- **density** (data_table): `compact` — 36px rows; `default` (default) — 40px rows (default); `comfortable` — 48px rows
+- **density** (data_table): `compact` — 36px rows; 44px with a coarse pointer; `default` (default) — 40px rows (default); 44px with a coarse pointer; `comfortable` — 48px rows
 
 ### DataTable
 
-A table for many rows: sorting, selection, loading and empty states, more rows on demand, and virtual scrolling for long lists.
+A table for many rows: sorting, selection, loading and empty states, more rows on demand, and virtual scrolling for long lists. One tab stop: the arrows move between rows and header buttons, Right reaches a row's controls, Shift with Left or Right resizes a column from its header, and a header's context menu widens, narrows or resets it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The table's accessible name. |
 | `columns` * | `ColumnDef<T, any>[]` |  | The columns, as TanStack Table column definitions. |
 | `data` * | `T[]` |  | The rows. |
-| `activeRowId` | `string` |  | The id of a row to show as active (open in a sheet). |
+| `activeRowId` | `string` |  | The id of the row whose detail is open, in a sheet beside the table: it keeps the selected fill and is marked aria-current. |
 | `canSelectRow` | `((row: T) => boolean)` |  | Whether a row can be selected; a row that can't keeps a disabled checkbox, and select all skips it. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `data-force-row` | `string` |  | Force a state on the first row for state matrices: hover, pressed, focus. |
 | `density` | `"default" \| "compact" \| "comfortable"` |  | How much room each row gets. |
-| `empty` | `ReactNode` |  | What to show when there are no rows, usually an `Empty`. |
-| `error` | `ReactNode` |  | The rows failed to load: the table says so where its rows would be and offers Try again (`onRetry`). Errors are toasts, so the value isn't shown; toast the message where the request fails. |
+| `empty` | `ReactNode` |  | What to show when there are no rows: an `Empty` with the page's own sentence, such as "No requests yet" or, behind filters, "No requests match". Without it the table says "No rows". |
+| `error` | `ReactNode` |  | The rows failed to load: the table says so where its rows would be and offers Try again (`onRetry`), or, without it, says to reload the page. Errors are toasts, so the value isn't shown; toast the message where the request fails. |
 | `freshRowIds` | `ReadonlySet<string>` |  | Rows that just arrived (a live list): each shows a fill that fades out over a second. |
 | `getRowId` | `((row: T) => string)` |  | Returns a row's stable id, for selection and keys. |
 | `hasMore` | `boolean` |  | Whether more rows can be loaded. |
@@ -885,7 +886,7 @@ A table for many rows: sorting, selection, loading and empty states, more rows o
 | `onSortingChange` | `((sorting: SortingState) => void)` |  | Called with the new sort order. |
 | `ref` | `Ref<HTMLDivElement>` |  | A ref to the outer element. |
 | `rowMenu` | `((row: T) => ReactNode)` |  | Items for a row's context menu (right-click). |
-| `selectable` | `boolean` |  | Adds a checkbox to every row. |
+| `selectable` | `boolean` |  | Adds a checkbox to every row, named after the row's first text column; Space, Shift with the arrows and ⌘A select from the keyboard. |
 | `selection` | `RowSelectionState` |  | The selected rows, when you control them. |
 | `sorting` | `SortingState` |  | The sort order, when you control it. |
 | `stickyFirstColumn` | `boolean` |  | Keeps the first column in view while scrolling sideways. |
@@ -918,7 +919,7 @@ A pill showing the date; a popover with the calendar and a typed ISO field.
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
 | `onValueChange` | `((value: Date \| null) => void)` |  | Called with the chosen day, or `null` when it is cleared. |
 | `optional` | `boolean` |  | Adds “Optional” to the label, for forms where most fields are required. |
-| `placeholder` | `string` |  | Shown without a date. Defaults to "Pick a date" ("Pick a range" for a range) in the provider's language. |
+| `placeholder` | `string` |  | Shown without a date. Defaults to "Choose a date" ("Choose a date range" for a range) in the provider's language. |
 | `required` | `boolean` |  | Marks it as required in a form. |
 | `size` | `"md" \| "sm" \| "lg"` |  | The height of the field. |
 | `value` | `Date \| null` |  | The chosen day, when you control it. |
@@ -944,7 +945,7 @@ A pill showing the range ("Oct 1 – Oct 12") or its preset ("Last 30 days"); pr
 | `layout` | `"horizontal" \| "vertical"` |  | The label above the control (`vertical`) or beside it (`horizontal`). |
 | `onValueChange` | `((value: DateRange \| null, details: { preset: string \| null; }) => void)` |  | A preset's range, or the days chosen with Apply; `preset` is the preset's id ("Last 7 days"), `null` for chosen days. |
 | `optional` | `boolean` |  | Adds “Optional” to the label, for forms where most fields are required. |
-| `placeholder` | `string` |  | Shown without a date. Defaults to "Pick a date" ("Pick a range" for a range) in the provider's language. |
+| `placeholder` | `string` |  | Shown without a date. Defaults to "Choose a date" ("Choose a date range" for a range) in the provider's language. |
 | `preset` | `string \| null` |  | The preset the value is, by its id (or label): the trigger shows its name ("Last 6 months", "All time") and the popover marks it. Set it from where the period lives (the address), with `null` for chosen days. Without it, the trigger names a preset picked here while the range is still that preset's. |
 | `presets` | `DateRangePreset[]` |  | Defaults to the last 24 hours, 7 and 30 days, this month and last month, named in the provider's language. |
 | `required` | `boolean` |  | Marks it as required in a form. |
@@ -979,34 +980,34 @@ Hours and minutes as two segments in one pill; arrows step, typing advances.
 
 `import { DeleteResource } from "@logicplanes/kaeso-ui/blocks/delete-resource";`
 
-- **confirm** (delete_resource): `typed` (default) — The person types the resource's name (default); `simple` — A confirm button only, for reversible archives
+- **confirm** (delete_resource): `typed` (default) — The person types the resource's name, for one that holds a lot: a project, an organization (default); `simple` — A confirm button only, for a resource that holds little: a key, an alias
 
 ### DeleteResource
 
-Confirms deleting a resource: names the object and the consequence, asks for its name typed, and ends with a danger button.
+Confirms deleting a resource for good: the title names it, the body says the consequence, the person types its name, and a danger button names the action. A reversible action needs no confirmation: act at once and offer Undo in a toast.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `consequence` * | `ReactNode` |  | What happens: "Applications using it will stop authenticating with the gateway." |
-| `kind` * | `string` |  | "project", "key", "organization" |
-| `name` * | `string` |  | The resource's name; typed to confirm. |
+| `kind` * | `string` |  | The kind of resource in the provider's language, as it reads after the verb on the button: "project", "key"; in German "Projekt". |
+| `name` * | `string` |  | The resource's name: the title names it, and the person types it to confirm. |
 | `onConfirm` * | `() => void \| Promise<void>` |  | Called when the action is confirmed; return a promise to keep the dialog busy until it ends. |
 | `confirm` | `"typed" \| "simple"` | `typed` | Asks to type the resource's name (`typed`) or just to confirm (`simple`). |
 | `inline` | `boolean` |  | Renders in place, without a trigger, for review pages and tests. |
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
 | `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | The element that opens it. |
-| `verb` | `string` |  | "Delete", "Archive". Defaults to "Delete" in the provider's language. |
+| `verb` | `string` |  | The action in the provider's language, in the form it takes on the button and in the title: "Archive" ("Archive project", "Archive “Checkout”?"); in German the infinitive, "archivieren" ("Projekt archivieren"). Defaults to "Delete" in the provider's language. |
 
 ## dialog
 
 `import { AlertDialog, Dialog, DialogScope, LayerDialog, StepDialog } from "@logicplanes/kaeso-ui/dialog";`
 
-- **tone** (alert_dialog): `danger` (default) — Destructive (default); `warning` — Risky but reversible; `info` — Neutral confirmation
+- **tone** (alert_dialog): `danger` (default) — Destructive: a danger confirm, with the focus on Cancel (default); `warning` — Risky but reversible: a primary confirm, with the focus on Cancel; `info` — A neutral confirmation: a primary confirm, with the focus on it
 - **size** (dialog): `sm` — 440px: confirmations, short forms; `md` (default) — 560px: forms (default); `lg` — 720px: two columns, previews
 - **anchor** (dialog): `center` (default) — Centered on the screen (default); `top` — A fixed top edge, for content that changes height, such as the steps of a StepDialog
 - **size** (layer_dialog): `sm` — 440px: confirmations, short forms; `md` (default) — 560px: forms (default); `lg` — 720px: two columns, previews
-- **anchor** (layer_dialog): `center` (default) — Centered on the screen (default); `top` — A fixed top edge, for content that changes height, such as the steps of a StepDialog
+- **anchor** (layer_dialog): `center` — Centered on the screen (default); `top` (default) — A fixed top edge, for content that changes height, such as the steps of a StepDialog
 - **size** (step_dialog): `sm` (default) — 440px: most tasks in a few steps (default); `md` — 560px: steps with longer forms; `lg` — 720px: steps with two columns or previews
 - **tone** (step_dialog): `default` (default) — The last step's button is primary (default); `danger` — The last step's button is a danger button, for a task that ends in deletion
 
@@ -1019,7 +1020,7 @@ Confirms an irreversible action: names it, explains the consequence, optionally
 | `confirmLabel` * | `string` |  | The confirm label, the verb and object: "Delete key". |
 | `description` * | `ReactNode` |  | The practical consequence. |
 | `onConfirm` * | `() => void \| Promise<unknown>` |  | Called when the action is confirmed; return a promise to keep the dialog busy until it ends. It closes when the promise resolves and stays open for another try when it rejects, so toast the error there. |
-| `title` * | `ReactNode` |  | Names the action: "Delete this key?" |
+| `title` * | `ReactNode` |  | Names the action and the object: "Delete “checkout-web”?" |
 | `cancelLabel` | `string` |  | Defaults to "Cancel" in the provider's language. |
 | `confirmText` | `string` |  | Typed confirmation: the person types this to enable the confirm. |
 | `defaultOpen` | `boolean` |  | Whether it starts open, when the component keeps its own state. |
@@ -1027,7 +1028,7 @@ Confirms an irreversible action: names it, explains the consequence, optionally
 | `loading` | `boolean` |  | Shows a spinner on the confirm while work runs (also automatic for a promise); until it ends, the dialog stays open. |
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
-| `tone` | `"warning" \| "danger" \| "info"` |  | How serious the confirmation is; `danger` for actions that can't be undone. |
+| `tone` | `"warning" \| "danger" \| "info"` |  | How serious the confirmation is: `danger` for an action that can't be undone (a danger confirm, the focus on Cancel), `warning` for a risky one that can (a primary confirm, the focus still on Cancel), `info` for a neutral one (the focus on the confirm). |
 | `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | The element that opens it. |
 
 ### Dialog
@@ -1036,8 +1037,8 @@ A modal dialog: 440 / 560 / 720, radius 20, title, description, body, actions. E
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `title` * | `ReactNode` |  | The dialog's heading, also its accessible name. |
-| `anchor` | `"center" \| "top"` |  | Where it sits: centered, or with a fixed top edge for content that changes height, so the title never moves. |
+| `title` * | `ReactNode` |  | The dialog's heading, also its accessible name; a long one, or an id, wraps. |
+| `anchor` | `"center" \| "top"` | `top` | Where it sits: centered, or with a fixed top edge for content that changes height, so the title never moves. |
 | `busy` | `boolean` |  | Keeps the dialog open while work it started is underway: Escape, a press outside, the close circle, Dialog.Close, Enter and ⌘Enter do nothing, so a request is never abandoned or sent twice. |
 | `children` | `ReactNode` |  | The dialog's content and actions. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
@@ -1051,7 +1052,7 @@ A modal dialog: 440 / 560 / 720, radius 20, title, description, body, actions. E
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
 | `onSubmit` | `(() => void)` |  | Enter in a single-line field and ⌘/Ctrl+Enter anywhere call this (usually the primary action); Enter in a text area, a search field, a combobox or a picker, and the Enter that confirms an input method's text, keep their own meaning. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
-| `persistent` | `boolean` |  | A press outside doesn't close it, for forms that would lose what was typed; Escape and the close circle still do. Every StepDialog is persistent. |
+| `persistent` | `boolean` |  | A press outside doesn't close it or move the focus, for forms that would lose what was typed; Escape and the close circle still close it. Every StepDialog is persistent. |
 | `size` | `"md" \| "sm" \| "lg"` |  | The dialog's width. |
 | `toolbar` | `ReactNode` |  | Controls that stay under the title while the body scrolls, such as a search over the list below; a hairline shows once the body is scrolled. |
 | `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | The trigger, a single element. |
@@ -1067,12 +1068,12 @@ Opens a dialog's flow fresh every time: its children mount anew when `open` turn
 
 ### LayerDialog
 
-A stacked dialog: a second layer slides over the first (add model → review values); back returns. The layers below stay as they were. Moving to a layer puts the focus on its first field, or its primary action; Back returns it to the control that opened the layer, scrolled where it was. Enter in a single-line field and ⌘/Ctrl+Enter call onSubmit on every layer.
+A stacked dialog: a second layer slides over the first (add model → review values); Back returns, and Escape closes the dialog from any layer. The layers below stay as they were. The close circle sits in a bar above the title, with Back at its start from the second layer, so the title keeps its place on every layer. Moving to a layer puts the focus on its first field, or its primary action; Back returns it to the control that opened the layer, scrolled where it was. Enter in a single-line field and ⌘/Ctrl+Enter call onSubmit on every layer.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `layers` * | `DialogLayer[]` |  | The layers, each with its title, content and footer, and optionally a toolbar and a footer start; one shows at a time, and the ones below it stay mounted and hidden. |
-| `anchor` | `"center" \| "top"` |  | Where it sits: centered, or with a fixed top edge for layers of different heights. |
+| `anchor` | `"center" \| "top"` | `top` | Where it sits: with a fixed top edge (default), so the title stays put on layers of different heights, or centered. |
 | `busy` | `boolean` |  | Keeps the dialog open while work it started is underway: Escape, a press outside, the close circle, Dialog.Close, Enter and ⌘Enter do nothing, so a request is never abandoned or sent twice. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `defaultOpen` | `boolean` |  | Whether it starts open, when the component keeps its own state. |
@@ -1094,7 +1095,7 @@ A form split into steps, one question at a time, like sign-in: the step's title
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `onSubmit` * | `() => void` |  | Called when the last step is submitted. |
-| `steps` * | `DialogStep[]` |  | The steps, each with its title, content and whether it can be continued; `onContinue` checks a step before the next opens, such as asking a server, and `continueLabel` names that check: "Detect settings". |
+| `steps` * | `DialogStep[]` |  | The steps, each with its title, content and whether it can be continued: with `blockedReason`, Continue waits, and Enter shows and announces the reason under the step; `onContinue` checks a step before the next opens, such as asking a server, and `continueLabel` names that check: "Detect settings". |
 | `submitLabel` * | `string` |  | The last step's button: "Create key". |
 | `title` * | `ReactNode` |  | What the whole dialog does: "Create key". |
 | `defaultStep` | `number` | `0` | Start on this step (state matrices). |
@@ -1134,16 +1135,16 @@ Display options: view, grouping and ordering, toggles, properties.
 
 ### Empty
 
-An empty state: a title, one sentence, one or two actions. No icon, no illustration.
+An empty state: a title, one sentence, one action. No icon, no illustration. The `lg` title is a heading (h2) for a page that is empty; `md` and `compact` titles are text, so an empty table, list or section adds no heading to the page's outline.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `title` * | `ReactNode` |  | What is missing, in a few words. |
-| `actions` | `ReactNode` |  | One primary and at most one secondary action. |
+| `actions` | `ReactNode` |  | The one action that makes something appear; put a link to read more in the description. |
 | `children` | `ReactNode` |  | One sentence that says what to do, and an action. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `description` | `ReactNode` |  | One sentence: what is absent and the next step. |
-| `size` | `"md" \| "lg" \| "compact"` | `lg` | How much room it takes: a whole page (`lg`), a section (`md`) or a row (`compact`). |
+| `size` | `"md" \| "lg" \| "compact"` | `lg` | How much room it takes: a whole page (`lg`, with a heading), a section (`md`) or a row (`compact`). |
 
 ## field
 
@@ -1158,7 +1159,7 @@ The aria wiring a control needs, whether it sits in a <Field> or wraps itself in
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `description` | `ReactNode` |  | One sentence of help under the label. |
-| `error` | `ReactNode` |  | The error message, shown under the control in the danger color: it marks the field invalid and is read out with the description. |
+| `error` | `ReactNode` |  | The error message, shown under the control in the danger color: it marks the field invalid and is read out with the description. After a failed submit, move focus to the first invalid field so its error is heard. |
 | `id` | `string` |  | The id of the control inside, so the label points to it. |
 | `invalid` | `boolean` |  | Marks the field invalid without a message. |
 | `label` | `ReactNode` |  | The field's label. |
@@ -1166,12 +1167,12 @@ The aria wiring a control needs, whether it sits in a <Field> or wraps itself in
 
 ### Fieldset
 
-A group of fields under one legend.
+A group of fields under one legend, which names the group for screen readers.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `legend` * | `ReactNode` |  | The heading of the group of fields. |
-| `description` | `ReactNode` |  | One sentence of help under the heading. |
+| `legend` * | `ReactNode` |  | The heading of the group of fields, read out as the group's name. |
+| `description` | `ReactNode` |  | One sentence of help under the heading; it also describes the group. |
 
 ## figure
 
@@ -1186,7 +1187,7 @@ A diagram or image set apart from the text: centred on a well, with a caption, s
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` * | `ReactNode` |  | What the figure shows, usually a ThemeImage. |
-| `label` * | `string` |  | The name of the figure's scrolling region, read by screen readers. |
+| `label` * | `string` |  | The name of the figure's scrolling region, read by screen readers; give each figure on a page its own. |
 | `caption` | `ReactNode` |  | A few words under the figure that say what it shows, such as a diagram's title. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `focus` | `number` | `0.5` | Where a figure wider than its column starts, as a share of its width: 0.5, the middle, by default. |
@@ -1231,7 +1232,7 @@ A filter as one pill: "Status is 2xx ×", each part opening a menu.
 
 ### FilterRow
 
-The row between a page's header and its list or table: pill tabs at the start, filters at the end. It grows with its content instead of keeping a toolbar's 48px, and on a narrow screen the filters wrap under the tabs, at the start. The tabs keep their own arrow keys; Left and Right move across the filters only, which form their own toolbar.
+The row between a page's header and its list or table: pill tabs at the start, filters at the end. It grows with its content instead of keeping a toolbar's 48px, and on a narrow screen the filters wrap under the tabs, at the start. The tabs keep their own arrow keys; Left and Right move from filter to filter, which form their own toolbar.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1244,17 +1245,17 @@ The row between a page's header and its list or table: pill tabs at the start, f
 
 `import { Flow } from "@logicplanes/kaeso-ui/flow";`
 
-- **node** (flow): `pill` (default) — A raised pill (default); `box` — A rounded-14 box with a description line
+- **node** (flow): `pill` (default) — A pill with a hairline (default); `box` — A rounded-14 box with a description line
 
 ### Flow
 
-A node-and-connector diagram: the route "app → Kaeso → provider / model".
+A node-and-connector diagram: the route "app → Kaeso → provider / model". A diagram wider than its column scrolls sideways with a fade at the edge and takes focus.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `columns` * | `FlowNode[][]` |  | Columns of nodes, left to right. |
 | `edges` * | `[string, string][]` |  | Connections as [from, to] node ids. |
-| `animated` | `boolean` | `false` | Dots that travel along the connectors. Off by default; never on loaded pages that need calm. |
+| `animated` | `boolean` | `false` | When the route changes, a dot runs once along each connector, to show where requests now go. Never on first render and never with reduced motion. |
 | `aria-label` | `string` |  | The accessible name of the diagram: what it shows, such as "Route of checkout requests". Defaults to "Flow diagram"; screen readers hear each node and each connection after it. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `node` | `"pill" \| "box"` | `pill` | The shape of each step: a pill or a box. |
@@ -1322,8 +1323,8 @@ A circle with an icon, a required name, and a tooltip that says it.
 
 - **size** (input): `sm` — 32px: toolbars and compact forms; `md` (default) — 36px: the default; `lg` — 40px; `xl` — 48px: sign-in and setup forms
 - **size** (input_group): `sm` — 32px: toolbars and compact forms; `md` (default) — 36px: the default; `lg` — 40px; `xl` — 48px: sign-in and setup forms
-- **align** (number_input): `end` (default) — Right-aligned tabular digits (default); `start` — Left-aligned
-- **size** (otp_input): `md` (default) — 48px cells (default); `sm` — 40px cells
+- **align** (number_input): `end` (default) — End-aligned tabular digits (default); `start` — Start-aligned
+- **size** (otp_input): `md` (default) — 48px cells (default); they shrink, square, when the row is narrower; `sm` — 40px cells
 - **size** (search_input): `sm` (default) — 32px: toolbars (default); `md` — 36px: a search at the top of a page or dialog; `lg` — 40px; `xl` — 48px
 - **kind** (sensitive_input): `secret` (default) — Provider keys and tokens: never autocompleted (default); `password` — Passwords: browser password managers allowed, Caps Lock hint
 - **size** (tag_input): `md` (default) — 36px at one row; grows as tags wrap (default)
@@ -1366,7 +1367,7 @@ Joins an input with buttons or text before or after it into one pill.
 
 ### NumberInput
 
-Numbers that stay exact: right-aligned tabular digits, a unit, stepper circles on hover, thousands separators on blur, and a decimal string value.
+Numbers that stay exact: end-aligned tabular digits, a unit, quiet stepper circles, thousands separators on blur, and a decimal string value.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1376,7 +1377,7 @@ Numbers that stay exact: right-aligned tabular digits, a unit, stepper circles o
 | `defaultValue` | `string` |  | The number on first render, as text. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
 | `error` | `ReactNode` |  | The error message, shown under the control in the danger color; it marks the control invalid and is read out with its description. |
-| `hideStepper` | `boolean` |  | Hide the stepper circles. |
+| `hideStepper` | `boolean` |  | Hide the stepper circles, where a value is typed rather than nudged, such as an id or a year. |
 | `integer` | `boolean` |  | Whole numbers only, such as a count of days: a numeric keypad on phones and no thousands separators in the field. |
 | `invalid` | `boolean` |  | Shows it as invalid; pair it with a message that says what to fix. |
 | `label` | `ReactNode` |  | The visible label. |
@@ -1520,13 +1521,14 @@ A model's capabilities as small icons, each named in a tooltip and read as one l
 
 ### ClientButton
 
-An agent client's mark, such as Claude, Cursor or GitHub Copilot, on a raised tile, as a button that opens how to connect it.
+An agent client's mark, such as Claude, Cursor or GitHub Copilot, in a raised circle beside the other header buttons, as a button that opens how to connect it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The client's name; also the tooltip. |
 | `client` * | `"cursor" \| "claude" \| "github-copilot"` |  | Which client's mark it shows. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `onClick` | `(() => void)` |  | Opens how to connect the client. |
 
 ### ConversationView
@@ -1543,7 +1545,7 @@ A model conversation from a request log: role captions, prose, tool calls and re
 
 ### EffectiveAccess
 
-What someone can do, at a glance: a row per group with the granted rights in words ("Every right", "None", or their names) and how many of the group's rights that is, under the roles it comes from. The detail, with a source per right, is RightsMatrix in read-only mode.
+What someone can do, at a glance: a row per group with the granted rights in words ("Every right", "None", or their names) and how many of the group's rights that is, under the roles it comes from; groups with nothing granted share one "No rights" row. A role chip with more to say has a dotted underline and says it in a tooltip. The detail, with a source per right, is RightsMatrix in read-only mode.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1566,19 +1568,19 @@ The gateway's base URL and a key placeholder to copy, with snippets per SDK.
 
 ### GrantSummary
 
-What an agent or a key may do, one short line each after a check mark, on a group surface.
+What an agent or a key may do, one short line each after a check mark, on a group surface with 20px inside, like a settings group.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The list's accessible name ("What it can do"). |
 | `items` * | `readonly ReactNode[]` |  | The lines, short and without a final period. |
-| `action` | `ReactNode` |  | A small button after the note, such as Customize. |
+| `action` | `ReactNode` |  | A small button after the note (or alone, at the end), such as Customize. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `footer` | `ReactNode` |  | A quiet note under the lines, such as how long it lasts. |
+| `footer` | `ReactNode` |  | A note under the lines in secondary text, such as how long it lasts. |
 
 ### KeyDisplay
 
-A redacted key: mono 13 with its state dot, copy of the redacted form, and its access.
+A redacted key: mono 13, a word badge for any state but active, a copy of the redacted form, and its access in an outline badge.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1591,13 +1593,13 @@ A redacted key: mono 13 with its state dot, copy of the redacted form, and its a
 
 ### LimitMeter
 
-A limit: its kind, scope and window, hard or soft, the meter with alert ticks, and when it resets.
+A limit: its kind, scope and window, hard or soft, the meter with alert ticks, and when it resets. Over the limit it says so, and what happens to requests.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `kind` * | `LimitKind` |  | What is limited: requests, tokens or spend, and over which period. |
 | `limit` * | `number` |  | The limit. |
-| `scope` * | `ReactNode` |  | "Project", "Key ci-runner", "Member Ada". |
+| `scope` * | `ReactNode` |  | "Project", "Key ci-runner", "Member Ada". A text scope also names the meter for screen readers, and shows whole on hover when it doesn't fit. |
 | `used` * | `number` |  | How much is used. |
 | `valueLabel` * | `ReactNode` |  | Formatted values: "$32.10 of $50.00". |
 | `window` * | `ReactNode` |  | "Per minute", "Per month". |
@@ -1686,7 +1688,7 @@ A bar of time to first byte against the total: 240px (default), 160px in a cell,
 
 ### RightsMatrix
 
-Rights by group, for a role, a member or a key. Edit mode: a checkbox per right and per group (mixed when some are granted), requirements kept (granting "edit" grants "view"; withdrawing "view" withdraws "edit"), each right's needs said under it, and arrow keys moving between checkboxes. Read-only mode: a mark per right and the roles that grant it. Rows keep their size whatever their state. Fits a sheet and a phone.
+Rights by group, for a role, a member or a key. Edit mode: a checkbox per right and per group (checked only when every right in it is granted, mixed when some are), requirements kept (granting "edit" grants "view"; withdrawing "view" withdraws "edit"), each right's needs said under it, and a right that can't change saying why under it. The matrix is one tab stop: the arrow keys move between checkboxes, and the right arrow reaches a right's sensitive mark. A group's name toggles the group, as a right's row toggles the right. Read-only mode: a mark per right and the roles that grant it. Rows keep their size whatever their state. Fits a sheet and a phone.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1701,7 +1703,7 @@ Rights by group, for a role, a member or a key. Edit mode: a checkbox per right
 
 ### RolePicker
 
-Choosing a role: built-in roles first, then custom ones under their own caption, each with its one-sentence description. A role the person can't give stays in the list, disabled, with the reason under it and in its tooltip, so nobody wonders where it went.
+Choosing a role: built-in roles first, then custom ones under their own caption, each with its one-sentence description. A role the person can't give stays in the list, disabled, with the reason under it, so nobody wonders where it went.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1719,11 +1721,11 @@ Choosing a role: built-in roles first, then custom ones under their own caption,
 
 ### SecretReveal
 
-The one-time secret: calm, centered, certain. The secret on a well (selected on click), a large "Copy key" that becomes "Copied" without changing size, a plain warning, and snippets that use it.
+The one-time secret: calm, centered, certain. The secret on a well (selected on click), a plain warning, a large "Copy key" that becomes "Key copied" without changing size, and a `.env` tab with the gateway's URL and the key beside SDK snippets that read the key from the environment.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `baseUrl` * | `string` |  | The gateway's address, for the code snippet that uses the key. |
+| `baseUrl` * | `string` |  | The gateway's address, for the `.env` tab and the code snippets. |
 | `secret` * | `string` |  | The full secret, shown once. |
 | `apiKey` | `string` | `$KAESO_API_KEY` | What stands in for the key: the real key right after creation, a placeholder elsewhere. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
@@ -1744,7 +1746,7 @@ An HTTP status: the code in mono, in its class color (with its phrase in a toolt
 
 ### UsageBreakdown
 
-A stacked bar of token kinds with the numbers under it, in the fixed series mapping.
+A stacked bar of token kinds with the numbers under it, in the fixed series mapping; cache read is a soft blue edged in input's blue. Each rounded count shows the exact one on hover and focus.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1784,7 +1786,7 @@ A shortcut: `⌘ K`, or a sequence like `G then L`.
 
 ### KeyValue
 
-Label and value pairs (13 secondary label, 14 value), copyable values. Side by side for sheets; label above value in columns (`grid`) where a sheet is wide enough for two or more to a row. A text value that doesn't fit ends in an ellipsis and shows whole in a tooltip.
+Label and value pairs (13 secondary label, 14 value), copyable values. Side by side for sheets; label above value in columns (`grid`) where a sheet is wide enough for two or more to a row. A value or grid label that doesn't fit ends in an ellipsis, takes focus and shows whole in a tooltip. Side by side, the label column grows to its longest label up to 240px, and longer labels wrap. Ids and keys (`mono`) are 13px, like ids everywhere in the library.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1801,7 +1803,7 @@ Label and value pairs (13 secondary label, 14 value), copyable values. Side by s
 
 ### Label
 
-The label of a form control.
+The label of a form control. Pass `data-disabled` beside a disabled control and it dims with it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1815,7 +1817,7 @@ The label of a form control.
 
 - **align** (layout): `start` — Align to the start; `center` — Center on the cross axis; `end` — Align to the end; `baseline` — Align text baselines; `stretch` (default) — Stretch
 - **justify** (layout): `start` (default) — Pack to the start; `center` — Center; `end` — Pack to the end; `between` — Space between
-- **columns** (layout): `1` — One column; `2` (default) — Two columns from 768px; `3` — Three columns from 768px; `4` — Two, then four from 1024px; `6` — Three, then six from 1024px
+- **columns** (layout): `1` — One column; `2` (default) — Two columns from 768px; `3` — Three columns from 768px; `4` — Two, then four from 1024px; `6` — Two, three from 768px, six from 1024px
 
 ### Grid
 
@@ -1826,7 +1828,7 @@ A responsive grid.
 | `align` | `"start" \| "end" \| "center" \| "baseline" \| "stretch"` | `center` | How items line up within their cells. |
 | `as` | `ElementType` |  | The element or component to render as, such as `section` or `ul`. |
 | `columns` | `2 \| 3 \| 4 \| 1 \| 6` | `2` | The number of columns. |
-| `gap` | `0 \| 2 \| 24 \| 20 \| 32 \| 40 \| 4 \| 6 \| 8 \| 12 \| 16 \| 48 \| 64` | `16` | The space between items, in pixels on the spacing scale. |
+| `gap` | `0 \| 2 \| 24 \| 8 \| 12 \| 16 \| 20 \| 32 \| 40 \| 4 \| 6 \| 48 \| 64` | `16` | The space between items, in pixels on the spacing scale. |
 
 ### Inline
 
@@ -1836,7 +1838,7 @@ A horizontal row that wraps.
 |---|---|---|---|
 | `align` | `"start" \| "end" \| "center" \| "baseline" \| "stretch"` | `center` | How items line up across the row. |
 | `as` | `ElementType` |  | The element or component to render as, such as `section` or `ul`. |
-| `gap` | `0 \| 2 \| 24 \| 20 \| 32 \| 40 \| 4 \| 6 \| 8 \| 12 \| 16 \| 48 \| 64` | `16` | The space between items, in pixels on the spacing scale. |
+| `gap` | `0 \| 2 \| 24 \| 8 \| 12 \| 16 \| 20 \| 32 \| 40 \| 4 \| 6 \| 48 \| 64` | `16` | The space between items, in pixels on the spacing scale. |
 | `justify` | `"start" \| "end" \| "center" \| "between"` |  | How items are spread along the main axis. |
 | `wrap` | `boolean` | `true` | Lets items wrap onto the next line. |
 
@@ -1848,14 +1850,14 @@ A vertical stack.
 |---|---|---|---|
 | `align` | `"start" \| "end" \| "center" \| "baseline" \| "stretch"` | `center` | How items line up across the column. |
 | `as` | `ElementType` |  | The element or component to render as, such as `section` or `ul`. |
-| `gap` | `0 \| 2 \| 24 \| 20 \| 32 \| 40 \| 4 \| 6 \| 8 \| 12 \| 16 \| 48 \| 64` | `16` | The space between items, in pixels on the spacing scale. |
+| `gap` | `0 \| 2 \| 24 \| 8 \| 12 \| 16 \| 20 \| 32 \| 40 \| 4 \| 6 \| 48 \| 64` | `16` | The space between items, in pixels on the spacing scale. |
 | `justify` | `"start" \| "end" \| "center" \| "between"` |  | How items are spread along the main axis. |
 
 ## link
 
 `import { Link } from "@logicplanes/kaeso-ui/link";`
 
-- **variant** (link): `inline` (default) — Inside prose: text color with a quiet underline that turns solid on hover; `quiet` — Navigation-style links in footers and metadata; no underline until hover; `standalone` — A link on its own line (“Team overview ›”); `heading` — A heading's link to itself: the heading's own look, with a # beside it on hover and keyboard focus; `card` — A page to read next: a filled well with the page's name and one sentence about it
+- **variant** (link): `inline` (default) — Inside prose: text color with a grey underline that turns to the text color on hover; `quiet` — Navigation-style links in footers and metadata; no underline until hover; `standalone` — A link on its own line (“Team overview ›”); `heading` — A heading's link to itself: the heading's own look, with a # beside it on hover and keyboard focus; `card` — A page to read next: a filled well with the page's name and one sentence about it
 
 ### Link
 
@@ -1872,11 +1874,11 @@ A link. Router links come from `LinkProvider`.
 
 `import { GroupHeader, List, ListRow, SelectionAction, SelectionBar } from "@logicplanes/kaeso-ui/list";`
 
-- **density** (list): `default` (default) — 44px rows (default); `compact` — 36px rows
+- **density** (list): `default` (default) — 44px rows (default); `compact` — 36px rows; 44px with a coarse pointer
 
 ### GroupHeader
 
-A quiet caption row above its group: title, count and a disclosure chevron, set in from the edges like the rows. No band: space separates the groups, and the + circle appears with hover or focus.
+A quiet caption row above its group: title, count and a disclosure chevron, set in from the edges like the rows. On the panel there is no band: 16px of space separates the groups. In a card the header is a `fill-1` band with a hairline, the card's way of separating groups. The + circle appears with hover or focus.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1885,9 +1887,9 @@ A quiet caption row above its group: title, count and a disclosure chevron, set
 | `addLabel` | `string` |  | The + circle's name. Defaults to "Add" in the provider's language. |
 | `collapsed` | `boolean` |  | Whether the group is collapsed. |
 | `count` | `number` |  | How many items the group has. |
-| `first` | `boolean` |  | The list's first row (no hairline above it in a card). |
+| `first` | `boolean` |  | The list's first row: no space above it on the panel, no hairline above it in a card. |
 | `glyph` | `ReactNode` |  | A mark before the name, such as a status dot. |
-| `indent` | `boolean` |  | In a selectable list, line the title up with the row titles after the checkbox column. |
+| `indent` | `boolean` |  | In a selectable list, line the title up with the row titles after the checkbox column; the hover fill still starts on the gutter. |
 | `index` | `number` |  | The header's position in the list, for keyboard navigation. |
 | `onAdd` | `(() => void)` |  | Shows an Add button and is called when it is pressed. |
 | `onFocus` | `(() => void)` |  | Called when the header's toggle or its add button gets focus. |
@@ -1895,25 +1897,25 @@ A quiet caption row above its group: title, count and a disclosure chevron, set
 
 ### List
 
-The console list: 44px rows on the panel, no lines, metadata on the right, keyboard-first. An ARIA grid of one-cell rows with one tab stop: arrows move between rows, Space selects, Enter opens, and the right arrow reaches a row's actions.
+The console list: 44px rows on the panel (48px in a card, 56px with a second line), no lines, metadata on the right, keyboard-first. An ARIA grid of one-cell rows with one tab stop: arrows move between rows, Space selects, Enter opens, the right arrow reaches a row's actions and Escape comes back. A row's text can be selected and copied; a click that selects text doesn't open the row.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `aria-label` * | `string` |  | The list's accessible name. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `data-force-row` | `string` |  | Force a state on the first row for state matrices: hover, focus, selected. |
+| `data-force-row` | `string` |  | Force a state on the first row for state matrices: hover, pressed, focus. |
 | `density` | `"default" \| "compact"` | `default` | How much room each row gets. |
 | `empty` | `ReactNode` |  | Shown when there are no rows and the list isn't loading: usually an `Empty` (`size="md"` in a settings column, where it sits inside the list's card; `size="compact"` on an edge-to-edge page). |
 | `groups` | `ListGroup[]` |  | …rows under group headers. |
 | `idWidth` | `48 \| 64 \| 80 \| 96 \| 120` |  | A fixed width for the id column when ids differ in length, so titles align. By default the id takes its own width. |
 | `items` | `ListItemData[]` |  | Rows without groups, or… |
-| `loading` | `boolean` |  | Loading rows shaped like items, while the rows aren't known yet. |
+| `loading` | `boolean` |  | Loading rows shaped like items, under a group header's shape when the list has groups, while the rows aren't known yet. |
 | `onOpen` | `((item: ListItemData) => void)` |  | Called when a row is opened with a click or Enter. Enter with ⌘ or Ctrl is left to the surrounding form. |
 | `onSelectedChange` | `((selected: Set<string>) => void)` |  | Called with the selected rows; rows then get checkboxes. |
 | `selectable` | `boolean` |  | Selection: checkboxes appear on hover, and on every row once something is selected. |
 | `selected` | `Set<string>` |  | The ids of the selected rows. |
 | `selectionActions` | `ReactNode` |  | Actions in the floating selection bar. |
-| `selectionBar` | `boolean` | `true` | The floating selection bar; off where the host shows the count itself, as in a dialog. |
+| `selectionBar` | `boolean` | `true` | The floating selection bar; off where the host shows the count itself, as in a dialog. Rows reached with the arrow keys scroll clear of it. |
 | `virtualizeAbove` | `number` | `100` | Virtualize above this many rows (100). |
 | `wrapSubtitle` | `boolean` | `false` | Lets a subtitle under its title wrap instead of ending with an ellipsis, for descriptions people read in full. |
 
@@ -1931,7 +1933,7 @@ One row: checkbox, glyph, id, title, subtitle, metadata, date, avatar, hover act
 | `idWidth` | `48 \| 64 \| 80 \| 96 \| 120` |  | The width of the id column in pixels, so ids line up. |
 | `index` | `number` |  | The row's position, for keyboard navigation. |
 | `lastChild` | `boolean` |  | Marks the last child of a parent, for the connecting line. |
-| `narrow` | `boolean` | `false` | The list is narrow (a phone): the title, the subtitle and the metadata with the date are lines of their own. |
+| `narrow` | `boolean` | `false` | The list is narrow (a phone): the title and the subtitle are lines of their own, and the metadata, the date, the avatar and the actions share one line under them, so titles keep the row's width. |
 | `onFocus` | `(() => void)` |  | Called when the row gets focus. |
 | `onOpen` | `(() => void)` |  | Called when the row is opened. |
 | `onSelect` | `(() => void)` |  | Called when the row is selected or unselected. |
@@ -1971,15 +1973,15 @@ The floating capsule with the selection count and its actions: the toast's mater
 
 ### Loader
 
-A status region with the spinner and a label: "Saving provider…", or a page or region that is loading. Its place is kept while it waits out `delay`, so nothing moves when it shows.
+A status region with the spinner and a label: "Saving provider…", or a page or region that is loading. Its place is kept while it waits out `delay`, so nothing moves when it shows; the status region is there, empty, from the start, and its words arrive when the spinner shows, so screen readers announce them.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `delay` | `number \| boolean` |  | Waits before the spinner and its label show, so quick work shows nothing: `true` for the library's 300ms (`useDelayedLoading`), or milliseconds. None by default. |
+| `delay` | `number \| boolean` |  | Waits before the spinner and its label show, so quick work shows nothing: the library's 300ms by default (`useDelayedLoading`), a number of milliseconds, or `false` to show at once. |
 | `hideLabel` | `boolean` |  | Keeps `label` for assistive technology only, where the page around it already says what is happening. |
 | `label` | `string` |  | Shown beside the spinner ("Saving provider…"); without one, "Loading" is announced in the provider's language. |
 | `loading` | `boolean` | `true` | Whether the work is underway; true by default. With `delay` and `minDuration`, it times the spinner. |
-| `minDuration` | `number` |  | Once shown, they stay at least this many milliseconds: 400 with a delay, 0 without. |
+| `minDuration` | `number` |  | Once shown, they stay at least this many milliseconds: 400 by default, 0 with `delay={false}`. |
 | `size` | `"md" \| "xs" \| "sm" \| "lg" \| "xl"` | `sm` | The loader's size on the type scale. |
 | `tone` | `"secondary" \| "tertiary" \| "current"` |  | The spinner's and the label's color: `secondary` by default. |
 
@@ -2018,7 +2020,7 @@ Kaeso's spinner: three routes on a ring, the lead in full color and the two behi
 
 ### Markdown
 
-Markdown, safely: headings, paragraphs, lists, tasks, code fences (CodeBlock), inline code, emphasis, links, quotes, rules and tables. Raw HTML stays text, links open only for http, https and mailto in a new tab, images are links. Long texts show their start until "Show all".
+Markdown, safely: headings, paragraphs, lists, tasks, code fences (CodeBlock), inline code, emphasis, links, quotes, rules and tables. Raw HTML stays text, links open only for http, https and mailto in a new tab, images are links. Long texts show their start until "Show all". A table wider than its column scrolls sideways with a fade and takes focus.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2046,12 +2048,12 @@ The same menu, opened by a right click, a long press or the context-menu key on
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` * | `ReactNode` |  | The area that opens the menu on a right click or long press. |
+| `children` * | `ReactNode` |  | The area that opens the menu on a right click or long press. When it holds nothing focusable, it becomes a focus stop, so Shift F10 and the context-menu key reach it; the focus returns to it when the menu closes. |
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
 
 ### Menu
 
-A dropdown menu: 16px radius, 34px rows, typeahead, Home/End, loops.
+A dropdown menu: 16px radius, 34px rows that grow when a label wraps, typeahead, Home/End, loops. An item's shortcut and hint describe it rather than name it. Checkbox and radio items show a check when chosen; the group's label says whether it takes one or several.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2075,18 +2077,18 @@ A row of menus, as in a desktop app's title bar.
 
 `import { Meter, Progress } from "@logicplanes/kaeso-ui/meter";`
 
-- **tone** (meter): `auto` (default) — Series 1 until the first alert threshold, warning after, danger at 100% (default); `neutral` — A plain share
+- **tone** (meter): `auto` (default) — Series 1 until the first alert threshold, amber (series 2) after, danger at 100%; the value and the caption take the warning or danger color too (default); `neutral` — A plain share
 - **kind** (progress): `determinate` (default) — A pill bar with a known amount; `indeterminate` — A 2px line at the top of a container
 
 ### Meter
 
-A limit or quota: label and value, a 6px pill track, threshold ticks, a caption.
+A limit or quota: label and value, a 6px pill track, threshold ticks cut out of the bar, a caption. Past the first threshold the bar turns amber and the value and caption turn the warning color, at the limit red, and screen readers hear "near the limit" or "over the limit" after the value; in light the bar's end keeps 3:1 against the track.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` * | `number` |  | 0–1 (or more when over the limit). |
 | `aria-label` | `string` |  | The accessible name, for when there is no visible label. |
-| `caption` | `ReactNode` |  | "Resets in 12 days" |
+| `caption` | `ReactNode` |  | "Resets in 12 days"; near or over the limit, say what happens, such as "Over the limit: requests are refused". |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `label` | `ReactNode` |  | The label above the bar. |
 | `leading` | `ReactNode` |  | Leading content in the label row (an icon). |
@@ -2097,7 +2099,7 @@ A limit or quota: label and value, a 6px pill track, threshold ticks, a caption.
 
 ### Progress
 
-Progress for work over a second: a determinate pill, or an indeterminate 2px line.
+Progress for work over a second: a determinate pill, or an indeterminate 2px line. With reduced motion the indeterminate line spans the width and pulses instead of sliding, so it never reads as a third done.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2109,7 +2111,7 @@ Progress for work over a second: a determinate pill, or an indeterminate 2px lin
 
 `import { PageHeader } from "@logicplanes/kaeso-ui/page-header";`
 
-- **size** (page_header): `md` (default) — 52px, no bottom line (default); on a phone the tabs take a second row
+- **size** (page_header): `md` (default) — 52px, no bottom line (default); on a phone the title and actions keep the first row and the tabs take a second
 
 ### PageHeader
 
@@ -2184,7 +2186,7 @@ Big numbers, period controls, a chart on the panel, a breakdown, an optional rig
 
 `import { Pagination } from "@logicplanes/kaeso-ui/pagination";`
 
-- **variant** (pagination): `load-more` (default) — A “Load more” pill while more rows exist, nothing once all are shown (cursor APIs, default); `cursor` — Previous and next circles, without a count; `pages` — Page numbers, for lists with a known number of pages
+- **variant** (pagination): `load-more` (default) — A “Load more” pill while more rows exist; once all are shown, nothing, or “All rows shown” where the button had focus (cursor APIs, default); `cursor` — Previous and next circles, without a count; `pages` — Page numbers in seven fixed slots, so Next stays under the pointer, for lists with a known number of pages
 
 ### Pagination
 
@@ -2193,14 +2195,14 @@ Moves through long lists by pages, by cursor, or with a Load more button.
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `hasMore` | `boolean` |  | Whether there is a next page. |
+| `hasMore` | `boolean` |  | Whether there is a next page; with Load more, turning it off after the last load shows “All rows shown” where focus was. |
 | `hasPrevious` | `boolean` |  | Whether there is a previous page. |
 | `loading` | `boolean` |  | Shows that a page is loading. |
 | `onLoadMore` | `(() => void)` |  | Called by the Load more button. |
 | `onNext` | `(() => void)` |  | Called to go to the next page. |
 | `onPageChange` | `((page: number) => void)` |  | Called with the chosen page number. |
 | `onPrevious` | `(() => void)` |  | Called to go to the previous page. |
-| `page` | `number` | `1` | pages: |
+| `page` | `number` | `1` | The current page, for numbered pages; previous and next stay in place and only announce themselves unavailable at the ends. |
 | `pageCount` | `number` | `1` | The number of pages, for numbered pages. |
 | `variant` | `"cursor" \| "load-more" \| "pages"` | `load-more` | Numbered pages, previous and next by cursor, or a Load more button. |
 
@@ -2219,7 +2221,7 @@ Moves through long lists by pages, by cursor, or with a Load more button.
 
 ### CompareGrid
 
-Columns side by side to compare models: equal widths, a header, a body that scrolls on its own and a footer each.
+Columns side by side to compare models: equal widths of at least 320px, a header, a body that scrolls on its own and a footer each. When the columns don't fit, Previous column and Next column reach the hidden ones. Removing a column is instant, so offer Undo in a toast.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2231,15 +2233,15 @@ Columns side by side to compare models: equal widths, a header, a body that scro
 | `divider` | `"none" \| "hairline"` | `hairline` | A hairline between columns, or none. |
 | `max` | `number` | `4` | Columns at most (4 by default): the add circle is disabled there, with the reason in its tooltip. |
 | `onActiveChange` | `((index: number) => void)` |  | Called with the index of the column in focus. |
-| `onAdd` | `(() => void)` |  | Adds a column: a circle at the end of the last column's header (and in the phone's switcher). |
+| `onAdd` | `(() => void)` |  | Adds a column: a circle in a narrow rail after the columns (on a phone, in the switcher, or in the header of a single column). Focus moves to the new column's header. |
 
 ### Composer
 
-The prompt box: a text box that grows with what is written up to `maxRows`, then scrolls; Send, which becomes Stop while a response streams. Enter sends and Shift Enter adds a line (`submitOn`); ⌘ Enter or Ctrl Enter also sends. On a touch screen Enter adds a line and the button sends.
+The prompt box: a text box that grows with what is written up to `maxRows`, then scrolls, its edge fading where more lines wait; Send, which becomes Stop while a response streams. Enter sends and Shift Enter adds a line (`submitOn`); ⌘ Enter or Ctrl Enter also sends. On a touch screen Enter adds a line and the button sends. A click anywhere in the box, the button row included, puts the cursor in the text.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `actions` | `ReactNode` |  | Controls at the start of the button row: parameters, clear. |
+| `actions` | `ReactNode` |  | Controls at the start of the button row: parameters, clear. Ghost and secondary buttons there take tones made for the composer's surface. |
 | `aria-label` | `string` |  | The text box's accessible name ("Prompt" by default). |
 | `autoFocus` | `boolean` |  | Focuses the composer when it appears. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
@@ -2255,9 +2257,9 @@ The prompt box: a text box that grows with what is written up to `maxRows`, then
 | `onValueChange` | `((value: string) => void)` |  | Called with the message as it is typed. |
 | `placeholder` | `string` |  | Text shown while there is no value. |
 | `size` | `"md" \| "sm"` | `md` | The composer's height. |
-| `stopLabel` | `string` |  | The stop button's accessible name, shown while a reply streams. |
-| `streaming` | `boolean` | `false` | A response is arriving: Send becomes Stop. The text box stays editable for the next prompt. |
-| `submitLabel` | `string` |  | The send button's accessible name. |
+| `stopLabel` | `string` |  | The Stop button's label, shown while a response streams ("Stop" by default). |
+| `streaming` | `boolean` | `false` | A response is arriving: Send becomes Stop. The text box stays editable for the next prompt; Enter waits, and the text box's description says to stop the response to send. |
+| `submitLabel` | `string` |  | The Send button's label ("Send" by default). |
 | `submitOn` | `"enter" \| "mod-enter"` | `enter` | The key that sends from the text box. `"enter"` (default): Enter sends and Shift Enter adds a line; on a touch screen Enter adds a line and the Send button sends. `"mod-enter"`: Enter adds a line and only ⌘ Enter (Ctrl Enter) sends. ⌘ Enter and Ctrl Enter send with either. |
 | `value` | `string` |  | The message being written, when you control it. |
 
@@ -2296,7 +2298,7 @@ A model from a catalogue of any size: a pill showing the chosen model that opens
 
 ### ParameterPanel
 
-A request's parameters: system instructions, temperature, top P, most output tokens, and, for a model that reasons, reasoning effort and summary. Unset values are the model's defaults; Reset returns to them (instructions stay).
+A request's parameters: system instructions, temperature, top P, maximum output tokens, and, for a model that reasons, reasoning effort and summary. Unset values are the model's defaults; Reset returns to them (instructions stay).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2307,13 +2309,13 @@ A request's parameters: system instructions, temperature, top P, most output tok
 | `disabled` | `boolean` | `false` | Turns off every parameter. |
 | `instructions` | `boolean` | `true` | Shows the system instructions field (true by default). |
 | `layout` | `"popover" \| "panel"` | `popover` | Compact inside a popover, or roomier in a side panel. |
-| `maxOutputTokensLimit` | `number` |  | The model's most output tokens: the field's maximum. |
+| `maxOutputTokensLimit` | `number` |  | The model's maximum output tokens: the field's maximum, named in a hint under it. |
 | `reasoning` | `boolean \| ReasoningEffort[]` | `false` | The reasoning efforts the model takes, or false (the default) when it doesn't reason: no effort and no summary. |
 | `sampling` | `boolean` | `true` | Shows temperature and top P; models that reason often take neither (true by default). |
 
 ### ParameterPopover
 
-ParameterPanel in a 320px popover from a sliders circle (or any trigger).
+ParameterPanel in a 320px popover from a sliders circle (or any trigger), with a Close button beside its title. Focus stays inside until it closes.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2324,7 +2326,7 @@ ParameterPanel in a 320px popover from a sliders circle (or any trigger).
 | `defaults` | `Pick<PlaygroundParameters, "temperature" \| "topP">` |  | What unset shows (temperature 1 and top P 1 unless given): the model's defaults. |
 | `disabled` | `boolean` | `false` | Turns off the button that opens the parameters. |
 | `instructions` | `boolean` | `true` | Shows the system instructions field (true by default). |
-| `maxOutputTokensLimit` | `number` |  | The model's most output tokens: the field's maximum. |
+| `maxOutputTokensLimit` | `number` |  | The model's maximum output tokens: the field's maximum, named in a hint under it. |
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
 | `reasoning` | `boolean \| ReasoningEffort[]` | `false` | The reasoning efforts the model takes, or false (the default) when it doesn't reason: no effort and no summary. |
@@ -2335,24 +2337,26 @@ ParameterPanel in a 320px popover from a sliders circle (or any trigger).
 
 ### PromptSuggestions
 
-Example prompts before a thread starts: up to three lines of plain secondary text that take a quiet fill on hover. No outlines, no icons; leave them out once a prompt is sent.
+Example prompts before a thread starts: up to three pill rows of secondary text that take a quiet fill on hover. No outlines, no icons; a prompt too long for its row shows in full in a tooltip. Leave them out once a prompt is sent.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `onSelect` * | `(prompt: string) => void` |  | Puts the prompt in the composer (or sends it). |
+| `onSelect` * | `(prompt: string) => void` |  | Puts the prompt in the composer (or sends it). The list usually goes away then, so move focus to the composer. |
 | `suggestions` * | `string[]` |  | Up to three short prompts; more are left out. |
 | `align` | `"start" \| "center"` | `start` | Aligns the suggestions at the start or in the center. |
 | `aria-label` | `string` |  | The list's accessible name. Defaults to "Example prompts" in the provider's language. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 
 ### Reasoning
 
-A model's reasoning behind a quiet disclosure, closed by default: “Thought for 4.2 s” when it is done, “Thinking” with the latest line beside it while it streams. Opened, the reasoning reads in small secondary text beside a line. The Playground and the request log show reasoning with it.
+A model's reasoning behind a quiet disclosure, closed by default: a chevron, then “Thought for 4.2 s” when it is done, or “Thinking” with the latest line beside it while it streams. Opened, the reasoning reads in small secondary text under the title, beside a line under the chevron. The Playground and the request log (ConversationView) show reasoning with it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` |  | What the open disclosure shows in place of `text`, such as why the reasoning can't be shown. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
+| `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `defaultOpen` | `boolean` |  | Whether it starts open. |
 | `duration` | `number` |  | How long the model reasoned, in milliseconds: “Thought for 4.2 s”. |
 | `hint` | `ReactNode` |  | A short note beside the title, such as “Redacted by the provider”; while `live`, the latest line of the reasoning shows there instead. |
@@ -2364,25 +2368,25 @@ A model's reasoning behind a quiet disclosure, closed by default: “Thought for
 
 ### ResponseMetrics
 
-A response's numbers on one line: time to first token, total time, tokens ("412 in · 168 out", and reasoning), cost to the millionth of a dollar, as request logs show it. Tabular figures, labels in tertiary text. While `live`, values not known yet show "—" in the room they will take; before any response the line is empty, its height kept.
+A response's numbers on one line: time to first token, total time, tokens ("412 in · 168 out", and reasoning), cost with the decimals it was given, as request logs show it. Tabular figures, labels in tertiary text. Every value keeps the room a typical value takes, so nothing moves when values arrive; while `live`, values not known yet show "—"; before any response the line is empty, its height kept.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `cost` | `string \| null` |  | USD as a decimal string: "0.004213" reads "$0.004213", and zero reads "$0". |
+| `cost` | `string \| null` |  | USD as a decimal string, shown with its own decimals (two at least, six at most): "0.004213" reads "$0.004213", "1.2311" reads "$1.2311", zero reads "$0" and less than a millionth reads "< $0.000001". |
 | `duration` | `number \| null` |  | Milliseconds from sending to the last token. |
 | `inputTokens` | `number \| null` |  | The tokens sent, once known. |
 | `live` | `boolean` | `false` | A response is arriving: values not known yet show a quiet "—" in the room they will take. |
 | `outputTokens` | `number \| null` |  | The tokens received, once known. |
 | `reasoning` | `boolean` |  | The model reasons: while `live`, the reasoning item waits with a placeholder. |
-| `reasoningTokens` | `number \| null` |  | Of the output tokens, those spent reasoning. Shown when given, or when `reasoning` is set. |
+| `reasoningTokens` | `number \| null` |  | Of the output tokens, those spent reasoning. Shown when given, or when `reasoning` is set ("—" when the provider didn't report them). |
 | `size` | `"md" \| "sm"` | `sm` | The text size. |
-| `startedAt` | `number` |  | When the request was sent (Date.now()): while live, Total counts up quietly until `duration` arrives. |
+| `startedAt` | `number` |  | When the request was sent (Date.now()): while live, Total counts up quietly, in tenths of a second and in whole seconds past ten, until `duration` arrives. |
 | `timeToFirstToken` | `number \| null` |  | Milliseconds from sending to the first token. |
 
 ### ResponseView
 
-A model's response as it arrives: Markdown text for reading (15/22), the reasoning summary in a "Thinking" disclosure (closed by default, live while it streams), and calm states for a stop, a cut-off reply or a failure, which shows its error in place.
+A model's response as it arrives: a quiet caret where the text will start until the first token, then Markdown text for reading (15/22) with the caret at its end while it streams; the reasoning summary in a "Thinking" disclosure (closed by default, live while it streams); and calm states for a stop, a cut-off reply or a failure, which shows its error in place. Text sits 12px in, code and tables on the edge; screen readers hear when a response finishes or stops.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2390,10 +2394,10 @@ A model's response as it arrives: Markdown text for reading (15/22), the reasoni
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `defaultReasoningOpen` | `boolean` |  | Whether the reasoning starts expanded. |
 | `error` | `string` |  | Why the reply failed, shown under "No response" with status "error": the gateway's message in the reader's language; `code` spans render as code. |
-| `footer` | `ReactNode` |  | Under the response: its metrics, actions. |
+| `footer` | `ReactNode` |  | Under the response, on its text line: its metrics, actions. |
 | `incompleteReason` | `string` |  | Why the model cut the reply off, with status "incomplete": `max_output_tokens` reads "Stopped at the output limit", `content_filter` names the filter. |
 | `onReasoningOpenChange` | `((open: boolean) => void)` |  | Called when the reasoning is expanded or collapsed. |
-| `onRetry` | `(() => void)` |  | Sends the turn again; shown with an error, a stop or a cut-off reply. |
+| `onRetry` | `(() => void)` |  | Sends the turn again: a Retry button after a stop, a cut-off reply or an error. |
 | `reasoning` | `string` |  | The reasoning summary so far, as Markdown. A "Thinking" disclosure shows it, closed by default. |
 | `reasoningDuration` | `number` |  | How long the model reasoned, in milliseconds: "Thought for 4.2 s". |
 | `reasoningOpen` | `boolean` |  | Whether the reasoning is expanded, when you control it. |
@@ -2411,7 +2415,7 @@ A conversation's turns, 32px apart: spacing, not lines or boxes, separates them.
 
 ### UserMessage
 
-A person's turn: their prompt as quiet text that opens the turn, no bubble. A long prompt shows its first lines until "Show all".
+A person's turn: their prompt as quiet text that opens the turn, no bubble. A long prompt shows its first lines until "Show all", a disclosure button under them.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2439,7 +2443,7 @@ A preview that opens while the pointer rests on its trigger or the trigger has f
 
 ### Popover
 
-A floating panel next to its trigger: radius 16, raised; collision-aware.
+A floating panel next to its trigger: radius 16, raised; collision-aware and never wider than the screen. Its content takes a title, or an aria-label, which names it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2583,7 +2587,7 @@ A release's artwork: flat geometric art in one of eight styles and Kaeso's palet
 
 ### ResourceList
 
-A console list of resources: search, group headers, row actions and a selection bar.
+A console list of resources: search, group headers, row actions and a selection bar. A search announces how many rows it leaves, and its no-match state offers Clear search.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2592,7 +2596,7 @@ A console list of resources: search, group headers, row actions and a selection
 | `bulkActions` | `{ label: string; icon?: IconSvgElement; onClick: (ids: string[]) => void; }[]` | `[]` | Actions for selected rows: [{label, icon, onClick(ids)}]. |
 | `emptyAction` | `ReactNode` |  | The action shown when there are no items. |
 | `emptyDescription` | `string` |  | The sentence shown when there are no items. |
-| `emptyTitle` | `string` |  | Defaults to "Nothing here yet" in the provider's language. |
+| `emptyTitle` | `string` |  | What will appear, such as "No keys yet". Pass it: the default names the collection by its `aria-label` ("No keys yet", in the provider's language), which only reads well for a plural noun. |
 | `onOpen` | `((item: ListItemData) => void)` |  | Called when an item is opened. |
 | `toolbar` | `ReactNode` |  | The filters and display options above the list. |
 
@@ -2600,11 +2604,11 @@ A console list of resources: search, group headers, row actions and a selection
 
 `import { ScrollArea } from "@logicplanes/kaeso-ui/scroll-area";`
 
-- **orientation** (scroll_area): `vertical` (default) — Scrolls up and down; the content fades at an edge with more to scroll to (default); `horizontal` — Scrolls sideways; `both` — Both directions
+- **orientation** (scroll_area): `vertical` (default) — Scrolls up and down; the content fades at an edge with more to scroll to (default); `horizontal` — Scrolls sideways; `both` — Both directions; the content fades at every edge with more to scroll to
 
 ### ScrollArea
 
-A scroll container with thin scrollbars in the strong line color that show on hover (5.1), its content fading at an edge with more to scroll to.
+A scroll container with thin scrollbars that show on hover and darken while held, its content fading at every edge with more to scroll to; its focus ring sits above the fade.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2712,7 +2716,7 @@ A pill that opens a list on the menu surface: check on the selected item, groups
 | `onValueChange` | `((value: string) => void) \| ((value: string[]) => void)` |  | Called with the chosen value, or the list of values with `multiple`. |
 | `open` | `boolean` |  | Whether the list is open, when you control it. |
 | `optional` | `boolean` |  | Adds “Optional” to the label, for forms where most fields are required. |
-| `placeholder` | `ReactNode` |  | Defaults to "Select" in the provider's language. |
+| `placeholder` | `ReactNode` |  | Defaults to "Not set" in the provider's language. |
 | `required` | `boolean` |  | Marks it as required in a form. |
 | `size` | `"md" \| "sm" \| "lg" \| "xl"` |  | The height of the field. |
 | `value` | `string \| string[] \| null` |  | The chosen value, or a list of values with `multiple`, when you control it. |
@@ -2794,17 +2798,17 @@ A panel that slides in from the edge of the screen, for details and longer forms
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` * | `ReactNode` |  | The sheet's content. |
-| `title` * | `ReactNode` |  | The sheet's heading, also its accessible name. |
+| `title` * | `ReactNode` |  | The sheet's heading, also its accessible name; a long one wraps. |
 | `actions` | `ReactNode` |  | Header actions before the close circle. |
 | `defaultOpen` | `boolean` |  | Whether it starts open, when the component keeps its own state. |
 | `footer` | `ReactNode` |  | Content at the bottom, usually actions. |
 | `inline` | `boolean` |  | Render without a portal, for documentation and state matrices. |
-| `modal` | `boolean` |  | Keep the page behind interactive (non-modal). |
+| `modal` | `boolean` |  | `false` keeps the page behind interactive, for an inspector: a press on the page leaves the sheet open, so the next row can fill it; Escape and the close circle close it. |
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
 | `side` | `"bottom" \| "left" \| "right"` |  | The edge it slides in from. |
-| `size` | `"md" \| "sm" \| "lg"` |  | The sheet's width, or its height from the bottom. |
-| `subtitle` | `ReactNode` |  | A mono subtitle for ids: `req_01J…`. |
+| `size` | `"md" \| "sm" \| "lg"` |  | The sheet's width from the side; a sheet from the bottom takes its content's height and ignores it. |
+| `subtitle` | `ReactNode` |  | A mono subtitle for ids, shown whole: `req_01J…`. |
 | `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | The element that opens it. |
 
 ## sidebar
@@ -2845,7 +2849,7 @@ Provided by NavSheet: how the sidebar's own toggle closes the sheet it floats in
 
 ### Skeleton
 
-A placeholder in the shape of the content that is loading.
+A placeholder in the shape of the content that is loading. It is hidden from screen readers, so the region it stands in for sets `aria-busy` while it loads (List, DataTable and StatTile do). In forced colours it keeps an outline.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2863,7 +2867,7 @@ Lines of text: the last one shorter.
 
 `import { Slider } from "@logicplanes/kaeso-ui/slider";`
 
-- **size** (slider): `md` (default) — A 4px track in a 20px hit area (default)
+- **size** (slider): `md` (default) — A 4px track in a 32px hit area (default)
 
 ### Slider
 
@@ -2916,7 +2920,7 @@ A big number followed by its word, no box, as on a usage page.
 
 ### StatGrid
 
-`StatTile`s in one raised group, divided by hairlines: two to a row, then as many as there are tiles (up to four) from 1024px. The last tile of a short row widens to fill it (the third of three spans both columns below 1024px), so the group never shows an empty cell. Where a number doesn't fit its tile (a phone, a long amount), every tile's number steps down a size, and the tiles take a row each when even the smallest doesn't fit: a value is never cut short.
+`StatTile`s in one raised group, divided by hairlines: two to a row, then as many as there are tiles (up to four) from 1024px. The last tile of a short row widens to fill it (the third of three spans both columns below 1024px), so the group never shows an empty cell. Where a number doesn't fit its tile (a phone, a long amount), every tile's number steps down a size, and the tiles take a row each when even the smallest doesn't fit. At the same width, live numbers only step the size down, never back up, so a digit that comes and goes doesn't make the tiles jump; a value that still can't fit ends in an ellipsis and shows in full in a tooltip.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -2932,7 +2936,7 @@ One metric of a dashboard row: its label, the number, the change against the pre
 |---|---|---|---|
 | `label` * | `ReactNode` |  | What the number is: "Requests", "Cost". |
 | `value` * | `ReactNode` |  | The number, already formatted. |
-| `change` | `{ value: number; better?: "up" \| "down"; }` |  | The change against the previous period, as a fraction (0.12 is +12%). `better` says which direction is good: errors are better down. |
+| `change` | `{ value: number; better?: "up" \| "down"; }` |  | The change against the previous period, as a fraction (0.12 is +12%). `better` says which direction is good: errors are better down. The badge is green or red and says "better" or "worse" to screen readers. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `detail` | `ReactNode` |  | A quiet line under the number: "vs. the previous 30 days", "0.4% of requests". |
 | `loading` | `boolean` |  | While the numbers load: the value, the change and the trend show their shape at the tile's final height. |
@@ -2954,7 +2958,7 @@ The same component under its plain name.
 | `children` | `ReactNode` |  | The word that carries the meaning. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `icon` | `IconSvgElement` |  | A mark before the word in the same color, e.g. `icons.success` for “Up to date”. |
-| `size` | `"md" \| "sm"` | `md` | The text size. |
+| `size` | `"md" \| "sm"` | `md` | The text size: 14px, or 13px (`sm`) with a 14px icon. |
 | `tone` | `"neutral" \| "success" \| "warning" \| "danger" \| "info"` | `neutral` | The status it marks. |
 
 ### StatusDot
@@ -2966,8 +2970,8 @@ A status word: "Active", "Expiring", "Down".
 | `children` | `ReactNode` |  | The word that carries the meaning. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
 | `icon` | `IconSvgElement` |  | A mark before the word in the same color, e.g. `icons.success` for “Up to date”. |
-| `size` | `"md" \| "sm"` | `md` | The dot's size. |
-| `tone` | `"neutral" \| "success" \| "warning" \| "danger" \| "info"` | `neutral` | The status the dot marks; keep it next to words that say the same. |
+| `size` | `"md" \| "sm"` | `md` | The text size: 14px, or 13px (`sm`) with a 14px icon. |
+| `tone` | `"neutral" \| "success" \| "warning" \| "danger" \| "info"` | `neutral` | The status the word marks; keep it next to words that say the same. |
 
 ## surface
 
@@ -3019,10 +3023,10 @@ A pill track and a round thumb that travels in 180ms.
 | `defaultChecked` | `boolean` |  | Whether it starts checked, when the component keeps its own state. |
 | `description` | `ReactNode` |  | One sentence of help under the label. |
 | `disabled` | `boolean` |  | Turns it off: it can't be used, and it looks dimmed. |
-| `disabledReason` | `string` |  | Why it is disabled, shown as a tooltip; it stays focusable so people can read it. |
+| `disabledReason` | `string` |  | Why it is disabled: shown under the label when there is one, and as a tooltip; it stays focusable so people can read it. |
 | `id` | `string` |  | The id of the control, so a label elsewhere can point to it. |
 | `label` | `ReactNode` |  | The switch's label. |
-| `loading` | `boolean` |  | Shows that the change is being saved and ignores clicks until it is. |
+| `loading` | `boolean` |  | Shows that the change is being saved: it ignores clicks at once, and a spinner shows in the track once saving takes 300ms. |
 | `name` | `string` |  | The field name the value is sent under in a form. |
 | `onCheckedChange` | `((checked: boolean) => void)` |  | Called with the new state when it is checked or unchecked. |
 | `readOnly` | `boolean` |  | Shows the value without letting people change it. |
@@ -3037,7 +3041,7 @@ A pill track and a round thumb that travels in 180ms.
 
 ### Table
 
-A plain table for small amounts of data; use `DataTable` for sorting, selection and many rows.
+A plain table for small amounts of data; use `DataTable` for sorting, selection and many rows. It has no row boxes, so its text sits on the gutter, not 12px in; its rows are 40px like DataTable's and grow when a cell wraps. Wider than its room, it scrolls sideways inside its own box under an edge fade, and the box takes focus as a group named "Table, scrolls sideways". Keep ids and model names on one line with `className="whitespace-nowrap"` on their cells.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -3047,8 +3051,8 @@ A plain table for small amounts of data; use `DataTable` for sorting, selection
 
 `import { PillTabs, Tabs } from "@logicplanes/kaeso-ui/tabs";`
 
-- **variant** (pill_tabs): `underline` — Underline tabs for detail pages: 40px, a 2px ink indicator that slides; `pill` (default) — Header tabs: separate 32px pills, the active one filled
-- **variant** (tabs): `underline` (default) — Underline tabs for detail pages: 40px, a 2px ink indicator that slides; `pill` — Header tabs: separate 32px pills, the active one filled
+- **variant** (pill_tabs): `underline` — Underline tabs for detail pages: 40px, labels 12px in like every box, a 2px ink indicator under the label that slides; `pill` (default) — Header tabs: separate 32px pills, the active one filled; the first pill's edge on the gutter
+- **variant** (tabs): `underline` (default) — Underline tabs for detail pages: 40px, labels 12px in like every box, a 2px ink indicator under the label that slides; `pill` — Header tabs: separate 32px pills, the active one filled; the first pill's edge on the gutter
 
 ### PillTabs
 
@@ -3092,10 +3096,10 @@ Another name for Tag.
 | `children` * | `ReactNode` |  | The pill's text. |
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `icon` | `IconSvgElement` |  | An icon before the text. |
-| `invalid` | `boolean` |  | Marks a value that isn't accepted. |
-| `onClick` | `((e: MouseEvent<HTMLElement, MouseEvent>) => void)` |  | Renders a button with a hover fill. |
+| `invalid` | `boolean` |  | Marks a value that isn't accepted: a red ring, red text and an error icon named "Not accepted", so it doesn't rest on color. |
+| `onClick` | `((e: MouseEvent<HTMLElement, MouseEvent>) => void)` |  | Renders a button with the control's hover, press and focus: raised tags take the secondary button's material, outline tags the ghost's. |
 | `onRemove` | `((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void)` |  | Shows a remove circle; called with the click. |
-| `pressed` | `boolean` |  | For toggle pills (DisplayOptions). |
+| `pressed` | `boolean` |  | For toggle pills (DisplayOptions): sets aria-pressed, and `true` draws the selected soft fill whatever the variant, so a toggle needs no variant swap. |
 | `removeLabel` | `string` |  | The remove circle's accessible name. Defaults to "Remove" and the label in the provider's language. |
 | `size` | `"md" \| "sm"` | `md` | The pill's height. |
 | `variant` | `"outline" \| "soft" \| "raised"` | `raised` | Raised on the panel, soft fill, or outlined. |
@@ -3109,10 +3113,10 @@ A metadata pill: 28px, 13/500, an optional icon, an optional remove circle. A la
 | `children` * | `ReactNode` |  | The tag's text. |
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `icon` | `IconSvgElement` |  | An icon before the text. |
-| `invalid` | `boolean` |  | Marks a value that isn't accepted. |
-| `onClick` | `((e: MouseEvent<HTMLElement, MouseEvent>) => void)` |  | Renders a button with a hover fill. |
+| `invalid` | `boolean` |  | Marks a value that isn't accepted: a red ring, red text and an error icon named "Not accepted", so it doesn't rest on color. |
+| `onClick` | `((e: MouseEvent<HTMLElement, MouseEvent>) => void)` |  | Renders a button with the control's hover, press and focus: raised tags take the secondary button's material, outline tags the ghost's. |
 | `onRemove` | `((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void)` |  | Shows a remove circle; called with the click. |
-| `pressed` | `boolean` |  | For toggle pills (DisplayOptions). |
+| `pressed` | `boolean` |  | For toggle pills (DisplayOptions): sets aria-pressed, and `true` draws the selected soft fill whatever the variant, so a toggle needs no variant swap. |
 | `removeLabel` | `string` |  | The remove circle's accessible name. Defaults to "Remove" and the label in the provider's language. |
 | `size` | `"md" \| "sm"` | `md` | The tag's height. |
 | `variant` | `"outline" \| "soft" \| "raised"` | `raised` | Raised on the panel, soft fill, or outlined. |
@@ -3136,7 +3140,7 @@ Text in the type scale.
 | `mono` | `boolean` |  | Geist Mono, for keys, ids, model ids and code. |
 | `tabular` | `boolean` |  | Tabular numerals. On by default for `metric`. |
 | `tone` | `"success" \| "warning" \| "danger" \| "info" \| "inherit" \| "secondary" \| "default" \| "tertiary"` | `default` | The text color role; status tones go next to words that say the same. |
-| `truncate` | `boolean` |  | One line with an ellipsis; the full text appears in a tooltip when it is cut. |
+| `truncate` | `boolean` |  | One line with an ellipsis; when it is cut, plain text becomes a focus stop whose tooltip shows all of it. |
 | `variant` | `"title" \| "display" \| "caption" \| "title-sm" \| "title-lg" \| "body" \| "small" \| "micro" \| "body-lg" \| "metric"` | `body` | The type style, from `micro` to `display`. |
 | `weight` | `"medium" \| "regular" \| "semibold"` |  | The weight, when it differs from the type style's. |
 
@@ -3157,7 +3161,7 @@ An image drawn twice, once for each theme: it follows the site's theme setting,
 | `light` * | `string` |  | The image's address for the light theme and for print. |
 | `aria-describedby` | `string` |  | The id of a longer description, such as a diagram's text alternative. |
 | `className` | `string` |  | Classes for the layout of the outer element: margin, width and placement, never its look. |
-| `height` | `number` |  | The image's own height in pixels, so the page keeps its place before it loads. |
+| `height` | `number` |  | The image's own height in pixels. Pass it with `width` so the page keeps the image's place before it loads; without both, the content below moves when it arrives. |
 | `width` | `number` |  | The image's own width in pixels; the image shrinks to its container, never grows past this. |
 
 ## theme-menu
@@ -3222,7 +3226,7 @@ A square image someone sent, such as a photo in a conversation: cropped to fill,
 
 ### Timeline
 
-Events down a 1px line (the audit log): each event marks the line with a short 3px bar in its tone, no dots; titles, and times on the right.
+Events down a 1px line (the audit log): each event marks the line with a short 3px bar in its tone, no dots; titles, and times on the right. A toned event's title starts with its tone in words for screen readers ("Critical: Key revoked"), and a time with `datetime` shows the exact date and time in a tooltip.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -3242,7 +3246,7 @@ Events down a 1px line (the audit log): each event marks the line with a short 3
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `limit` | `number` | `3` | How many toasts show at once. |
-| `timeout` | `number` | `5000` | How long a toast stays, in milliseconds. |
+| `timeout` | `number` | `5000` | How long a toast stays, in milliseconds; errors and toasts with an action stay until dismissed, unless `toast()` gets a timeout of its own. |
 
 ### ToastCapsule
 
@@ -3252,29 +3256,29 @@ The capsule alone, for documentation and state matrices.
 |---|---|---|---|
 | `title` * | `ReactNode` |  | The message. |
 | `action` | `string` |  | The label of the toast's action button. |
-| `closable` | `boolean` |  | Shows a close button. |
+| `closable` | `boolean` |  | Shows the close button at its end, as a toast that stays until dismissed has. |
 | `data-force` | `string` |  | Forces an interaction state for state matrices: `hover`, `pressed`, `focus`, `open`. |
 | `description` | `ReactNode` |  | One more sentence, when the message needs it. |
 | `tone` | `"neutral" \| "success" \| "warning" \| "info" \| "loading" \| "error"` | `neutral` | The kind of message; `loading` shows a spinner. |
 
 ### Toaster
 
-Mount once near the root. Three visible at most; 5s, paused on hover and focus; swipe or Escape to dismiss. With a client router that replaces <body> on navigation (Astro's ClientRouter), mount it in a persisted element inside a `PortalContainer`, so the toasts are not swapped away with the page.
+Mount once near the root. Three visible at most; 5s, paused on hover and focus; an error, or a toast with an action such as Undo, stays until it is dismissed; the close button, a swipe or Escape dismisses, and F6 moves the focus to the toasts. With a client router that replaces <body> on navigation (Astro's ClientRouter), mount it in a persisted element inside a `PortalContainer`, so the toasts are not swapped away with the page.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `limit` | `number` | `3` | How many toasts show at once. |
-| `timeout` | `number` | `5000` | How long a toast stays, in milliseconds. |
+| `timeout` | `number` | `5000` | How long a toast stays, in milliseconds; errors and toasts with an action stay until dismissed, unless `toast()` gets a timeout of its own. |
 
 ## toc
 
 `import { TableOfContents } from "@logicplanes/kaeso-ui/toc";`
 
-- **state** (table_of_contents): `default` (default) — A heading; `active` — The heading in view, with a 2px ink bar
+- **state** (table_of_contents): `default` (default) — A heading; `active` — The heading in view, with a 2px ink bar on the rail (a solid line in forced colours)
 
 ### 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.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -3287,11 +3291,11 @@ Mount once near the root. Three visible at most; 5s, paused on hover and focus;
 
 `import { Toolbar } from "@logicplanes/kaeso-ui/toolbar";`
 
-- **size** (toolbar): `md` (default) — 48px, 24px side padding, under the page header (default); `inset` — 48px without side padding, inside padded content
+- **size** (toolbar): `md` (default) — 48px, 24px side padding, under the page header (default); one tab stop, arrows move between controls; `inset` — 48px without side padding, inside padded content
 
 ### Toolbar
 
-A row of controls above a list or a chart.
+A row of controls above a list or a chart: one tab stop, with the arrow keys moving between its controls.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -3307,7 +3311,7 @@ A row of controls above a list or a chart.
 
 ### Tooltip
 
-A short label for a control, shown on hover and focus. Never on disabled elements without a reason.
+A short label for a control, shown on hover and focus. When it says more than the control's name, it is also the control's accessible description. Never on disabled elements without a reason.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -3318,14 +3322,14 @@ A short label for a control, shown on hover and focus. Never on disabled element
 | `disabled` | `boolean` |  | Never shows the tooltip. |
 | `onOpenChange` | `((open: boolean) => void)` |  | Called when it opens or closes. |
 | `open` | `boolean` |  | Whether it is open, when you control it. |
-| `shape` | `"pill" \| "multiline"` | `pill` | A pill for a short label, or a box for several lines. |
+| `shape` | `"pill" \| "multiline"` | `pill` | A pill for a short label, or a box for several lines; a pill too long for the screen wraps into the box. |
 | `shortcut` | `string[] \| string[][]` |  | A shortcut shown after the text: `["mod", "k"]` or `[["g"], ["m"]]`. |
 | `side` | `"top" \| "bottom" \| "left" \| "right"` |  | The side it opens on. |
 | `sideOffset` | `number` |  | Distance from the trigger in px. |
 
 ### TooltipProvider
 
-Tooltips open after 500ms, and instantly when moving between tooltipped siblings.
+Tooltips open once the pointer has rested on a control for 500ms, and instantly when moving between tooltipped siblings.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|