ngwr 11.2.0 → 12.0.0

package/theme/styles/_colors.scss

@@ -113,33 +113,47 @@ $contrast-light: #ffffff !default;
 
 // 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;
-  --wr-color-black-rgb: 0, 0, 0;
-
-  // Overlay dim — used by dialog / drawer / image preview / command
-  // palette / image cropper for the behind-the-panel scrim. Always
-  // black so the dim reads as "covered" regardless of theme. Don't
-  // wire to `--wr-color-dark-rgb` — that flips to light in dark mode
-  // and turns the backdrop into a white wash.
-  --wr-color-backdrop-rgb: 0, 0, 0;
-
+/// Every public token whose value is COMPOSED out of another token.
+///
+/// They live in a mixin rather than straight in `:root` because a custom
+/// property's `var()` references are substituted at computed-value time ON THE
+/// ELEMENT THAT DECLARES IT, and what inherits down the tree is the substituted
+/// LITERAL. Declared once at `:root`, `--wr-color-surface: var(--wr-color-white)`
+/// computes to `#ffffff` there and every descendant inherits `#ffffff` — not the
+/// reference. Re-tuning `--wr-color-white` further down the tree does nothing to
+/// it afterwards.
+///
+/// That costs nothing for the whole-page dark theme: `[data-theme='dark']`
+/// matches the same `<html>` that `:root` does, so the bases it re-tunes and the
+/// tokens composed off them resolve on ONE element and stay consistent. It
+/// breaks the moment the attribute goes on a SUBTREE — a forced-dark preview, a
+/// dark hero on a light page — where the bases flip and fifty composed tokens
+/// keep their light values. The docs' own colours guide does exactly that, and
+/// its forced-dark panel painted muted text at 3.27:1 with `--wr-color-surface`
+/// still reading `#ffffff` beside a `--wr-color-muted-text` that had correctly
+/// flipped.
+///
+/// So `_dark.scss` includes this too: re-declaring the compositions ON the themed
+/// element is what makes them re-resolve against that element's own bases. A new
+/// token written in terms of `var()` gets that for free if it is added HERE, and
+/// is frozen again if it is added to `:root` directly — that is the whole rule.
+@mixin derived() {
   // Generic subtle hover-surface tint (icon buttons, list rows) — one place
   // so the hover strength stays consistent everywhere.
   --wr-color-hover: rgba(var(--wr-color-light-rgb), 0.4);
 
   // Border / divider strengths — translucent so they read on any surface and
   // auto-adapt in dark (via the flipping `light` channels). One place each.
+  //
+  // unused-ok: for `-subtle` and `-strong`. The catalog draws its hairlines with
+  // the opaque `--wr-color-outline`, and `--wr-color-border` has one consumer
+  // (`wr-avatar`'s ring), so these two are the weaker and stronger ends of a
+  // scale offered to consumers rather than one we paint with. They were NOT the
+  // answer to the twenty-two files that hand-rolled
+  // `rgba(var(--wr-color-outline-rgb), α)` at eight alphas — four of which
+  // computed to exactly these values. Those were FILLS, and naming a fill after a
+  // hairline is how a token layer starts lying, so the `--wr-color-fill*` scale
+  // below absorbed them instead; not one of those hand-rolls is left.
   --wr-color-border: rgba(var(--wr-color-light-rgb), 0.5);
   --wr-color-border-subtle: rgba(var(--wr-color-light-rgb), 0.35);
   --wr-color-border-strong: rgba(var(--wr-color-light-rgb), 0.6);
@@ -148,15 +162,23 @@ $contrast-light: #ffffff !default;
   // regardless of theme.
   --wr-color-overlay: rgba(var(--wr-color-backdrop-rgb), 0.45);
 
-  // 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
-  // fill it has to clear the bar the other way, against its own label. v11 pulled
-  // them further apart rather than closer — the `medium` fill went deeper
-  // (#6a7683, whose label is now white at 4.63) while this token stayed where a
-  // light canvas needs it. Aliasing them left secondary text at 2.69:1.
-  --wr-color-muted-text: #5f6c7d;
-  --wr-color-muted-text-rgb: 95, 108, 125;
+  // Neutral FILL scale — the low-contrast wash a table header, a track, a
+  // readonly field or a code chip sits on. Three steps, because the catalog had
+  // **thirty-three declarations at eight alphas** hand-rolled across 22 files,
+  // and `wr-table` alone used six of them; the values below are the weighted
+  // centre of the three clusters those eight actually formed.
+  //
+  // **Off `light-rgb`, deliberately NOT off `--wr-color-outline-rgb`**, even
+  // though the two resolve to the same channel today. That is the bug this scale
+  // exists to prevent: every one of those hand-rolls read the OUTLINE channel, so
+  // a hairline retuned for its own job — a plausible contrast fix — would have
+  // dragged 33 unrelated fills with it, and one measured pair in `wr-table` goes
+  // from 6.58:1 to 4.05:1 that way. A fill is not a hairline, which is also why
+  // these are not `--wr-color-border-*` under a new name: those three carry the
+  // right VALUES under the wrong noun.
+  --wr-color-fill-subtle: rgba(var(--wr-color-light-rgb), 0.15);
+  --wr-color-fill: rgba(var(--wr-color-light-rgb), 0.3);
+  --wr-color-fill-strong: rgba(var(--wr-color-light-rgb), 0.55);
 
   // De-emphasized text — the muted ink dimmed to two canonical strengths so
   // labels / captions / placeholders read consistently. One place each.
@@ -169,22 +191,6 @@ $contrast-light: #ffffff !default;
   --wr-color-text-muted: rgba(var(--wr-color-muted-text-rgb), 0.95);
   --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
-  // semantic neutrals, does NOT flip in dark mode. For theme-aware surface /
-  // text jobs reach for the role aliases below instead.
-  --wr-color-gray-50: #f8fafc;
-  --wr-color-gray-100: #f1f5f9;
-  --wr-color-gray-200: #e2e8f0;
-  --wr-color-gray-300: #cbd5e1;
-  --wr-color-gray-400: #94a3b8;
-  --wr-color-gray-500: #64748b;
-  --wr-color-gray-600: #475569;
-  --wr-color-gray-700: #334155;
-  --wr-color-gray-800: #1e293b;
-  --wr-color-gray-900: #0f172a;
-  --wr-color-gray-950: #020617;
-
   // Semantic role aliases over the flipping neutrals — prefer these in new code
   // for intent-free surface / text / outline jobs. They resolve through
   // `white` / `dark` / `medium` / `light`, so they flip with the theme
@@ -214,18 +220,14 @@ $contrast-light: #ffffff !default;
   // with today. Both are kept: swapping one for the other changes appearance,
   // not just naming.
   --wr-color-outline: var(--wr-color-light);
+  // unused-ok: the channel form of the hairline, kept for a consumer writing
+  // their own `rgba()` rule. The library's twenty-two hand-rolls read it and
+  // moved to `--wr-color-fill*` above — deliberately off `light-rgb`, for the
+  // reason stated there — so nothing paints with the channels today. Until this
+  // check stopped counting comments as consumers, the paragraph at :152 was the
+  // only thing keeping it green.
   --wr-color-outline-rgb: var(--wr-color-light-rgb);
 
-  @each $name, $base in $base-colors {
-    --wr-color-#{$name}: #{$base};
-    --wr-color-#{$name}-rgb: #{_rgb-channels($base)};
-    --wr-color-#{$name}-contrast: #{_contrast($base)};
-    --wr-color-#{$name}-dark: #{color.adjust($base, $lightness: -5%)};
-    --wr-color-#{$name}-darker: #{color.adjust($base, $lightness: -10%)};
-    --wr-color-#{$name}-light: #{color.adjust($base, $lightness: 5%)};
-    --wr-color-#{$name}-lighter: #{color.adjust($base, $lightness: 10%)};
-  }
-
   // Soft trio per intent (+ `medium` for neutral surfaces) — tokenizes the
   // ad-hoc `rgba(var(--*-rgb), α)` fills components hand-rolled at ~8
   // different alphas, so each alpha lives in ONE place. `-soft` is the
@@ -236,6 +238,10 @@ $contrast-light: #ffffff !default;
   @each $name in (primary, secondary, success, warning, danger, info, medium) {
     --wr-color-#{$name}-soft: rgba(var(--wr-color-#{$name}-rgb), 0.12);
     --wr-color-#{$name}-soft-border: rgba(var(--wr-color-#{$name}-rgb), 0.3);
+    // unused-ok: superseded in practice by `-ink`, which is calibrated to 5.0:1
+    // against this very tint while this one is a flat 62% mix that was never
+    // measured. Kept because it is public and predates `-ink`; do not reach for
+    // it in new code, and do not delete it in a minor.
     --wr-color-#{$name}-soft-contrast: color-mix(in srgb, var(--wr-color-#{$name}) 62%, var(--wr-color-dark));
     --wr-color-#{$name}-active: rgba(var(--wr-color-#{$name}-rgb), 0.2);
   }
@@ -304,10 +310,90 @@ $contrast-light: #ffffff !default;
   // either theme — so there is no darkening that keeps it recognisable AND
   // readable. It borrows the page's own ink; the border still carries the
   // intent. `dark` already IS the ink.
+  // unused-ok: the two ends of the ink ramp that resolve to something already
+  // named. `light` borrows the page's own ink and `dark` IS the ink, so a
+  // component would write the role directly — these exist so that
+  // `var(--wr-color-#{$intent}-ink)` in a loop resolves for all nine intents
+  // instead of nine minus two.
   --wr-color-light-ink: var(--wr-color-on-surface);
   --wr-color-dark-ink: var(--wr-color-dark);
 }
 
