wcag and responsiveness

openspec/changes/archive/2026-02-10-wcag-responsive/design.md

@@ -0,0 +1,88 @@
+## Context
+
+- The site is an Astro-based static site with shared global styling in `site/public/styles/global.css` and shared layout/navigation in `site/src/layouts/*`.
+- Current UX gaps:
+  - Responsive behavior is inconsistent at smaller breakpoints (navigation does not collapse into a mobile-friendly menu).
+  - The background gradient shows abrupt cuts/banding on larger resolutions.
+  - Typography relies on system fonts; a smoother, display-friendly font is desired.
+  - Accessibility baseline is not formally enforced; target is WCAG 2.2 AA minimum standard (not necessarily 100% compliance).
+
+## Goals / Non-Goals
+
+**Goals:**
+- Establish an explicit baseline of WCAG 2.2 AA-aligned behavior for the site shell and common interactive elements.
+- Implement responsive layouts across common breakpoints; ensure primary navigation collapses into a hamburger menu with mild animation.
+- Ensure the mobile menu is fully keyboard accessible and screen-reader friendly (correct semantics, labeling, focus management).
+- Improve background rendering so gradients do not cut abruptly on large displays.
+- Introduce a display-friendly font and apply it consistently across pages and components.
+- Add lightweight verification (tests and/or build checks) that ensures the baseline remains intact.
+
+**Non-Goals:**
+- Full accessibility audit and remediation of all possible WCAG 2.2 AA items across all content (e.g., all third-party embeds, all user-provided HTML).
+- Building a complete design system or replacing all visual styling.
+- Implementing complex client-side routing or heavy JS frameworks.
+
+## Decisions
+
+1. Use a small client-side navigation controller for the hamburger menu
+Why: Astro renders static HTML; a small, isolated script can provide toggling + focus management without adding framework complexity.
+Alternatives considered:
+- CSS-only checkbox hack: rejected (harder to manage focus/ARIA correctly, less robust).
+- A full component framework (React/Vue): rejected (unnecessary weight).
+
+2. Prefer semantic HTML + minimal ARIA
+Why: Better interoperability across assistive technologies and less risk of incorrect ARIA.
+Approach:
+- Use a `<button>` to toggle the menu.
+- Control a `<nav>` region (or a `<div>` wrapper) via `aria-controls` and `aria-expanded`.
+- Ensure menu items remain standard links with predictable tab order.
+
+3. Add explicit focus styles and reduced-motion support globally
+Why: Focus visibility and motion preferences are core accessibility/usability requirements; implementing globally reduces drift.
+Approach:
+- Provide a consistent `:focus-visible` outline that meets contrast requirements.
+- Wrap animations/transitions in `@media (prefers-reduced-motion: reduce)` fallbacks.
+
+4. Fix gradient banding/cuts via a single, oversized background layer
+Why: Multiple fixed-size radial gradients can show cutoffs on ultrawide/large viewports.
+Approach:
+- Render the background using a `body::before` fixed-position layer with large gradients and `inset: -40vmax` (or similar) to eliminate edges.
+- Keep the existing aesthetic but adjust sizes/stops so it scales smoothly.
+Alternatives considered:
+- Using an image background: rejected (asset management, potential compression artifacts).
+
+5. Use a webfont with good UI readability and a limited weight range
+Why: Improve perceived polish while keeping performance predictable.
+Approach:
+- Choose a modern UI font family (e.g., `Inter`, `DM Sans`, `Manrope`, or `Space Grotesk`) with 2-3 weights.
+- Prefer self-hosted font assets or a single external source with `font-display: swap`.
+Decision will be finalized during implementation based on desired look and licensing.
+
+## Risks / Trade-offs
+
+- [Risk] Mobile menu introduces accessibility regressions (trap focus, broken escape handling)
+  -> Mitigation: implement standard patterns (toggle button, ESC closes, return focus, body scroll lock optional) and add tests for key attributes.
+
+- [Risk] Global CSS changes affect existing layouts
+  -> Mitigation: keep changes scoped to site shell classes and add visual spot-checks for key pages (`/`, `/videos`, `/podcast`, `/blog`, `/about`).
+
+- [Risk] Webfont increases page weight
+  -> Mitigation: limit to necessary weights, use `woff2`, preload critical fonts, and keep fallbacks.
+
+## Migration Plan
+
+1. Implement navigation collapse + hamburger toggle script and styles.
+2. Add global focus-visible styling and reduced-motion fallbacks.
+3. Fix background gradient rendering on large displays.
+4. Add/replace typography stack and adjust headings/line-height as needed.
+5. Add verification (tests / lint checks) and confirm responsive behavior on key pages.
+
+Rollback:
+- Revert navigation script + CSS changes to restore previous behavior.
+
+## Open Questions
+
+- Which specific webfont should be used (and will it be self-hosted or loaded via a provider)?
+- Should the mobile menu lock body scroll while open (common pattern, but optional)?
+- Should the menu close on route navigation (likely yes), and should it close on outside click (likely yes)?
+