@stonedogcode/style 0.10.1 → 0.12.0

package/README.md

@@ -82,7 +82,8 @@ token reads one, and **a token whose property is undefined renders as nothing**
 no fallback, no warning, no error. An app that skips this compiles, builds,
 serves, and shows you a blank page.
 
-There are **44** of them. Get the list at runtime rather than copying one:
+There are **45** of them. Get the list at runtime rather than copying one — a
+number in prose goes stale the day a token is added, and this one already had:
 
 ```ts
 import { requiredCssCustomProperties } from "@stonedogcode/style/preset";
@@ -91,7 +92,57 @@ requiredCssCustomProperties();           // --hopper-* (default)
 requiredCssCustomProperties("optima");   // --optima-*, if you set cssVarPrefix
 ```
 
-A complete starter theme — all 44, nothing elided. Dark, and every text/surface
+### 8 colour tokens you do NOT have to define
+
+`textMuted` and `textSubtle` are the **emphasis** axis — how important a piece
+of text is, on whatever surface it sits. They are the one exception to the
+no-fallback rule above, and they are not in `requiredCssCustomProperties()`.
+
+They can have a default because *"like the surrounding text, but quieter"* has a
+correct answer on every theme, which *"what colour is this surface?"* does not:
+
+```css
+color-mix(in srgb, currentColor 78%, transparent)   /* textMuted  */
+color-mix(in srgb, currentColor 64%, transparent)   /* textSubtle */
+```
+
+`currentColor` inside a `color` declaration resolves to the **inherited** value,
+so both follow whatever text they sit among — light theme, dark theme, or a
+palette this package has never seen. Both clear WCAG AA against the surfaces
+they pair with, measured in a browser rather than chosen by eye.
+
+Define `--<prefix>-text-muted-text` / `--<prefix>-text-subtle-text` only if you
+want a different step.
+
+### ...and six more, for status
+
+`boxSuccess` / `boxWarning` / `boxError` and their `borderSuccess` /
+`borderWarning` / `borderError` are the chips `StyledAlert` paints on. They are
+defaulted for the same reason and a slightly different one: **danger-red,
+caution-amber and success-green are near-universal**, so a default is knowable
+where "what colour is this surface?" is not.
+
+The hue is fixed and the *lightness* is not, which is the split that matters —
+red has to stay red to mean danger, but how light that red sits has to follow
+the page:
+
+```css
+color-mix(in srgb, #dc2626 14%, transparent)   /* boxError    — tints the page */
+#dc2626                                        /* borderError — a solid hue    */
+```
+
+The borders are solid because a translucent one cannot clear WCAG 1.4.11 (3:1
+for a non-text boundary): at 45% they measured 1.72–2.05:1 against a dark page.
+A saturated mid-tone clears 3:1 at both ends, which is what lets one value serve
+a light theme and a dark one.
+
+Define `--<prefix>-box-{success,warning,error}-{bg,border}` to use your own.
+
+**Do not reach for `textSecondary` when you mean "muted".** That is the *surface*
+axis — it means "text on the secondary surface" — and using it for emphasis
+collapses two levels onto one colour.
+
+A complete starter theme — all 45, nothing elided. Dark, and every text/surface
 pair clears WCAG AA (measured: worst 5.17:1, ten of thirteen pairs at AAA), so
 it is a legitimate starting point rather than a placeholder. Replace the values;
 keep every key.
@@ -115,6 +166,7 @@ keep every key.
   --hopper-text-pop-text: #38bdf8;
   --hopper-text-error-text: #f87171;
   --hopper-text-warning-text: #fbbf24;
+  --hopper-text-success-text: #4ade80;
 
   /* Borders */
   --hopper-box-primary-border: #475569;