+: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;
+  // unused-ok: the flat primitive. Only `-black-rgb` is painted with (eleven
+  // sites, all of them building an `rgba()` scrim), but a library that ships
+  // `--wr-color-white` and not its opposite reads as an omission.
+  --wr-color-black: #000000;
+  --wr-color-black-rgb: 0, 0, 0;
+
+  // Overlay dim — used by dialog / drawer / image preview / command
+  // palette / image cropper for the behind-the-panel scrim. Always
+  // black so the dim reads as "covered" regardless of theme. Don't
+  // wire to `--wr-color-dark-rgb` — that flips to light in dark mode
+  // and turns the backdrop into a white wash.
+  --wr-color-backdrop-rgb: 0, 0, 0;
+
+  // 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
+  // fill it has to clear the bar the other way, against its own label. v11 pulled
+  // them further apart rather than closer — the `medium` fill went deeper
+  // (#6a7683, whose label is now white at 4.63) while this token stayed where a
+  // light canvas needs it. Aliasing them left secondary text at 2.69:1.
+  --wr-color-muted-text: #5f6c7d;
+  --wr-color-muted-text-rgb: 95, 108, 125;
+
+  // Neutral gray ramp — a FIXED primitive scale (slate). Each step is a stable
+  // job (50 = subtlest surface tint … 950 = strongest ink) and, unlike the
+  // semantic neutrals, does NOT flip in dark mode. For theme-aware surface /
+  // text jobs reach for the role aliases in `derived()` above instead.
+  //
+  // unused-ok: and deliberately so — the sentence above IS the reason. A fixed
+  // ramp cannot serve a component that has to work in both themes, so the
+  // library paints with the flipping roles and ships this for consumers who want
+  // a stable step. Reaching for one of these inside a component would be the bug
+  // it exists to prevent.
+  --wr-color-gray-50: #f8fafc;
+  --wr-color-gray-100: #f1f5f9;
+  --wr-color-gray-200: #e2e8f0;
+  --wr-color-gray-300: #cbd5e1;
+  --wr-color-gray-400: #94a3b8;
+  --wr-color-gray-500: #64748b;
+  --wr-color-gray-600: #475569;
+  --wr-color-gray-700: #334155;
+  --wr-color-gray-800: #1e293b;
+  --wr-color-gray-900: #0f172a;
+  --wr-color-gray-950: #020617;
+
+  @each $name, $base in $base-colors {
+    --wr-color-#{$name}: #{$base};
+    --wr-color-#{$name}-rgb: #{_rgb-channels($base)};
+    --wr-color-#{$name}-contrast: #{_contrast($base)};
+    --wr-color-#{$name}-dark: #{color.adjust($base, $lightness: -5%)};
+    --wr-color-#{$name}-darker: #{color.adjust($base, $lightness: -10%)};
+    // unused-ok: the symmetric half. Hover and active DEEPEN an intent, so the
+    // catalog reads `-dark` / `-darker` and never these two — but a shade set
+    // with holes in it is worse than one half of which is for consumers, and the
+    // dark theme re-derives all four for the same reason.
+    --wr-color-#{$name}-light: #{color.adjust($base, $lightness: 5%)};
+    --wr-color-#{$name}-lighter: #{color.adjust($base, $lightness: 10%)};
+  }
+
+  // Re-resolved per themed element — see the mixin above. Anything composed
+  // out of another token belongs in there, not here.
+  @include derived;
+}
+
 // Public SCSS list
 //
 // Color names available for `@each` loops in component styles.

