@stonedogcode/style 0.15.0 → 0.17.0

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

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

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

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

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

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

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

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

package/src/preset/recipes/list.ts

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

package/src/preset/recipes/tooltip.ts

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

package/src/preset/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. */

package/src/preset/z-layers.ts

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