@stonedogcode/style 0.15.0 → 0.17.0

package/src/components/StyledTooltip.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { log } from "../config/logger";
-import React, { useRef, useState, useLayoutEffect, useEffect } from "react";
+import React, { useRef, useState, useLayoutEffect, useEffect, useCallback } from "react";
 import { createPortal } from "react-dom";
 import { styled } from "styled-system/jsx";
 import StyledText from "./StyledText";
@@ -44,7 +44,6 @@ const HelpTrigger = styled("button", {
     // is hard to hit is a help control that does not get used.
     minWidth: "48px",
     minHeight: "48px",
-    marginLeft: "4px",
     borderRadius: "9999px",
     borderWidth: "1px",
     borderStyle: "solid",
@@ -53,6 +52,17 @@ const HelpTrigger = styled("button", {
     lineHeight: "1",
     verticalAlign: "middle",
   },
+  variants: {
+    // Which side of the children the control sits on — see helpGoesFirst
+    // below for how that is decided. The gap has to follow the side, or the
+    // control touches its subject on one side and floats away from it on the
+    // other, which is exactly the ambiguity this fix is about.
+    side: {
+      before: { marginRight: "4px" },
+      after: { marginLeft: "4px" },
+    },
+  },
+  defaultVariants: { side: "after" },
 });
 
 /**
@@ -111,7 +121,7 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   "aria-label": ariaLabel,
   variant,
   trigger = "hover",
-  helpLabel = "More information",
+  helpLabel,
   ...rest
 }) => {
   // Caller's variant, else the app-wide one, else `solid` — and anything the
@@ -133,6 +143,42 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   const triggerRef = useRef<HTMLDivElement>(null);
   const tooltipRef = useRef<HTMLDivElement>(null);
   const helpRef = useRef<HTMLButtonElement>(null);
+  /**
+   * Schedule the open.
+   *
+   * **Clearing first is the whole of NEH-818.** `show()` runs from four
+   * places — the trigger's mouseenter and focus, and the tooltip's own
+   * mouseenter — and more than one of them fires for a single gesture: a press
+   * both hovers and focuses the trigger, ~0ms apart. Assigning over
+   * `timeoutRef.current` left the earlier timer running with nothing holding
+   * its id, so `hide()` could cancel only the last one scheduled.
+   *
+   * The orphan then fired into a page the reader had already left, opening a
+   * tooltip that no departure event could ever close — measured as a live,
+   * opaque, click-eating overlay sitting over the dialog the press had just
+   * opened, gone only on reload.
+   *
+   * One timer at a time; the id is nulled when it fires so `hide()` never
+   * clears a stale one.
+   *
+   * Hoisted above the effects (and memoised) rather than declared beside the
+   * JSX: the ancestor-focus effect added for NEH-950 has to bind these as
+   * listeners, and a second copy of the timer discipline above is exactly how
+   * NEH-818 would come back.
+   */
+  const show = useCallback(() => {
+    if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    timeoutRef.current = setTimeout(() => {
+      timeoutRef.current = null;
+      setVisible(true);
+    }, delay);
+  }, [delay]);
+  const hide = useCallback(() => {
+    if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    timeoutRef.current = null;
+    setVisible(false);
+  }, []);
+
   /**
    * A hover trigger on a device that cannot hover is not a worse experience —
    * it is an unreachable one. There is no hover event, and tapping the control
@@ -146,6 +192,7 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   const canHover = useCanHover();
   const isClick = trigger === "click" || !canHover;
 
+
   // The child may be any component (StyledIconButton, a link, a bare span), so
   // whether it is focusable can only be known from the rendered DOM — React
   // cannot see inside a child component's output. Starts as "yes" so the common
@@ -154,6 +201,38 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   const [focusableChild, setFocusableChild] = useState<HTMLElement | null>(null);
   const [hasFocusableChild, setHasFocusableChild] = useState(true);
 
+  /**
+   * The focusable element this trigger sits *inside*, if any (NEH-950).
+   *
+   * `hasFocusableChild` looks down and cannot see upwards, so it answers "no
+   * focusable child" for an icon that is decorative content inside a control
+   * that is already focusable and already named — and the trigger then took a
+   * `tabIndex` of its own. The result was the exact failure the conditional
+   * above exists to prevent, one level in: a second tab stop inside a button
+   * the reader has already passed, carrying no role and no name because
+   * `needsFallbackName` correctly declines to name it (the ancestor already
+   * has). Every icon in `stonedog-icons` that carries its own tooltip
+   * reproduced it, in every consumer.
+   *
+   * Deleting the `tabIndex` alone would have been a different WCAG failure
+   * rather than a fix — the tooltip must stay reachable by keyboard (2.1.1).
+   * So the ancestor becomes the trigger instead: it already owns the tab stop,
+   * and the effect below opens the tooltip when it takes focus, exactly as a
+   * focusable *child* already does by bubbling.
+   *
+   * Starts null, and the layout effect below can only ever find an ancestor
+   * when there is no focusable child — the two are mutually exclusive by
+   * construction, so nothing has to decide between them.
+   */
+  const [focusableAncestor, setFocusableAncestor] = useState<HTMLElement | null>(null);
+
+  /**
+   * True when something else — a descendant or an ancestor — already puts this
+   * trigger's content in the tab sequence. When it does, the trigger must add
+   * no stop of its own, and must not invent a role or a name for one.
+   */
+  const insideFocusable = hasFocusableChild || focusableAncestor !== null;
+
   // When the trigger KEEPS its tab stop it must have a role and a name (WCAG
   // 2.2 4.1.2) — but only if nothing else already provides one. Borrowing the
   // tooltip text unconditionally is what broke SharedWithIndicator, which names
@@ -165,14 +244,65 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   // a duplicated one is a new bug.
   const [needsFallbackName, setNeedsFallbackName] = useState(false);
 
+  /**
+   * The child's own visible text, used to name the help control after the
+   * thing it explains (NEH-769).
+   *
+   * A screen carrying twenty tooltips carried twenty buttons all called "More
+   * information", which names nothing: a reader tabbing through hears the same
+   * four words twenty times and cannot tell which one answers their question.
+   * "Help: Require PIN" is the same control with a name that distinguishes it.
+   *
+   * Measured from the DOM rather than read from `children` because the child
+   * may be any component — React cannot see the text inside a child component's
+   * output, only the element it was handed.
+   */
+  const [subjectLabel, setSubjectLabel] = useState("");
+
   useLayoutEffect(() => {
     const node = triggerRef.current;
-    const found = node?.querySelector<HTMLElement>(FOCUSABLE_SELECTOR) ?? null;
+    const help = helpRef.current;
+
+    // The help control is itself a `button`, so it matches FOCUSABLE_SELECTOR
+    // and must be excluded from every question asked about the CHILD. This was
+    // already wrong before the control could be rendered first — with a
+    // non-focusable child the query returned the help button, so
+    // aria-describedby landed on the button that already names itself instead
+    // of on the thing being described. Once the control renders first it would
+    // have matched every time (NEH-769).
+    const found =
+      Array.from(node?.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR) ?? []).find(
+        (candidate) => candidate !== help,
+      ) ?? null;
     // Same-value setState is a no-op in React, so this cannot loop.
     setFocusableChild((prev) => (prev === found ? prev : found));
     setHasFocusableChild(found !== null);
 
+    // `parentElement.closest`, not `node.closest`: the trigger itself may be
+    // carrying the very `tabindex` this is deciding whether to keep, and
+    // matching ourselves would make the answer depend on the previous render.
+    // Only asked when there is no focusable child, because a child already
+    // settles the question and is the nearer trigger of the two.
+    const ancestor = found
+      ? null
+      : node?.parentElement?.closest<HTMLElement>(FOCUSABLE_SELECTOR) ?? null;
+    setFocusableAncestor((prev) => (prev === ancestor ? prev : ancestor));
+
     if (!node) return;
+
+    // The child's own text — the help control's "?" deliberately excluded, or
+    // every subject would be named "… ?" and a text-free child would look as
+    // though it had text.
+    const ownText = Array.from(node.childNodes)
+      .filter((child) => child !== help)
+      .map((child) => child.textContent ?? "")
+      .join(" ")
+      .replace(/\s+/g, " ")
+      .trim();
+    // Long enough to distinguish twenty controls, short enough that a screen
+    // reader does not read a paragraph before the reader can act on it.
+    setSubjectLabel(ownText.length > 80 ? `${ownText.slice(0, 80).trimEnd()}…` : ownText);
+
     // parentElement, not the node itself: closest() would match our own
     // aria-label once we set one, and the answer would flip every render.
     const namedByAncestor = Boolean(
@@ -181,12 +311,12 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
     // Text content names an element for free; so does a labelled descendant
     // (an icon carrying its own aria-label, an <img alt>).
     const namedByContent =
-      (node.textContent ?? "").trim().length > 0 ||
-      Boolean(
-        node.querySelector('[aria-label], [aria-labelledby], img[alt]:not([alt=""])'),
-      );
+      ownText.length > 0 ||
+      Array.from(
+        node.querySelectorAll('[aria-label], [aria-labelledby], img[alt]:not([alt=""])'),
+      ).some((el) => el !== help);
     setNeedsFallbackName(!namedByAncestor && !namedByContent);
-  }, [children]);
+  }, [children, isClick]);
 
   // aria-describedby has to sit on whatever actually receives focus, or a screen
   // reader announces the control with no description. Set imperatively rather
