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

package/ai/component-composition.json

@@ -646,6 +646,21 @@
           "id": "whether the header is docked in its own row or laid over the scrolling content on the translucent chrome material (headerPresentation, also in PaneConfig)",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "an optional app-chosen surface color that replaces the appearance's fill (background, a typed CssColor from @kerfjs/ui/css-values, also in PaneConfig, so a Workbench panel or mainPane, a CollapsiblePanel pane, or a NavStack view pane forwards it)",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "an optional scoped tint (tint: { color, scheme }, also in PaneConfig): the color and the declared light or dark scheme it belongs to; Kerf does no color detection",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "an optional tint accent (tint.accent) that re-derives the brand ramp, links, and focus ring inside the tinted scope at AA",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -687,7 +702,8 @@
             "deepInset adds --kui-space-xs to every side of the scrolling content and its block scroll padding; header/footer chrome still owns safe-area padding at its edge.",
             "For opaque edge-to-edge children, --kui-pane-scrollbar-gutter: stable reserves a vertical scrollbar gutter outside the published content insets; the default is auto.",
             "scrollClearance adds the inherited --kui-scroll-clearance-block-start/end context, published by overlaying chrome, to the scrolling content block padding and scroll padding alongside safe areas and deepInset.",
-            "headerPresentation overlay: once wireScrollDividers measures the header, the header shares the content cell above the scroller, its border-box height is published as --kui-scroll-clearance-block-start on the Pane root, and the content clears it automatically; unwired or with chromePlacement auto, the header stays docked."
+            "headerPresentation overlay: once wireScrollDividers measures the header, the header shares the content cell above the scroller, its border-box height is published as --kui-scroll-clearance-block-start on the Pane root, and the content clears it automatically; unwired or with chromePlacement auto, the header stays docked.",
+            "The scrolling content also publishes its resolved block-start padding (safe area, deepInset, and overlay or clear header clearance) as --kui-pane-content-inset-block-start, so a first child such as an underChrome BackdropImage can run up beneath it."
           ]
         }
       },
@@ -695,7 +711,10 @@
         "obligations": [
           "Choose semantic root and content elements that match the region and provide labels for landmark elements.",
           "Keep fixed header/footer chrome outside the single scrolling content slot so reading and focus order remain coherent.",
-          "An overlay header's text uses the normal text color, which keeps WCAG AA over the 80% chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter."
+          "An overlay header's text uses the normal text color, which keeps WCAG AA over the 80% chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.",
+          "A background color is app-chosen: Keep text at WCAG AA over the color: a dark background needs dark-tone content or a scoped tint; forced colors paint Canvas instead.",
+          "A tint clamps the re-derived surface and text lightness so normal, quiet, link, and neutral-on-quiet text keep 4.5:1 over the tinted surface, raised surface, and quiet fills for any color; under prefers-contrast: more or without relative color syntax the scope keeps the plain palette in its declared scheme.",
+          "A clear header has no material of its own: keep its controls in glass ToolbarControlGroups and a title over imagery on a scrim; it turns opaque under reduced transparency or increased contrast and paints Canvas in forced colors."
         ]
       },
       "cssValueProps": [],
@@ -797,6 +816,16 @@
           "id": "whether the bottom toolbar docks below the active view or lies over it on the translucent chrome material (bottomToolbarPresentation)",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "an optional app-chosen color for the stack, its docked chrome and bottom toolbar, and every view (background, a typed CssColor); one view's own color goes in its pane: { background }",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "an optional scoped tint for the stack, its chrome, and views: tint: { color, scheme } re-derives surface and text tokens from an app color with text kept at AA",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -882,7 +911,9 @@
           "Use wireNavStack so each controlled push moves focus into the new top view and each pop restores the revealed view's remembered descendant.",
           "Mark a preferred initial heading or control with data-nav-focus when the first enabled focusable descendant is not the right target.",
           "Overlay chrome (chromePresentation overlay) keeps WCAG AA over content passing beneath the translucent material: an untoned ToolbarText there takes the normal text color for its title and lifts its description halfway toward it; keep other quiet copy in the view. The material turns opaque under reduced transparency, increased contrast, forced colors, or without backdrop-filter.",
