@stonedogcode/style 0.13.0 → 0.16.0

package/src/preset/index.ts

@@ -25,6 +25,7 @@ import {
 } from "./recipes/separator";
 import { stackRecipe } from "./recipes/stack";
 import { stripedRecipe } from "./recipes/striped";
+import { tagRecipe } from "./recipes/tag";
 import { textRecipe } from "./recipes/text";
 import { tooltipRecipe } from "./recipes/tooltip";
 
@@ -35,6 +36,7 @@ import {
   createSemanticFonts,
   createSemanticSizes,
 } from "./semantic-variables";
+import { createZIndexTokens } from "./z-layers";
 
 export interface StonedogStylePresetOptions {
   /**
@@ -83,6 +85,7 @@ const recipes = {
   separatorVerticalRecipe,
   stackRecipe,
   stripedRecipe,
+  tagRecipe,
   textRecipe,
   tooltipRecipe,
 };
@@ -135,7 +138,7 @@ const staticCssAlignment = [
 
 /**
  * The @stonedogcode/style Panda preset: colour tokens, breakpoints, keyframes, and
- * the 22 recipes the component library is built on.
+ * the 23 recipes the component library is built on.
  *
  * Deliberately does NOT set `globalCss`, `preflight`, `include`, or `outdir` —
  * those are application decisions, and a preset that quietly restyles `body` is
@@ -182,6 +185,19 @@ export function stonedogStylePreset(options: StonedogStylePresetOptions = {}) {
            */
           fonts: createSemanticFonts(cssVarPrefix),
           fontWeights: createSemanticFontWeights(cssVarPrefix),
+          /**
+           * Named stacking layers (NEH-830). Neither this preset nor either
+           * base Panda preset defined any, so `drawerRecipe`'s `zIndex:
+           * "modal"` resolved to nothing and was emitted as the literal
+           * `z-index: modal` — invalid CSS the browser discards, leaving that
+           * panel with no z-index at all.
+           *
+           * Unlike the colour tokens these carry no custom property: a layer
+           * is not a brand decision and there is nothing for a theme to
+           * restyle. A HOST overrides the numbers in its own config; see
+           * z-layers.ts for why the names live here and the values do not.
+           */
+          zIndex: createZIndexTokens(),
         },
         keyframes: {
           spin: {
@@ -248,6 +264,13 @@ export {
   requiredCssCustomProperties,
 } from "./semantic-variables";
 
+export {
+  Z_LAYERS,
+  createZIndexTokens,
+  zIndexTokenNames,
+  type ZLayerName,
+} from "./z-layers";
+
 export { recipes as stonedogStyleRecipes };
 
 /* ------------------------------------------------------------------------- *

package/src/preset/recipes/button.ts

@@ -37,10 +37,20 @@ export const buttonRecipe = defineRecipe({
     variant: {
       solid: {
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        // The same pairing `outline` states below, and for the same reason
+        // (NEH-441, NEH-796). `textPrimary` is the colour that goes on
+        // `boxBgPrimary`, not on an accent surface: against optima's light
+        // theme that pairing measures 2.43:1, below WCAG AA, while
+        // `buttonTextAccent` measures 7.34:1. The dark theme happens to
+        // survive it, which is what let a default variant ship unreadable.
+        //
+        // `TEXT_BACKGROUND_PAIRS` in `semantic-variables.ts` is the contract
+        // being obeyed: `buttonTextAccent` sits on `buttonBgAccent`, and
+        // `buttonTextSecondary` on the `buttonBgSecondary` the hover repaints.
+        color: "buttonTextAccent",
         _hover: {
           bg: "buttonBgSecondary",
-          color: "textPrimary",
+          color: "buttonTextSecondary",
         },
       },
       outline: {
@@ -77,7 +87,15 @@ export const buttonRecipe = defineRecipe({
         border: "2px solid",
         borderRadius: "xl",
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        // The same correction `solid` took in NEH-796, which this variant was
+        // missed by twice over (NEH-877): the pairing sweep that landed with it
+        // was scoped to this recipe, but it also skipped every variant named
+        // `glass` — on the reasoning that a translucent surface should inherit.
+        // This one is not translucent. It paints an opaque `buttonBgAccent` and
+        // blurs what is BEHIND it, so it owes a paired foreground like any
+        // other accent surface: 2.43:1 with `textPrimary` against optima's
+        // light theme, 7.34:1 with this.
+        color: "buttonTextAccent",
         boxShadow: "0 8px 32px rgba(0,0,0,0.2)",
         backdropFilter: "blur(12px)",
         WebkitBackdropFilter: "blur(12px)",
@@ -86,6 +104,13 @@ export const buttonRecipe = defineRecipe({
         transition: "all 0.3s ease",
         _hover: {
           bg: "buttonBgSecondary",
+          // Stated, because the hover repaints a DIFFERENT surface (NEH-877).
+          // Without it the label rides its base `buttonTextAccent` onto a
+          // secondary background — 1.06:1 in optima's light theme, white on
+          // near-white, i.e. the label vanishing on hover. This is the same
+          // move `solid` made in NEH-796 and the reason a base-colour fix has
+          // to look at every pseudo-state that repaints beneath it.
+          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)",
@@ -126,7 +151,12 @@ export const buttonRecipe = defineRecipe({
         },
       },
       selected: {
-        color: "textPrimary",
+        // `textAccent`, not `textPrimary` — the same mispairing `solid` had
+        // (NEH-796). `boxBgAccent` is an accent surface and the contract's
+        // partner for it is `textAccent`; `textPrimary` is the colour for
+        // `boxBgPrimary`, a different surface. Adjacent instance of the defect
+        // the issue names, in the same recipe, so it is fixed here.
+        color: "textAccent",
         border: "3px dashed black",
         borderRadius: "xl",
         bg: "boxBgAccent",

package/src/preset/recipes/form.ts

@@ -15,7 +15,12 @@ export const formRecipe = defineRecipe({
     variant: {
       solid: {
         bg: "boxBgAccent",
-        color: "textPrimary",
+        // `textAccent`, not `textPrimary` (NEH-877). `textPrimary` is the
+        // contract's partner for `boxBgPrimary`, a different surface: against
+        // optima's light theme, whose accent surface is a near-black graphite,
+        // that pairing measures 1.17:1 — a form whose every label is the exact
+        // colour of the panel behind it. `textAccent` measures 15.27:1.
+        color: "textAccent",
         borderColor: "borderBgPrimary",
         "& > li:not(:last-child)": {
           borderBottom: "1px solid",

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

@@ -0,0 +1,96 @@
+import { defineRecipe } from "@pandacss/dev";
+
+/**
+ * A small label, in one of six tones.
+ *
+ * ## Why this is a recipe and not `css()` in the component
+ *
+ * `StyledTag` painted itself with an inline `css()` call, which was right while
+ * it had exactly one appearance. A tone chosen at runtime is a different
+ * problem: Panda's extractor reads source text, so `tone={STATUS_COLOR[status]}`
+ * resolves to nothing and emits no rule — while the class name still lands in
+ * the DOM. The result is an unstyled tag, with no build error and no console
+ * warning.
+ *
+ * Recipes are the escape from that, because `staticCssRecipes` in
+ * `preset/index.ts` forces **every variant of every recipe** into the
+ * stylesheet. So a tone computed from a status map is covered for free, which is
+ * how the consuming apps actually use this (NEH-721: HopperGuard drives 109 of
+ * its 155 tags from `STATUS_COLOR[item.status]` and friends).
+ *
+ * ## The tones reuse StyledAlert's vocabulary exactly
+ *
+ * `info` / `success` / `warning` / `error` are `AlertStatus`, and each pairs the
+ * **same tokens** the alert recipe pairs. Two status vocabularies in one package
+ * — one for banners and a different one for tags — is how a product ends up with
+ * a green that means "success" in one place and "active" in another.
+ *
+ * Two tones are additional rather than borrowed:
+ *
+ * - **`neutral`** is the historical default and stays the default, so every
+ *   existing call site renders exactly as it did before this variant existed.
+ * - **`accent`** has no alert equivalent, because an alert is always *about*
+ *   something being fine or not. A tag is often just a category — a label, a
+ *   type, a group — and forcing those into `info` would make "informational"
+ *   mean nothing.
+ *
+ * ## No border, unlike the alert
+ *
+ * The alert recipe pairs each background with a `border*` token. A tag is small
+ * and usually appears in groups; a 1px edge on each turns a row of five into
+ * visual noise, and the tinted background already separates it from the page.
+ * The border tokens stay available if a consumer disagrees.
+ */
+export const tagRecipe = defineRecipe({
+  className: "tag",
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: "1",
+    paddingInline: "2",
+    /*
+     * Vertical padding is deliberately absent: the height comes from the line
+     * box and the horizontal padding, so a tag tracks the font scale instead of
+     * needing a re-tune whenever it moves.
+     */
+    borderRadius: "md",
+    /*
+     * Not a tap target. A plain tag is not interactive, so the 48px floor does
+     * not apply to it — the remove BUTTON inside `StyledTag` is, and states its
+     * own.
+     */
+    fontSize: "sm",
+    whiteSpace: "nowrap",
+  },
+  variants: {
+    tone: {
+      neutral: {
+        backgroundColor: "boxBgSecondary",
+        color: "textSecondary",
+      },
+      info: {
+        backgroundColor: "boxInfo",
+        color: "textMain",
+      },
+      success: {
+        backgroundColor: "boxSuccess",
+        color: "textSuccess",
+      },
+      warning: {
+        backgroundColor: "boxWarning",
+        color: "textWarning",
+      },
+      error: {
+        backgroundColor: "boxError",
+        color: "textError",
+      },
+      accent: {
+        backgroundColor: "boxBgAccent",
+        color: "textMain",
+      },
+    },
+  },
+  defaultVariants: {
+    tone: "neutral",
+  },
+});

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",
       },
     },
   },