@@ -193,7 +245,7 @@ the three ways this goes wrong silently:
 ```bash
 npx panda cssgen --outfile styled-system/styles.css
 
-# 1. Did the preset load? Expect ~44 matches, not 0.
+# 1. Did the preset load? Expect ~45 matches, not 0.
 grep -c 'var(--hopper-' styled-system/styles.css
 
 # 2. Did Panda parse the package's source? Expect ~240 classes, not ~0.
@@ -278,7 +330,7 @@ stonedogStylePreset({ cssVarPrefix: "acme" }); // → var(--acme-box-primary-bg)
 
 The rename is total — every token re-points, and no `--hopper-*` reference
 survives anywhere in the generated CSS. Choose it **before** you write a theme,
-because it changes all 44 property names you have to define.
+because it changes all 45 property names you have to define.
 
 ## Adopting it in a new app — a worked example
 
@@ -361,7 +413,7 @@ export default defineConfig({
 
 ```tsx
 // 4. Your root — theme first, then the provider
-import "./theme.css";                 // the 44 properties, from step 3 above
+import "./theme.css";                 // the 45 properties, from step 3 above
 import { StonedogStyleProvider } from "@stonedogcode/style";
 
 export function Root({ children }) {
@@ -579,7 +631,7 @@ rail simply grows — which is correct, and is not a bug.
 
 ## Adopting a component as it is migrated
 
-Components move out of HopperGuard into this package one at a time (NEH-167).
+Components move out of HopperGuard into this package one at a time.
 Each lands as its own release, so consumers adopt on their own schedule rather
 than waiting for a big-bang switch.
 
@@ -640,7 +692,7 @@ import { StyledSpinner } from "@stonedogcode/style";
 `optima-filings` is public and AGPLv3 and ships a public Docker image, so it
 uses a **permissive icon set** (Lucide) through the icon seam rather than the
 private Font Awesome package. Everything else is shared. Both Optima repos run
-their own `--optima-*` namespace via `cssVarPrefix` (NEH-170).
+their own `--optima-*` namespace via `cssVarPrefix`.
 
 ### Verify — the three checks that actually catch things
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.10.1",
+  "version": "0.12.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 NEH-482 and it is the single thing most likely to be forgotten in a scope migration.",
+  "//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": {
     "access": "public"
   },

package/src/components/StyledAlert.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import React from "react";
+import { alertRecipe } from "styled-system/recipes";
+import { cx } from "styled-system/css";
+
+/** The four things an alert can be. */
+export type AlertStatus = "info" | "success" | "warning" | "error";
+
+/**
+ * Which ARIA role each status takes, and why they are not all the same.
+ *
+ * The difference is whether the announcement **interrupts**. `alert` is an
+ * assertive live region: a screen reader abandons what it was saying to read it.
+ * That is right for a failure the user must deal with and wrong for a
+ * confirmation — being interrupted mid-sentence to be told something worked is
+ * hostile, and doing it for every status trains people to ignore the important
+ * ones.
+ *
+ * The original component had **no role at all**, so none of the four was
+ * announced. An alert that is not announced is not an alert (NEH-421).
+ */
+const ROLE_FOR_STATUS: Record<AlertStatus, "alert" | "status"> = {
+  error: "alert",
+  warning: "alert",
+  info: "status",
+  success: "status",
+};
+
+/**
+ * The non-colour signal for each status — WCAG 1.4.1 (Use of Colour), Level A.
+ *
+ * The original conveyed status by background colour alone. The `Indicator` slot
+ * existed and every call site left it empty, so the whole distinction was
+ * invisible to anyone who cannot separate four pale washes — which includes
+ * roughly one man in twelve, and anyone on a bad screen in daylight.
+ *
+ * These are text characters rather than icons on purpose. This package ships no
+ * artwork by policy, and a glyph inherits `currentColor` and the font scale for
+ * free, so the signal survives a font-size change and cannot end up a different
+ * colour from the message beside it.
+ *
+ * They are `aria-hidden`: the role above already tells a screen reader what kind
+ * of message this is, and reading "warning sign" before the text would be the
+ * same information twice.
+ */
+const GLYPH_FOR_STATUS: Record<AlertStatus, string> = {
+  info: "i",
+  success: "✓",
+  warning: "!",
+  error: "✕",
+};
+
+export interface StyledAlertProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Which kind of message this is. Decides colour, glyph AND announcement. */
+  status?: AlertStatus;
+  /** Optional heading, shown above the message in bold. */
+  title?: React.ReactNode;
+  /**
+   * Replace the built-in glyph.
+   *
+   * Pass a node to substitute your own icon, or `null` to render no indicator.
+   * `null` is deliberately possible and deliberately awkward to reach for: it
+   * puts the component back in breach of WCAG 1.4.1 unless the surrounding UI
+   * carries the signal some other way.
+   */
+  indicator?: React.ReactNode;
+  children?: React.ReactNode;
+}
+
+/**
+ * A status banner.
+ *
+ * ```tsx
+ * <StyledAlert status="error" title="Something went wrong">
+ *   We could not save your changes.
+ * </StyledAlert>
+ * ```
+ */
+export const StyledAlert = React.forwardRef<HTMLDivElement, StyledAlertProps>(
+  function StyledAlert(
+    { status = "info", title, indicator, children, className, ...rest },
+    ref,
+  ) {
+    const classes = alertRecipe({ status });
+    const glyph = indicator === undefined ? GLYPH_FOR_STATUS[status] : indicator;
+
+    return (
+      <div
+        ref={ref}
+        // `role` and `aria-live` together: the role carries the semantics, and
+        // the explicit `aria-live` is what makes an alert rendered into an
+        // already-present region announce when its CONTENT changes rather than
+        // only when it mounts. A banner that swaps "saving" for "failed" in
+        // place is the common case and the one that otherwise goes silent.
+        role={ROLE_FOR_STATUS[status]}
+        aria-live={ROLE_FOR_STATUS[status] === "alert" ? "assertive" : "polite"}
+        className={cx(classes.root, className)}
+        {...rest}
+      >
+        {glyph !== null && (
+          <span aria-hidden="true" className={classes.indicator}>
+            {glyph}
+          </span>
+        )}
+        <div className={classes.content}>
+          {title !== undefined && title !== null && (
+            <div className={classes.title}>{title}</div>
+          )}
+          {children !== undefined && children !== null && (
+            <div className={classes.description}>{children}</div>
+          )}
+        </div>
+      </div>
+    );
+  },
+);
+
+export default StyledAlert;

