@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/ai/components/edge-activity-indicator.md

@@ -0,0 +1,81 @@
+# EdgeActivityIndicator
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:edge-activity-indicator` · Kerf UI · component · Feedback
+
+A layout-free top-edge activity strip with a traveling wave and an optional hanging status pill.
+
+## When to use
+
+Signal ambient background activity (server work, sync) along the top edge of the viewport without allocating layout or taking the pointer, with Kerf-owned motion and reduced-motion handling.
+
+- Ambient, app-wide background activity (server work, sync) should be visible without a modal, a banner, or any layout shift.
+
+**Not when:**
+
+- Do not use for progress the user waits on or must read; use CornerStatus or a StateBanner.
+- Do not use for known progress; use a progress bar.
+- Do not use it as the only record of important state; the bars are hidden from assistive technology.
+
+**Alternatives:**
+
+- [CornerStatus](./corner-status.md) (nearest) — Use CornerStatus for readable, non-dismissible app-level progress.
+- [LoadingSpinner](./loading-spinner.md) (nearest) — Use LoadingSpinner for local activity beside the affected control.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/edge-activity-indicator` — exports `EdgeActivityIndicator`.
+- CSS: the browser build of `@kerfjs/ui/edge-activity-indicator` pulls its CSS automatically; import `@kerfjs/ui/edge-activity-indicator.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/edge-activity-indicator`](../public-api-signatures-v1.md#kerfjsuiedge-activity-indicator) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- busy or idle
+- with or without a status pill
+- semantic tone
+- safe-area inset or flush
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the busy state; the optional status message; the tone.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Fixed to the top edge below the device safe area; it allocates no layout.
+
+## Accessibility
+
+- The strip is aria-hidden and pointer-inert; the optional pill is a polite live region that holds text only while it shows. Under reduced motion the wave and scale stop and the strip and pill only fade.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-edge-activity-indicator`, `kui-edge-activity-indicator__strip`, `kui-edge-activity-indicator__message`.
+
+Never put `kui-edge-activity-indicator`, `kui-edge-activity-indicator__strip`, `kui-edge-activity-indicator__message` on an element you write; render `EdgeActivityIndicator` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-edge-activity-indicator-z-index`, `--kui-safe-area-block-start`, `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-pop-fill-loud`, `--kui-color-pop-on-loud`, `--kui-color-success-fill-loud`, `--kui-color-success-on-loud`, `--kui-color-warning-fill-loud`, `--kui-color-warning-on-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-font-2xs`, `--kui-space-m`, `--kui-space-s`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [CornerStatus](./corner-status.md), [LoadingSpinner](./loading-spinner.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=edge-activity-indicator`.

package/ai/components/empty-state.md

@@ -0,0 +1,80 @@
+# EmptyState
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:empty-state` · Kerf UI · component · Feedback
+
+## When to use
+
+Actionable empty and busy content states.
+
+- Explain absent or busy content and offer an optional recovery action.
+
+**Not when:**
+
+- Do not use for an inline update or transient success.
+
+**Alternatives:**
+
+- [StateBanner](./state-banner.md) (nearest)
+- [Toast](./wa-toast.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/empty-state` — exports `EmptyState`.
+- CSS: the browser build of `@kerfjs/ui/empty-state` pulls its CSS automatically; import `@kerfjs/ui/empty-state.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/empty-state`](../public-api-signatures-v1.md#kerfjsuiempty-state) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- actionable
+- busy
+- illustrated
+
+## Composition
+
+- Parents: any.
+- Contexts: `empty-content`, `busy-content`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md), [LoadingSpinner](./loading-spinner.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `icon` — JSX prop `icon`; accepts `dormant-decoration`; 0–1.
+- `action` — JSX prop `action`; accepts `control`; 0–1.
+
+## State and wiring
+
+**The app owns:** empty/busy policy; recovery action; copy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Busy state uses aria-busy; the illustration never supplies the only label.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-empty-state`, `kui-empty-state__action`, `kui-empty-state__icon`.
+
+Never put `kui-empty-state`, `kui-empty-state__action`, `kui-empty-state__icon` on an element you write; render `EmptyState` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-on-quiet`, `--kui-color-text`, `--kui-empty-state-foreground`, `--kui-empty-state-title`, `--kui-font-l`, `--kui-font-s`, `--kui-space-xl`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [LoadingSpinner](./loading-spinner.md), [StateBanner](./state-banner.md), [Toast](./wa-toast.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#ambiguous-choices`](../../docs/component-selection.md#ambiguous-choices).
+- UX catalog route: `?component=empty-state`.

package/ai/components/feedback.md

@@ -0,0 +1,71 @@
+# Feedback
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:feedback` · Kerf UI · CSS composition · Feedback
+
+## When to use
+
+Banners, empty states, and labeled progress.
+
+- Compose persistent status, empty/busy content, and compact loading feedback.
+
+**Not when:**
+
+- Do not collapse different message lifetimes or urgency into one visual treatment.
+
+**Alternatives:**
+
+- [StateBanner](./state-banner.md) (nearest)
+- [EmptyState](./empty-state.md) (nearest)
+- [Callout](./wa-callout.md) (prefer-over)
+- [Toast](./wa-toast.md) (prefer-over)
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- banner
+- empty
+- busy
+- spinner
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md).
+
+## State and wiring
+
+**The app owns:** state mapping; message lifetime; recovery policy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: child · border: child · padding: child (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Choose polite status versus assertive alert deliberately.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md), [Callout](./wa-callout.md), [Toast](./wa-toast.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#ambiguous-choices`](../../docs/component-selection.md#ambiguous-choices).
+- UX catalog route: `?component=feedback`.

package/ai/components/file-picker.md

@@ -0,0 +1,88 @@
+# FilePicker
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:file-picker` · Kerf UI · component · Controls
+
+A compact browse trigger and a dashed drop zone around native file inputs, with wiring that reports chosen and dropped files.
+
+## When to use
+
+Let people choose or drop files (attachments, evidence, imports) without app CSS: a link-toned browse trigger and a dashed drop target that highlights while dragging, both around visually hidden native file inputs.
+
+- People attach or import files by browsing or by dropping them onto a target.
+
+**Not when:**
+
+- Do not style a native file input or label from app CSS; use these components.
+- Do not rely on the drop zone alone; it also opens the chooser when clicked or activated from the keyboard.
+
+**Alternatives:**
+
+- [Button](./wa-button.md) (prefer-over) — A button cannot open the native chooser without script; the trigger is a label around the input.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/file-picker` — exports `FilePickerTrigger`, `FileDropZone`, `wireFilePickers`, `fileMatchesAccept`.
+- CSS: the browser build of `@kerfjs/ui/file-picker` pulls its CSS automatically; import `@kerfjs/ui/file-picker.css` manually only without the `browser` export condition.
+- Wiring: `wireFilePickers` from `@kerfjs/ui/wire-file-pickers` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/file-picker`](../public-api-signatures-v1.md#kerfjsuifile-picker) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- browse trigger
+- drop zone
+- dragging
+- disabled
+- accept filter
+- multiple or single
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** what happens to the reported files (upload, validation, limits); the list of chosen files; copy and accepted types.
+
+**Wiring:** `wireFilePickers` is required.
+
+- Reports chosen and dropped files and accepts drops on the zone; without it drops open the file in the browser.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-dragging` on `kui-file-picker (drop zone)` (`wireFilePickers`): "true" while files are dragged over the zone.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The drop zone carries the 8px content-item inline margin; the trigger is a compact 32px inline control.
+
+## Accessibility
+
+- Each control is a label around a real file input that receives keyboard focus; the visible control shows the focus ring. Give the input an accessibleLabel when the visible copy is short.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-file-picker`, `kui-file-picker__title`, `kui-file-picker__detail`, `kui-file-picker__input`, `kui-file-picker__icon`.
+
+Never put `kui-file-picker`, `kui-file-picker__title`, `kui-file-picker__detail`, `kui-file-picker__input`, `kui-file-picker__icon` on an element you write; render `FilePickerTrigger` or `FileDropZone` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-text-link`, `--kui-color-brand-fill-quiet`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-text`, `--kui-focus-ring`, `--kui-font-xs`, `--kui-font-2xs`, `--kui-font-weight-semibold`, `--kui-layout-inline-margin`, `--kui-layout-rounded-radius`, `--kui-radius-pill`, `--kui-space-2xs`, `--kui-space-s`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Button](./wa-button.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=file-picker`.

package/ai/components/floating-toolbar.md

@@ -0,0 +1,82 @@
+# FloatingToolbar
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:floating-toolbar` · Kerf UI · component · Structure
+
+## When to use
+
+A transparent, forced-dark toolbar that floats over its container's content.
+
+- Float a small cluster of controls (e.g. a drawer restore) over scrolling content without covering dialogs.
+
+**Not when:**
+
+- Do not use for a primary page or panel toolbar, or for anything that must sit above overlays (it is not top-layer).
+
+**Alternatives:**
+
+- [Toolbar](./toolbar.md) (nearest)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/floating-toolbar` — exports `FloatingToolbar`.
+- CSS: the browser build of `@kerfjs/ui/floating-toolbar` pulls its CSS automatically; import `@kerfjs/ui/floating-toolbar.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/floating-toolbar`](../public-api-signatures-v1.md#kerfjsuifloating-toolbar) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- bottom-end
+- bottom-start
+- bottom
+- top-end
+- top-start
+- top
+- inline placement
+- safe-area-aware per-edge inset
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `inset`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `inset={space("xs")}`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** controls; position; visibility.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: child · padding: child (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Give the toolbar an accessible name (label is required — it exposes role="toolbar").
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-floating-toolbar`.
+
+Never put `kui-floating-toolbar` on an element you write; render `FloatingToolbar` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-floating-toolbar-inset`, `--kui-floating-toolbar-inset-block-start`, `--kui-floating-toolbar-inset-block-end`, `--kui-floating-toolbar-inset-inline-start`, `--kui-floating-toolbar-inset-inline-end`, `--kui-space-m`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Toolbar](./toolbar.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=floating-toolbar`.

package/ai/components/foundation.md

@@ -0,0 +1,65 @@
+# Foundation Tokens
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:foundation` · Kerf UI · CSS composition · Foundation
+
+The complete public typography, spacing, breakpoint, geometry, radius, color, focus, and shadow token surface shipped by foundation.css.
+
+## When to use
+
+Provide the shared semantic token foundation for application themes and every styled Kerf UI component.
+
+- Theme a Kerf application globally or reuse the shipped semantic typography, spacing, geometry, color, focus, and shadow values in application-owned composition CSS.
+
+**Not when:**
+
+- Do not replace a component-specific prop or token with a broad foundation override when only one component instance should change.
+
+## Imports
+
+- CSS: import `@kerfjs/ui/foundation.css` once.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- light
+- dark
+- increased contrast
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** application theme overrides; responsive policy at the cataloged device-class breakpoints.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Preserve semantic contrast relationships and the visible focus ring when overriding foundation colors.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public tokens it reads: `--kui-font-sans`, `--kui-font-mono`, `--kui-font-2xs`, `--kui-font-xs`, `--kui-font-s`, `--kui-font-m`, `--kui-font-l`, `--kui-font-xl`, `--kui-font-2xl`, `--kui-font-weight-semibold`, `--kui-space-none`, `--kui-space-2xs`, `--kui-space-xs`, `--kui-space-s`, `--kui-space-m`, `--kui-space-l`, `--kui-space-xl`, `--kui-bp-mobile`, `--kui-bp-tablet`, `--kui-bp-desktop`, `--kui-bp-xl-desktop`, `--kui-layout-inline-margin`, `--kui-layout-item-border-width`, `--kui-layout-item-padding`, `--kui-layout-item-gap`, `--kui-layout-content-gap`, `--kui-layout-control-gap`, `--kui-layout-metadata-gap`, `--kui-layout-highlight-inset`, `--kui-layout-rounded-radius`, `--kui-layout-pill-radius`, `--kui-toolbar-group-inner-size`, `--kui-toolbar-group-size`, `--kui-toolbar-gap`, `--kui-safe-area-block-start`, `--kui-safe-area-block-end`, `--kui-safe-area-inline-start`, `--kui-safe-area-inline-end`, `--kui-radius-s`, `--kui-radius-m`, `--kui-radius-l`, `--kui-radius-circle`, `--kui-radius-pill`, `--kui-disclosure-icon-scale`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-color-surface-lowered`, `--kui-sunken-texture`, `--kui-sunken-surface`, `--kui-chrome-material`, `--kui-chrome-material-raised`, `--kui-chrome-material-filter`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-text-link`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-border-normal`, `--kui-color-brand-border-loud`, `--kui-color-brand-on-quiet`, `--kui-color-brand-on-normal`, `--kui-color-brand-on-loud`, `--kui-color-brand-on-fill`, `--kui-color-pop-fill-loud`, `--kui-color-pop-fill-quiet`, `--kui-color-pop-fill-normal`, `--kui-color-pop-border-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-border-loud`, `--kui-color-pop-on-quiet`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-loud`, `--kui-color-pop-on-fill`, `--kui-color-success-fill-loud`, `--kui-color-success-fill-quiet`, `--kui-color-success-fill-normal`, `--kui-color-success-border-quiet`, `--kui-color-success-border-normal`, `--kui-color-success-border-loud`, `--kui-color-success-on-quiet`, `--kui-color-success-on-normal`, `--kui-color-success-on-loud`, `--kui-color-success-on-fill`, `--kui-color-warning-fill-loud`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-fill-normal`, `--kui-color-warning-border-quiet`, `--kui-color-warning-border-normal`, `--kui-color-warning-border-loud`, `--kui-color-warning-on-quiet`, `--kui-color-warning-on-normal`, `--kui-color-warning-on-loud`, `--kui-color-warning-on-fill`, `--kui-color-danger-fill-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-fill-normal`, `--kui-color-danger-border-quiet`, `--kui-color-danger-border-normal`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-color-danger-on-normal`, `--kui-color-danger-on-loud`, `--kui-color-danger-on-fill`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-shadow-l`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#foundation-tokens`](../../docs/component-selection.md#foundation-tokens).
+- UX catalog route: `?component=foundation`.

package/ai/components/framed-list.md

@@ -0,0 +1,80 @@
+# FramedList
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:framed-list` · Kerf UI · component · Structure
+
+An inset-grouped list: one rounded, bordered frame with dividers between rows of arbitrary content.
+
+## When to use
+
+Group settings-style rows of arbitrary content (copy, keycaps, controls) in one framed surface with between-row dividers and an optional highlighted row, without app list CSS.
+
+- Settings rows, account or source cards, or shortcut lists group several rows of arbitrary content in one framed surface.
+
+**Not when:**
+
+- Do not use for read-only label/value facts; use ValueTable.
+- Do not use for selectable navigation rows; use List with ListItem.
+- Do not pad or border its rows from application CSS; FramedListRow owns the inset and divider.
+
+**Alternatives:**
+
+- [ValueTable](./value-table.md) (nearest) — Use ValueTable when every row is a label and a value.
+- [List](./list.md) (nearest) — Use List with ListItem for navigation or selectable rows.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/framed-list` — exports `FramedList`, `FramedListRow`.
+- CSS: the browser build of `@kerfjs/ui/framed-list` pulls its CSS automatically; import `@kerfjs/ui/framed-list.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/framed-list`](../public-api-signatures-v1.md#kerfjsuiframed-list) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- lowered surface
+- base surface
+- highlighted row
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** row content and its controls; which row is highlighted; the list's accessible name.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Rows own the 8px inset and the inset 1px divider above them; the frame owns the 8px margin, border, and radius.
+
+## Accessibility
+
+- Renders a list (ul role=list, li rows); pass label when no heading names it. Highlight is visual; carry its meaning in row content or a control's state.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-framed-list`, `kui-framed-list__row`.
+
+Never put `kui-framed-list`, `kui-framed-list__row` on an element you write; render `FramedList` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-framed-list-border`, `--kui-color-neutral-border-normal`, `--kui-color-surface-lowered`, `--kui-color-surface`, `--kui-color-brand-fill-quiet`, `--kui-layout-inline-margin`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [ValueTable](./value-table.md), [List](./list.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=framed-list`.

package/ai/components/grid.md

@@ -0,0 +1,101 @@
+# Grid
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:grid` · Kerf UI · component · Structure
+
+Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, physical-side text/control insets, and optional flex participation.
+
+## When to use
+
+Arrange related siblings in equal-width columns with either a fixed count or automatic container-width collapse.
+
+- Arrange related siblings into a fixed positive number of equal-width columns.
+- Fit equal-width columns down to a typed minimum and collapse as the container narrows.
+- 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.
+
+**Not when:**
+
+- Do not use Grid for intrinsic, asymmetric, spanning, or masonry tracks; use application-owned CSS grid.
+- Do not use Grid when columns need a user-operable separator; use ResizableRegion.
+- Do not combine fixed columns with minColumnWidth; choose one layout mode.
+- 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:**
+
+- [Row](./row.md) (axis-alternative) — Use Row for one horizontal flex line, alignment, or wrapping rather than fixed equal tracks.
+- [List](./list.md) (axis-alternative) — Use List when the main layout axis is vertical.
+- [ResizableRegion](./resize.md) (interactive-alternative) — Use ResizableRegion when people must adjust the boundary between tracks.
+- [ColumnTrack](./column-track.md) (nearest) — Use ColumnTrack for a board of columns that scroll sideways or page instead of wrapping.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/grid` — exports `Grid`.
+- CSS: the browser build of `@kerfjs/ui/grid` pulls its CSS automatically; import `@kerfjs/ui/grid.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/grid`](../public-api-signatures-v1.md#kerfjsuigrid) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- any positive safe-integer equal-track count
+- typed minimum column width with automatic container-width collapse
+- named none/2xs/xs/s/m/l/xl token gap
+- typed CssLength gap
+- boolean, finite-keyword, or typed CssFlex flex
+- top/right/bottom/left text and control inset combinations
+- fill: the layout root fills a definite-height parent
+- rootAttributes: safe data-\* metadata on the root
+- selectionMode=multiple: labeled multi-select grid for ContentItem tiles
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `minColumnWidth`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `minColumnWidth={px(376)}`
+- `gap`: length grammar; raw values: forbid; shorthands `none`, `2xs`, `xs`, `m`, `l`; exceptional (justify) `s`, `xl`; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `gap="m"`
+- `flex`: flex grammar; raw values: forbid; shorthands `none`, `auto`, `initial`; helpers `flex` — e.g. `flex`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** child semantics and content; fixed column count or responsive minimum width; typed gap, flex, and physical-side inset choices.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: conditional (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- textInsets adds 17px and controlInsets adds 8px on selected physical sides; text wins on overlap.
+- Fixed tracks use minmax(0, 1fr); responsive tracks use auto-fit with a minimum width capped at 100%, preserving equal distribution without narrow overflow.
+
+## Accessibility
+
+- Grid adds no role by default; selectionMode=multiple requires ariaLabel and supplies a multi-select grid for ContentItem row/gridcell tiles.
+- wireContentItems uses rendered tile positions for Left/Right/Up/Down and reaches the first or last tile with Home/End.
+- Responsive column-count changes preserve source and focus order.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-grid`.
+
+Never put `kui-grid` on an element you write; render `Grid` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-grid-gap`, `--kui-layout-item-gap`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Row](./row.md), [List](./list.md), [ResizableRegion](./resize.md), [ColumnTrack](./column-track.md).
+- Docs: [`docs/layout.md`](../../docs/layout.md), [`docs/layout.md#grid`](../../docs/layout.md#grid).
+- UX catalog route: `?component=grid`.