fix: WCAG AA contrast across public pages + green a11y/Lighthouse CI (#396)

## Why
The `playwright-a11y` and Lighthouse `accessibility` CI gates have been
red. Root causes (both real, not harness flakes):

1. **Every public page had genuine WCAG 2.1 AA color-contrast
violations** — `axe` flagged `color-contrast` (and one
`link-in-text-block`) on home, login, register, all legal pages,
pricing, about, and the AI/Scholar/Library landings.
2. **The Lighthouse accessibility job aborted before auditing** — it ran
`vite build` but never served the output, so Chrome hit a dead `:4173`
and failed with `CHROME_INTERSTITIAL_ERROR`.

## What changed
Contrast fixed at the **token/source level** so it can't recur
page-by-page:
- `--sh-muted` `#8a8a8a` → `#6b6b6b` (the dominant muted-text token; was
~3.3:1 on white/paper)
- keyboard-hint, legal kicker, footer copyright, dark search-pill text,
nav + footer brand wordmark
- About roadmap headers → `-text` color variants; About step numerals
darkened (were ~1.2:1) + kept `aria-hidden`
- Pricing "coming soon" tag → `brand-hover`
- data-request in-text email link underlined (WCAG 1.4.1 — a link in
body text can't rely on color alone)
- the a11y spec now logs the failing **selector + fg/bg/ratio** per
node, so a future regression is diagnosable straight from the CI log

Lighthouse: config now starts `vite preview` itself
(`startServerCommand`) before collecting.

## Verification
- All **13/13** a11y smoke pages pass locally (`playwright test
tests/a11y.smoke.spec.js`)
- Frontend lint clean (0 errors), build succeeds

## Summary by Sourcery

Address accessibility contrast issues across public pages and stabilize
a11y-related CI by updating design tokens, UI styles, and Lighthouse
configuration.

Bug Fixes:
- Resolve WCAG 2.1 AA color-contrast violations across public pages by
adjusting muted text, footer copy, wordmarks, roadmap headers, keyboard
hints, and tags to AA-compliant colors.
- Ensure in-text email links are visually distinguishable by adding
underlines to satisfy WCAG link-in-text requirements.
- Fix Lighthouse accessibility CI failures by starting the built app
with `vite preview` before running audits so Lighthouse no longer hits a
dead port.
- Make the About page step numerals decorative-only in the accessibility
tree to avoid low-contrast text violations.
- Improve a11y smoke test diagnostics by logging failing selectors with
their foreground/background colors and contrast ratios.

Enhancements:
- Refine navigation search text color and About roadmap tone tokens to
use more appropriate text-specific variants that preserve brand intent
while meeting contrast guidelines.

Documentation:
- Update the release log with notes about the accessibility contrast
fixes and CI gate stabilization.

Tests:
- Enhance the a11y smoke test output to provide more actionable
information for debugging accessibility regressions.

Author: Apexone11

docs/release-log.md

@@ -28,7 +28,10 @@ internal log into this file when they describe user-visible behavior.
 
 ## v2.2.0 — public launch ship (2026-04-30)
 
-### Wave-12.25 — green CI: raise backend test timeout for bcrypt-heavy cases (2026-06-02)
+### Wave-12.27 — accessibility contrast fixes + green a11y/Lighthouse CI (2026-06-02)
+
+- Fixed WCAG 2.1 AA color-contrast failures across every public page (home, login, register, all legal pages, pricing, about, AI/Scholar/Library landings). Darkened the muted-text token and the keyboard-hint, legal-kicker, and footer-copy colors; lightened the brand wordmark on the dark nav/footer; switched the About roadmap headers and pricing "coming soon" tag to AA-passing color variants; underlined the in-text email link on the data-request page (links can't rely on color alone). All 13 a11y smoke pages now pass. The a11y test now logs the failing selector + colors so future regressions are diagnosable.
+- Fixed the Lighthouse `accessibility` Quality Gate, which had aborted with `CHROME_INTERSTITIAL_ERROR`: the job built the app but never served it, so Lighthouse hit a dead port. The config now starts `vite preview` itself before auditing.
 
 - CI (StudyHub CI + Quality Gates) had been red on `local-main`/#385 because one security test (`recoveryCodes.unit.test.js` — hashes all 10 recovery codes at bcrypt cost 12 and verifies each) took ~5.05s and tripped vitest's 5000ms default. Raised the backend `testTimeout`/`hookTimeout` to 15s in `vitest.config.mjs` (still fails a genuinely-hung test fast). Full backend suite now green on CI (3,513 tests). This was the long-standing red-CI cause, not a regression from recent work.
 - Lighthouse CI (`accessibility` Quality Gate) was failing with "module is not defined in ES module scope" — `lighthouse.config.js` used CommonJS `module.exports` in a `"type": "module"` workspace. Renamed it to `lighthouse.config.cjs` and updated the workflow `configPath`. (The `playwright-smoke`/`playwright-a11y` E2E checks remain red on a pre-existing, multi-spec UI/test-drift issue unrelated to this work — tracked separately.)

frontend/studyhub-app/lighthouse.config.cjs

@@ -4,6 +4,14 @@
 module.exports = {
   ci: {
     collect: {
+      // Serve the built app ourselves. The CI job only runs `vite build`, so
+      // without this the URL below hit a dead port and Lighthouse aborted with
+      // CHROME_INTERSTITIAL ("server is not responding"). `vite preview` serves
+      // dist/ on 4173 (preview.port in vite.config). The action runs from the
+      // repo root, hence the --prefix.
+      startServerCommand: 'npm --prefix frontend/studyhub-app run preview',
+      startServerReadyPattern: 'Local:',
+      startServerReadyTimeout: 30000,
       url: ['http://localhost:4173/'],
       numberOfRuns: 3,
       settings: {

frontend/studyhub-app/src/components/navbar/Navbar.jsx

@@ -164,7 +164,9 @@ export default function Navbar({
               <LogoMark size={28} />
             )}
             <span style={wordmarkStyle}>
-              Study<span style={{ color: 'var(--sh-nav-tab-active)' }}>Hub</span>
+              {/* Brand blue (#2563eb) is only ~3.4:1 on the dark #1a1a1a nav;
+                  the lighter brand-border blue clears AA for the wordmark. */}
+              Study<span style={{ color: 'var(--sh-brand-border)' }}>Hub</span>
             </span>
           </Link>
 

frontend/studyhub-app/src/index.css

@@ -129,7 +129,10 @@
   --sh-text: #1a1a1a;
   --sh-heading: #111111;
   --sh-subtext: #5a5a5a;
-  --sh-muted: #8a8a8a;
+  /* #6b6b6b clears WCAG AA (4.5:1) on white, paper (#faf9f7), and warm
+     paper (#f6f5f2); the prior #8a8a8a was ~3.3:1 and failed the a11y gate
+     on every muted-text surface. */
+  --sh-muted: #6b6b6b;
 
   /* ── Brand ───────────────────────────────────────────────────────── */
   --sh-brand: #2563eb;
@@ -245,7 +248,9 @@
   --sh-footer-dark-bg: #0f172a;
   --sh-footer-dark-text: #ffffff;
   --sh-footer-dark-muted: rgba(255, 255, 255, 0.46);
-  --sh-footer-dark-copy: rgba(255, 255, 255, 0.25);
+  /* 0.62 alpha over the #0f172a footer composites to ~4.7:1; the prior 0.25
+     rendered ~2.2:1 and failed AA for the footer copyright line. */
+  --sh-footer-dark-copy: rgba(255, 255, 255, 0.62);
 
   /* ── Extended accent families ──────────────────────────────────── */
   --sh-neutral-soft-bg: #f1f5f9;
@@ -411,7 +416,7 @@
   --sh-nav-accent: #a0a0a0;
   --sh-nav-search-bg: #2a2a2a;
   --sh-nav-search-border: #3a3a3a;
-  --sh-nav-search-text: #6b6b6b;
+  --sh-nav-search-text: #a8a8a8;
   --sh-nav-tab-active: #2563eb;
   --sh-nav-badge-bg: #dc2626;
 
@@ -605,7 +610,7 @@
   --sh-nav-accent: #a0a0a0;
   --sh-nav-search-bg: #1c1c1c;
   --sh-nav-search-border: #2a2a2a;
-  --sh-nav-search-text: #6b6b6b;
+  --sh-nav-search-text: #a8a8a8;
   --sh-nav-tab-active: #60a5fa;
   --sh-nav-badge-bg: #dc2626;
 
@@ -2822,7 +2827,9 @@ textarea.sh-input {
 }
 
 .home-footer-logo-text span {
-  color: var(--sh-brand);
+  /* Brand blue (#2563eb) is only ~3.4:1 on the dark #0f172a footer; the
+     lighter brand-border blue clears AA while keeping the accent. */
+  color: var(--sh-brand-border);
 }
 
 .home-footer-links {
@@ -3134,7 +3141,9 @@ textarea.sh-input {
   font-weight: 800;
   letter-spacing: 0.08em;
   text-transform: uppercase;
-  color: var(--sh-slate-400);
+  /* slate-400 (#94a3b8) is ~2.6:1 on white — fails AA. Muted (#6b6b6b)
+     reads as a kicker label and clears 4.5:1. */
+  color: var(--sh-muted);
   margin-bottom: 12px;
 }
 
@@ -3711,7 +3720,8 @@ textarea.sh-input {
   font-size: 10px;
   font-weight: 600;
   font-family: inherit;
-  color: #94a3b8;
+  /* #94a3b8 on #f1f5f9 is ~2.3:1; slate-600 clears AA for the shortcut hint. */
+  color: #475569;
   background: #f1f5f9;
   border: 1px solid #e2e8f0;
   border-radius: 5px;

frontend/studyhub-app/src/pages/legal/AboutPage.jsx

@@ -77,10 +77,13 @@ const GOAL_TONES = {
   },
 }
 
+// Use the darker `-text` token variants: the base success (#16a34a) and
+// warning (#d97706) are only ~3.2:1 on white and fail AA as heading text.
+// The -text variants clear 4.5:1 while staying green/amber.
 const ROADMAP_TONES = {
-  current: 'var(--sh-success)',
-  next: 'var(--sh-warning)',
-  future: 'var(--sh-info)',
+  current: 'var(--sh-success-text)',
+  next: 'var(--sh-warning-text)',
+  future: 'var(--sh-info-text)',
 }
 
 export default function AboutPage() {
@@ -302,7 +305,12 @@ export default function AboutPage() {
           <div style={s.stepsRow}>
             {HOW_STEPS.map((step, i) => (
               <div key={i} style={s.stepCard}>
-                <div style={s.stepNum}>{step.step}</div>
+                {/* Decorative large step numeral — the step's meaning is in
+                    the title/desc below. Faint by design (low contrast), so
+                    hide it from the a11y tree rather than darken it. */}
+                <div style={s.stepNum} aria-hidden="true">
+                  {step.step}
+                </div>
                 <h3 style={s.stepTitle}>{step.title}</h3>
                 <p style={s.stepDesc}>{step.desc}</p>
               </div>
@@ -607,7 +615,9 @@ const s = {
     padding: '32px 24px',
     textAlign: 'center',
   },
-  stepNum: { fontSize: 40, fontWeight: 'bold', color: 'var(--sh-border)', marginBottom: 16 },
+  // Muted (not border-grey): the faint #e5e2dd was ~1.2:1 on paper and failed
+  // even the 3:1 large-text bar. Muted clears it and the numerals stay subtle.
+  stepNum: { fontSize: 40, fontWeight: 'bold', color: 'var(--sh-muted)', marginBottom: 16 },
   stepTitle: { fontSize: 18, fontWeight: 'bold', color: 'var(--sh-heading)', margin: '0 0 12px' },
   stepDesc: { fontSize: 14, color: 'var(--sh-muted)', margin: 0, lineHeight: 1.7 },
   roadmapGrid: {

frontend/studyhub-app/src/pages/legal/DataRequestPage.jsx

@@ -139,7 +139,9 @@ function DataRequestPage() {
           You can also email us directly at{' '}
           <a
             href={`mailto:${LEGAL_EMAILS.privacy}`}
-            style={{ color: 'var(--sh-brand)', textDecoration: 'none' }}
+            // Underlined: a link inside a text block can't rely on color alone
+            // to be distinguishable (WCAG 1.4.1 / axe link-in-text-block).
+            style={{ color: 'var(--sh-brand)', textDecoration: 'underline' }}
           >
             {LEGAL_EMAILS.privacy}
           </a>

frontend/studyhub-app/src/pages/pricing/PricingPage.jsx

@@ -1559,7 +1559,9 @@ const c = {
     top: 16,
     right: 16,
     background: 'var(--sh-brand-soft)',
-    color: 'var(--sh-brand)',
+    // brand (#2563eb) on brand-soft (#dbeafe) is 4.23:1 — just under AA;
+    // brand-hover (#1d4ed8) clears it.
+    color: 'var(--sh-brand-hover)',
     fontSize: 11,
     fontWeight: 700,
     padding: '4px 12px',

frontend/studyhub-app/tests/a11y.smoke.spec.js

@@ -60,10 +60,22 @@ for (const page of PUBLIC_PAGES) {
       console.error(
         `[a11y:${page.name}] ${blocking.length} blocking violation(s):\n` +
           blocking
-            .map(
-              (v) =>
-                `  - ${v.id} (${v.impact}): ${v.help}\n    ${v.helpUrl}\n    ${v.nodes.length} node(s)`,
-            )
+            .map((v) => {
+              // Print the offending selector + the actual/required contrast
+              // colors per node. A bare rule name + count isn't actionable
+              // in CI logs — you can't fix a contrast bug you can't locate.
+              const nodes = v.nodes
+                .map((n) => {
+                  const data = n.any?.find((c) => c.id === v.id)?.data
+                  const contrast =
+                    data && data.fgColor
+                      ? ` [fg=${data.fgColor} bg=${data.bgColor} ratio=${data.contrastRatio} need=${data.expectedContrastRatio}]`
+                      : ''
+                  return `      ${n.target.join(' ')}${contrast}`
+                })
+                .join('\n')
+              return `  - ${v.id} (${v.impact}): ${v.help}\n    ${v.helpUrl}\n    ${v.nodes.length} node(s):\n${nodes}`
+            })
             .join('\n'),
       )
     }