@stonedogcode/style 0.10.1 → 0.13.0

package/src/config/link-component.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import React from "react";
+
+/**
+ * The props any link implementation must accept.
+ *
+ * Deliberately the native anchor's own surface plus a required `href`. That is
+ * not a compromise to keep the type simple — it is the boundary. A router's
+ * link component accepts these and adds its own (prefetch, scroll, replace);
+ * this package neither knows nor passes those, so the extra props stay the
+ * host's business and no routing concept leaks in here.
+ *
+ * `href` is a `string`, not `string | UrlObject`. Next.js accepts the object
+ * form, but naming it here would put a Next.js type in a package whose whole
+ * premise is that it has none — and a host that wants the object form can wrap
+ * its own component and take it there, which is exactly what the seam is for.
+ */
+export interface LinkComponentProps
+  extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  href: string;
+  children?: React.ReactNode;
+}
+
+/**
+ * What `StyledLink` renders for an in-app destination.
+ *
+ * A host swaps in its router's link — `next/link`, `react-router`'s `Link`,
+ * whatever it has — and gets client-side navigation and prefetching. A host
+ * that says nothing gets `DefaultLinkComponent` below.
+ *
+ * Typed as a component rather than an `ElementType` union so the intrinsic
+ * `"a"` string is not a valid value. Allowing it would mean two ways to say the
+ * same thing, and the one that looks simpler is the one that cannot be given a
+ * `displayName` or wrapped.
+ *
+ * **It must forward its ref to the underlying anchor.** `RefAttributes` is in
+ * the props type rather than left implicit because this package's peer range
+ * starts at React 18, where a `ref` handed to a plain function component is not
+ * a prop — React 18 drops it and logs "Function components cannot be given
+ * refs". Stating it in the type is what makes that a compile error for the host
+ * instead of a console warning nobody reads. `next/link` and react-router's
+ * `Link` both forward already, so the common cases need nothing.
+ */
+export type LinkComponent = React.ComponentType<
+  LinkComponentProps & React.RefAttributes<HTMLAnchorElement>
+>;
+
+/**
+ * A plain anchor, and the reason this seam is safe to leave unconfigured.
+ *
+ * This is the point of the whole arrangement (NEH-430): the default is not a
+ * placeholder that throws, warns, or renders nothing until someone wires a
+ * router. It is a **real, correct, accessible link** — it navigates, it opens in
+ * a new tab when told to, middle-click and "open in new window" work, and a
+ * screen reader announces it as a link. What a host gains by overriding is
+ * client-side navigation and prefetching: real benefits, and neither of them
+ * load-bearing for the link *working*.
+ *
+ * A seam whose default is broken is a required configuration step wearing a
+ * disguise, and it recreates exactly the adoption deadlock this issue set out
+ * to remove.
+ */
+export const DefaultLinkComponent: LinkComponent = React.forwardRef<
+  HTMLAnchorElement,
+  LinkComponentProps
+>(function DefaultLinkComponent(props, ref) {
+  return <a ref={ref} {...props} />;
+}) as LinkComponent;

package/src/config/style-config.tsx

@@ -5,6 +5,7 @@ import type { DensityProfile, FontSizeProfile, IconSize, ThemeVariant } from "./
 import { resolveDensityStep, type DensityBase, type DensityStep } from "./density";
 import { THEME_VARIANTS } from "./types";
 import { IntentIconProvider, type IntentIcons } from "./intent-icons";
+import { DefaultLinkComponent, type LinkComponent } from "./link-component";
 
 /**
  * Everything this component library needs to know about the host application.
@@ -69,6 +70,26 @@ export interface StyleConfig {
    * (a business tool for a general audience) sets `"md"`.
    */
   iconSize: IconSize;