package/theme/styles/_dark.scss

@@ -1,6 +1,7 @@
 @use 'sass:color';
 
 @use 'colors';
+@use 'variables';
 
 // Dark theme overrides — opt-in via `[data-theme="dark"]` on <html>.
 // Drive the toggle from `WrTheme` (provided automatically with
@@ -53,6 +54,11 @@ $_dark: #e6ebf3;
   // `--wr-color-white` are reassigned for dark mode. Tooltip-style
   // surfaces (`bg: dark; color: dark-contrast`) would render
   // white-on-white without this override; re-pair them by hand here.
+  // unused-ok: for `-white-contrast`. Both are re-paired here because the light
+  // palette baked them, and a tooltip painting `bg: dark; color: dark-contrast`
+  // would render white-on-white without it. Only the `dark` half is painted with
+  // today; the `white` one has to be right anyway, or a consumer reaching for it
+  // in dark mode gets the light theme's answer.
   --wr-color-dark-contrast: #0b1120;
   --wr-color-white-contrast: #e6ebf3;
   // Same story as the contrast pair: the shades were baked from the light
@@ -67,6 +73,11 @@ $_dark: #e6ebf3;
   // percentage of the REMAINING headroom, so it approaches white without ever
   // leaving the gamut. 70% reproduces the previous `-light` to within a rounding
   // step; 85% is the distinct step beyond it.
