astro-website/openspec/changes/archive/2026-02-10-lighthouse-fixes/proposal.md

Why

Chrome Lighthouse runs against the production site show repeated misses across Performance, SEO, Best Practices, and (in dark theme) Accessibility. These gaps reduce technical robustness and make it hard to trust deploy-to-deploy quality.

We want the site to be measurably correct and fast under a repeatable, automated Lighthouse configuration, and to treat Lighthouse regressions as build-blocking.

What Changes

• Make SEO outputs Lighthouse-clean by fixing robots.txt validity (absolute sitemap URL) and ensuring key links are crawlable.
• For better SEO, implement schema based on https://schema.org/docs/full.html
• If it helps performance and SEO, minify relevant assets.
• Remove non-crawlable anchor patterns (anchors without href) in the media modal and CTA surfaces.
• Fix dark theme contrast failures so text and links meet WCAG intent and Lighthouse color-contrast passes.
• Reduce render-blocking work in the initial load path (fonts + global stylesheet) to improve mobile Performance.
• Reduce CSS overhead by moving global.css through the build/minification pipeline and trimming unused rules.
• Eliminate forced reflow hotspots caused by synchronous layout reads/writes in scroll/resize handlers.
• Improve image delivery (size, format, and caching) to address Lighthouse image savings and cache lifetime findings.
• Add a deterministic Lighthouse quality gate (CI or scripted) that runs against known URLs, form factors, and themes and requires 100s in a clean environment (no extensions).

Capabilities

New Capabilities

• lighthouse-quality-gate: Define the target Lighthouse configuration (URLs, mobile/desktop, themes, run environment) and require 100/100/100/100 with report artifacts.
• responsive-image-delivery: Deliver appropriately sized images and modern formats (or controlled proxies/self-hosting) for key surfaces so image delivery audits pass consistently.

Modified Capabilities

• seo-content-surface: Ensure robots.txt is valid and sitemap references are correct for the deployed domain; ensure Lighthouse SEO crawlability audits pass.
• media-modal: Ensure modal fallback and CTA links are crawlable anchors (real hrefs) and remain accessible.
• wcag-responsive-ui: Tighten requirements to prevent Lighthouse accessibility regressions (contrast and keyboard/focus behavior).
• site-theming: Ensure dark theme tokens never produce low-contrast text-on-light backgrounds on primary surfaces.
• service-worker-performance: Ensure caching behavior does not cause stale critical assets after deploy, and align cache strategy/headers with Lighthouse expectations where feasible.

Impact

• Affected areas include: site/public/robots.txt, site/src/layouts/BaseLayout.astro, site/src/components/MediaModal.astro, site/public/styles/global.css, site/public/sw.js, and deploy/nginx.conf.
• This change may require build-pipeline adjustments (CSS processing/minification, image processing or controlled caching/proxying) and CI scripting to run Lighthouse deterministically.
• Some Lighthouse findings are attributable to third-party resources (e.g., YouTube thumbnails, externally hosted podcast art) and/or local Chrome extensions; hitting a strict 100 may require reducing third-party dependence and running audits in a clean profile.
• Coding agent may run out of context window. In that case, compact the context and retry with chunking.