ngwr 11.2.0 → 12.1.0

package/table/styles/_index.scss

@@ -3,8 +3,8 @@
 .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);
+  --wr-table-head-bg: var(--wr-color-fill);
+  --wr-table-row-hover: var(--wr-color-fill-subtle);
   // 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
@@ -188,6 +188,15 @@
     transform: rotate(90deg);
   }
 
+  // The glyph is a chevron-RIGHT, so a closed row points into its own content
+  // under `dir="rtl"` instead of at the direction the children will indent.
+  // Turn it around with the tree, the way the cascader's branch arrow does.
+  // Scoped to the CLOSED state deliberately: `scaleX(-1)` composed over the open
+  // state's `rotate(90deg)` resolves to "up", not "down".
+  [dir='rtl'] &__tree-toggle:not(.wr-table__tree-toggle--open) &__tree-icon {
+    transform: scaleX(-1);
+  }
+
   // Card mode stacks label / value with `justify-content: space-between`, so an
   // extra inline child would strand the chevron mid-row. Fold the lead into the
   // value side instead.
@@ -255,9 +264,14 @@
     transform: rotate(90deg);
   }
 
+  // Same chevron-right, same mirror — closed state only. See `__tree-icon` above.
+  [dir='rtl'] &__expand-btn:not(.wr-table__expand-btn--open) &__expand-icon {
+    transform: scaleX(-1);
+  }
+
   &__detail-row > &__detail {
     padding: 0.875rem 1rem;
-    background: rgba(var(--wr-color-outline-rgb), 0.08);
+    background: var(--wr-color-fill-subtle);
     border-bottom: 1px solid var(--wr-table-border);
   }
 
@@ -322,21 +336,36 @@
   }
 
   // Separating shadow on the inner edge of each pinned group. `box-shadow` has
-  // no logical form — its offset is always physical — and the cell it belongs to
-  // is anchored by `[style.left.px]` / `[style.right.px]` in table.html, written
-  // from `leftPin()` / `rightPin()`. The shadow leans the way the offset pins.
+  // no logical form — its offset is always physical — while the cell it belongs
+  // to is anchored by `[style.inset-inline-start.px]` / `[style.inset-inline-end.px]`
+  // in table.html, written from `leftPin()` / `rightPin()`. The shadow leans the
+  // way the offset pins, so the sign has to be set per direction by hand.
   &__th--pin-edge-left,
   &__td--pin-edge-left {
-    // rtl-ok: physical offset matching the physical `left` pin set by the component
+    // rtl-ok: `box-shadow` has no logical form; the RTL sign is set explicitly below
     box-shadow: 0.375rem 0 0.375rem -0.25rem rgba(0, 0, 0, 0.18);
   }
 
   &__th--pin-edge-right,
   &__td--pin-edge-right {
-    // rtl-ok: physical offset matching the physical `right` pin set by the component
+    // rtl-ok: `box-shadow` has no logical form; the RTL sign is set explicitly below
+    box-shadow: -0.375rem 0 0.375rem -0.25rem rgba(0, 0, 0, 0.18);
+  }
+
+  // Under `dir="rtl"` the start-pinned group sits at the physical right and the
+  // end-pinned group at the physical left, so both shadows point the other way.
+  [dir='rtl'] &__th--pin-edge-left,
+  [dir='rtl'] &__td--pin-edge-left {
+    // rtl-ok: this IS the RTL sign for the rule above
     box-shadow: -0.375rem 0 0.375rem -0.25rem rgba(0, 0, 0, 0.18);
   }
 