@@ -194,7 +324,7 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   // component forwarding the prop, and a child that quietly drops it would fail
   // invisibly.
   useLayoutEffect(() => {
-    const node = focusableChild;
+    const node = focusableChild ?? focusableAncestor;
     if (!node || !visible) return;
     const previous = node.getAttribute("aria-describedby");
     node.setAttribute(
@@ -205,7 +335,31 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
       if (previous === null) node.removeAttribute("aria-describedby");
       else node.setAttribute("aria-describedby", previous);
     };
-  }, [focusableChild, visible, tooltipId]);
+  }, [focusableChild, focusableAncestor, visible, tooltipId]);
+
+  /**
+   * Open on the ANCESTOR's focus, when the trigger is inside one (NEH-950).
+   *
+   * A focusable *child* needs nothing here: `focusin`/`focusout` bubble, so the
+   * wrapper's own `onFocus`/`onBlur` already fire for it. An ancestor is the
+   * other direction, where nothing bubbles, so the listeners go on the ancestor
+   * itself.
+   *
+   * Without this the fix would trade WCAG 2.2 4.1.2 (a focusable element with
+   * no role and no name) for 2.1.1 — the explanation would be rendered and
+   * reachable by pointer only. Hover mode only: click mode never took a tab
+   * stop, so it has nothing to give back.
+   */
+  useEffect(() => {
+    const node = focusableAncestor;
+    if (isClick || !node) return;
+    node.addEventListener("focusin", show);
+    node.addEventListener("focusout", hide);
+    return () => {
+      node.removeEventListener("focusin", show);
+      node.removeEventListener("focusout", hide);
+    };
+  }, [focusableAncestor, isClick, show, hide]);
 
   useLayoutEffect(() => {
     if (visible && triggerRef.current && tooltipRef.current) {
@@ -269,9 +423,19 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
     }
   }, [visible, placement]);
 
