fix(ui): tokenise globals motion/z, Ward PRM, hash scroll clamp

docs/design-system/GATES.md

@@ -128,7 +128,7 @@ because it contributed nothing.
 `tests/ui-style-contract.spec.ts`) — do not re-litigate. Overlay z-index vs
 named `--z-*` tokens is **implemented-blocking** in the same spec (`overlay
 z-index computed tokens`); class-string assertions are forbidden; the
-`rawCssZIndices` exception baseline stays at 8 in `globals.css`. Still planned
+`rawCssZIndices` exception baseline stays at 4 in `globals.css`. Still planned
 (PR 1–2): Tailwind conflict order · v2 cascade, ancestor **and** same-node
 forms · target geometry · contrast · print token reset. Class-string assertions
 are not accepted for any of these — computed values only.

src/app/globals.css

@@ -501,6 +501,12 @@
   --disabled: #8794a8;
   --focus: var(--clinical-accent);
   --overlay-backdrop: rgb(4 8 14 / 56%);
+  /* Documented stacking ladder (TOKENS). Live overlay/popover/modal/toast plus
+     v2 base/raised/chrome. Do not invent rungs; z-index:30 phone stack and
+     z-index:2 carets have no named token and stay literal. */
+  --z-base: 0;
+  --z-raised: 10;
+  --z-chrome: 60;
   --z-overlay: 80;
   --z-popover: 95;
   --z-modal: 100;
@@ -1250,9 +1256,9 @@ summary::-webkit-details-marker {
       0 8px 24px rgb(16 24 40 / 8%);
     backdrop-filter: blur(18px) saturate(140%);
     transition:
-      border-color 180ms var(--ease-out-soft),
-      box-shadow 180ms var(--ease-out-soft),
-      transform 180ms var(--ease-spring);
+      border-color var(--duration-base) var(--ease-out-soft),
+      box-shadow var(--duration-base) var(--ease-out-soft),
+      transform var(--duration-base) var(--ease-spring);
   }
 }
 
