@stonedogcode/style 0.16.0 → 0.17.0

package/README.md

@@ -629,6 +629,55 @@ Scroll mode needs a height to scroll inside: `StyledScrollbar` is
 height (`display: flex; flex-direction: column; height: …`). Unconstrained, the
 rail simply grows — which is correct, and is not a bug.
 
+## Form help — `StyledFieldHelp`
+
+Permanent explanatory text for a field: below the label, above the control,
+always visible.
+
+```tsx
+<StyledFormLabel htmlFor="dose">Dose</StyledFormLabel>
+<StyledFieldHelp htmlFor="dose">
+  Milligrams per tablet, as printed on the bottle.
+</StyledFieldHelp>
+<StyledInputText id="dose" />
+```
+
+It is **text, and nothing else** — no trigger, no disclosure, no popover, no
+preference. That is the design rather than a simplification, and it is what the
+guarantees below rest on.
+
+### What it guarantees
+
+- **Zero tab stops.** Nothing here is focusable, so explaining a hundred fields
+  costs the keyboard nothing. The pattern this replaces put a help *button*
+  beside every explained control, which roughly doubled keyboard traversal on a
+  busy form and cannot be fixed while a per-control control remains: taking the
+  buttons out of the tab order loses the help for sighted keyboard users
+  instead.
+- **The control's `aria-describedby` points at it**, so a screen reader
+  announces the words as the field's description rather than reading them as
+  stray prose further down the page. The component sets the attribute itself,
+  merging with any description the control already had and removing only its own
+  id when it unmounts — so a call site that forgets still gets the association.
+  `fieldHelpId("dose")` is `"dose-help"`, exported so a host can put the
+  attribute in server-rendered markup instead; the component notices and stands
+  down.
+- **No pointer is involved**, which sidesteps WCAG 1.4.13 (Content on Hover or
+  Focus) rather than trying to satisfy it. Touch, mouse and keyboard all get the
+  same words with no gesture and no setting.
+- **One tier below the app-wide text size, and never below the smallest tier**
+  the host offers. A reader who has already turned their text down is the one
+  with the least room to spare.
+- **Contrast is measured, not assumed.** The colour is the emphasis token
+  `textMuted`, which is `currentColor`-relative, so it de-emphasises correctly
+  on a light theme and a dark one. The component tests composite the whole
+  ancestor chain — every translucent layer, not the page background — and assert
+  WCAG 1.4.3 AA against the surface the text really paints on. Measuring against
+  the page is how text on a tinted chip gets a confident, wrong pass.
+
+`children` is typed `ReactNode` for formatting — a unit, a `<strong>`, a line
+break. Putting a control in there defeats the only promise the component makes.
+
 ## Adopting a component as it is migrated
 
 Components move out of HopperGuard into this package one at a time.

package/package.json

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

package/src/components/StyledFieldHelp.tsx

