@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/ai/components/disclosure.md

@@ -0,0 +1,88 @@
+# Disclosure
+
+<!-- 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` · Kerf UI · component · Structure
+
+Content a person shows and hides under a summary row: a native details element with a DisclosureArrow, a title, and an optional quiet detail, on content-item geometry, with plain, framed, and sunken appearances, an embedded appearance for a compact panel inside a ContentItem, and native exclusive (accordion) groups.
+
+## When to use
+
+Keep secondary or optional content one press away under a summary, or let a person open one of several sections at a time.
+
+- Optional or advanced content should stay out of the way until a person asks for it (advanced settings, a build log, release notes).
+- A list of questions or sections should open one at a time: give the Disclosures the same name for a native exclusive accordion.
+- A compact details panel belongs inside a ContentItem (a note card's AI feedback): use appearance embedded so the item's own inset frames it once.
+
+**Not when:**
+
+- Do not use it to switch between peer views; use a SegmentedControl or TabBar.
+- Do not use it for primary navigation or a collapsible sidebar; use a List or CollapsiblePanel.
+- Do not hand-build a details element with its own marker CSS, and do not use wa-details or wa-accordion.
+
+**Alternatives:**
+
+- [CollapsiblePanel](./collapsible-panel.md) (nearest) — Use a CollapsiblePanel for a rail or drawer that collapses beside the work area.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/disclosure` — exports `Disclosure`, `DisclosureProps`, `DisclosureAppearance`, `DisclosureRootAttributes`.
+- CSS: the browser build of `@kerfjs/ui/disclosure` pulls its CSS automatically; import `@kerfjs/ui/disclosure.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/disclosure`](../public-api-signatures-v1.md#kerfjsuidisclosure) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- plain, framed, or sunken appearance
+- embedded appearance inside a ContentItem or other owner chrome: no margin, border, or padding of its own and a 24px minimum summary row
+- open or closed initially
+- a quiet detail after the title
+- an exclusive accordion group sharing a name
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [DisclosureArrow](./disclosure-arrow.md), [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** the title, detail, and content; the initial open state, and closing it from code (element.open = false); the exclusive group name; reacting to the native toggle event (captured, through toggleAction).
+
+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 root takes the content-item geometry (8px inline margin, a 1px border, 8px padding); the content starts on the title's text column.
+- appearance embedded drops that geometry inside a ContentItem, which already owns it: the arrow sits on the item's content inset, the summary row is at least 24px tall, and the content (a flush Text or other content without an inset) starts on the title's text column 8px below the summary. Do not use embedded outside owner chrome.
+
+While `appearance="embedded"` is set, direct children must bring no content-item inset: a child that owns its margin, border, and padding double-insets this one. Use an inset-free form such as `Text flush`, or inline content (`KUI-L204`).
+
+## Accessibility
+
+- The native summary is a button that Enter and Space toggle and that reports its expanded state; the DisclosureArrow is decorative.
+- Keep the title a short, meaningful name for the hidden content; the open state survives re-renders because the platform owns it.
+
+## 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`, `kui-disclosure__summary`, `kui-disclosure__title`, `kui-disclosure__detail`, `kui-disclosure__content`.
+
+Never put `kui-disclosure`, `kui-disclosure__summary`, `kui-disclosure__title`, `kui-disclosure__detail`, `kui-disclosure__content` on an element you write; render `Disclosure` instead (`KUI-L103`).
+
+Public tokens it reads: `--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: [DisclosureArrow](./disclosure-arrow.md), [LucideIcon](./lucide-icon.md), [CollapsiblePanel](./collapsible-panel.md).
+- Docs: [`docs/disclosure.md`](../../docs/disclosure.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=disclosure`.

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`.

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,89 @@
+# 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
+- dropScope: a selector for an enclosing panel that also takes drops, highlighting the zone while files are over any part of it
+
+## 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-color-surface-current`, `--kui-color-surface-current-region`, `--kui-color-surface-current-tint`, `--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-m`, `--kui-shadow-l`, `--kui-color-brand`. 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`.