@kerfjs/ui 5.0.0-beta.48 → 5.0.0-beta.49

package/README.md

@@ -126,7 +126,7 @@ Do not concatenate a count into `label` or pass a numeric `badge`; the mutually
 exclusive legacy `badge` slot remains available for non-count `SafeHtml` such
 as a `New` marker.
 
-`Row.gap`, `List.gap`, and `Spacer` dimensions accept a direct spacing name such as
+`Row.gap`, `Grid.gap`, `List.gap`, and `Spacer` dimensions accept a direct spacing name such as
 `gap="xs"` or `gap="m"`, or a branded `CssLength`. Import `space`, `rem`, `em`,
 `px`, `pct`, `lengthVar`, `plus`, and `calc` from the CSS-free
 `@kerfjs/ui/css-values` subpath when a named step is not enough. `plus` returns
@@ -148,8 +148,13 @@ precedence where both select the same side. `ListInsetText` and
 grammar for selective insets. Nested Rows and Lists resolve their inset sides
 independently, so an unselected inner side does not inherit its parent's inset.
 
+Use `Grid` for a fixed positive number of evenly distributed columns. Its
+`minmax(0, 1fr)` tracks stay equal when children have different intrinsic
+widths; the application owns responsive count changes. Use application CSS grid
+for asymmetric or intrinsic tracks and `ResizableRegion` for adjustable ones.
+
 The same property-specific boundary applies beyond spacing: use `flex()` (or a
-finite keyword) for `Row.flex` and `List.flex`; length builders and intrinsic-size keywords for
+finite keyword) for `Row.flex`, `Grid.flex`, and `List.flex`; length builders and intrinsic-size keywords for
 `Skeleton.width`/`height`; length builders for `Skeleton.radius`; and
 `uiColor()` or `colorVar()` for `SelectChoice.color`. These grammars are not
 interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
@@ -169,6 +174,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `Text`                                                              | `@kerfjs/ui/text`                       | `@kerfjs/ui/text.css`                  |
 | `List`                                                              | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                  |
 | `Row`                                                               | `@kerfjs/ui/row`                        | `@kerfjs/ui/row.css`                   |
+| `Grid`                                                              | `@kerfjs/ui/grid`                       | `@kerfjs/ui/grid.css`                  |
 | `Spacer`                                                            | `@kerfjs/ui/spacer`                     | `@kerfjs/ui/spacer.css`                |
 | Typed CSS dimension builders                                        | `@kerfjs/ui/css-values`                 | —                                      |
 | `ListActionRow`                                                     | `@kerfjs/ui/list-action-row`            | `@kerfjs/ui/list-action-row.css`       |

package/ai/component-catalog-v2.json

@@ -1494,6 +1494,91 @@
         "composition": "docs/layout.md#row-and-list-alignment"
       }
     },
+    {
+      "key": "@kerfjs/ui:grid",
+      "package": "@kerfjs/ui",
+      "id": "grid",
+      "name": "Grid",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "child semantics and content",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "column count and responsive changes",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "typed gap and flex choices",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": { "required": false, "helpers": [], "obligations": [] },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["structure"],
+        "geometry": {
+          "margin": "none",
+          "border": "none",
+          "padding": "none",
+          "notes": [
+            "Every track uses minmax(0, 1fr), so unequal intrinsic widths cannot break equal distribution."
+          ]
+        }
+      },
+      "accessibility": {
+        "obligations": [
+          "Grid adds layout only and no grid role; children retain responsibility for native or ARIA semantics.",
+          "Responsive column-count changes must preserve source and focus order."
+        ]
+      },
+      "cssValueProps": [
+        {
+          "path": "gap",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": [
+            "gap=\"m\"",
+            "gap={space(\"m\")}",
+            "gap={calc(plus(rem(0.25), pct(10)))}"
+          ]
+        },
+        {
+          "path": "flex",
+          "grammar": "flex",
+          "helpers": ["flex"],
+          "shorthands": ["none", "auto", "initial"],
+          "canonicalShorthands": ["none", "auto", "initial"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["flex", "flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
+        }
+      ],
+      "boundaries": {
+        "rootClass": "kui-grid",
+        "publicClasses": ["kui-grid"],
+        "publicTokens": ["--kui-grid-gap", "--kui-layout-item-gap"]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:spacer",
       "package": "@kerfjs/ui",

package/ai/component-catalog.json

@@ -1680,6 +1680,104 @@
         "recipe": "docs/layout.md#row-and-list-alignment"
       }
     },
