@helloimjolopez-pathway/pathway-tokens 11.0.0 → 11.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Design system for Ministry Brands Amplify. Tokens + components + specifications, all versioned in one place, with Storybook deployed from `main`.
 
-> **Looking for the tokens?** → **[TOKENS.md](TOKENS.md)** — where the CSS lives, which
+> **Looking for the tokens?** → **[TOKENS.md](TOKENS.md)**, where the CSS lives, which
 > of the 284 names you may use, and what to link in what order.
 
 ## Using the tokens
@@ -16,14 +16,14 @@ one name set rather than each having their own.
 
 | | Count | Name these? |
 |---|---|---|
-| Colour (`themes/light.css`, `themes/midnight.css` — same names) | **186** | Yes |
+| Colour (`themes/light.css`, `themes/midnight.css`, same names) | **186** | Yes |
 | Type scale (`type.css`) | 41 | Yes |
 | Spacing, radii, borders (`layout.css`) | 40 | Yes |
 | Motion (`motion.css`) | 17 | Yes |
 | Sheet and TopNav padding (`layout-responsive.css`) | 6 | Yes |
 | Breakpoints (`breakpoints.css`) | 5 | Yes |
 | **Working vocabulary** | **284** | |
-| Raw ramps (`primitives.css`) | 350 | **No** — but you must load it |
+| Raw ramps (`primitives.css`) | 350 | **No**, but you must load it |
 | Component metrics (`layout-contextual.css`) | 26 | This repo's components |
 
 **The CSS lives in [`src/tokens/`](src/tokens/), and that folder has its own README**
@@ -40,8 +40,7 @@ npm install @helloimjolopez-pathway/pathway-tokens
 NuGet: `Pathway.DesignTokens`.
 
 ```js
-// Every stylesheet is a named subpath export. primitives.css MUST come first —
-// the themes resolve through it, so without it all colour resolves to nothing
+// Every stylesheet is a named subpath export. primitives.css MUST come first, // the themes resolve through it, so without it all colour resolves to nothing
 // and the page renders unstyled with no console error.
 import "@helloimjolopez-pathway/pathway-tokens/primitives.css";
 import "@helloimjolopez-pathway/pathway-tokens/themes/light.css";
@@ -92,8 +91,7 @@ as too granular to adopt. Retired 2026-09-03 and not coming back.
 ```
 
 One name carries both modes. Set `data-theme="midnight"` on `<html>` to flip the page,
-or on any element to flip just that subtree. Never write a mode into a property name —
-`--semantic-color-light-mode-*` resolves to nothing.
+or on any element to flip just that subtree. Never write a mode into a property name, `--semantic-color-light-mode-*` resolves to nothing.
 
 ### Can I use a primitive?
 
