ngwr 9.1.0 → 10.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngwr",
-  "version": "9.1.0",
+  "version": "10.0.0",
   "license": "MIT",
   "description": "Signals-first Angular UI library: 100+ standalone, zoneless-ready components with native Signal Forms, SSR-safe rendering and CSS-variable theming.",
   "author": "Roman Khegay <rk@garuna.dev> (https://garuna.dev)",
@@ -68,6 +68,8 @@
     "migrations": "./schematics/migrations.json"
   },
   "exports": {
+    "./schematics/*": "./schematics/*",
+    "./i18n/*.json": "./i18n/*.json",
     ".": {
       "sass": "./styles.scss",
       "types": "./types/ngwr.d.ts",

package/pagination/styles/_index.scss

@@ -2,6 +2,11 @@
 
 .wr-pagination {
   display: block;
+  // Breathing room of its own. A pager almost always sits right under a table or
+  // list, and with a bare `display: block` and no padding its cells touched the
+  // content above and below. Padding rather than margin so it stays inside the
+  // component's own box and can't collapse into the consumer's spacing.
+  padding-block: 0.5rem;
 
   &--disabled {
     opacity: 0.6;
@@ -80,6 +85,13 @@
 
   &__size {
     min-width: 0;
+
+    // The 10rem floor on `.wr-select__trigger` is sized for a standalone field.
+    // Here the select only ever holds "20 / page", so the pager was reserving
+    // 160px for a ~75px label — the single widest thing in the control.
+    .wr-select__trigger {
+      min-width: 0;
+    }
   }
 
   // Size variants — set the cell size; each button gets the matching [size].

package/popover/styles/_index.scss

@@ -1,8 +1,85 @@
+@use 'sass:list';
+
 @use '../../theme/styles' as theme;
 @use '../../overlay/styles'; // shared .wr-overlay-sheet / .wr-overlay-backdrop for responsive mode
 
+// --- Arrow -----------------------------------------------------------------
+//
+// A small square rotated 45°, half tucked under the panel so only the tip shows.
+// Tooltip and popover share the geometry; the popover additionally carries the
+// panel's border on the two outward faces so the outline reads as continuous.
+//
+// Placement is driven by the resolved position modifier the directive puts on the
+// overlay host (`--top` means the panel sits ABOVE the trigger, so the arrow hangs
+// off the panel's BOTTOM edge). All 12 positions are covered — the hand-written
+// tooltip rules this replaces only handled 8, so `top-start` / `top-end` /
+// `bottom-start` / `bottom-end` tooltips have been shipping with no arrow at all.
+$_arrow: 6px;
+$_arrow-half: 3px;
+$_arrow-inset: 0.625rem; // distance from the panel corner for the -start / -end variants
+
+// edge = which side of the panel the arrow hangs off; align = where along that side.
+$_arrow-placement: (
+  top: (bottom, center),
+  top-start: (bottom, start),
+  top-end: (bottom, end),
+  bottom: (top, center),
+  bottom-start: (top, start),
+  bottom-end: (top, end),
+  left: (right, center),
+  left-start: (right, start),
+  left-end: (right, end),
+  right: (left, center),
+  right-start: (left, start),
+  right-end: (left, end),
+);
+
+/// Positions the arrow against `$edge`, offset outwards by `$pull`.
+@mixin _arrow-at($edge, $align, $pull) {
+  #{$edge}: -$pull;
+
+  @if $edge == bottom or $edge == top {
+    @if $align == center {
+      left: 50%;
+      margin-left: -$_arrow-half;
+    } @else if $align == start {
+      left: $_arrow-inset;
+    } @else {
+      right: $_arrow-inset;
+    }
+  } @else {
+    @if $align == center {
+      top: 50%;
+      margin-top: -$_arrow-half;
+    } @else if $align == start {
+      top: $_arrow-inset;
+    } @else {
+      bottom: $_arrow-inset;
+    }
+  }
+}
+
+/// The two faces of the rotated square that stay visible outside the panel.
+@mixin _arrow-border($edge) {
+  @if $edge == bottom {
+    border-right: 1px solid var(--wr-color-outline);
+    border-bottom: 1px solid var(--wr-color-outline);
+  } @else if $edge == top {
+    border-left: 1px solid var(--wr-color-outline);
+    border-top: 1px solid var(--wr-color-outline);
+  } @else if $edge == right {
+    border-top: 1px solid var(--wr-color-outline);
+    border-right: 1px solid var(--wr-color-outline);
+  } @else {
+    border-bottom: 1px solid var(--wr-color-outline);
+    border-left: 1px solid var(--wr-color-outline);
+  }
+}
+
 .wr-popover-overlay {
   > * {
+    // Containing block for the arrow below.
+    position: relative;
     display: block;
     min-width: 8rem;
     max-width: 22rem;
@@ -14,6 +91,36 @@
     color: var(--wr-color-on-surface);
     animation: wr-overlay-in var(--wr-overlay-duration) var(--wr-overlay-ease);
     transform-origin: top left;
+
+    &::after {
+      content: '';
+      position: absolute;
+      width: $_arrow;
+      height: $_arrow;
+      background: var(--wr-color-surface);
+      transform: rotate(45deg);
+    }
+  }
+
+  // Responsive bottom-sheet mode has no anchor to point at, so no arrow.
+  &.wr-overlay-sheet > *::after {
+    content: none;
+  }
+}
+
+@each $position, $spec in $_arrow-placement {
+  $edge: list.nth($spec, 1);
+  $align: list.nth($spec, 2);
+
+  // Pulled one extra pixel so the square's own border lines up flush with the
+  // panel's, instead of leaving the panel border showing across the arrow's base.
+  .wr-popover-overlay--#{$position} > *::after {
+    @include _arrow-at($edge, $align, $_arrow-half + 1px);
+    @include _arrow-border($edge);
+  }
+
+  .wr-tooltip-overlay--#{$position} .wr-tooltip::after {
+    @include _arrow-at($edge, $align, $_arrow-half);
   }
 }
 
@@ -28,12 +135,25 @@
 }
 
 .wr-tooltip {
+  // Follows the theme instead of inverting against it: on a dark canvas the
+  // tooltip is dark, on a light canvas light. It used to invert (a light chip on
+  // dark), which is a common convention but reads as a foreign element here.
+  //
+  // Both halves are tokens, so an app that wants the inverted look back needs one
+  // rule, not an override of every tooltip rule:
+  //   .wr-tooltip { --wr-tooltip-bg: var(--wr-color-on-surface);
+  //                 --wr-tooltip-color: var(--wr-color-dark-contrast); }
+  --wr-tooltip-bg: var(--wr-color-surface);
+  --wr-tooltip-color: var(--wr-color-on-surface);
+  --wr-tooltip-border: var(--wr-color-outline);
+
   position: relative;
   display: inline-block;
   max-width: 18rem;
   padding: 0.3125rem 0.5rem;
-  background: var(--wr-color-on-surface);
-  color: var(--wr-color-dark-contrast);
+  background: var(--wr-tooltip-bg);
+  color: var(--wr-tooltip-color);
+  border: 1px solid var(--wr-tooltip-border);
   border-radius: var(--wr-border-radius-sm);
   font-family: var(--wr-font-family-base);
   font-size: var(--wr-text-xs);
@@ -42,56 +162,20 @@
   animation: wr-overlay-in var(--wr-overlay-duration) var(--wr-overlay-ease);
   transform-origin: top left;
 
-  // Arrow
+  // Arrow — geometry from the shared placement loop at the top of this file.
   &::after {
     content: '';
     position: absolute;
-    width: 6px;
-    height: 6px;
-    background: var(--wr-color-on-surface);
+    width: $_arrow;
+    height: $_arrow;
+    background: var(--wr-tooltip-bg);
     transform: rotate(45deg);
   }
 }
 
-// Arrow placement is dictated by the overlay panel's position modifier
-// (the wr-tooltip-overlay--top|bottom|left|right class lives on the
-// portal host wrapping the tooltip).
-.wr-tooltip-overlay--top .wr-tooltip::after {
-  left: 50%;
-  bottom: -3px;
-  margin-left: -3px;
-}
-.wr-tooltip-overlay--bottom .wr-tooltip::after {
-  left: 50%;
-  top: -3px;
-  margin-left: -3px;
-}
-.wr-tooltip-overlay--left .wr-tooltip::after {
-  top: 50%;
-  right: -3px;
-  margin-top: -3px;
-}
-.wr-tooltip-overlay--left-start .wr-tooltip::after {
-  top: 0.625rem;
-  right: -3px;
-}
-.wr-tooltip-overlay--left-end .wr-tooltip::after {
-  bottom: 0.625rem;
-  right: -3px;
-}
-.wr-tooltip-overlay--right .wr-tooltip::after {
-  top: 50%;
-  left: -3px;
-  margin-top: -3px;
-}
-.wr-tooltip-overlay--right-start .wr-tooltip::after {
-  top: 0.625rem;
-  left: -3px;
-}
-.wr-tooltip-overlay--right-end .wr-tooltip::after {
-  bottom: 0.625rem;
-  left: -3px;
-}
+// Arrow placement for both modes is generated from `$_arrow-placement` at the top
+// of this file — the per-position rules that used to live here are emitted there,
+// byte-identical for the 8 positions they covered plus the 4 they missed.
 
 @media (prefers-reduced-motion: reduce) {
   .wr-tooltip {

package/schematics/ng-add/index.js

@@ -10,8 +10,17 @@ const schematics_1 = require("@angular-devkit/schematics");
 const tasks_1 = require("@angular-devkit/schematics/tasks");
 const dependencies_1 = require("@schematics/angular/utility/dependencies");
 const workspace_1 = require("@schematics/angular/utility/workspace");
-/** Base peers, regardless of prompt answers. */
-const BASE_PEERS = [['@angular/cdk', '>=22.0.0']];
+/**
+ * Base peers, regardless of prompt answers.
+ *
+ * `lucide` is here because the bootstrap snippet this schematic prints registers
+ * icons through the lucide adapter — leaving it out made the very first snippet
+ * a consumer pastes fail to resolve.
+ */
+const BASE_PEERS = [
+    ['@angular/cdk', '>=22.0.0'],
+    ['lucide', '>=1.0.0'],
+];
 /** Extra peers contributed by the `dateAdapter` choice. */
 const DATE_ADAPTER_PEERS = {
     none: [],
@@ -121,11 +130,16 @@ function printNextSteps(options, context) {
         const adapter = options.dateAdapter ?? 'none';
         const density = options.density ?? 'none';
         const theme = options.theme ?? 'none';
+        // `ngwr/icon` exports only WrIcon / provideWrIcons / svgIcon — there are no
+        // bare icon exports, so the old `{ plus, trash }` import did not compile.
+        // Icons come from an adapter (lucide / feather) or from svgIcon().
         const imports = [
             "import { provideWrOverlay } from 'ngwr/overlay';",
-            "import { provideWrIcons, plus, trash } from 'ngwr/icon';",
+            "import { provideWrIcons } from 'ngwr/icon';",
+            "import { lucideIcons } from 'ngwr/icon/adapters/lucide';",
+            "import { Plus, Trash2 } from 'lucide';",
         ];
-        const providers = ['provideWrOverlay()', 'provideWrIcons([plus, trash])'];
+        const providers = ['provideWrOverlay()', 'provideWrIcons(lucideIcons({ plus: Plus, trash: Trash2 }))'];
         const adapterCall = DATE_ADAPTER_PROVIDER[adapter];
         if (adapterCall) {
             imports.push("import { provideWrDateAdapter } from 'ngwr/date-adapter';");

package/schematics/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/schematics/use/symbol-map.json

@@ -158,6 +158,7 @@
   "WrI18nParams": "ngwr/i18n",
   "WrI18nMissingHandler": "ngwr/i18n",
   "WrI18nLoader": "ngwr/i18n",
+  "WrI18nBaseCatalogs": "ngwr/i18n",
   "WrI18nStaticLoader": "ngwr/i18n",
   "WrI18nStaticCatalogs": "ngwr/i18n",
   "WrI18nStaticScopedCatalogs": "ngwr/i18n",
@@ -216,6 +217,7 @@
   "WrMetaTwitter": "ngwr/meta",
   "WrMeterGroup": "ngwr/meter-group",
   "WrMeterSegment": "ngwr/meter-group",
+  "WrOutsideClick": "ngwr/overlay",
   "WrOverlayContainer": "ngwr/overlay",
   "WrPageHeader": "ngwr/page-header",
   "WrPagination": "ngwr/pagination",

package/select/styles/_index.scss

@@ -270,6 +270,10 @@
   --wr-option-padding-y: 0.4375rem;
   --wr-option-padding-x: 0.625rem;
   --wr-option-gap: 0.1875rem;
+  // Space between an option's own bits — an icon or checkbox and its label.
+  // `--wr-option-gap` above is the panel's row rhythm, a different axis; without
+  // this one, a projected `<wr-icon>` sat flush against the text.
+  --wr-option-inline-gap: 0.5rem;
 
   display: flex;
   flex-direction: column;
@@ -292,6 +296,7 @@
     --wr-option-padding-y: 0.3125rem;
     --wr-option-padding-x: 0.5rem;
     --wr-option-gap: 0.125rem;
+    --wr-option-inline-gap: 0.375rem;
   }
 
   &--lg {
@@ -300,6 +305,7 @@
     --wr-option-padding-y: 0.5rem;
     --wr-option-padding-x: 0.75rem;
     --wr-option-gap: 0.25rem;
+    --wr-option-inline-gap: 0.625rem;
   }
 
   &__loading,
@@ -314,6 +320,7 @@
 .wr-option {
   display: flex;
   align-items: center;
+  gap: var(--wr-option-inline-gap, 0.5rem);
   padding: var(--wr-option-padding-y) var(--wr-option-padding-x);
   border-radius: var(--wr-border-radius-sm);
   color: var(--wr-color-on-surface);
@@ -399,6 +406,12 @@
     text-transform: uppercase;
   }
 
+  // A group needs a visible seam above it, or its label reads as one more dim
+  // option in the list. This only fired between two groups, so the common shape
+  // — loose options and then a group — got no divider at all. Match a preceding
+  // option too; deliberately not `* + &`, which would also draw a line under the
+  // search field, where the field's own border already does the job.
+  .wr-option + &,
   + .wr-option-group {
     border-top: 1px solid var(--wr-color-outline);
     margin-top: 0.25rem;

package/splitter/styles/_index.scss

@@ -19,7 +19,13 @@
 
   &__pane {
     flex-grow: 0;
-    flex-shrink: 0;
+    // Shrinkable on purpose. The two panes are sized in percentages that add up
+    // to 100, and the 4px divider sits between them — with `flex-shrink: 0` the
+    // row came to 100% + 4px and both panes hung over the container's edge.
+    // Shrinking splits that 4px between them and keeps the ratio the drag set.
+    // Safe to shrink: `min-width: 0` plus `overflow: auto` means content never
+    // props a pane open.
+    flex-shrink: 1;
     min-width: 0;
     min-height: 0;
     overflow: auto;

package/table/styles/_index.scss

@@ -1,12 +1,27 @@
 @use '../../theme/styles' as theme;
 
 .wr-table {
+  --wr-table-bg: var(--wr-color-surface);
   --wr-table-border: var(--wr-color-outline);
   --wr-table-head-bg: rgba(var(--wr-color-outline-rgb), 0.25);
   --wr-table-row-hover: rgba(var(--wr-color-outline-rgb), 0.15);
+  // Head casing. The library renders column titles as the author wrote them —
+  // forcing `uppercase` mutates their content, and a header written "ID" or
+  // "created at" is the consumer's decision to make, not ours. Both halves stay
+  // tokens, so opting back into the old treatment is one rule:
+  //   .wr-table { --wr-table-head-transform: uppercase;
+  //               --wr-table-head-letter-spacing: 0.04em; }
+  // The tracking moves with the casing on purpose — 0.04em is there to open up
+  // capitals and looks wrong on sentence case.
+  --wr-table-head-transform: none;
+  --wr-table-head-letter-spacing: var(--wr-tracking-normal);
 
   display: block;
   position: relative;
+  // The table paints its own surface. Sticky pinned cells already fill with
+  // --wr-color-surface, so leaving the table transparent let a page background
+  // show through the normal rows while the pinned ones stayed opaque.
+  background: var(--wr-table-bg);
   // Own stacking context so the loading overlay reliably outranks the sticky
   // pinned cells regardless of the surrounding page z-index.
   isolation: isolate;
@@ -50,8 +65,8 @@
     color: var(--wr-color-on-surface-muted);
     font-weight: 600;
     font-size: var(--wr-text-xs);
-    letter-spacing: 0.04em;
-    text-transform: uppercase;
+    letter-spacing: var(--wr-table-head-letter-spacing);
+    text-transform: var(--wr-table-head-transform);
     white-space: nowrap;
   }
 
@@ -203,7 +218,7 @@
   // Pinned footer cells need an opaque base (over the head tint) to stay sticky.
   &__foot-cell#{&}__td--pin-left,
   &__foot-cell#{&}__td--pin-right {
-    background-color: var(--wr-color-surface);
+    background-color: var(--wr-table-bg);
     background-image: linear-gradient(var(--wr-table-head-bg), var(--wr-table-head-bg));
   }
 
@@ -221,14 +236,14 @@
   &__td--pin-left,
   &__td--pin-right {
     z-index: 1;
-    background-color: var(--wr-color-surface);
+    background-color: var(--wr-table-bg);
   }
 
   // Header cells lay the head tint over the opaque base so the row stays seamless.
   &__th--pin-left,
   &__th--pin-right {
     z-index: 2;
-    background-color: var(--wr-color-surface);
+    background-color: var(--wr-table-bg);
     background-image: linear-gradient(var(--wr-table-head-bg), var(--wr-table-head-bg));
   }
 
@@ -392,7 +407,7 @@
   &__group-foot-row > &__foot-cell {
     border-top: 0;
     border-bottom: 1px solid var(--wr-table-border);
-    background-color: var(--wr-color-surface);
+    background-color: var(--wr-table-bg);
     background-image: linear-gradient(var(--wr-table-group-bg), var(--wr-table-group-bg));
   }
 
@@ -424,7 +439,7 @@
   }
 
   thead th:not(.wr-table__th--pin-left):not(.wr-table__th--pin-right) {
-    background-color: var(--wr-color-surface);
+    background-color: var(--wr-table-bg);
     background-image: linear-gradient(var(--wr-table-head-bg), var(--wr-table-head-bg));
   }
 
@@ -456,7 +471,7 @@
   }
 
   tfoot .wr-table__foot-cell:not(.wr-table__td--pin-left):not(.wr-table__td--pin-right) {
-    background-color: var(--wr-color-surface);
+    background-color: var(--wr-table-bg);
     background-image: linear-gradient(var(--wr-table-head-bg), var(--wr-table-head-bg));
   }
 
@@ -518,8 +533,11 @@
     color: var(--wr-color-on-surface-muted);
     font-size: var(--wr-text-xs);
     font-weight: 600;
-    letter-spacing: 0.04em;
-    text-transform: uppercase;
+    // Route through the same tokens as `&__th` instead of re-hard-coding the
+    // treatment — card mode used to ignore `--wr-table-head-transform` entirely,
+    // so a consumer who opted out still got capitals on mobile.
+    letter-spacing: var(--wr-table-head-letter-spacing);
+    text-transform: var(--wr-table-head-transform);
     text-align: left;
     white-space: nowrap;
   }

package/theme/styles/_box-model.scss

@@ -0,0 +1,29 @@
+// Box model baseline for ngwr's own elements.
+//
+// `ngwr/reset` (which does set `box-sizing: border-box` globally) is opt-in by
+// design, and the umbrella `@use 'ngwr'` deliberately leaves it out — so a
+// consumer following the documented "import once, everything works" path lands
+// in a `content-box` world. Components can't assume otherwise, and several of
+// them did: any `.wr-*` element that pairs `width: 100%` with padding or a
+// border overflowed its container by exactly padding + border. Measured in a
+// stock Angular app on `@use 'ngwr'`:
+//
+//   .wr-btn--block                → 30px over (14+14 padding, 1+1 border)
+//   .wr-input (sm / md / lg)      → 18 / 26 / 34px over
+//   .wr-textarea__native          → 16 / 24 / 32px over
+//   .wr-input-group               → 2px over (border only)
+//
+// Which is where the stray horizontal scrollbars came from.
+//
+// Scoped to the `wr-` namespace so it can never change the box model of
+// consumer markup — that stays their call, via `ngwr/reset` or their own reset.
+//
+// `:where()` contributes zero specificity on purpose: this is a baseline, not an
+// override. `.wr-icon` and `.wr-spinner` declare `content-box` deliberately (the
+// declared size IS the glyph box) and keep winning without needing `!important`
+// or a particular load order.
+:where([class^='wr-'], [class*=' wr-']),
+:where([class^='wr-'], [class*=' wr-'])::before,
+:where([class^='wr-'], [class*=' wr-'])::after {
+  box-sizing: border-box;
+}

package/theme/styles/_colors.scss

@@ -21,11 +21,10 @@ $base-colors: (
   dark: #0f172a,
 ) !default;
 
-// YIQ luminosity threshold (0–255) above which a color is treated as
-// "light" and pairs with dark text. Uses the classic Bootstrap formula —
-// it weights the green channel higher than blue, which matches human
-// perception of brightness far better than HSL lightness (HSL classes
-// pure blue as 50%-lightness even though it reads as dark).
+// Deprecated: the old YIQ brightness cut-off. No longer read — `_contrast()`
+// compares real WCAG contrast ratios, which needs no threshold. Kept declared
+// so `@use 'ngwr/theme' with ($contrast-threshold: …)` in an existing app still
+// compiles instead of erroring on an unknown variable.
 $contrast-threshold: 150 !default;
 
 // Dark text used on light backgrounds.
@@ -40,20 +39,69 @@ $contrast-light: #ffffff !default;
   @return color.channel($c, 'red'), color.channel($c, 'green'), color.channel($c, 'blue');
 }
 
+/** One channel, linearised per WCAG 2.x. */
+@function _linear($channel) {
+  $s: math.div($channel, 255);
+  @if $s <= 0.03928 {
+    @return math.div($s, 12.92);
+  }
+  @return math.pow(math.div($s + 0.055, 1.055), 2.4);
+}
+
+/** WCAG relative luminance of a colour. */
+@function _luminance($c) {
+  @return 0.2126 * _linear(color.channel($c, 'red')) + 0.7152 * _linear(color.channel($c, 'green')) + 0.0722 *
+    _linear(color.channel($c, 'blue'));
+}
+
+/** WCAG contrast ratio between two colours. */
+@function _ratio($a, $b) {
+  $la: _luminance($a);
+  $lb: _luminance($b);
+  $hi: math.max($la, $lb);
+  $lo: math.min($la, $lb);
+  @return math.div($hi + 0.05, $lo + 0.05);
+}
+
+/**
+ * Foreground that actually reads best on `$c` — whichever of the two candidates
+ * wins on WCAG contrast ratio.
+ *
+ * Was a YIQ brightness threshold, which is a brightness *estimate*, not the
+ * metric accessibility is judged by, and it mispicked on every mid-saturation
+ * colour: five of the nine shipped intents got white text below AA
+ * (success 3.33:1, medium 3.10:1, danger and info 3.68:1, secondary 3.99:1)
+ * where dark text would have cleared it (5.43 / 5.82 / 4.90 / 4.91 / 4.52).
+ * Comparing the real ratios needs no threshold to tune.
+ */
 @function _contrast($c) {
-  $r: color.channel($c, 'red');
-  $g: color.channel($c, 'green');
-  $b: color.channel($c, 'blue');
-  $yiq: math.div($r * 299 + $g * 587 + $b * 114, 1000);
-  @if $yiq >= $contrast-threshold {
+  @if _ratio($c, $contrast-dark) >= _ratio($c, $contrast-light) {
     @return $contrast-dark;
   }
   @return $contrast-light;
 }
 
+/**
+ * Public alias of {@link _contrast}. Any theme partial that re-tunes an intent
+ * has to re-derive its `-contrast` token too, otherwise the token stays baked
+ * from the light palette — which is how the dark theme ended up putting white
+ * text on its lightened primary at 3.36:1.
+ */
+@function contrast($c) {
+  @return _contrast($c);
+}
+
 // CSS variables
 
 :root {
+  // Declared here so the light token set also claims the light UA scheme.
+  // Without it the browser fell back to the OS preference, and an app running
+  // ngwr's LIGHT theme on a dark-mode machine got dark scrollbars and dark
+  // native controls (<textarea>, date/colour inputs) against light surfaces.
+  // `_dark.scss` still flips it to `dark` under [data-theme='dark'], which wins
+  // on specificity.
+  color-scheme: light;
+
   --wr-color-white: #ffffff;
   --wr-color-white-rgb: 255, 255, 255;
   --wr-color-black: #000000;
@@ -80,10 +128,21 @@ $contrast-light: #ffffff !default;
   // regardless of theme.
   --wr-color-overlay: rgba(var(--wr-color-backdrop-rgb), 0.45);
 
-  // De-emphasized text — `medium` dimmed to two canonical strengths so muted
+  // Muted TEXT, deliberately its own token rather than an alias of the `medium`
+  // intent. The two roles pull in opposite directions and cannot share a value:
+  // as text it needs >= 4.5:1 against the lightest surface (#ebeff4), while as a
+  // button fill it carries dark text and needs >= 4.5:1 the other way. The best
+  // candidate for either fails the other — the window closes around #6b7a8a
+  // (3.81 as text, 4.11 as fill). Aliasing them left secondary text at 2.69:1.
+  --wr-color-muted-text: #5f6c7d;
+  --wr-color-muted-text-rgb: 95, 108, 125;
+
+  // De-emphasized text — the muted ink dimmed to two canonical strengths so
   // labels / captions / placeholders read consistently. One place each.
-  --wr-color-text-muted: rgba(var(--wr-color-medium-rgb), 0.85);
-  --wr-color-text-faint: rgba(var(--wr-color-medium-rgb), 0.6);
+  // Only the full-opacity token above is AA-safe for body text; these two are
+  // decorative by design (0.85 reaches ~3.5:1, 0.6 ~2.3:1 on a light surface).
+  --wr-color-text-muted: rgba(var(--wr-color-muted-text-rgb), 0.85);
+  --wr-color-text-faint: rgba(var(--wr-color-muted-text-rgb), 0.6);
 
   // Neutral gray ramp — a FIXED primitive scale (slate). Each step is a stable
   // job (50 = subtlest surface tint … 950 = strongest ink) and, unlike the
@@ -121,8 +180,8 @@ $contrast-light: #ffffff !default;
   --wr-color-surface-rgb: var(--wr-color-white-rgb);
   --wr-color-on-surface: var(--wr-color-dark);
   --wr-color-on-surface-rgb: var(--wr-color-dark-rgb);
-  --wr-color-on-surface-muted: var(--wr-color-medium);
-  --wr-color-on-surface-muted-rgb: var(--wr-color-medium-rgb);
+  --wr-color-on-surface-muted: var(--wr-color-muted-text);
+  --wr-color-on-surface-muted-rgb: var(--wr-color-muted-text-rgb);
 
   // Solid hairline / divider colour. Distinct from `--wr-color-border` above,
   // which is deliberately translucent (`light` at 50%) so it reads on any