@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.100

package/ai/components/combobox.md

@@ -0,0 +1,88 @@
+# Combobox
+
+<!-- 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:combobox` · Kerf UI · component · Controls
+
+A free-text field with a filtered suggestion list that can also create a new value.
+
+## When to use
+
+Let people pick an existing value or create a new one by typing (tags, labels, recipients), with the themed field chrome, the ARIA combobox pattern, and a touch-safe font size, without a native datalist or app CSS.
+
+- People type to find an existing value among many, or create a new one (tags, labels, recipients).
+
+**Not when:**
+
+- Do not use when only existing values are allowed and nothing needs typing; use Select.
+- Do not use for free text plus removable filter tokens in one editor; use TokenSearchField.
+- Do not style a native input with a datalist from app CSS.
+
+**Alternatives:**
+
+- [Select](./select.md) (nearest) — Use Select when only existing values are allowed.
+- [TokenSearchField](./token-search-field.md) (nearest) — Use TokenSearchField for search text with removable filter tokens.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/combobox` — exports `Combobox`, `wireComboboxes`.
+- CSS: the browser build of `@kerfjs/ui/combobox` pulls its CSS automatically; import `@kerfjs/ui/combobox.css` manually only without the `browser` export condition.
+- Wiring: `wireComboboxes` from `@kerfjs/ui/wire-comboboxes` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/combobox`](../public-api-signatures-v1.md#kerfjsuicombobox) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- with create
+- suggestions only (createLabel={false})
+- hint
+- disabled
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the suggestions and the committed values; normalizing and validating created values; clearing the field after a commit.
+
+**Wiring:** `wireComboboxes` is required.
+
+- Filters suggestions, moves the active option, and reports commits; without it the list never opens.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-value` on `the create option (kui-combobox__option[data-create])` (`wireComboboxes`): The typed text the create option would commit; rewritten as the person types.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Label and hint sit on the value's text column (1px border + 8px padding); the 44px field matches a themed wa-input.
+
+## Accessibility
+
+- Native input with role=combobox, aria-autocomplete=list, aria-expanded, aria-controls, and aria-activedescendant; options are role=option in a listbox. The visible label is a real label; the hint is aria-describedby.
+
+## 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-combobox`, `kui-combobox__label`, `kui-combobox__hint`, `kui-combobox__control`, `kui-combobox__input`, `kui-combobox__listbox`, `kui-combobox__option`.
+
+Never put `kui-combobox`, `kui-combobox__label`, `kui-combobox__hint`, `kui-combobox__control`, `kui-combobox__input`, `kui-combobox__listbox`, `kui-combobox__option` on an element you write; render `Combobox` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-combobox-z-index`, `--kui-color-neutral-on-quiet`, `--kui-color-text-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-text`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-color-text-link`, `--kui-color-brand-fill-quiet`, `--kui-font-xs`, `--kui-font-s`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`, `--kui-shadow-l`, `--kui-space-2xs`, `--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: [Select](./select.md), [TokenSearchField](./token-search-field.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=combobox`.

package/ai/components/composer.md

@@ -0,0 +1,83 @@
+# Composer
+
+<!-- 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:composer` · Kerf UI · component · Controls
+
+A raised chat or prompt composer: a framed message field that grows with its content above an action row with a hint and a send button.
+
+## When to use
+
+Write a chat message or prompt in a raised frame whose border turns brand while focus is within, with a field that grows between row bounds and a trailing send action.
+
+- Write a chat message, assistant prompt, or comment reply that is sent with a trailing action, especially in a DialogSurface floating footer over a transcript.
+
+**Not when:**
+
+- Use wa-textarea with a FieldLabel for an ordinary form field that is submitted with the rest of a form.
+- Do not wrap it in another framed ContentItem or card; it owns its frame, padding, and shadow.
+
+**Alternatives:**
+
+- [Textarea](./wa-textarea.md) (prefer-over) — Use Composer instead of a wa-textarea and a button in app-styled chrome for a chat or prompt composer; it owns the raised frame, focus-within border, auto-grow, and action row.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/composer` — exports `Composer`, `wireComposers`.
+- CSS: the browser build of `@kerfjs/ui/composer` pulls its CSS automatically; import `@kerfjs/ui/composer.css` manually only without the `browser` export condition.
+- Wiring: `wireComposers` from `@kerfjs/ui/wire-composers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/composer`](../public-api-signatures-v1.md#kerfjsuicomposer), [`@kerfjs/ui/wire-composers`](../public-api-signatures-v1.md#kerfjsuiwire-composers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- minRows and maxRows bounds for the growing field
+- optional hint, described by the field when an id is given
+- disabled field
+- submitOnEnter: Enter or Cmd/Ctrl+Enter activates the first trailing action, Shift+Enter inserts a newline (with wireComposers)
+- slotted into a DialogSurface floating footer
+
+## Composition
+
+- Parents: any.
+- Contexts: `chat-composer`, `dialog-floating-footer`.
+- Children: unrestricted.
+- Built from: [Text](./text.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `actions` — JSX prop `actions`; accepts `KerfUiContent`; at least 1.
+
+## State and wiring
+
+- value — controlled
+
+**Wiring:** `wireComposers` is optional.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Name the message field with label in title style; give it an id so a hint becomes its accessible description.
+- Give every trailing action a visible or accessible name, such as a Send button.
+
+## 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-composer`.
+
+Never put `kui-composer` on an element you write; render `Composer` instead (`KUI-L103`).
+
+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: [Text](./text.md), [Textarea](./wa-textarea.md).
+- Docs: [`docs/composer.md`](../../docs/composer.md), [`docs/accessibility.md#composer`](../../docs/accessibility.md#composer).
+- UX catalog route: `?component=composer`.

package/ai/components/content-item.md

@@ -0,0 +1,98 @@
+# ContentItem
+
+<!-- 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:content-item` · Kerf UI · component · Structure
+
+One self-contained content child with shared geometry plus typed transparent, surface, or semantic appearance, frame, and shape choices.
+
+## When to use
+
+Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.
+
+- An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.
+- A content item marks a real distinction and must read as visibly bounded: pass frame="framed" (the border is always reserved, so geometry does not change).
+- A content item needs the base surface or a coordinated semantic status treatment: pass appearance="surface" or a semantic appearance such as success or danger.
+- A content item should follow a pill control's 22px radius: pass shape="pill".
+- A selectable rich card needs nested controls: use selectionMode="multiple" inside a labeled List multi-select grid.
+
+**Not when:**
+
+- Do not wrap a component that already owns content-item geometry (ListItem, ListHeader, StateBanner, Toolbar, ValueTable) or pad around a ContentItem; either double-insets.
+- Do not frame an item only to make it look contained; hierarchy comes from alignment, spacing, and type first.
+- Do not use its surface appearance for a lowered inset panel around a stack; use SunkenPanel for that structure.
+- Do not use it for bare text alone; use ListInsetText, which adds the same inset without claiming a surface.
+
+**Alternatives:**
+
+- [ListInsetText](./list-inset-text.md) (nearest) — Use ListInsetText when bare text only needs to align with neighboring content items.
+- [SunkenPanel](./sunken-panel.md) (nearest) — Use SunkenPanel for a lowered, filled surface around a vertical stack.
+- [Application Layout](./layout.md) (composes-with) — Place ContentItem children in a Pane or .kui-content stack, which owns the 24px major rhythm.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/content-item` — exports `ContentItem`.
+- CSS: the browser build of `@kerfjs/ui/content-item` pulls its CSS automatically; import `@kerfjs/ui/content-item.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures-v1.md#kerfjsuicontent-item) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- unframed rounded item
+- framed rounded item
+- pill item
+- framed pill item
+- base surface item
+- neutral, info, pop, success, warning, or danger semantic item
+- brand-loud item (solid brand fill, on-loud foreground)
+- chat bubble at the start or end of the row (bubble), fit to its content up to 80%
+- named focus-target region
+- multi-select rich grid row
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the item content; whether the item marks a real distinction that warrants a visible frame; whether the item needs a surface or semantic appearance; corner shape; region semantics and accessible name; whether the item is a programmatic focus target; optional static-item Tab stop and persistent focus outline; the selection set and Shift/Cmd extension for multi-select rich cards.
+
+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.
+
+- The 1px border is always reserved; transparent items paint it only when frame="framed", while surface and semantic appearances coordinate its color with their background and foreground.
+
+## Accessibility
+
+- An ordinary item adds no role or name; pass ariaLabel only when the item is a distinct named region (it then renders role="region").
+- focusTarget makes the item a programmatic focus target (tabindex="-1", never a tab stop), such as a NavStack view's data-nav-focus target.
+- The frame is decorative and never the only signal of state.
+- selectionMode="multiple" renders a focusable row with aria-selected and a gridcell for nested controls; place it in a labeled List selectionMode="multiple" grid. wireContentItems moves focus among rows with Up/Down and Home/End while nested controls retain those keys. Guard the app's delegated card action with isContentItemActivation so a nested control does not select the row.
+
+## 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-content-item`, `kui-content-item--pill`, `kui-content-item--framed`.
+
+Classes an application may place on its own elements: `kui-content-item`, `kui-content-item--pill`, `kui-content-item--framed`.
+
+A plain `<div>` carrying them is exactly what `ContentItem` renders: render `ContentItem` instead (`KUI-L103`), and place the classes only on another carrier element.
+
+Public tokens it reads: `--kui-content-item-border`, `--kui-content-item-radius`, `--kui-content-item-background`. 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: [ListInsetText](./list-inset-text.md), [SunkenPanel](./sunken-panel.md), [Application Layout](./layout.md).
+- Docs: [`docs/layout.md`](../../docs/layout.md), [`docs/layout.md#content-items`](../../docs/layout.md#content-items).
+- UX catalog route: `?component=content-item`.

package/ai/components/content-swap.md

@@ -0,0 +1,78 @@
+# ContentSwap
+
+<!-- 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:content-swap` · Kerf UI · component · Structure
+
+Two content sides sharing one cell, swapped in place with a push, a crossfade, or no motion.
+
+## When to use
+
+Swap arbitrary content in place (a dialog body that steps to a second page, a label or footer whose actions change) with Kerf-owned push or crossfade motion, reduced-motion handling, and an inert, hidden inactive side.
+
+- A region swaps between two contents in place, such as a dialog's two steps or a footer's action sets, and the change should read as motion.
+
+**Not when:**
+
+- Do not use for full navigation views with their own toolbars; use NavStack.
+- Do not use to swap more than two states at once; render the current pair.
+- Do not hand-roll stacked cells, inert handling, or push keyframes in app CSS.
+
+**Alternatives:**
+
+- [NavStack](./nav-stack.md) (nearest) — Use NavStack for full views with toolbars and back navigation.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/content-swap` — exports `ContentSwap`.
+- CSS: the browser build of `@kerfjs/ui/content-swap` pulls its CSS automatically; import `@kerfjs/ui/content-swap.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/content-swap`](../public-api-signatures-v1.md#kerfjsuicontent-swap) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- push forward or backward
+- crossfade
+- none
+- full-width slot region
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** which side is active and the push direction; both sides' content; the region's name.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Both sides share one grid cell; the region keeps the active side's height and clips the motion.
+
+## Accessibility
+
+- The inactive side is inert and aria-hidden; label makes the swap a named region. Push mirrors in right-to-left documents. Reduced motion replaces the slide with a short 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-content-swap`, `kui-content-swap__side`.
+
+Never put `kui-content-swap`, `kui-content-swap__side` on an element you write; render `ContentSwap` instead (`KUI-L103`).
+
+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: [NavStack](./nav-stack.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=content-swap`.

package/ai/components/corner-status.md

@@ -0,0 +1,88 @@
+# CornerStatus
+
+<!-- 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:corner-status` · Kerf UI · component · Feedback
+
+Non-dismissible app-level status pinned to a viewport corner in the top layer, hosting StateBanner.
+
+## When to use
+
+Show ongoing app-level progress such as "Loading…" or "Updating Tickets… 3 of 12" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.
+
+- Show ongoing app-level progress or status that has no better home beside the affected work and must stay visible until the work ends.
+
+**Not when:**
+
+- Do not use for transient, dismissible confirmation; use a toast.
+- Do not use for status that belongs beside the affected work; place a StateBanner there.
+- Do not position a StateBanner with fixed-position application CSS; use CornerStatus.
+
+**Alternatives:**
+
+- [StateBanner](./state-banner.md) (composes-with) — Compose one or more StateBanners (urgency="status") inside it; they stack.
+- [Toast](./wa-toast.md) (prefer-over) — A toast item is transient and always dismissible; CornerStatus stays until the application removes it.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/corner-status` — exports `CornerStatus`, `wireCornerStatus`.
+- CSS: the browser build of `@kerfjs/ui/corner-status` pulls its CSS automatically; import `@kerfjs/ui/corner-status.css` manually only without the `browser` export condition.
+- Wiring: `wireCornerStatus` from `@kerfjs/ui/wire-corner-status` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/corner-status`](../public-api-signatures-v1.md#kerfjsuicorner-status) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- bottom-end
+- bottom-start
+- top-end
+- top-start
+- embedded (in flow)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [StateBanner](./state-banner.md).
+
+## State and wiring
+
+**The app owns:** status lifetime (render while the work runs, remove when it ends); the composed StateBanner copy and progress; corner placement.
+
+**Wiring:** `wireCornerStatus` is required.
+
+- Opens each overlay host in the top layer as renders insert it; without it the Popover API keeps the host hidden.
+
+## Geometry
+
+Margin: none · border: child · padding: child (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Placement owns the 16px viewport gutter plus device safe-area insets; a StateBanner inside drops its inline margin and gains elevation.
+
+## Accessibility
+
+- The host adds no role; the composed StateBanner with urgency="status" is the polite live region.
+- Opening never moves focus, and there is no close button, light dismiss, or Escape handling to compete with dialogs.
+- A modal dialog opened while it shows stacks above it and makes it inert (unannounced); show progress the dialog's task depends on inside the dialog.
+
+## 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-corner-status`.
+
+Never put `kui-corner-status` on an element you write; render `CornerStatus` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-corner-status-gutter`, `--kui-corner-status-z-index`, `--kui-safe-area-block-end`, `--kui-safe-area-block-start`, `--kui-safe-area-inline-end`, `--kui-safe-area-inline-start`, `--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: [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=corner-status`.

package/ai/components/disclosure-arrow.md

@@ -0,0 +1,77 @@
+# DisclosureArrow
+
+<!-- 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:disclosure-arrow` · Kerf UI · component · Foundation
+
+Root-scaled 18px animated open and closed disclosure indicator with configurable directions, shortest-path rotation, and right-oriented replacement icon content.
+
+## When to use
+
+Indicate whether a disclosure control is open with an overridable 18px root-scaled visual and shortest-path rotation behavior.
+
+- Add a shortest-path rotating indicator to a control that owns open and closed state; author replacement icon content facing right before direction transforms are applied.
+
+**Not when:**
+
+- Do not use the arrow as the interactive control or accessible name by itself.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/disclosure-arrow` — exports `DisclosureArrow`.
+- CSS: the browser build of `@kerfjs/ui/disclosure-arrow` pulls its CSS automatically; import `@kerfjs/ui/disclosure-arrow.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/disclosure-arrow`](../public-api-signatures-v1.md#kerfjsuidisclosure-arrow) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- open
+- closed
+- custom directions
+- replacement icon
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `size`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `size={remify(24)}`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** open state; interaction; accessible control label.
+
+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
+
+- The arrow is decorative; expose expanded state through aria-expanded on its owning control and keep that control's accessible name stable.
+
+## 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-disclosure-arrow`.
+
+Never put `kui-disclosure-arrow` on an element you write; render `DisclosureArrow` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-disclosure-arrow-duration`, `--kui-disclosure-arrow-size`. 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).
+- 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=disclosure-arrow`.

package/ai/components/document-baseline.md

@@ -0,0 +1,77 @@
+# Document Baseline
+
+<!-- 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:document-baseline` · Kerf UI · CSS composition · Foundation
+
+Opt-in document-level defaults: border-box sizing, body margin/font/surface, native table-cell and form-control font metrics, semantic control cursors, link color, and the html → body → .kui-app-root full-height chain.
+
+## When to use
+
+Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.
+
+- An application wants Kerf UI to own document-level box sizing, body typography, native table-cell and form-control font metrics, surface, and link color.
+- A full-height shell (Workbench, SplitView, NavStack, or TabNavigator) mounts into one direct container: put .kui-app-root on that container.
+
+**Not when:**
+
+- Do not put .kui-app-root on several sibling containers; each requests the full available document height.
+- Do not import it where the host page already owns document-level defaults it would override.
+
+**Alternatives:**
+
+- [Foundation Tokens](./foundation.md) (composes-with) — Import the foundation tokens the baseline reads; the baseline itself adds only global document selectors.
+
+## Imports
+
+- CSS: import `@kerfjs/ui/document.css` once.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- document-flow page (no .kui-app-root)
+- full-height application root
+- viewport-locked application root (data-viewport="locked" on a body-child .kui-app-root: 100dvh and overflow clip on html, body, and the root)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the one direct mount container; application overrides loaded after the baseline.
+
+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.
+
+- The body margin is removed; .kui-app-root only sets height: 100% and owns no inset.
+
+## Accessibility
+
+- Links keep the semantic link color at zero specificity so application focus and link styles still apply.
+- Native controls get semantic cursors at zero specificity: pointer on enabled buttons, links, role=button, checkbox/radio/button-type inputs, selects, and checkbox/radio labels; not-allowed on disabled controls, aria-disabled role=button, and a disabled wa-button's base part; text on text-like inputs and textareas.
+
+## 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-app-root`.
+
+Classes an application may place on its own elements: `kui-app-root`.
+
+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: [Foundation Tokens](./foundation.md).
+- Docs: [`docs/document-baseline.md`](../../docs/document-baseline.md).
+- UX catalog route: `?component=document-baseline`.