@@ -0,0 +1,248 @@
+"use client";
+
+import React, { useEffect, useRef } from "react";
+import { styled } from "styled-system/jsx";
+import type { HTMLStyledProps } from "styled-system/types";
+import { log } from "../config/logger";
+import { useFontSizeProfile } from "../config/style-config";
+import { fontSizeMap, stepDownFontSize } from "../config/font-size";
+
+/**
+ * Permanent help text for a form control: below the label, above the control,
+ * always visible, never interactive.
+ *
+ * ```tsx
+ * <StyledFormLabel htmlFor="dose">Dose</StyledFormLabel>
+ * <StyledFieldHelp htmlFor="dose">
+ *   Milligrams per tablet, as printed on the bottle.
+ * </StyledFieldHelp>
+ * <StyledInputText id="dose" />
+ * ```
+ *
+ * ## Why this exists rather than another tooltip (PRD-0037, NEH-972)
+ *
+ * The pattern this replaces is `StyledTooltip` plus its `HelpTrigger`, and the
+ * problem with it is not placement — NEH-769 fixed the placement and the
+ * pattern was still wrong. Four things fail at once:
+ *
+ * - **Hover-only help excludes touch entirely**, and is actively hostile to a
+ *   reader with a tremor: they open tooltips by accident and cannot reliably
+ *   move a pointer *into* one before it closes.
+ * - **`HelpTrigger` is a `<button>`, so every instance is a tab stop.** A
+ *   screenshot of one production screen showed roughly twenty of them; ~160
+ *   across the app. That roughly doubles keyboard traversal, and it cannot be
+ *   fixed by taking them out of the tab order — a sighted keyboard user not
+ *   running a screen reader would lose the help altogether. There is no fix
+ *   for the tab-stop tax that keeps a per-control control.
+ * - **Twenty identical glyphs are not twenty helps, they are noise.** Older
+ *   readers have measurably low tolerance for hidden information behind an
+ *   abstract icon, so the pattern penalised exactly the audience it was for.
+ * - It needed a **preference** (`accessibility.clickForTooltips`) to be usable
+ *   on a touch device, and a preference is a thing to get wrong.
+ *
+ * So this component has **no trigger, no state, no preference and no
+ * interaction**. It is text. That is the entire design, and every constraint
+ * below follows from it:
+ *
+ * - it adds **zero tab stops** — no `tabindex`, no focusable element, nothing
+ *   Tab can land on;
+ * - it needs **no pointer**, so it sidesteps WCAG 1.4.13 (Content on Hover or
+ *   Focus) rather than trying to satisfy dismissible/hoverable/persistent;
+ * - it is in the DOM from first paint, so a touch reader, a keyboard reader and
+ *   a screen-reader user all get the same words with no gesture at all.
+ *
+ * ## It wires `aria-describedby` itself, and that is deliberate
+ *
+ * Text sitting near a control is not a description of it. Without
+ * `aria-describedby` a screen reader announces "Dose, edit text" and the help
+ * is stray prose somewhere else in the reading order — which is how a field
+ * ends up *looking* explained and being unexplained.
+ *
+ * Two things make the association hard to get wrong, because this pattern is
+ * about to be applied at well over a hundred call sites and the one that gets
+ * skipped is the one nobody notices:
+ *
+ * 1. **The id is derived, not generated.** `fieldHelpId("dose")` is
+ *    `"dose-help"` — deterministic from the control's own id, so both sides can
+ *    name it without passing a generated value around, and it is stable across
+ *    server and client render.
+ * 2. **The component sets the attribute on the control** in an effect, merging
+ *    with anything already there. A call site that forgets still gets the
+ *    association.
+ *
+ * Set imperatively rather than by cloning the child, for the reason
+ * `StyledTooltip` records: `cloneElement` depends on every child component
+ * forwarding the prop, and a child that quietly drops it fails invisibly. It is
+ * not a wrapper for the same reason — a wrapper would have to own the control's
+ * markup, and this has to drop into a form whose markup already exists.
+ *
+ * `useEffect` rather than `useLayoutEffect`: nothing here affects layout, and
+ * the accessibility tree is read after hydration. A host may still write
+ * `aria-describedby={fieldHelpId("dose")}` on the control itself if it wants
+ * the association present in server-rendered HTML; the effect sees it is
+ * already there and leaves it alone.
+ *
+ * ## Size and colour
+ *
+ * **One tier below the app-wide text size, never below `xs`.** The size is an
+ * inline style rather than a Panda prop because Panda extracts styles by
+ * parsing source at BUILD time: a prop whose value is only known at runtime
+ * yields a class name with no rule behind it, and nothing errors.
+ * `StyledFormLabel` and `StyledText` reach for an inline style for exactly this
+ * reason. Reading the profile also matters — plain inheritance would pin the
+ * help to whatever the browser default is, which in a product whose body text
+ * is 1.375rem makes the help less than two-thirds the size of the text it
+ * explains.
+ *
+ * **Colour is `textMuted`**, the emphasis axis, which resolves relative to
+ * `currentColor` — so it de-emphasises against the surface it is actually on,
+ * light theme or dark, rather than picking a grey that is right on one of them.
+ * `StyledFieldHelp.contrast.ct.tsx` measures the rendered result against the
+ * **composited** background — every ancestor layer, not the page — and asserts
+ * WCAG 1.4.3 AA. Measuring against the page background is how a confidently
+ * wrong pass gets produced for text that sits on a tinted chip.
+ *
+ * The size step and the colour step are two signals, not one, so the help still
+ * reads as secondary for anyone who cannot see the colour difference.
+ */
+
+const PandaFieldHelp = styled("p", {
+  base: {
+    display: "block",
+    // Longhands, never the `margin` shorthand. Panda emits atomic rules, and a
+    // shorthand competing with a longhand for the same box is decided by
+    // stylesheet order rather than by what was written.
+    marginTop: "0",
+    marginInline: "0",
+    // The gap before the control. `StyledFormLabel` supplies the gap above.
+    marginBottom: "0.5rem",
+    color: "textMuted",
+    // Prose, and prose that is being read carefully — a little more leading
+    // than the label above it.
+    lineHeight: "1.4",
+    fontWeight: "normal",
+    // No `fontSize`: it is resolved at runtime from the profile. See above.
+  },
+});
+
+/**
+ * The `id` this component gives its help text, derived from the control's id.
+ *
+ * Exported so a call site can put the association in server-rendered HTML —
+ * `aria-describedby={fieldHelpId("dose")}` — and so a test can name the element
+ * without reaching into the DOM for it. Deterministic on purpose: a generated
+ * id (`useId`) cannot be named by the other half of the pair without threading
+ * a value between two siblings, and threading is what gets skipped.
+ */
+export function fieldHelpId(controlId: string): string {
+  return `${controlId}-help`;
+}
+
+/** Split an `aria-describedby` attribute into its id tokens. */
+function idTokens(value: string | null): string[] {
+  return value ? value.split(/\s+/).filter(Boolean) : [];
+}
+
+export interface StyledFieldHelpProps
+  extends Omit<HTMLStyledProps<"p">, "children"> {
+  /**
+   * The `id` of the control this describes.
+   *
+   * Required, and it is the whole point: without it this is prose near a
+   * control rather than the control's description. Named `htmlFor` to match
+   * `StyledFormLabel`, so the pair reads the same at a call site.
+   */
+  htmlFor: string;
+  /**
+   * The help itself. **Text.** Anything focusable put in here defeats the one
+   * guarantee this component makes, so it is typed as `ReactNode` for
+   * formatting (`<strong>`, a unit, a line break) rather than for controls.
+   */
+  children: React.ReactNode;
+  /** Override the derived id. Rarely wanted — see `fieldHelpId`. */
+  id?: string;
+}
+
+const StyledFieldHelp: React.FC<StyledFieldHelpProps> = ({
+  htmlFor,
+  children,
+  id,
+  style,
+  fontSize,
+  ...props
+}) => {
+  // Unconditional and at the top: folding this into the expression below reads
+  // fine and is a hooks-order violation the moment `fontSize` is passed.
+  const profile = useFontSizeProfile();
+  const ref = useRef<HTMLParagraphElement | null>(null);
+
+  const helpId = id ?? fieldHelpId(htmlFor);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+
+    // The element's own document, not the global one: a component test mounts
+    // inside an iframe, and a host may portal into another window.
+    const control = node.ownerDocument.getElementById(htmlFor);
+    if (!control) {
+      // Not thrown. A missing control is a call-site bug, but the help text is
+      // still readable on screen and throwing would take the whole form down
+      // over an attribute. The host hears about it through its own logger.
+      log.warn(
+        "StyledFieldHelp: no element has this id, so the help is not announced as the field's description",
+        { htmlFor, helpId },
+      );
+      return;
+    }
+
+    const tokens = idTokens(control.getAttribute("aria-describedby"));
+    // Already named — the call site wired it statically. Leave it be, or the
+    // id lands twice and a screen reader reads the description twice.
+    if (tokens.includes(helpId)) return;
+
+    control.setAttribute("aria-describedby", [...tokens, helpId].join(" "));
+
+    return () => {
+      // Read the attribute again rather than restoring the value captured
+      // above. Something else may have added its own id in the meantime — an
+      // error summary is the obvious one — and restoring a stale string would
+      // silently drop it.
+      const remaining = idTokens(
+        control.getAttribute("aria-describedby"),
+      ).filter((token) => token !== helpId);
+      if (remaining.length > 0) {
+        control.setAttribute("aria-describedby", remaining.join(" "));
+      } else {
+        control.removeAttribute("aria-describedby");
+      }
+    };
+  }, [htmlFor, helpId]);
+
+  // Applied only when the caller named no size, so their Panda `fontSize` class
+  // is not beaten by an inline declaration.
+  const sized = fontSize
+    ? undefined
+    : fontSizeMap[stepDownFontSize(profile)] ?? fontSizeMap.sm;
+
+  return (
+    <PandaFieldHelp
+      ref={ref}
+      id={helpId}
+      fontSize={fontSize}
+      // A stable hook for the app's own end-to-end assertion that help is in
+      // the DOM with no pointer interaction (PRD-0037's success criteria), and
+      // for finding the call sites during the migration.
+      data-field-help="true"
+      style={{ ...(sized ? { fontSize: sized } : {}), ...style }}
+      {...props}
+    >
+      {children}
+    </PandaFieldHelp>
+  );
+};
+
+StyledFieldHelp.displayName = "StyledFieldHelp";
+
+export default StyledFieldHelp;
+export { StyledFieldHelp };