package/src/components/StyledText.tsx

@@ -6,7 +6,7 @@ import { styled } from "styled-system/jsx";
 import { css, cx } from "styled-system/css";
 import StyledTooltip from "./StyledTooltip";
 import { useFontSizeProfile } from "../config/style-config";
-import { fontSizeMap } from "../config/font-size";
+import { fontSizeMap, resolveFontSizeKey } from "../config/font-size";
 import type { AllowedTextVariant } from "../config/types";
 import { textRecipe } from "styled-system/recipes";
 
@@ -114,15 +114,7 @@ const StyledText = React.forwardRef<HTMLSpanElement, StyledTextProps>((props, re
   } = props;
   const fontSizeProfile = useFontSizeProfile();
 
-  let finalSize;
-  if (size) {
-    finalSize = size;
-  } else if (fixedSize) {
-    finalSize = "md";
-  } else {
-    finalSize = fontSizeProfile;
-  }
-
+  const finalSize = resolveFontSizeKey({ size, fixedSize, profile: fontSizeProfile });
   const fontSize = fontSizeMap[finalSize] || fontSizeMap.md;
 
   const extraStyles: React.CSSProperties = {};

package/src/config/font-size.ts

@@ -62,6 +62,42 @@ export function getFontSizeLabel(size: string): string {
   return fontSizeLabelMap[size] ?? size;
 }
 
+/**
+ * Which scale step a piece of text ends up at: caller → `fixedSize` → profile.
+ *
+ * The same precedence shape as `useResolvedVariant`, and here for the same
+ * reason — but it is a *pure function* rather than a branch inside `StyledText`
+ * specifically so the unit tier can assert it (NEH-406).
+ *
+ * That mattered more than it looks. The rule was only ever checked through a
+ * rendered `font-size`, and **jsdom cannot see one of these values at all**:
+ * every `fontSizeMap` entry is a `var(--font-sizes-*, …)` reference, jsdom's
+ * CSS parser rejects it against the `font-size` grammar, and the declaration is
+ * dropped — the element ends up with no `style` attribute whatsoever. So
+ * `toHaveStyle({ fontSize: <anything> })` compared "" with "" and passed for
+ * every possible expectation, including one asserting a size that had not been
+ * true since the scale moved.
+ *
+ * Splitting the rule out gives each tier a question it can actually answer:
+ * *which step wins* here, and *what does it measure* in the browser tier.
+ *
+ * `fixedSize` pins to `md` — used where a label must not grow with the profile,
+ * e.g. inside a fixed-height control it would otherwise clip.
+ */
+export function resolveFontSizeKey({
+  size,
+  fixedSize,
+  profile,
+}: {
+  size?: string | undefined;
+  fixedSize?: boolean | undefined;
+  profile?: string | undefined;
+}): string {
+  if (size) return size;
+  if (fixedSize) return "md";
+  return profile ?? "md";
+}
+
 /**
  * The literal fallback inside a `fontSizeMap` entry, e.g. `"1rem"`.
  *

package/src/index.ts

@@ -229,6 +229,9 @@ export type { StyledSearchProps } from "./components/StyledSearch";
 export { default as StyledInputToggle } from "./components/StyledInputToggle";
 export type { StyledInputToggleProps } from "./components/StyledInputToggle";
 
+export { default as StyledAlert } from "./components/StyledAlert";
+export type { StyledAlertProps, AlertStatus } from "./components/StyledAlert";
+
 export { default as StyledInputRadio } from "./components/StyledInputRadio";
 export type { StyledInputRadioProps, RadioItem, RadioVariant } from "./components/StyledInputRadio";
 export { RADIO_VARIANTS } from "./components/StyledInputRadio";

package/src/preset/index.ts

@@ -14,6 +14,7 @@ import {
   inputDropdownItemRecipe,
   inputDropdownRecipe,
 } from "./recipes/input-dropdown";
+import { alertRecipe } from "./recipes/alert";
 import { inputRadioRootRecipe } from "./recipes/input-radio";
 import { inputTextRecipe } from "./recipes/input-text";
 import { listRecipe } from "./recipes/list";
@@ -53,7 +54,7 @@ export interface StonedogStylePresetOptions {
 /**
  * Every recipe, keyed by the name it is exported under in `styled-system/recipes`.
  *
- * Four of these (`listRecipe`, `menuRecipe`, `inputBoolRecipe`,
+ * Five of these (`alertRecipe`, `listRecipe`, `menuRecipe`, `inputBoolRecipe`,
  * `inputRadioRootRecipe`) are slot recipes declared with `defineSlotRecipe`.
  * Panda accepts them here rather than under `slotRecipes` and generates them
  * correctly — verified against HopperGuard's own generated output. Moving them
@@ -61,6 +62,7 @@ export interface StonedogStylePresetOptions {
  * generated surface, so it is deliberately not done during extraction.
  */
 const recipes = {
+  alertRecipe,
   arrowRecipe,
   boxRecipe,
   buttonRecipe,

package/src/preset/recipes/alert.ts

@@ -0,0 +1,95 @@
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * A status banner: an icon, a title and a message, on a tinted chip.
+ *
+ * Extracted from HopperGuard, where all four statuses painted from the raw
+ * Panda palette (`red.50` / `red.200` / `red.700` and friends). Those ignore the
+ * theme and dark mode entirely and sit outside contrast validation, so on a dark
+ * theme the component rendered dark text on a light chip regardless of its
+ * surroundings — the NEH-278 family (NEH-421).
+ *
+ * Every colour here is now a token. Three of the four statuses needed tokens
+ * that did not exist; see `STATUS_SURFACE_TOKENS` for why those carry a default
+ * where the rest of the contract does not.
+ */
+export const alertRecipe = defineSlotRecipe({
+  className: "alert",
+  description: "A status banner — info, success, warning or error",
+  slots: ["root", "indicator", "content", "title", "description"],
+  base: {
+    root: {
+      position: "relative",
+      display: "flex",
+      alignItems: "flex-start",
+      gap: "3",
+      padding: "4",
+      borderRadius: "md",
+      borderWidth: "1px",
+      borderStyle: "solid",
+      // Stated, not inherited: a themed typeface otherwise reaches the page and
+      // stops at the edge of the component (NEH-289).
+      fontFamily: "body",
+    },
+    indicator: {
+      flexShrink: 0,
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      // Sized to sit on the first line of the title rather than centred against
+      // the whole block, which drifts as the message grows.
+      width: "1.25em",
+      height: "1.5em",
+      lineHeight: "1",
+      fontSize: "lg",
+      // The glyph inherits the chip's text colour, so it never needs a colour of
+      // its own and can never disagree with the message beside it.
+      color: "inherit",
+    },
+    content: {
+      flex: "1",
+      minWidth: "0",
+    },
+    title: {
+      fontWeight: "bold",
+    },
+    description: {
+      display: "block",
+    },
+  },
+  variants: {
+    status: {
+      info: {
+        root: {
+          backgroundColor: "boxInfo",
+          borderColor: "borderBgAccent",
+          color: "textMain",
+        },
+      },
+      success: {
+        root: {
+          backgroundColor: "boxSuccess",
+          borderColor: "borderSuccess",
+          color: "textSuccess",
+        },
+      },
+      warning: {
+        root: {
+          backgroundColor: "boxWarning",
+          borderColor: "borderWarning",
+          color: "textWarning",
+        },
+      },
+      error: {
+        root: {
+          backgroundColor: "boxError",
+          borderColor: "borderError",
+          color: "textError",
+        },
+      },
+    },
+  },
+  defaultVariants: {
+    status: "info",
+  },
+});

package/src/preset/recipes/box.ts

@@ -34,6 +34,12 @@ export const boxRecipe = defineRecipe({
       },
       link: {
         bg: "boxBgPrimary",
+        // Its two siblings above, `solid` and `outline`, paint the same
+        // background and both state `textPrimary`; this one did not, so its
+        // text inherited from the page and could land unreadable on the same
+        // surface they render correctly on (NEH-441). Character for character
+        // the defect already fixed in `listRecipe` under NEH-167 cycle 9.
+        color: "textPrimary",
         _hover: {
           textDecoration: "underline",
         },

package/src/preset/recipes/button.ts

@@ -45,11 +45,23 @@ export const buttonRecipe = defineRecipe({
       },
       outline: {
         bg: "buttonBgAccent",
+        // Paints an accent background, so it must state the text colour that
+        // goes with it. Without this the label inherits whatever the page has,
+        // and under a theme whose surface sits at the same end of the scale as
+        // the inherited text it is unreadable — the NEH-278 family (NEH-441).
+        //
+        // `buttonTextAccent` exists in the token contract specifically to pair
+        // with `buttonBgAccent`, and every host already defines it, so this
+        // costs no host action. The hover state repaints the background, so it
+        // takes the matching hover pairing rather than letting the base colour
+        // ride along against a different surface.
+        color: "buttonTextAccent",
         border: "2px solid",
         borderRadius: 0,
         _hover: {
           border: "2px solid",
           bg: "buttonBgAccentHover",
+          color: "buttonTextAccentHover",
         },
       },
       aurora: {

package/src/preset/recipes/icon.ts

@@ -3,7 +3,19 @@ import { defineRecipe } from "@pandacss/dev";
 export const iconRecipe = defineRecipe({
   className: "icon",
   base: {
-    display: "inline-block",
+    // A centring flex box, not `inline-block` (NEH-562). `StyledIcon` sizes
+    // this wrapper in pixels while the icon set sizes the glyph from
+    // `font-size` — two independent numbers — so on an inline-block wrapper the
+    // glyph sat on a text baseline rather than in the middle of the box, and
+    // Font Awesome's `vertical-align: -0.125em` pushed it a further ~2px down.
+    // That was a visible sag under the label on every icon-bearing button in
+    // the product. A flex item ignores `vertical-align`, so centring here fixes
+    // the whole class rather than one call site.
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    // Still meaningful: it aligns this wrapper within a parent's line box, for
+    // the call sites that drop an icon into running text.
     verticalAlign: "middle",
     lineHeight: 1,
     fontSize: "var(--font-sizes-2xl, 1.5rem)",

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

@@ -126,10 +126,20 @@ export const inputRadioRootRecipe = defineSlotRecipe({
           border: "none",
         },
       },
+      // "none" means no chrome, not no surface: it drops the border and sits
+      // the item on the page's own background. That was written as a literal
+      // `white`, which is the page background of exactly one theme — under a
+      // dark one it painted a white slab, and no theme-aware text colour could
+      // be paired with it (a light `textPrimary` on it is white-on-white, the
+      // same NEH-278 illegibility in the other direction). `boxBgMain` is the
+      // token that means "the page surface", so the variant now follows the
+      // theme instead of contradicting it, and `textMain` is its documented
+      // partner in TEXT_BACKGROUND_PAIRS.
       none: {
         item: {
           border: "none",
-          backgroundColor: "white",
+          backgroundColor: "boxBgMain",
+          color: "textMain",
         },
       },
     },

package/src/preset/recipes/menu.ts

@@ -13,6 +13,15 @@ export const menuRecipe = defineSlotRecipe({
       gap: 3,
       px: 4,
       py: 2,
+      // Stated, not derived — the same reason `button`, `icon-button`,
+      // `input-bool`, `input-radio` and `input-surface` all state it. Height
+      // that emerges from padding plus the current font size moves whenever
+      // either does, and this recipe measured 34px at the default profile.
+      //
+      // A menu is a column of adjacent targets, so missing one does not fail:
+      // it performs the neighbour's action instead. An unexpected navigation
+      // is worse than a dead tap for the audience this system is built for.
+      minHeight: "48px",
       borderRadius: "md",
       cursor: "pointer",
       _hover: {

package/src/preset/recipes/stack.ts

@@ -72,6 +72,13 @@ export const stackRecipe = defineRecipe({
         },
         ghost: {
             bg: "boxBgSecondary",
+            // Found by the new stylesheet guard, not by the NEH-441 sweep that
+            // preceded it — the sweep missed this one, which is the argument
+            // for having a guard rather than a one-off scan. `matte` directly
+            // above paints the identical `boxBgSecondary` and pairs it with
+            // `textSecondary`; this painted the same surface and left its text
+            // to inherit.
+            color: "textSecondary",
             border: "none",
         },
         none: {

package/src/preset/semantic-variables.ts

@@ -39,9 +39,28 @@ const COLOR_TOKENS: TokenMap = {
   textPop: "text-pop-text",
   textError: "text-error-text",
   textWarning: "text-warning-text",
+  // Added NEH-519. The contract could express failure and caution but not
+  // success, so every consumer that needed one improvised — and the obvious
+  // substitute, `textAccent`, is wrong: accent is whatever the host theme sets
+  // it to, with nothing constraining it to read as positive, so a confirmation
+  // could land in an alarming colour. HopperGuard had a live site doing exactly
+  // this dance (an SSO panel reporting "ok" vs error) and had to settle for
+  // neutral text.
+  //
+  // Deliberately NOT in TEXT_BACKGROUND_PAIRS, matching textError and
+  // textWarning: a meaning-carrying colour appears on whatever surface the
+  // message happens to sit on, so there is no single pairing to contrast-check
+  // it against.
+  textSuccess: "text-success-text",
 
   // Text on each surface. Pair these with the matching `boxBg*` — see
   // TEXT_BACKGROUND_PAIRS for which goes with which.
+  //
+  // These are a SURFACE axis, not an emphasis one. `textSecondary` means "text
+  // on the secondary surface"; it does not mean "less important text". Reading
+  // it as the latter is the mistake NEH-519 records — it collapses two
+  // different emphasis levels onto one colour and loses a distinction the UI
+  // meant to draw. De-emphasis is EMPHASIS_TOKENS below.
   textMain: "box-main-text",
   textPrimary: "box-primary-text",
   textSecondary: "box-secondary-text",
@@ -97,6 +116,131 @@ const COLOR_TOKENS: TokenMap = {
   iconBgAccentHover: "icon-accent-hover-bg",
 };
 
+/**
+ * The emphasis axis: how important this text is, on whatever surface it sits.
+ *
+ * The contract had no such axis (NEH-519). It has a *surface* axis — `textMain`
+ * on `boxBgMain`, `textSecondary` on `boxBgSecondary` — and consumers reached
+ * for `textSecondary` when they meant "muted", which is a different question
+ * with a different answer. HopperGuard had a stepper wanting three levels at
+ * once:
+ *
+ * ```tsx
+ * color={active ? "fg" : done ? "fg.muted" : "fg.subtle"}
+ * ```
+ *
+ * and the mapping collapsed "done" and "upcoming" onto one colour, losing a
+ * distinction that UI was drawing on purpose.
+ *
+ * ## The default is relative, which is what makes these adoptable
+ *
+ * Every other colour token is fallback-free by design: an undefined colour
+ * paints an invisible element, a louder and earlier bug than a wrong shade.
+ * That rule is right where "what colour is this?" has no answer without a
+ * theme.
+ *
+ * Emphasis is not that question. "Like the surrounding text, but quieter" has a
+ * correct answer on *every* theme, and `color-mix` states it directly:
+ * `currentColor` inside a `color` declaration resolves to the INHERITED colour
+ * (the property being computed is `color` itself), so the default de-emphasises
+ * whatever the text around it already is — light theme, dark theme, or a host
+ * palette nobody has seen.
+ *
+ * So these follow the font tokens' shape rather than the colours': they carry a
+ * fallback and stay OUT of `requiredCssCustomProperties()`. Putting them there
+ * would fail every existing host for no safety gain, and would move the
+ * `required === fallback-free colours` identity the contract test pins on both
+ * sides. This is the owner direction recorded on NEH-421 — a new token ships
+ * 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
+ *
+ * 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.
+ */
+const EMPHASIS_TOKENS: Record<string, [suffix: string, fallback: string]> = {
+  /** Secondary information: still read, just not first. */
+  textMuted: ["text-muted-text", "color-mix(in srgb, currentColor 78%, transparent)"],
+  /** Furthest back — hints, placeholders, a step not yet reached. */
+  textSubtle: ["text-subtle-text", "color-mix(in srgb, currentColor 64%, transparent)"],
+};
+
+/**
+ * Status SURFACES — the chip an alert or banner is painted on (NEH-421).
+ *
+ * The contract could already say what colour an error *message* is
+ * (`textError`), and had `boxInfo`, but nothing for a warning, error or success
+ * surface. So `StyledAlert` painted all four statuses from the raw palette —
+ * `red.50` / `red.200` / `red.700` and friends — which ignores the theme and
+ * dark mode entirely and sits outside contrast validation. On a dark theme
+ * those render dark text on a light chip regardless of surroundings.
+ *
+ * ## These carry defaults, and status is the reason
+ *
+ * The fallback-free rule is right where "what colour is this?" has no answer
+ * without a theme. **Danger-red, caution-amber and success-green are
+ * near-universal**, so the cost that rule imposes here — an invisible alert in
+ * any host that has not yet defined the property — is real, while the thing it
+ * protects against is not. A product wanting its own says so.
+ *
+ * It also dissolves the two-repo deadlock: without a default the package cannot
+ * add the token (the bump goes red until the hosts adopt) and the hosts cannot
+ * adopt until the bump lands. This is the owner direction recorded on NEH-421.
+ *
+ * ## The defaults are translucent on purpose
+ *
+ * A fixed `#fee2e2` chip is a light-theme chip; on a dark theme it is a glaring
+ * white slab. `color-mix` with `transparent` tints whatever surface the alert
+ * is placed on, so one default reads correctly in both — the same reasoning as
+ * EMPHASIS_TOKENS, applied to a background instead of a foreground.
+ *
+ * The hue is fixed and the *lightness* is not, which is the split that matters:
+ * red has to stay red to mean danger, but how light that red sits has to follow
+ * the page. `alert.ct.tsx` measures the paired text against each chip in both a
+ * light and a dark surrounding and asserts AA.
+ */
+const STATUS_SURFACE_TOKENS: Record<string, [suffix: string, fallback: string]> = {
+  boxSuccess: [
+    "box-success-bg",
+    "color-mix(in srgb, #16a34a 14%, transparent)",
+  ],
+  boxWarning: [
+    "box-warning-bg",
+    "color-mix(in srgb, #d97706 16%, transparent)",
+  ],
+  boxError: ["box-error-bg", "color-mix(in srgb, #dc2626 14%, transparent)"],
+  /**
+   * The border that goes with each chip — the **solid** hue, not a tint of it.
+   *
+   * The fill is deliberately faint, so the border is what makes the alert read
+   * as a container rather than as a colour accident. That means it has to clear
+   * WCAG 1.4.11 (3:1 for a non-text boundary) against the page, and a
+   * translucent border cannot: at 45% these measured **1.72–2.05:1** on a dark
+   * surface, which is the first thing `StyledAlert.ct.tsx` caught.
+   *
+   * A saturated mid-tone hue clears 3:1 at BOTH ends, which is what lets one
+   * value serve a light theme and a dark one without adapting:
+   *
+   * | | vs `#0f172a` | vs `#ffffff` |
+   * |---|---|---|
+   * | `#16a34a` | 4.37 | 3.79 |
+   * | `#d97706` | 4.63 | 3.58 |
+   * | `#dc2626` | 3.20 | 5.18 |
+   *
+   * So these are the one place in this file a bare literal colour is correct.
+   * It is a *hue carrying meaning* — red means danger to everyone — not a
+   * surface colour standing in for a theme, and the numbers above are why it
+   * does not need to follow the page the way the fill does.
+   */
+  borderSuccess: ["box-success-border", "#16a34a"],
+  borderWarning: ["box-warning-border", "#d97706"],
+  borderError: ["box-error-border", "#dc2626"],
+};
+
 /**
  * Host-provided *layout* properties, as `token name → [suffix, fallback]`.
  *
@@ -253,9 +397,35 @@ export function getBackgroundForText(textToken: string): string | undefined {
   return TEXT_BACKGROUND_PAIRS[textToken];
 }
 
-/** Every Panda colour token this preset defines. */
+/**
+ * Every colour token that carries a default, and is therefore NOT required of a
+ * host.
+ *
+ * Two groups with two different justifications, kept separate because their
+ * defaults obey different rules and a test has to be able to say which:
+ * emphasis is relative to the inherited colour, status fixes a hue and leaves
+ * the lightness relative.
+ */
+const DEFAULTED_COLOR_TOKENS = { ...EMPHASIS_TOKENS, ...STATUS_SURFACE_TOKENS };
+
+/** Every Panda colour token this preset defines, defaulted ones included. */
 export function colorTokenNames(): string[] {
-  return Object.keys(COLOR_TOKENS);
+  return [...Object.keys(COLOR_TOKENS), ...Object.keys(DEFAULTED_COLOR_TOKENS)];
+}
+
+/** The de-emphasis tiers, which carry a fallback and are not required of a host. */
+export function emphasisTokenNames(): string[] {
+  return Object.keys(EMPHASIS_TOKENS);
+}
+
+/** The status chips and their borders, which also carry a fallback. */
+export function statusSurfaceTokenNames(): string[] {
+  return Object.keys(STATUS_SURFACE_TOKENS);
+}
+
+/** Every colour token a host may leave undefined. */
+export function defaultedColorTokenNames(): string[] {
+  return Object.keys(DEFAULTED_COLOR_TOKENS);
 }
 
 /**
@@ -270,14 +440,25 @@ export function requiredCssCustomProperties(
   return Object.values(COLOR_TOKENS).map((suffix) => `--${prefix}-${suffix}`);
 }
 
-/** Panda colour-token definitions, bound to a custom-property prefix. */
+/**
+ * Panda colour-token definitions, bound to a custom-property prefix.
+ *
+ * Two shapes in one map, deliberately: the surface and meaning colours emit a
+ * bare `var(…)` with no fallback, while the emphasis tiers and the status chips
+ * emit `var(…, <default>)`. See `COLOR_TOKENS`, `EMPHASIS_TOKENS` and
+ * `STATUS_SURFACE_TOKENS` for why each asymmetry is correct rather than an
+ * oversight.
+ */
 export function createSemanticColors(
   prefix: string = DEFAULT_CSS_VAR_PREFIX,
 ): Record<string, { value: string }> {
-  return Object.fromEntries(
-    Object.entries(COLOR_TOKENS).map(([token, suffix]) => [
-      token,
-      { value: `var(--${prefix}-${suffix})` },
-    ]),
-  );
+  return {
+    ...Object.fromEntries(
+      Object.entries(COLOR_TOKENS).map(([token, suffix]) => [
+        token,
+        { value: `var(--${prefix}-${suffix})` },
+      ]),
+    ),
+    ...createFallbackTokens(DEFAULTED_COLOR_TOKENS, prefix),
+  };
 }