+    {
+      "id": "grid",
+      "name": "Grid",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A fixed positive number of evenly distributed minmax columns with a typed xs gap by default and optional flex participation.",
+      "uses": [],
+      "purpose": "Arrange related siblings in equal-width columns without repeating application-owned grid-template-columns CSS.",
+      "publicExports": ["Grid"],
+      "cssValueProps": [
+        {
+          "path": "gap",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": ["gap=\"m\"", "gap={space(\"m\")}", "gap={calc(plus(rem(0.25), pct(10)))}"]
+        },
+        {
+          "path": "flex",
+          "grammar": "flex",
+          "helpers": ["flex"],
+          "shorthands": ["none", "auto", "initial"],
+          "canonicalShorthands": ["none", "auto", "initial"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["flex", "flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
+        }
+      ],
+      "useWhen": [
+        "Arrange related siblings into a fixed positive number of equal-width columns.",
+        "Prevent wider intrinsic content from making one fractional track wider than its peers.",
+        "Use a finite flex keyword or the flex() builder when Grid participates in a flexible parent layout."
+      ],
+      "avoidWhen": [
+        "Do not use Grid for intrinsic, asymmetric, spanning, auto-fit, or masonry tracks; use application-owned CSS grid.",
+        "Do not use Grid when columns need a user-operable separator; use ResizableRegion.",
+        "Do not expect Grid to choose responsive breakpoints or change the column count; the application owns that policy.",
+        "Do not pass raw CSS strings to gap or flex, mix their distinct grammars, or use s/xl spacing steps without a deliberate exception."
+      ],
+      "alternatives": [
+        {
+          "id": "row",
+          "relationship": "axis-alternative",
+          "when": "Use Row for one horizontal flex line, alignment, or wrapping rather than fixed equal tracks."
+        },
+        {
+          "id": "list",
+          "relationship": "axis-alternative",
+          "when": "Use List when the main layout axis is vertical."
+        },
+        {
+          "id": "resize",
+          "relationship": "interactive-alternative",
+          "when": "Use ResizableRegion when people must adjust the boundary between tracks."
+        }
+      ],
+      "appOwns": [
+        "child semantics and content",
+        "column count and responsive changes",
+        "typed gap and flex choices"
+      ],
+      "variants": [
+        "any positive safe-integer equal-track count",
+        "named none/2xs/xs/s/m/l/xl token gap",
+        "typed CssLength gap",
+        "boolean, finite-keyword, or typed CssFlex flex"
+      ],
+      "accessibility": [
+        "Grid adds layout only and no grid role; children retain responsibility for native or ARIA semantics.",
+        "Responsive column-count changes must preserve source and focus order."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none",
+        "notes": [
+          "Every track uses minmax(0, 1fr), so unequal intrinsic widths cannot break equal distribution."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/grid",
+        "manualCssImport": "@kerfjs/ui/grid.css",
+        "sideEffects": ["browser-condition-css"]
+      },
+      "wiring": [],
+      "publicClasses": ["kui-grid"],
+      "publicTokens": ["--kui-grid-gap", "--kui-layout-item-gap"],
+      "links": {
+        "catalogRoute": "?component=grid",
+        "documentation": "docs/layout.md",
+        "recipe": "docs/layout.md#grid"
+      }
+    },
     {
       "id": "spacer",
       "name": "Spacer",

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.48` and `kerfjs@5.0.0-beta.48`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.49` and `kerfjs@5.0.0-beta.49`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -2072,6 +2072,29 @@ declare function Row({ children, hAlign, vAlign, gap, flex, wrap, textInsets, co
 export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowProps, Sides, UiSpaceName, VerticalAlignment };
 ```
 
+## `@kerfjs/ui/grid`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+interface GridProps {
+    children?: KerfUiContent;
+    /** Number of equal-width columns. Must be a positive safe integer. */
+    columns: number;
+    /** A named UI spacing token or typed CSS length. Defaults to xs. */
+    gap?: UiSpaceName | CssLength;
+    /** Allow this grid to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
+    flex?: boolean | CssFlexKeyword | CssFlex;
+    className?: string;
+}
+/** A fixed-count grid whose columns share the available width equally. */
+declare function Grid({ children, columns, gap, flex, className, }: GridProps): kerfjs.SafeHtml;
+
+export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, UiSpaceName };
+```
+
 ## `@kerfjs/ui/spacer`
 
 ```ts

package/ai/skill.md

@@ -79,12 +79,13 @@ Quick routing:
 | ------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Navigation row                        | `ListItem`                                                 | Use an ordinary link or button when sidebar/menu anatomy and state do not apply. Its rounded root clips overflowing descendants; set `multiline` when the primary label should wrap. Multiline leading icons stay aligned with the first text line.                                                                                                                                                                                                                                                          |
 | Horizontal flex layout                | `Row`                                                      | Use `hAlign`/`vAlign`, a typed `gap`, and opt-in `wrap`; use `List` when the main axis is vertical.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Equal-width columns                   | `Grid`                                                     | Use a positive fixed `columns` count plus typed `gap`/`flex`. The app owns responsive count changes; use CSS grid for asymmetric/intrinsic tracks and `ResizableRegion` for adjustable boundaries.                                                                                                                                                                                                                                                                                                           |
 | Navigation row with a trailing action | `ListActionRow`                                            | Use `ListItem` when the trailing region is dormant; never put controls inside either component's SafeHtml slots. Multiline leading icons stay aligned with the first text line.                                                                                                                                                                                                                                                                                                                              |
 | Page, panel, or dialog heading        | `Toolbar` + `ToolbarText`                                  | Use a direct extra-large `ToolbarText`, optional grouped icon, grouped trailing controls, and app-owned supporting copy below.                                                                                                                                                                                                                                                                                                                                                                               |
 | Exclusive choice                      | `TabBar`, `SegmentedControl`, or `Select`                  | Tabs switch tabpanels; segments expose a few choices; Select handles a longer value list.                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | Status or absent content              | `StateBanner` or `EmptyState`                              | `StateBanner` accepts an optional terse, tone-tinted `badge` beside its title for a count or compact status; do not rely on color alone. Web Awesome callouts suit ecosystem content; toasts are transient and never the only record of important state.                                                                                                                                                                                                                                                     |
 | Loading placeholder                   | a component's `placeholder` prop, or `Skeleton`            | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render its real chrome with value slots as subtle **unanimated** skeletons and interactivity disabled — do not hand-rebuild an empty state. `Skeleton` is the standalone block for a custom slot. Use `LoadingSpinner` for known busy activity, not a skeleton; never animate a skeleton; prefer it over `wa-skeleton`. |
-| Adjustable or static columns          | `ResizableRegion` or CSS grid                              | Use the component only for a user-operable controlled separator.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Adjustable or asymmetric columns      | `ResizableRegion` or CSS grid                              | Use `ResizableRegion` only for a user-operable controlled separator, CSS grid for asymmetric/intrinsic tracks, and `Grid` for static equal-width tracks.                                                                                                                                                                                                                                                                                                                                                     |
 | Structured or ordinary search         | `TokenSearchField` or an input                             | Use token search only when text and ordered filter chips form one editor.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | Key/value facts                       | `ValueTable` with `ValueTableRow`                          | Use rows with `icon` only when the optional 24px leading visual adds context.                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | Command search                        | Application-local semantics using shared layout vocabulary | No runtime component or production recipe is exported; the app owns behavior, policy, and copy.                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -126,16 +127,16 @@ Hard rules:
 10. Compose `AppTab` inside controlled `TabBar`; call `wireTabBars()` once and retain its disposer. It owns same-bar drag mechanics, including proximity-based horizontal edge autoscroll, while the app applies `onReorder` and owns order, selection, panels, close policy, routing, and persistence. Arrow/Home/End select on move by default and restore focus by bar/tab identity when controlled activation replaces the strip; pass `activation: 'manual'` (or `TabBar activation="manual"` per strip) so arrow keys move focus only and the user selects with Enter/Space/click — use it when selecting a tab is a heavy action. Use runtime-filtered `rootAttributes` for domain metadata and keep an optional `closeIcon` decorative and noninteractive.
 11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. The app owns parsing and suggestions; call `readTokenSearchField()` on input, empty `textContent` on clear, use `placeTokenSearchCaret()` after explicit controlled focus changes, and call `wireTokenSearchFields()` once so Enter submits without inserting a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded, and `wireTokenSearchFields()` manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse). Bind the field's `expanded` to the returned handle's `expanded(id)` signal or adopt your own via `collapsible.signals`; opt a behavior out only when the app must own it. Do not hand-roll the open handler, the focusout collapse, a clear-button mousedown guard, or reopening after controlled clear or Select All deletion — the helper keeps the replacement editor open and focused. Clear and deletion restoration finish at the replacement mutation checkpoint before the next input task, so shortcut-letter typing cannot escape to the page and delayed animation frames cannot overwrite a later selection. Persist both query and tokens returned by the DOM read. For real-app adoption it also provides a focusout keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn(target)`, so a sibling suggestions/date/help surface does not collapse an empty field), opt-in atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — reach for these instead of re-adding hand-rolled keydown/input handlers around the field.
 12. Demo work uses public production component subpaths and their browser-selected CSS. Give every public visual component its own category-grouped catalog route; list themed third-party components under a clearly labeled collapsible ecosystem section, with a focused route for each. For the complete focused/composition decision, `CatalogExample` / `CatalogExampleStack` row/group nesting, exact specimen selection, geometry-overlay legend and exclusions, skip-marker behavior, and metadata ownership, follow the single [Catalog demo authoring contract](../docs/catalog.md#catalog-demo-authoring-contract), discovered machine-readably through [`catalog-authoring.json`](./catalog-authoring.json). Never infer structure from private `kui-catalog-*` classes. Project each component's deterministic repository-relative demo source and existing documentation path so the detail can expose `View demo source` and `Read guidance` links without a runtime export; also derive first-party component implementation paths from their canonical browser imports, and label Web Awesome documentation as Kerf integration guidance. Declare direct `uses` relationships so `Used by` stays derivable, and theme shell chrome through the same semantic tokens as the stage instead of drawing a substitute. Enable `wireCatalog({ revealSelection: true })` for long desktop sidebars so controlled selections remain visible without moving focus; keep its default compact media guard unless compact scrolling is an explicit product behavior, and use `revealCatalogEntry` for an initial deep link.
-13. The Web Awesome theme makes Tooltip and Popover arrowless by default. Keep that default unless a pointer materially clarifies the anchor; opt back in with `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or a popover's public `--arrow-size`, and use `without-arrow` when local no-arrow intent should survive theme changes. Its non-field chrome uses `--kui-wa-control-inset` (8px controls/items), `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside Accordion, Card, Details, Callout, and Include), and `--kui-wa-container-inset` (16px Tab Panel content); Dialog maps its body to the 8px surface tier and its footer to the 16px container tier independently of `--spacing`. Override those tiers instead of restyling individual parts. Filled badges use each variant's quiet fill with normal text so their compact copy stays WCAG-AA readable; override the pair with `--kui-wa-badge-filled-background` / `--kui-wa-badge-filled-foreground`, not host selectors. When a dialog provides another dismissal affordance, put `hide-actions` on the `wa-dialog` host to hide its directly exported `header-actions` part; never chain `::part()` selectors through internal parts. Checkbox and Radio Group option regions, the Color Picker trigger, and Slider's complete interactive region receive the shared 8px logical inline outer inset because those controls have no bordered field shell. Known Date field captions and bordered text-like field hints align with values at the 9px border-plus-padding inset. OTP Input's label uses the same uppercase xs/650 treatment as other field labels, and both its label and hint use that 9px inset.
+13. The Web Awesome theme makes Tooltip and Popover arrowless by default. Keep that default unless a pointer materially clarifies the anchor; opt back in with `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or a popover's public `--arrow-size`, and use `without-arrow` when local no-arrow intent should survive theme changes. Its non-field chrome uses `--kui-wa-control-inset` (8px controls/items), `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside Accordion, Card, Details, Callout, and Include), and `--kui-wa-container-inset` (16px Tab Panel content and outlined/sunken disclosure headers); plain Accordion and Details remove inline trigger/body padding. Dialog maps its body to the 8px surface tier and its footer to the 16px container tier independently of `--spacing`. Override those tiers instead of restyling individual parts. Filled badges use each variant's quiet fill with normal text so their compact copy stays WCAG-AA readable; override the pair with `--kui-wa-badge-filled-background` / `--kui-wa-badge-filled-foreground`, not host selectors. When a dialog provides another dismissal affordance, put `hide-actions` on the `wa-dialog` host to hide its directly exported `header-actions` part; never chain `::part()` selectors through internal parts. Checkbox and Radio Group option regions, the Color Picker trigger, and Slider's complete interactive region receive the shared 8px logical inline outer inset because those controls have no bordered field shell. Known Date field captions and bordered text-like field hints align with values at the 9px border-plus-padding inset. OTP Input's label uses the same uppercase xs/650 treatment as other field labels, and both its label and hint use that 9px inset.
 14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. Its UX sidebar marks superseded and exceptional entries `Discouraged`. Consider Popup when it replaces custom anchored positioning. Prefer Kerf `Select` over direct Dropdown/Dropdown Item/Select/Option composition, `SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over Split Panel. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame.
-15. Build sidebars, main areas, inspectors, and dialogs from `@kerfjs/ui/layout.css`: an unpadded `.kui-pane`, optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Use `Row` instead of a hand-written flex-row wrapper and `List` instead of a hand-written flex-column wrapper when children need shared physical-axis alignment and typed spacing. `Row` defaults to left/full with an `xs` gap and no wrapping; `List` retains full/top and zero-gap defaults. Use `List` when rows or sections also need flex growth, one vertical scroll owner, or physical-edge dividers. `dividerSides`, `textInsets`, and `controlInsets` use canonical physical `t`/`r`/`b`/`l` order; text geometry wins where text and control selections overlap. `ListInsetText` and `ListInsetControl` inset all four sides by default and accept the same `sides` grammar for selective edges. A dialog body is generally a `List`: set `DialogSurface bodyInset="none"` when its list children own geometry, and wrap bare dialog prose in `ListInsetText` so it aligns with bordered siblings without a second inset. Add `.kui-content` for 24px major vertical separation and `.kui-content-item` for a child-owned 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px radius. Use the pill modifier for 22px. Do not pad pane shells, duplicate item geometry in wrappers, or create nested scroll owners.
+15. Build sidebars, main areas, inspectors, and dialogs from `@kerfjs/ui/layout.css`: an unpadded `.kui-pane`, optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Use `Row` instead of a hand-written flex-row wrapper, `List` instead of a hand-written flex-column wrapper, and `Grid` instead of repeated equal-track CSS when children need a fixed positive count of evenly distributed columns. `Row` defaults to left/full with an `xs` gap and no wrapping; Grid defaults to an `xs` gap and keeps each track at `minmax(0, 1fr)`; List retains full/top and zero-gap defaults. The app owns Grid's responsive column-count changes. Use `List` when rows or sections also need flex growth, one vertical scroll owner, or physical-edge dividers. `dividerSides`, `textInsets`, and `controlInsets` use canonical physical `t`/`r`/`b`/`l` order; text geometry wins where text and control selections overlap. `ListInsetText` and `ListInsetControl` inset all four sides by default and accept the same `sides` grammar for selective edges. A dialog body is generally a `List`: set `DialogSurface bodyInset="none"` when its list children own geometry, and wrap bare dialog prose in `ListInsetText` so it aligns with bordered siblings without a second inset. Add `.kui-content` for 24px major vertical separation and `.kui-content-item` for a child-owned 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px radius. Use the pill modifier for 22px. Do not pad pane shells, duplicate item geometry in wrappers, or create nested scroll owners.
     15a. Use `Text` from `@kerfjs/ui/text` for ordinary headings and paragraphs outside toolbar title zones. Omit `variant` for the default `p`, or pass `h1`–`h6` according to the document outline; ordinary native attributes pass through. Express supporting, error, compact, or code text with the independent finite `tone="quiet|danger"`, `size="compact"`, and `font="monospace"` props instead of global utility classes or appearance-only heading choices. Text owns a transparent 1px border and the standard item padding. Keep toolbar identity/title content on `ToolbarText` and list-aligned bare prose on `ListInsetText`.
 16. Keep a visible collapsible pane's collapse control in its own toolbar. When hidden, move its restore control into the adjacent main toolbar on the corresponding logical edge: leading for an inline-start sidebar and trailing for an inline-end inspector. Collapse the pane completely; do not preserve an empty icon-only rail.
 17. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. Put identity/title text directly in the zone as `ToolbarText`; wrap interactive controls and icon tiles in `ToolbarControlGroup`. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a group. For an ordinary icon/action control inside a group, use a plain `<button>` (the group styles `> button` fully) — that is the default; reach for `wa-button` only when you need a Web Awesome feature, chiefly a `wa-dropdown` popup trigger. A popup menu in a toolbar is a `single` group wrapping a `wa-dropdown` whose `slot="trigger"` `wa-button` is the toolbar button and whose `wa-dropdown-item`s are the menu, with the dropdown kept under `data-morph-skip-children`. For a compact mixed group, keep the standard item padding and raised selected chrome; the selected item paints over the outer border without an internal separator. For an avatar control, set `content="avatar"` and `avatarImage` on the group instead of inserting an `img`: a lone control paints the contained image on the outer group and a multi-button group paints it only on the pressed selection highlight. Compose panel/dialog/page headings with a direct extra-large `ToolbarText`, optional grouped icon, grouped trailing controls, and app-owned supporting copy below. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Split dormant and interactive regions: `ListHeader` fills the available inline width by default; set `inline` only when it should shrink-wrap in surrounding content without outer margin, border, or padding. It keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; never shrink the target to match it. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets.
 18. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, toolbar title/supporting-copy ids, shared 8px field/action gutters, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card or double-inset intrinsically bordered controls. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.
 19. Compose `ValueTable` from typed `ValueTableRow` entries instead of handwritten `dt`/`dd` wrappers. Pass `icon` for the optional 24px leading visual; the row owns 8px of root-scaled top and bottom padding, the 8px iconless or 40px icon-bearing separator start, and the common 8px right inset.
 20. Use the standard direct `Toolbar` composition for a panel, dialog, or page heading, not a private wrapper or custom heading row. Put an optional icon in a `ToolbarControlGroup`, the title directly in the leading zone as extra-large `ToolbarText`, and actions in a trailing group. Set `headingLevel` for page/section landmarks. Supporting copy stays below the toolbar as app-owned content. The app owns modal behavior, focus, dismissal, command policy, ids, and action handling.
-21. Space with the official five-step scale, picked by how connected two elements are — not by eye. `0` `--kui-space-none` = no separation (one unit); `4px` `--kui-space-2xs` = very minor air on a connected cluster; `8px` `--kui-space-xs` = standard, between elements within a group; `16px` `--kui-space-m` = minor, between homogeneous groups; `24px` `--kui-space-l` = major, between heterogeneous groups (the `.kui-content` rhythm). The 8px-vs-24px distinction is inside-a-group vs between-major-differing-regions. `--kui-space-s` (12px) and `--kui-space-xl` (32px) are off-scale exceptions. For `Row.gap` or `List.gap`, pass a finite shorthand such as `gap="xs"` or `gap="m"`; use `Spacer` for one intentional typed empty width/height or a flexible main-axis gap. When one token is insufficient, import typed builders from the CSS-free `@kerfjs/ui/css-values` subpath. Preserve property grammar: lengths for gap/Spacer/Skeleton geometry, `flex()` for List flex, and `uiColor()`/`colorVar()` for choice icons. Never cast between brands or emit raw row `style` declarations. `plus` is not standalone and must be wrapped in `calc`; `remify()` remains source-CSS syntax and is never a runtime prop value. See `docs/layout.md` "Spacing scale".
+21. Space with the official five-step scale, picked by how connected two elements are — not by eye. `0` `--kui-space-none` = no separation (one unit); `4px` `--kui-space-2xs` = very minor air on a connected cluster; `8px` `--kui-space-xs` = standard, between elements within a group; `16px` `--kui-space-m` = minor, between homogeneous groups; `24px` `--kui-space-l` = major, between heterogeneous groups (the `.kui-content` rhythm). The 8px-vs-24px distinction is inside-a-group vs between-major-differing-regions. `--kui-space-s` (12px) and `--kui-space-xl` (32px) are off-scale exceptions. For `Row.gap`, `Grid.gap`, or `List.gap`, pass a finite shorthand such as `gap="xs"` or `gap="m"`; use `Spacer` for one intentional typed empty width/height or a flexible main-axis gap. When one token is insufficient, import typed builders from the CSS-free `@kerfjs/ui/css-values` subpath. Preserve property grammar: lengths for gap/Spacer/Skeleton geometry, `flex()` for Row/Grid/List flex, and `uiColor()`/`colorVar()` for choice icons. Never cast between brands or emit raw row `style` declarations. `plus` is not standalone and must be wrapped in `calc`; `remify()` remains source-CSS syntax and is never a runtime prop value. See `docs/layout.md` "Spacing scale".
 22. Pick a whole-screen layout from the opt-in, tree-shakeable subpaths by data + interaction + device, and derive responsiveness from `@kerfjs/ui/device-class`'s `deviceClass()` (`compact` = handset or portrait tablet = one pane at a time). Simple/flat → `NavStack` with one entry (single pane), plus `TabScaffold` (`@kerfjs/ui/tab-scaffold`, iOS bottom tabs, each tab its own `NavStack`) for 2–5 co-equal sections on `compact`. Drill-down → `NavStack` (`@kerfjs/ui/nav-stack`), upgrading to `SplitView` (`@kerfjs/ui/split-view`, list-detail) once both panes fit (`atLeast('tablet')` landscape); `SplitView` collapses to a `NavStack` on `compact`. Keep each stack's ordered views controlled; put view-specific bottom chrome on `NavStackView.bottomToolbar` (or use the component-level persistent fallback), then call `wireNavStack` so content slides while the active view's top and bottom chrome cross-fade and focus moves into the new top view/restores on pop. Mark a preferred initial heading or control with `data-nav-focus` when DOM order is not sufficient. Complex tool with peripheral panels → `Workbench` (`@kerfjs/ui/workbench`, collapsible rails + drawer) `atLeast('desktop')`, degrading to `NavStack`/overlays below. These are declarative (the app owns the stack/selection/collapsed/active state as signals) with disposer-returning `wire…` helpers; each ships a companion CSS import and stays out of the barrel. For a standalone collapsible rail or bottom drawer outside a full shell, use `CollapsiblePanel` + `CollapsiblePanelToggle` (`@kerfjs/ui/collapsible-panel`) with `wireSidebar` (`@kerfjs/ui/wire-sidebar`): the standard collapse animation and per-side icon convention (`PanelLeft*`/`PanelRight*`/`PanelBottom*`) plus toggle, focus, compact overlay, and persistence semantics. Dialogs pick the same inner layout, then present per device class (full-screen modal on `compact`, inline on desktop). See `docs/app-layouts.md` and `docs/collapsible-panel.md`.
 
 Common mistakes:

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.48` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.49` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/dist/browser/grid.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/grid.css';
+export * from '../grid.js';

package/dist/catalog.js

@@ -1,11 +1,11 @@
 import { ToolbarControlGroup } from './chunk-B6JYRX3P.js';
 import { Toolbar } from './chunk-VXFGMDA7.js';
+import { List } from './chunk-WVLMZ5SG.js';
 import { Pane } from './chunk-I4V3UDSA.js';
+
 import { ListHeader } from './chunk-GYGM363P.js';
 import { Text } from './chunk-XKFRMGMW.js';
 import { ListItem } from './chunk-I45QO2IZ.js';
-import { List } from './chunk-WVLMZ5SG.js';
-
 import { filterDataAttributes } from './chunk-SRSJO5QE.js';
 
 

package/dist/chunk-IU4QUY5I.js

@@ -0,0 +1,45 @@
+import { space } from './chunk-OL4TC3U2.js';
+import { jsx } from 'kerfjs/jsx-runtime';
+
+var spaceNames = [
+  "none",
+  "2xs",
+  "xs",
+  "s",
+  "m",
+  "l",
+  "xl"
+];
+function Grid({
+  children,
+  columns,
+  gap = "xs",
+  flex = false,
+  className = ""
+}) {
+  if (!Number.isSafeInteger(columns) || columns < 1) {
+    throw new RangeError("Grid columns must be a positive safe integer");
+  }
+  const gapValue = spaceNames.includes(gap) ? space(gap) : gap;
+  const flexValue = flex === true ? "1 1 auto" : flex || void 0;
+  const style = [
+    `--_kui-grid-columns:${columns}`,
+    `--_kui-grid-gap:${gapValue}`,
+    flexValue ? `--_kui-grid-flex:${flexValue}` : ""
+  ].filter(Boolean).join(";");
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      class: `kui-grid ${className}`.trim(),
+      "data-component": "grid",
+      "data-columns": String(columns),
+      "data-flex": String(Boolean(flex)),
+      style,
+      children
+    }
+  );
+}
+
+export { Grid };
+
+//# sourceMappingURL=chunk-IU4QUY5I.js.map

package/dist/chunk-IU4QUY5I.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/grid.tsx"],"names":[],"mappings":";;;AASA,IAAM,UAAA,GAAqC;AAAA,EACzC,MAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA;AACF,CAAA;AAcO,SAAS,IAAA,CAAK;AAAA,EACnB,QAAA;AAAA,EACA,OAAA;AAAA,EACA,GAAA,GAAM,IAAA;AAAA,EACN,IAAA,GAAO,KAAA;AAAA,EACP,SAAA,GAAY;AACd,CAAA,EAAc;AACZ,EAAA,IAAI,CAAC,MAAA,CAAO,aAAA,CAAc,OAAO,CAAA,IAAK,UAAU,CAAA,EAAG;AACjD,IAAA,MAAM,IAAI,WAAW,8CAA8C,CAAA;AAAA,EACrE;AAEA,EAAA,MAAM,WAAW,UAAA,CAAW,QAAA,CAAS,GAAkB,CAAA,GACnD,KAAA,CAAM,GAAkB,CAAA,GACxB,GAAA;AACJ,EAAA,MAAM,SAAA,GAAY,IAAA,KAAS,IAAA,GAAO,UAAA,GAAa,IAAA,IAAQ,MAAA;AACvD,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,uBAAuB,OAAO,CAAA,CAAA;AAAA,IAC9B,mBAAmB,QAAQ,CAAA,CAAA;AAAA,IAC3B,SAAA,GAAY,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,GAAK;AAAA,GAChD,CACG,MAAA,CAAO,OAAO,CAAA,CACd,KAAK,GAAG,CAAA;AAEX,EAAA,uBACE,GAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,SAAA,EAAY,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACpC,gBAAA,EAAe,MAAA;AAAA,MACf,cAAA,EAAc,OAAO,OAAO,CAAA;AAAA,MAC5B,WAAA,EAAW,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAC,CAAA;AAAA,MAC/B,KAAA;AAAA,MAEC;AAAA;AAAA,GACH;AAEJ","file":"chunk-IU4QUY5I.js","sourcesContent":["import {\n  type CssFlex,\n  type CssFlexKeyword,\n  type CssLength,\n  space,\n  type UiSpaceName,\n} from './css-values.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\nconst spaceNames: readonly UiSpaceName[] = [\n  'none',\n  '2xs',\n  'xs',\n  's',\n  'm',\n  'l',\n  'xl',\n];\n\nexport interface GridProps {\n  children?: KerfUiContent;\n  /** Number of equal-width columns. Must be a positive safe integer. */\n  columns: number;\n  /** A named UI spacing token or typed CSS length. Defaults to xs. */\n  gap?: UiSpaceName | CssLength;\n  /** Allow this grid to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */\n  flex?: boolean | CssFlexKeyword | CssFlex;\n  className?: string;\n}\n\n/** A fixed-count grid whose columns share the available width equally. */\nexport function Grid({\n  children,\n  columns,\n  gap = 'xs',\n  flex = false,\n  className = '',\n}: GridProps) {\n  if (!Number.isSafeInteger(columns) || columns < 1) {\n    throw new RangeError('Grid columns must be a positive safe integer');\n  }\n\n  const gapValue = spaceNames.includes(gap as UiSpaceName)\n    ? space(gap as UiSpaceName)\n    : gap;\n  const flexValue = flex === true ? '1 1 auto' : flex || undefined;\n  const style = [\n    `--_kui-grid-columns:${columns}`,\n    `--_kui-grid-gap:${gapValue}`,\n    flexValue ? `--_kui-grid-flex:${flexValue}` : '',\n  ]\n    .filter(Boolean)\n    .join(';');\n\n  return (\n    <div\n      class={`kui-grid ${className}`.trim()}\n      data-component=\"grid\"\n      data-columns={String(columns)}\n      data-flex={String(Boolean(flex))}\n      style={style}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport type {\n  CssFlex,\n  CssFlexKeyword,\n  CssLength,\n  UiSpaceName,\n} from './css-values.js';\n"]}

package/dist/grid.d.ts

@@ -0,0 +1,18 @@
+import * as kerfjs from 'kerfjs';
+import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+interface GridProps {
+    children?: KerfUiContent;
+    /** Number of equal-width columns. Must be a positive safe integer. */
+    columns: number;
+    /** A named UI spacing token or typed CSS length. Defaults to xs. */
+    gap?: UiSpaceName | CssLength;
+    /** Allow this grid to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
+    flex?: boolean | CssFlexKeyword | CssFlex;
+    className?: string;
+}
+/** A fixed-count grid whose columns share the available width equally. */
+declare function Grid({ children, columns, gap, flex, className, }: GridProps): kerfjs.SafeHtml;
+
+export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, UiSpaceName };

package/dist/grid.js

@@ -0,0 +1,4 @@
+export { Grid } from './chunk-IU4QUY5I.js';
+
+
+//# sourceMappingURL=grid.js.map

package/dist/grid.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"grid.js"}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { CssColor, CssFlex, CssFlexBasis, CssFlexKeyword, CssLength, CssLengthEx
 export { DisclosureArrow, DisclosureArrowProps, DisclosureDirection } from './disclosure-arrow.js';
 export { EmptyState, EmptyStateProps } from './empty-state.js';
 export { FloatingToolbar, FloatingToolbarPosition, FloatingToolbarProps } from './floating-toolbar.js';
+export { Grid, GridProps } from './grid.js';
 export { List, ListProps } from './list.js';
 export { ListActionRow, ListActionRowProps } from './list-action-row.js';
 export { ListHeader, ListHeaderProps } from './list-header.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { wireResizableRegions } from './chunk-WN52USHV.js';
 export { reorderTabs, wireTabBars } from './chunk-UKKSMZYT.js';
 export { wireTokenSearchFields } from './chunk-VDUJZF5G.js';
+export { TabBar } from './chunk-ZPWZIVI6.js';
 export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-TIGSG6BX.js';
 export { ValueTable, ValueTableRow } from './chunk-V6HCTCVD.js';
 export { Select } from './chunk-CK6P5AUK.js';
@@ -8,24 +9,24 @@ export { Spacer } from './chunk-OGTJNHRG.js';
 export { StateBanner } from './chunk-UDHHKZWO.js';
 export { SunkenPanel } from './chunk-SOK5EUF7.js';
 export { DialogSurface, PopupSurface } from './chunk-WSXUPSID.js';
-export { TabBar } from './chunk-ZPWZIVI6.js';
 export { ToolbarText } from './chunk-V6GQKOX2.js';
 export { ResizableRegion, clampRegionSize, resizeRegionFromPointer } from './chunk-CAB6NQ2T.js';
 export { Row } from './chunk-OGNE3OFT.js';
 export { SegmentedControl } from './chunk-E34TE2ZI.js';
 export { FloatingToolbar } from './chunk-DYBPI5O2.js';
+export { Grid } from './chunk-IU4QUY5I.js';
 export { ListActionRow } from './chunk-DAO2VFTT.js';
 export { ListInsetControl } from './chunk-2TYUFZUC.js';
 export { ListInsetText } from './chunk-EYALJQQD.js';
 export { AppTab } from './chunk-OMSRSL3B.js';
 export { ToolbarControlGroup } from './chunk-B6JYRX3P.js';
 export { Toolbar } from './chunk-VXFGMDA7.js';
+export { List } from './chunk-WVLMZ5SG.js';
 export { Pane } from './chunk-I4V3UDSA.js';
+
 export { ListHeader } from './chunk-GYGM363P.js';
 export { Text } from './chunk-XKFRMGMW.js';
 export { ListItem } from './chunk-I45QO2IZ.js';
-export { List } from './chunk-WVLMZ5SG.js';
-
 
 export { Skeleton } from './chunk-T7DOWS6T.js';
 export { calc, colorVar, em, flex, lengthVar, pct, plus, px, rem, space, uiColor } from './chunk-OL4TC3U2.js';

package/dist/styles/grid.css

@@ -0,0 +1,11 @@
+.kui-grid {
+  --kui-grid-gap: var(--kui-layout-item-gap, 0.5rem);
+
+  display: grid;
+  min-width: 0;
+  min-height: 0;
+  box-sizing: border-box;
+  flex: var(--_kui-grid-flex, initial);
+  grid-template-columns: repeat(var(--_kui-grid-columns), minmax(0, 1fr));
+  gap: var(--_kui-grid-gap, var(--kui-grid-gap));
+}

package/dist/styles/styles.css

@@ -9,6 +9,7 @@
 @import "./text.css";
 @import "./list.css";
 @import "./row.css";
+@import "./grid.css";
 @import "./spacer.css";
 @import "./list-action-row.css";
 @import "./list-item.css";

package/dist/styles/webawesome.css

@@ -336,6 +336,22 @@
     box-shadow: none;
   }
 
+  /* Unframed disclosures align directly with their surrounding content.
+     Framed disclosure headers use the roomier container tier so the trigger
+     reads as the surface heading while the body keeps its compact inset. */
+  wa-details[appearance="plain"]::part(header),
+  wa-details[appearance="plain"]::part(content),
+  wa-accordion[appearance="plain"] > wa-accordion-item::part(button),
+  wa-accordion[appearance="plain"] > wa-accordion-item::part(content) {
+    padding-inline: 0;
+  }
+
+  wa-details:is([appearance="outlined"], [appearance="sunken"])::part(header),
+  wa-accordion:is([appearance="outlined"], [appearance="sunken"])
+    > wa-accordion-item::part(button) {
+    padding-inline: var(--kui-wa-container-inset);
+  }
+
   wa-card,
   wa-details,
   wa-accordion-item {

package/docs/component-selection.md

@@ -38,7 +38,7 @@ foreground/background contrast relationships and visible focus ring.
 
 ### Typed runtime dimensions
 
-Use `Row` or `List` spacing shorthands for repeated sibling spacing: `gap="xs"`,
+Use `Row`, `Grid`, or `List` spacing shorthands for repeated sibling spacing: `gap="xs"`,
 `gap="m"`, and the other `UiSpaceName` values resolve to their matching
 `--kui-space-*` token. Use `Spacer` for one deliberate empty width or height, or
 pass `flex` to consume the remaining space along a flex parent's main axis.
@@ -53,23 +53,25 @@ application-owned length tokens. `plus` creates a non-standalone
 
 ```tsx
 import { calc, pct, plus, rem, space } from "@kerfjs/ui/css-values";
+import { Grid } from "@kerfjs/ui/grid";
 import { List } from "@kerfjs/ui/list";
 import { Row } from "@kerfjs/ui/row";
 
 <List gap="xs">...</List>;
+<Grid columns={3} gap="m">...</Grid>;
 <Row hAlign="full" vAlign="middle" gap="m">...</Row>;
 <List gap={space("m")}>...</List>;
 <List gap={calc(plus(rem(0.25), pct(10)))}>...</List>;
 ```
 
 `CssValue` is the common branded base, not an arbitrary-string constructor.
-Raw strings such as `"0.25rem"` no longer satisfy `Row.gap` or `List.gap`; this breaking
+Raw strings such as `"0.25rem"` do not satisfy `Row.gap`, `Grid.gap`, or `List.gap`; this
 contract lands before the 5.0 stable release so misspelled tokens and incomplete
 expressions fail during typechecking rather than in the browser.
 
 Other CSS-valued props use distinct contracts: `Spacer.width` and
 `Spacer.height` take `UiSpaceName | CssLength`; `flex()` creates `CssFlex` for
-`Row.flex` and `List.flex`; `Skeleton` dimensions take typed lengths (plus finite intrinsic
+`Row.flex`, `Grid.flex`, and `List.flex`; `Skeleton` dimensions take typed lengths (plus finite intrinsic
 keywords for width/height); and `uiColor()`/`colorVar()` create `CssColor` for
 `SelectChoice.color`. Do not substitute one brand for another. Row components
 have no declaration-string `style` prop; use `className`, documented public
@@ -126,6 +128,7 @@ an upstream component or recipe request.
 | Toolbar identity text — `ToolbarText`                                                                                   | A toolbar needs extra-large (page/panel title), large, default, or compact textual identity.                                                                                                                            | Plain text is not a heading by default; when a title needs heading semantics pass `headingLevel`.                                                                                                                                                                                                                                          | Optional `headingLevel` for `role="heading"` + `aria-level`. Defaults to one line, ellipsized when it does not fit; `wrap` flows onto multiple lines, `ellipsis` toggles the trailing …, and `maxLines` caps a wrap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Text, heading level, overflow behavior, and responsive priority.                                                                                         | `@kerfjs/ui/toolbar-text`                                                                 | [Toolbar composition](../README.md#component-subpaths)                              |
 | Semantic heading or paragraph — `Text`                                                                                  | Ordinary application copy needs native `h1`–`h6` or `p` semantics plus standard geometry, or a semantic quiet/danger tone, compact size, or monospace font.                                                             | Do not choose heading levels for appearance alone or recreate muted, error, small, or code utility classes. Use `ToolbarText` for toolbar identity/title content and `ListInsetText` when list-aligned prose needs full margin/border/padding geometry.                                                                                    | Omit `variant` for the default `p`, or choose `h1`–`h6` from the document outline. Independently compose `tone="quiet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | danger"`, `size="compact"`, and `font="monospace"`; ordinary native global, `data-_`, and `aria-_` attributes pass through.                              | Copy, localization, semantic variant, presentation roles, and document heading hierarchy. | `@kerfjs/ui/text`                                                                   | [Text](./layout.md#text) |
 | Vertical stack — `List`                                                                                                 | Rows, sections, or arbitrary components need a consistent vertical stretch layout, optional standard/custom gap, flex growth, one vertical scroll owner, or edge dividers.                                              | It is layout-only and does not provide `ul`/`ol` semantics. Do not nest scroll owners or use it when a horizontal layout is required.                                                                                                                                                                                                      | Choose `gap`, `flex`, `scrollable`, and canonical `dividerSides` (`t`, `r`, `b`, `l` combinations in that order); bound the block size when scrolling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Child semantics/content, containing height, and which optional layout behaviors apply.                                                                   | `@kerfjs/ui/list`                                                                         | [Pane geometry](../README.md#pane-and-content-geometry)                             |
+| Equal-width columns — `Grid`                                                                                            | A fixed positive number of sibling columns must divide the available width evenly, including when child content has different intrinsic widths.                                                                         | Do not use it for intrinsic, asymmetric, spanning, auto-fit, or masonry tracks; use application-owned CSS grid. Do not use it for a user-operable separator; use `ResizableRegion`.                                                                                                                                                        | Choose `columns`, a typed `gap`, and optional typed `flex`; preserve source order when the app changes the count responsively.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Child semantics/content, the column count and responsive policy, and typed gap/flex choices.                                                             | `@kerfjs/ui/grid`                                                                         | [Grid](./layout.md#grid)                                                            |
 | Navigation row — `ListItem`                                                                                             | A pane or navigation area needs a selectable, disabled, dormant-trailing, or multiline action row.                                                                                                                      | Do not put a control in `trailing`; use `ListActionRow` when the trailing region must be independently interactive. Use an `<a>` for navigation that must retain link behavior, a native `<button>` for an ordinary action, or implement the complete ARIA menu widget.                                                                    | Delegate its `data-action`; compose inside a `.kui-content` section. Put domain event/drop metadata in `rootAttributes` rather than adding wrapper markup. The rounded root clips overflowing descendants; set `multiline` when the primary label should wrap.                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Routing, selection, permissions, copy, action handling, and domain `data-*` values.                                                                      | `@kerfjs/ui/list-item`                                                                    | [Pane geometry](../README.md#pane-and-content-geometry)                             |
 | Navigation row with trailing action — `ListActionRow`                                                                   | A full-width row needs a selectable primary action and an independently focusable trailing action.                                                                                                                      | Use `ListItem` when trailing content is dormant metadata. Do not put controls inside the row's `label`, `icon`, or `trailingActionIcon` SafeHtml slots. Do not use `AppTab` outside tablist semantics or `ToolbarControlGroup` outside a toolbar.                                                                                          | Delegate both action strings; update controlled selection and any popover/context-menu state in the app.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Routing, selection, both action policies, domain metadata, and popover/context-menu behavior.                                                            | `@kerfjs/ui/list-action-row`                                                              | [Accessibility](./accessibility.md#listactionrow)                                   |
 | Navigation section heading — `ListHeader`                                                                               | A menu section needs a full-width label, semantic count, non-count badge, logical-end action, or real disclosure state.                                                                                                 | Do not concatenate counts into `label` or put numeric content in `badge`; use `count` with the localized full phrase in `countLabel`. Do not add a disclosure arrow to navigation that reveals nothing. Do not shrink its 44px action target to the 18px visual. Do not use it as a page, panel, or dialog title; use a heading `Toolbar`. | Delegate its optional action; the app controls expanded state and revealed content. Toggle mode supplies `DisclosureArrow` unless `actionIcon` replaces it. Use `triggerAttributes` only for domain `data-*` or a native popover relationship.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Section organization, valid count and localized count label, disclosure state and content, non-count badge content, popover target behavior, and policy. | `@kerfjs/ui/list-header`                                                                  | [Pane geometry](../README.md#pane-and-content-geometry)                             |
@@ -139,7 +142,7 @@ an upstream component or recipe request.
 | Standalone rail or drawer — `CollapsiblePanel`                                                                          | One left/right rail or bottom drawer needs controlled collapse without adopting the complete `Workbench` shell.                                                                                                         | Do not use it for several coordinated workspace panels or retain an empty icon-only rail while collapsed.                                                                                                                                                                                                                                  | Pair it with `CollapsiblePanelToggle`; call `wireSidebar` for focus transfer, Escape/backdrop dismissal, compact overlay trapping, and persistence integration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Panel content/size, collapsed state, toggle placement, persistence, and compact policy.                                                                  | `@kerfjs/ui/collapsible-panel`                                                            | [App-layout decision matrix](./app-layouts.md#decision-matrix)                      |
 | Lowered content surface — `SunkenPanel`                                                                                 | A main work area or nested content group needs one visually lowered surface with a compact inset and vertical stack.                                                                                                    | Do not use it merely to add padding, as a replacement for `Pane` anatomy, or around children that already own the same outer surface.                                                                                                                                                                                                      | Compose the application-owned content as children, choose the default `rounded` shape or `square` for a flush edge-to-edge area, and pass `ariaLabel` only when the surface is a distinct named region.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Region semantics, accessible name, shape, scroll ownership, child ordering, and content.                                                                 | `@kerfjs/ui/sunken-panel`                                                                 | [SunkenPanel](./sunken-panel.md)                                                    |
 | Menu composition                                                                                                        | Navigation sections need full-size rows and the same content-item geometry as every other pane.                                                                                                                         | Do not add sidebar-specific wrapper padding, shrink targets to icon size, nest an interactive trailing control in `ListItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract.                                                                                            | Compose `ListHeader`, `ListItem`, and `ListActionRow` in `.kui-content`; use `ListHeader` toggle mode with real controlled content, and use `.kui-content-item` for other surfaces plus a pane footer for toolbar actions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Information architecture, disclosure content and state, responsive drawer/shell behavior, and token overrides.                                           | `@kerfjs/ui/layout.css`                                                                   | [Pane geometry](../README.md#pane-and-content-geometry)                             |
-| Resizable application pane — `ResizableRegion`, `clampRegionSize`, `resizeRegionFromPointer`                            | A controlled split pane needs the Kerf separator, collapse state, pointer plus keyboard resizing, or a product-specific decorative grip.                                                                                | Do not use it for a static two-column layout; use CSS grid. Prefer it over Web Awesome `wa-split-panel` unless that component's distinct API is required. Keep `handleIcon` noninteractive.                                                                                                                                                | Call `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` once and retain its disposer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Size signal, min/max policy, collapse policy, persistence, and optional decorative handle icon.                                                          | `@kerfjs/ui/resizable-region`                                                             | [ResizableRegion contract](./accessibility.md#resizableregion)                      |
+| Resizable application pane — `ResizableRegion`, `clampRegionSize`, `resizeRegionFromPointer`                            | A controlled split pane needs the Kerf separator, collapse state, pointer plus keyboard resizing, or a product-specific decorative grip.                                                                                | Do not use it for static equal columns; use `Grid`. Use application CSS grid for static asymmetric or intrinsic tracks. Prefer it over Web Awesome `wa-split-panel` unless that component's distinct API is required. Keep `handleIcon` noninteractive.                                                                                    | Call `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` once and retain its disposer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Size signal, min/max policy, collapse policy, persistence, and optional decorative handle icon.                                                          | `@kerfjs/ui/resizable-region`                                                             | [ResizableRegion contract](./accessibility.md#resizableregion)                      |
 | One application tab — `AppTab`                                                                                          | A controlled app tab needs selection, close, drag, leading/trailing anatomy, compact/segmented/icon-only presentation, label truncation, safe domain metadata, or a product-specific close glyph.                       | Do not render it alone or use it for a small settings choice; compose in `TabBar`, or use `SegmentedControl`. Keep `closeIcon` noninteractive.                                                                                                                                                                                             | Compose in `TabBar`; let `wireTabBars` manage interaction. Put only domain `data-*` values in `rootAttributes`; use typed appearance props instead of descendant CSS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Tab identity, order, selection, close policy, content, domain metadata values, and outer placement.                                                      | `@kerfjs/ui/app-tab`                                                                      | [Tabs contract](./accessibility.md#tabs)                                            |
 | Application tab strip — `TabBar`, `wireTabBars`, `reorderTabs`                                                          | Tabs switch page regions and may overflow, close, reorder, fill a segmented inspector strip, or sit beside a trailing action.                                                                                           | Do not use it for a compact local view toggle; use `SegmentedControl`. Do not use it for a long choice list; use `Select`. Prefer it over Web Awesome `wa-tab-group`, `wa-tab`, and `wa-tab-panel` for Kerf app tabs.                                                                                                                      | Call `wireTabBars` once, retain the disposer, and apply `onReorder` synchronously; `reorderTabs` is the default array helper. Choose typed presentation/allocation props while the parent owns outer placement.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Ordered tabs, selection, panels, routing, closing, persistence, and outer placement.                                                                     | `@kerfjs/ui/tab-bar` plus `@kerfjs/ui/wire-tab-bars`                                      | [Tabs contract](./accessibility.md#tabs)                                            |
 | Panel, dialog, or page heading — `Toolbar` + `ToolbarText`                                                              | A panel, dialog, or page needs an extra-large title, optional icon, grouped trailing actions, and optional supporting copy.                                                                                             | Do not add a private heading wrapper or bespoke layout. The toolbar supplies structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior.                                                                                                                                                       | Connect title/supporting-copy ids to the host, group controls, and delegate actions. **For a page or view title set `headingLevel` (usually `1`)** on `ToolbarText`; omit it for a dialog title referenced by `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Open state, focus lifecycle, dismissal, controls, ids, copy, and heading level.                                                                          | `@kerfjs/ui/toolbar` + `@kerfjs/ui/toolbar-text`                                          | [Toolbar headings](./accessibility.md#toolbar-headings)                             |
@@ -158,7 +161,7 @@ an upstream component or recipe request.
 - `Toolbar` serves persistent app chrome and headings; the zone contents and accessible naming distinguish the purpose.
 - `TabBar` changes tabpanels and supports overflow/reorder; `SegmentedControl` chooses among a few compact views; `Select` handles a longer value list.
 - `StateBanner` persists beside affected work; `EmptyState` replaces absent content; `wa-callout` is contextual ecosystem content; `wa-toast` and `wa-toast-item` are transient and must not carry the only copy of important state.
-- `ResizableRegion` is an interactive controlled pane. CSS grid is the right answer when columns do not need a user-operable separator.
+- `ResizableRegion` is an interactive controlled pane. `Grid` is the right answer for static equal-width columns; application CSS grid remains the answer for asymmetric or intrinsic tracks.
 - A `ResizableRegion` overlay automatically clamps both its track and fixed-size
   animated content to the responsive overlay maximum. Set the policy and maximum
   on the component instead of adding application descendant width/height fixes.

package/docs/layout.md

@@ -112,7 +112,7 @@ The two relationships that get confused most are 8px vs 24px: 8px is _inside_ a
 group, 24px is _between_ major, differing regions. 16px sits between them for
 same-kind groups.
 
-For `Row.gap` and `List.gap`, pass these token names directly (`gap="xs"`, `gap="m"`) or use
+For `Row.gap`, `Grid.gap`, and `List.gap`, pass these token names directly (`gap="xs"`, `gap="m"`) or use
 `space('xs')` from `@kerfjs/ui/css-values` when composing a value in JavaScript.
 Use `rem`, `em`, `px`, `pct`, `lengthVar`, and `calc(plus(...))` only when a
 named spacing relationship does not express the requirement; do not pass raw
@@ -169,6 +169,29 @@ uses physical width and height. Prefer `Row.gap` or `List.gap` for uniform
 sibling rhythm, and never use Spacer to cancel or duplicate component-owned
 insets.
 
+## Grid
+
+Use `Grid` from `@kerfjs/ui/grid` when a fixed positive number of columns must
+share the available width evenly. Every track is `minmax(0, 1fr)`, so a child
+with wider intrinsic content cannot make its column wider than its peers. Grid
+defaults to the `xs` gap and accepts the same finite spacing names, complete
+typed `CssLength` values, and typed flex-participation contract as Row.
+
+```tsx
+import { Grid } from "@kerfjs/ui/grid";
+
+<Grid columns={2} gap="m">
+  <label>Quantity <input /></label>
+  <label>Unit <input /></label>
+</Grid>;
+```
+
+`columns` must be a positive safe integer; invalid counts throw instead of
+silently producing invalid CSS. Grid is layout-only and adds no ARIA grid role.
+The application owns child semantics and responsive count changes. Use
+application-owned CSS grid for intrinsic, asymmetric, spanning, auto-fit, or
+masonry tracks, and use `ResizableRegion` when people must adjust a boundary.
+
 ## Row and List alignment
 
 Use `Row` for a horizontal flex layout and `List` for a vertical one. `Row`

package/docs/webawesome-theme.md

@@ -97,6 +97,10 @@ tiers:
   complete surface and the inset within it. Accordion applies the outer margin
   once to the group rather than separating connected items; Card's header,
   body, and footer all receive the full inset.
+- Plain Accordion and Details remove inline padding from both their trigger and
+  content so their text aligns directly with the surrounding flow. Outlined and
+  sunken disclosure triggers use the 16px `--kui-wa-container-inset`, one 8px
+  step beyond their compact body inset.
 - `appearance="sunken"` is a Kerf theme extension for Accordion, Card, and
   Details. It removes raised chrome, paints the lowered semantic surface, and
   uses the shared rounded-rectangle radius. Override
@@ -177,10 +181,9 @@ component should declare the no-arrow choice independent of theme context.
 The UX catalog includes a focused, addressable specimen for every component in
 this list. Because these are themed ecosystem components rather than
 first-class `@kerfjs/ui` exports, the sidebar keeps them under a collapsible
-`Web Awesome` heading with category subgroups. The aggregate theme route
-remains a broad visual-regression surface, while modal, drawer, toast, media,
-and helper routes make their own behavior inspectable without opening every
-state at once.
+`Web Awesome` heading with category subgroups. There is no aggregate theme
+route: the focused modal, drawer, toast, media, and helper routes make each
+component's behavior inspectable without opening every state at once.
 
 ## Badge and tag guidance
 

package/llms.txt

@@ -107,10 +107,17 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   for List flex, typed lengths for Skeleton geometry, and
   `uiColor()`/`colorVar()` for choice-icon colors. These brands are intentionally
   not interchangeable; rows use classes/tokens/props rather than raw `style`.
+- **Use `Grid` for a fixed positive count of equal-width columns.** It uses
+  zero-minimum fractional tracks, so intrinsic content cannot make one column
+  wider than its peers. The app owns responsive count changes; use custom CSS
+  grid for asymmetric/intrinsic tracks and `ResizableRegion` for adjustable
+  boundaries. `Grid.gap` and `Grid.flex` use the same typed grammars as Row.
 - **Keep Web Awesome on the shared inset tiers.** `webawesome.css` uses
   `--kui-wa-control-inset` (8px controls/items) and
   `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside
   Accordion, Card, Details, Callout, and Include), while
+  plain Accordion/Details remove inline trigger/body padding and their
+  outlined/sunken headers use the 16px container inset,
   `--kui-wa-container-inset` keeps Tab Panel at 16px. Dialog body and footer use
   the surface (8px) and container (16px) tiers respectively, independent of the
   dialog's shared `--spacing`. Override the tier at the narrowest useful scope

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.48",
+  "version": "5.0.0-beta.49",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -98,6 +98,11 @@
       "browser": "./dist/browser/row.js",
       "import": "./dist/row.js"
     },
+    "./grid": {
+      "types": "./dist/grid.d.ts",
+      "browser": "./dist/browser/grid.js",
+      "import": "./dist/grid.js"
+    },
     "./spacer": {
       "types": "./dist/spacer.d.ts",
       "browser": "./dist/browser/spacer.js",
@@ -295,6 +300,7 @@
     "./text.css": "./dist/styles/text.css",
     "./list.css": "./dist/styles/list.css",
     "./row.css": "./dist/styles/row.css",
+    "./grid.css": "./dist/styles/grid.css",
     "./spacer.css": "./dist/styles/spacer.css",
     "./list-action-row.css": "./dist/styles/list-action-row.css",
     "./list-item.css": "./dist/styles/list-item.css",