+  // unused-ok: for `-light` / `-lighter`. The catalog's intent loops run over
+  // `dark` like any other intent, so `.wr-btn--dark` really does paint `-dark`
+  // on hover and `-darker` on active — leaving those inherited is what once made
+  // that hover almost black under near-black text. Nothing reaches for the two
+  // lighter steps; they keep the shade set symmetric.
   --wr-color-dark-light: #{color.scale($_dark, $lightness: 70%)};
   --wr-color-dark-lighter: #{color.scale($_dark, $lightness: 85%)};
   --wr-color-dark-dark: #{color.adjust($_dark, $lightness: -5%)};
@@ -83,7 +94,8 @@ $_dark: #e6ebf3;
   --wr-color-light-rgb:
     #{color.channel($_light, 'red')}, #{color.channel($_light, 'green')}, #{color.channel($_light, 'blue')};
   // The baked contrast pairs with the LIGHT value (#cbd5e1 → dark text);
-  // the dark surface above needs light text instead.
+  // the dark surface above needs light text instead. Painted: it is the label
+  // `.wr-btn--light` puts on the fill.
   --wr-color-light-contrast: #e6ebf3;
   // `*-lighter` / `*-darker` are baked at SCSS compile time from the
   // LIGHT palette (slate-300 ± 10% lightness ≈ #e8eef5), so without
