@kerfjs/ui 5.0.0-beta.18 → 5.0.0-beta.21

package/docs/catalog.md

@@ -40,47 +40,113 @@ Per-entry `resources` render as "open in new tab" links in the footer, and
 around a `wa-dropdown` (grouped by each entry's `group`), so register its elements
 with `@kerfjs/ui/select/register` when you use it.
 
-## Preview examples
-
-Compose each entry's `content` from `CatalogExample` (and `CatalogExampleStack`)
-instead of hand-rolled example markup, so labels, notes, and left-edge alignment
-stay consistent:
+## Catalog demo authoring contract
+
+This section is the single authoritative contract for tools and people that
+author Catalog previews. The machine-readable discovery entry is
+[`catalog-authoring.json`](../ai/catalog-authoring.json); exact props remain in
+[`public-api-signatures-v1.md`](../ai/public-api-signatures-v1.md#kerfjsuicatalog).
+The component catalog deliberately does not duplicate these rules: it describes
+which component to choose, while this contract describes how to present the
+chosen component.
+
+### Choose the demo mode
+
+Classify every entry before rendering it:
+
+| Entry kind            | Preview purpose                                                         | Geometry overlay                                                                    |
+| --------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Focused component     | Show one public component, its meaningful variants, and adverse states. | `true`; the overlay inspects each selected specimen.                                |
+| Composition or recipe | Show several components cooperating as one product surface.             | `false`; child geometry remains unmarked so the composition can be read as a whole. |
+
+Keep `geometryOverlay` present and compute it from the active entry. Do not make
+it a permanent catalog-wide `true`, and do not give individual specimens their
+own overlay implementation.
+
+### Required structure
+
+- `Catalog` is the one shell. The app owns active-entry state and passes one
+  active preview through `content`.
+- `CatalogExampleStack` is the group for one preview's rows. Put route/test
+  metadata such as `data-demo` on its rendered root through `rootAttributes`.
+  Pass `label` when the stack needs an accessible name: the rendered `section`
+  is then exposed as a named region. An unlabeled stack remains an ordinary
+  grouping rather than adding an unnecessary landmark.
+- `CatalogExample` is one row: optional generated `ListHeader` label, optional
+  generated note, then one specimen or one intentionally coupled specimen
+  cluster. Use one row per variant/state; do not hand-author the helper's private
+  classes.
+- The specimen is an immediate child of `CatalogExample`. A focused component
+  row should place the component root there, without a decorative card or
+  spacing wrapper. A composition row may place the composition root there.
+
+Use `align="glyph"` for a bare glyph/text specimen, `align="inline-control"`
+for a control whose own inline padding contributes about 8px, and `align="none"`
+(the default) for a content item or composition that owns its geometry.
 
 ```tsx
 import { CatalogExample, CatalogExampleStack } from "@kerfjs/ui/catalog";
 
 const buttonPreview = (
-  <CatalogExampleStack label="Button variants">
+  <CatalogExampleStack
+    label="Button variants"
+    rootAttributes={{ "data-demo": "button" }}
+  >
     <CatalogExample label="Icon" note="A bare glyph." align="glyph">
       <LucideIcon icon={Plus} name="plus" />
     </CatalogExample>
     <CatalogExample label="Control" align="inline-control">
       <SegmentedControl id="view" label="View" value="list" choices={choices} />
     </CatalogExample>
-    <CatalogExample label="In composition">
-      <ValueTable label="Metadata">{rows}</ValueTable>
+    <CatalogExample
+      label="Authoring note"
+      note="Explanatory chrome is not a specimen."
+      rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}
+    >
+      <p>Use the public helper contract.</p>
     </CatalogExample>
   </CatalogExampleStack>
 );
 ```
 
-`label` is optional — omit it for a bare specimen with no `ListHeader`. `align`
-lines a specimen's visible left edge up with its label text: `'glyph'`
-(16px) for a bare glyph/text specimen, `'inline-control'` (8px) for a control that
-already carries ~8px of its own inline padding, and `'none'` (the default) for a
-content-item/composition that already owns its geometry. The inset is published as
-the `--kui-catalog-example-align` custom property so a debug overlay can exclude it
-from a specimen's measured margin.
-
-## Geometry inspection
-
-Pass `geometryOverlay` to `Catalog` when individual component previews should
-show otherwise-invisible geometry. The controlled boolean draws a dashed outer
-bound around specimens with transparent backgrounds and devtools-style orange
-bands over positive margins. Keep the prop present while switching entries so
-`wireCatalog` can reuse one overlay layer; set it to `true` for focused component
-previews and `false` for full compositions whose child geometry should remain
-unmarked.
+The overlay selects every immediate child of a `CatalogExample` except the
+helper-generated label and note. It does not recursively promote a nested child
+to be the specimen. Outside an example row, it selects only top-level
+`[data-component]` roots in the canvas and ignores nested component descendants.
+These rules keep a row's label/group scaffolding out of the measurement and make
+the authored nesting determine exactly what is inspected.
+
+### Metadata ownership
+
+Use `rootAttributes` on either helper for authoring metadata such as `data-demo`
+or `data-catalog-geometry-overlay-skip`; the metadata lands on that helper's
+rendered root. The slot accepts only `data-*` strings. Structural
+`data-catalog-example`, `data-catalog-example-stack`, and `data-align` semantics
+remain helper-owned and are rejected case-insensitively at runtime, including
+from structurally widened or JavaScript objects. Do not copy the helpers'
+private `kui-catalog-*` classes into preview markup.
+
+The app owns entry ids, `kind`, routing, sources, relationships, and test hooks.
+The helpers own their structural markers, label/note anatomy, alignment marker,
+and private classes. Component metadata such as margin/border/padding ownership
+lives in `component-catalog.json`; do not infer or overwrite it from overlay
+pixels.
+
+### Geometry overlay and legend
+
+Pass the conditional `geometryOverlay` boolean to `Catalog`, then call
+`wireCatalogGeometryOverlay(root)` once after the first render and retain its
+disposer alongside `wireCatalog`'s.
+
+| Overlay mark            | Meaning                                                                                              | It is not                                                                              |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Orange translucent band | A positive computed margin on the selected specimen, after subtracting the helper's alignment inset. | Padding, gap, or empty content. Zero and negative margins are not drawn.               |
+| Quiet dashed outline    | The border-box outer bound of a selected specimen whose computed background is transparent.          | A real CSS border, focus ring, padding edge, or proof that the specimen owns its size. |
+
+The overlay does not visualize padding, borders, gaps, negative/zero margins,
+scroll overflow, hit targets, nested descendants, or geometry ownership. Inspect
+computed styles and the machine-readable `geometry` metadata for those facts.
+Opaque specimens do not receive the transparent-bound outline.
 
 ```tsx
 <Catalog
@@ -90,13 +156,12 @@ unmarked.
 />
 ```
 
-Call `wireCatalogGeometryOverlay(root)` after the first render to synchronize the
-opt-in layer across rerenders, theme changes, resizes, and scrolling, and retain
-its disposer alongside `wireCatalog`'s. `CatalogExample` labels and notes are
-excluded; its `align` inset is also subtracted so alignment scaffolding is not
-reported as intrinsic component margin. Put
-`data-catalog-geometry-overlay-skip` on a preview subtree that is intentionally
-explanatory chrome rather than a specimen.
+Put `rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}` on a
+`CatalogExample` or `CatalogExampleStack` only when that whole subtree is
+explanatory chrome rather than a specimen. The marker excludes the marked root
+and every descendant from selection; it does not merely hide one band. It is
+normally unnecessary in a composition because the active entry already sets the
+global overlay to `false`.
 
 Use the overlay together with machine-readable geometry ownership metadata; the
 overlay verifies what is rendered, while metadata tells people and AI tools
@@ -107,6 +172,36 @@ contract and can start from the checked
 [`component-catalog-extension.json`](./examples/component-catalog-extension.json)
 example; provide those entries beside Kerf's shipped catalog to AI tools.
 
+### Automated conformance and reviewed exceptions
+
+Run `npm run check:demo-conformance` after changing a first-party demo, its
+catalog kind, or the shell's overlay logic. The TypeScript-AST gate verifies
+facts that source can prove without guessing at rendered intent:
+
+- focused component routes import and use `CatalogExampleStack` and
+  `CatalogExample` from the public package;
+- focused route metadata uses the helpers' `rootAttributes` slot, example rows
+  are not empty, and composition routes do not add redundant skip markers;
+- every `@kerfjs/ui` import is a published package export and relative imports
+  do not reach into `ui/src`;
+- demo JSX does not copy private `kui-catalog-*` structural classes; and
+- the shell derives both geometry-overlay enablement and documented demo mode
+  from the active entry's source and kind.
+
+The gate deliberately does not infer component ownership from arbitrary class
+names, margins, borders, or nested descendants. Runtime selection and geometry
+remain the browser suite's job.
+
+A focused route may bypass the two public layout helpers only when the route's
+stage geometry is itself the reviewed specimen. Add the narrow waiver to
+[`catalog-conformance-exceptions.json`](../ux-demo/catalog-conformance-exceptions.json)
+with the exact route, source file, stable diagnostic ids, a substantive reason,
+and the reviewing `KF-*` ticket. Only helper/metadata rules are waivable;
+private imports, private markup, empty examples, composition overlay drift, and
+shell-mode drift always fail. The gate rejects duplicate, malformed, unused,
+and stale exceptions, so delete a waiver when its route adopts the standard
+helpers.
+
 ## Selection reveal
 
 Set `revealSelection: true` on `wireCatalog` for a long desktop sidebar. After
@@ -124,8 +219,13 @@ sizes. For an initial deep link that did not come through `wireCatalog`, call
 ## Complete example
 
 ```tsx
-import { mount, signal } from "kerfjs";
-import { Catalog, type CatalogSection } from "@kerfjs/ui/catalog";
+import { mount, signal, type SafeHtml } from "kerfjs";
+import {
+  Catalog,
+  CatalogExample,
+  CatalogExampleStack,
+  type CatalogSection,
+} from "@kerfjs/ui/catalog";
 import {
   revealCatalogEntry,
   wireCatalog,
@@ -133,45 +233,63 @@ import {
 } from "@kerfjs/ui/wire-catalog";
 import "@kerfjs/ui/styles.css"; // or import each primitive's CSS + @kerfjs/ui/catalog.css
 
-// 1. Describe your components once.
-const sections: CatalogSection[] = [
+type DemoKind = "component" | "composition";
+type DemoEntry = CatalogSection["entries"][number] & { kind: DemoKind };
+
+// 1. Describe selection and overlay mode once.
+const entries: DemoEntry[] = [
   {
-    category: "Controls",
-    entries: [
-      {
-        id: "button",
-        name: "Button",
-        description: "A pressable control.",
-        resources: [
-          {
-            label: "Source",
-            href: "/src/button.tsx",
-            detail: "src/button.tsx",
-          },
-        ],
-      },
-      {
-        id: "field",
-        name: "Field",
-        description: "A labeled input.",
-        tags: ["Discouraged"],
-        related: [{ id: "button", name: "Button", group: "Used with" }],
-      },
+    id: "button",
+    name: "Button",
+    kind: "component",
+    description: "A pressable control.",
+    resources: [
+      { label: "Source", href: "/src/button.tsx", detail: "src/button.tsx" },
     ],
   },
   {
-    category: "Feedback",
-    entries: [
-      { id: "toast", name: "Toast", description: "A transient message." },
-    ],
+    id: "profile-form",
+    name: "Profile form",
+    kind: "composition",
+    description: "A labeled field and save action working together.",
+  },
+];
+const sections: CatalogSection[] = [
+  {
+    category: "Examples",
+    entries: entries.map(({ kind: _kind, ...entry }) => entry),
   },
 ];
 
-// 2. One preview render per entry id.
-const renderers: Record<string, () => ReturnType<typeof Button>> = {
-  button: () => <Button label="Save" />,
-  field: () => <Field label="Name" />,
-  toast: () => <Toast>Saved</Toast>,
+// 2. Every preview uses one public group and public example rows.
+const renderers: Record<string, () => SafeHtml> = {
+  button: () => (
+    <CatalogExampleStack
+      label="Button states"
+      rootAttributes={{ "data-demo": "button" }}
+    >
+      <CatalogExample label="Default" align="inline-control">
+        <Button label="Save" />
+      </CatalogExample>
+      <CatalogExample
+        label="Authoring note"
+        note="This explanatory row is deliberately excluded from inspection."
+        rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}
+      >
+        <p>The application owns product copy and actions.</p>
+      </CatalogExample>
+    </CatalogExampleStack>
+  ),
+  "profile-form": () => (
+    <CatalogExampleStack
+      label="Profile form composition"
+      rootAttributes={{ "data-demo": "profile-form" }}
+    >
+      <CatalogExample label="Complete composition">
+        <ProfileForm />
+      </CatalogExample>
+    </CatalogExampleStack>
+  ),
 };
 
 // 3. App-owned state (domain: which entry; transient: collapsed; global: theme).
@@ -180,6 +298,7 @@ const initial =
 const active = signal(initial);
 const collapsed = signal(false);
 const theme = signal<"light" | "dark">("light");
+const activeEntry = () => entries.find(({ id }) => id === active.value) ?? entries[0];
 
 const app = document.getElementById("app")!;
 mount(app, () => (
@@ -190,7 +309,7 @@ mount(app, () => (
     content={renderers[active.value]?.() ?? <></>}
     collapsed={collapsed.value}
     theme={theme.value}
-    geometryOverlay={true}
+    geometryOverlay={activeEntry().kind === "component"}
   />
 ));
 

package/docs/component-contract.md

@@ -18,6 +18,94 @@ package delivery paths, Web Awesome's installed manifest, AI guidance, and
 documentation links. Nuanced prose in this contract and the selection guide
 remains authored rather than generated.
 
+### Composition catalog v2
+
+[`component-catalog-v2.json`](../ai/component-catalog-v2.json) adds a formal,
+machine-evaluable composition layer without changing the v1 selection and
+delivery contract. Every v1 entry projects once, in order, under the stable
+qualified key `package:id`. Each v2 entry explicitly covers parents/contexts,
+named zones and cardinality, child concepts, state ownership, required wiring,
+responsive ownership, layout and geometry, accessibility obligations, public
+CSS boundaries, diagnostics, and provenance.
+
+The generator starts with permissive defaults. An `any` mode records that the
+catalog has no defensible prohibition; it does not claim every composition is
+recommended. Objective rules live in
+`component-catalog-v2-overrides.json` and may carry stable `KUI-C###`
+diagnostics. A tool reports a diagnostic only after proving its exact `when`
+condition. Subjective choice, product policy, and visual taste remain prose.
+
+V1 consumers continue unchanged. V2 consumers read v1 for selection/delivery
+and v2 for composition. `npm run catalog:sync` projects every new component,
+recipe, and supported Web Awesome entry, and the completeness gate prevents
+silent omissions. Downstream catalogs use the v2 extension schema and types,
+retain their own package identity, and qualify cross-catalog references. See
+the checked
+[`component-catalog-extension-v2.json`](./examples/component-catalog-extension-v2.json)
+application-owned example.
+
+### Compile-time contract boundary
+
+The versioned
+[`compile-time-contracts-v1.json`](../ai/compile-time-contracts-v1.json)
+artifact maps stable `KUI-T###` ids to public imports, emitted symbols, and
+catalog identities. Its positive/negative fixture compiles against both source
+and a freshly packed package, so source declarations and shipped declarations
+cannot silently diverge. See [Compile-time contracts](./type-contracts.md) for
+the full audit, migration guidance, and the relationships deliberately left to
+runtime/catalog checks because TypeScript cannot prove them.
+
+### Application UI profile
+
+The component catalogs describe what packages provide; an application profile
+describes which supported choices a project has approved. A workspace may
+check in `.kerf-ui-profile.json` conforming to
+[`application-ui-profile.schema.json`](../ai/application-ui-profile.schema.json).
+Keep package-qualified catalog locations and recurring-concept preferences,
+allowed color schemes and density, public semantic-token overrides,
+layout/responsive conventions, and narrow rule exceptions there. Product
+records, copy, permissions, user preferences, and transport state do not belong
+in this policy file.
+
+Every catalog location names a v2 composition artifact. `selection` is optional
+for consumer packages whose generated metadata declares v1 selection guidance
+not applicable; `@kerfjs/ui` retains its required v1 selection artifact. This
+lets a generated `component-catalog-v2.json` participate directly without a
+fabricated compatibility file.
+
+Discovery and precedence are deterministic:
+
+1. Load `application-ui-profile.defaults.json` from `@kerfjs/ui`.
+2. Load `.kerf-ui-profile.json` at the workspace root when present.
+3. Walk from the workspace root toward the target directory and load each
+   directory-local profile in parent-to-child order.
+
+Later scalar and object-map values win. Catalogs merge by package; preferences
+and token overrides merge by key; exceptions merge by stable id. Lists such as
+allowed themes/densities replace the earlier list rather than accumulating.
+Every resolved field retains its source file. The shipped
+`application-ui-profile.mjs` API implements discovery, merge, loading, and
+validation and reports actionable originating file + JSON-path diagnostics for stale
+catalogs, unknown component/rule/token references, preference conflicts, and
+broad exceptions. Each raw layer is validated against the catalogs effective at
+that exact precedence point before merge, so a broken parent catalog, stale
+parent reference, invalid value, or unknown field cannot disappear merely
+because a child profile replaces it. The shipped
+`application-ui-profile-sync.cjs` projects the same merge and validation contract
+for synchronous hosts such as ESLint rules; it deliberately performs no async
+I/O.
+See the
+[`application-ui-profile.json`](./examples/application-ui-profile.json) example.
+
+Catalog detail footers use one standard resource vocabulary and order. Build
+them with `catalogResources()` from `@kerfjs/ui/catalog-resources`: `Demo source`
+first, optional `Component source` and `Design template`, then `Guidance`.
+Third-party entries use the typed `integrationGuidance` kind, which renders
+`Integration guidance`, and omit `Component source` when the implementation is
+not owned by the catalog's project. Prefer these semantic kinds over local labels
+such as “View source” or “Read UI guidance”; the helper makes that convention a
+compile-time choice while still returning ordinary `CatalogResource[]` values.
+
 ## Ownership boundaries
 
 ### Geometry ownership metadata
@@ -55,7 +143,8 @@ claim Kerf delivery paths for them.
 - Consumers style through `--kui-*` semantic tokens and public component classes. Foundation tokens provide opinionated neutral, brand/info, success, warning, and danger fill/border/foreground roles. Stateful components expose local override variables; prefer an equivalent prop or token before writing a selector.
 
 `ListItem.rootAttributes`, `ListActionRow.rootAttributes`,
-`ListHeader.rootAttributes`, and `AppTab.rootAttributes` accept
+`ListHeader.rootAttributes`, `AppTab.rootAttributes`,
+`CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` accept
 application-owned `data-*` metadata without
 adding product fields to the shared API. A `ListActionRow` trailing action uses
 `trailingActionAttributes`, and a `ListHeader` action/disclosure uses
@@ -64,7 +153,7 @@ the corresponding `aria-controls`/`aria-haspopup` relationship. These slots do
 not accept roles or component-owned action, selection, disclosure, accessible
 name, disabled, or icon fields. Extension objects are filtered at runtime,
 including case-insensitive rejection of protected `data-*` names, and the
-component writes its protected attributes after the accepted metadata. Typed,
+component or helper writes its protected attributes after the accepted metadata. Typed,
 structurally widened, and JavaScript callers therefore cannot replace its
 contract.
 
@@ -93,6 +182,11 @@ layout cannot be expressed by a prop or token. A class being public does not
 make copied component markup an invocation or transfer state and accessibility
 ownership to the application.
 
+The v2 composition catalog additionally requires `boundaries.rootClass` to be
+either one exact member of `publicClasses` or `null` when the entry has no
+rendered class root. Runtime geometry tooling uses this explicit field; array
+order never implies root ownership.
+
 Do not select a component's descendant by element name, id, attribute alone, or
 an unlisted implementation class. Selectors such as `.kui-state-banner span`,
 `.kui-list-item [data-state]`, and `.kui-list-item .local-label` depend on
@@ -131,9 +225,12 @@ separator with a compact grip that appears on hover or keyboard focus. Override
 `--kui-resizable-region-handle-active-color` on a region when its containing
 surface needs a different contrast level.
 
-`@kerfjs/ui/layout.css` defines one structural model for sidebars, main areas,
-inspectors, and dialogs. `.kui-pane` is unpadded and contains an optional
-toolbar, one scrolling `.kui-pane__content`, and an optional footer.
+`Pane` defines one structural model for sidebars, main areas, inspectors, and
+dialogs. Its `.kui-pane` root is unpadded and contains an optional vertical
+header, one scrolling vertical `.kui-pane__content`, and an optional footer.
+Logical-edge separator lines are independently opt-in and default off.
+`@kerfjs/ui/layout.css` retains the pane roles and supplies the related content
+geometry classes.
 `.kui-content` gives major children 24px vertical separation.
 `.kui-content-item` gives one child 8px inline margin, a real 1px border,
 8px padding, and 12px corners; border and background may be transparent without

package/docs/component-selection.md

@@ -45,6 +45,11 @@ application boundary:
 Recipes use public production exports and show ownership boundaries; they are
 copyable reference compositions, not new monolithic components.
 
+When presenting a component or recipe in a Catalog, use the authoritative
+[Catalog demo authoring contract](./catalog.md#catalog-demo-authoring-contract)
+rather than deriving preview structure or geometry-overlay behavior from these
+selection entries.
+
 ## Missing recurring concepts
 
 Kerf UI does not export a command-palette component. Do not invent a package
@@ -71,7 +76,8 @@ an upstream component or recipe request.
 | Navigation section heading — `ListHeader`                                                                               | A menu section needs a full-width label, semantic count, non-count badge, logical-end action, or real disclosure state.                                                                                                 | Do not concatenate counts into `label` or put numeric content in `badge`; use `count` with the localized full phrase in `countLabel`. Do not add a disclosure arrow to navigation that reveals nothing. Do not shrink its 44px action target to the 18px visual. Do not use it as a page, panel, or dialog title; use `PanelHeader`. | Delegate its optional action; the app controls expanded state and revealed content. Toggle mode supplies `DisclosureArrow` unless `actionIcon` replaces it. Use `triggerAttributes` only for domain `data-*` or a native popover relationship.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Section organization, valid count and localized count label, disclosure state and content, non-count badge content, popover target behavior, and policy. | `@kerfjs/ui/list-header`                             | [Pane geometry](../README.md#pane-and-content-geometry)                             |
 | Inset self-bordered control — `ListInsetControl`                                                                        | A control that owns its own border and padding but no outer margin (a search input, a `SegmentedControl`) must line up inside a `.kui-content` list with the standard 8px inline margins and stretch to fill the row.   | Do not wrap a `.kui-content-item` or a `ListItem`/`ListHeader` that already owns its inline margin — that double-insets it. Do not add ad-hoc `margin`/`padding` around a bare control to align it; use this instead.                                                                                                                | Place the self-bordered control(s) as children; they stretch to fill. It applies only the inline margin, flex stretch, and 8px gap — the child owns its own border and padding.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | The control(s), their state, and action wiring.                                                                                                          | `@kerfjs/ui/list-inset-control`                      | [Pane geometry](../README.md#component-subpaths)                                    |
 | Inset bare text — `ListInsetText`                                                                                       | A plain string or inline content with no margin, border, or padding of its own must sit in a `.kui-content` list with its text edge aligned to the bordered items around it.                                            | Do not use it to wrap a component that already owns content-item geometry (`ListItem`, `StateBanner`, a `.kui-content-item`) — that double-insets it. Do not hand-roll the 8px margin / 1px border / 8px padding.                                                                                                                    | Pass the text or inline `SafeHtml` as children; it supplies the 8px inline margin, 1px transparent border, and 8px padding so the text edge lands at the standard 17px inset. Pass `horizontalOnly` to keep that horizontal inset but drop the vertical margin, border, and padding for tight text layout.                                                                                                                                                                                                                                                                                                                                                                                                             | The text, copy, and localization.                                                                                                                        | `@kerfjs/ui/list-inset-text`                         | [Pane geometry](../README.md#component-subpaths)                                    |
-| Application layout composition                                                                                          | A sidebar, main area, inspector, or dialog needs shared toolbar/content/footer and child geometry.                                                                                                                      | Do not pad the pane shell, wrap child-owned geometry in competing insets, invent unrelated centered measures, or leave an icon-only rail for a hidden pane.                                                                                                                                                                          | Use `.kui-pane` and one `.kui-pane__content`; add `.kui-content` and `.kui-content-item` as needed. A visible pane owns collapse in its toolbar; move a hidden inline-start pane's restore control to the main toolbar leading edge and an inline-end pane's restore control to its trailing edge.                                                                                                                                                                                                                                                                                                                                                                                                                     | Layout hierarchy, reading width, scroll ownership, responsive relocation, and pane visibility state.                                                     | `@kerfjs/ui/layout.css`                              | [Pane anatomy](./layout.md#anatomy)                                                 |
+| Application column — `Pane`                                                                                             | A sidebar, main area, inspector, or dialog needs shared vertical header/content/footer organization, one scroll owner, and optional edge separators.                                                                    | Do not pad the pane shell, wrap child-owned geometry in competing insets, invent unrelated centered measures, or leave an icon-only rail for a hidden pane.                                                                                                                                                                          | Import `Pane`, provide optional fixed header/footer slots around its primary vertical content, and opt into only the needed logical-edge separators; add `.kui-content-item` as needed. A visible pane owns collapse in its toolbar; move a hidden inline-start pane's restore control to the main toolbar leading edge and an inline-end pane's restore control to its trailing edge.                                                                                                                                                                                                                                                                                                                                 | Layout hierarchy, reading width, responsive relocation, pane visibility state, slot semantics, labels, and separator placement.                          | `@kerfjs/ui/pane`                                    | [Pane anatomy](./layout.md#anatomy)                                                 |
+| Lowered content surface — `SunkenPanel`                                                                                 | A main work area or nested content group needs one visually lowered surface with a compact inset and vertical stack.                                                                                                    | Do not use it merely to add padding, as a replacement for `Pane` anatomy, or around children that already own the same outer surface.                                                                                                                                                                                                | Compose the application-owned content as children and pass `ariaLabel` only when the surface is a distinct named region.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Region semantics, accessible name, scroll ownership, child ordering, and content.                                                                        | `@kerfjs/ui/sunken-panel`                            | [SunkenPanel](./sunken-panel.md)                                                    |
 | Menu composition                                                                                                        | Navigation sections need full-size rows and the same content-item geometry as every other pane.                                                                                                                         | Do not add sidebar-specific wrapper padding, shrink targets to icon size, nest an interactive trailing control in `ListItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract.                                                                                      | Compose `ListHeader`, `ListItem`, and `ListActionRow` in `.kui-content`; use `ListHeader` toggle mode with real controlled content, and use `.kui-content-item` for other surfaces plus a pane footer for toolbar actions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Information architecture, disclosure content and state, responsive drawer/shell behavior, and token overrides.                                           | `@kerfjs/ui/layout.css`                              | [Pane geometry](../README.md#pane-and-content-geometry)                             |
 | Resizable application pane — `ResizableRegion`, `clampRegionSize`, `resizeRegionFromPointer`                            | A controlled split pane needs the Kerf separator, collapse state, pointer plus keyboard resizing, or a product-specific decorative grip.                                                                                | Do not use it for a static two-column layout; use CSS grid. Prefer it over Web Awesome `wa-split-panel` unless that component's distinct API is required. Keep `handleIcon` noninteractive.                                                                                                                                          | Call `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` once and retain its disposer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Size signal, min/max policy, collapse policy, persistence, and optional decorative handle icon.                                                          | `@kerfjs/ui/resizable-region`                        | [ResizableRegion contract](./accessibility.md#resizableregion)                      |
 | One application tab — `AppTab`                                                                                          | A controlled app tab needs selection, close, drag, leading/trailing anatomy, safe domain metadata, or a product-specific close glyph.                                                                                   | Do not render it alone or use it for a small settings choice; compose in `TabBar`, or use `SegmentedControl`. Keep `closeIcon` noninteractive.                                                                                                                                                                                       | Compose in `TabBar`; let `wireTabBars` manage interaction. Put only domain `data-*` values in `rootAttributes`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Tab identity, order, selection, close policy, content, and domain metadata values.                                                                       | `@kerfjs/ui/app-tab`                                 | [Tabs contract](./accessibility.md#tabs)                                            |
@@ -142,8 +148,7 @@ Correct: let the pane stay unpadded while its children own the shared 8/1/8
 geometry and 44px targets.
 
 ```tsx
-<aside class="kui-pane">
-  <nav class="kui-pane__content kui-content">
+<Pane element="aside" contentElement="nav" label="Workspace" contentLabel="Workspace pages">
     <section>
       <ListHeader label="Workspace" />
       <ListItem action="open" label="Inbox" icon={inboxIcon} />
@@ -156,8 +161,7 @@ geometry and 44px targets.
       />
     </section>
     <div class="kui-content-item">Workspace details</div>
-  </nav>
-</aside>
+</Pane>
 ```
 
 Incorrect: duplicating component-like rows and compensating for nested padding

package/docs/design-philosophy.md

@@ -50,16 +50,14 @@ toolbar groups use 8px. Rows and actions keep 44px targets.
 Use the package composition so the geometry has one owner:
 
 ```tsx
-<aside class="kui-pane">
-  <nav class="kui-pane__content kui-content">
+<Pane element="aside" contentElement="nav" label="Workspace" contentLabel="Workspace pages">
     <section>
       <ListHeader label="Workspace" />
       <ListItem action="open" label="Inbox" icon={inboxIcon} />
       <ListItem action="open" label="Drafts" />
     </section>
     <div class="kui-content-item">Panel contents</div>
-  </nav>
-</aside>
+</Pane>
 ```
 
 Do not pad the pane and then pad every wrapper. That duplicates the geometry

package/docs/examples/application-ui-profile.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "../../ai/application-ui-profile.schema.json",
+  "schemaVersion": 1,
+  "scope": "workspace",
+  "catalogs": [
+    {
+      "package": "@kerfjs/ui",
+      "selection": {
+        "path": "../../ai/component-catalog.json",
+        "schemaVersion": 1
+      },
+      "composition": {
+        "path": "../../ai/component-catalog-v2.json",
+        "schemaVersion": 2
+      }
+    },
+    {
+      "package": "@acme/ui",
+      "composition": {
+        "path": "./component-catalog-extension-v2.json",
+        "schemaVersion": 2
+      }
+    }
+  ],
+  "preferences": {
+    "application-shell": {
+      "preferred": "@kerfjs/ui:recipe-app-shell",
+      "rationale": "The workspace uses the standard resizable three-region shell."
+    },
+    "record-inspector": {
+      "preferred": "@acme/ui:inspector",
+      "rationale": "The application-owned inspector maps record policy onto Kerf panel primitives."
+    }
+  },
+  "theme": {
+    "colorScheme": "light",
+    "allowedColorSchemes": ["light", "dark"],
+    "density": "standard",
+    "allowedDensities": ["standard"]
+  },
+  "tokens": {
+    "--kui-color-brand-fill-normal": "oklch(0.62 0.16 255)"
+  },
+  "layout": {
+    "shell": "@kerfjs/ui:recipe-app-shell",
+    "pane": "@kerfjs/ui:pane",
+    "responsiveStrategy": "device-class",
+    "compactNavigation": "nav-stack",
+    "scrollOwnership": "one-per-pane",
+    "spacingScale": "kerf-five-step"
+  },
+  "exceptions": [
+    {
+      "id": "legacy-report-grid",
+      "rules": ["KUI-C101"],
+      "target": "src/features/legacy-report/report-grid.tsx",
+      "rationale": "The embedded report engine owns this isolated toolbar-compatible control row."
+    }
+  ]
+}