Explorer: accessibility, mobile performance budget, artifact revalidation

Five improvements from a repository review. Every figure below was
measured, and each change is pinned by a test that fails against the
defect it describes.

Mobile total blocking time 1210 ms -> 120 ms. Unlabeled sliders 8 -> 0.

1. Accessible names and a text equivalent for the chart
   All 8 range sliders had no accessible name -- a screen reader
   announced "slider, 353" with no indication of the ingredient
   (WCAG 4.1.2). The sibling value input was already labelled; the range
   input was missed. Both now share one shortIngredientName() helper and
   follow the unit toggle, so the announced unit cannot drift from the
   displayed one. The canvases had an aria-label but exposed no data, so
   #curve-summary publishes the 1/7/28-day predictions into a polite live
   region -- debounced, emitted only once the composition settles, and
   skipped when unchanged, since assigning identical text re-announces.

2. Lighthouse measures mobile
   The config used preset "desktop" only, so the platform where the
   problems live was never scored -- which is how a 6 px touch target and
   1.2 s of blocking time both shipped unnoticed. The new profile failed
   on its first run.

   Kept as one job with two steps rather than a matrix: a matrix job's
   check runs are named "lighthouse (<values>)", which would strand any
   branch protection requiring the "lighthouse" context.

   Budgets are calibrated honestly. No "perf" preset -- it silently
   forces throttlingMethod "devtools", which measured LCP 3.2 s against
   simulate's 11.6 s for the same page and diverged from the desktop
   profile. Error gates are limited to metrics this harness measures
   representatively (CPU, accessibility, layout); http-server serves
   uncompressed bytes where Pages gzips them (188 KB -> 22 KB), which
   inflates transfer-bound metrics ~7x, so those are warn-only and say so
   in the config.

3. The UI shell renders before the model
   buildSliders() and setupEventListeners() ran after awaiting the
   strength GP, so moving that work into a worker removed the freeze but
   not the delay. The shell now builds from compositions.json plus the
   linear GWP/cost models, and the draw paths tolerate a null model.

   The model-dependent guard in drawScatter is scoped to the selected-
   composition marker alone. An early return there also skipped the axes
   and the canvas._pad/_xMin/... scale stash, and the mousemove handler
   bails without _pad -- so for the whole model-load window hover did
   nothing and clicking a point was a silent no-op.

4. Startup animation was the real mobile cost
   Profiling under 4x CPU throttle showed only two large init tasks
   followed by a continuous stream of ~55 ms tasks from 1.2 s to 2.8 s:
   the startup fade-in, where every animated frame redraws both canvases
   and is therefore itself a main-thread long task. Time-to-interactive
   can never find a quiet window against that.

   Easing now snaps on the first animated frame and under
   prefers-reduced-motion, which also covers the interaction transitions
   (composition slide, Material Source crossfade, unit transition) and
   CSS -- gradientShift is a 30 s infinite animation with no pause
   control, a WCAG 2.2.2 Level A exposure rather than merely 2.3.3.
   Slider input additionally coalesces onto one rAF, since touch and
   high-polling mice fire faster than 60 Hz.

   Measured but deliberately unchanged: a drag redraw is 24 ms at 4x
   throttle (~40 fps) and 98% of that is the strength-curve GP, not the
   scatter (2%). Cutting curve resolution would trade visible quality --
   32 vs 48 points already differ by 17% in the steep gate region.

5. Model artifacts revalidate together
   loadJSON was a bare fetch. The artifacts are mutually index-dependent
   (mix_analyses.json is keyed by position in compositions.json) but
   Pages serves them with max-age=600 and independent age values, so a
   visitor could hold a fresh compositions.json beside a stale
   mix_analyses.json for ten minutes after any deploy. Observed in
   production after the 3-class merge. `cache: "no-cache"` revalidates
   while still reusing the cached body on a 304, and a non-ok response
   now throws instead of surfacing later as a JSON parse error.

Accessibility items found while reviewing the above:

- The Pareto pill failed WCAG 1.4.3 AA in dark theme: white on #fb7185 is
  2.69:1, and at 9.6 px bold the bar is 4.5:1, not 3:1. Added --pareto-on
  following the existing --accent-on precedent, which already documents
  the identical problem for --accent. 4.70:1 light, 5.81:1 dark.
  Only visible on the locked toolchain -- node_modules held Lighthouse
  12.1.0 while the lockfile and CI pin 12.6.1, and 12.1.0 does not flag
  it. Both profiles re-verified on 12.6.1.

- Range sliders had `outline: none` with no replacement anywhere, a WCAG
  2.4.7 (AA) failure on the control this change otherwise improves.
  Lighthouse's accessibility category does not audit focus visibility, so
  the score gate cannot catch it; there is now an explicit test.

- Both modal overlays were hidden with opacity and pointer-events only,
  leaving their close buttons, links and iframe permanently tabbable and
  in the accessibility tree. Added visibility toggling.

  That in turn exposed a real heading skip the invisible dialog had been
  masking: with the modal's h2 gone, the mobile outline read H1 -> H3.
  The two insight panels are siblings of the h2 chart panels, so their
  titles are now h2.

- The unit toggle showed "SI" but was named "Toggle metric/imperial
  units", failing WCAG 2.5.3 Label in Name. The name now contains the
  visible text and tracks it. Pre-existing and weight-zero in the
  Lighthouse score, so nothing flagged it.

- No aria-describedby on the curve canvas. The sr-only summary is
  clip-hidden rather than display:none, so it already sits in reading
  order after the canvas; referencing it as well makes a browse-mode user
  hear the same sentence twice, and the canvas is not focusable so the
  description would be unreliable regardless.

Also exposes __test.modelReady: "page loaded" no longer implies "model
ready", and several specs were asserting on predictions without waiting
for one.

Deliberately not addressed here, so the next person does not have to
re-derive why:

- Modals still have no focus management -- no role="dialog", focus is not
  moved in on open nor restored on close. This change only stops them
  being reachable while closed.
- requestRedraw and animLoop both redraw during a drag, so the work
  happens twice per frame. Pre-existing; untangling redraw ownership is a
  separate refactor.
- #scatter-canvas has no text equivalent; only the curve canvas got one.
- _reduceMotion is sampled once at module load, so flipping the OS
  setting at runtime updates the CSS half but not the JS canvas easing.
- Whether "lighthouse" is a required status check could not be verified
  from here. The workflow deliberately keeps a single job so the existing
  check name is preserved, but confirm against branch protection.

Verification: lint 0, test-js 13/13, test-py 270 at 100% coverage,
e2e 100 on macOS and 104 on Linux in the matching Playwright image (visual
baselines still matching), and both Lighthouse profiles green on the
locked toolchain (12.6.1) with zero failing accessibility audits and zero
phantom assertions. The pre-model,
unit-toggle, reduced-motion CSS, animation-delay and script-animation
tests were each confirmed to fail against the defect they pin.

Author: SebastianAment

.github/workflows/lighthouse.yml

@@ -15,6 +15,7 @@ on:
     paths: &lighthouse_paths
       - 'docs/**'
       - 'lighthouserc.json'
+      - 'lighthouserc.mobile.json'
       - '.github/workflows/lighthouse.yml'
   pull_request:
     branches: [main, master]
@@ -30,7 +31,7 @@ env:
 jobs:
   lighthouse:
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 25
 
     steps:
       - uses: actions/checkout@v5
@@ -43,9 +44,27 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Run Lighthouse CI
-        run: npx lhci autorun
+      # Desktop and mobile are separate Lighthouse profiles, not one run with
+      # two viewports. Only desktop was ever measured, which is why a 6 px
+      # touch target and 1.2 s of mobile blocking time both shipped unnoticed.
+      #
+      # Deliberately two steps in ONE job rather than a matrix: a matrix job's
+      # check-run name becomes "lighthouse (<matrix values>)", so any branch
+      # protection requiring the "lighthouse" context would wait forever on a
+      # status that is never reported again. Keeping a single job preserves
+      # the existing check name.
+      - name: Run Lighthouse CI (desktop)
+        run: npx lhci autorun --config=lighthouserc.json
         env:
           # Public uploads to temporary-public-storage are anonymous;
           # no token required for our config.
           LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