-          "An overlay bottom toolbar (bottomToolbarPresentation overlay) keeps the same AA rule: an untoned ToolbarText there lifts its title and description, and a default-tone ToolbarControlGroup in either overlaid bar takes the normal text color for its controls. Its 1px top edge stays visible in forced colors."
+          "An overlay bottom toolbar (bottomToolbarPresentation overlay) keeps the same AA rule: an untoned ToolbarText there lifts its title and description, and a default-tone ToolbarControlGroup in either overlaid bar takes the normal text color for its controls. Its 1px top edge stays visible in forced colors.",
+          "A background color is app-chosen: Keep text at WCAG AA over the color: a dark background needs dark-tone content or a scoped tint; forced colors paint Canvas instead.",
+          "Clear bars have no material of their own: keep their controls in glass ToolbarControlGroups; they turn opaque under reduced transparency or increased contrast and paint Canvas in forced colors."
         ]
       },
       "cssValueProps": [],
@@ -1109,6 +1140,16 @@
           "id": "optional active-scene focus (tabIndex) and persistent outline (outlined)",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "an optional app-chosen color for the navigator and its docked bar (background) and per scene (tab.background), each a typed CssColor that replaces the default or sunken fill",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "an optional scoped tint for the navigator (tint) or one scene (tab.tint): tint: { color, scheme } re-derives surface and text tokens from an app color with text kept at AA",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -1156,7 +1197,9 @@
           "Wire selection through the controlled active id while leaving inactive scenes mounted and hidden.",
           "A focusable scene is a tabpanel named by its tab label; optional scene tabIndex applies only while active.",
           "A tab badge is aria-hidden; supply badgeLabel so the tab's accessible name becomes \"<label>, <badgeLabel>\" (it defaults to the badge text). The dot form, badge: true, has no text, so its badgeLabel is required.",
-          "Over the overlay bar's translucent material, unselected labels lift halfway toward --kui-color-text and the selected label mixes 40% of it into the brand color, so both keep 4.5:1 over worst-case content; the material turns opaque under reduced transparency or increased contrast and paints Canvas with a CanvasText edge in forced colors."
+          "Over the overlay bar's translucent material, unselected labels lift halfway toward --kui-color-text and the selected label mixes 40% of it into the brand color, so both keep 4.5:1 over worst-case content; the material turns opaque under reduced transparency or increased contrast and paints Canvas with a CanvasText edge in forced colors.",
+          "A background color is app-chosen: Keep text at WCAG AA over the color: a dark background needs dark-tone content or a scoped tint; forced colors paint Canvas instead.",
+          "Clear bars have no material of their own: keep their controls in glass ToolbarControlGroups; they turn opaque under reduced transparency or increased contrast and paint Canvas in forced colors."
         ]
       },
       "cssValueProps": [],
@@ -1552,6 +1595,81 @@
         "composition": "generated-permissive-default"
       }
     },