-  // Click mode owns its own dismissal. Hover mode needs none of this: it
-  // closes when the pointer leaves. A panel opened by a deliberate press has
-  // to be closable by a deliberate action, and Escape has to work, or a
+  // A pending open timer must not outlive the component. Nothing else clears
+  // it on unmount, so a trigger removed inside the delay window fired
+  // setVisible on a component React had already torn down.
+  useEffect(
+    () => () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    },
+    [],
+  );
+
+  // Click mode's dismissal. A panel opened by a deliberate press has to be
+  // closable by a deliberate action — a press outside it, or Escape — or a
   // keyboard user is stuck with it open.
   useEffect(() => {
     if (!isClick || !visible || typeof document === "undefined") return;
@@ -280,6 +444,7 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
       if (event.key !== "Escape") return;
       setVisible(false);
       // Focus goes back to what opened it — never to the top of the document.
+      // Hover mode has no equivalent, because nothing was focused to open it.
       helpRef.current?.focus();
     };
     const onPointerDown = (event: MouseEvent) => {
@@ -298,6 +463,69 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
     };
   }, [isClick, visible]);
 
+  /**
+   * Hover mode's dismissal, which used to be nothing at all (NEH-818).
+   *
+   * `hide()` is reachable only from the trigger's own `onMouseLeave` /
+   * `onBlur`, so an open tooltip whose trigger never receives another
+   * departure event stays on the page for the life of the document — opaque,
+   * taking pointer events, over whatever opened on top of it. That is not a
+   * hypothetical ordering: a press both focuses the trigger and covers it, so
+   * blur cannot fire (focus stays put) and mouseleave has already been and
+   * gone.
+   *
+   * These two listeners are on `document`, so neither depends on the trigger
+   * being reachable — which is the property the trigger's own handlers lack.
+   *
+   * - **`pointermove`** closes it once the pointer is over neither the trigger
+   *   nor the tooltip. It deliberately does not fire on the tooltip itself:
+   *   WCAG 2.2 1.4.13 *Hoverable* requires the reader be able to move onto the
+   *   revealed text without it vanishing, which is also why the portal keeps
+   *   `pointer-events: auto`.
+   * - **Escape** satisfies 1.4.13 *Dismissible*, which hover mode did not meet
+   *   before: content revealed on hover or focus must be dismissable without
+   *   moving the pointer or focus, and a reader whose pointer is parked had no
+   *   way to clear it.
+   *
+   * Bound only while a hover tooltip is actually open, so the common case
+   * costs nothing.
+   */
+  useEffect(() => {
+    if (isClick || !visible || typeof document === "undefined") return;
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") return;
+      // No focus move: in hover mode nothing was focused to open this, and
+      // stealing focus on Escape would be its own bug.
+      setVisible(false);
+    };
+    const onPointerMove = (event: PointerEvent) => {
+      const target = event.target as Node | null;
+      if (!target) return;
+      if (triggerRef.current?.contains(target) || tooltipRef.current?.contains(target)) return;
+      // A tooltip revealed by FOCUS belongs to the focus, not to the pointer.
+      // WCAG 2.2 1.4.13 Persistent requires it to stay until its trigger is
+      // released, so taking it away because an unrelated mouse moved would
+      // trade one conformance failure for another — and would do it to a
+      // keyboard reader who never touched the mouse. Escape above is their
+      // dismissal.
+      if (
+        document.activeElement &&
+        triggerRef.current?.contains(document.activeElement)
+      ) {
+        return;
+      }
+      setVisible(false);
+    };
+
+    document.addEventListener("keydown", onKeyDown);
+    document.addEventListener("pointermove", onPointerMove);
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("pointermove", onPointerMove);
+    };
+  }, [isClick, visible]);
+
   if (!tooltip) {
     return <>{children}</>;
   }
