@stonedogcode/style 0.13.0 → 0.16.0

package/README.md

@@ -12,7 +12,7 @@ the whole component set re-skins at runtime. No component here knows a colour.
 
 ## Status
 
-Early. The preset is complete (22 recipes, 43 colour tokens); the component set
+Early. The preset is complete (23 recipes, 43 colour tokens); the component set
 is being extracted incrementally and currently covers the layout and typography
 primitives. See [CLAUDE.md](./CLAUDE.md) for the architecture and the
 contribution rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.13.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/StyledLink.tsx

@@ -2,7 +2,7 @@
 
 import React from "react";
 import { buttonRecipe } from "styled-system/recipes";
-import { cx } from "styled-system/css";
+import { css, cx } from "styled-system/css";
 import { useLinkComponent, useResolvedVariant } from "../config/style-config";
 import { ALL_VARIANTS } from "../config/types";
 
@@ -17,6 +17,15 @@ import { ALL_VARIANTS } from "../config/types";
  */
 const LINK_VARIANTS = ALL_VARIANTS;
 
+/**
+ * How a link sits in its surroundings.
+ *
+ * `text` is the default and the safe one: a link in a sentence must not become
+ * a 48px control. `flow` is the layout participant. `control` is the tap
+ * target, and carries the house 48px floor.
+ */
+export type LinkPresentation = "text" | "flow" | "control";
+
 export interface StyledLinkProps
   extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
   /** Where the link goes. */
@@ -55,6 +64,61 @@ export interface StyledLinkProps
    */
   externalIndicator?: React.ReactNode;
   variant?: string;
+  /**
+   * Render as a standalone control with a 48x48 tap target, rather than as
+   * text inside a sentence.
+   *
+   * **The default is inline, and that is deliberate rather than a shortcut.**
+   * `buttonRecipe`'s base states `min-height: 48px`, `display: inline-flex`
+   * and padding — correct for a control, and wrong for a link in a paragraph,
+   * where it forces a 48px line box and breaks the text flow. Measured at
+   * 48.375px before this prop existed.
+   *
+   * Inline is also what the standard expects: WCAG 2.5.5 and 2.5.8 both carve
+   * out targets that are "in a sentence or block of text", so a text link at
+   * text height is conformant. The floor applies to the standalone case, and
+   * `standalone` is how a nav item, a card action or a button-shaped link asks
+   * for it.
+   *
+   * @deprecated Use `presentation` instead — `standalone` maps to
+   * `presentation="control"`. It is kept because it is public API and consumers
+   * pass it today; it will be removed once they have moved.
+   */
+  standalone?: boolean;
+  /**
+   * How the link sits in its surroundings. Three cases, because there are
+   * genuinely three (NEH-728).
+   *
+   * | | display | min-height | for |
+   * |---|---|---|---|
+   * | `text` (default) | `inline` | none | a link inside a sentence |
+   * | `flow` | `inline-flex` | none | a link that is a layout participant |
+   * | `control` | `inline-flex` | **48px** | a nav item, a card action |
+   *
+   * ## Why `flow` had to exist
+   *
+   * `text` and `control` look like they cover the space, and they do not. A
+   * link that is neither prose nor a tap target is extremely common — a row in
+   * a list, a cell in a grid, anything given a width by its parent — and
+   * HopperGuard had 67 of them (NEH-728).
+   *
+   * Neither of the other two can express it, and **both fail silently**:
+   *
+   * - `control` adds the 48px floor to links that are not tap targets, which
+   *   changes layout everywhere it is wrong.
+   * - `text` sets `display: inline`, and on a non-replaced inline box **`width`
+   *   does not apply** and **`margin-left: auto` does nothing** — so a `w` prop
+   *   becomes a no-op and a right-hand icon loses its push-to-end. No build
+   *   error, no type error, no warning; the link just renders wrong.
+   *
+   * `flow` is inline-flex without the floor: it takes a width, it lays its
+   * icons out, and it does not claim to be a 48px target when it is not.
+   *
+   * **Do not reach for `flow` to escape the tap-target floor on something that
+   * IS a control.** The floor is a house minimum, not a default to be routed
+   * around; `control` is the honest answer for anything a finger aims at.
+   */
+  presentation?: LinkPresentation;
 }
 
 /** The default external-destination glyph — "↗", north-east arrow. */
@@ -83,6 +147,8 @@ export const StyledLink = React.forwardRef<HTMLAnchorElement, StyledLinkProps>(
       rightIcon,
       externalIndicator,
       variant,
+      standalone = false,
+      presentation,
       className,
       ...rest
     },