@@ -92,14 +104,20 @@ $_dark: #e6ebf3;
   // semantics inverted: "lighter" still means "subtler hairline"
   // (closer to canvas, so darker absolute color), "darker" still
   // means "stronger divider" (further from canvas, so lighter).
+  // Both are painted: `-lighter` by the showcase chrome's hairline, `-darker` by
+  // `.wr-btn--light:active` through the intent loop.
   --wr-color-light-lighter: #1a2236;
   --wr-color-light-darker: #3a4661;
-  // `-light` / `-dark` were the two the hand block forgot, and they are what
-  // `.wr-btn--light` uses for hover / active. Left inherited, hover swapped in
+  // `-light` / `-dark` were the two the hand block forgot, and `-dark` is what
+  // `.wr-btn--light` uses for hover. Left inherited, hover swapped in
   // the LIGHT palette's slate-300 — a near-white fill under the near-white
   // `-contrast` text above, so the button simply disappeared under the cursor.
   // Half-steps of the tuned pair, same inverted reading: toward the canvas for
   // `-light`, away from it for `-dark`, which also makes hover read as a lift.
+  // unused-ok: for `-light`. Only its opposite is reached for — `.wr-btn--light`
+  // takes the `-dark` step on hover and nothing takes this one — but a half-step
+  // that exists in one direction and not the other is the kind of hole the hand
+  // block already shipped once.
   --wr-color-light-light: #{color.adjust($_light, $lightness: -2.5%)};
   --wr-color-light-dark: #{color.adjust($_light, $lightness: 5%)};
 
@@ -111,6 +129,10 @@ $_dark: #e6ebf3;
     #{color.channel($_medium, 'red')}, #{color.channel($_medium, 'green')}, #{color.channel($_medium, 'blue')};
   // This block shipped base + rgb only, so contrast and all four shades still
   // came from the light palette's slate. Ink token, plain shades.
+  // unused-ok: for `-light` / `-lighter`. `.wr-btn--medium` paints `-contrast`,
+  // `-dark` and `-darker` through the intent loop, and inheriting the light
+  // palette's slate for those is the bug this block fixes. Nothing reaches for
+  // the two lighter steps; they keep the set symmetric.
   --wr-color-medium-contrast: #{colors.contrast($_medium)};
   --wr-color-medium-light: #{color.adjust($_medium, $lightness: 5%)};
   --wr-color-medium-lighter: #{color.adjust($_medium, $lightness: 10%)};
@@ -144,6 +166,10 @@ $_dark: #e6ebf3;
   --wr-color-primary-contrast: #{colors.contrast(#3567ff)};
   --wr-color-primary-rgb: 53, 103, 255;
   // The same lightness steps as before, taken off the new base.
+  // unused-ok: for `-light` / `-lighter`. `.wr-btn--primary` paints `-dark` on
+  // hover and `-darker` on active; the two lighter steps keep the set symmetric
+  // with the light palette, which is what makes an intent swap-in-place for a
+  // consumer.
   --wr-color-primary-light: #547eff;
   --wr-color-primary-dark: #2848aa;
   --wr-color-primary-lighter: #7396ff;
@@ -158,6 +184,10 @@ $_dark: #e6ebf3;
     --wr-color-#{$name}-contrast: #{colors.contrast($base)};
     --wr-color-#{$name}-rgb:
       #{color.channel($base, 'red')}, #{color.channel($base, 'green')}, #{color.channel($base, 'blue')};
