@kb.ui/react 0.11.0 → 0.12.0

package/docs/components/Spinner.md

@@ -17,11 +17,16 @@ export function Example() {
 
 ## More examples
 
-- [Fancy variants and status pills](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--fancy-variants): Compare `ring`, `orbit`, `dots`, and `bars` indicators alongside elevated `pill` status framing.
-- [Visible status label](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--with-visible-label): Pair the animated arc with explicit text describing what is loading.
-- [Busy button submission](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--busy-button): Render a decorative spinner inside a disabled button during asynchronous submission.
+- [Variants](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--variants): Compare the `ring`, `orbit`, `dots`, and `bars` indicators.
+- [Pill](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--pill): Frame a spinner and its visible label as a compact status chip.
+- [With label](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--with-label): Show the label next to the indicator so sighted users know what is loading.
+- [Busy button](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--busy-button): Render a decorative spinner inside a disabled button during asynchronous submission.
 - [Sizes and tones](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--sizes-and-tones): Match compact controls, inline status rows, or section-level waits.
 
+## Motion
+
+The ring expands and contracts through a continuous sweep. Orbit combines two opposing sweeps around a breathing core; dots lift in sequence and bars run a staggered wave. Motion uses the existing `--kb-spinner-*` duration, easing, and stagger tokens. Reduced-motion preferences leave a static indicator and retain the status label.
+
 ## Reference
 
 | Prop         | Type                                                                         | Default     | Notes                                                                                |
@@ -37,4 +42,4 @@ export function Example() {
 
 ## Related components
 
-Use [Progress](Progress.md) when a numeric completion ratio exists, [Skeleton](Skeleton.md) to preserve layout geometry while loading content, and [Status](Status.md) for persistent state labels.
+Use [`Progress`](Progress.md) when a numeric completion ratio exists, [`Skeleton`](Skeleton.md) to preserve layout geometry while loading content, and [`Status`](Status.md) for persistent state labels.

package/docs/components/Split.md

@@ -1,6 +1,6 @@
 # Split
 
-Two children form equal or weighted columns through layout-owned `.kb-split-track` wrappers. Below the available-width threshold, columns stack in source order. Layout uses CSS alone, including inside nested panels. Native props and matching ref pass through.
+Use `Split` for two columns with equal or different widths. Each child sits in a `.kb-split-track` wrapper. When space is tight, the columns stack in source order. This uses CSS alone and also works inside nested panels. Native HTML props and the matching `ref` pass through.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-split--docs)
 
@@ -36,12 +36,12 @@ export function Example() {
 | `as`         | `div` `section` `article`                          | `div`     |
 | `ratio`      | `equal` (1:1) `wide-start` (2:1) `wide-end` (1:2)  | `equal`   |
 | `collapse`   | `sm` (32rem) `md` (48rem) `lg` (64rem)             | `md`      |
-| `gap`        | `none` `sm` `md` `lg`, same scale as Inline        | `md`      |
+| `gap`        | `none` `sm` `md` `lg`, same scale as `Inline`        | `md`      |
 | `align`      | `start` `center` `end` `baseline` `stretch`        | `stretch` |
 | `classNames` | `{ track?: string }`, applied to each column track | unset     |
 
-Provide two children; empty conditional children add no track. Each track owns column sizing, so Text keeps its reading measure and nested token overrides stay local. Non-default generic native elements require an explicit `as`. Use Grid for variable child counts. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md).
+Provide two children, one per column. Empty conditional children add no track. The track controls column width, so `Text` keeps its line-length limit and nested token overrides affect only that nested layout. Set `as` explicitly when using an element other than the default. Use `Grid` when the number of children varies. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md).
 
 ## Related components
 
-Use [Grid](Grid.md) for a variable number of children and [Container](Container.md) for the page boundary.
+Use [`Grid`](Grid.md) for a variable number of children and [`Container`](Container.md) for the page boundary.

package/docs/components/Stack.md