+
+  /**
+   * What `StyledLink` renders for an in-app destination (NEH-430).
+   *
+   * This is a seam, not a dependency. `StyledLink` used to import `next/link`
+   * directly, which is why it could not live in this package at all — CLAUDE.md
+   * names `next/*` as forbidden, and three products with three framework
+   * choices cannot be made to share one.
+   *
+   * The default is a plain `<a>`: a real, working, accessible link, not a
+   * placeholder. A host passes its router's component to gain client-side
+   * navigation and prefetching, and gains nothing else — so an unconfigured
+   * host is not broken, merely un-optimised.
+   *
+   * Note this is the only field here whose value is a *component*. It sits on
+   * `StyleConfig` rather than being a `StyledLink` prop because the choice is
+   * app-wide by nature: passing it per call site is how ~40 links end up with
+   * two navigation behaviours and no way to retune either.
+   */
+  linkComponent: LinkComponent;
 }
 
 /**
@@ -91,6 +112,10 @@ export const DEFAULT_STYLE_CONFIG: StyleConfig = {
   // what the originating application already renders. Changing it would be an
   // invisible, app-wide visual change to every existing consumer.
   iconSize: "2x",
+  // A plain anchor. Unlike `iconSize` above this is genuinely the safe middle:
+  // it navigates correctly everywhere, and a host overriding it is opting into
+  // an improvement rather than repairing a default.
+  linkComponent: DefaultLinkComponent,
 };
 
 const StyleConfigContext = createContext<StyleConfig>(DEFAULT_STYLE_CONFIG);
@@ -143,6 +168,7 @@ export function StonedogStyleProvider({
   iconSize,
   density,
   densityBase,
+  linkComponent,
   icons,
 }: StonedogStyleProviderProps) {
   const value = useMemo<StyleConfig>(
@@ -153,8 +179,9 @@ export function StonedogStyleProvider({
       iconSize: iconSize ?? DEFAULT_STYLE_CONFIG.iconSize,
       density: density ?? DEFAULT_STYLE_CONFIG.density,
       densityBase: densityBase ?? DEFAULT_STYLE_CONFIG.densityBase,
+      linkComponent: linkComponent ?? DEFAULT_STYLE_CONFIG.linkComponent,
     }),
-    [fontSizeProfile, variant, iconSize, density, densityBase],
+    [fontSizeProfile, variant, iconSize, density, densityBase, linkComponent],
   );
 
   return (
@@ -196,6 +223,17 @@ export function useIconSize(): IconSize {
   return useStyleConfig().iconSize;
 }
 
+/**
+ * The host's link implementation, or a plain `<a>` if it supplied none.
+ *
+ * Exported so an application component outside this package can render a link
+ * the same way `StyledLink` does, without reaching for the router directly and
+ * re-creating the coupling the seam removed.
+ */
+export function useLinkComponent(): LinkComponent {
+  return useStyleConfig().linkComponent;
+}
+
 /**
  * Resolve a control's appearance: **the caller's, else the user's app-wide
  * setting, else `solid`.**

package/src/index.ts

@@ -20,6 +20,7 @@ export {
   useStyleConfig,
   useFontSizeProfile,
   useIconSize,
+  useLinkComponent,
   useResolvedVariant,
   DEFAULT_STYLE_CONFIG,
 } from "./config/style-config";
@@ -28,6 +29,10 @@ export type {
   StonedogStyleProviderProps,
 } from "./config/style-config";
 
+/** The link seam — see `config/link-component.tsx` and NEH-430. */
+export { DefaultLinkComponent } from "./config/link-component";
+export type { LinkComponent, LinkComponentProps } from "./config/link-component";
+
 /**
  * Deprecated `Hopper*` aliases — NEH-251. See `config/style-config.tsx`.
  * Removed once every consumer has landed its rename PR.
@@ -192,6 +197,43 @@ export type { StyledTooltipProps } from "./components/StyledTooltip";
 export { default as StyledFormLabel } from "./components/StyledFormLabel";
 export type { StyledFormLabelProps } from "./components/StyledFormLabel";
 
+// ---------------------------------------------------------------------------
+// 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
+// supplies the framework-specific half, or takes the default and loses nothing
+// that stops it working.
+// ---------------------------------------------------------------------------
+export { default as StyledLink, StyledLink as Link } from "./components/StyledLink";
+export type { StyledLinkProps } from "./components/StyledLink";
+
+export { default as StyledTag, StyledTag as Tag } from "./components/StyledTag";
+export type { StyledTagProps } from "./components/StyledTag";
+
+export {
+  default as StyledFieldErrors,
+  StyledFieldErrors as FieldErrors,
+} from "./components/StyledFieldErrors";
+export type {
+  StyledFieldErrorsProps,
+  FieldError,
+} from "./components/StyledFieldErrors";
+
+export { default as StyledPage, StyledPage as Page } from "./components/StyledPage";
+export type { StyledPageProps } from "./components/StyledPage";
+
+export { default as StyledForm, StyledForm as Form } from "./components/StyledForm";
+export type { StyledFormProps } from "./components/StyledForm";
+
+export {
+  default as StyledConfetti,
+  StyledConfetti as Confetti,
+} from "./components/StyledConfetti";
+export type {
+  StyledConfettiProps,
+  CelebrateFn,
+  CelebrateOptions,
+} from "./components/StyledConfetti";
+
 export { default as StyledInputBool } from "./components/StyledInputBool";
 export type { StyledInputBoolProps, InputBoolVariant } from "./components/StyledInputBool";
 export { INPUT_BOOL_VARIANTS } from "./components/StyledInputBool";
@@ -229,6 +271,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,
@@ -193,6 +195,34 @@ export function stonedogStylePreset(options: StonedogStylePresetOptions = {}) {
             "0%": { transform: "scaleX(0)" },
             "100%": { transform: "scaleX(1)" },
           },
+          /**
+           * One confetti particle's flight — `StyledConfetti`'s zero-dependency
+           * default (NEH-430).
+           *
+           * The three `--sd-confetti-*` properties are set inline, per
+           * particle, so one keyframe serves a whole burst travelling in every
+           * direction. A keyframe cannot randomise, and a hundred generated
+           * keyframes would be a hundred rules in every consumer's stylesheet.
+           *
+           * **These are NOT the theme namespace and must not be confused with
+           * it.** CLAUDE.md's rule — never write `var(--…)` for anything the
+           * HOST supplies — is about `--<prefix>-*` properties that a theme
+           * defines and `cssVarPrefix` re-points. These are component-internal,
+           * written and read in the same breath by the same component, and
+           * named `--sd-confetti-*` precisely so they cannot collide with a
+           * host's namespace. The particle's COLOUR still comes from a token.
+           */
+          stonedogConfettiBurst: {
+            "0%": {
+              transform: "translate3d(0, 0, 0) rotate(0deg)",
+              opacity: "1",
+            },
+            "100%": {
+              transform:
+                "translate3d(var(--sd-confetti-dx, 0), var(--sd-confetti-dy, 0), 0) rotate(var(--sd-confetti-rot, 0deg))",
+              opacity: "0",
+            },
+          },
         },
         recipes,
       },

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-bool.ts