+    // unused-ok: for `-light` / `-lighter`, the symmetric half — same reasoning
+    // as the light palette's loop. `-dark` and `-darker` below are painted by
+    // hover and active; they fall inside this marker's run only because the four
+    // shades are written as one block.
     --wr-color-#{$name}-light: #{color.adjust($base, $lightness: 5%)};
     --wr-color-#{$name}-lighter: #{color.adjust($base, $lightness: 10%)};
     --wr-color-#{$name}-dark: #{color.adjust($base, $lightness: -5%)};
@@ -173,5 +203,18 @@ $_dark: #e6ebf3;
   --wr-shadow-float: 0 8px 24px rgb(0 0 0 / 55%);
   --wr-shadow-modal: 0 24px 56px rgb(0 0 0 / 60%);
 
+  // Re-declare every token that is COMPOSED out of the bases above, so the
+  // composition resolves against THIS element's values instead of the ones
+  // `:root` already substituted. Without it the block is only correct when it
+  // lands on `:root` itself; put `data-theme="dark"` on a SUBTREE — a forced-dark
+  // preview, a dark hero on a light page — and the bases flip while fifty
+  // derived tokens stay light. `--wr-color-surface` read `#ffffff` inside a dark
+  // panel, which is how the docs' own colours guide got to 3.27:1. The two
+  // mixins are the single source of those compositions; see the long note above
+  // `colors.derived()` for why a `var()` in a custom property cannot do this on
+  // its own.
+  @include colors.derived;
+  @include variables.derived-focus-ring;
+
   color-scheme: dark;
 }

package/theme/styles/_focus.scss

@@ -2,32 +2,55 @@
 // library. Component-specific focus styles still win via higher specificity;
 // this is a safety net so every keyboard-reachable target has a visible
 // focus indicator out of the box.
+//
+// The ring is an outline plus a halo, both read from `--wr-focus-ring-*` — see
+// `_variables.scss` for why, and for the measured ratios. The short version:
+// the halo alone was 1.41:1 and this mixin also cleared the UA outline, so
+// "visible focus indicator out of the box" was not true of the forty-one
+// selectors that rely on it.
+//
+// Override the offset AFTER the include, the way `list` and `window` do, when
+// the target sits inside a clipping container.
 
 @mixin focus-ring {
-  outline: none;
-  box-shadow: 0 0 0 3px rgba(var(--wr-color-primary-rgb), 0.25);
+  outline: var(--wr-focus-ring-width) solid var(--wr-focus-ring-color);
+  outline-offset: var(--wr-focus-ring-offset);
+  box-shadow: 0 0 0 var(--wr-focus-ring-offset) var(--wr-focus-ring-halo);
 }
 
-// Tabs
+// Tabs — `.wr-tabs__strip` is `overflow-y: hidden` (to suppress a stray
+// vertical scrollbar) and its box is exactly the tab's height, so an outset
+// ring loses both horizontal strokes and renders as two disconnected bars.
 .wr-tabs__tab:focus-visible {
   @include focus-ring;
+  outline-offset: -2px;
 }
 
 // Sidebar
 .wr-sidebar__entry:focus-visible,
-.wr-sidebar__item:focus-visible,
 .wr-sidebar__group-toggle:focus-visible {
   @include focus-ring;
 }
 
+// `.wr-sidebar__group-body` is `overflow: hidden` so the group can animate
+// `grid-template-rows` from 1fr to 0fr, and the item runs flush to its inline
+// end — an outset ring loses its whole inline-end stroke there.
+.wr-sidebar__item:focus-visible {
+  @include focus-ring;
+  outline-offset: -2px;
+}
+
 // Anchor
 .wr-anchor__link:focus-visible {
   @include focus-ring;
 }
 
-// Collapse / accordion header
+// Collapse / accordion header — `.wr-collapse` is `overflow: hidden` and the
+// header fills it but for the 1px border, so an outset ring is clipped down to
+// a single row of halo.
 .wr-collapse__header:focus-visible {
   @include focus-ring;
+  outline-offset: -2px;
 }
 
 // Command palette options