+    {
+      "key": "@kerfjs/ui:backdrop-image",
+      "package": "@kerfjs/ui",
+      "id": "backdrop-image",
+      "name": "BackdropImage",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "the image, its alt text (empty for a decorative image), and responsive candidates",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "the fade color, whether the image lags the scroll, and whether it blurs (and any pre-blurred asset)",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "overlay content and its contrast against the image and scrim",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "the content below the image",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "whether the image runs up beneath overlay or clear chrome and the top safe area (underChrome); it must then be the first child of the Pane's content",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["structure"],
+        "geometry": {
+          "margin": "none",
+          "border": "none",
+          "padding": "none",
+          "notes": [
+            "The root bleeds to the Pane's resolved inline insets (the safe area) and hands them back to its overlay and content, so their items keep the ordinary text axis.",
+            "The image block is height tall (default 320px) and grows with taller overlay content."
+          ]
+        }
+      },
+      "accessibility": {
+        "obligations": [
+          "alt describes a meaningful image; pass an empty alt for a decorative one. A tiled image with alt text is exposed as role=\"img\". Parallax and the progressive blur run only with prefers-reduced-motion: no-preference and scroll-driven animation support, and are off under data-kui-effects=\"static\" and on slow-update displays, leaving a static, sharp image; the blurred copy is decorative and aria-hidden. Reduced transparency or increased contrast replaces the fade with a hard edge on solid fadeTo and puts overlay content on a solid fadeTo band. Overlay text needs a scrim or fade color that keeps it at AA."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-backdrop-image",
+        "publicClasses": ["kui-backdrop-image"],
+        "rootElement": "div",
+        "publicTokens": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:toolbar",
       "package": "@kerfjs/ui",
@@ -1891,11 +2009,16 @@
         { "id": "focus lifecycle", "owner": "application", "required": false },
         { "id": "dismissal policy", "owner": "application", "required": false },
         { "id": "content", "owner": "application", "required": false },
-        { "id": "outer placement", "owner": "application", "required": false }
+        { "id": "outer placement", "owner": "application", "required": false },
+        {
+          "id": "whether core kerfjs/overlay dialogs presented as bottom sheets take this package's geometry and slide (import @kerfjs/ui/overlay-sheet.css; exitClass 'kui-overlay-sheet-exit' for the slide out; the kui-overlay-sheet-resizable class plus wireOverlaySheets for a resize grabber)",
+          "owner": "application",
+          "required": false
+        }
       ],
       "wiring": {
         "required": false,
-        "helpers": [],
+        "helpers": ["wireOverlaySheets"],
         "obligations": [],
         "stateAttributes": []
       },
@@ -1909,6 +2032,7 @@
           "Supply the wrapped wa-dialog label and retain Web Awesome's native modal and focus behavior.",
           "Name a PopoverDialogSurface with label or labelledBy, and describe it with describedBy (rendered as aria-describedby), usually a title ToolbarText descriptionId.",
           "A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.",
+          "A resizable bottom sheet's grabber is a focusable horizontal separator (\"Resize sheet\") with aria-valuemin, aria-valuenow, and aria-valuemax in visible px; the arrow keys, Page Up/Down, Home, and End resize it, and its slide motion falls back to Web Awesome's under prefers-reduced-motion.",
           "Use popup surfaces only for real dropdown menus with named triggers."
         ]
       },
@@ -1973,6 +2097,26 @@
           "rawPolicy": "forbid",
           "examples": ["footerOffset={remify(8)}"]
         },
+        {
+          "path": "minHeight",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["minHeight={remify(200)}"]
+        },
         {
           "path": "maxHeight",
           "grammar": "length",
@@ -2002,13 +2146,15 @@
           "kui-popup-surface"
         ],
         "publicTokens": [
-          "--kui-radius-l",
+          "--kui-layout-pill-radius",
           "--kui-wa-container-inset",
           "--kui-wa-surface-inset",
           "--kui-chrome-material-raised",
           "--kui-chrome-material-filter",
           "--kui-scroll-clearance-block-start",
-          "--kui-scroll-clearance-block-end"
+          "--kui-scroll-clearance-block-end",
+          "--kui-safe-area-block-start",
+          "--kui-safe-area-block-end"
         ]
       },
       "diagnostics": [],
@@ -8724,6 +8870,68 @@
         "selection": "ai/component-catalog.json",
         "composition": "generated-permissive-default"
       }
+    },
+    {
+      "key": "@kerfjs/ui:recipe-media-detail",
+      "package": "@kerfjs/ui",
+      "id": "recipe-media-detail",
+      "name": "Media Detail",
+      "kind": "recipe",
+      "source": "kerf",
+      "parents": { "mode": "root", "entries": [] },
+      "contexts": ["application-reference"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "the artwork and its accessible description",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "the artwork's bottom color and the scheme it belongs to (the tint)",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "the stack (a signal of views)",
+          "owner": "application",
+          "required": false
+        },
+        { "id": "playback", "owner": "application", "required": false },
+        { "id": "data", "owner": "application", "required": false }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "application", "behaviors": [] },
+      "layout": {
+        "roles": ["reference-composition"],
+        "geometry": {
+          "margin": "composed",
+          "border": "composed",
+          "padding": "composed"
+        }
+      },
+      "accessibility": {
+        "obligations": [
+          "Glass control groups keep every chrome control at AA over the artwork; the tint clamps text to AA over the tinted surface; parallax, blur, and the scroll-edge fade go static under reduced motion or the static-effects switch, and the chrome and fade go opaque under reduced transparency and increased contrast."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": null,
+        "publicClasses": [],
+        "publicTokens": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
     }
   ]
 }