@@ -90,7 +156,38 @@ export const StyledLink = React.forwardRef<HTMLAnchorElement, StyledLinkProps>(
   ) {
     const HostLink = useLinkComponent();
     const resolved = useResolvedVariant(variant ?? "link", LINK_VARIANTS);
-    const classes = cx(buttonRecipe({ variant: resolved }), className);
+
+    /*
+     * `presentation` wins; `standalone` is the deprecated spelling of
+     * `control`. Resolved in one place so there is no call site where the two
+     * disagree and the answer depends on which branch is read first.
+     */
+    const mode: LinkPresentation =
+      presentation ?? (standalone ? "control" : "text");
+
+    // The variant still comes from `buttonRecipe`, so colour, underline and
+    // hover stay one definition shared with every other control. Only the BOX
+    // is overridden — the properties that make a control a control are exactly
+    // the ones that break a sentence.
+    const classes = cx(
+      buttonRecipe({ variant: resolved }),
+      mode === "control"
+        ? undefined
+        : css({
+            /*
+             * `text` goes fully inline so it sits in a line box like any other
+             * word. `flow` stays a flex container: it is a layout participant,
+             * and on a non-replaced inline box `width` does not apply and
+             * `margin-left: auto` does nothing — so an inline `flow` would
+             * silently drop both (NEH-728).
+             */
+            display: mode === "flow" ? "inline-flex" : "inline",
+            minHeight: "0",
+            minWidth: "0",
+            padding: "0",
+          }),
+      className,
+    );
 
     const indicator =
       externalIndicator === undefined ? EXTERNAL_GLYPH : externalIndicator;

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/StyledTag.tsx

@@ -2,10 +2,51 @@
 
 import React from "react";
 import { css, cx } from "styled-system/css";
+import { tagRecipe } from "styled-system/recipes";
+import type { AlertStatus } from "./StyledAlert";
+
+/**
+ * A tag's tone.
+ *
+ * The four status names ARE `AlertStatus`, referenced rather than retyped, so
+ * the package cannot drift into two status vocabularies — a green that means
+ * "success" on a banner and "active" on a tag is the kind of divergence nobody
+ * notices until a product has both.
+ *
+ * `neutral` and `accent` extend it. `neutral` is the historical appearance and
+ * stays the default; `accent` exists because a tag is frequently just a
+ * *category* — a type, a group, a label — and forcing those into `info` would
+ * make "informational" mean nothing.
+ */
+export type TagTone = "neutral" | AlertStatus | "accent";
 
 export interface StyledTagProps
   extends Omit<React.HTMLAttributes<HTMLSpanElement>, "onSelect"> {
   children: React.ReactNode;
+  /**
+   * The tag's colour, carrying meaning.
+   *
+   * ## Colour must not be the only signal (WCAG 1.4.1, Level A)
+   *
+   * Usually it is not, and that is why there is no forced glyph here: a tag
+   * generally *is* its label, so `<StyledTag tone="success">Enabled</StyledTag>`
+   * says "enabled" in words and the colour merely reinforces it. `StyledAlert`
+   * needs a glyph because a banner's status is genuinely carried by its
+   * colouring; a tag's is carried by its text.
+   *
+   * **The exception is a tag whose label does not name its own state** — a
+   * feature name tinted green for on and grey for off, say. There the colour is
+   * the only signal and the criterion is unmet, so pass `indicator`.
+   */
+  tone?: TagTone;
+  /**
+   * A non-colour signal rendered before the label.
+   *
+   * Deliberately not defaulted per tone. See `tone` above: defaulting one would
+   * put a glyph on every tag in every consumer to fix the minority of cases
+   * where the label does not already say what the colour says.
+   */
+  indicator?: React.ReactNode;
   /**
    * Show a remove control, and call this when it is activated.
    *
@@ -49,33 +90,29 @@ export interface StyledTagProps
  */
 export const StyledTag = React.forwardRef<HTMLSpanElement, StyledTagProps>(
   function StyledTag(
-    { children, onRemove, removeLabel = "Remove", className, ...rest },
+    {
+      children,
+      tone = "neutral",
+      indicator,
+      onRemove,
+      removeLabel = "Remove",
+      className,
+      ...rest
+    },
     ref,
   ) {
     return (
       <span
         ref={ref}
-        className={cx(
-          css({
-            display: "inline-flex",
-            alignItems: "center",
-            gap: "1",
-            paddingInline: "2",
-            // Vertical padding is deliberately absent: the height comes from
-            // the line box and the horizontal padding, so a tag tracks the
-            // font scale instead of needing a re-tune whenever it moves.
-            borderRadius: "md",
-            backgroundColor: "boxBgSecondary",
-            color: "textSecondary",
-            // Not a tap target: a plain tag is not interactive, so the 48px
-            // floor does not apply to it. The remove BUTTON below is, and does.
-            fontSize: "sm",
-            whiteSpace: "nowrap",
-          }),
-          className,
-        )}
+        /*
+         * The recipe, not an inline `css()` — see `preset/recipes/tag.ts`. A
+         * tone computed at runtime (`tone={STATUS_COLOR[status]}`) is invisible
+         * to Panda's extractor, and `staticCssRecipes` is what covers it.
+         */
+        className={cx(tagRecipe({ tone }), className)}
         {...rest}
       >
+        {indicator !== undefined && <span aria-hidden="true">{indicator}</span>}
         <span>{children}</span>
         {onRemove !== undefined && (
           <button

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/index.ts

@@ -204,10 +204,10 @@ export type { StyledFormLabelProps } from "./components/StyledFormLabel";
 // that stops it working.
 // ---------------------------------------------------------------------------
 export { default as StyledLink, StyledLink as Link } from "./components/StyledLink";
-export type { StyledLinkProps } from "./components/StyledLink";
+export type { StyledLinkProps, LinkPresentation } from "./components/StyledLink";
 
 export { default as StyledTag, StyledTag as Tag } from "./components/StyledTag";
-export type { StyledTagProps } from "./components/StyledTag";
+export type { StyledTagProps, TagTone } from "./components/StyledTag";
 
 export {
   default as StyledFieldErrors,