## Context

The production site is built as static output and served via nginx (Docker image). Lighthouse runs (mobile/desktop, light/dark/high-contrast) report repeated misses across Performance, SEO, Best Practices, and (in dark theme) Accessibility.

Notable characteristics from the current system:

- SEO is mostly static-file driven (`site/public/robots.txt`, sitemap output) and must be correct for the deployed domain.
- Global styling is served from `site/public/styles/global.css`, which bypasses typical bundler optimizations (minification, pruning) unless explicitly piped through the build.
- A service worker exists (`site/public/sw.js`) and is involved in caching shell assets; cache behavior must not cause stale critical assets after deploy.
- The site uses environment-driven configuration and has multiple theme modes (light/dark/high-contrast) that must remain visually consistent and accessible.

The goal is a deterministic, repeatable Lighthouse gate that can hit 100s in a clean run environment.

## Goals / Non-Goals

**Goals:**

- Reach 100 Lighthouse scores (Performance, Accessibility, Best Practices, SEO) for the defined set of URLs, form factors, and theme variants.
- Fix SEO correctness issues that are unambiguous (e.g., `robots.txt` sitemap URL must be absolute for the production domain).
- Ensure all user-visible navigational CTAs and modal actions are implemented as crawlable anchors (real `href`s) when they represent links.
- Eliminate dark theme contrast regressions by tightening theme token choices and/or component-level styles.
- Reduce initial render blocking work (fonts + CSS) to improve mobile performance.
- Reduce CSS overhead by ensuring the global stylesheet is minified and sized appropriately for production.
- Make Lighthouse runs deterministic (clean Chrome profile, fixed throttling/UA) and enforce a quality gate in CI or a scripted check.

**Non-Goals:**

- Redesigning the visual aesthetic.
- Building a general-purpose CSS framework migration.
- Perfect scores when Lighthouse is run with extensions or non-deterministic settings.
- Solving third-party performance/caching issues by weakening metrics (the goal is to reduce third-party dependence where it blocks 100s, or scope the gate to first-party pages that can be made deterministic).

## Decisions

### 1) Define the Lighthouse gate upfront

Decision: treat 100s as a contract under a specific, documented run configuration.

- URLs: start with the production home page and any key landing/content pages that are stable and representative.
- Variants: mobile/desktop x light/dark/high-contrast.
- Run environment: headless Chrome in CI (no extensions), consistent throttling, at least N runs per variant with median selection.

Rationale: Lighthouse scores are otherwise too sensitive to environment noise to serve as a reliable build gate.

Alternative considered: manual Lighthouse checks. Rejected because it does not prevent regressions.

### 2) Fix SEO static outputs in `public/`

Decision: keep `robots.txt` and sitemap-related outputs as static files, but ensure correctness for production.

- Make the sitemap reference in `site/public/robots.txt` absolute (not a relative path).

Rationale: This is required for Lighthouse SEO audits and is the least invasive change.

Alternative considered: generate robots dynamically. Rejected as unnecessary complexity.

### 3) Enforce crawlable links in modal/CTA surfaces

Decision: if an element semantically represents navigation (internal or outbound), it must be an `<a href="...">`.

- For modal components, ensure the CTA is rendered as an anchor with a real destination URL when appropriate.
- If the interaction is not navigation (e.g., close modal), use a `<button>` and ensure it is accessible.

Rationale: Lighthouse flags anchors without `href` as non-crawlable. Using correct semantics also improves accessibility.

Alternative considered: keep `<a>` without `href` and add JS click handlers. Rejected (SEO + a11y regression).

### 4) Process `global.css` through a production pipeline

Decision: stop serving the main global stylesheet as an unprocessed static asset.

Options:

- Import `global.css` from the Astro entry/layout so Vite can minify it for production builds.
- If the site intentionally keeps a standalone global CSS file, add an explicit build step to minify it and (optionally) run a basic unused rule trimming strategy.

Rationale: Lighthouse currently flags unminified CSS and unused CSS rules; bundling/minification is the most straightforward fix.

Alternative considered: leave it in `public/` and accept lower scores. Rejected (goal is 100s).

### 5) Font loading strategy optimized for mobile performance

Decision: make font loading non-blocking and deterministic.

- Prefer self-hosted fonts or Astro's recommended font strategy.
- Use `font-display: swap` and consider `preload` for critical weights.
- Avoid unnecessary font variants.

Rationale: render-blocking and late text rendering negatively impact Performance and perceived load.

Alternative considered: keep current remote font loading. Rejected if it remains render-blocking.

### 6) Theme token constraints for contrast

Decision: fix contrast failures at the token level first, with targeted overrides only when needed.

- Identify failing color pairs (foreground/background) in dark mode.
- Update tokens in `site/public/styles/global.css` so common surfaces always meet contrast expectations.

Rationale: token-level fixes prevent regressions across multiple components.

Alternative considered: per-component overrides only. Rejected as brittle.

### 7) CSP / Best Practices compliance

Decision: address Lighthouse Best Practices issues by aligning nginx headers with modern expectations without breaking the site.

- Keep security headers in `deploy/nginx.conf`.
- If inline scripts/styles exist, prefer refactoring to external files to avoid unsafe CSP allowances; otherwise use a nonce/hash strategy.

Rationale: strong CSP improves security posture and can satisfy Lighthouse findings, but must be implemented in a way compatible with the build output.

Alternative considered: disable CSP to appease some checks. Rejected.

### 8) Images: reduce third-party variability

Decision: prioritize first-party control of above-the-fold images.

- Use Astro image tooling for locally hosted images.
- For third-party images that block 100s (e.g., external thumbnails), prefer either self-hosting (if allowed) or avoid rendering them above the fold during initial load.

Rationale: image delivery and caching audits can be impossible to satisfy if key images are served from third parties with unknown caching/format behavior.

Alternative considered: ignore image findings. Rejected if they prevent the 100 gate.

## Risks / Trade-offs

- [Lighthouse instability] Scores vary across runs/environments -> Mitigation: lock run configuration and use a clean profile in CI.
- [Build pipeline change risk] Moving `global.css` into bundling may change selector precedence -> Mitigation: diff visual output across themes and add a lightweight snapshot/DOM test where possible.
- [CSP breakage] Tight CSP can block analytics or inline scripts -> Mitigation: inventory scripts, move to external, or add nonce/hash strategy.
- [Third-party dependencies] External media assets may prevent 100 -> Mitigation: reduce third-party assets on gated pages or self-host where permissible.
- [Service worker caching] SW can serve stale assets after deploy -> Mitigation: version critical assets and disable caching for SW + critical CSS, ensure SW update flow.

## Migration Plan

- Implement fixes behind minimal, incremental commits (SEO correctness, crawlable anchors, contrast tokens, CSS pipeline/font loading, CSP).
- Deploy with cache-busting in place so critical style updates reach clients quickly.
- Rollback: revert to a known-good image tag/digest and confirm SW cache versioning does not pin stale assets.

## Open Questions

- Which URLs are included in the Lighthouse gate (home only vs additional pages)?
- Are 100 scores required even when pages include third-party embeds/thumbnails, or should we scope the gate to pages that can be made first-party deterministic?
- Should schema.org structured data be implemented for all pages or only key landing/content types?