@kb.ui/react 0.10.4 → 0.12.0

package/docs/components/Separator.md

@@ -0,0 +1,40 @@
+# Separator
+
+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)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Separator } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <div>
+      <p>Project summary</p>
+      <Separator />
+      <p>Review history</p>
+    </div>
+  );
+}
+```
+
+## More examples
+
+- [A divider in a row](https://kbui.kcb.pro/storybook/?path=/story/layout-separator--vertical): Inspect orientation and stretching.
+- [Visual grouping](https://kbui.kcb.pro/storybook/?path=/story/layout-separator--decorative): Hide a decorative rule from assistive technology.
+
+## Reference
+
+| Prop          | Values                                               | Default      |
+| ------------- | ---------------------------------------------------- | ------------ |
+| `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).
+
+## Related components
+
+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

@@ -0,0 +1,86 @@
+# Skeleton
+
+Reserve the footprint of incoming text, media, or cards so the page does not jump when asynchronous data resolves.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-skeleton--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Card, Skeleton } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Card aria-busy="true" aria-label="Loading release summary">
+      <Skeleton variant="text" lines={3} animation="wave" />
+    </Card>
+  );
+}
+```
+
+## 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
+
+- [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.
+- [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` / `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"`.

package/docs/components/Spinner.md

@@ -0,0 +1,45 @@
+# Spinner
+
+Signal an indeterminate wait when completion percentage is unknown. Pair standalone indicators with a clear status label, or mark the spinner decorative inside a button that already names its busy action.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-spinner--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Spinner } from "@kb.ui/react";
+
+export function Example() {
+  return <Spinner label="Loading workspace" variant="orbit" appearance="pill" showLabel />;
+}
+```
+
+## More examples
+
+- [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                                                                                |
+| ------------ | ---------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
+| `label`      | `string`                                                                     | `"Loading"` | Accessible status text announced by `role="status"`                                  |
+| `showLabel`  | `boolean`                                                                    | `false`     | Renders `label` visibly beside the spinner instead of `.kb-sr-only`                  |
+| `decorative` | `boolean`                                                                    | `false`     | Omits `role="status"` and sets `aria-hidden="true"` inside already-labeled controls  |
+| `size`       | `sm` / `md` / `lg`                                                           | `md`        | Scales the SVG indicator and accompanying label                                      |
+| `tone`       | `current` / `accent` / `neutral` / `info` / `success` / `warning` / `danger` | `accent`    | Stroke ink; use `current` inside buttons or badges to inherit text color             |
+| `variant`    | `ring` / `orbit` / `dots` / `bars`                                           | `ring`      | Selects classic arc, dual counter-rotating orbit, staggered wave dots, or equalizer bars |
+| `appearance` | `plain` / `pill`                                                             | `plain`     | Wraps the indicator and label in a tinted status pill when set to `pill`             |
+| `classNames` | keyed classes                                                                | unset       | Style `icon`, `track`, `arc`, `core`, `dot`, `bar`, or `label`                       |
+
+## 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.

package/docs/components/Split.md

@@ -0,0 +1,47 @@
+# Split
+
+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)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Split } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Split>
+      <section aria-labelledby="main-title">
+        <h2 id="main-title">Project</h2>
+        <p>Current work.</p>
+      </section>
+      <aside aria-label="Project details">Last updated today.</aside>
+    </Split>
+  );
+}
+```
+
+## More examples
+
+- [Stacked columns](https://kbui.kcb.pro/storybook/?path=/story/layout-split--responsive): Resize the available width and inspect reading order.
+- [Readable column content](https://kbui.kcb.pro/storybook/?path=/story/layout-split--content-measures): Retain text measure within layout tracks.
+- [Nested columns](https://kbui.kcb.pro/storybook/?path=/story/layout-split--nested): Inspect collapse behavior inside another layout.
+
+## Reference
+
+| Prop         | Values                                             | Default   |
+| ------------ | -------------------------------------------------- | --------- |
+| `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`      |
+| `align`      | `start` `center` `end` `baseline` `stretch`        | `stretch` |
+| `classNames` | `{ track?: string }`, applied to each column track | unset     |
+
+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.

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

@@ -0,0 +1,34 @@
+# Stat
+
+Show a value with the label that explains it. Include units and a time period in the label or value when they affect the meaning.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-stat--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Stat } from "@kb.ui/react";
+
+export function Example() {
+  return <Stat label="Open tasks" value={12} />;
+}
+```
+
+## More examples
+
+- [A headline figure](https://kbui.kcb.pro/storybook/?path=/story/components-stat--display): Compare emphasis for one primary value.
+- [Several measures](https://kbui.kcb.pro/storybook/?path=/story/components-stat--row): Keep labels beside comparable figures.
+
+## Reference
+
+| Prop         | Type             | Default  | Notes                                              |
+| ------------ | ---------------- | -------- | -------------------------------------------------- |
+| `label`      | `ReactNode`      | required | What the value measures; read before the value     |
+| `value`      | `ReactNode`      | required | Number or short text; include units where needed   |
+| `size`       | `md` / `display` | `md`     | Use display for one headline number, md for groups |
+| `classNames` | keyed classes    | unset    | Style the label and value separately               |
+
+## Related components
+
+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

@@ -0,0 +1,48 @@
+# 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.
+
+[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)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Status } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Status tone="running" live>
+      Build running
+    </Status>
+  );
+}
+```
+
+## More examples
+
+- [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; 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
+
+```tsx
+<Status tone="running" appearance="chip" icon={<PlayIcon />} live>
+  Running
+</Status>
+```
+
+| Prop         | Values                                                             | Default   | Notes                                                                   |
+| ------------ | ------------------------------------------------------------------ | --------- | ----------------------------------------------------------------------- |
+| `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     | 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.

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

@@ -0,0 +1,73 @@
+# 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.
+
+[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)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Switch } from "@kb.ui/react";
+import { useState } from "react";
+
+export function Example() {
+  const [checked, setChecked] = useState(false);
+  return (
+    <Switch
+      label="Email notifications"
+      checked={checked}
+      onCheckedChange={setChecked}
+    />
+  );
+}
+```
+
+## More examples
+
+- [Form integration](https://kbui.kcb.pro/storybook/?path=/story/components-switch--native-form): Include an on/off value in a native form.
+- [A retained setting](https://kbui.kcb.pro/storybook/?path=/story/components-switch--read-only): Show a setting while blocking edits.
+- [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-switch--with-error): Associate a correction with the setting.
+
+## Reference
+
+| Prop                                   | Type                                                                    | Default              | Notes                                                                                                                                |
+| -------------------------------------- | ----------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `label`                                | `string`                                                                | required             | Associated visible label and accessible name                                                                                         |
+| `checked`                              | `boolean`                                                               | required             | Current controlled state                                                                                                             |
+| `onCheckedChange`                      | `(checked: boolean) => void`                                            | required             | Requests next state; owner updates checked                                                                                           |
+| `size`                                 | `"sm" \| "md" \| "lg"`                                                  | `"md"`               | Visual track size (`36×20px`, `44×24px`, `56×32px`); `Fieldset` defaults nested switches to `"sm"` while keeping a 44px touch target |
+| `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`                                                                                |
+| `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                                                                               |
+| `ref`                                  | `Ref<HTMLInputElement>`                                                 |                      | Native checkbox, never an extra hidden control                                                                                       |
+| `className` / `controlClassName`       | `string`                                                                |                      | Root/native `input` class                                                                                                              |
+| `style`                                | `CSSProperties`                                                         |                      | Native input styles; CSS custom properties also reach visible track and thumb                                                        |
+
+```tsx
+import { useState } from "react";
+import { Switch } from "@kb.ui/react";
+
+export function Preference() {
+  const [checked, setChecked] = useState(false);
+  return (
+    <Switch
+      label="Email updates"
+      checked={checked}
+      onCheckedChange={setChecked}
+      name="updates"
+    />
+  );
+}
+```
+
+Import `useState` from React and `Switch` from `@kb.ui/react`. Clicking or pressing Space calls `onCheckedChange`. Unchecked or disabled controls submit no value; a checked control submits its native value (`"on"` unless you supply one). Reset `checked` in the form’s `onReset` handler when needed. Use `offTone`/`onTone` or `offColor`/`onColor` when both sides of a toggle carry distinct state colors. The `switch` token group controls its appearance in both themes, and reduced motion removes the thumb’s travel animation.
+
+## Related components
+
+Use [`Checkbox`](Checkbox.md) for a choice submitted with other answers and [`RadioGroup`](RadioGroup.md) for one of several settings.