Merge pull request #37 from facebookresearch/explorer-a11y-perf-and-cache

Explorer: accessibility, mobile performance budget, artifact revalidation

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;
+  }
+}