89 lines
4.9 KiB
Markdown
89 lines
4.9 KiB
Markdown
## 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)?
|
|
|