@@ -306,13 +534,51 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   // would produce "[object Object]" in the accessibility tree.
   const tooltipLabel = typeof tooltip === "string" ? tooltip : undefined;
 
-  const show = () => {
-    timeoutRef.current = setTimeout(() => setVisible(true), delay);
-  };
-  const hide = () => {
-    if (timeoutRef.current) clearTimeout(timeoutRef.current);
-    setVisible(false);
-  };
+  /**
+   * `Label → ? → Input` — the help control goes after the label and before the
+   * control it explains, never after it (NEH-769).
+   *
+   * Not aesthetic. A screen-magnifier user reads linearly at high zoom, so a
+   * `?` placed after a long input is pushed off the visible viewport entirely;
+   * before the control, the reader meets the concept, can ask what it means,
+   * and only then enters data.
+   *
+   * Consumers wrap two shapes and both have to obey that rule, which is why
+   * neither a fixed "always before" nor a fixed "always after" is right:
+   *
+   *   `<Tooltip><Label/></Tooltip> <Input/>`      the input is OUTSIDE us, so
+   *                                               the control goes AFTER  →  Label ? | Input
+   *   `<Tooltip><Row><Label/><Toggle/></Row></Tooltip>`
+   *                                               the control is INSIDE us, so
+   *                                               it goes BEFORE          →  ? Label Toggle
+   *
+   * So the side keys on whether the children contain something focusable —
+   * which the component already measures for its own tab-stop logic. It is
+   * measured in a layout effect, so it settles before paint rather than
+   * flickering into place.
+   */
+  const helpGoesFirst = hasFocusableChild;
+
+  /**
+   * Explicit label wins; otherwise name the control after its subject. Only
+   * when there is no text at all does it fall back to the old generic name.
+   */
+  const resolvedHelpLabel =
+    helpLabel ?? (subjectLabel ? `Help: ${subjectLabel}` : "More information");
+
+  const helpControl = isClick ? (
+    <HelpTrigger
+      ref={helpRef}
+      type="button"
+      side={helpGoesFirst ? "before" : "after"}
+      aria-label={resolvedHelpLabel}
+      aria-expanded={visible}
+      aria-controls={visible ? tooltipId : undefined}
+      onClick={() => setVisible((open) => !open)}
+    >
+      ?
+    </HelpTrigger>
+  ) : null;
 
   return (
     <>
@@ -323,7 +589,13 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
         // tooltip still fires without the wrapper taking focus itself. Adding
         // tabIndex here regardless is what gave every tooltipped control two
         // tab stops, the second of them silent (NEH-127).
-        tabIndex={isClick || hasFocusableChild ? undefined : 0}
+        //
+        // `insideFocusable`, not `hasFocusableChild`: an ANCESTOR owns the tab
+        // stop just as effectively as a descendant, and looking only downwards
+        // put the same silent second stop inside every icon button in the
+        // fleet (NEH-950). The ancestor-focus effect above is what keeps the
+        // tooltip reachable once the trigger stops taking focus itself.
+        tabIndex={isClick || insideFocusable ? undefined : 0}
         // A focusable element needs a role and a name (WCAG 2.2 4.1.2). Applied
         // only when the trigger keeps the tab stop AND nothing else names it —
         // see needsFallbackName above for why the condition matters (NEH-151).
@@ -332,9 +604,9 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
         // reveals content on focus, which is the closest standard role and what
         // the ARIA tooltip pattern assumes of a trigger. A focusable generic
         // with only a name still fails 4.1.2, which asks for both.
-        role={!isClick && !hasFocusableChild && needsFallbackName ? "button" : undefined}
+        role={!isClick && !insideFocusable && needsFallbackName ? "button" : undefined}
         aria-label={
-          isClick || hasFocusableChild
+          isClick || insideFocusable
             ? undefined
             : ariaLabel ?? (needsFallbackName ? tooltipLabel : undefined)
         }
@@ -344,24 +616,21 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
         onMouseLeave={isClick ? undefined : hide}
         onFocus={isClick ? undefined : show}
         onBlur={isClick ? undefined : hide}
-        aria-describedby={
-          !isClick && !hasFocusableChild && visible ? tooltipId : undefined
-        }
+        // When something focusable is in play the description is set
+        // imperatively on THAT element instead (see the layout effect above) —
+        // it has to sit on whatever actually receives focus. This wrapper is
+        // the fallback for label-only children, and it applies in click mode
+        // too: help that is reachable but never announced is help a screen
+        // reader user does not know exists (NEH-769).
+        //
+        // `insideFocusable`, not `hasFocusableChild`, so a focusable ANCESTOR
+        // still owns the description rather than this wrapper (NEH-950).
+        aria-describedby={!insideFocusable && visible ? tooltipId : undefined}
         {...rest}
       >
+        {helpGoesFirst && helpControl}
         {children}
-        {isClick && (
-          <HelpTrigger
-            ref={helpRef}
-            type="button"
-            aria-label={helpLabel}
-            aria-expanded={visible}
-            aria-controls={visible ? tooltipId : undefined}
-            onClick={() => setVisible((open) => !open)}
-          >
-            ?
-          </HelpTrigger>
-        )}
+        {!helpGoesFirst && helpControl}
       </TooltipTrigger>
       {visible && typeof document !== "undefined" &&
         createPortal(

package/src/config/font-size.ts

@@ -147,3 +147,28 @@ export function stepUpFontSize(size: FontSizeKey, steps = 1): FontSizeKey {
   // clamp fails safe instead of returning undefined to a caller typed otherwise.
   return next ?? size;
 }
+
+/**
+ * The next size DOWN, clamped at the bottom of the scale.
+ *
+ * The counterpart to `stepUpFontSize`, added for `StyledFieldHelp` (NEH-972),
+ * and the clamp is the load-bearing half. Inline help is deliberately one tier
+ * below the text it accompanies — but "one tier below" must never mean "below
+ * the smallest tier the host offers", because the reader who has turned their
+ * text size all the way down is the reader with the least room to spare. At
+ * `xs` this returns `xs`, so help matches the body text rather than shrinking
+ * past it.
+ *
+ * Steps through `FONT_SIZE_ORDER`, so it moves through whatever scale the host
+ * has pinned its `--font-sizes-*` properties to rather than through a fixed set
+ * of pixel values.
+ */
+export function stepDownFontSize(size: FontSizeKey, steps = 1): FontSizeKey {
+  const index = FONT_SIZE_ORDER.indexOf(size);
+  if (index === -1) return size;
+  const next = FONT_SIZE_ORDER[Math.max(index - steps, 0)];
+  // Clamped into range above, so this cannot miss — but staying total means a
+  // future change to the clamp fails safe rather than handing a caller
+  // `undefined` from a function typed otherwise. Same shape as stepUpFontSize.
+  return next ?? size;
+}

package/src/index.ts

@@ -48,6 +48,7 @@ export {
   getFontSizeLabel,
   getFontSizeValue,
   stepUpFontSize,
+  stepDownFontSize,
   FONT_SIZE_ORDER,
 } from "./config/font-size";
 
@@ -197,6 +198,18 @@ export type { StyledTooltipProps } from "./components/StyledTooltip";
 export { default as StyledFormLabel } from "./components/StyledFormLabel";
 export type { StyledFormLabelProps } from "./components/StyledFormLabel";
 
+/**
+ * Permanent inline help for a field — PRD-0037's replacement for the hover
+ * tooltip and its `?` button. `fieldHelpId` is exported so a host can put the
+ * `aria-describedby` association in server-rendered HTML.
+ */
+export {
+  default as StyledFieldHelp,
+  StyledFieldHelp as FieldHelp,
+  fieldHelpId,
+} from "./components/StyledFieldHelp";
+export type { StyledFieldHelpProps } from "./components/StyledFieldHelp";
+
 // ---------------------------------------------------------------------------
 // Components that were blocked on a runtime dependency until NEH-430 gave each
 // a seam with a working default. None of them adds a dependency; the host

package/src/preset/index.ts

@@ -36,6 +36,7 @@ import {
   createSemanticFonts,
   createSemanticSizes,
 } from "./semantic-variables";
+import { createZIndexTokens } from "./z-layers";
 
 export interface StonedogStylePresetOptions {
   /**
@@ -184,6 +185,19 @@ export function stonedogStylePreset(options: StonedogStylePresetOptions = {}) {
            */
           fonts: createSemanticFonts(cssVarPrefix),
           fontWeights: createSemanticFontWeights(cssVarPrefix),
+          /**
+           * Named stacking layers (NEH-830). Neither this preset nor either
+           * base Panda preset defined any, so `drawerRecipe`'s `zIndex:
+           * "modal"` resolved to nothing and was emitted as the literal
+           * `z-index: modal` — invalid CSS the browser discards, leaving that
+           * panel with no z-index at all.
+           *
+           * Unlike the colour tokens these carry no custom property: a layer
+           * is not a brand decision and there is nothing for a theme to
+           * restyle. A HOST overrides the numbers in its own config; see
+           * z-layers.ts for why the names live here and the values do not.
+           */
+          zIndex: createZIndexTokens(),
         },
         keyframes: {
           spin: {
@@ -250,6 +264,13 @@ export {
   requiredCssCustomProperties,
 } from "./semantic-variables";
 
+export {
+  Z_LAYERS,
+  createZIndexTokens,
+  zIndexTokenNames,
+  type ZLayerName,
+} from "./z-layers";
+
 export { recipes as stonedogStyleRecipes };
 
 /* ------------------------------------------------------------------------- *

package/src/preset/recipes/button.ts

@@ -37,10 +37,20 @@ export const buttonRecipe = defineRecipe({
     variant: {
       solid: {
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        // The same pairing `outline` states below, and for the same reason
+        // (NEH-441, NEH-796). `textPrimary` is the colour that goes on
+        // `boxBgPrimary`, not on an accent surface: against optima's light
+        // theme that pairing measures 2.43:1, below WCAG AA, while
+        // `buttonTextAccent` measures 7.34:1. The dark theme happens to
+        // survive it, which is what let a default variant ship unreadable.
+        //
+        // `TEXT_BACKGROUND_PAIRS` in `semantic-variables.ts` is the contract
+        // being obeyed: `buttonTextAccent` sits on `buttonBgAccent`, and
+        // `buttonTextSecondary` on the `buttonBgSecondary` the hover repaints.
+        color: "buttonTextAccent",
         _hover: {
           bg: "buttonBgSecondary",
-          color: "textPrimary",
+          color: "buttonTextSecondary",
         },
       },
       outline: {
@@ -77,7 +87,15 @@ export const buttonRecipe = defineRecipe({
         border: "2px solid",
         borderRadius: "xl",
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        // The same correction `solid` took in NEH-796, which this variant was
+        // missed by twice over (NEH-877): the pairing sweep that landed with it
+        // was scoped to this recipe, but it also skipped every variant named
+        // `glass` — on the reasoning that a translucent surface should inherit.
+        // This one is not translucent. It paints an opaque `buttonBgAccent` and
+        // blurs what is BEHIND it, so it owes a paired foreground like any
+        // other accent surface: 2.43:1 with `textPrimary` against optima's
+        // light theme, 7.34:1 with this.
+        color: "buttonTextAccent",
         boxShadow: "0 8px 32px rgba(0,0,0,0.2)",
         backdropFilter: "blur(12px)",
         WebkitBackdropFilter: "blur(12px)",
@@ -86,6 +104,13 @@ export const buttonRecipe = defineRecipe({
         transition: "all 0.3s ease",
         _hover: {
           bg: "buttonBgSecondary",
+          // Stated, because the hover repaints a DIFFERENT surface (NEH-877).
+          // Without it the label rides its base `buttonTextAccent` onto a
+          // secondary background — 1.06:1 in optima's light theme, white on
+          // near-white, i.e. the label vanishing on hover. This is the same
+          // move `solid` made in NEH-796 and the reason a base-colour fix has
+          // to look at every pseudo-state that repaints beneath it.
+          color: "buttonTextSecondary",
           borderColor: "rgba(255,255,255,0.4)",
           boxShadow: "0 8px 32px rgba(0,0,0,0.3), inset 0 0 20px rgba(255,255,255,0.1)",
           transform: "translateY(-1px)",
@@ -126,7 +151,12 @@ export const buttonRecipe = defineRecipe({
         },
       },
       selected: {
-        color: "textPrimary",
+        // `textAccent`, not `textPrimary` — the same mispairing `solid` had
+        // (NEH-796). `boxBgAccent` is an accent surface and the contract's
+        // partner for it is `textAccent`; `textPrimary` is the colour for
+        // `boxBgPrimary`, a different surface. Adjacent instance of the defect
+        // the issue names, in the same recipe, so it is fixed here.
+        color: "textAccent",
         border: "3px dashed black",
         borderRadius: "xl",
         bg: "boxBgAccent",

package/src/preset/recipes/form.ts

@@ -15,7 +15,12 @@ export const formRecipe = defineRecipe({
     variant: {
       solid: {
         bg: "boxBgAccent",
-        color: "textPrimary",
+        // `textAccent`, not `textPrimary` (NEH-877). `textPrimary` is the
+        // contract's partner for `boxBgPrimary`, a different surface: against
+        // optima's light theme, whose accent surface is a near-black graphite,
+        // that pairing measures 1.17:1 — a form whose every label is the exact
+        // colour of the panel behind it. `textAccent` measures 15.27:1.
+        color: "textAccent",
         borderColor: "borderBgPrimary",
         "& > li:not(:last-child)": {
           borderBottom: "1px solid",