@hraness/design-kit 0.36.3 → 0.36.5

package/dist/stylex.css

@@ -3066,10 +3066,6 @@
     min-block-size: 2.75rem;
   }
 
-  .xd0akbl {
-    min-block-size: 2rem;
-  }
-
   .xo67i2s {
     min-block-size: 3.25rem;
   }
@@ -3090,12 +3086,16 @@
     min-block-size: var(--hraness-marketing-header-action-height, 2rem);
   }
 
-  .x1jqubh4 {
-    min-block-size: var(--hraness-marketing-header-height, 2.75rem);
+  .x5c9nq0 {
+    min-block-size: var(--hraness-marketing-header-control-target, 2rem);
+  }
+
+  .x5zky9q {
+    min-block-size: var(--hraness-marketing-header-control-target, var(--interactive-target-compact, 2.75rem));
   }
 
-  .x1qwoi4t {
-    min-block-size: var(--interactive-target-compact, 2.75rem);
+  .x1jqubh4 {
+    min-block-size: var(--hraness-marketing-header-height, 2.75rem);
   }
 
   .x1j3ipif {
@@ -3114,10 +3114,6 @@
     min-inline-size: 0;
   }
 
-  .x1o8ym9z {
-    min-inline-size: 2rem;
-  }
-
   .xze7o54 {
     min-inline-size: 40rem;
   }
@@ -3134,8 +3130,12 @@
     min-inline-size: 9rem;
   }
 
-  .x9hh0qe {
-    min-inline-size: var(--interactive-target-compact, 2.75rem);
+  .xye2cm2 {
+    min-inline-size: var(--hraness-marketing-header-control-target, 2rem);
+  }
+
+  .xq5ipov {
+    min-inline-size: var(--hraness-marketing-header-control-target, var(--interactive-target-compact, 2.75rem));
   }
 
   .xz1t8dp {
@@ -4202,15 +4202,23 @@
     .xn27wch.xn27wch {
       min-block-size: max(2.75rem,var(--hraness-marketing-header-action-height, 2rem));
     }
+  }
+
+  @media (pointer: coarse) {
+    .xczs0xf.xczs0xf {
+      min-block-size: max(3rem,var(--hraness-marketing-header-control-target, 3rem));
+    }
+  }
 
+  @media (width <= 48rem) {
     .x1l2grcz.x1l2grcz {
       min-inline-size: 0;
     }
   }
 
   @media (pointer: coarse) {
-    .x11je3w3.x11je3w3 {
-      min-inline-size: 3rem;
+    .x12c0uzw.x12c0uzw {
+      min-inline-size: max(3rem,var(--hraness-marketing-header-control-target, 3rem));
     }
   }
 
@@ -5699,6 +5707,10 @@
   --hraness-marketing-grid-columns: initial;
 }
 
+.xlhppvv {
+  --hraness-marketing-header-control-target: 2.75rem;
+}
+
 .xphms39 {
   --hraness-marketing-pillar-columns: 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/design-kit",
-  "version": "0.36.3",
+  "version": "0.36.5",
   "description": "React components and CSS for Hraness apps and product sites: application shells, marketing sections, charts, themes, effects, and syntax highlighting. Built on @hraness/ui.",
   "license": "MIT",
   "type": "module",
@@ -143,6 +143,7 @@
     "src/browser/artifact-share.ts",
     "src/browser/foil.ts",
     "src/browser/index.ts",
+    "src/browser/marketing-header.ts",
     "src/browser/status-field.ts",
     "src/browser/status-page.ts",
     "src/browser/sticky-offset.ts",
@@ -322,7 +323,7 @@
     "test": "bun test --preload ./scripts/register-stylex-test-transform.ts ./src",
     "browser:install": "bun ./node_modules/playwright-core/cli.js install chromium",
     "test:browser": "bun run test:browser:marketing && bun run test:browser:rest",
-    "test:browser:marketing": "bun run ./scripts/product-marketing-browser.ts",
+    "test:browser:marketing": "bun run ./scripts/product-marketing-browser.ts && bun run ./scripts/marketing-header-browser.ts",
     "test:browser:rest": "bun run ./scripts/site-shell-browser.ts && bun run ./scripts/palette-browser.ts && bun run ./scripts/gallery-browser.ts && bun run ./scripts/global-error-browser.ts && bun run ./scripts/security-delivery-browser.ts && bun run ./scripts/paper-theme-browser.ts && bun run ./scripts/product-marketing-preset-browser.ts && bun run ./scripts/lantern-material-browser.ts && bun run ./scripts/foil-browser.ts && bun run ./scripts/hero-light-browser.ts && bun run ./scripts/status-page-browser.ts && bun run ./scripts/platform-install-browser.ts && bun run ./scripts/mockups-browser.ts && bun run ./scripts/agent-setup-browser.ts",
     "test:package": "bun run ./scripts/package-smoke.ts && bun run ./scripts/mockups-import.ts",
     "kb:refresh": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.24.0/hraness-wordcell-0.24.0.tgz wordcell refresh --root kb",

package/portfolio-inventory.json

@@ -6,7 +6,7 @@
       "name": "@hraness/design-kit",
       "path": ".",
       "visibility": "public",
-      "version": "0.36.3"
+      "version": "0.36.5"
     }
   ],
   "contract": "hraness.portfolio-inventory/v1",

package/src/browser/index.ts

@@ -5,6 +5,7 @@ export * from "./artifact-share.js";
 export * from "./design-palette.js";
 export * from "./foil.js";
 export * from "./hero-light.js";
+export * from "./marketing-header.js";
 export * from "./status-page.js";
 export * from "./sticky-offset.js";
 export * from "../palette-appearance.js";

package/src/browser/marketing-header.ts

@@ -0,0 +1,113 @@
+export interface MarketingHeaderOptions {
+  readonly brandHref?: string;
+  readonly brandLabel?: string;
+  readonly brandMark?: string;
+  /** Fixed-theme and authentication pages may explicitly omit appearance. */
+  readonly appearance?: "required" | "omitted";
+  /** Turn off geometry only when inspecting an unrendered DOM in unit tests. */
+  readonly measure?: boolean;
+  /** Require hydrated sticky clearance to match the live header height. */
+  readonly stickyOffset?: boolean;
+}
+
+export interface MarketingHeaderInspection {
+  readonly headerCount: number;
+  readonly appearanceCount: number;
+  readonly brandHref: string | null;
+  readonly brandLabel: string | null;
+  readonly brandMark: string | null;
+  readonly links: readonly Readonly<{ href: string; label: string }>[];
+  readonly problems: readonly string[];
+}
+
+/**
+ * Inspect a complete public page, including article, documentation, and status
+ * routes. This read-only function is self-contained so browser runners can use
+ * `page.evaluate(inspectMarketingHeader, options)` without loading a test script.
+ */
+export function inspectMarketingHeader(
+  options: MarketingHeaderOptions = {},
+  document: Document = globalThis.document,
+): MarketingHeaderInspection {
+  const problems: string[] = [];
+  const headers = document.querySelectorAll('header[data-hraness-marketing="header"], header.hraness-marketing-header, header.hraness-marketing-header-surface');
+  const appearances = document.querySelectorAll("[data-hraness-appearance-menu]");
+  const mains = document.querySelectorAll("main");
+  const header = headers[0];
+  if (headers.length !== 1) problems.push(`Expected one product header; found ${headers.length}.`);
+  if (mains.length !== 1) problems.push(`Expected one main landmark; found ${mains.length}.`);
+  const appearanceCount = options.appearance === "omitted" ? 0 : 1;
+  if (appearances.length !== appearanceCount) problems.push(`Expected ${appearanceCount} appearance controls; found ${appearances.length}.`);
+
+  const brand = header?.querySelector<HTMLAnchorElement>("a.hraness-marketing-header__brand");
+  const mark = brand?.querySelector(".hraness-foil-mark");
+  const image = mark?.querySelector("img");
+  const brandHref = brand?.getAttribute("href") ?? null;
+  const brandLabel = (brand?.getAttribute("aria-label") ?? brand?.textContent)?.trim() || null;
+  const brandMark = image?.getAttribute("src") ?? null;
+  const nav = header?.querySelector("nav.hraness-marketing-header__nav");
+  const links = [...(nav?.querySelectorAll("a[href]") ?? [])].map(link => ({
+    href: link.getAttribute("href") ?? "",
+    label: (link.getAttribute("aria-label") ?? link.textContent)?.trim() ?? "",
+  }));
+  if (header !== undefined) {
+    const main = mains[0];
+    if (main !== undefined && (main.contains(header) || header.contains(main) || !(header.compareDocumentPosition(main) & 4))) {
+      problems.push("The product header must precede and sit outside the main landmark.");
+    }
+    if (brandHref !== (options.brandHref ?? "/")) problems.push("The product home link is missing or points to a different page.");
+    if (brandLabel === null || (options.brandLabel !== undefined && brandLabel !== options.brandLabel)) problems.push("The product home link has a missing or inconsistent name.");
+    if (brand?.hasAttribute("data-foil") !== true || mark === null || mark === undefined || image === null || image === undefined || !mark.querySelector(".hraness-foil-mark__paint") || !brandMark) {
+      problems.push("The product home link is missing its foil mark and artwork fallback.");
+    } else if (options.brandMark !== undefined && brandMark !== options.brandMark) {
+      problems.push("The product header uses different mark artwork.");
+    }
+    if (!nav || !(nav.getAttribute("aria-label")?.trim() || nav.getAttribute("aria-labelledby")?.trim()) || links.length === 0 || links.some(link => !link.label)) {
+      problems.push("The product header needs a named navigation with readable links.");
+    }
+    const appearance = appearances[0];
+    const actions = header.querySelector(".hraness-marketing-header__actions");
+    if (appearanceCount === 1 && appearance !== undefined) {
+      if (!actions?.contains(appearance) || !actions.lastElementChild?.contains(appearance)) {
+        problems.push("Appearance must be the final product-header action.");
+      }
+      if (!appearance.querySelector(":scope > summary, :scope > button, button.hraness-design-theme-toggle__trigger")) problems.push("Appearance is missing its trigger.");
+    }
+
+    if (options.measure !== false) {
+      const view = document.defaultView;
+      if (view === null) problems.push("Rendered header inspection requires a browser window.");
+      else {
+        const trigger = appearance?.querySelector(":scope > summary, :scope > button, button.hraness-design-theme-toggle__trigger");
+        for (const [name, element] of [["header", header], ["brand", brand], ["mark", mark], ["navigation", nav], ["appearance", appearanceCount === 1 ? appearance : null], ["appearance trigger", appearanceCount === 1 ? trigger : null]] as const) {
+          if (!element) continue;
+          const box = element.getBoundingClientRect();
+          let hidden = false;
+          for (let ancestor: Element | null = element; ancestor !== null; ancestor = ancestor.parentElement) {
+            const style = view.getComputedStyle(ancestor);
+            if (style.display === "none" || style.visibility === "hidden" || style.visibility === "collapse" || Number(style.opacity) === 0) hidden = true;
+          }
+          if (box.width <= 0 || box.height <= 0 || hidden) problems.push(`The product ${name} is not visible.`);
+        }
+        const box = header.getBoundingClientRect();
+        if (box.left < -1 || box.right > view.innerWidth + 1) problems.push("The product header extends outside the viewport.");
+        const inner = header.querySelector(".hraness-marketing-header__inner");
+        if (!inner || !["grid", "flex"].includes(view.getComputedStyle(inner).display)) problems.push("The shared product-header layout styles are missing.");
+        if (options.stickyOffset === true && view.getComputedStyle(header).position === "sticky") {
+          for (const target of [document.documentElement, mains[0]]) {
+            if (!target) continue;
+            const offset = Number.parseFloat(view.getComputedStyle(target).getPropertyValue("--hraness-sticky-offset"));
+            if (!Number.isFinite(offset) || Math.abs(offset - box.height) > 1) problems.push("Sticky clearance does not match the measured product header.");
+          }
+        }
+        if (appearanceCount === 1 && trigger) {
+          const triggerBox = trigger.getBoundingClientRect();
+          if (triggerBox.width < 43.5 || triggerBox.height < 43.5) problems.push("The appearance trigger is smaller than 44px.");
+          const actionLinks = actions?.querySelectorAll("a[href]") ?? [];
+          if ([...actionLinks].some(link => link.getBoundingClientRect().right > triggerBox.right + 1)) problems.push("Appearance is not the rightmost header action.");
+        }
+      }
+    }
+  }
+  return { headerCount: headers.length, appearanceCount: appearances.length, brandHref, brandLabel, brandMark, links, problems };
+}

package/src/browser/sticky-offset.ts

@@ -32,10 +32,13 @@ function resolveHeader(
   return root.querySelector(stickyOffsetHeaderSelector);
 }
 
-function resolveTarget(header: Element, target: HTMLElement | undefined): HTMLElement {
-  if (target !== undefined) return target;
-  const page = header.closest<HTMLElement>(".hraness-marketing-page");
-  return page ?? header.ownerDocument.documentElement;
+function resolveTargets(header: Element, target: HTMLElement | undefined): readonly HTMLElement[] {
+  if (target !== undefined) return [target];
+  const targets = new Set<HTMLElement>([header.ownerDocument.documentElement]);
+  for (let ancestor: Element | null = header; ancestor !== null; ancestor = ancestor.parentElement) {
+    if (ancestor.matches(".hraness-marketing-page, [data-hraness-marketing-preset]")) targets.add(ancestor as HTMLElement);
+  }
+  return [...targets];
 }
 
 /** Border-box height of sticky marketing chrome, as a CSS length. */
@@ -43,10 +46,10 @@ export function measureStickyOffset(header: Element): string {
   return `${header.getBoundingClientRect().height}px`;
 }
 
-/** Write --hraness-sticky-offset onto the page or document so siblings inherit it. */
+/** Publish on the document and enclosing page/preset scopes so local defaults cannot mask the measurement. */
 export function publishStickyOffset(header: Element, target?: HTMLElement): string {
   const value = measureStickyOffset(header);
-  resolveTarget(header, target).style.setProperty(stickyOffsetCustomProperty, value);
+  for (const destination of resolveTargets(header, target)) destination.style.setProperty(stickyOffsetCustomProperty, value);
   return value;
 }
 
@@ -62,21 +65,30 @@ export function syncStickyOffset(options: StickyOffsetSyncOptions = {}): () => v
   const root = options.root ?? document;
   const header = resolveHeader(root, options.header);
   if (header === null) return () => {};
-  const target = resolveTarget(header, options.target);
+  const targets = resolveTargets(header, options.target);
+  const prior = targets.map(target => ({ target, value: target.style.getPropertyValue(stickyOffsetCustomProperty), priority: typeof target.style.getPropertyPriority === "function" ? target.style.getPropertyPriority(stickyOffsetCustomProperty) : "" }));
+  let published: string;
   const publish = () => {
-    publishStickyOffset(header, target);
+    published = measureStickyOffset(header);
+    for (const target of targets) target.style.setProperty(stickyOffsetCustomProperty, published);
+  };
+  const restore = () => {
+    for (const { target, value, priority } of prior) {
+      if (target.style.getPropertyValue(stickyOffsetCustomProperty) !== published
+        || (typeof target.style.getPropertyPriority === "function" && target.style.getPropertyPriority(stickyOffsetCustomProperty) !== "")) continue;
+      if (value) target.style.setProperty(stickyOffsetCustomProperty, value, priority);
+      else target.style.removeProperty(stickyOffsetCustomProperty);
+    }
   };
   publish();
   const view = document.defaultView;
   if (view === null || typeof view.ResizeObserver !== "function") {
-    return () => {
-      target.style.removeProperty(stickyOffsetCustomProperty);
-    };
+    return restore;
   }
   const observer = new view.ResizeObserver(publish);
   observer.observe(header);
   return () => {
     observer.disconnect();
-    target.style.removeProperty(stickyOffsetCustomProperty);
+    restore();
   };
 }

package/src/palette-bridge.css

@@ -101,7 +101,7 @@
   .hraness-palette.hraness-palette[data-palette],
   :root[data-palette][data-theme],
   [data-palette][data-theme],
-  :root[data-palette]:not([data-theme]),
+  :root[data-palette][data-palette]:not([data-theme]),
   [data-palette]:not([data-theme]),
   :root.hraness-palette.hraness-palette[data-theme],
   .hraness-palette.hraness-palette[data-theme] {

package/src/palette-system.css

@@ -1,5 +1,5 @@
 /* Generated by scripts/generate-palettes.ts. System-first palette paint without JavaScript. */
-:root[data-palette="catppuccin"]:not([data-theme]),
+:root[data-palette][data-palette="catppuccin"]:not([data-theme]),
 [data-palette="catppuccin"]:not([data-theme]) {
   color-scheme: light dark;
   --hraness-palette-background: light-dark(#eff1f5, #1e1e2e);
@@ -143,7 +143,7 @@
   --hraness-palette-chart4: #f9e2af;
   --hraness-palette-chart5: #cda9f7;
 }
-:root[data-palette="gruvbox"]:not([data-theme]),
+:root[data-palette][data-palette="gruvbox"]:not([data-theme]),
 [data-palette="gruvbox"]:not([data-theme]) {
   color-scheme: light dark;
   --hraness-palette-background: light-dark(#fbf1c7, #282828);
@@ -287,7 +287,7 @@
   --hraness-palette-chart4: #fabd2f;
   --hraness-palette-chart5: #e2aebc;
 }
-:root[data-palette="rose-pine"]:not([data-theme]),
+:root[data-palette][data-palette="rose-pine"]:not([data-theme]),
 [data-palette="rose-pine"]:not([data-theme]) {
   color-scheme: light dark;
   --hraness-palette-background: light-dark(#faf4ed, #191724);
@@ -431,7 +431,7 @@
   --hraness-palette-chart4: #f6c177;
   --hraness-palette-chart5: #c4a7e7;
 }
-:root[data-palette="tokyo-night"]:not([data-theme]),
+:root[data-palette][data-palette="tokyo-night"]:not([data-theme]),
 [data-palette="tokyo-night"]:not([data-theme]) {
   color-scheme: light dark;
   --hraness-palette-background: light-dark(#e1e2e7, #1a1b26);
@@ -575,7 +575,7 @@
   --hraness-palette-chart4: #e0af68;
   --hraness-palette-chart5: #bb9af7;
 }
-:root[data-palette="paper"]:not([data-theme]),
+:root[data-palette][data-palette="paper"]:not([data-theme]),
 [data-palette="paper"]:not([data-theme]) {
   color-scheme: light dark;
   --hraness-palette-background: light-dark(#f8f7f4, #12100f);

package/src/react/design-gallery.tsx

@@ -286,14 +286,14 @@ export function DesignSystemGallery({
       <section className="design-gallery__section" id="paper-theme">
         <h2>Paper theme</h2>
         <p>Import paper-theme.css to share warm neutral colors and compact typography without replacing layouts or saved appearance choices.</p>
-        <div className="design-gallery__paper" data-hraness-theme="paper" data-theme="light">
+        <div className="design-gallery__paper" data-hraness-theme="paper" data-palette="paper" data-theme="light">
           <MarketingSiteHeader brand="Light paper" brandHref="#paper-theme" links={[{ href: "#foundation", label: "Foundation" }]} sticky={false} />
           <TopBar surface="glass" title="Glass application header" data-gallery-glass-top-bar="" />
           <h3>Light paper</h3><p>Headers blur scrolling content and become opaque when reduced transparency is preferred.</p>
           <p><a className="design-gallery__paper-link" href="#foundation">Read about the foundation</a></p>
           <Button variant="primary">Create note</Button>
         </div>
-        <div className="design-gallery__paper" data-hraness-theme="paper" data-theme="dark">
+        <div className="design-gallery__paper" data-hraness-theme="paper" data-palette="paper" data-theme="dark">
           <MarketingSiteHeader brand="Dark paper" brandHref="#paper-theme" links={[{ href: "#foundation", label: "Foundation" }]} sticky={false} />
           <TopBar surface="glass" title="Glass application header" data-gallery-glass-top-bar="" />
           <h3>Dark paper</h3><p>The same header treatment follows an explicit dark preference.</p>

package/src/react/design-palette.stylex.ts

@@ -38,8 +38,8 @@ export const paletteMenuStyles = stylex.create({
     display: "inline-flex",
     justifyContent: "center",
     listStyleType: "none",
-    "min-block-size": "var(--interactive-target-compact, 2.75rem)",
-    "min-inline-size": "var(--interactive-target-compact, 2.75rem)",
+    "min-block-size": "var(--hraness-marketing-header-control-target, var(--interactive-target-compact, 2.75rem))",
+    "min-inline-size": "var(--hraness-marketing-header-control-target, var(--interactive-target-compact, 2.75rem))",
     outlineColor: "var(--hraness-material-focus, var(--focus, Highlight))",
     outlineOffset: 3,
     paddingBlock: "0.5rem",

package/src/react/product-marketing.stylex.ts

@@ -88,6 +88,7 @@ export const marketingStyles = stylex.create({
     "-webkit-font-smoothing": "antialiased"
   },
   "header": {
+    "--hraness-marketing-header-control-target": "2.75rem",
     "--hraness-sticky-offset": "calc(var(--hraness-marketing-header-height, 2.75rem) + 1px)",
     "color": {
       "default": "var(--hraness-marketing-ink)",

package/src/react/theme.stylex.ts

@@ -226,12 +226,12 @@ export const themeStyles = stylex.create({
     },
     lineHeight: "inherit",
     "min-block-size": {
-      default: "2rem",
-      [coarsePointer]: "3rem",
+      default: "var(--hraness-marketing-header-control-target, 2rem)",
+      [coarsePointer]: "max(3rem, var(--hraness-marketing-header-control-target, 3rem))",
     },
     "min-inline-size": {
-      default: "2rem",
-      [coarsePointer]: "3rem",
+      default: "var(--hraness-marketing-header-control-target, 2rem)",
+      [coarsePointer]: "max(3rem, var(--hraness-marketing-header-control-target, 3rem))",
     },
     opacity: {
       default: null,