package/theme/styles/_mixins.scss

@@ -1,7 +1,7 @@
 // Shared SCSS mixins.
 //
 // Available via:
-//   @use 'ngwr/theme/mixins' as wr;
+//   @use 'ngwr/theme' as wr;
 //   .thing { @include wr.smooth-br(0.625rem); }
 
 /// Smooth border-radius — opts into the native `corner-shape: squircle`

package/theme/styles/_variables.scss

@@ -3,6 +3,20 @@
 // These are the canonical knobs every component reads from. Consumers
 // override them on `:root` (or any subtree) without touching SCSS.
 
+/// The tokens here that are composed out of one the THEME re-tunes, kept in a
+/// mixin so `_dark.scss` can re-declare them on the themed element. See the long
+/// note above `colors.derived()`: a `var()` inside a custom property is
+/// substituted where it is DECLARED, so a `:root` composition inherits into a
+/// scoped `[data-theme="dark"]` subtree as the light literal.
+///
+/// Only the ring. The other compositions in this file — `--wr-control-font-size-*`,
+/// `--wr-transition-*`, `--wr-overlay-*` — read sizes and durations, which no
+/// theme flips, so freezing them is the same value either way.
+@mixin derived-focus-ring() {
+  --wr-focus-ring-color: var(--wr-color-primary);
+  --wr-focus-ring-halo: rgba(var(--wr-color-primary-rgb), 0.25);
+}
+
 :root {
   // Border radius
   --wr-border-radius-sm: 0.375rem;
@@ -45,11 +59,16 @@
   --wr-duration-fast: 0.1s;
   --wr-duration-base: 0.15s;
   --wr-duration-slow: 0.3s;
+  // unused-ok: the slow end of a public scale. The catalog's own animations top
+  // out at `-slow`; a consumer's need not.
   --wr-duration-slower: 0.5s;
 
   // Transition shorthands
   --wr-transition-short: var(--wr-duration-fast) var(--wr-ease-out);
   --wr-transition-base: var(--wr-duration-base) var(--wr-ease-linear);
+  // unused-ok: the third shorthand. Components compose `-slow` with an easing
+  // themselves where they need it, but dropping one rung out of three would make
+  // the set look arbitrary.
   --wr-transition-long: var(--wr-duration-slow) var(--wr-ease-out);
 
   // Elevation
@@ -65,6 +84,52 @@
   --wr-shadow-float: 0 8px 24px rgb(0 0 0 / 18%);
   --wr-shadow-modal: 0 20px 48px rgb(0 0 0 / 25%);
 
+  // Disabled
+  //
+  // How far a control fades when it will not respond. One number, because the
+  // catalog had **seven** — 0.6 in eighteen places, then 0.5, 0.7, 0.55, 0.4,
+  // 0.35 and 0.65 — spread over 29 entry points, and two components disagreed
+  // with THEMSELVES three ways inside one file (`date-picker` at 0.5 / 0.4 / 0.7,
+  // `calendar` at 0.5 / 0.35 / 0.6). Sibling text fields fading differently is
+  // not a design decision anyone made; it is what happens when the value has no
+  // name.
+  //
+  // 0.6 is the value eighteen of them already used. A component that genuinely
+  // needs another strength overrides this token in its own block, with the reason
+  // — the point is that the exception has to be argued rather than typed.
+  --wr-disabled-opacity: 0.6;
+
+  // Focus ring
+  //
+  // The keyboard indicator, as tokens rather than a recipe baked into SCSS —
+  // the ring was the one surface a consumer could not retheme, because
+  // `theme.focus-ring` hard-coded it.
+  //
+  // It is an OUTLINE now, and the halo is a second channel rather than the only
+  // one. The halo alone is a 25% tint of the primary over the page: **1.41:1 in
+  // light, 1.31:1 in dark**, where WCAG 1.4.11 asks 3:1 of a focus indicator —
+  // and the mixin also set `outline: none`, so for the forty-one selectors whose
+  // entire focus style is that mixin, nothing on screen met the bar. The solid
+  // token measures 4.89:1 and 4.07:1. Two components had already worked this out
+  // on their own, in three places, and hand-rolled
+  // `outline: 2px solid var(--wr-color-primary)` (`event-calendar` twice,
+  // `lightbox` once), and four more wrote an `outline-offset` next to the include
+  // that could never apply.
+  //
+  // An outline is also the only form the indicator survives in under
+  // `forced-colors`, which drops every `box-shadow` outright, and it is exempt
+  // from layout, so focus never reflows the box.
+  //
+  // Halo spread equals the offset on purpose: the halo fills exactly the gap the
+  // outline leaves, so the two read as one ring instead of two. A component that
+  // insets its outline (`outline-offset: -2px`, the idiom for a row inside an
+  // `overflow: hidden` container) keeps the halo outside, where its own clipping
+  // hides it.
+  // `-color` and `-halo` are composed off `--wr-color-primary`, so they live in
+  // `derived-focus-ring()` at the top of this file, included at the end of `:root`.
+  --wr-focus-ring-width: 2px;
+  --wr-focus-ring-offset: 2px;
+
   // Z-index scale
   //
   // Overlay panels inside the CDK container inherit its stacking; these
@@ -124,6 +189,8 @@
   --wr-tracking-wide: 0.025em;
   --wr-tracking-wider: 0.05em;
   --wr-tracking-widest: 0.1em;
+
+  @include derived-focus-ring;
 }
 
 // Shared open animation for overlay panels. Every overlay component