package/src/components/StyledTooltip.tsx

@@ -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
@@ -182,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
@@ -233,9 +244,36 @@ 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);
@@ -251,6 +289,20 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
     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(
@@ -259,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
@@ -482,6 +534,51 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   // would produce "[object Object]" in the accessibility tree.
   const tooltipLabel = typeof tooltip === "string" ? tooltip : undefined;
 
+  /**
+   * `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 (
     <>
@@ -519,24 +616,21 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
         onMouseLeave={isClick ? undefined : hide}
         onFocus={isClick ? undefined : show}
         onBlur={isClick ? undefined : hide}
-        aria-describedby={
-          !isClick && !insideFocusable && 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/semantic-variables.ts

@@ -154,13 +154,30 @@ const COLOR_TOKENS: TokenMap = {
  * with a sensible default so every project can adopt it immediately — applied
  * to the case where a default is genuinely knowable.
  *
- * ## The percentages are measured, not chosen
+ * ## `textMuted` is measured. `textSubtle` is still only chosen (NEH-974)
  *
  * Alpha de-emphasis trades contrast for hierarchy, and past some point it
- * trades away legibility. `emphasis-contrast.ct.tsx` measures both tiers
- * against the harness theme in a real browser and asserts they clear WCAG AA
- * (4.5:1); the values below are what passed. A host that wants a stronger or
- * weaker step defines the property.
+ * trades away legibility, so these percentages want measuring rather than
+ * picking.
+ *
+ * This comment claimed both tiers were measured by a file called
+ * `emphasis-contrast.ct.tsx`, **and no such file has ever existed** — the whole
+ * repo contains exactly one reference to that name, this one. A documented
+ * guard nobody implemented is worse than an absent one: it is a guard everybody
+ * believes in, and it is what made "the values below are what passed" read as a
+ * measurement rather than as a guess.
+ *
+ * What is true today: `components/StyledFieldHelp.contrast.ct.tsx` measures
+ * **`textMuted`** in a real browser, composited over the surface it actually
+ * paints on rather than over the page, and asserts WCAG 1.4.3 AA (4.5:1). On
+ * the harness theme it clears comfortably — 11.7:1 on the page, 9.1:1 on an
+ * opaque card, 8.2:1 on a translucent chip over that card.
+ *
+ * **`textSubtle` at 64% is not measured anywhere.** It is the tier closer to
+ * the legibility floor, so it is the one that needed the check more. Tracked;
+ * do not restore the claim that it passed something.
+ *
+ * A host that wants a stronger or weaker step defines the property.
  */
 const EMPHASIS_TOKENS: Record<string, [suffix: string, fallback: string]> = {
   /** Secondary information: still read, just not first. */