@@ -24,9 +24,16 @@ export const inputBoolRecipe = defineSlotRecipe({
        * Verified in the component-test harness rather than assumed: a raw
        * checkbox given a red 2px border and a slate background paints as the
        * default white box. The UA draws the widget and discards
-       * `background-color`, `border-*` and `border-radius` — while
-       * `getComputedStyle` cheerfully reports all of them, which is what made
-       * this recipe look styled for so long.
+       * `background-color` and `border-*` — while `getComputedStyle`
+       * cheerfully reports both, which is what made this recipe look styled
+       * for so long.
+       *
+       * `border-radius` is worse still and worth separating out (NEH-310): it
+       * does not even COMPUTE. A control set to `9999px` reports `0px`, so it
+       * cannot be asserted on, cannot be differed by, and is not merely
+       * invisible. The `borderRadius: "md"` below is therefore inert too; it is
+       * kept only because it belongs to the same `appearance: none` fallback
+       * set as `border` and `background-color`.
        *
        * The three it DOES honour, and therefore the only levers here:
        * `accent-color` (the checked fill and tick), `box-shadow` (painted
@@ -77,9 +84,21 @@ export const inputBoolRecipe = defineSlotRecipe({
        *
        * `buttonRecipe` expresses outline as a 2px edge with squared corners.
        * A native checkbox discards `border`, so the same reading is carried by
-       * a `box-shadow` ring, which it does paint — squared to match, and
-       * themed. `solid` states `none` explicitly rather than by omission, so
-       * switching between them cannot leave a ring behind.
+       * a `box-shadow` ring, which it does paint — themed. `solid` states
+       * `none` explicitly rather than by omission, so switching between them
+       * cannot leave a ring behind.
+       *
+       * **The squared corners were dropped in NEH-310, because they never
+       * existed.** This comment used to say the ring was "squared to match",
+       * and the variant carried `borderRadius: "0"` to do it. Probed in the
+       * harness: Chromium computes `border-radius: 0px` on a checkbox at
+       * `appearance: auto` **whatever the stylesheet says** — a control set to
+       * `9999px` reports `0px`, while a plain `<span>` beside it reports its
+       * `12px` correctly. So the property is not merely discarded at paint
+       * time like `background-color`; it does not even compute, and no variant
+       * here can differ by corner. The declaration is removed rather than left
+       * as decoration, since a recipe full of inert declarations is the exact
+       * condition that made this defect take three issues to find.
        */
       solid: {
         control: {
@@ -100,18 +119,60 @@ export const inputBoolRecipe = defineSlotRecipe({
            * different — and made a ticked outline checkbox a dark box on a dark
            * surface, which is the checked state, the one thing the control
            * exists to communicate. Distinguishing an appearance must not cost
-           * state legibility, so the difference is carried entirely by the ring
-           * and the corners.
+           * state legibility, so the difference is carried entirely by the
+           * ring.
            */
           accentColor: "buttonBgPrimary",
           boxShadow: "0 0 0 2px {colors.borderBgPrimary}",
-          borderRadius: "0",
         },
       },
+      /**
+       * The remaining variants, given a painted difference (NEH-310).
+       *
+       * NEH-234 fixed `solid` vs `outline` and stopped there, so these still
+       * differed only in `background`, `background-image`, `color` and a
+       * pseudo-element — every one of which this control discards. A user
+       * picking `aurora` app-wide watched every other control change and every
+       * checkbox stay put: the same complaint NEH-234 was filed for, one layer
+       * down.
+       *
+       * ## The rule they all follow
+       *
+       * **Appearance is carried by the ring; the checked colour never varies.**
+       *
+       * Not a stylistic choice — it is the lesson recorded on `outline` above.
+       * Giving a variant a recessive `accentColor` did make it more distinct,
+       * and made a ticked box dark-on-dark: illegible in the one state the
+       * control exists to communicate. So every variant keeps
+       * `accentColor: buttonBgPrimary` and differs by `box-shadow` alone.
+       *
+       * `outline` (the CSS property) is not available as a lever either: it is
+       * the focus ring, and a variant using it would look permanently focused.
+       * `border-radius` is not available because it does not even COMPUTE here
+       * — see the note on the `outline` variant.
+       *
+       * ## What this deliberately does NOT attempt
+       *
+       * `aurora` is a gradient and `glass` is a blur; a box-shadow ring is
+       * neither. These are **approximations** — a two-tone ring, a soft halo —
+       * not renderings of the intent. The real thing needs `appearance: none`
+       * plus a hand-drawn tick, which means owning forced-colors mode and every
+       * engine's default widget, and this repo's CT tier is Chromium-only so it
+       * cannot answer that. NEH-310 names it as option 2 and says it needs
+       * someone to look at the result in more than one engine.
+       *
+       * The unpainted `bg` / `color` / gradient declarations are left exactly
+       * as they were, per the note in `base`.
+       */
       aurora: {
         control: {
           backgroundImage: "linear-gradient(to right, #ff7e5f, #feb47b)",
           color: "buttonTextPrimary",
+          accentColor: "buttonBgPrimary",
+          // Two stops, two rings — the nearest a box-shadow gets to the
+          // gradient this variant means. Layers paint inner-first.
+          boxShadow:
+            "0 0 0 2px {colors.borderBgAccent}, 0 0 0 4px {colors.borderBgPrimary}",
         },
       },
       glass: {
@@ -120,7 +181,6 @@ export const inputBoolRecipe = defineSlotRecipe({
           overflow: "hidden",
           bg: "buttonBgPrimary/20",
           color: "textPrimary/10",
-          boxShadow: "xl",
           backdropFilter: "blur(8px)",
           fontWeight: "bold",
           lineHeight: "shorter",
@@ -135,6 +195,19 @@ export const inputBoolRecipe = defineSlotRecipe({
               "linear(to-br, rgba(255,255,255,0.1), rgba(255,255,255,0.05))",
             zIndex: -1,
           },
+          accentColor: "buttonBgPrimary",
+          // A soft halo rather than a hard edge — the nearest painted reading
+          // of "frosted".
+          //
+          // This REPLACES the `boxShadow: "xl"` this variant used to carry
+          // (removed above, not shadowed — a second `boxShadow` key here was a
+          // TS1117 duplicate-property error that the CSS build silently
+          // resolved in favour of the last one). `xl` was the only thing glass
+          // ever painted, and it is Panda's own neutral shadow: the same grey
+          // in every theme this package can wear, which is the one thing a
+          // themeable package must not ship.
+          boxShadow:
+            "0 0 0 1px {colors.borderBgSecondary}, 0 0 12px 2px {colors.boxshadowBgAccent}",
         },
       },
       matte: {
@@ -145,18 +218,46 @@ export const inputBoolRecipe = defineSlotRecipe({
           // is a FIXED dark gradient, so themed text on it risks dark-on-dark.
           color: "white",
           fontWeight: "bold",
+          accentColor: "buttonBgPrimary",
+          // Wide, blurred and low-contrast: a matte surface absorbs light
+          // rather than edging it. The only soft-edged ring in the set, so it
+          // cannot be mistaken for `outline` at a glance.
+          boxShadow: "0 2px 8px 0 {colors.boxshadowBgSecondary}",
         },
       },
       ghost: {
         control: {
           color: "textSecondary",
           bg: "buttonBgSecondary",
+          accentColor: "buttonBgPrimary",
+          // The thinnest ring in the set, in the secondary border colour.
+          // `ghost` means "present but not asserting itself", which every other
+          // recipe expresses by having no fill — exactly the property this
+          // control discards.
+          boxShadow: "0 0 0 1px {colors.borderBgSecondary}",
         },
       },
+      /**
+       * `none` is the one variant that CANNOT be distinguished, and saying so
+       * is more useful than inventing a difference (NEH-310).
+       *
+       * Every lever this control has is additive — a ring, a halo, a checked
+       * colour. `none` means "do not style this", so the only honest rendering
+       * of it is the bare widget, which is what `solid` already is. Giving it a
+       * ring to make a test pass would mean the variant named `none` was the
+       * only one wearing decoration.
+       *
+       * So `none` and `solid` render identically, deliberately, and the
+       * component test asserts that pair is equal rather than skipping it —
+       * so if a future `appearance: none` redesign (option 2 on NEH-310) makes
+       * them separable, the test says so instead of quietly passing.
+       */
       none: {
         control: {
           color: "buttonTextPrimary",
           bg: "gray.300",
+          accentColor: "buttonBgPrimary",
+          boxShadow: "none",
         },
       },
       button: {

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: {