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

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)?