+
+      # `if: always()` so a desktop failure still reports the mobile result --
+      # otherwise the profile this change exists to add would be skipped
+      # exactly when something is wrong.
+      - name: Run Lighthouse CI (mobile)
+        if: always()
+        run: npx lhci autorun --config=lighthouserc.mobile.json
+        env:
+          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

docs/index.html

@@ -164,7 +164,7 @@ <h3>Papers</h3>
     <div class="panel sliders fade-in-up" id="sliders-panel" style="--delay: 0ms">
       <div class="sliders-header">
         <h2 id="sliders-title">Composition (kg/m³)</h2>
-        <button class="unit-toggle" id="unit-toggle" aria-label="Toggle metric/imperial units">
+        <button class="unit-toggle" id="unit-toggle" aria-label="SI units - switch to US units">
           <span class="unit-label" id="unit-label">SI</span>
         </button>
       </div>
@@ -179,7 +179,7 @@ <h2 id="sliders-title">Composition (kg/m³)</h2>
         <div class="mobile-panel-header">
           <button id="mobile-show-scatter" class="active">Performance Tradeoffs</button>
           <button id="mobile-show-sliders">Composition (kg/m³)</button>
-          <button class="unit-toggle mobile-unit-toggle" id="mobile-unit-toggle" aria-label="Toggle metric/imperial units">
+          <button class="unit-toggle mobile-unit-toggle" id="mobile-unit-toggle" aria-label="SI units - switch to US units">
             <span class="unit-label" id="mobile-unit-label">SI</span>
           </button>
         </div>
@@ -208,7 +208,7 @@ <h2>Performance Tradeoffs</h2>
       <!-- Mix Insight (below scatter) -->
       <div class="panel mix-insight-panel fade-in-up" id="mix-insight" style="--delay: 300ms">
         <div class="mix-insight-header">
-          <h3 class="mix-insight-title">Mix Insight</h3>
+          <h2 class="mix-insight-title">Mix Insight</h2>
           <span class="pareto-pill" id="pareto-pill">Pareto-optimal</span>
         </div>
         <div class="mix-insight-body">
@@ -218,7 +218,7 @@ <h3 class="mix-insight-title">Mix Insight</h3>
 
       <!-- Ingredient Insights (below mix insight) -->
       <div class="panel ingredient-insight-panel fade-in-up" id="ingredient-insight" style="--delay: 350ms">
-        <h3 class="ingredient-insight-title">Ingredient Insight</h3>
+        <h2 class="ingredient-insight-title">Ingredient Insight</h2>
         <div class="ingredient-insight-body">
           <p class="ingredient-insight-text" id="ingredient-insight-text"><span class="mix-insight-placeholder">Click an ingredient name in the Composition panel to learn more.</span></p>
         </div>
@@ -232,6 +232,21 @@ <h3 class="ingredient-insight-title">Ingredient Insight</h3>
         <span class="extrapolation-warning" id="extrapolation-warning">⚠ Far from data</span>
         <h2>Predicted Strength Curve</h2>
         <canvas id="curve-canvas" aria-label="Predicted concrete strength curve over curing time"></canvas>
+        <!-- Text equivalent of the curve for screen readers. A canvas exposes
+             no data, so aria-label conveys that a chart exists but not what it
+             says. Updated only once the composition settles, and skipped when
+             unchanged, so the live region does not chatter.
+
+             Deliberately NOT wired up via aria-describedby on the canvas. These
+             divs are clip-hidden, not display:none, so they already sit in
+             reading order immediately after it; referencing them as well makes
+             a browse-mode user hear the same sentence twice. The canvas is also
+             not focusable, so the description would be unreliable anyway. -->
+        <div id="curve-summary" class="sr-only" role="status" aria-live="polite"></div>
+        <!-- Static caveat, deliberately OUTSIDE the live region: it never
+             changes, so re-speaking it on every update would add ~9 words to
+             each announcement for no information. -->
+        <div id="curve-summary-note" class="sr-only">Strength figures are model predictions with a 95 percent interval.</div>
         <div class="readouts" id="readouts">
           <div>GWP: <span class="value" id="gwp-value">–</span> <span class="unit" id="gwp-unit">kg CO₂e/m³</span></div>
           <div>Cost: <span class="value" id="cost-value">–</span> <span id="cost-uncertainty"></span> <span class="unit" id="cost-unit">$/m³</span></div>