package/ai/components/README.md

@@ -25,6 +25,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Workbench](./workbench.md) — Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.
 - [CollapsiblePanel](./collapsible-panel.md) — Add one independently collapsible peripheral panel without adopting the complete multi-panel Workbench shell.
 - [SunkenPanel](./sunken-panel.md) — Group a vertical list of application content on a visually lowered surface with one owned 8px inset and an explicit rounded or square-corner shape.
+- [BackdropImage](./backdrop-image.md) — Open a scrolling Pane or NavStack view with a hero or tiled backdrop image (an artist, album, or place page) that lags the scroll and progressively blurs on a compositor-only scroll timeline, dissolves through a mask into an app-chosen color, and continues that color under the following content, with Kerf-owned static fallbacks.
 - [Toolbar](./toolbar.md) — Leading, centered, and trailing toolbar composition.
 - [ToolbarControlGroup](./toolbar-control-group.md) — Provide complete toolbar action geometry through configuration, including semantic anchors, overflow containment, and dropdown menu insets without application CSS.
 - [Surface Scaffolds](./surface-scaffold.md) — Configure recurring dialog and popup geometry without consumer ::part() overrides.
@@ -183,3 +184,4 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Navigation Stack](./recipe-navigation-stack.md) — A push/pop navigation stack drill-down with animated slides and a live device class.
 - [Loading Inspector](./recipe-loading-inspector.md) — A record inspector whose per-record values load asynchronously — every value-bearing component takes a shared placeholder flag, so the same chrome renders a faithful loading state and then the populated record.
 - [Collapsible Sidebar](./recipe-collapsible-sidebar.md) — A mini app frame whose left navigation rail and bottom activity drawer are standalone CollapsiblePanels driven by wireSidebar: per-side collapse/expand toggles, focus move-in and restore, a dismissable compact overlay, and per-panel persistence.
+- [Media Detail](./recipe-media-detail.md) — An Apple-Music-style album page: clear NavStack chrome with the scroll-edge material, a scoped tint from the artwork's color, an underChrome BackdropImage with parallax and progressive blur, and glass control groups.

package/ai/components/backdrop-image.md

