@owlmeans/web-panel 0.1.18-rc.11 → 0.1.18-rc.12

package/build/components/nav/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/components/nav/layout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAA;AAO/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAahD;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,EAAE,CAAC,cAAc,CAiCxC,CAAA"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/components/nav/layout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAA;AAO/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAahD;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,EAAE,CAAC,cAAc,CAiDxC,CAAA"}

package/build/components/nav/layout.js

@@ -22,11 +22,11 @@ const CONTAINER = 'mx-auto w-full max-w-6xl px-4';
  * viewports and one strip for narrow ones. Both render only when the active section has
  * more than one screen, so the single-screen case costs nothing but the elements' absence.
  */
-export const NavLayout = ({ nav, translate, title, home, actions, footer, children, className, style, contentClassName, containerClassName }) => {
+export const NavLayout = ({ nav, translate, title, home, actions, footer, children, className, style, headerClassName, contentClassName, containerClassName }) => {
     const navigator = useNavigate();
     const brandAlias = home ?? nav.sections.find(section => section.items.length > 0)?.items[0]?.alias;
     const container = containerClassName ?? CONTAINER;
-    return _jsxs("div", { className: cn('flex min-h-screen flex-col bg-background text-foreground', className), style: style, children: [_jsxs("header", { className: "sticky top-0 z-40 border-b bg-background", children: [_jsxs("div", { className: cn('flex h-14 items-center gap-6', container), children: [title != null ? _jsx("a", { onClick: brandAlias != null ? navigator.press(brandAlias) : undefined, className: cn('brand flex items-center gap-2 text-lg font-semibold', brandAlias != null && 'cursor-pointer'), children: title }) : null, _jsx(TopNav, { config: nav, translate: translate, ariaLabel: "Sections" }), _jsx("div", { className: "ml-auto flex items-center gap-2", children: actions })] }), _jsx(SideNav, { config: nav, translate: translate, variant: "bar", ariaLabel: "Screens", className: "md:hidden" })] }), _jsxs("div", { className: "flex flex-1", children: [_jsx(SideNav, { config: nav, translate: translate, variant: "side", ariaLabel: "Screens", className: "hidden md:block" }), _jsx("main", { className: cn('flex-1 py-8', contentClassName), children: _jsx("div", { className: cn(container), children: children }) })] }), Array.isArray(footer)
+    return _jsxs("div", { className: cn('flex min-h-screen flex-col bg-background text-foreground', className), style: style, children: [_jsxs("header", { className: cn('sticky top-0 z-40 border-b bg-background text-foreground', headerClassName), children: [_jsxs("div", { className: cn('flex h-14 items-center gap-6', container), children: [title != null ? _jsx("a", { onClick: brandAlias != null ? navigator.press(brandAlias) : undefined, className: cn('brand flex items-center gap-2 text-lg font-semibold', brandAlias != null && 'cursor-pointer'), children: title }) : null, _jsx(TopNav, { config: nav, translate: translate, ariaLabel: "Sections" }), _jsx("div", { className: "ml-auto flex items-center gap-2", children: actions })] }), _jsx(SideNav, { config: nav, translate: translate, variant: "bar", ariaLabel: "Screens", className: "md:hidden" })] }), _jsxs("div", { className: "flex flex-1", children: [_jsx(SideNav, { config: nav, translate: translate, variant: "side", ariaLabel: "Screens", className: "hidden md:block" }), _jsx("main", { className: cn('flex-1 py-8', contentClassName), children: _jsx("div", { className: cn(container), children: children }) })] }), Array.isArray(footer)
                 ? _jsx(Footer, { links: footer, translate: translate, containerClassName: container })
                 : footer != null ? _jsx(Footer, { containerClassName: container, children: footer }) : null] });
 };

package/build/components/nav/layout.js.map

@@ -1 +1 @@
-{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../../src/components/nav/layout.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAGjC;;;;;;;;GAQG;AACH,MAAM,SAAS,GAAG,+BAA+B,CAAA;AAEjD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAuB,CAAC,EAC5C,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EACxE,gBAAgB,EAAE,kBAAkB,EACrC,EAAE,EAAE;IACH,MAAM,SAAS,GAAG,WAAW,EAAE,CAAA;IAC/B,MAAM,UAAU,GAAG,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAA;IAClG,MAAM,SAAS,GAAG,kBAAkB,IAAI,SAAS,CAAA;IAEjD,OAAO,eACL,SAAS,EAAE,EAAE,CAAC,0DAA0D,EAAE,SAAS,CAAC,EACpF,KAAK,EAAE,KAAK,aAEZ,kBAAQ,SAAS,EAAC,0CAA0C,aAC1D,eAAK,SAAS,EAAE,EAAE,CAAC,8BAA8B,EAAE,SAAS,CAAC,aAC1D,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,YACf,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,EACrE,SAAS,EAAE,EAAE,CAAC,qDAAqD,EAAE,UAAU,IAAI,IAAI,IAAI,gBAAgB,CAAC,YAC5G,KAAK,GAAK,CAAC,CAAC,CAAC,IAAI,EACnB,KAAC,MAAM,IAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAC,UAAU,GAAG,EAClE,cAAK,SAAS,EAAC,iCAAiC,YAAE,OAAO,GAAO,IAC5D,EACN,KAAC,OAAO,IAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAC,KAAK,EAAC,SAAS,EAAC,SAAS,EAAC,SAAS,EAAC,WAAW,GAAG,IAC/F,EACT,eAAK,SAAS,EAAC,aAAa,aAC1B,KAAC,OAAO,IAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAC,MAAM,EAAC,SAAS,EAAC,SAAS,EAAC,SAAS,EAAC,iBAAiB,GAAG,EAC7G,eAAM,SAAS,EAAE,EAAE,CAAC,aAAa,EAAE,gBAAgB,CAAC,YAClD,cAAK,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,YAAG,QAAQ,GAAO,GAC1C,IACH,EACL,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBACpB,CAAC,CAAC,KAAC,MAAM,IAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,kBAAkB,EAAE,SAAS,GAAI;gBAChF,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAC,MAAM,IAAC,kBAAkB,EAAE,SAAS,YAAG,MAAM,GAAU,CAAC,CAAC,CAAC,IAAI,IAChF,CAAA;AACR,CAAC,CAAA"}
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../../src/components/nav/layout.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAGjC;;;;;;;;GAQG;AACH,MAAM,SAAS,GAAG,+BAA+B,CAAA;AAEjD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAuB,CAAC,EAC5C,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EACxE,eAAe,EAAE,gBAAgB,EAAE,kBAAkB,EACtD,EAAE,EAAE;IACH,MAAM,SAAS,GAAG,WAAW,EAAE,CAAA;IAC/B,MAAM,UAAU,GAAG,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAA;IAClG,MAAM,SAAS,GAAG,kBAAkB,IAAI,SAAS,CAAA;IAEjD,OAAO,eACL,SAAS,EAAE,EAAE,CAAC,0DAA0D,EAAE,SAAS,CAAC,EACpF,KAAK,EAAE,KAAK,aAkBZ,kBAAQ,SAAS,EAAE,EAAE,CAAC,0DAA0D,EAAE,eAAe,CAAC,aAChG,eAAK,SAAS,EAAE,EAAE,CAAC,8BAA8B,EAAE,SAAS,CAAC,aAC1D,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,YACf,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,EACrE,SAAS,EAAE,EAAE,CAAC,qDAAqD,EAAE,UAAU,IAAI,IAAI,IAAI,gBAAgB,CAAC,YAC5G,KAAK,GAAK,CAAC,CAAC,CAAC,IAAI,EACnB,KAAC,MAAM,IAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAC,UAAU,GAAG,EAClE,cAAK,SAAS,EAAC,iCAAiC,YAAE,OAAO,GAAO,IAC5D,EACN,KAAC,OAAO,IAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAC,KAAK,EAAC,SAAS,EAAC,SAAS,EAAC,SAAS,EAAC,WAAW,GAAG,IAC/F,EACT,eAAK,SAAS,EAAC,aAAa,aAC1B,KAAC,OAAO,IAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAC,MAAM,EAAC,SAAS,EAAC,SAAS,EAAC,SAAS,EAAC,iBAAiB,GAAG,EAC7G,eAAM,SAAS,EAAE,EAAE,CAAC,aAAa,EAAE,gBAAgB,CAAC,YAClD,cAAK,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,YAAG,QAAQ,GAAO,GAC1C,IACH,EACL,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBACpB,CAAC,CAAC,KAAC,MAAM,IAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,kBAAkB,EAAE,SAAS,GAAI;gBAChF,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAC,MAAM,IAAC,kBAAkB,EAAE,SAAS,YAAG,MAAM,GAAU,CAAC,CAAC,CAAC,IAAI,IAChF,CAAA;AACR,CAAC,CAAA"}

package/build/components/nav/types.d.ts

@@ -27,6 +27,16 @@ export interface NavLayoutProps extends PropsWithChildren<StyledProps> {
     actions?: ReactNode;
     /** Links array renders the standard footer; a node replaces it entirely. */
     footer?: PanelNavLink[] | ReactNode;
+    /**
+     * Styles the HEADER — the sticky bar carrying the brand, the section menu and `actions`.
+     *
+     * The header is its own SURFACE: it paints an opaque background because content scrolls
+     * under it. Give it a background here and you must give it the paired foreground too
+     * (`bg-secondary text-secondary-foreground`), exactly as on any other surface — this is the
+     * supported way to give an application a dark top bar, and it is why colouring the root
+     * instead is not.
+     */
+    headerClassName?: string;
     /** Styles the content area. NOT its width — see `containerClassName`. */
     contentClassName?: string;
     /**

package/build/components/nav/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/nav/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,UAAU,cAAe,SAAQ,WAAW;IAC1C,MAAM,EAAE,cAAc,CAAA;IACtB,yFAAyF;IACzF,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,WAAY,SAAQ,cAAc;CAAI;AAEvD,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;CACzB;AAED,MAAM,WAAW,cAAe,SAAQ,iBAAiB,CAAC,WAAW,CAAC;IACpE,GAAG,EAAE,cAAc,CAAA;IACnB,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yFAAyF;IACzF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,SAAS,CAAA;IACnC,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/nav/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,UAAU,cAAe,SAAQ,WAAW;IAC1C,MAAM,EAAE,cAAc,CAAA;IACtB,yFAAyF;IACzF,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,WAAY,SAAQ,cAAc;CAAI;AAEvD,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;CACzB;AAED,MAAM,WAAW,cAAe,SAAQ,iBAAiB,CAAC,WAAW,CAAC;IACpE,GAAG,EAAE,cAAc,CAAA;IACnB,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yFAAyF;IACzF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,SAAS,CAAA;IACnC;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/web-panel",
-  "version": "0.1.18-rc.11",
+  "version": "0.1.18-rc.12",
   "license": "MIT",
   "type": "module",
   "scripts": {

package/src/components/nav/layout.tsx

@@ -28,7 +28,7 @@ const CONTAINER = 'mx-auto w-full max-w-6xl px-4'
  */
 export const NavLayout: FC<NavLayoutProps> = ({
   nav, translate, title, home, actions, footer, children, className, style,
-  contentClassName, containerClassName
+  headerClassName, contentClassName, containerClassName
 }) => {
   const navigator = useNavigate()
   const brandAlias = home ?? nav.sections.find(section => section.items.length > 0)?.items[0]?.alias
@@ -38,7 +38,23 @@ export const NavLayout: FC<NavLayoutProps> = ({
     className={cn('flex min-h-screen flex-col bg-background text-foreground', className)}
     style={style}
   >
-    <header className="sticky top-0 z-40 border-b bg-background">
+    {/*
+      * The header is a SURFACE, and it states both halves of one.
+      *
+      * It has to paint an opaque background — it is sticky, and content scrolls underneath —
+      * which makes it a different surface from the root behind it. A colour set on the root
+      * (`className="bg-secondary text-secondary-foreground"`, a dark application shell) then
+      * inherits INTO this bar while its own `bg-background` stays put, and every child that
+      * states no colour of its own — the brand, a ghost-variant action button — is painted in
+      * the foreground of a surface it is not on. That is light-on-light, it raises nothing at
+      * build or run time, and it is invisible only to whoever opens the page.
+      *
+      * `text-foreground` is what stops the inheritance at the boundary. It is not decoration
+      * and it is not redundant with the root: pairing has to be restated by every element that
+      * repaints its own background. `headerClassName` lands after it, so an app that wants a
+      * dark bar overrides BOTH halves through tailwind-merge.
+      */}
+    <header className={cn('sticky top-0 z-40 border-b bg-background text-foreground', headerClassName)}>
       <div className={cn('flex h-14 items-center gap-6', container)}>
         {title != null ? <a
           onClick={brandAlias != null ? navigator.press(brandAlias) : undefined}

package/src/components/nav/types.ts

@@ -30,6 +30,16 @@ export interface NavLayoutProps extends PropsWithChildren<StyledProps> {
   actions?: ReactNode
   /** Links array renders the standard footer; a node replaces it entirely. */
   footer?: PanelNavLink[] | ReactNode
+  /**
+   * Styles the HEADER — the sticky bar carrying the brand, the section menu and `actions`.
+   *
+   * The header is its own SURFACE: it paints an opaque background because content scrolls
+   * under it. Give it a background here and you must give it the paired foreground too
+   * (`bg-secondary text-secondary-foreground`), exactly as on any other surface — this is the
+   * supported way to give an application a dark top bar, and it is why colouring the root
+   * instead is not.
+   */
+  headerClassName?: string
   /** Styles the content area. NOT its width — see `containerClassName`. */
   contentClassName?: string
   /**

package/tests/harness/mount.tsx

@@ -53,6 +53,12 @@ const Layout: FC<PropsWithChildren> = ({ children }) => <NavLayout
   title="Harness"
   actions={<button id="action-slot">action</button>}
   footer={footerLinks}
+  // A DARK APPLICATION SHELL, which is what a themed app does to the root: a contrasting
+  // surface pair, both halves correct. The header paints its own opaque background, so it is
+  // a different surface, and everything in it must stay legible against `--background`
+  // rather than against this. The harness carries it permanently so every navigation test
+  // runs against the hostile case instead of a default-coloured page.
+  className="bg-primary text-primary-foreground"
 >{children}</NavLayout>
 
 /** A grouping screen — it renders whichever child the router matched. */

package/tests/nav.spec.ts

@@ -98,6 +98,88 @@ describe('@owlmeans/web-panel — two-layer navigation', () => {
   }, TIMEOUT)
 })
 
+/**
+ * Perceptual lightness of a computed colour, 0 (black) to 1 (white).
+ *
+ * The theme is authored in `oklch(L C H)` and Chromium hands that back from
+ * `getComputedStyle` unchanged — it does not convert to `rgb()`, and neither does a canvas
+ * `fillStyle` round-trip — so L is read straight off. `rgb()` still turns up for the
+ * transparent case, and is approximated through its luminance.
+ *
+ * Comparing lightness rather than colour strings is the point: the failure being pinned is
+ * not a wrong colour, it is two colours too CLOSE to tell apart, which equality never sees.
+ */
+const lightness = (value: string): number => {
+  const oklch = /^oklch\(\s*([\d.]+%?)/i.exec(value.trim())
+  if (oklch != null) {
+    const raw = oklch[1]
+
+    return raw.endsWith('%') ? parseFloat(raw) / 100 : parseFloat(raw)
+  }
+
+  const [r, g, b] = (value.match(/[\d.]+/g) ?? []).slice(0, 3).map(Number)
+  const channel = (c: number): number => {
+    const v = c / 255
+
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4
+  }
+
+  // The cube root maps luminance onto roughly the same perceptual scale as OKLab's L.
+  return (0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)) ** (1 / 3)
+}
+
+/** The gap below which text stops being readable on its surface — as `ensureReadableTheme`. */
+const READABLE = 0.35
+
+describe('@owlmeans/web-panel — the header is its own surface', () => {
+  // The harness root carries `bg-primary text-primary-foreground`: a dark application shell,
+  // both halves of the pair correct. The header paints `bg-background` over it and is
+  // therefore a DIFFERENT surface — a near-white foreground inherited from the root lands on
+  // a near-white bar, and every child stating no colour of its own goes invisible. Nothing
+  // fails at build or at run time, so this is pinned from outside, on rendered pixels.
+  test('header content stays legible when the shell around it is dark', async () => {
+    const { page, close } = await open('/dash')
+    try {
+      await page.waitForSelector('#dash')
+      const style = async (selector: string, property: 'color' | 'backgroundColor') =>
+        page.locator(selector).first().evaluate(
+          (el, prop) => window.getComputedStyle(el)[prop as 'color'], property
+        )
+
+      const surface = lightness(await style('header', 'backgroundColor'))
+      const legible = async (selector: string) =>
+        Math.abs(lightness(await style(selector, 'color')) - surface) >= READABLE
+
+      // The brand and the action slot state no colour of their own, so they are exactly the
+      // elements that inherit across the boundary. The action slot is the reported case: a
+      // ghost-variant button rendered white on a white bar.
+      expect({
+        brand: await legible('a.brand'),
+        actions: await legible('#action-slot'),
+        section: await legible('[data-slot="navigation-menu-link"]'),
+      }).toEqual({ brand: true, actions: true, section: true })
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('the header keeps an opaque background of its own', async () => {
+    // This is what makes it a separate surface, and therefore what makes the pairing above
+    // mandatory rather than redundant: it is sticky, so content scrolls beneath it and a
+    // transparent bar would show that content through the menu.
+    const { page, close } = await open('/dash')
+    try {
+      await page.waitForSelector('#dash')
+      const background = await page.locator('header').first()
+        .evaluate(el => window.getComputedStyle(el).backgroundColor)
+
+      expect(background).not.toMatch(/rgba\(0, 0, 0, 0\)|transparent/)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})
+
 describe('@owlmeans/web-panel — layout rhythm and link styling', () => {
   test('header, content and footer share one horizontal rhythm', async () => {
     // A content area with a width of its own sits visibly inset from a full-width header, which