@@ -129,7 +127,7 @@ pathway-ds/
 ├── scripts/                     Token sync/audit/fix + component build scripts
 ```
 
-## Governance — where things live
+## Governance: where things live
 
 | To change… | Where |
 |---|---|
@@ -146,15 +144,15 @@ pathway-ds/
 
 Three workflows in `.github/workflows/`:
 
-1. **`sync-tokens.yml`** — fires when `tokens/figma-export/**` changes. Normalises the Figma export into the W3C DTCG JSON and commits `tokens/pathway-design-tokens.json`.
-2. **`sync-component.yml`** — fires when `components/sidenav/sidenav.html` changes. Regenerates the `sidenav-figmamake.html` variant and commits it.
-3. **`deploy-pages.yml`** — fires on every push to `main`. Builds Style Dictionary and Storybook fresh and deploys a clean `_site` artifact through the official Pages actions. Nothing is committed back to `main`. (`deploy-storybook.yml` is the retired predecessor, kept manual-only; it committed 14MB of build output per push.)
+1. **`sync-tokens.yml`**, fires when `tokens/figma-export/**` changes. Normalises the Figma export into the W3C DTCG JSON and commits `tokens/pathway-design-tokens.json`.
+2. **`sync-component.yml`**, fires when `components/sidenav/sidenav.html` changes. Regenerates the `sidenav-figmamake.html` variant and commits it.
+3. **`deploy-pages.yml`**, fires on every push to `main`. Builds Style Dictionary and Storybook fresh and deploys a clean `_site` artifact through the official Pages actions. Nothing is committed back to `main`. (`deploy-storybook.yml` is the retired predecessor, kept manual-only; it committed 14MB of build output per push.)
 
 Source of truth is always the repo on `main`; Storybook is a downstream artifact.
 
 ## Typography (brand fonts)
 
-Pathway uses **Red Hat Text** (all UI text) and **Red Hat Display** (headings H1–H3 only). Both are open-source Google Fonts.
+Pathway uses **Red Hat Text** (all UI text) and **Red Hat Display** (headings H1H3 only). Both are open-source Google Fonts.
 
 **Load via CDN (web/prototypes):**
 
@@ -170,6 +168,174 @@ Pathway uses **Red Hat Text** (all UI text) and **Red Hat Display** (headings H1
 
 Licensed under the [SIL Open Font License](https://scripts.sil.org/OFL). Free for any use.
 
+## The components
+
+Everything in the library, with the four things you need for each: what it is
+specified as, what implements it, where to see it running, and which Figma node
+it was measured from. This table is generated from
+[`components/manifest.json`](components/manifest.json) by
+`npm run build-component-index`, so it cannot drift from the registry.
+
+<!-- BEGIN component-index (generated by scripts/build-component-index.js) -->
+
+**17 components with their own page, 2 building blocks that only exist nested.**
+
+| Component | Spec | Module | Storybook | Figma node | Code Connect files |
+|---|---|---|---|---|---|
+| **SideNav** | [spec](components/sidenav/sidenav-spec.md) | [`sidenav.jsx`](components/sidenav/sidenav.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-sidenav--docs) | `40004059:1375` | 9 |
+| **Scrollable** | [spec](components/scrollbar/scrollbar-spec.md) | [`scrollbar.jsx`](components/scrollbar/scrollbar.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-scrollbar--docs) | repo only, not in Figma | 0 |
+| **Checkbox** | [spec](components/checkbox/checkbox-spec.md) | [`checkbox.jsx`](components/checkbox/checkbox.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-checkbox--docs) | `40002324:54532` | 1 |
+| **OrgSwitcher** | [spec](components/org-switcher/org-switcher-spec.md) | [`org-switcher.jsx`](components/org-switcher/org-switcher.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-orgswitcher--docs) | `40006819:14583` | 2 |
+| **TopNav.Global** | [spec](components/top-nav/top-nav-spec.md) | [`top-nav.jsx`](components/top-nav/top-nav.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-topnav--docs) | `40007067:6508` | 4 |
+| **Spinner** | [spec](components/spinner/spinner-spec.md) | [`spinner.jsx`](components/spinner/spinner.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-spinner--docs) | `40006622:50003` | 0 |
+| **Button** | [spec](components/button/button-spec.md) | [`button.jsx`](components/button/button.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-button--docs) | `40003293:93741` | 3 |
+| **Search** | [spec](components/search/search-spec.md) | [`search.jsx`](components/search/search.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-global-search-top-nav--docs) | `40007095:4048` | 1 |
+| **NavShell** | [spec](components/nav-shell/nav-shell-spec.md) | composed, see its stories | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-navshell--docs) | 3 sets on page `Navigation: Top Nav, Navigation: Side Nav, Page Template` | 0 |
+| **Widget** | [spec](components/widget/widget-spec.md) | [`widget.jsx`](components/widget/widget.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-widget--docs) | `40009622:39702` | 2 |
+| **KPI Tile** | [spec](components/kpi-tile/kpi-tile-spec.md) | [`kpi-tile.jsx`](components/kpi-tile/kpi-tile.jsx)<br>[`kpi-number-trend.jsx`](components/kpi-tile/kpi-number-trend.jsx)<br>[`mini-chart.jsx`](components/kpi-tile/mini-chart.jsx)<br>[`bar-chart.jsx`](components/kpi-tile/bar-chart.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-kpi-tile--docs) | 7 sets on page `40009862:10309` | 9 |
+| **Dashboard** | [spec](components/dashboard/dashboard-spec.md) | [`dashboard.jsx`](components/dashboard/dashboard.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-dashboard--docs) | no Figma component | 0 |
+| **Icon** | [spec](components/icon/icon-spec.md) | [`icon.jsx`](components/icon/icon.jsx)<br>[`action-icon.jsx`](components/icon/action-icon.jsx)<br>[`display-icon.jsx`](components/icon/display-icon.jsx)<br>[`featured-icon.jsx`](components/icon/featured-icon.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-action-icon--docs) | `48:1153` | 4 |
+| **Dropdown** | [spec](components/dropdown/dropdown-spec.md) | [`dropdown.jsx`](components/dropdown/dropdown.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-dropdown--docs) | `40005568:4207` | 3 |
+| **Mini Chart** | [spec](components/kpi-tile/mini-chart-spec.md) | [`mini-chart.jsx`](components/kpi-tile/mini-chart.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-mini-chart--docs) | `40009415:27919` | 1 |
+| **Bar Chart** | [spec](components/kpi-tile/bar-chart-spec.md) | [`bar-chart.jsx`](components/kpi-tile/bar-chart.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-bar-chart--docs) | `40009417:13029` | 3 |
+| **Page Template** | [spec](components/page-template/page-template-spec.md) | [`page-template.jsx`](components/page-template/page-template.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-page-template--docs) | `40009709:26016` | 0 |
+
+Building blocks. Each is mapped for Code Connect and specced, but has no page
+of its own because it only ever appears as a nested instance inside the
+component above it.
+
+| Component | Spec | Module | Storybook | Figma node | Code Connect files |
+|---|---|---|---|---|---|
+| **ModuleIcon** | [spec](components/module-icon/module-icon-spec.md) | [`module-icon.jsx`](components/module-icon/module-icon.jsx) | nested only | `40006876:42134` | 1 |
+| **TopNav.Actions** | [spec](components/top-nav-actions/top-nav-actions-spec.md) | [`top-nav.jsx`](components/top-nav/top-nav.jsx) | [open](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/library-topnav--docs) | `40007082:7313` | 1 |
+
+<!-- END component-index -->
+
+### What is checked, and what is not
+
+Two suites. `npm run build-dist` runs the token-integrity checks, and
+`npm run check-tokens` runs the documentation and story checks, so both fail a
+build rather than relying on someone noticing.
+
+In `build-dist`:
+
+| Check | What it catches |
+|---|---|
+| `check-demo-tokens` | a document naming a token that does not exist |
+| `check-token-refs` | a reference to the retired `--semantic-color-light-mode-*` form |
+| `check-token-names` | a name that is not kebab-case lowercase |
+| `check-token-object-refs` | a `T`/`L` object key referenced but never defined |
+| `check-ladder-order` | a ladder whose names disagree with its resolved luminance |
+| `check-state-distinctness` | an interaction state indistinguishable from another state in its group |
+| `check-variant-distinctness` | a component prop that has stopped changing anything |
+| `check-fill-foreground-pairs` | a fill with no paired `On Subtle` / `On Strong` foreground, or the reverse |
+| `check-motion-coverage` | a state change with no transition, or a partial one |
+| `fix-stale-doc-hex --check` | a hand-copied hex in a doc that no longer matches its token |
+| `check-story-yield` | a token docs page rendering less content than its floor |
+
+In `check-tokens`, additionally:
+
+| Check | What it catches |
+|---|---|
+| `build-component-index --check` | the component table above out of step with the manifest, and a Storybook link in it that is not in the build |
+| `check-spec-stories` | a spec whose Storybook section names a story that does not exist, or omits one that does |
+| `check-demo-links` | a standalone demo linking a stylesheet or script that is not served where the page is served. All twelve demos linked `../../src/tokens/*.css`, which resolves in the repo and NOWHERE ELSE: the built Storybook mounts `components/` only, and Pages copies `components/` while putting the token contract at `/tokens/`. Verified against the live site on 2026-10-08, `/src/tokens/primitives.css` was 404. Every `StandaloneDemo` story and every published demo URL had been loading nine 404s and rendering on fallback colours rather than Pathway's. `pathway-sidenav.html` was worse: it loaded `../../dist/pathway-sidenav.js`, which is gitignored and never published, so that page had no script at all and rendered nothing. |
+| `check-component-tables` | a component that keeps its measurements as data naming a key its lookup object does not define. `KPI_TILE_SPECS` named `gapChart03`, `L` had no such key, so the value was undefined, React dropped the style and CSS fell back to no gap. Nothing threw and no story was blank. |
+
+And the ones that need a built Storybook, so they are their own command,
+`npm run verify-storybook`:
+
+| Check | What it catches |
+|---|---|
+| `check-syntax` | a component or story file that does not parse. Redundant with the build and worth it anyway: it parses all 54 files in about a second, where the build takes three minutes and reports the same error as a WARN line far above the failure |
+| `check-stories-render` | a story that renders NOTHING while the build stays green |
+| `check-mdx-refs` | a docs page referencing a story that does not exist, which renders an empty block, and a `<Controls>` pointed at a story with no argTypes, which renders an empty table under a heading promising controls |
+| `check-accessible-names` | a button with no accessible name, resolved the way a browser does: `aria-label`, `aria-labelledby`, text content with `aria-hidden` subtrees removed, then `title` |
+
+**That last one matters more than it sounds.** A module-level error in a CSF
+file blanks every story in that file and webpack compiles it happily. It has
+happened three times here: a leftover `storyName` assignment after a rename
+blanked all nine Global Search stories, a dangling `BRAND_AXIS` reference
+blanked more, and `useState` used without being imported blanked the Widget
+Glance configurations story. The check loads all 107 stories in headless Chrome
+and fails on an empty root. It was verified by breaking a story on purpose: the
+build reported no errors and the check reported the blank page.
+
+**`check-accessible-names` found 101 on its first run,** all of them Buttons.
+Every labelled Pathway Button announced as just "button": `aria-label` was set
+only when `showText` was false, on the rule that a button showing its text does
+not need a label. True of an ordinary button, false here, because the text sat
+inside `pw-button__container`, which carried `aria-hidden="true"`, so the name
+computation skipped it. The only named case was the icon-only one, which is
+backwards. Fixed by removing that `aria-hidden` rather than adding a label, so
+the name comes from the visible text and cannot drift from it.
+
+**Standalone demos are generated now, for the three newest components.**
+`scripts/build-demos.js` bundles the real module with esbuild and writes the
+page around it, so Widget, KPI Tile and Dashboard have a hands-on resize demo
+that cannot fall behind the component. The twelve older demos are hand-written
+and each says, at the top of its script block, "Mirrors `<name>.jsx` exactly.
+Keep the two in step": a second implementation of a shipped component, kept
+correct by memory. Converting them is a separate job. Their token links were
+repointed at `components/_demo/tokens/` so they at least render.
+
+**What is NOT checked, and why it matters.**
+
+- **Code Connect verifies nothing.** It publishes a code snippet to a Figma
+  component. It never compares a token value, a measurement or a layout, and it
+  flows repo to Figma only. A component can be fully mapped and completely
+  wrong.
+- **The token checks confirm that a name RESOLVES, not that it is the right
+  name.** `check-fill-foreground-pairs` proves every fill HAS a paired
+  foreground; nothing measures the pair a component actually uses against a
+  contrast ratio per mode. Button's Primary and Negative labels sat on the mono
+  anchor at 3.04:1 and 2.85:1 in Midnight while every check passed.
+- **Nothing can verify a Figma node id from here.** Only Figma knows whether an
+  id resolves and what kind of thing it is, and the MCP is interactively
+  authenticated, so this needs an agent session.
+  `npm run check-figma-nodes` does the half that can be automated: it lists
+  every id the repo cites, where each is cited, and which are cited as a set.
+
+So drift between Figma and this repo is the normal state, not the exception,
+and only measurement finds it. A sweep on 2026-10-07 found four defects of that
+class that had each survived months: two cited ids that do not exist in the
+file at all, Search's node pointing at a 2594x1680 layout frame rather than a
+component, and NavShell's pointing at a variant rather than its set.
+
+A second sweep on 2026-10-12 found three more. NavShell cited `ScreenTemplate`
+as though it owned it: there is no NavShell set in the file, so the manifest now
+names the three sets it composes and says so. `icon-spec.md` held the whole
+14-section spec twice, 645 lines, the second copy still describing the retired
+single `Icon` Storybook page. The Page Template page's second
+`Page Template` frame is the Midnight Mode showcase: instances of the one
+`ScreenTemplate` set under a `Semantic: Color` override to `Amplify Dark`, one
+of them also overridden to `Tablet 798pt`.
+
+That last one is in this list as a defect of MINE, not of the file. On
+2026-10-12 the manifest and a commit message both called those four nodes
+duplicate component sets. They are one set and two instances of it. The error
+came from comparing bound fill variables, which are identical across modes
+because a variable is the same variable in every mode, and never reading
+`explicitVariableModes`, which is the only thing that marks a mode showcase.
+When two nodes look identical in Figma, read the mode override before
+concluding anything.
+
+### Walking through one
+
+Take Widget as the shape of it. Open [`components/widget/widget-spec.md`](components/widget/widget-spec.md)
+for the anatomy, the token table, the size ladder and the grid; open the
+Storybook page for the same thing running, with a Playground, a size ladder at
+the exact Figma boxes, and two token listings that resolve against the live
+document; open [`components/widget/widget.jsx`](components/widget/widget.jsx)
+for the implementation, where every measurement carries the Figma node it came
+from. The Code Connect file next to it is what makes the Figma component offer
+this code, and it publishes repo to Figma only.
+
+Widget, KPI Tile and Dashboard are three components, not three views of one.
+A Widget is a container that does not know what it holds. A KPI Tile is a card
+in its own right. Both nest the same building block, `KpiNumberAndTrend`, which
+has no card of its own and gets one from whatever nests it.
+
 ## Component-to-token map
 
 `tokens/component-token-map.json` maps every component element to its CSS variable. Use this file to answer "which token does X use?" without reading specs.

package/components/scrollbar/scrollbar.jsx

@@ -1,16 +1,16 @@
 /**
- * Scrollable — Pathway Design System
+ * Scrollable, Pathway Design System
  *
  * A reusable overlay-scrollbar wrapper. Hides the native OS scrollbar entirely and renders
  * one custom liquid-glass thumb so scrolling looks and behaves IDENTICALLY on macOS, Windows,
- * iOS, and Android (native scrollbars can't be made consistent — this sidesteps them).
+ * iOS, and Android (native scrollbars can't be made consistent: this sidesteps them).
  *
  * Behaviour (see components/scrollbar/scrollbar-spec.md):
  *   - Thumb height is PROPORTIONAL to content: (viewport / total) × track, floored at 28px.
  *   - Reveal: appears while scrolling, fades ~900ms after; also appears when the MOUSE is near
  *     the right-edge bar (so it can be grabbed). It does NOT appear from hovering the panel.
  *   - Drag: MOUSE only, via a wider invisible grab strip (the 6px thumb alone is hard to hit).
- *   - Touch: passive — the bar just shows position; you scroll by swiping content. The grab
+ *   - Touch: passive: the bar just shows position; you scroll by swiping content. The grab
  *     strip is disabled on touch devices via a `(hover: none)` rule.
  *   - Keyboard / a11y: the content scrolls natively (arrows, PageUp/Down, Home/End, Space); the
  *     thumb is decorative (`aria-hidden`) and never the only scroll mechanism.
@@ -20,16 +20,17 @@
  */
 
 import React, { useRef, useState, useEffect, useCallback } from "react";
