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