@@ -340,7 +355,12 @@ <h3>References</h3>
     });
 
     // Crossfade helper: fade out current, swap, fade in new
+    // 150 ms matches the .fading opacity transition. Under reduced motion that
+    // transition is instant, so the wait would leave the panel blank for
+    // 150 ms instead of fading -- collapse it to match.
+    const REDUCE_MOTION = matchMedia('(prefers-reduced-motion: reduce)').matches;
     function crossfade(fadeOut, fadeIn, onSwap) {
+      const fadeMs = REDUCE_MOTION ? 0 : 150;
       fadeOut.classList.add('fading');
       setTimeout(() => {
         fadeOut.classList.add('hidden');
@@ -351,7 +371,7 @@ <h3>References</h3>
         requestAnimationFrame(() => {
           requestAnimationFrame(() => fadeIn.classList.remove('fading'));
         });
-      }, 150);
+      }, fadeMs);
     }
 
     mobileScatterBtn.addEventListener('click', () => {

docs/style.css

@@ -11,6 +11,10 @@
   --accent-on: #ffffff;
   --band: rgba(37, 99, 235, 0.18);
   --pareto: #e11d48;
+  /* Foreground for text ON the pareto pill, same pattern as --accent-on.
+     White on #e11d48 is 4.70:1, which clears WCAG AA for the pill's 9.6 px
+     bold text (not "large text", so the bar is 4.5:1, not 3:1). */
+  --pareto-on: #ffffff;
   --observation: #475569;
   --point: #475569;
   --glass-bg: rgba(var(--card-bg-rgb), 0.7);
@@ -30,6 +34,10 @@
   --accent-on: #0f0f1a;
   --band: rgba(96, 165, 250, 0.2);
   --pareto: #fb7185;
+  /* White on #fb7185 is only 2.69:1 and FAILED WCAG AA at the pill's 9.6 px
+     bold size. Keep the bright chip -- it needs to read against a dark panel
+     -- and darken the text instead, exactly as --accent-on does: 5.81:1. */
+  --pareto-on: #4c0519;
   --observation: #94a3b8;
   --point: #94a3b8;
   --glass-bg: rgba(var(--card-bg-rgb), 0.7);
@@ -232,11 +240,18 @@ body {
   justify-content: center;
   opacity: 0;
   pointer-events: none;
-  transition: opacity 0.25s ease;
+  /* Also remove it from the tab order and the accessibility tree while closed.
+     opacity alone left .about-close, the two arXiv links, .video-close and the
+     iframe permanently tabbable, and put the modal's h2/h3 headings ahead of
+     the app's own in the heading outline. `visibility` still animates, so the
+     fade is preserved. */
+  visibility: hidden;
+  transition: opacity 0.25s ease, visibility 0.25s ease;
 }
 .about-overlay.visible {
   opacity: 1;
   pointer-events: all;
+  visibility: visible;
 }
 .about-modal {
   background: var(--glass-bg);
@@ -325,11 +340,18 @@ body {
   justify-content: center;
   opacity: 0;
   pointer-events: none;
-  transition: opacity 0.25s ease;
+  /* Also remove it from the tab order and the accessibility tree while closed.
+     opacity alone left .about-close, the two arXiv links, .video-close and the
+     iframe permanently tabbable, and put the modal's h2/h3 headings ahead of
+     the app's own in the heading outline. `visibility` still animates, so the
+     fade is preserved. */
+  visibility: hidden;
+  transition: opacity 0.25s ease, visibility 0.25s ease;
 }
 .video-overlay.visible {
   opacity: 1;
   pointer-events: all;
+  visibility: visible;
 }
 .video-modal {
   background: var(--glass-bg);
@@ -606,6 +628,12 @@ h2 {
   border-color: var(--accent);
   background: rgba(var(--card-bg-rgb), 0.6);
 }
+/* A border-colour change alone is colour-only signalling; keyboard users get
+   a real outline. */
+.slider-value:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
 /* The input is the TOUCH TARGET; the visible 6 px bar is drawn by the track
    pseudo-elements below. Previously the element itself was the 6 px bar, which
    meant the whole hit area was 6 px tall -- measured 220x6 on mobile, against a
@@ -622,6 +650,15 @@ h2 {
   background: transparent;
   outline: none;
 }
+/* `outline: none` above removed the only focus indicator these controls had,
+   with no replacement anywhere -- a WCAG 2.4.7 Focus Visible (AA) failure on
+   the app's primary controls. Note Lighthouse's accessibility category does
+   NOT audit focus visibility, so the a11y score gate cannot catch this. */
+.slider-group input[type=range]:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 3px;
+  border-radius: 3px;
+}
 .slider-group input[type=range]::-webkit-slider-runnable-track {
   height: 6px;
   background: var(--border);
@@ -898,6 +935,20 @@ h2 {
 .filter-row-wrapper.collapsed {
   display: none;
 }
+/* Visible to assistive technology only. Standard clip-rect pattern: stays in
+   the accessibility tree (unlike display:none) while occupying no space. */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 .filter-row {
   display: flex;
   align-items: center;
@@ -951,6 +1002,10 @@ h2 {
   border-color: var(--accent);
   outline: none;
 }
+.filter-row input[type=number]:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 1px;
+}
 /* Categorical filter (Material Source). An unordered class axis has no
    meaningful min/max, so its row renders one toggle per class instead of
    numeric bounds. All start active, making a fresh row a no-op -- the same
@@ -1183,7 +1238,7 @@ a.ref-link {
   text-transform: uppercase;
   letter-spacing: 0.04em;
   background: var(--pareto);
-  color: #fff;
+  color: var(--pareto-on);
   padding: 2px 8px;
   border-radius: 999px;
   opacity: 0;
@@ -1624,3 +1679,56 @@ a.ref-link {
     width: calc(50% - 0.2rem);
   }
 }
+
+/* ---------------------------------------------------------------------------
+   Reduced motion (WCAG 2.3.3, and 2.2.2 for the infinite animations).
+
+   The JS honours prefers-reduced-motion for canvas easing and the transition
+   durations, but CSS animations are independent of that and were not covered.
+   Two of them run forever:
+
+     - `gradientShift` (30 s, infinite) on the page title. Automatically
+       starting, moving, presented alongside other content and lasting well
+       over 5 s with no pause control -- that is a Pause/Stop/Hide (Level A)
+       exposure, not merely a 2.3.3 (AAA) one.
+     - `previewPulse` (1.5 s, infinite) on the slider preview marker.
+
+   `fadeInUp` and the transitions are one-shot, but a reduced-motion user has
+   asked not to see them either.
+
+   Motion is removed rather than merely shortened; `animation: none` also stops
+   the infinite ones from holding a compositor layer awake. Durations are set
+   to a near-zero value rather than 0 so that transitionend/animationend
+   listeners still fire, which is the standard form of this reset.
+   -------------------------------------------------------------------------- */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    /* Required, and easy to omit: .fade-in-up uses `animation-fill-mode: both`
+       with staggered per-panel delays (0-350 ms via --delay). Without this the
+       backwards fill holds the `from` keyframe (opacity 0) for the delay, so
+       the six panels stay invisible and then pop in one at a time -- a staged
+       reveal, which is precisely what the preference asks to remove. */
+    animation-delay: -1ms !important;
+    transition-duration: 0.01ms !important;
+    transition-delay: 0ms !important;
+    scroll-behavior: auto !important;
+  }
+
+  /* The two infinite decorative animations: stop outright, and pin the title
+     gradient to a static position so it does not freeze mid-sweep. */
+  h1 {
+    animation: none !important;
+    /* gradientShift runs 200% -> 0%, so this pins the END keyframe (a settled
+       gradient), not a mid-sweep frame. */
+    background-position: 0% 50% !important;
+  }
+  .slider-preview-marker {
+    /* The base rule already sets the centring transform, so stopping the
+       animation is sufficient -- no transform override needed. */
+    animation: none !important;
+  }
+}