@kb.ui/react 0.11.0 → 0.12.1

package/docs/components/Heading.md

@@ -23,7 +23,7 @@ export function Example() {
 
 - [Document hierarchy](https://kbui.kcb.pro/storybook/?path=/story/components-heading--hierarchy): Compare semantic heading ranks.
 - [Visual hierarchy](https://kbui.kcb.pro/storybook/?path=/story/components-heading--sizes): Compare sizes separately from heading rank.
-- [A complete article](https://kbui.kcb.pro/storybook/?path=/story/components-heading--article): Combine Heading, Text, Link, and Code.
+- [A complete article](https://kbui.kcb.pro/storybook/?path=/story/components-heading--article): Combine `Heading`, `Text`, `Link`, and `Code`.
 
 ## Reference
 
@@ -33,8 +33,8 @@ export function Example() {
 | `size`             | `sm` \| `md` \| `lg` \| `xl` \| `display` | From level | Levels 1–6 map to xl, lg, md, sm, sm, sm; display is an explicit hero size |
 | `className`, `ref` | Native heading props                      | unset      | Classes merge; ref targets native heading                                  |
 
-Use one page title and nest section ranks without skipping levels. Adjust `size` for context without changing the outline. Headings have no margin; use Grid or parent layout for spacing. See [Typography](https://github.com/KhallilB/kbui/blob/main/docs/guides/typography.md) for composition, CSS recipes and accessibility guidance.
+Use one page title and nest section ranks without skipping levels. Adjust `size` for context without changing the outline. Headings have no margin; use `Grid` or parent layout for spacing. See [Typography](https://github.com/KhallilB/kbui/blob/main/docs/guides/typography.md) for composition, CSS recipes and accessibility guidance.
 
 ## Related components
 
-Pair with [Text](Text.md), [Link](Link.md), and [Code](Code.md) for readable document content.
+Pair with [`Text`](Text.md), [`Link`](Link.md), and [`Code`](Code.md) for readable document content.

package/docs/components/Image.md

@@ -53,10 +53,10 @@ export function Example() {
 
 The frame exposes `data-state="empty|loading|loaded|error"`, `data-ratio`, and `data-fit`. The internal native image is hidden from assistive technology; the outer image role owns the alternative across all states. `aria-label`, `aria-labelledby`, and `aria-describedby` belong to the frame. An empty `alt` always hides the complete image.
 
-`auto` uses positive width and height; without both, it falls back to the landscape ratio. The image remains within the reserved frame, including after failure. A caller `style.aspectRatio` overrides framing. Image fetches follow native browser behavior; the component adds no timeout, retry loop, cache, upload or URL policy. A new source starts a fresh request; to retry the same URL intentionally, change the component key.
+`auto` uses positive width and height; without both, it falls back to the landscape ratio. The image remains within the reserved frame, including after failure. A caller `style.aspectRatio` overrides framing. `Image` fetches follow native browser behavior; the component adds no timeout, retry loop, cache, upload or URL policy. A new source starts a fresh request; to retry the same URL intentionally, change the component key.
 
-Fallback content is visual-only and must contain no controls. Place a named replacement/retry Button and meaningful error text outside the frame. Use [media recipes](../../../../docs/guides/media-and-identity.md) for responsive sources, localized errors and CSS-only markup.
+Fallback content is visual-only and must contain no controls. Place a named replacement/retry `Button` and meaningful error text outside the frame. Use [media recipes](../../../../docs/guides/media-and-identity.md) for responsive sources, localized errors and CSS-only markup.
 
 ## Related components
 
-Use [Avatar](Avatar.md) for fixed-size identity, [Thumbnail](Thumbnail.md) for captions and metadata, and [Grid](Grid.md) for responsive collections.
+Use [`Avatar`](Avatar.md) for fixed-size identity, [`Thumbnail`](Thumbnail.md) for captions and metadata, and [`Grid`](Grid.md) for responsive collections.

package/docs/components/Inline.md

@@ -1,6 +1,6 @@
 # Inline
 
-Wrapping row for independent content or controls. Adds no toolbar role or keyboard handling; controls retain native tab order. Native props and matching ref pass through.
+Use `Inline` for a row of content or controls that wraps when space runs out. Each control keeps its normal Tab stop; the row adds no toolbar role or keyboard handling. 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-inline--docs)
 
@@ -35,8 +35,8 @@ export function Example() {
 | `align`   | `start` `center` `end` `baseline` `stretch`    | `center` |
 | `justify` | `start` `center` `end` `between`               | `start`  |
 
-Non-default generic native elements require an explicit `as`. Lists retain markers and native list spacing. Use li children. Choose Toolbar when actions require its coordinated arrow-key model. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md).
+Set `as` explicitly when using an element other than the default. Lists keep their markers and outer spacing; `gap` controls spacing between `<li>` children. Choose `Toolbar` when actions need arrow-key navigation. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md).
 
 ## Related components
 
-Use [Toolbar](Toolbar.md) when actions need coordinated arrow-key navigation. Use [Grid](Grid.md) when items need shared columns.
+Use [`Toolbar`](Toolbar.md) when actions need coordinated arrow-key navigation. Use [`Stack`](Stack.md) for vertical flow and [`Grid`](Grid.md) when items need shared columns.

package/docs/components/Input.md

@@ -1,6 +1,6 @@
 # Input
 
-Use Input for text entry. It keeps the label, help text, and error message together, and has space for icons or actions at either end.
+Use `Input` for text entry. It keeps the label, help text, and error message together, and has space for icons or actions at either end.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-input--docs)
 
@@ -33,7 +33,7 @@ export function Example() {
 | `size`                        | `"sm" \| "md" \| "lg"` | `"md"`   | Field height. Replaces the native `size` attribute            |
 | `className`                   | `string`               |          | Applied to the wrapper, not the input element                 |
 
-Other native input props, including `value` and `defaultValue`, pass through to the input. Base UI's `onValueChange` is also supported.
+Other native `input` props, including `value` and `defaultValue`, pass through to the input. Base UI's `onValueChange` is also supported.
 
 ## Search composition
 
@@ -79,4 +79,4 @@ The field label names the input. Give each action its own accessible name, and h
 
 ## Related components
 
-Use [Textarea](Textarea.md) for multiline answers, [NumberField](NumberField.md) for numeric stepping, and [Combobox](Combobox.md) for a searchable choice from existing values.
+Use [`Textarea`](Textarea.md) for multiline answers, [`NumberField`](NumberField.md) for numeric stepping, and [`Combobox`](Combobox.md) for a searchable choice from existing values.

package/docs/components/Link.md

@@ -28,7 +28,7 @@ export function Example() {
 | `target`, `rel`, `download`, `aria-current` | Native anchor props | unset    | Passed through without rewriting |
 | `className`, `ref`                          | Native anchor props | unset    | Ref targets anchor               |
 
-Use descriptive link text. Use Button for an action. Links inherit surrounding type size; Tab focuses, Enter follows, and Space retains native behavior. Callers own new-tab wording and target/rel policy. No disabled link is provided. Color, underline and focus must remain visible.
+Use descriptive link text. Use `Button` for an action. Links inherit surrounding type size; Tab focuses, Enter follows, and Space retains native behavior. Callers own new-tab wording and target/rel policy. No disabled link is provided. Color, underline and focus must remain visible.
 
 ### Router links
 
@@ -49,4 +49,4 @@ const AppLink = ({ href, ...props }: LinkProps) => <RouterLink to={href} {...pro
 
 ## Related components
 
-Use [Button](Button.md) for an action and [Card](Card.md) to group content around a destination.
+Use [`Button`](Button.md) for an action and [`Card`](Card.md) to group content around a destination.

package/docs/components/Menu.md

@@ -1,6 +1,6 @@
 # Menu
 
-Offer a short list of actions without leaving the current context. Use a Select when people are choosing a saved field value.
+Offer a short list of actions without leaving the current context. Use a `Select` when people are choosing a saved field value.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-menu--docs)
 
@@ -25,14 +25,14 @@ export function Example() {
 ## More examples
 
 - [Keyboard interaction](https://kbui.kcb.pro/storybook/?path=/story/components-menu--default): Try the trigger, arrow keys, and dismissal.
-- [A themed popup](https://kbui.kcb.pro/storybook/?path=/story/components-menu--nested-theme): Keep a portaled popup within its intended theme.
+- [A themed popup](https://kbui.kcb.pro/storybook/?path=/story/components-menu--nested-theme): Check that the popup uses its parent theme.
 
 ## Reference
 
 | Part             | Props and responsibility                                                                 |
 | ---------------- | ---------------------------------------------------------------------------------------- |
-| `Menu`           | Root; use open/defaultOpen and onOpenChange when your app controls visibility            |
-| `Menu.Trigger`   | Named trigger; render a Button for shared styling                                        |
+| `Menu`           | Root; use open/`defaultOpen` and `onOpenChange` when your app controls visibility            |
+| `Menu.Trigger`   | Named trigger; render a `Button` for shared styling                                        |
 | `Menu.Content`   | Popup; side defaults to bottom, align to start; container chooses the themed portal host |
 | `Menu.Item`      | Action text and click handler; disabled prevents selection                               |
 | `Menu.Separator` | Divides related groups without adding a focus stop                                       |
@@ -41,4 +41,4 @@ Name the trigger, keep action labels specific, and retain the default arrow-key
 
 ## Related components
 
-Use [Select](Select.md) for a saved field value and [Dialog](Dialog.md) for a focused task with content or fields.
+Use [`Select`](Select.md) for a saved field value and [`Dialog`](Dialog.md) for a focused task with content or fields.

package/docs/components/MultiSelect.md

@@ -1,6 +1,6 @@
 # MultiSelect
 
-Use MultiSelect when people need to search a longer list and keep multiple selections visible as removable chips. Selected values render inside a named chip toolbar with keyboard arrow/Backspace/Delete support and per-chip remove buttons. Choosing or deselecting an option keeps the popup open and preserves the filter. Escape, an outside click, or the toggle closes it.
+Use `MultiSelect` when people need to search a longer list and keep multiple selections visible as removable chips. Selected values render inside a named chip toolbar with keyboard arrow/Backspace/Delete support and per-chip remove buttons. Choosing or deselecting an option keeps the popup open and preserves the filter. Escape, an outside click, or the toggle closes it.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-multiselect--docs)
 
@@ -56,4 +56,4 @@ export function ScopeMultiSelect() {
 
 ## Related components
 
-Use [Combobox](Combobox.md) for one searchable choice and [Checkbox](Checkbox.md) for independent choices that should remain visible.
+Use [`Combobox`](Combobox.md) for one searchable choice and [`Checkbox`](Checkbox.md) for independent choices that should remain visible.

package/docs/components/NumberField.md

@@ -1,6 +1,6 @@
 # NumberField
 
-Use NumberField for quantities people can type or adjust with step buttons. Your app sets the range and validates the value. See [Numeric fields](https://github.com/KhallilB/kbui/blob/main/docs/guides/number-fields.md) for examples, keyboard behavior, and styling. Available since v0.6.0.
+Use `NumberField` for quantities people can type or adjust with step buttons. Your app sets the range and validates the value. See [Numeric fields](https://github.com/KhallilB/kbui/blob/main/docs/guides/number-fields.md) for examples, keyboard behavior, and styling. Available since v0.6.0.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-numberfield--docs)
 
@@ -31,11 +31,11 @@ export function Example() {
 }
 ```
 
-The field can be empty (`null`), and directly typed values remain available for your app to validate. The example validates a whole-number quantity; `min`, `max`, and `step` govern stepping. See [numeric-field state and interaction](https://github.com/KhallilB/kbui/blob/main/docs/guides/number-fields.md#state-and-interaction) for locale and draft behavior.
+The field can be empty (`null`), and directly typed values remain available for your app to validate. The example validates a whole-number quantity; `min`, `max`, and `step` control the step buttons and stepping keys. See [numeric-field state and interaction](https://github.com/KhallilB/kbui/blob/main/docs/guides/number-fields.md#state-and-interaction) for locale and draft behavior.
 
 ## More examples
 
-- [An unanswered quantity](https://kbui.kcb.pro/storybook/?path=/story/components-numberfield--empty): Represent an empty field with null.
+- [An unanswered quantity](https://kbui.kcb.pro/storybook/?path=/story/components-numberfield--empty): Use `null` for an empty field.
 - [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-numberfield--invalid): Explain a value that needs correction.
 - [Fractional steps](https://kbui.kcb.pro/storybook/?path=/story/components-numberfield--fractional): Compare non-integer increments.
 
@@ -58,8 +58,8 @@ The field can be empty (`null`), and directly typed values remain available for
 | `inputRef`, `inputProps`                        | input ref / native props          | unset                     | Visible input access and supported native event or ARIA extensions      |
 | `className`, `groupClassName`, `inputClassName` | `string`                          | unset                     | Classes for root, step group, and input                                 |
 
-Native div props and the root ref pass through to the wrapper. Any `aria-describedby` values from the root and `inputProps` are added after the help and error IDs. Use the explicit NumberField props for the input’s value, type, disabled/read-only state, name, required state, and ref; `inputProps` cannot override those. Custom event handlers can prevent defaults, so take care to preserve keyboard behavior.
+Native `<div>` props and the root `ref` apply to the wrapper. Root and `inputProps` descriptions follow the help and error IDs in `aria-describedby`. Set the input’s value, type, disabled/read-only state, name, required state and ref through `NumberField` props; `inputProps` cannot override them. Custom event handlers can prevent default actions, so check keyboard behavior after adding them.
 
 ## Related components
 
-Use [Input](Input.md) for text or identifiers whose leading zeroes and exact characters must be preserved.
+Use [`Input`](Input.md) for text or identifiers whose leading zeroes and exact characters must be preserved.

package/docs/components/PageHeader.md

@@ -0,0 +1,68 @@
+# PageHeader
+
+Open a screen with its title, short context, status and page-level actions. Use one per screen, at the top of `main`.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-pageheader--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Badge, Button, Link, PageHeader } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <main>
+      <PageHeader
+        navigation={<Link href="/orders">← All orders</Link>}
+        eyebrow="Order"
+        title="#10482"
+        meta={<Badge tone="success">Paid</Badge>}
+        description="Placed on 12 October 2026 by Ana Ruiz · 3 items · €184.00"
+        actions={
+          <>
+            <Button variant="secondary">Refund</Button>
+            <Button>Fulfil order</Button>
+          </>
+        }
+      />
+    </main>
+  );
+}
+```
+
+The title renders as an `h1`. Actions sit at the end of the title row. Below 40rem of header width they take their own row under the heading, still end-aligned; wider headers move them below only when the heading's minimum width no longer fits.
+
+## More examples
+
+- [Detail with status](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--detail-with-status): Add a back link, an object-type eyebrow and status badges to a record screen.
+- [Breadcrumbs](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--breadcrumbs): Place a labelled breadcrumb `nav` in `navigation` for nested settings.
+- [With tabs](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--with-tabs): Put a `Tabs.List` in the body and draw a divider above the panels.
+- [Sizes](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--sizes): Choose `sm` for dense app shells and `lg` for landing screens.
+- [Narrow wrap](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--narrow-wrap): See long titles wrap and actions move below the heading at 320 pixels.
+
+## Reference
+
+| Prop           | Type            | Default  | Notes                                                                                                                 |
+| -------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `title`        | `ReactNode`     | required | Page name, rendered as the heading                                                                                    |
+| `description`  | `ReactNode`     | unset    | One or two sentences of context below the title                                                                       |
+| `eyebrow`      | `ReactNode`     | unset    | Short section or object-type label above the title                                                                    |
+| `navigation`   | `ReactNode`     | unset    | Back link or breadcrumb `nav` above the heading                                                                       |
+| `meta`         | `ReactNode`     | unset    | `Status` badges or metadata beside the title; kept out of the heading's accessible name                                 |
+| `actions`      | `ReactNode`     | unset    | Page-level buttons or links; end-aligned, wrapping below the heading when narrow                                      |
+| `headingLevel` | `1` / `2` / `3` | `1`      | Heading rank; lower it only when the header introduces a region below an existing `h1`                                |
+| `size`         | `sm` / `md` / `lg` | `md`  | Title scale: `sm` uses the `h2` size, `md` the `h1` size, `lg` the display size                                       |
+| `divider`      | `boolean`       | `false`  | Draws a rule below the header                                                                                         |
+| `children`     | `ReactNode`     | unset    | Header body below the title row, such as a `Tabs.List` or filters                                                     |
+| `classNames`   | keyed classes   | unset    | Style `navigation`, `main`, `heading`, `eyebrow`, `headline`, `title`, `meta`, `description`, `actions`, `body`       |
+
+The root is a `div`, not `header`. A `header` outside `main` or a sectioning element becomes a banner landmark and would compete with the site header. Other native `div` props pass through to the root.
+
+Keep one primary action. Put secondary actions before it and move rarely used actions into a [`Menu`](Menu.md).
+
+For breadcrumbs, use a labelled `nav` with an ordered list and mark the current item with `aria-current="page"`. Reset list-item margins when using flex layout with `gap`, allow the trail to wrap, and hide decorative separators from assistive technology. Links keep their normal Tab order. See the [breadcrumb example](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--breadcrumbs) and [WAI breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/).
+
+## Related components
+
+Use [`Heading`](Heading.md) for section titles inside the page, [`EmptyState`](EmptyState.md) when the page has no content yet, [`Toolbar`](Toolbar.md) for a dense group of controls that act on the content below, and [`Container`](Container.md) to set the page width the header shares with its content.

package/docs/components/Panel.md

@@ -1,6 +1,6 @@
 # Panel
 
-Use Panel for a section that needs a header, body, and actions. Its parts help keep those areas aligned. Give the section an accessible name with `aria-labelledby`, pointing to the heading in `Panel.Header`.
+Use `Panel` for a section that needs a header, body, and actions. Its parts help keep those areas aligned. Give the section an accessible name with `aria-labelledby`, pointing to the heading in `Panel.Header`.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-panel--docs)
 
@@ -30,6 +30,7 @@ export function Example() {
 - [Optional details](https://kbui.kcb.pro/storybook/?path=/story/components-panel--collapsible): Expand and collapse a section from its toggle.
 - [Section actions](https://kbui.kcb.pro/storybook/?path=/story/components-panel--toolbar): Group actions alongside the section heading.
 - [Nested sections](https://kbui.kcb.pro/storybook/?path=/story/components-panel--nested): Inspect depth and grouping inside a parent panel.
+- [Opaque surface](https://kbui.kcb.pro/storybook/?path=/story/components-panel--opaque): Compare a glass panel with one that drops the blur.
 
 ## Reference
 
@@ -53,7 +54,8 @@ export function Example() {
 | `tone`         | `quiet` / `default` / `sunken` / `active` / `critical` | `default`    | Changes the surface emphasis; pair state colors with explanatory text |
 | `rail`         | `none` / `accent` / `status`                           | `none`       | Accent stays the accent color; status follows the current tone        |
 | `density`      | `compact` / `standard`                                 | `standard`   | Changes padding without changing semantics                            |
-| `collapsible`  | `boolean`                                              | `false`      | Enables Panel.Toggle and collapsible body behavior                    |
+| `opaque`       | `boolean`                                              | `false`      | Solid fill with no backdrop filter, whatever the theme sets           |
+| `collapsible`  | `boolean`                                              | `false`      | Enables `Panel.Toggle` and collapsible body behavior                    |
 | `open`         | `boolean`                                              | uncontrolled | Current body visibility when collapsible is enabled                   |
 | `defaultOpen`  | `boolean`                                              | `false`      | Initial visibility for an uncontrolled collapsible panel              |
 | `onOpenChange` | `(open: boolean) => void`                              | unset        | Update open here when your app controls visibility                    |
@@ -62,6 +64,12 @@ export function Example() {
 
 For additional lighting, use `--kb-panel-sheen`, `--kb-panel-backdrop`, `--kb-panel-glow`, `--kb-panel-glow-active`, and `--kb-panel-glow-critical`. These effects stay off by default. Active and critical tones change the upper rim and glow colors. The rail follows the panel’s rounded corners.
 
+`opaque` turns off the theme’s glass for one panel: it drops `--kb-panel-backdrop` and paints the tone fill over the `--kb-panel-background-opaque` base. Use it under content that redraws often, such as a live terminal or log, where a backdrop blur costs memory and compositing work. It fills even a `quiet` panel. Nested panels keep their own glass; give each one that holds live content `opaque` too. Set `--kb-panel-background-opaque` in your theme to change the base; keep it a solid color that contrasts with `--kb-color-fg` in light and dark.
+
+```tsx
+<Panel opaque aria-labelledby="terminal-title">…</Panel>
+```
+
 ## Resizable panels
 
 Put `Panel.Handle` between two panels in a `Panel.Group` to let people resize them. The handle sizes the panel before it, as a percentage of the group; the panel after it takes the remaining space. Name each handle with `aria-label` or `aria-labelledby`. A column group needs a height.
@@ -80,7 +88,7 @@ The handle follows the window splitter pattern. Arrow keys along the group's dir
 
 ## Related components
 
-Use [Card](Card.md) for a self-contained item and [Grid](Grid.md) or [Split](Split.md) to arrange sections.
+Use [`Card`](Card.md) for a self-contained item and [`Grid`](Grid.md) or [`Split`](Split.md) to arrange sections.
 
 ## Resizing without dragging
 

package/docs/components/Popover.md

@@ -37,27 +37,27 @@ export function ViewOptions() {
 
 | Part / prop | Type | Default | Purpose |
 |---|---|---|---|
-| `Popover` | Base UI Popover root props | — | Groups parts without adding a DOM element. |
+| `Popover` | Base UI `Popover` root props | — | Groups parts without adding a DOM element. |
 | `open` / `defaultOpen` | `boolean` | `false` | Controlled or initial open state. |
 | `onOpenChange` | `(open, details) => void` | — | Requests opening/dismissal; supports `details.cancel()`. |
 | `modal` | `boolean` or `"trap-focus"` | `false` | Configures interaction containment. Include Close for modal focus containment and touch-screen-reader escape. |
-| `Popover.Trigger` | Base UI Popover trigger props | `button` | Supports Button composition, refs and native disabled. |
-| `Popover.Content` | Base UI Popover popup props | `div` | Portaled interactive popup with ref and native attributes. |
+| `Popover.Trigger` | Base UI `Popover` trigger props | `button` | Supports `Button` composition, refs and native disabled. |
+| `Popover.Content` | Base UI `Popover` popup props | `div` | Portaled interactive popup with ref and native attributes. |
 | `Content.title` / `description` | `ReactNode` | — | Adds associated Title and Description inside Header; omit when composing those parts. |
 | `Content.container` | Base UI portal container | `document.body` | Targets a stable theme host, including refs. |
 | `Content.side` / `align` | Base UI positioner values | `bottom` / `start` | Preferred placement; collision handling may adjust it. |
 | `Content.sideOffset` | Base UI side offset | `6` | Gap from trigger in CSS pixels. |
-| `Content.positionerProps` | Base UI positioner props | — | Advanced collision boundary/padding, offsets, custom anchor, styles and ref; excludes children, className, side, align and sideOffset. |
+| `Content.positionerProps` | Base UI positioner props | — | Advanced collision boundary/padding, offsets, custom anchor, styles and ref; excludes children, `className`, side, align and `sideOffset`. |
 | `Content.initialFocus` / `finalFocus` | Base UI focus target | Primitive defaults | Customize entry and return focus; supports refs and callbacks. |
 | `Content.className` | `string` | — | Additional popup class. |
 | `Content.classNames` | `{ positioner?: string }` | — | Additional class on positioning wrapper. |
-| `Popover.Title` / `Description` | Base UI naming part props | — | Compose accessible names and descriptions; accepts string className and refs. |
+| `Popover.Title` / `Description` | Base UI naming part props | — | Compose accessible names and descriptions; accepts string `className` and refs. |
 | `Popover.Header` / `Body` / `Footer` | Native `div` props and refs | `div` | Header and Footer stay outside Body scrolling. Body must be a direct Content child; Footer holds visible actions. |
 | `Popover.Close` | Base UI close props | `button` | Dismisses without performing an application action. |
 
-Name every popup with title, Title or aria-label. Include a visible Close action, especially for touch and modal usage. Escape closes the popup and restores focus; a non-modal outside press dismisses while allowing outside interaction. Default keyboard opening focuses the first tabbable control or the popup; touch opening can focus the popup to avoid launching a virtual keyboard. Keep required instructions available outside temporary content.
+Name every popup with title, Title or `aria-label`. Include a visible Close action, especially for touch and modal usage. Escape closes the popup and restores focus; a non-modal outside press dismisses while allowing outside interaction. Default keyboard opening focuses the first tabbable control or the popup; touch opening can focus the popup to avoid launching a virtual keyboard. Keep required instructions available outside temporary content.
 
-Keep popovers short: show the relevant controls and a visible Done/Close action together. Avoid artificial height caps, large descriptions or long lists of secondary content. Use Dialog, Drawer or inline Disclosure when a task needs more room.
+Keep popovers short: show the relevant controls and a visible Done/Close action together. Avoid artificial height caps, large descriptions or long lists of secondary content. Use `Dialog`, Drawer or inline `Disclosure` when a task needs more room.
 
 For constrained viewports, compose direct Header, Body and Footer children. Content title/description props create Header automatically. Only Body shrinks and scrolls; Footer actions and the heading stay visible. A long scrollable Body needs a name and `tabIndex={0}` for keyboard scrolling; keep essential instructions and actions outside it. The outer popup can still scroll as a fallback when enlarged header/footer content alone exceeds available space. The popup fits the positioning engine's available width/height. `positionerProps` retains Base UI collision and anchor configuration. Set `container` for nested themes and keep the host outside clipping/transformed ancestors when needed. See [theme hosts and portals](../../../../docs/guides/forms-and-overlays.md#theme-hosts-and-portals).
 
@@ -76,7 +76,7 @@ Choose one update model and explain it:
 
 The Default and Controlled stories implement these two models. Do not label a dismiss-only button Save, and do not silently commit a draft on outside dismissal. Keep asynchronous operations and error recovery application-owned.
 
-Test the actual embedding viewport. A portal escapes DOM clipping but cannot escape an iframe's viewport. Leave space around the trigger for the complete panel and its actions; a tiny host must offer a larger preview or compose Dialog/Drawer. Do not accept a Body that collapses to zero height while a field technically remains in the accessibility tree. Catalog previews reserve the popup footprint and open the real panel at mobile/desktop widths, including paired themes.
+Test the actual embedding viewport. A portal escapes DOM clipping but cannot escape an iframe's viewport. Leave space around the trigger for the complete panel and its actions; a tiny host must offer a larger preview or compose `Dialog`/Drawer. Do not accept a Body that collapses to zero height while a field technically remains in the accessibility tree. Catalog previews reserve the popup footprint and open the real panel at mobile/desktop widths, including paired themes.
 
 Follow the [Base UI focus/positioning contract](https://base-ui.com/react/components/popover) and [WAI non-modal dialog guidance](https://www.w3.org/TR/wai-aria-1.2/#dialog). For complex tasks on compact screens, use an explicit sheet/dialog composition and preserve its modal semantics rather than changing modes during an open interaction.
 
@@ -86,4 +86,4 @@ Run `bun run test:overlays` for Chromium, Firefox and WebKit checks in both them
 
 ## Related components
 
-Use [Tooltip](Tooltip.md) for brief non-interactive hints, [Menu](Menu.md) for action lists, [Disclosure](Disclosure.md) for inline details, and [Dialog](Dialog.md) for modal tasks and the documented drawer/confirmation patterns.
+Use [`Tooltip`](Tooltip.md) for brief non-interactive hints, [`Menu`](Menu.md) for action lists, [`Disclosure`](Disclosure.md) for inline details, and [`Dialog`](Dialog.md) for modal tasks and the documented drawer/confirmation patterns.

package/docs/components/Progress.md

@@ -34,4 +34,4 @@ The current value stays available to assistive technology. Your app owns task co
 
 ## Related components
 
-Use [Status](Status.md) for a textual state and [Stat](Stat.md) for a headline measure without completion semantics.
+Use [`Status`](Status.md) for a textual state and [`Stat`](Stat.md) for a headline measure without completion semantics.

package/docs/components/RadioGroup.md

@@ -1,6 +1,6 @@
 # RadioGroup
 
-Use RadioGroup when people need to choose one option and see all the choices at once. Give the group a label and each item a unique string value. Arrow keys change the selection and skip disabled options.
+Use `RadioGroup` when people need to choose one option and see all the choices at once. Give the group a label and each item a unique string value. Arrow keys change the selection and skip disabled options.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-radiogroup--docs)
 
@@ -25,7 +25,7 @@ export function Example() {
 ## More examples
 
 - [An unanswered choice](https://kbui.kcb.pro/storybook/?path=/story/components-radiogroup--empty-selection): Start without a selected option.
-- [Segmented choices](https://kbui.kcb.pro/storybook/?path=/story/components-radiogroup--segmented): Compare a visual treatment with the same single-choice contract.
+- [Segmented choices](https://kbui.kcb.pro/storybook/?path=/story/components-radiogroup--segmented): Show a compact layout with the same single-choice behavior.
 - [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-radiogroup--invalid): Explain why a choice is required.
 
 ## Reference
@@ -66,4 +66,4 @@ In dark mode, the primary pill uses a darker orange with white text for contrast
 
 ## Related components
 
-Use [Checkbox](Checkbox.md) for independent choices and [Select](Select.md) when the options belong in a dropdown.
+Use [`Checkbox`](Checkbox.md) for independent choices and [`Select`](Select.md) when the options belong in a dropdown.

package/docs/components/ScrollArea.md

@@ -37,4 +37,4 @@ Tab reaches the viewport so keyboard users can scroll it. Keep the focus indicat
 
 ## Related components
 
-Use [Panel](Panel.md) to group the scrolling content with its heading and actions.
+Use [`Panel`](Panel.md) to group the scrolling content with its heading and actions.

package/docs/components/Select.md

@@ -1,6 +1,6 @@
 # Select
 
-Use Select to choose one option from a dropdown. Each option has a string value, a visible label, and an optional disabled flag. Pass `null` to show the placeholder. Your app stores the selected value and decides whether it is valid.
+Use `Select` to choose one option from a dropdown. Each option has a string value, a visible label, and an optional disabled flag. Pass `null` to show the placeholder. Your app stores the selected value and decides whether it is valid.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-select--docs)
 
@@ -68,4 +68,4 @@ By default, the popup mounts inside the field root and inherits its theme. If yo
 
 ## Related components
 
-Use [RadioGroup](RadioGroup.md) for a visible set of choices and [Menu](Menu.md) for actions.
+Use [`RadioGroup`](RadioGroup.md) for a visible set of choices and [`Menu`](Menu.md) for actions.

package/docs/components/Separator.md

@@ -1,6 +1,6 @@
 # Separator
 
-Native hr thematic break; decorative dividers are hidden from assistive technology. Native hr props and ref pass through; orientation and decorative own role, aria-hidden and aria-orientation.
+Use `Separator` for a thematic break or a decorative divider. It renders a native `<hr>` and accepts its props and `ref`. The `orientation` and `decorative` props set `role`, `aria-hidden` and `aria-orientation`; decorative dividers are hidden from assistive technology.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-separator--docs)
 
@@ -33,8 +33,8 @@ export function Example() {
 | `orientation` | `horizontal` `vertical`                              | `horizontal` |
 | `decorative`  | Hide a visual-only divider from assistive technology | `false`      |
 
-Vertical rules stretch inside Inline and have a 1rem minimum height. No tab stop or resizing interaction is added. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md).
+Vertical rules stretch inside `Inline` and have a 1rem minimum height. No tab stop or resizing interaction is added. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md).
 
 ## Related components
 
-Use [Inline](Inline.md) to arrange a row and [Panel](Panel.md) to group a complete section.
+Use [`Inline`](Inline.md) to arrange a row and [`Panel`](Panel.md) to group a complete section.

package/docs/components/Settings.md

@@ -0,0 +1,57 @@
+# Settings
+
+Use `Settings` for a page of preferences or account management: sections of fields, and managed lists such as members, API keys or sessions with row actions. Each section is saved on its own. `Settings` renders a header region and a sections region with a rule between sections; [`FormSection`](FormSection.md) children put their heading beside their fields on wide screens and above them on narrow ones. Record rows from [`CollectionRow`](CollectionRow.md) keep their status and actions end-aligned, on one line beside the main text from 40rem of page width. For one task with a single submit, use [`Form`](Form.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-settings--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Container, FormSection, Heading, Input, Settings, Switch } from "@kb.ui/react";
+import { useState } from "react";
+
+export function Example() {
+  const [digest, setDigest] = useState(true);
+  return (
+    <Container as="main">
+      <Settings header={<Heading level={1}>Account</Heading>}>
+        <form onSubmit={(event) => event.preventDefault()}>
+          <FormSection
+            title="Profile"
+            description="Shown to everyone in your workspace."
+            actions={<Button type="submit">Save profile</Button>}
+          >
+            <Input label="Display name" name="name" />
+          </FormSection>
+        </form>
+        <FormSection title="Email" description="Sent to the address on your profile.">
+          <Switch label="Weekly digest" checked={digest} onCheckedChange={setDigest} />
+        </FormSection>
+      </Settings>
+    </Container>
+  );
+}
+```
+
+## More examples
+
+- [Notifications](https://kbui.kcb.pro/storybook/?path=/story/layout-settings--notifications): Email, push and quiet-hours sections with switches, a frequency select and event checkboxes.
+- [Team members](https://kbui.kcb.pro/storybook/?path=/story/layout-settings--team-members): An invite form beside a member list with role changes and a confirmed removal.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `header` | `ReactNode` | unset | Page title and intro above the sections |
+| `classNames` | `{ header?, sections? }` | unset | Classes for the regions |
+
+Other native `div` props and `ref` pass through. Direct children of the sections region are separated by a rule; wrap a section in its own `form` when it saves fields, and leave list sections unwrapped.
+
+A `FormSection` inside `Settings` uses the split layout unless you set its `layout`: header in one third, fields in two thirds from 40rem of section width, stacked below it. Tokens: `--kb-settings-gap` and `--kb-settings-divider`.
+
+Start the header with an `h1` and keep section headings at `h2`. Put destructive row actions behind a confirmation such as [`Dialog`](Dialog.md), and announce saved or failed sections with a status message. Your app owns saving, list data and permissions.
+
+## Related components
+
+Use [`FormSection`](FormSection.md) for each section, [`CollectionList`](CollectionList.md) for managed lists and [`Form`](Form.md) for a single task.

package/docs/components/Skeleton.md

@@ -19,28 +19,68 @@ export function Example() {
 }
 ```
 
+## Shape from content
+
+Set `variant="auto"` and pass the real layout as children. While `loading` is true, Skeleton renders the children inert and hidden from assistive technology. kbui avatars, buttons, badges, status chips, images, form fields, headings and text then become placeholders in their own size and shape. Leave data-driven fields empty while loading: empty headings and text still reserve one line. Other text elements fall back to plain text bars. Skeleton marks itself `aria-busy` and announces `label` once, so callers do not write placeholder copy.
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Avatar, Card, Heading, Inline, Skeleton, Text } from "@kb.ui/react";
+
+type Person = { name: string; role: string };
+
+export function Example({ person }: { person?: Person | undefined }) {
+  return (
+    <Skeleton variant="auto" loading={!person} label="Loading profile">
+      <Card>
+        <Inline gap="md" align="center">
+          <Avatar name={person?.name ?? ""} decorative />
+          <div>
+            <Heading level={3} size="sm">
+              {person?.name}
+            </Heading>
+            <Text size="sm" tone="muted">
+              {person?.role}
+            </Text>
+          </div>
+        </Inline>
+      </Card>
+    </Skeleton>
+  );
+}
+```
+
+Skeleton cannot know how many items a list will hold. Render a fixed number of empty rows while loading. Without children, `auto` falls back to `text` lines.
+
 ## More examples
 
-- [Wave, pulse, and accent synthesis](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--wave-and-pulse): Choreograph staggered multi-line wave cascades, breathing pulse blocks, and warm accent-tinted synthesis placeholders.
-- [Structured card placeholder](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--card-placeholder): Combine avatar circles, pills, rectangular wells, and multi-line text placeholders.
+- [Animations](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--animations): Compare `shimmer`, `pulse`, and `wave` motion.
+- [Tones](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--tones): Compare the `default`, `subtle`, and `accent` surfaces.
+- [Profile card](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--profile-card): Combine circle, pill, block, and text placeholders into a card layout.
 - [Shapes and sizes](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--shapes-and-sizes): Compare `text`, `rect`, `circle`, and `pill` geometry across the size scale.
-- [Loading-to-content transition](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--content-transition): Toggle `loading` to swap placeholder bars for resolved children without layout shift.
+- [Content transition](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--content-transition): Toggle `loading` to swap placeholder bars for resolved children without layout shift.
+- [Auto](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--auto): Shape placeholders from a real profile card and toggle `loading` to reveal it in place.
+
+## Motion
+
+Shimmer moves a soft light band across the placeholder, with a short rest between passes. Pulse and wave use a restrained brightness change so the reserved shape stays visible. In `auto`, one animation drives every placeholder in step, and `wave` fades without a stagger. Existing `--kb-skeleton-*` motion tokens control timing; reduced-motion preferences and forced-colors mode use static placeholders.
 
 ## Reference
 
-| Prop         | Type                                  | Default     | Notes                                                                                     |
-| ------------ | ------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
-| `variant`    | `text` / `rect` / `circle` / `pill`   | `text`      | Matches incoming typography, media blocks, avatars, or status chips                       |
-| `size`       | `sm` / `md` / `lg`                    | `md`        | Scales line height and circle diameter                                                    |
-| `lines`      | `number`                              | `1`         | Number of stacked lines when `variant="text"`; the final line shortens naturally          |
-| `width`      | `number` / `string`                   | unset       | Explicit inline size override (`px` number or CSS length)                                 |
-| `height`     | `number` / `string`                   | unset       | Explicit block size override (`px` number or CSS length)                                  |
-| `animated`   | `boolean`                             | `true`      | Enables motion that stops automatically under `prefers-reduced-motion`                    |
-| `animation`  | `shimmer` / `pulse` / `wave` / `none` | `"shimmer"` | Selects specular sweep, breathing pulse, staggered multi-line wave, or static placeholder |
-| `tone`       | `default` / `subtle` / `accent`       | `"default"` | Surface treatment (`default` surface, `subtle` recessed well, or `accent` synthesis tint) |
-| `loading`    | `boolean`                             | `true`      | Renders decorative placeholders when `true`, or `children` inside `.kb-skeleton-content`  |
-| `classNames` | keyed classes                         | unset       | Style `line` or `content`                                                                 |
+| Prop         | Type                                         | Default     | Notes                                                                                     |
+| ------------ | -------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `variant`    | `text` / `rect` / `circle` / `pill` / `auto` | `text`      | Matches typography, media blocks, avatars, or status chips; `auto` shapes from `children` |
+| `size`       | `sm` / `md` / `lg`                           | `md`        | Scales line height and circle diameter                                                    |
+| `lines`      | `number`                                     | `1`         | Number of stacked lines when `variant="text"`; the final line shortens naturally          |
+| `width`      | `number` / `string`                          | unset       | Explicit inline size override (`px` number or CSS length)                                 |
+| `height`     | `number` / `string`                          | unset       | Explicit block size override (`px` number or CSS length)                                  |
+| `animated`   | `boolean`                                    | `true`      | Enables motion that stops automatically under `prefers-reduced-motion`                    |
+| `animation`  | `shimmer` / `pulse` / `wave` / `none`        | `"shimmer"` | Light sweep, fade, staggered fade across lines, or a static placeholder                   |
+| `tone`       | `default` / `subtle` / `accent`              | `"default"` | Surface treatment: `default`, `subtle` recessed, or `accent` tinted                       |
+| `loading`    | `boolean`                                    | `true`      | Renders decorative placeholders when `true`, or `children` inside `.kb-skeleton-content`  |
+| `label`      | `string`                                     | `"Loading"` | Status announced while `variant="auto"` is loading                                        |
+| `classNames` | keyed classes                                | unset       | Style `line`, `content`, or `status`                                                      |
 
 ## Related components
 
-Use [Spinner](Spinner.md) for compact indeterminate waits, [EmptyState](EmptyState.md) when a query resolves with zero items, and [Card](Card.md) as the owning surface with `aria-busy="true"`.
+Use [`Spinner`](Spinner.md) for compact indeterminate waits, [`EmptyState`](EmptyState.md) when a query resolves with zero items, and [`Card`](Card.md) as the owning surface with `aria-busy="true"`.