@stonedogcode/style 0.10.1 → 0.13.0

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),
+  };
 }