@@ -0,0 +1,84 @@
+# BackdropImage
+
+<!-- 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:backdrop-image` · Kerf UI · component · Structure
+
+An image block at the top of a scrolling view that can lag the scroll, fade into an app color, and keep painting that color under the content below.
+
+## When to use
+
+Open a scrolling Pane or NavStack view with a hero or tiled backdrop image (an artist, album, or place page) that lags the scroll and progressively blurs on a compositor-only scroll timeline, dissolves through a mask into an app-chosen color, and continues that color under the following content, with Kerf-owned static fallbacks.
+
+- A scrolling view opens with a large mood or identity image (an artist, album, place, or collection header) whose page should read as one surface with it.
+- The image should lag the scroll (parallax), blur progressively as it scrolls away, or dissolve into a color without app scroll listeners, animated filters, or background-attachment: fixed.
+
+**Not when:**
+
+- Do not use for inline content images, thumbnails, avatars, or media a person inspects; render an img or the matching media component.
+- Do not hand-roll scroll listeners, background-attachment: fixed, animated blur filters, or mask gradients around an image in app CSS.
+- Do not put it in a region that does not scroll vertically; parallax needs a scroll container ancestor.
+
+**Alternatives:**
+
+- [Pane](./pane.md) (composes-with) — Place BackdropImage first in a Pane's scrolling content (or a NavStack view) so its scroller drives the parallax.
+- [SunkenPanel](./sunken-panel.md) (nearest) — Use SunkenPanel for a lowered work surface without imagery.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/backdrop-image` — exports `BackdropImage`.
+- CSS: the browser build of `@kerfjs/ui/backdrop-image` pulls its CSS automatically; import `@kerfjs/ui/backdrop-image.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/backdrop-image`](../public-api-signatures-v1.md#kerfjsuibackdrop-image) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- fitted image (cover, contain, fill) with a focal position
+- tiled background (repeat, repeat-x, repeat-y)
+- parallax none, subtle, or a 0 to 1 lag factor
+- progressive blur from a once-filtered copy or an app-supplied blurred asset, with an optional dim
+- fade into a color that also paints below
+- bottom or full scrim under overlay content
+- image running beneath clear or overlay chrome (underChrome)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the image, its alt text (empty for a decorative image), and responsive candidates; the fade color, whether the image lags the scroll, and whether it blurs (and any pre-blurred asset); overlay content and its contrast against the image and scrim; the content below the image; whether the image runs up beneath overlay or clear chrome and the top safe area (underChrome); it must then be the first child of the Pane's content.
+
+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.
+
+- The root bleeds to the Pane's resolved inline insets (the safe area) and hands them back to its overlay and content, so their items keep the ordinary text axis.
+- The image block is height tall (default 320px) and grows with taller overlay content.
+
+## Accessibility
+
+- alt describes a meaningful image; pass an empty alt for a decorative one. A tiled image with alt text is exposed as role="img". Parallax and the progressive blur run only with prefers-reduced-motion: no-preference and scroll-driven animation support, and are off under data-kui-effects="static" and on slow-update displays, leaving a static, sharp image; the blurred copy is decorative and aria-hidden. Reduced transparency or increased contrast replaces the fade with a hard edge on solid fadeTo and puts overlay content on a solid fadeTo band. Overlay text needs a scrim or fade color that keeps it at AA.
+
+## 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-backdrop-image`.
+
+Never put `kui-backdrop-image` on an element you write; render `BackdropImage` 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: [Pane](./pane.md), [SunkenPanel](./sunken-panel.md).
+- Docs: [`docs/backdrop-image.md`](../../docs/backdrop-image.md), [`docs/backdrop-image.md#fallbacks`](../../docs/backdrop-image.md#fallbacks).
+- UX catalog route: `?component=backdrop-image`.

package/ai/components/nav-stack.md

@@ -50,6 +50,9 @@ Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1
 - permanent or no chrome dividers (chromeDividers always or none)
 - translucent top chrome laid over the active view (chromePresentation overlay, measured by wireNavStack)
 - translucent bottom toolbar laid over the active view (bottomToolbarPresentation overlay, measured by wireNavStack)
+- app-chosen stack background color (background); overlay chrome keeps the chrome material
+- scoped tint (tint)
+- clear (transparent) bars with an optional scroll-edge material (chromePresentation / bottomToolbarPresentation: clear, scrollEdge: material)
 
 ## Composition
 
@@ -60,7 +63,7 @@ Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1
 
 ## State and wiring
 
-**The app owns:** ordered view stack and stable keys; view content and structured top and bottom toolbar configurations; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar or a persistent structured fallback; per-view leading, center, and trailing top-toolbar groups; per-view header and footer with List and Pane configuration; top-toolbar defaults, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers); whether the top chrome docks above the active view or lies over it on the translucent chrome material (chromePresentation); whether the bottom toolbar docks below the active view or lies over it on the translucent chrome material (bottomToolbarPresentation).
+**The app owns:** ordered view stack and stable keys; view content and structured top and bottom toolbar configurations; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar or a persistent structured fallback; per-view leading, center, and trailing top-toolbar groups; per-view header and footer with List and Pane configuration; top-toolbar defaults, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers); whether the top chrome docks above the active view or lies over it on the translucent chrome material (chromePresentation); whether the bottom toolbar docks below the active view or lies over it on the translucent chrome material (bottomToolbarPresentation); an optional app-chosen color for the stack, its docked chrome and bottom toolbar, and every view (background, a typed CssColor); one view's own color goes in its pane: { background }; an optional scoped tint for the stack, its chrome, and views: tint: { color, scheme } re-derives surface and text tokens from an app color with text kept at AA.
 
 **Wiring:** `wireNavStack`, `wireScrollDividers` is required.
 