@@ -0,0 +1,54 @@
+# Stack
+
+Vertical flow with shared spacing: the block-axis counterpart to `Inline`. Children keep source and tab order; `Stack` adds no role, focus management or keyboard handling. Native props and matching ref pass through.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-stack--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Heading, Inline, Stack, Text } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Stack as="section" aria-labelledby="billing-title">
+      <Heading level={2} size="md" id="billing-title">
+        Billing
+      </Heading>
+      <Text>Your plan renews on 1 December.</Text>
+      <Inline gap="sm">
+        <Button>Change plan</Button>
+        <Button variant="secondary">Download invoices</Button>
+      </Inline>
+    </Stack>
+  );
+}
+```
+
+## More examples
+
+- [Section rhythm](https://kbui.kcb.pro/storybook/?path=/story/layout-stack--sections): Nest sections with a wider outer gap.
+- [Inline-axis alignment](https://kbui.kcb.pro/storybook/?path=/story/layout-stack--alignment): Compare stretched and content-width children.
+- [Block-axis distribution](https://kbui.kcb.pro/storybook/?path=/story/layout-stack--justify): Push actions to the bottom of a fixed-height card.
+- [Form fields](https://kbui.kcb.pro/storybook/?path=/story/layout-stack--form): Space fields and actions in a native form.
+- [A native list](https://kbui.kcb.pro/storybook/?path=/story/layout-stack--list): Ordered steps without list chrome.
+
+## Reference
+
+| Prop      | Values                                                        | Default   |
+| --------- | ------------------------------------------------------------- | --------- |
+| `as`      | `div` `section` `article` `aside` `ul` `ol` `nav` `form`      | `div`     |
+| `gap`     | `none` `sm` (0.5rem) `md` (1rem) `lg` (1.5rem)                | `md`      |
+| `align`   | `start` `center` `end` `stretch`                              | `stretch` |
+| `justify` | `start` `center` `end` `between`                              | `start`   |
+
+Non-default native elements require an explicit `as`; native props and refs follow that element. Explicit layout props own their data attributes even when caller attributes conflict.
+
+`gap` owns vertical rhythm: `Stack` removes block margins from its direct children and its own browser margins, padding and list markers. `align="stretch"` fills the stack's width; `start`, `center` and `end` size children to their content. `justify` distributes children only when the stack is taller than its content, for example with `style={{ blockSize: "100%" }}` inside a fixed-height parent.
+
+A named `section` exposes a region landmark; name it with `aria-labelledby`. With `ul` or `ol`, use `li` children. `Stack` removes list markers, so include `role="list"` when Safari must keep announcing the list; see [MDN’s list-style accessibility guidance](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/list-style#accessibility). Override `--kb-layout-gap-sm`, `-md` or `-lg` on a subtree to change the shared scale. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md).
+
+## Related components
+
+Use [`Inline`](Inline.md) for a wrapping row, [`Grid`](Grid.md) when items may share columns, and [`Split`](Split.md) for two columns that stack below a threshold.

package/docs/components/Stat.md

@@ -31,4 +31,4 @@ export function Example() {
 
 ## Related components
 
-Use [Progress](Progress.md) when the number represents completion and [Status](Status.md) for changing state.
+Use [`Progress`](Progress.md) when the number represents completion and [`Status`](Status.md) for changing state.

package/docs/components/StatsRow.md

@@ -0,0 +1,80 @@
+# StatsRow
+
+Show a few comparable metrics in a row, such as the key figures at the top of a dashboard. The row fills its region and wraps into more rows when narrow.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-statsrow--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Link, StatsRow } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <StatsRow aria-label="Store performance, September 2026">
+      <StatsRow.Item
+        label="Total revenue"
+        value="$48,250"
+        change="+12.8%"
+        trend="up"
+        tone="positive"
+        context="vs. previous month"
+        link={<Link href="/revenue">View revenue</Link>}
+      />
+      <StatsRow.Item
+        label="Orders"
+        value="625"
+        change="+8.7%"
+        trend="up"
+        tone="positive"
+        context="vs. previous month"
+      />
+      <StatsRow.Item
+        label="Refund requests"
+        value="38"
+        change="+12 requests"
+        trend="up"
+        tone="negative"
+        context="vs. previous month"
+      />
+    </StatsRow>
+  );
+}
+```
+
+Items share equal columns no narrower than `--kb-statsrow-item-min-width` (10rem) and fill the row. Below that width they wrap into more rows, so no screen size scrolls sideways. Labels, values, changes and links each share a track across a row, so a label that wraps to two lines keeps the values beside it aligned.
+
+## More examples
+
+- [Outlined with links](https://kbui.kcb.pro/storybook/?path=/story/components-statsrow--outlined): Put each metric on a card surface and link to its detail screen.
+- [Direction and tone](https://kbui.kcb.pro/storybook/?path=/story/components-statsrow--direction-and-tone): Set the direction glyph apart from whether the change is good news.
+- [Compact wrap](https://kbui.kcb.pro/storybook/?path=/story/components-statsrow--wrap): See six metrics wrap at the widths of 390 and 768 pixel screens.
+
+## Reference
+
+`StatsRow` renders a `ul`; other native `ul` props, including `aria-label` and `aria-labelledby`, pass through to it.
+
+| Prop         | Type                  | Default | Notes                                                     |
+| ------------ | --------------------- | ------- | --------------------------------------------------------- |
+| `appearance` | `plain` / `outlined`  | `plain` | Plain metrics on the page, or each metric on a card surface |
+| `children`   | `StatsRow.Item` nodes | unset   | One item per metric                                       |
+
+`StatsRow.Item` renders an `li` around a [`Stat`](Stat.md); other native `li` props pass through to it.
+
+| Prop         | Type                                | Default   | Notes                                                                       |
+| ------------ | ----------------------------------- | --------- | --------------------------------------------------------------------------- |
+| `label`      | `ReactNode`                         | required  | What the value measures; read first                                         |
+| `value`      | `ReactNode`                         | required  | The figure with its unit; tabular figures                                   |
+| `change`     | `ReactNode`                         | unset     | Change since the comparison period; its text states the direction, such as `+12.8%` |
+| `trend`      | `up` / `down` / `flat`              | unset     | Direction glyph before `change`; hidden from assistive technology; needs `change` |
+| `tone`       | `positive` / `negative` / `neutral` | `neutral` | Colors `change` by whether it is good news, apart from its direction; needs `change` |
+| `context`    | `ReactNode`                         | unset     | Comparison period or freshness, such as `vs. previous month`                |
+| `link`       | `ReactNode`                         | unset     | `Link` to the detail behind the metric; aligned on the last row of the item   |
+| `classNames` | keyed classes                       | unset     | Style `stat`, `label`, `value`, `trend`, `change`, `glyph`, `context`, `link` |
+
+Keep units comparable across a row: one currency, the same precision and one comparison period. Write the direction into the change text; color and the glyph do not convey it on their own. Tone is color only, so when good or bad news is not obvious from the label, say it in the change or context text, such as `+12 requests, above target`.
+
+## Related components
+
+Use [`Stat`](Stat.md) for a single figure, [`Progress`](Progress.md) when a metric measures completion toward a target, [`DescriptionList`](DescriptionList.md) for labelled record details that are not comparable figures, and [`Grid`](Grid.md) for collections of cards that are not metrics.

package/docs/components/Status.md

@@ -1,6 +1,6 @@
 # Status
 
-Use Status for a state such as running, blocked, or complete. Always include text so the meaning is clear without relying on color or an icon.
+Use `Status` for a state such as running, blocked, or complete. Always include text so the meaning is clear without relying on color or an icon.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-status--docs)
 
@@ -21,9 +21,10 @@ export function Example() {
 
 ## More examples
 
-- [Changing state](https://kbui.kcb.pro/storybook/?path=/story/components-status--live): Inspect the status announcement contract.
+- [Changing state](https://kbui.kcb.pro/storybook/?path=/story/components-status--live): Check how status updates are announced.
 - [Supporting iconography](https://kbui.kcb.pro/storybook/?path=/story/components-status--with-icon): Keep meaning in text when an icon is present.
-- [A compact state label](https://kbui.kcb.pro/storybook/?path=/story/components-status--chip): Compare a contained appearance.
+- [A compact state label](https://kbui.kcb.pro/storybook/?path=/story/components-status--chip): Compare a contained appearance; the icon leads the chip.
+- [A chip without an icon](https://kbui.kcb.pro/storybook/?path=/story/components-status--chip-without-icon): The chip leads with a dot in the tone's color.
 
 ## Reference
 
@@ -38,10 +39,10 @@ export function Example() {
 | `children`   | `ReactNode`                                                        | unset     | State text such as Running or Blocked; keep it meaningful without color |
 | `tone`       | `neutral` / `info` / `running` / `success` / `warning` / `blocked` | `neutral` | Reinforces the written state                                            |
 | `appearance` | `plain` / `chip`                                                   | `plain`   | Plain stays inline; chip adds separation with a tinted surface          |
-| `icon`       | `ReactNode`                                                        | unset     | Optional decorative icon; the text still names the state                |
-| `live`       | `boolean`                                                          | `false`   | Adds role=status for changing text; does not move focus                 |
+| `icon`       | `ReactNode`                                                        | unset     | Decorative; the text still names the state. Replaces a chip's dot       |
+| `live`       | `boolean`                                                          | `false`   | Adds `role=status` for changing text; does not move focus                 |
 | `compact`    | `boolean`                                                          | `false`   | Tighter spacing and smaller text for dense layouts                      |
 
 ## Related components
 
-Use [Badge](Badge.md) for static metadata, [Progress](Progress.md) for completion, and [Callout](Callout.md) for a fuller message.
+Use [`Badge`](Badge.md) for static metadata, [`Progress`](Progress.md) for completion, and [`Callout`](Callout.md) for a fuller message.

package/docs/components/SupportingPane.md

@@ -0,0 +1,59 @@
+# SupportingPane
+
+Use `SupportingPane` for a page with one main task and supporting context beside it, such as a cart with its order summary or a record list with an inspector. It renders a main region and a named `aside` landmark. From 48rem of page content width the aside sits beside main at a fixed width while main fills the rest; below that it moves under main. It also frames the page: full width up to 80rem, centred, with 1, 1.5 and 2rem gutters. For two equal columns inside a section, use [`Split`](Split.md).
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-supportingpane--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Card, Heading, PageHeader, SupportingPane, Text } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <main>
+      <SupportingPane
+        asideLabelledBy="summary-title"
+        aside={
+          <Card as="div">
+            <Heading level={2} id="summary-title">
+              Order summary
+            </Heading>
+            <Text>Total $245.75</Text>
+            <Button>Continue to payment</Button>
+          </Card>
+        }
+      >
+        <PageHeader title="Your cart" description="Your sneakers are reserved for 15 minutes." />
+        <Text>2 items</Text>
+      </SupportingPane>
+    </main>
+  );
+}
+```
+
+## More examples
+
+- [Shoe cart](https://kbui.kcb.pro/storybook/?path=/story/layout-supportingpane--shoe-cart): Items, free-shipping progress and help in main; the order summary beside them, or below them on narrow screens.
+- [Inspector](https://kbui.kcb.pro/storybook/?path=/story/layout-supportingpane--inspector): An order list with the selected order's details in the aside.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | unset | Main region content, starting with the page heading |
+| `aside` | `ReactNode` | unset | Supporting content; omit it and main fills the page |
+| `asideLabelledBy` | `string` | unset | Id of a visible heading inside the aside that names it |
+| `asideLabel` | `string` | unset | Accessible name for the aside when it has no visible heading |
+| `classNames` | `{ main?, aside? }` | unset | Classes for the regions |
+
+Other native `div` props and `ref` pass through to the root. Main comes first in source order and the aside second at every width; nothing is reordered. Each region stacks its children with the pane's gap, so main content needs no extra wrapper.
+
+Tokens: `--kb-supportingpane-max-width`, `--kb-supportingpane-gutter-sm`, `-md`, `-lg`, `--kb-supportingpane-gap` and `--kb-supportingpane-aside-width`. Gutters step at 48rem and 64rem of viewport width; the aside moves beside main at 48rem of the pane's own content width, so a pane inside a narrow parent stays stacked.
+
+Place `SupportingPane` inside your page's `main` and start main content with the page's `h1`, such as a [`PageHeader`](PageHeader.md). Name the aside, preferably from its visible heading; the complementary landmark is allowed inside main. The aside does not stick or hide; your app owns any show and hide control and its focus.
+
+## Related components
+
+Use [`PageHeader`](PageHeader.md) to open main, [`Card`](Card.md) to group the aside, and [`Split`](Split.md) for proportional columns inside a section.

package/docs/components/Switch.md

@@ -1,6 +1,6 @@
 # Switch
 
-Use Switch for a preference that takes effect as soon as it changes. Pass `checked` and update it in `onCheckedChange`; your app handles saving and form reset. Switch uses a labelled native checkbox with `role="switch"`. Use Checkbox when people are selecting items instead.
+Use `Switch` for a preference that takes effect as soon as it changes. Pass `checked` and update it in `onCheckedChange`; your app handles saving and form reset. `Switch` uses a labelled native checkbox with `role="switch"`. Use `Checkbox` when people are selecting items instead.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-switch--docs)
 
@@ -40,13 +40,13 @@ export function Example() {
 | `tone`                                 | `"accent" \| "neutral" \| "info" \| "success" \| "warning" \| "danger"` | `"accent"`           | Checked-state track tone when `onTone` is unset                                                                                      |
 | `offTone` / `onTone`                   | `SwitchTone`                                                            | `"neutral"` / `tone` | Independent track tone for unchecked and checked sides                                                                               |
 | `offColor` / `onColor`                 | `string`                                                                |                      | Custom CSS color for the unchecked or checked track                                                                                  |
-| `description` / `error`                | `string`                                                                |                      | Associated helper/error text; error sets aria-invalid                                                                                |
+| `description` / `error`                | `string`                                                                |                      | Associated helper/error text; error sets `aria-invalid`                                                                                |
 | `disabled` / `readOnly`                | `boolean`                                                               | `false`              | Disabled blocks focus/changes; read-only keeps focus and form value while blocking edits                                             |
 | `visuallyHidden`                       | `boolean`                                                               | `false`              | Hide label visually, keep its accessible name                                                                                        |
 | `offIcon` / `onIcon`                   | `ReactNode`                                                             |                      | Decorative slots; do not place interactive content inside                                                                            |
-| `name` / `value` / `form` / `required` | native input props                                                      |                      | Native form ownership, successful value and validation                                                                               |
+| `name` / `value` / `form` / `required` | native `input` props                                                      |                      | Native form ownership, successful value and validation                                                                               |
 | `ref`                                  | `Ref<HTMLInputElement>`                                                 |                      | Native checkbox, never an extra hidden control                                                                                       |
-| `className` / `controlClassName`       | `string`                                                                |                      | Root/native input class                                                                                                              |
+| `className` / `controlClassName`       | `string`                                                                |                      | Root/native `input` class                                                                                                              |
 | `style`                                | `CSSProperties`                                                         |                      | Native input styles; CSS custom properties also reach visible track and thumb                                                        |
 
 ```tsx
@@ -70,4 +70,4 @@ Import `useState` from React and `Switch` from `@kb.ui/react`. Clicking or press
 
 ## Related components
 
-Use [Checkbox](Checkbox.md) for a choice submitted with other answers and [RadioGroup](RadioGroup.md) for one of several settings.
+Use [`Checkbox`](Checkbox.md) for a choice submitted with other answers and [`RadioGroup`](RadioGroup.md) for one of several settings.

package/docs/components/Table.md

@@ -48,7 +48,7 @@ export function Example() {
 ## More examples
 
 - [Sorting and selection](https://kbui.kcb.pro/storybook/?path=/story/components-table--sorting-and-selection): Numeric and text ordering, stable selected IDs, mixed selection and excluded rows.
-- [Row actions](https://kbui.kcb.pro/storybook/?path=/story/components-table--sorting-and-selection): Named Buttons and Menu composition with focus return.
+- [Row actions](https://kbui.kcb.pro/storybook/?path=/story/components-table--sorting-and-selection): Named Buttons and `Menu` composition with focus return.
 - [Dense and sticky](https://kbui.kcb.pro/storybook/?path=/story/components-table--dense-sticky): Bounded scrolling, sticky headers and a pinned first column.
 
 ## Reference
@@ -63,14 +63,14 @@ export function Example() {
 | `Table.ColumnHeader` | `th`, optional `button` | Defaults `scope="col"`; controlled sorting and logical alignment |
 | `Table.RowHeader` | `th` | Defaults `scope="row"`; supports grouped header scope override |
 | `Table.Cell` | `td` | Native data cell; supports `colSpan`, `rowSpan`, children and ref |
-| `Table.SelectionCheckbox` | Checkbox | Same required `label`, `checked`, `onCheckedChange`, optional `indeterminate`, `disabled`, `readOnly`, ref and slots as Checkbox |
-| `Table.RowActions` | `div` | Wrapping, end-aligned actions; compose named Buttons, links or Menu |
+| `Table.SelectionCheckbox` | `Checkbox` | Same required `label`, `checked`, `onCheckedChange`, optional `indeterminate`, `disabled`, `readOnly`, ref and slots as `Checkbox` |
+| `Table.RowActions` | `div` | Wrapping, end-aligned actions; compose named Buttons, links or `Menu` |
 
 | Prop | Applies to | Default | Behavior |
 |---|---|---|---|
-| `density` | Table | `comfortable` | `comfortable` or `dense`; controls cell spacing, preserves control targets |
-| `layout` | Table | `auto` | `auto` or `fixed`; with fixed layout supply widths through native `colgroup`/`col` or styles |
-| `stickyHeader` | Table | false | Pins the complete head, including grouped header rows, to the scroll boundary |
+| `density` | `Table` | `comfortable` | `comfortable` or `dense`; controls cell spacing, preserves control targets |
+| `layout` | `Table` | `auto` | `auto` or `fixed`; with fixed layout supply widths through native `colgroup`/`col` or styles |
+| `stickyHeader` | `Table` | false | Pins the complete head, including grouped header rows, to the scroll boundary |
 | `align` | Cell, ColumnHeader, RowHeader | `start` | Logical `start`, `center`, `end`; works with `dir="rtl"` |
 | `sticky` | Cell, ColumnHeader, RowHeader | unset | Pins one `start` or `end` edge cell; match the same edge across rows |
 | `sortDirection` | ColumnHeader | `none` | `none`, `ascending`, `descending`; explicit direction owns `aria-sort`, otherwise native `aria-sort` passes through |
@@ -84,22 +84,22 @@ Every part accepts its native element attributes, `style`, `className` and ref.
 
 Sortable headings use the full cell as the button target. Unsorted headings show paired arrows; the applied order uses one arrow with stronger ink. Keep headings readable with native column widths and a bounded scroll container. Fixed-layout sortable headings wrap within their assigned columns. Reserve a compact checkbox column, align numeric headings with their values, and keep row action labels short while supplying record-specific accessible names. The sorting example places its title, instructions and selection count outside scrolling data, with visible text explaining unavailable selection.
 
-Sort a copy of your data or request server ordering. Keep the column and direction together; reset other headers to `none` so only one header announces an active sort. For server requests, handle stale responses in your app, keep applied order authoritative, set `sortDisabled` while pending, and announce progress through a status message outside an `aria-busy` body. Table does not mutate or fetch records. It does not implement multiple simultaneous sort keys.
+Sort a copy of your data or request server ordering. Keep the column and direction together; reset other headers to `none` so only one header announces an active sort. For server requests, handle stale responses in your app, keep applied order authoritative, set `sortDisabled` while pending, and announce progress through a status message outside an `aria-busy` body. `Table` does not mutate or fetch records. It does not implement multiple simultaneous sort keys.
 
 Keep selection by stable ID rather than visible row index. Define whether select-all covers the current page, filtered results or all records; label that scope explicitly. Compute mixed/all state from eligible rows only, exclude disabled rows, and disable select-all when no rows are eligible. Decide how removed records and page changes affect selection. `Table.Row selected` provides styling; selection controls own the accessible state. Row actions have their own names and normal Tab order, and do not toggle selection implicitly.
 
 ### Layout and feedback
 
-Place the table inside `Table.ScrollContainer` for horizontal overflow or a bounded vertical viewport. Its region is keyboard focusable; `maxHeight` limits height. On focus, the React container reveals controls hidden beneath sticky headers or pinned edges without moving keyboard focus. Keep enough free viewport space for the action; a pinned column wider than the viewport cannot expose adjacent cells. Supply a readable minimum table width with `style` when columns should scroll rather than wrap. A table can also render directly when page scrolling is sufficient. To keep the table title fixed on both scroll axes, render a Heading outside ScrollContainer and name the table through `aria-labelledby`, as in Dense and sticky. Native Table.Caption remains part of the scrollable table. Column headings stay fixed vertically with stickyHeader and scroll horizontally with their data columns.
+Place the table inside `Table.ScrollContainer` for horizontal overflow or a bounded vertical viewport. Its region is keyboard focusable; `maxHeight` limits height. On focus, the React container reveals controls hidden beneath sticky headers or pinned edges without moving keyboard focus. Keep enough free viewport space for the action; a pinned column wider than the viewport cannot expose adjacent cells. In auto layout, headings and cells keep whole words, so a table narrower than its longest words scrolls instead of breaking them; supply a minimum table width with `style` when columns need more room. Fixed layout breaks long words within its assigned columns. A table can also render directly when page scrolling is sufficient. To keep the table title fixed on both scroll axes, render a `Heading` outside `ScrollContainer` and name the table through `aria-labelledby`, as in Dense and sticky. Native `Table.Caption` remains part of the scrollable table. Column headings stay fixed vertically with `stickyHeader` and scroll horizontally with their data columns.
 
-Sticky edges support one cell on each edge. For several pinned columns, calculate non-overlapping offsets in your own styles; Table does not assign column offsets. Keep sufficient viewport space for unpinned cells. Header/body column widths must match. Set `dir="rtl"` on the application or ScrollContainer as well as the table when the scroll direction should follow RTL; the stories expose a direction control. Nested tables keep their own density and section surfaces. Native `colSpan`, `rowSpan`, `scope="colgroup"` and explicit `id`/`headers` relationships support grouped headers. Sticky and selected cell backgrounds stay opaque in both themes; restyled background tokens must remain opaque.
+Sticky edges support one cell on each edge. For several pinned columns, calculate non-overlapping offsets in your own styles; `Table` does not assign column offsets. Keep sufficient viewport space for unpinned cells. Header/body column widths must match. Set `dir="rtl"` on the application or ScrollContainer as well as the table when the scroll direction should follow RTL; the stories expose a direction control. Nested tables keep their own density and section surfaces. Native `colSpan`, `rowSpan`, `scope="colgroup"` and explicit `id`/`headers` relationships support grouped headers. Sticky and selected cell backgrounds stay opaque in both themes; restyled background tokens must remain opaque.
 
-Render empty or error feedback in a row containing a `Table.Cell colSpan={columnCount}`; supply retry as a named Button if appropriate. Use a separate status for asynchronous updates. Table preserves semantic HTML and ordinary Tab navigation; arrow-key cell navigation, pagination, filtering, virtualization and record management remain app-owned. For very large sets, paginate in your app rather than assuming all rows are virtualized.
+Render empty or error feedback in a row containing a `Table.Cell colSpan={columnCount}`; supply retry as a named `Button` if appropriate. Use a separate status for asynchronous updates. `Table` preserves semantic HTML and ordinary Tab navigation; arrow-key cell navigation, pagination, filtering, virtualization and record management remain app-owned. For very large sets, paginate in your app rather than assuming all rows are virtualized.
 
 Adjust `--kb-table-cell-padding-block`, `--kb-table-cell-padding-inline`, `--kb-table-dense-padding-block`, `--kb-table-background`, `--kb-table-header-background`, `--kb-table-selected-background`, `--kb-table-border`, `--kb-table-radius` and `--kb-table-sort-target` through normal CSS. Keep focus visible and dense action targets usable. See [accessibility verification](../../../../docs/guides/accessibility.md) for manual keyboard, screen-reader, zoom, spacing and contrast checks. Automated stories do not establish screen-reader interoperability or page conformance.
 
 ## Related components
 
-Use [DescriptionList](DescriptionList.md) for labeled facts about one record and [CollectionList](CollectionList.md) with [CollectionRow](CollectionRow.md) for records with variable details. The [Structured data guide](../../../../docs/guides/structured-data.md) compares these choices.
+Use [`DescriptionList`](DescriptionList.md) for labeled facts about one record and [`CollectionList`](CollectionList.md) with [`CollectionRow`](CollectionRow.md) for records with variable details. The [Structured data guide](../../../../docs/guides/structured-data.md) compares these choices.
 
-Use [Checkbox](Checkbox.md) for independent selection, [Menu](Menu.md) for overflow actions, [Button](Button.md) for immediate actions, and [Status](Status.md) for meaningful asynchronous feedback. Use [Grid](Grid.md) for visual page layout rather than tabular relationships.
+Use [`Checkbox`](Checkbox.md) for independent selection, [`Menu`](Menu.md) for overflow actions, [`Button`](Button.md) for immediate actions, and [`Status`](Status.md) for meaningful asynchronous feedback. Use [`Grid`](Grid.md) for visual page layout rather than tabular relationships.

package/docs/components/Tabs.md

@@ -1,6 +1,6 @@
 # Tabs
 
-Switch between peer panels within one page. Use links for navigation to another URL and RadioGroup for a single form choice.
+Switch between peer panels within one page. Use links for navigation to another URL and `RadioGroup` for a single form choice.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-tabs--docs)
 
@@ -31,7 +31,7 @@ export function Example() {
 - [Vertical settings](https://kbui.kcb.pro/storybook/?path=/story/components-tabs--vertical): Up/Down navigation beside settings content.
 - [Retained settings draft](https://kbui.kcb.pro/storybook/?path=/story/components-tabs--retained-draft): Manual activation retains an input while its panel is hidden.
 
-- [Nested panels](https://kbui.kcb.pro/storybook/?path=/story/components-tabs--nested): Each Tabs root owns its orientation, density and variant.
+- [Nested panels](https://kbui.kcb.pro/storybook/?path=/story/components-tabs--nested): Each `Tabs` root owns its orientation, density and variant.
 
 ## Reference
 
@@ -43,7 +43,7 @@ export function Example() {
 | `Tabs.Indicator` | Optional explicit active indicator inside the list |
 | `Tabs.Panel` | Content associated with a matching trigger |
 
-| Tabs prop | Type | Default | Purpose |
+| `Tabs` prop | Type | Default | Purpose |
 | --- | --- | --- | --- |
 | `value` | `string \| number \| null` | — | Controlled selection; null selects no panel |
 | `defaultValue` | `string \| number \| null` | First enabled tab | Initial uncontrolled selection; null selects none |
@@ -52,7 +52,7 @@ export function Example() {
 | `variant` | `"line" \| "pill"` | `"line"` | Underline or raised active surface |
 | `size` | `"sm" \| "md"` | `"md"` | Trigger density |
 | `className` | `string` | — | Root class |
-| `classNames` | `ClassNames<TabsClassKey>` | — | root, list, tab, tabIcon, tabLabel, tabBadge, indicator, panel |
+| `classNames` | `ClassNames<TabsClassKey>` | — | root, list, tab, `tabIcon`, `tabLabel`, `tabBadge`, indicator, panel |
 
 | Part prop | Type | Default | Purpose |
 | --- | --- | --- | --- |
@@ -66,24 +66,24 @@ export function Example() {
 | `Tabs.Panel.value` | `string \| number` | Required | Matching trigger value |
 | `Tabs.Panel.keepMounted` | `boolean` | `false` | Retain hidden DOM and local draft state |
 
-All parts forward refs, native element props and Base UI composition props; `className` accepts a string. Keep triggers and panels inside their Tabs root. Put an explicit indicator directly inside Tabs.List, or set showIndicator to false when supplying a custom composition. Use unique values within each root and avoid interactive elements inside tab labels or badges.
+All parts forward refs, native element props and Base UI composition props; `className` accepts a string. Keep triggers and panels inside their `Tabs` root. Put an explicit indicator directly inside `Tabs.List`, or set `showIndicator` to false when supplying a custom composition. Use unique values within each root and avoid interactive elements inside tab labels or badges.
 
 ## Selection and focus
 
 Base UI owns selection, tab/panel relationships and roving focus. Tab enters the selected trigger; Left/Right moves horizontal focus, Up/Down moves vertical focus, and Home/End reaches the first/last trigger. Disabled tabs can receive arrow-key focus but cannot be selected. Automatic activation selects enabled tabs while moving; manual activation requires Enter or Space. Controlled values change only when the parent updates them. A null value selects no tab.
 
-Uncontrolled roots recover to an enabled tab when the selected tab is removed or disabled, reporting the reason through onValueChange. Controlled recovery belongs to the parent. User selection can be cancelled through details.cancel(); automatic fallback cannot. Applications own fetching, loading feedback and content availability. Prefer manual activation for panels that require loading.
+Uncontrolled roots recover to an enabled tab when the selected tab is removed or disabled, reporting the reason through `onValueChange`. Controlled recovery belongs to the parent. User selection can be cancelled through details.cancel(); automatic fallback cannot. Applications own fetching, loading feedback and content availability. Prefer manual activation for panels that require loading.
 
-Inactive panels unmount by default. keepMounted preserves their DOM and draft state while hiding them from reading and keyboard navigation; hidden components can still run effects. Default values must match a tab when selecting a particular initial panel.
+Inactive panels unmount by default. `keepMounted` preserves their DOM and draft state while hiding them from reading and keyboard navigation; hidden components can still run effects. Default values must match a tab when selecting a particular initial panel.
 
 ## Styling and accessibility
 
-Each part receives its nearest root’s `data-variant`, `data-size` and `data-orientation`, so nested roots retain independent styling. Use the documented classes and component tokens: --kb-tabs-radius, --kb-tabs-list-padding, --kb-tabs-tab-height-sm, --kb-tabs-tab-height-md, --kb-tabs-indicator-thickness and --kb-tabs-panel-padding. The tab list scrolls horizontally when labels exceed available width. Vertical layouts need enough room for labels and content; applications can choose horizontal orientation at narrow widths.
+Each part receives its nearest root’s `data-variant`, `data-size` and `data-orientation`, so nested roots retain independent styling. Use the documented classes and component tokens: `--kb-tabs-radius`, `--kb-tabs-list-padding`, `--kb-tabs-tab-height-sm`, `--kb-tabs-tab-height-md`, `--kb-tabs-indicator-thickness` and `--kb-tabs-panel-padding`. The tab list scrolls horizontally when labels exceed available width. Vertical tabs place the list beside the panel from 48rem of their own width; at narrower widths, the panel moves beneath the list.
 
 For right-to-left interfaces, combine HTML `dir="rtl"` with Base UI `DirectionProvider direction="rtl"` so keyboard direction matches layout.
 
-Name Tabs.List with aria-label or aria-labelledby. Keep tab labels descriptive and use associated panels for peer views. Verify selected versus focused states, hidden panel controls, long labels, both themes, forced colors and enlarged text. Browser automation covers tested keyboard and accessibility fixtures; manual screen-reader and browser-zoom checks remain pending. See [shared verification](../../../../docs/guides/accessibility.md) and the informative [WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+Name `Tabs.List` with `aria-label` or `aria-labelledby`. Keep tab labels descriptive and use associated panels for peer views. Verify selected versus focused states, hidden panel controls, long labels, both themes, forced colors and enlarged text. Browser automation covers tested keyboard and accessibility fixtures; manual screen-reader and browser-zoom checks remain pending. See [shared verification](../../../../docs/guides/accessibility.md) and the informative [WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
 
 ## Related components
 
-Use [RadioGroup](RadioGroup.md) for a form choice and [Toolbar](Toolbar.md) for grouped actions.
+Use [`RadioGroup`](RadioGroup.md) for a form choice and [`Toolbar`](Toolbar.md) for grouped actions.

package/docs/components/Text.md

@@ -29,8 +29,8 @@ export function Example() {
 | `tone`             | `default` \| `muted`   | `default` | Primary ink or readable secondary ink                 |
 | `className`, `ref` | Native element props   | unset     | Ref type follows chosen element                       |
 
-Body line height is 1.6; block content is bounded to 65ch by `--kb-text-measure`. Text has no margin. Inline spans keep natural flow. Use native `strong` and `em` for meaningful emphasis. Do not nest paragraphs or place block children inside the default paragraph.
+Body text has a line height of 1.6 and a 65ch line-length limit set by `--kb-text-measure`. `Text` adds no margin. Inline spans stay in the flow of the sentence. Use native `<strong>` and `<em>` for emphasis. Keep paragraphs and other block elements outside the default paragraph.
 
 ## Related components
 
-Use [Heading](Heading.md) for hierarchy, [Link](Link.md) for navigation, and [Code](Code.md) for literal code.
+Use [`Heading`](Heading.md) for hierarchy, [`Link`](Link.md) for navigation, and [`Code`](Code.md) for literal code.

package/docs/components/Textarea.md

@@ -1,6 +1,6 @@
 # Textarea
 
-Use Textarea for multiline notes, summaries, or configuration payloads. It pairs a native textarea with a persistent label, optional help text, and validation feedback.
+Use `Textarea` for multiline notes, summaries, or configuration payloads. It pairs a native `textarea` with a persistent label, optional help text, and validation feedback.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-textarea--docs)
 
@@ -35,13 +35,13 @@ export function Example() {
 | `visuallyHidden` | `boolean`                                                      | `false`      | Hides the label visually while keeping its accessible name |
 | `description`    | `string`                                                       | unset        | Supporting help text below the control                     |
 | `error`          | `string`                                                       | unset        | Validation message; marks the control invalid              |
-| `rows`           | `number`                                                       | `4`          | Initial visible line count on the native textarea          |
+| `rows`           | `number`                                                       | `4`          | Initial visible line count on the native `textarea`          |
 | `resize`         | `"vertical" \| "none" \| "both"`                               | `"vertical"` | Controls user drag-resizing axis                           |
 | `onValueChange`  | `(value: string) => void`                                      | unset        | Called with the next string value on change                |
 | `classNames`     | `ClassNames<"label" \| "control" \| "description" \| "error">` | unset        | Classes for inner parts                                    |
 
-Other native textarea props (`value`, `defaultValue`, `onChange`, `placeholder`, `disabled`, `readOnly`, `required`, `name`, `form`, `ref`) pass through to the `<textarea>` element. Adjust minimum height and padding with `--kb-textarea-min-height`, `--kb-textarea-padding-block`, and `--kb-textarea-padding-inline`.
+Other native `textarea` props (`value`, `defaultValue`, `onChange`, `placeholder`, `disabled`, `readOnly`, `required`, `name`, `form`, `ref`) pass through to the `<textarea>` element. Adjust minimum height and padding with `--kb-textarea-min-height`, `--kb-textarea-padding-block`, and `--kb-textarea-padding-inline`.
 
 ## Related components
 
-Use [Input](Input.md) for a single-line value and [Fieldset](Fieldset.md) to group related answers.
+Use [`Input`](Input.md) for a single-line value and [`Fieldset`](Fieldset.md) to group related answers.

package/docs/components/Thumbnail.md

@@ -1,6 +1,6 @@
 # Thumbnail
 
-Pair stable image frames with visible titles and metadata for products, studies and attachments. Compose figures into responsive collections with Grid.
+Pair stable image frames with visible titles and metadata for products, studies and attachments. Compose figures into responsive collections with `Grid`.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-thumbnail--docs)
 
@@ -42,7 +42,7 @@ export function Example() {
 
 - [Products](https://kbui.kcb.pro/storybook/?path=/story/components-thumbnail--products): Responsive product cards and absent photography.
 - [Attachments](https://kbui.kcb.pro/storybook/?path=/story/components-thumbnail--attachments): Persistent filenames, formats and file sizes.
-- [Gallery](https://kbui.kcb.pro/storybook/?path=/story/components-thumbnail--gallery): Keyboard-operable Dialog inspection and focus return.
+- [Gallery](https://kbui.kcb.pro/storybook/?path=/story/components-thumbnail--gallery): Keyboard-operable `Dialog` inspection and focus return.
 
 ## Reference
 
@@ -50,17 +50,17 @@ export function Example() {
 | --- | --- | --- | --- |
 | `alt` | `string` | required | Meaningful visual alternative; empty when decorative |
 | `src` | `string` | unset | Preview source |
-| `ratio`, `fit`, `position`, `fallback` | Image props | Image defaults | Framing and non-interactive fallback |
-| `caption` | `ReactNode` | unset | Visible figure title; may contain Link, Button or Dialog.Trigger |
+| `ratio`, `fit`, `position`, `fallback` | `Image` props | `Image` defaults | Framing and non-interactive fallback |
+| `caption` | `ReactNode` | unset | Visible figure title; may contain `Link`, `Button` or `Dialog.Trigger` |
 | `description` | `ReactNode` | unset | Persistent supporting text such as format and size |
-| `imageProps` | remaining Image props | unset | Responsive source/loading attributes, callbacks, frame ref, style and Image slots |
+| `imageProps` | remaining `Image` props | unset | Responsive source/loading attributes, callbacks, frame ref, style and `Image` slots |
 | `classNames` | keyed classes | unset | `root`, `media`, `caption`, `title`, `description` |
 | `ref` | `Ref<HTMLElement>` | unset | Native figure; remaining figure props apply here |
 
 A caption names the figure through `aria-labelledby`; caller naming attributes take precedence. Description is visible metadata within `figcaption`. Without either, no caption element is rendered. Figure and image remain non-interactive; caption actions own their native keyboard behavior. The component never infers file type, size or download policy from the URL.
 
-Use `Grid as="ul"` with `li` children for a gallery in reading order. A named Dialog trigger in the caption supports enlarged inspection, Escape dismissal and focus return through Dialog. The gallery recipe provides no carousel, arrow-key selection, image editor or upload. See [media recipes](../../../../docs/guides/media-and-identity.md) for a complete implementation.
+For a page of previews, put each `Thumbnail` in a [`Gallery`](Gallery.md) item. A named `Dialog` trigger in the caption supports enlarged inspection, Escape dismissal and focus return through `Dialog`. `Gallery` provides no carousel, arrow-key selection, image editor or upload. See [media recipes](../../../../docs/guides/media-and-identity.md#build-a-gallery-in-reading-order) for a complete implementation.
 
 ## Related components
 
-Use [Image](Image.md) for an image alone, [Avatar](Avatar.md) for people, [Grid](Grid.md) for layout, and [Dialog](Dialog.md) for focused media inspection.
+Use [`Image`](Image.md) for an image alone, [`Avatar`](Avatar.md) for people, [`Grid`](Grid.md) for layout, and [`Dialog`](Dialog.md) for focused media inspection.