package/transfer/styles/_index.scss

@@ -11,7 +11,7 @@
   color: var(--wr-color-on-surface);
 
   &--disabled {
-    opacity: 0.6;
+    opacity: var(--wr-disabled-opacity);
   }
 
   &__pane {
@@ -31,11 +31,24 @@
     gap: 0.5rem;
     padding: 0.5rem 0.625rem;
     border-bottom: 1px solid var(--wr-color-outline);
-    background: rgba(var(--wr-color-outline-rgb), 0.25);
+    background: var(--wr-color-fill);
+    // The checkbox and the count are intrinsically sized, so on a narrow pane
+    // the title absorbed the entire shortfall: at 375px it was 26px of a 91px
+    // track and the headers read "A…" and "S…". Let the count drop to its own
+    // line before that happens — it is the one part of the row that reads fine
+    // anywhere. Nothing moves while the row fits (measured: identical at 190px
+    // and 430px panes).
+    flex-wrap: wrap;
   }
 
   &__title {
-    flex: 1 1 auto;
+    // A small basis rather than `auto`: the title has to be the item that
+    // yields, and with a content-sized basis a long title pushes ITSELF onto
+    // the next line, leaving the select-all checkbox alone on a row and the
+    // two panes of one transfer with headers of different heights. 3.5rem is
+    // the widest basis that still shares a row with the checkbox in the
+    // narrowest pane the component reaches (113px).
+    flex: 1 1 3.5rem;
     min-width: 0;
     overflow: hidden;
     text-overflow: ellipsis;
@@ -98,6 +111,16 @@
     height: 1rem;
   }
 
+  // The panes are a plain flex row, so they already swap: under `dir="rtl"` the
+  // source pane lays out at the right. The move chevrons are drawn to physical
+  // directions, though, so "move to target" ends up pointing at the pane it
+  // moves away from. Turn them around with the panes, the same way the
+  // pagination and carousel arrows do. Both move buttons are icon-only, so
+  // nothing textual is caught.
+  [dir='rtl'] &__move .wr-icon__svg {
+    transform: scaleX(-1);
+  }
+
   // No container query here on purpose: `@container` only styles DESCENDANTS, so
   // a rule that reflows `.wr-transfer` itself could never match its own query.
   // Doing it properly means the house `responsive` opt-in modifier (a wrapper