@@ -95,6 +98,8 @@ Margin: none · border: conditional · padding: child (layout role: structure).
 - Mark a preferred initial heading or control with data-nav-focus when the first enabled focusable descendant is not the right target.
 - Overlay chrome (chromePresentation overlay) keeps WCAG AA over content passing beneath the translucent material: an untoned ToolbarText there takes the normal text color for its title and lifts its description halfway toward it; keep other quiet copy in the view. The material turns opaque under reduced transparency, increased contrast, forced colors, or without backdrop-filter.
 - An overlay bottom toolbar (bottomToolbarPresentation overlay) keeps the same AA rule: an untoned ToolbarText there lifts its title and description, and a default-tone ToolbarControlGroup in either overlaid bar takes the normal text color for its controls. Its 1px top edge stays visible in forced colors.
+- A background color is app-chosen: Keep text at WCAG AA over the color: a dark background needs dark-tone content or a scoped tint; forced colors paint Canvas instead.
+- Clear bars have no material of their own: keep their controls in glass ToolbarControlGroups; they turn opaque under reduced transparency or increased contrast and paint Canvas in forced colors.
 
 ## Styling boundary
 

package/ai/components/pane.md

@@ -18,6 +18,9 @@ Organize a sidebar, main area, inspector, or dialog column into fixed vertical h
 - An opaque edge-to-edge child needs a reserved vertical scrollbar gutter.
 - Scrolling content must pass beneath chrome laid over the pane edge (a DialogSurface floating footer) while its first and last items still rest clear of it (scrollClearance).
 - The header should float over the scrolling content on a translucent material so content scrolls visibly beneath it, with the first item still resting below the header (headerPresentation: overlay, measured by wireScrollDividers).
+- A pane needs an app-chosen surface color, such as a media detail page painted in its artwork's color (background, a typed CssColor; also in PaneConfig).
+- A region should take on an app color (a media page in its artwork's color) with its text, quiet text, links, fills, and chrome material re-derived to keep AA (tint: { color, scheme }; also in PaneConfig).
+- The header lies over imagery and must be fully transparent, with glass control groups for legibility and the material fading back in once content scrolls beneath (headerPresentation: clear, scrollEdge: material).
 
 **Not when:**
 
@@ -53,6 +56,9 @@ Exact prop names and types: [`@kerfjs/ui/pane`](../public-api-signatures-v1.md#k
 - always or no chrome dividers
 - scrollClearance block-start, block-end, or both on the scrolling content
 - overlay header on the translucent chrome material (headerPresentation: overlay)
+- app-chosen background color (background), replacing the default or sunken fill
+- scoped tint re-deriving surface and text tokens from an app color (tint)
+- clear (transparent) overlay header, optionally with the scroll-edge material (headerPresentation: clear, scrollEdge: material)
 
 ## Composition
 
@@ -68,7 +74,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 ## State and wiring
 
-**The app owns:** root and content semantics; accessible labels; header, content, and footer children; which logical boundaries show separators; which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges); responsive placement and visibility; whether the chrome dividers follow the scroll, always show, or never show (chromeDividers); default or sunken scrolling work surface (appearance); whether to reserve a vertical scrollbar gutter for opaque edge-to-edge content (--kui-pane-scrollbar-gutter); optional keyboard or programmatic focus (tabIndex) and persistent focus outline (outlined); whether the scrolling content clears overlaying chrome on its block edges (scrollClearance, also in PaneConfig, so a Workbench mainPane or panel pane, a CollapsiblePanel pane, or a NavStack view pane forwards it); whether the header is docked in its own row or laid over the scrolling content on the translucent chrome material (headerPresentation, also in PaneConfig).
+**The app owns:** root and content semantics; accessible labels; header, content, and footer children; which logical boundaries show separators; which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges); responsive placement and visibility; whether the chrome dividers follow the scroll, always show, or never show (chromeDividers); default or sunken scrolling work surface (appearance); whether to reserve a vertical scrollbar gutter for opaque edge-to-edge content (--kui-pane-scrollbar-gutter); optional keyboard or programmatic focus (tabIndex) and persistent focus outline (outlined); whether the scrolling content clears overlaying chrome on its block edges (scrollClearance, also in PaneConfig, so a Workbench mainPane or panel pane, a CollapsiblePanel pane, or a NavStack view pane forwards it); whether the header is docked in its own row or laid over the scrolling content on the translucent chrome material (headerPresentation, also in PaneConfig); an optional app-chosen surface color that replaces the appearance's fill (background, a typed CssColor from @kerfjs/ui/css-values, also in PaneConfig, so a Workbench panel or mainPane, a CollapsiblePanel pane, or a NavStack view pane forwards it); an optional scoped tint (tint: { color, scheme }, also in PaneConfig): the color and the declared light or dark scheme it belongs to; Kerf does no color detection; an optional tint accent (tint.accent) that re-derives the brand ramp, links, and focus ring inside the tinted scope at AA.
 
 **Wiring:** `wireScrollDividers` is optional.
 
