@stonedogcode/style 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "A Panda CSS design system: a themeable Panda preset plus the React components built on it.",
   "license": "Apache-2.0",
   "author": "StoneDogCode L.L.C.",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/stonedog-code/stonedog-style.git"
   },
-  "//publishConfig": "A SCOPED package defaults to access: restricted. Publishing one without this succeeds, prints nothing unusual, and then 404s for every consumer — which reads as a missing package rather than as a private one. It was not needed while the name was unscoped (those default to public), so it is new as of the scope migration and it is the single thing most likely to be forgotten in one.",
+  "//publishConfig": "A SCOPED package defaults to access: restricted. Publishing one without this succeeds, prints nothing unusual, and then 404s for every consumer \u2014 which reads as a missing package rather than as a private one. It was not needed while the name was unscoped (those default to public), so it is new as of the scope migration and it is the single thing most likely to be forgotten in one.",
   "publishConfig": {
     "access": "public"
   },
@@ -20,7 +20,7 @@
     "./preset": "./src/preset/index.ts",
     "./package.json": "./package.json"
   },
-  "//files": "The package ships SOURCE, so `src` has to go out whole — but only the part a consumer imports. Tests, Playwright component tests and their harnesses were 57 of 130 entries and never resolvable from any export, so every one of them was a file a consumer's Panda run had to be told to skip. `src/__tests__/published-package.test.ts` asserts this listing rather than this array: npm's own resolution of these negations is the only thing that decides what ships.",
+  "//files": "The package ships SOURCE, so `src` has to go out whole \u2014 but only the part a consumer imports. Tests, Playwright component tests and their harnesses were 57 of 130 entries and never resolvable from any export, so every one of them was a file a consumer's Panda run had to be told to skip. `src/__tests__/published-package.test.ts` asserts this listing rather than this array: npm's own resolution of these negations is the only thing that decides what ships.",
   "files": [
     "src",
     "!src/**/__tests__/**",
@@ -38,7 +38,7 @@
     "pretype-check": "npm run panda:prepare",
     "type-check": "tsc --noEmit",
     "lint": "eslint . --ext ts,tsx",
-    "//pretest": "panda:build, not panda:prepare — the token-contract suite asserts against the generated stylesheet, which cssgen produces and codegen alone does not.",
+    "//pretest": "panda:build, not panda:prepare \u2014 the token-contract suite asserts against the generated stylesheet, which cssgen produces and codegen alone does not.",
     "pretest": "npm run panda:build",
     "test": "jest",
     "pretest:ct": "npm run panda:build",
@@ -46,7 +46,7 @@
     "test:ct:ui": "playwright test --config playwright-ct.config.ts --ui",
     "test:coverage": "jest --coverage",
     "gate": "npm run type-check && npm run lint && npm run test",
-    "//publish:stonedog-style": "Publish to npm, end to end. Run from a terminal, interactively — npm prompts for the 2FA one-time password and the login flow needs a browser. It refuses a checkout that is detached, dirty, or behind origin/main: a submodule sits detached at the consumer's gitlink by default, and publishing from one commit behind ships a tarball missing the very thing you are publishing for while looking like a success (it did, on 2026-08-04, without TitleLogo.tsx). Runs the gate, prints the tarball listing, then proves the result by installing from the registry into a temp directory.",
+    "//publish:stonedog-style": "Publish to npm, end to end. Run from a terminal, interactively \u2014 npm prompts for the 2FA one-time password and the login flow needs a browser. It refuses a checkout that is detached, dirty, or behind origin/main: a submodule sits detached at the consumer's gitlink by default, and publishing from one commit behind ships a tarball missing the very thing you are publishing for while looking like a success (it did, on 2026-08-04, without TitleLogo.tsx). Runs the gate, prints the tarball listing, then proves the result by installing from the registry into a temp directory.",
     "publish:stonedog-style": "bash scripts/publish-package.sh",
     "version:bump:patch": "npm version patch --no-git-tag-version",
     "version:bump:minor": "npm version minor --no-git-tag-version",

package/src/components/StyledPage.tsx

@@ -173,6 +173,28 @@ export const StyledPage = React.forwardRef<HTMLDivElement, StyledPageProps>(
             flexDirection: "column",
             flex: "1",
             width: "100%",
+            // BOTH `flex: 1` and `height: 100%`, and the second is not
+            // redundant (NEH-802).
+            //
+            // `flex: 1` covers the common case — the page is a flex item in a
+            // column, and takes the space the column offers. That is what the
+            // app shell does, so it is easy to conclude this is the only case
+            // and drop the height. It was dropped, and it broke a production
+            // dashboard.
+            //
+            // `flex: 1` is INERT inside a block-level parent. HopperGuard's
+            // `/dashboard` nests one page inside another through plain
+            // `display: block` wrappers, and there the page's height came
+            // entirely from `height: 100%`. Without it the inner page fell
+            // back to CONTENT height — 138px, of which a widget header took
+            // ~128, leaving its `1fr` body 10px of padding and the grid zero.
+            // The header rendered; every tile was clipped to nothing.
+            //
+            // The failure is silent in the worst way: nothing errors, nothing
+            // is unstyled, and the page looks deliberately empty. Only a
+            // computed-height walk up the DOM shows it, which is why no unit
+            // test or type-check can stand in for the assertion below.
+            height: "100%",
             // See the contract note above: without this the overflow escapes
             // the row rather than scrolling inside it.
             minHeight: "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";
@@ -133,6 +133,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
@@ -154,6 +190,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
@@ -172,6 +240,16 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
     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;
     // parentElement, not the node itself: closest() would match our own
     // aria-label once we set one, and the answer would flip every render.
@@ -194,7 +272,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 +283,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 +371,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 +392,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 +411,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 +482,6 @@ 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);
-  };
 
   return (
     <>
@@ -323,7 +492,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 +507,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)
         }