+  [dir='rtl'] &__th--pin-edge-right,
+  [dir='rtl'] &__td--pin-edge-right {
+    // rtl-ok: this IS the RTL sign for the rule above
+    box-shadow: 0.375rem 0 0.375rem -0.25rem rgba(0, 0, 0, 0.18);
+  }
+
   &__th-inner {
     display: inline-flex;
     align-items: center;
@@ -393,10 +422,15 @@
     backdrop-filter: blur(2px);
     // Above the pinned sticky cells (th z-index 2), so loading veils them too.
     z-index: 3;
+    // A positioned box over the whole table swallowed every click while leaving
+    // the keyboard untouched — sort headers, row checkboxes and the pager all
+    // stayed operable by Tab + Enter. The veil is a marker (the host carries
+    // `aria-busy`), not a shield, so it stops eating the pointer too.
+    pointer-events: none;
   }
 
   // --- Row grouping ---------------------------------------------------------
-  --wr-table-group-bg: rgba(var(--wr-color-outline-rgb), 0.18);
+  --wr-table-group-bg: var(--wr-color-fill-subtle);
 
   &__group-cell {
     // NOTE: never add `overflow` here — the inner box below is `position: sticky`
@@ -451,6 +485,14 @@
     transform: none; // collapsed — chevron points right
   }
 
+  // …which is the wrong way round under `dir="rtl"`, where the label the arrow
+  // discloses sits to its left. Mirror the collapsed state only — the expanded
+  // one already points down, and `scaleX(-1)` over its `rotate(90deg)` would
+  // point it up. See `__tree-icon` above.
+  [dir='rtl'] &__group-row--collapsed &__group-icon {
+    transform: scaleX(-1);
+  }
+
   &__group-label {
     // Cap intrinsic width: in the default (auto) layout a colspan cell's
     // min-content is spread across columns, so an ellipsizing shrinkable label
@@ -465,7 +507,14 @@
     flex: 0 0 auto;
     padding: 0 0.375rem;
     border-radius: var(--wr-border-radius-pill);
-    background: rgba(var(--wr-color-outline-rgb), 0.5);
+    // `-subtle`, not `-strong`: this chip is the SECOND tint in the stack — it
+    // sits on the group row, which already paints `--wr-table-group-bg`
+    // (`-fill-subtle`) over the table's own surface. At `-strong` the pair
+    // composited to #dee5ed, and `--wr-color-on-surface-muted` is calibrated
+    // against the plain surface (5.35:1) and the lightest one the library
+    // paints (4.63:1) — on that composite it fell to 4.21:1, under AA. The same
+    // double-tint trap the event-calendar header comment records.
+    background: var(--wr-color-fill-subtle);
     color: var(--wr-color-on-surface-muted);
     font-size: var(--wr-text-xs);
     font-weight: 500;
@@ -784,7 +833,7 @@
     cursor: pointer;
 
     &:hover {
-      background: rgba(var(--wr-color-outline-rgb), 0.35);
+      background: var(--wr-color-fill);
     }
   }
 
@@ -853,7 +902,7 @@
   // the same defaults that block sets. `--wr-density-*` and `--wr-color-*` are
   // root-level and resolve as-is.
   padding: calc(0.625rem * var(--wr-density-y, 1)) calc(0.875rem * var(--wr-density-x, 1));
-  background: var(--wr-table-head-bg, rgba(var(--wr-color-outline-rgb), 0.25));
+  background: var(--wr-table-head-bg, var(--wr-color-fill));
   color: var(--wr-color-on-surface-muted);
   font-family: var(--wr-font-family-base);
   font-weight: 600;

package/tabs/styles/_index.scss

@@ -113,7 +113,7 @@
 
     &--disabled,
     &:disabled {
-      opacity: 0.5;
+      opacity: var(--wr-disabled-opacity);
       cursor: not-allowed;
     }
   }

package/textarea/styles/_index.scss

@@ -33,7 +33,7 @@
 
   &--disabled {
     --wr-textarea-color: var(--wr-color-on-surface-muted);
-    --wr-textarea-bg: rgba(var(--wr-color-outline-rgb), 0.35);
+    --wr-textarea-bg: var(--wr-color-fill);
     cursor: not-allowed;
   }
 

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`