@stonedogcode/style 0.20.1 → 0.20.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "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.",
@@ -48,6 +48,9 @@
     "gate": "npm run type-check && npm run lint && npm run test",
     "//publish:stonedog-style": "Publish to npm, end to end. Run from a terminal, interactively — npm prompts for the 2FA one-time password and the login flow needs a browser. It refuses a checkout that is detached, dirty, or behind origin/main: a submodule sits detached at the consumer's gitlink by default, and publishing from one commit behind ships a tarball missing the very thing you are publishing for while looking like a success (it did, on 2026-08-04, without TitleLogo.tsx). Runs the gate, prints the tarball listing, then proves the result by installing from the registry into a temp directory.",
     "publish:stonedog-style": "bash scripts/publish-package.sh",
+    "publishnpm": "npm run publish:stonedog-style",
+    "//release": "One memorable command per repo. It cannot be called `publish`: that is a reserved npm lifecycle name, so `npm publish` inside scripts/publish-package.sh would fire it and run the whole gate and publish a second time, hitting the already-published guard and reporting a successful release as a failure.",
+    "release": "npm run publish:stonedog-style",
     "version:bump:patch": "npm version patch --no-git-tag-version",
     "version:bump:minor": "npm version minor --no-git-tag-version",
     "audit": "npm audit --audit-level=moderate"

package/src/components/StyledHeading.tsx

@@ -1,3 +1,30 @@
+"use client";
+
+/**
+ * `"use client"`, and it is load-bearing.
+ *
+ * This component calls `useFontSizeProfile()` (a client hook) during its
+ * render. Without the directive above, the module is a Server Component in a
+ * consumer's App Router tree, the hook is invoked on the server, and React
+ * throws:
+ *
+ *     Attempted to call useFontSizeProfile() from the server but
+ *     useFontSizeProfile is on the client.
+ *
+ * Next serves that as its blank "This page couldn't load" page with no detail
+ * anywhere in the browser, so a consumer sees a dead route and nothing naming
+ * this component. Every PRD and how-to page on stonedogcode.com was unreachable
+ * this way (NEH-1290).
+ *
+ * Every other component here that calls the hook already declared it — this was
+ * the only one that did not, which is why the failure looked like something
+ * specific to whichever page happened to render a heading on the server.
+ *
+ * `src/components/__tests__/client-directive.test.ts` keeps this honest. It has
+ * to be a source assertion: a jsdom render imports the module directly, so no
+ * RSC boundary exists and every test here passes with or without the directive.
+ */
+
 import React from "react";
 import StyledSeparator from "./StyledSeparator";
 import StyledText from "./StyledText";

package/src/preset/recipes/button.ts

@@ -133,13 +133,24 @@ export const buttonRecipe = defineRecipe({
           pointerEvents: "none",
         },
       },
+      /**
+       * The same correction `iconButton`'s `matte` takes, for the same reason
+       * (NEH-881) — see the long note there.
+       *
+       * NEH-881 named only `iconButton`. These two recipes are the same control
+       * in two shapes and their `matte` blocks were byte-identical, including
+       * the inert `bgGradient` that kept the pairing guard from inspecting
+       * either of them. Fixing one and leaving the other would ship the defect
+       * under a different class name, so both move together: the same 8-of-18
+       * measurement applies unchanged, because it is a property of the surface
+       * and the text token, not of the shape of the control.
+       */
       matte: {
-        bgGradient: "linear(to-b, gray.800, gray.900)",
         borderColor: "gray.700",
         borderWidth: "1px",
         boxShadow: "md",
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        color: "buttonTextAccent",
         borderRadius: "lg",
         fontWeight: "bold",
       },

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

@@ -155,13 +155,50 @@ export const buttonIconRecipe = defineRecipe({
           pointerEvents: "none",
         },
       },
+      /**
+       * The accent pairing again, and the gradient that was hiding it
+       * (NEH-881).
+       *
+       * This variant was filed as a different defect class: a FIXED dark
+       * `gray.800`→`gray.900` gradient painting over the accent fill in every
+       * theme, with a themed `textPrimary` glyph left dark-on-dark on top of
+       * it. The proposed fix was a deliberate literal `color: "white"`, as
+       * `box` and `input-bool` had already taken for their own `matte`.
+       *
+       * **There is no gradient.** `bgGradient` is Chakra v2 syntax; Panda has
+       * no such utility and no `linear()` shorthand, so it emitted
+       * `background-image: linear(to-b, gray.800, gray.900)` — not valid CSS,
+       * discarded at parse time by every engine. Chromium reads the element
+       * back as `background-image: none`, and the `background` shorthand
+       * emitted just above it had already reset `background-image` in any case.
+       *
+       * So the surface here has always been plain `buttonBgAccent`, and this is
+       * the ordinary NEH-796 / NEH-877 mispairing after all — `textPrimary` is
+       * the contract's partner for `boxBgPrimary`, not for an accent fill.
+       * Measured over nine host themes in both modes, 18 pairs: `textPrimary`
+       * is below WCAG AA on 8 of them, every one in dark mode, the worst at
+       * 2.15:1 (white on `#F59E0B`). `buttonTextAccent` is below AA on 0 of the
+       * 18, and reaches 9.78:1 on that same worst pair.
+       *
+       * Had `color: "white"` been taken as filed, it would have pinned the
+       * failing half of that measurement in place under a comment calling it
+       * deliberate — the shape where a test makes a bug unfixable by review.
+       *
+       * The dead declaration goes too, and that is not tidying. The pairing
+       * sweep in `variant-contrast-pairing.test.ts` reads `background-image`
+       * before `background`, so while the invalid gradient was emitted the
+       * guard took it as this variant's surface, found the token contract said
+       * nothing about it, and skipped the variant entirely. Removing it is what
+       * puts `matte` back under the guard that already covers its five
+       * siblings — verified by planting the old colour back and watching that
+       * guard name both selectors.
+       */
       matte: {
-        bgGradient: "linear(to-b, gray.800, gray.900)",
         borderColor: "gray.700",
         borderWidth: "1px",
         boxShadow: "md",
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        color: "buttonTextAccent",
         borderRadius: "lg",
         fontWeight: "bold",
       },