@@ -345,7 +520,7 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
         onFocus={isClick ? undefined : show}
         onBlur={isClick ? undefined : hide}
         aria-describedby={
-          !isClick && !hasFocusableChild && visible ? tooltipId : undefined
+          !isClick && !insideFocusable && visible ? tooltipId : undefined
         }
         {...rest}
       >

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",

package/src/preset/recipes/icon-button.ts

@@ -64,23 +64,42 @@ export const buttonIconRecipe = defineRecipe({
       },
     },
     variant: {
+      /**
+       * The NEH-796 pairing, applied to the recipe it was never applied to
+       * (NEH-877).
+       *
+       * `buttonRecipe` and this one are the same control in two shapes, and
+       * `iconButton` carried the identical defect in three variants: an accent
+       * fill labelled with `textPrimary`, the contract's partner for
+       * `boxBgPrimary`. Against optima's light theme that measures 2.43:1,
+       * below WCAG AA; `buttonTextAccent` measures 7.34:1. The dark theme
+       * clears AA either way, which is what let it ship.
+       *
+       * Each `_hover` that repaints a different surface states its own colour
+       * for the same reason — the base colour riding onto a secondary fill is
+       * the failure one state along.
+       */
       solid: {
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        color: "buttonTextAccent",
         _hover: {
           bg: "buttonBgSecondary",
-          color: "textPrimary",
+          color: "buttonTextSecondary",
         },
       },
       outline: {
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        color: "buttonTextAccent",
         border: "1px solid",
         borderColor: "borderBgSecondary",
         borderRadius: 0,
         _hover: {
           border: "2px solid",
           bg: "buttonBgAccentHover",
+          // The hover surface has its own partner in the contract, and it is
+          // not the base one. Both are white in optima's palette today; the
+          // point is that a host is free to make them differ.
+          color: "buttonTextAccentHover",
         },
       },
       aurora: {
@@ -98,7 +117,10 @@ export const buttonIconRecipe = defineRecipe({
         borderColor: "black",
         borderRadius: "xl",
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        // Not translucent, whatever the name suggests: the fill is an opaque
+        // `buttonBgAccent` and the blur applies to what is behind it. So it
+        // takes the accent partner like its neighbours above (NEH-877).
+        color: "buttonTextAccent",
         boxShadow: "0 8px 32px rgba(0,0,0,0.2)",
         backdropFilter: "blur(12px)",
         WebkitBackdropFilter: "blur(12px)",
@@ -107,6 +129,10 @@ export const buttonIconRecipe = defineRecipe({
         transition: "all 0.3s ease",
         _hover: {
           bg: "buttonBgSecondary",
+          // Stated because the hover repaints a different surface — otherwise
+          // the glyph keeps `buttonTextAccent` over a secondary fill, 1.06:1 in
+          // optima's light theme (NEH-877).
+          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)",
@@ -140,11 +166,16 @@ export const buttonIconRecipe = defineRecipe({
         fontWeight: "bold",
       },
       ghost: {
+        // The base stays `textPrimary`: a 50% accent fill is a BLEND with
+        // whatever is behind it, so the contract has no partner for it and
+        // `textPrimary` measures 5.9:1 over the light-theme blend. The hover
+        // takes the fill to full opacity, which IS a contract surface — and
+        // there `textPrimary` is the 2.43:1 pairing again (NEH-877).
         bg: "buttonBgAccent/50",
         color: "textPrimary",
         _hover: {
           bg: "buttonBgAccent",
-          color: "textPrimary",
+          color: "buttonTextAccent",
           border: "1px solid",
           borderColor: "gray.700",
         },

package/src/preset/recipes/input-bool.ts

@@ -103,7 +103,19 @@ export const inputBoolRecipe = defineSlotRecipe({
       solid: {
         control: {
           bg: "buttonBgAccent",
-          color: "textPrimary",
+          /**
+           * The contract's partner for this fill (NEH-877), and INERT today.
+           *
+           * Neither `bg` nor `color` paints on a checkbox at `appearance:
+           * auto` — the note in `base` and NEH-234 are about exactly that — so
+           * this changes nothing anyone can see, and that is the honest reason
+           * to make it: the declarations are left in place per that note, and
+           * a declaration left in place should not be left WRONG. `textPrimary`
+           * is the partner of `boxBgPrimary`; the day option 2 on NEH-310
+           * (`appearance: none` plus a hand-drawn tick) makes these paint, it
+           * would paint at 2.43:1 against optima's light theme.
+           */
+          color: "buttonTextAccent",
           accentColor: "buttonBgPrimary",
           boxShadow: "none",
         },
@@ -111,7 +123,8 @@ export const inputBoolRecipe = defineSlotRecipe({
       outline: {
         control: {
           bg: "buttonBgAccent",
-          color: "textPrimary",
+          // Same fill, same partner, same inertness as `solid` above.
+          color: "buttonTextAccent",
           /**
            * The SAME checked fill as `solid`, deliberately.
            *
@@ -227,7 +240,10 @@ export const inputBoolRecipe = defineSlotRecipe({
       },
       ghost: {
         control: {
-          color: "textSecondary",
+          // `buttonTextSecondary` is the partner of the fill below;
+          // `textSecondary` belongs to `boxBgSecondary` (NEH-877). Inert for
+          // the same reason as `solid`.
+          color: "buttonTextSecondary",
           bg: "buttonBgSecondary",
           accentColor: "buttonBgPrimary",
           // The thinnest ring in the set, in the secondary border colour.

package/src/preset/recipes/input-radio.ts

@@ -82,7 +82,11 @@ export const inputRadioRootRecipe = defineSlotRecipe({
       solid: {
         item: {
           bg: "boxBgAccent",
-          color: "textPrimary",
+          // `textAccent` is the contract's partner for this surface;
+          // `textPrimary` belongs to `boxBgPrimary` and measures 1.17:1 on it
+          // against optima's light theme, whose accent surface is a near-black
+          // graphite (NEH-877). This is the DEFAULT variant of this recipe.
+          color: "textAccent",
           borderColor: "borderBgPrimary",
         },
       },
@@ -116,12 +120,16 @@ export const inputRadioRootRecipe = defineSlotRecipe({
       matte: {
         item: {
           bg: "buttonBgSecondary",
-          color: "textAccent",
+          // Was `textAccent` — the partner of `boxBgAccent`, a surface this
+          // variant does not paint. 1.14:1 in optima's light theme, where the
+          // accent text is white and this fill is near-white (NEH-877).
+          color: "buttonTextSecondary",
         },
       },
       ghost: {
         item: {
-          color: "textSecondary",
+          // `textSecondary` is `boxBgSecondary`'s partner, not this fill's.
+          color: "buttonTextSecondary",
           bg: "buttonBgSecondary",
           border: "none",
         },

package/src/preset/recipes/input-surface.ts

@@ -66,12 +66,31 @@ export const inputSurfaceBase = {
  * The variant map. Every variant states its own `bg`, `color`, and
  * `borderColor` rather than inheriting some and not others — that asymmetry is
  * what let the two recipes disagree without either looking wrong on its own.
+ *
+ * ## The colour has to be the surface's PARTNER, not just a colour (NEH-877)
+ *
+ * Four of these paired a surface with the wrong contract token, and because
+ * `inputTextRecipe` and `inputDropdownRecipe` both spread this map, each one was
+ * eight offending selectors rather than four. `solid` and `glass` paint
+ * `boxBgAccent` and said `textPrimary` — the partner of `boxBgPrimary` — which
+ * measures **1.17:1** against optima's light theme, a control whose typed value
+ * is the exact colour of the field. `matte` and `ghost` paint
+ * `buttonBgSecondary` and said `textSecondary`, the partner of `boxBgSecondary`.
+ *
+ * **The placeholder moves with the text**, which is the part easy to miss here:
+ * `inputSurfaceBase` sets `&::placeholder { color: textPrimary }` for the
+ * base's own `textPrimary`, so a variant that repaints the surface and only
+ * fixes `color` leaves the placeholder on the old pairing — the same defect,
+ * surviving in the one piece of text an empty field actually shows.
  */
 export const inputSurfaceVariants = {
   solid: {
     bg: "boxBgAccent",
-    color: "textPrimary",
+    color: "textAccent",
     borderColor: "borderBgPrimary",
+    "&::placeholder": {
+      color: "textAccent",
+    },
   },
   outline: {
     // Stated, not omitted. An outline control is meant to show whatever is
@@ -97,12 +116,15 @@ export const inputSurfaceVariants = {
     borderStyle: "solid",
     borderRadius: "xl",
     bg: "boxBgAccent",
-    color: "textPrimary",
+    // An opaque accent fill with a blur applied to what is behind it — not a
+    // translucent surface, whatever the name says, so it takes the accent
+    // partner like `solid` (NEH-877).
+    color: "textAccent",
     borderColor: "borderBgSecondary",
     backdropFilter: "blur(12px)",
     fontWeight: "normal",
     _placeholder: {
-      color: "textPrimary",
+      color: "textAccent",
       opacity: 0.8,
     },
     _focusVisible: {
@@ -130,15 +152,20 @@ export const inputSurfaceVariants = {
   },
   matte: {
     bg: "buttonBgSecondary",
-    color: "textSecondary",
+    color: "buttonTextSecondary",
     borderColor: "borderBgPrimary",
+    // Otherwise the placeholder keeps the base's `textPrimary` while the value
+    // above it moves — see the note on this map (NEH-877).
+    "&::placeholder": {
+      color: "buttonTextSecondary",
+    },
   },
   ghost: {
-    color: "textSecondary",
+    color: "buttonTextSecondary",
     bg: "buttonBgSecondary",
     borderColor: "borderBgPrimary",
     "&::placeholder": {
-      color: "textSecondary/60",
+      color: "buttonTextSecondary/60",
     },
   },
   none: {

package/src/preset/recipes/list.ts

@@ -164,12 +164,18 @@ export const listRecipe = defineSlotRecipe({
       },
       ghost: {
         item: {
-          color: "textSecondary",
+          // The partner of `buttonBgSecondary` (NEH-877). `textSecondary`
+          // belongs to `boxBgSecondary`, a surface this variant does not paint.
+          color: "buttonTextSecondary",
           bg: "buttonBgSecondary",
           borderRadius: "md",
           cursor: "pointer",
           _hover: {
             bg: "boxBgAccent",
+            // The hover repaints an accent surface, so the row must take that
+            // surface's partner rather than ride the base colour onto it —
+            // 1.14:1 in optima's light theme if it did.
+            color: "textAccent",
           },
         },
       },

package/src/preset/recipes/tooltip.ts

@@ -1,12 +1,34 @@
 import { defineRecipe } from "@pandacss/dev";
 
+/**
+ * Every variant here paints the SAME surface, so every variant owes the same
+ * text colour (NEH-877).
+ *
+ * `boxBgPrimary` is the background of all nine, base included — the variants
+ * differ by border and nothing else. Yet seven of them named a text token
+ * belonging to some other surface: `buttonTextSecondary`, `textSecondary`,
+ * `textMain`, `buttonTextPrimary`. The contract's partner for `boxBgPrimary` is
+ * `textPrimary`, and there is no reading of these variants under which a
+ * different one is intended — they are copy-paste drift, not design.
+ *
+ * Measured against optima-cloud-saas's light theme, the worst was `glass` at
+ * **1.05:1** — `buttonTextPrimary` is white and `boxBgPrimary` is #f8f9fa, so
+ * that tooltip rendered white text on a near-white panel and said nothing at
+ * all. The dark theme reads it at 17.84:1, which is why nobody saw it.
+ * `textPrimary` measures 16.92:1 light and 15.02:1 dark.
+ *
+ * A tooltip is the one surface where this class of defect is invisible in
+ * review: it appears on hover, over the thing it describes, and an empty-looking
+ * one reads as a tooltip that has not opened yet.
+ */
 export const tooltipRecipe = defineRecipe({
   className: "tooltip",
   base: {
     position: "absolute",
     zIndex: 9999,
     pointerEvents: "none",
-    color: "buttonTextSecondary",
+    // The partner of the `boxBgPrimary` this base paints (NEH-877).
+    color: "textPrimary",
     padding: "2px",
     borderRadius: "md",
     fontSize: "var(--font-sizes-lg, 1rem)",
@@ -25,7 +47,7 @@ export const tooltipRecipe = defineRecipe({
     variant: {
       solid: {
         bg: "boxBgPrimary",
-        color: "buttonTextSecondary",
+        color: "textPrimary",
         borderColor: "borderBgPrimary",
       },
       outline: {
@@ -36,25 +58,25 @@ export const tooltipRecipe = defineRecipe({
       },
       aurora: {
         bg: "boxBgPrimary",
-        color: "textSecondary",
+        color: "textPrimary",
         borderColor: "borderBgSecondary",
         border: "1px solid",
       },
       glass: {
         bg: "boxBgPrimary",
-        color: "buttonTextPrimary",
+        color: "textPrimary",
         border: "1px solid",
         borderColor: "borderBgPrimary",
       },
       matte: {
         bg: "boxBgPrimary",
-        color: "textSecondary",
+        color: "textPrimary",
         borderColor: "borderBgSecondary",
         border: "1px solid",
       },
       ghost: {
         bg: "boxBgPrimary",
-        color: "buttonTextSecondary",
+        color: "textPrimary",
       },
       link: {
         bg: "boxBgPrimary",
@@ -64,13 +86,13 @@ export const tooltipRecipe = defineRecipe({
       },
       none: {
         bg: "boxBgPrimary",
-        color: "textMain",
+        color: "textPrimary",
         border: "1px solid",
         borderColor: "borderBgPrimary",
       },
       unstyled: {
         bg: "boxBgPrimary",
-        color: "textMain",
+        color: "textPrimary",
       },
     },
   },

package/src/preset/z-layers.ts

@@ -0,0 +1,101 @@
+/**
+ * The stacking-order vocabulary: names for the layers a UI actually has.
+ *
+ * ## The bug this exists to fix
+ *
+ * `drawerRecipe` has said `zIndex: "modal"` since it was extracted, and there
+ * has never been a `zIndex` token scale for `"modal"` to resolve against —
+ * neither here nor in either base Panda preset. Panda passes an unknown token
+ * through as a **literal**, so the generated stylesheet said
+ *
+ *     .drawer { position: fixed; z-index: modal; }
+ *
+ * `modal` is not a valid `z-index` value, so the browser discards the whole
+ * declaration. **The drawer panel has never had a z-index at all.** No build
+ * error, no console warning, no type error — the class is in the DOM and the
+ * rule behind it is one line shorter than it looks.
+ *
+ * This is precisely the defect class CLAUDE.md records under "Token
+ * compliance", one property along from `bg: "buttonBgHover"`. The colour half
+ * is guarded by `token-contract.test.ts`; the z-index half is now guarded
+ * beside it.
+ *
+ * ## This package owns the NAMES. The host owns the NUMBERS
+ *
+ * A z-index ladder is an application concern — it encodes which of *that
+ * product's* surfaces may cover which, and no two products agree. So the
+ * values below are conventional defaults chosen to be sane for a fresh
+ * consumer, and a host is expected to override them:
+ *
+ * ```ts
+ * // the host's panda.config.ts
+ * theme: { extend: { tokens: { zIndex: { modal: { value: 99999 } } } } }
+ * ```
+ *
+ * Overriding a value keeps the name, and the name is the part that makes the
+ * order reviewable. A literal at a call site expresses nothing; `zIndex:
+ * "menu"` says what the element *is*, and a reader can check it against this
+ * table without opening a second file.
+ *
+ * ## The ladder
+ *
+ * Ascending, and the ORDER is the contract — not the numbers:
+ *
+ *     hide      behind its own box (decorative pseudo-elements)
+ *     base      the ordinary flow
+ *     raised    lifted within its own stacking context
+ *     docked    a bar or rail pinned inside a region
+ *     sticky    a sticky header inside a scroll region
+ *     banner    page-level chrome above sticky content
+ *     surface   a page surface that fills the viewport
+ *     dialog    a modal dialog and its scrim
+ *     menu      menus, drawer scrims, docked panels — the floating band's floor
+ *     popover   a popover that has to clear an open menu
+ *     overlay   a full-viewport cover: a splash, a loading shade
+ *     toast     toasts, pickers, transient chrome
+ *     modal     a drawer or modal panel that must clear everything but a tip
+ *     tooltip   the top of the application
+ *
+ * **A dialog sits LOW on purpose.** Menus, toasts, tooltips and dropdowns all
+ * have to be able to open *on* a dialog, so every one of them is above it.
+ * Raising the dialog to "win" is the change that looks right and breaks every
+ * control opened inside one.
+ */
+
+/**
+ * The layer names, in ascending order, with this package's default values.
+ *
+ * Exported as plain numbers as well as tokens because a **portalled** element
+ * usually sets its z-index from an inline `style`, and an inline style cannot
+ * name a Panda token. Both readings have to come from one place or they drift.
+ */
+export const Z_LAYERS = {
+  hide: -1,
+  base: 0,
+  raised: 1,
+  docked: 10,
+  sticky: 20,
+  banner: 50,
+  surface: 100,
+  dialog: 200,
+  menu: 300,
+  popover: 400,
+  overlay: 500,
+  toast: 600,
+  modal: 700,
+  tooltip: 800,
+} as const;
+
+export type ZLayerName = keyof typeof Z_LAYERS;
+
+/** Every layer name. Useful to a consumer's guard test. */
+export function zIndexTokenNames(): ZLayerName[] {
+  return Object.keys(Z_LAYERS) as ZLayerName[];
+}
+
+/** The scale in the shape Panda's `theme.extend.tokens.zIndex` wants. */
+export function createZIndexTokens(): Record<string, { value: number }> {
+  return Object.fromEntries(
+    Object.entries(Z_LAYERS).map(([token, value]) => [token, { value }]),
+  );
+}