@@ -89,12 +95,16 @@ Margin: child · border: conditional · padding: child (layout role: structure).
 - For opaque edge-to-edge children, --kui-pane-scrollbar-gutter: stable reserves a vertical scrollbar gutter outside the published content insets; the default is auto.
 - scrollClearance adds the inherited --kui-scroll-clearance-block-start/end context, published by overlaying chrome, to the scrolling content block padding and scroll padding alongside safe areas and deepInset.
 - headerPresentation overlay: once wireScrollDividers measures the header, the header shares the content cell above the scroller, its border-box height is published as --kui-scroll-clearance-block-start on the Pane root, and the content clears it automatically; unwired or with chromePlacement auto, the header stays docked.
+- The scrolling content also publishes its resolved block-start padding (safe area, deepInset, and overlay or clear header clearance) as --kui-pane-content-inset-block-start, so a first child such as an underChrome BackdropImage can run up beneath it.
 
 ## Accessibility
 
 - Choose semantic root and content elements that match the region and provide labels for landmark elements.
 - Keep fixed header/footer chrome outside the single scrolling content slot so reading and focus order remain coherent.
 - An overlay header's text uses the normal text color, which keeps WCAG AA over the 80% chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.
+- A background color is app-chosen: Keep text at WCAG AA over the color: a dark background needs dark-tone content or a scoped tint; forced colors paint Canvas instead.
+- A tint clamps the re-derived surface and text lightness so normal, quiet, link, and neutral-on-quiet text keep 4.5:1 over the tinted surface, raised surface, and quiet fills for any color; under prefers-contrast: more or without relative color syntax the scope keeps the plain palette in its declared scheme.
+- A clear header has no material of its own: keep its controls in glass ToolbarControlGroups and a title over imagery on a scrim; it turns opaque under reduced transparency or increased contrast and paints Canvas in forced colors.
 
 ## Styling boundary
 

package/ai/components/recipe-media-detail.md

@@ -0,0 +1,57 @@
+# Media Detail
+
+<!-- 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:recipe-media-detail` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+An Apple-Music-style album page: clear NavStack chrome with the scroll-edge material, a scoped tint from the artwork's color, an underChrome BackdropImage with parallax and progressive blur, and glass control groups.
+
+- A detail page for media (an album, artist, film, or place) should take on its artwork's color with the artwork running beneath transparent chrome.
+
+**Not when:**
+
+- Use the Navigation Stack recipe for a plain drill-down; imagery, tint, and clear chrome are for pages whose artwork is the identity.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [NavStack](./nav-stack.md), [Pane](./pane.md), [BackdropImage](./backdrop-image.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md).
+
+## State and wiring
+
+**The app owns:** the artwork and its accessible description; the artwork's bottom color and the scheme it belongs to (the tint); the stack (a signal of views); playback; data.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Glass control groups keep every chrome control at AA over the artwork; the tint clamps text to AA over the tinted surface; parallax, blur, and the scroll-edge fade go static under reduced motion or the static-effects switch, and the chrome and fade go opaque under reduced transparency and increased contrast.
+
+## 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: [NavStack](./nav-stack.md), [Pane](./pane.md), [BackdropImage](./backdrop-image.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md).
+- Docs: [`docs/recipes.md#media-detail`](../../docs/recipes.md#media-detail).
+- UX catalog route: `?component=recipe-media-detail`.