@@ -1282,6 +1288,7 @@ summary::-webkit-details-marker {
   position: absolute;
   inset-inline: 0;
   top: 0;
+  /* Below the documented ladder; no --z rung for underlay scrims. */
   z-index: -1;
   height: max(6.5rem, calc(var(--safe-area-top) + 5.5rem));
   overflow: hidden;
@@ -1323,7 +1330,7 @@ summary::-webkit-details-marker {
   position: fixed;
   inset-inline: 0;
   bottom: 0;
-  z-index: 0;
+  z-index: var(--z-base);
   height: max(6.5rem, calc(var(--safe-area-bottom) + 5.25rem));
   background: linear-gradient(
     180deg,
@@ -1351,7 +1358,7 @@ summary::-webkit-details-marker {
 .differentials-mobile-compare-fab {
   pointer-events: none;
   position: relative;
-  z-index: 10;
+  z-index: var(--z-raised);
   display: flex;
   width: 100%;
   justify-content: center;
@@ -1381,6 +1388,7 @@ summary::-webkit-details-marker {
   letter-spacing: -0.01em;
   box-shadow: 0 18px 42px rgb(0 0 0 / 24%);
   touch-action: manipulation;
+  /* 160ms has no duration rung — do not invent one; nearest is --duration-quick (150ms). */
   transition:
     transform 160ms var(--ease-spring),
     background-color 160ms var(--ease-out-soft),
@@ -1411,7 +1419,7 @@ summary::-webkit-details-marker {
 .patient-details-fab {
   pointer-events: none;
   position: relative;
-  z-index: var(--z-raised, 10);
+  z-index: var(--z-raised);
   display: flex;
   width: 100%;
   justify-content: center;
@@ -1492,7 +1500,7 @@ summary::-webkit-details-marker {
    and disabled behaviour come from the design system, per COMPONENTS.md 9.1. */
 .therapy-compare-tray {
   position: relative;
-  z-index: var(--z-raised, 10);
+  z-index: var(--z-raised);
   display: flex;
   width: 100%;
   align-items: center;
@@ -1606,7 +1614,7 @@ summary::-webkit-details-marker {
   inset-inline: 0;
   bottom: 0;
   top: auto;
-  z-index: 0;
+  z-index: var(--z-base);
   height: var(--footer-scrim-height);
   overflow: hidden;
   /* Localized glass only: tint around the pill, then return to true zero at
@@ -1648,7 +1656,7 @@ summary::-webkit-details-marker {
   opacity: 1;
   visibility: visible;
   transition:
-    opacity 180ms var(--ease-out-soft),
+    opacity var(--duration-base) var(--ease-out-soft),
     visibility 0s linear;
 }
 
@@ -1850,6 +1858,7 @@ summary::-webkit-details-marker {
   position: absolute;
   bottom: -0.42rem;
   left: var(--mode-action-caret-left, 2.4rem);
+  /* Caret stacking; no --z rung between base (0) and raised (10). */
   z-index: 2;
   width: 0.9rem;
   height: 0.9rem;
@@ -1867,6 +1876,7 @@ summary::-webkit-details-marker {
   position: absolute;
   top: -0.42rem;
   left: var(--mode-action-caret-left, 2.4rem);
+  /* Caret stacking; no --z rung between base (0) and raised (10). */
   z-index: 2;
   width: 0.9rem;
   height: 0.9rem;
@@ -1885,13 +1895,13 @@ summary::-webkit-details-marker {
 }
 
 .mode-action-surface[data-placement="up"] .mode-action-panel {
-  border-bottom-left-radius: 1rem;
-  border-bottom-right-radius: 1rem;
+  border-bottom-left-radius: var(--radius-xl);
+  border-bottom-right-radius: var(--radius-xl);
 }
 
 .mode-action-surface[data-placement="down"] .mode-action-panel {
-  border-top-left-radius: 1rem;
-  border-top-right-radius: 1rem;
+  border-top-left-radius: var(--radius-xl);
+  border-top-right-radius: var(--radius-xl);
 }
 
 .mode-action-mode-option:focus-visible {
@@ -1921,9 +1931,9 @@ summary::-webkit-details-marker {
   text-align: left;
   color: var(--text-muted);
   transition:
-    background-color 150ms var(--ease-out-soft),
-    border-color 150ms var(--ease-out-soft),
-    color 150ms var(--ease-out-soft);
+    background-color var(--duration-quick) var(--ease-out-soft),
+    border-color var(--duration-quick) var(--ease-out-soft),
+    color var(--duration-quick) var(--ease-out-soft);
 }
 
 .mode-action-mode-option:hover {
@@ -2078,10 +2088,10 @@ summary::-webkit-details-marker {
   place-items: center;
   border-radius: 999px;
   transition:
-    background-color 150ms var(--ease-out-soft),
-    color 150ms var(--ease-out-soft),
-    box-shadow 150ms var(--ease-out-soft),
-    transform 150ms var(--ease-spring);
+    background-color var(--duration-quick) var(--ease-out-soft),
+    color var(--duration-quick) var(--ease-out-soft),
+    box-shadow var(--duration-quick) var(--ease-out-soft),
+    transform var(--duration-quick) var(--ease-spring);
 }
 
 .chat-composer-icon-button {
@@ -2163,6 +2173,7 @@ summary::-webkit-details-marker {
 }
 /* Mirrors the `motion-safe` variant: animate when the OS allows it, and also when
    the in-app Motion preference explicitly opts in over an OS reduce request. */
+/* 170ms has no duration rung — do not invent one; nearest is --duration-base (180ms). */
 @media (prefers-reduced-motion: reduce) {
   html[data-motion="full"] .mode-action-surface[data-placement="up"] {
     animation: mode-action-fold-up 170ms var(--ease-out-soft) both;
@@ -2254,6 +2265,7 @@ summary::-webkit-details-marker {
   font-weight: 700;
   box-shadow: 0 2px 10px rgb(16 24 40 / 6%);
   backdrop-filter: blur(14px);
+  /* 160ms has no duration rung — leave literal (search-chip chrome). */
   transition:
     border-color 160ms var(--ease-out-soft),
     background-color 160ms var(--ease-out-soft),
@@ -2612,6 +2624,7 @@ summary::-webkit-details-marker {
   text-align: left;
   text-overflow: ellipsis;
   white-space: nowrap;
+  /* 160ms has no duration rung — leave literal (suggestion-chip chrome). */
   transition:
     border-color 160ms var(--ease-out-soft),
     background-color 160ms var(--ease-out-soft),
@@ -2982,6 +2995,9 @@ summary::-webkit-details-marker {
   .answer-footer-search-dock[data-scroll-hidden="true"] .answer-footer-search-backdrop {
     opacity: 0;
     visibility: hidden;
+    /* Phone-chrome hide delay must stay 240ms (--duration-slow). Keep the
+       0ms / 240ms pair literal: mobile-chrome-paint-contract pins this string,
+       and 0ms delays are not token-swapped. */
     transition-delay: 0ms, 240ms;
   }
 
@@ -3158,7 +3174,7 @@ summary::-webkit-details-marker {
   --pwa-motion-enter: 280ms;
 
   position: fixed;
-  z-index: 95;
+  z-index: var(--z-popover);
   left: max(0.5rem, var(--safe-area-left));
   right: max(0.5rem, var(--safe-area-right));
   bottom: var(--pwa-notice-bottom-gap);
@@ -4034,6 +4050,7 @@ td,
     .phone-sticky-header-stack {
       position: sticky;
       top: 0;
+      /* Between raised (10) and chrome (60); no named rung. Do not retune. */
       z-index: 30;
     }
 
@@ -4227,9 +4244,9 @@ td,
   .source-capsule-face {
     border-color: var(--border);
     transition:
-      border-color 150ms var(--ease-out-soft),
-      box-shadow 150ms var(--ease-out-soft),
-      transform 150ms var(--ease-spring);
+      border-color var(--duration-quick) var(--ease-out-soft),
+      box-shadow var(--duration-quick) var(--ease-out-soft),
+      transform var(--duration-quick) var(--ease-spring);
   }
 
   .source-capsule-hit:hover .source-capsule-face {
@@ -4258,7 +4275,7 @@ td,
   .polished-scroll {
     scrollbar-color: color-mix(in srgb, var(--border-strong) 65%, transparent) transparent;
     scrollbar-width: thin;
-    transition: scrollbar-color 200ms ease;
+    transition: scrollbar-color var(--duration-moderate) ease;
   }
 
   .polished-scroll:hover,
@@ -4283,8 +4300,8 @@ td,
     background-color: color-mix(in srgb, var(--border-strong) 60%, transparent);
     background-clip: padding-box;
     border: 3px solid transparent;
-    border-radius: 999px;
-    transition: background-color 150ms ease;
+    border-radius: var(--radius-pill);
+    transition: background-color var(--duration-quick) ease;
   }
 
   .polished-scroll:hover::-webkit-scrollbar-thumb {
@@ -4341,6 +4358,7 @@ html[data-motion="reduced"] .answer-activity-trace__sweep {
 
 .stagger-item {
   animation: cascade-fade-up var(--duration-moderate) var(--ease-out-soft) both;
+  /* 35ms stagger interval has no duration rung. */
   animation-delay: calc(var(--stagger-index, 0) * 35ms);
 }
 

src/components/ClinicalDashboard.tsx

@@ -532,9 +532,15 @@ function ClinicalDashboardContent({
       if (!target) return;
       setActiveHash(href);
       const targetTop = target.getBoundingClientRect().top;
-      const top = ownsVerticalScroll(main)
+      const unclamped = ownsVerticalScroll(main)
         ? main.scrollTop + targetTop - main.getBoundingClientRect().top - 8
         : window.scrollY + targetTop - 8;
+      // Clamp like settings-dialog: short #quotes|#images|#sources sections can
+      // compute a top past the runway. scrollSurface also clamps; keep the
+      // local clamp so this hash path does not fight use-hide-on-scroll.
+      const scroller = ownsVerticalScroll(main) ? main : (document.scrollingElement ?? document.documentElement);
+      const maxOffset = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
+      const top = Math.min(Math.max(0, unclamped), maxOffset);
       scrollSurface(main, top);
       if (shouldUpdateHistory) window.history.replaceState(null, "", href);
       navSyncLockRef.current = window.setTimeout(() => {

src/components/calculators/guided-flow.tsx

@@ -130,8 +130,8 @@ function QuestionScreen({
         className="h-1.5 overflow-hidden rounded-full bg-[color:var(--surface-inset)]"
       >
         <div
-          className="h-full rounded-full bg-[color:var(--clinical-accent)] transition-[width] duration-[var(--duration-deliberate)]"
-          style={{ width: `${(stepIndex / total) * 100}%` }}
+          className="h-full w-full origin-left rounded-full bg-[color:var(--clinical-accent)] transition-transform duration-[var(--duration-deliberate)]"
+          style={{ transform: `scaleX(${total > 0 ? stepIndex / total : 0})` }}
         />
       </div>
 

src/components/clinical-dashboard/scroll-surface.ts

@@ -5,16 +5,22 @@ export function ownsVerticalScroll(element: HTMLElement) {
   return overflowY === "auto" || overflowY === "scroll" || overflowY === "overlay";
 }
 
+function clampScrollOffset(scroller: Element, target: ScrollSurfaceTarget) {
+  const maxOffset = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
+  if (target === "end") return maxOffset;
+  return Math.min(Math.max(0, target), maxOffset);
+}
+
 export function scrollSurface(
   element: HTMLElement | null,
   target: ScrollSurfaceTarget,
   behavior: ScrollBehavior = "auto",
 ) {
   if (!element) return;
   if (ownsVerticalScroll(element)) {
-    element.scrollTo({ top: target === "end" ? element.scrollHeight : target, behavior });
+    element.scrollTo({ top: clampScrollOffset(element, target), behavior });
     return;
   }
   const scrollingElement = document.scrollingElement ?? document.documentElement;
-  window.scrollTo({ top: target === "end" ? scrollingElement.scrollHeight : target, behavior });
+  window.scrollTo({ top: clampScrollOffset(scrollingElement, target), behavior });
 }

src/components/ward-management/coordinator/coordinator.module.css

@@ -1,4 +1,5 @@
 .screen {
+  composes: descendantKillWithScroll from "../ward-reduced-motion.module.css";
   --co-space-2: 0.125rem;
   --co-space-6: 0.375rem;
   --co-space-8: 0.5rem;
@@ -1892,13 +1893,6 @@
   }
 }
 
-@media (prefers-reduced-motion: reduce) {
-  .screen * {
-    scroll-behavior: auto !important;
-    transition: none !important;
-  }
-}
-
 @media (forced-colors: active) {
   .queueRowSelected {
     border: 0.125rem solid Highlight;

src/components/ward-management/officer/officer.module.css

@@ -4,6 +4,7 @@
  * needs is declared here, never borrowed from another module's scope.
  */
 .screen {
+  composes: descendantKill from "../ward-reduced-motion.module.css";
   --of-space-4: 0.25rem;
   --of-space-6: 0.375rem;
   --of-space-8: 0.5rem;
@@ -242,12 +243,6 @@
   }
 }
 
-@media (prefers-reduced-motion: reduce) {
-  .screen * {
-    transition: none !important;
-  }
-}
-
 /*
  * Below 40rem the icon rail is gone and `ward-sidebar.module.css`'s fixed phone bar takes its
  * place. The bar is fixed rather than sticky because it has to sit above ten different shells

src/components/ward-management/tracker/live-tracker.module.css

@@ -4,6 +4,7 @@
  * (see `officer.module.css`'s own note on the same convention).
  */
 .screen {
+  composes: descendantKill from "../ward-reduced-motion.module.css";
   --tr-space-4: 0.25rem;
   --tr-space-6: 0.375rem;
   --tr-space-8: 0.5rem;
@@ -199,12 +200,6 @@
   font-weight: 700;
 }
 
-@media (prefers-reduced-motion: reduce) {
-  .screen * {
-    transition: none !important;
-  }
-}
-
 /*
  * Below 40rem the icon rail is gone and `ward-sidebar.module.css`'s fixed phone bar takes its
  * place. The bar is fixed rather than sticky because it has to sit above ten different shells

src/components/ward-management/ward-demo-controls.module.css

@@ -11,6 +11,7 @@
  * distinction in words (never colour alone).
  */
 .demo {
+  composes: descendantKill from "./ward-reduced-motion.module.css";
   --dc-warn: var(--warning-text);
   --dc-warn-soft: var(--warning-bg);
   --dc-warn-border: var(--warning-border);