+import { useReducedMotion } from "../_shared/use-reduced-motion.jsx";
 
 // ─── TOKENS ──────────────────────────────────────────────────────────────────
-// Every colour + unit resolves through a SEMANTIC Pathway token — no primitives,
+// Every colour + unit resolves through a SEMANTIC Pathway token: no primitives,
 // no hardcoded hex/px. Motion uses the --motion-* tokens (durations/easings from design-system-spec §2).
 export const SCROLL = {
-  thumbWidth:  "var(--semantic-layout-units-padding-xtight)",     // 6px — visible thumb thickness
+  thumbWidth:  "var(--semantic-layout-units-padding-xtight)",     // 6px: visible thumb thickness
   thumbRadius: "var(--semantic-layout-units-cornerradius-full)",  // fully-rounded pill
-  thumbMin:    28,                                                // px — min thumb length (grab-target floor); JS layout math
-  gutter:      "var(--semantic-layout-units-padding-xxxtight)",   // 2px — inset from the right edge
-  grabZone:    16,                                                // px — invisible mouse grab strip (wider than the 6px thumb so it's catchable)
+  thumbMin:    28,                                                // px, min thumb length (grab-target floor); JS layout math
+  gutter:      "var(--semantic-layout-units-padding-xxxtight)",   // 2px, inset from the right edge
+  grabZone:    16,                                                // px, invisible mouse grab strip (wider than the 6px thumb so it's catchable)
   // THE LIGHT RUNGS ARE A DELIBERATE CHOICE BY THE DESIGN OWNER. Do not raise
   // them again without asking Jo first.
   //
@@ -43,14 +44,25 @@ export const SCROLL = {
   // an overlay scrollbar is a redundant affordance (the content scrolls with or
   // without it, and the OS bar remains). So contrast is bought back with SIZE
   // and PRESENCE rather than with darkness: see thumbWidth and the grab strip.
-  thumbRest:   "var(--semantic-color-scrim-faint)",    // black 16% — faint overlay (rest)
-  thumbHover:  "var(--semantic-color-scrim-light)",    // black 24% — hover/drag
+  // Scrim/Faint and Scrim/Light resolve to Cool Neutral 800, so the thumb was
+  // drawing a COOL grey over warm surfaces and reading as a cold bar against
+  // them. Reported 2026-10-02. The comment below has always said "light warm
+  // overlay": the value simply did not match it.
+  //
+  // Scrim is also the wrong family: it is the modal backdrop, where a cool
+  // near-black is right. The thumb is an overlay on a surface, and under the
+  // alpha rule surfaces and fills are WARM. So the thumb now resolves through
+  // its own themed custom properties, set in the injected sheet below off the
+  // warm neutral alpha primitives. No new design token: a component-local
+  // property, the same mechanism the Widget uses for its column spans.
+  thumbRest:   "var(--pw-scrollbar-thumb-rest)",    // warm neutral 16%
+  thumbHover:  "var(--pw-scrollbar-thumb-hover)",   // warm neutral 24%
   thumbBlur:   "blur(8px) saturate(180%)",
   // Hairline glass edge: semantic white at 35% via color-mix.
   thumbEdge:   "inset 0 0 0 0.5px color-mix(in srgb, var(--semantic-color-fill-static-neutral-faint) 35%, transparent)",
   // Fade OUT gracefully, but appear INSTANTLY. Animating opacity on the way in
   // multiplied the thumb's own alpha by the in-flight opacity, so during the
-  // 200ms glide-in it rendered as low as 1.18:1 — below the floor at the exact
+  // 200ms glide-in it rendered as low as 1.18:1, below the floor at the exact
   // moment the user is looking for it. Only the fade-out is animated now.
   // Asymmetric fade: snappy decelerate glide-IN, graceful fade-OUT. Each entry
   // names every property it is responsible for, because the element swaps
@@ -72,13 +84,24 @@ if (typeof document !== "undefined" && !document.getElementById("pds-scrollable-
   const s = document.createElement("style");
   s.id = "pds-scrollable-base";
   s.textContent =
+    // Warm neutral, and it has to INVERT: 500 is the dark warm grey for a light
+    // surface, 100 the light warm grey for a dark one. An inline style cannot
+    // branch on [data-theme], which is why these live here rather than in the
+    // SCROLL map above.
+    ":root,[data-theme=\"light\"]{" +
+      "--pw-scrollbar-thumb-rest:var(--primitive-color-warm-neutral-500-16);" +
+      "--pw-scrollbar-thumb-hover:var(--primitive-color-warm-neutral-500-24)}" +
+    "[data-theme=\"midnight\"],[data-theme=\"dark\"]{" +
+      "--pw-scrollbar-thumb-rest:var(--primitive-color-warm-neutral-100-16);" +
+      "--pw-scrollbar-thumb-hover:var(--primitive-color-warm-neutral-100-24)}" +
     ".pds-scrollable__view{scrollbar-width:none;-ms-overflow-style:none}" +
-    ".pds-scrollable__view::-webkit-scrollbar{width:0;height:0;display:none}" +
+    ".pds-scrollable__view:-webkit-scrollbar{width:0;height:0;display:none}" +
     "@media (hover: none){.pds-scrollable__grab{pointer-events:none!important}}";
   document.head.appendChild(s);
 }
 
 export function Scrollable({ children, className = "", style = {}, viewClassName = "", viewStyle = {} }) {
+  const noMotion = useReducedMotion();
   const viewRef = useRef(null);
   const dragRef = useRef(null);
   const idleRef = useRef(null);
@@ -119,7 +142,7 @@ export function Scrollable({ children, className = "", style = {}, viewClassName
   const onScroll = () => { recompute(); wake(); };
 
   // Edge-proximity reveal (mouse): show the bar when the cursor is within grabZone of the right
-  // edge, so it can be grabbed — but NOT from hovering the rest of the panel.
+  // edge, so it can be grabbed: but NOT from hovering the rest of the panel.
   const onMouseMove = (e) => {
     const rect = e.currentTarget.getBoundingClientRect();
     if (rect.right - e.clientX <= SCROLL.grabZone) {
@@ -173,7 +196,7 @@ export function Scrollable({ children, className = "", style = {}, viewClassName
 
       {thumb.show && (
         <>
-          {/* Visual thumb — decorative, never intercepts pointer events. */}
+          {/* Visual thumb, decorative, never intercepts pointer events. */}
           <div
             aria-hidden="true"
             style={{
@@ -182,11 +205,11 @@ export function Scrollable({ children, className = "", style = {}, viewClassName
               background: hot ? SCROLL.thumbHover : SCROLL.thumbRest,
               backdropFilter: SCROLL.thumbBlur, WebkitBackdropFilter: SCROLL.thumbBlur,
               boxShadow: SCROLL.thumbEdge,
-              opacity: active ? 1 : 0, transition: active ? SCROLL.fadeIn : SCROLL.fadeOut,
+              opacity: active ? 1 : 0, transition: noMotion ? "none" : (active ? SCROLL.fadeIn : SCROLL.fadeOut),
               pointerEvents: "none", zIndex: 5,
             }}
           />
-          {/* Invisible mouse grab strip — wider than the thumb so it's catchable; disabled on
+          {/* Invisible mouse grab strip, wider than the thumb so it's catchable; disabled on
               touch via the (hover:none) rule so finger-swipes scroll the content beneath. */}
           <div
             aria-hidden="true"