astro-website/openspec/changes/archive/2026-02-10-lighthouse-fixes/specs/media-modal/spec.md

MODIFIED Requirements

Requirement: Media modal dialog

The site MUST provide a modal dialog that displays embedded media (YouTube video or podcast episode) when a user clicks a video or podcast content card on a listing surface (homepage, /videos, /podcast).

The modal MUST render the following elements in order:

• A header row with the content title on the left and a close button on the right
• An embedded media player (YouTube iframe for videos; Spotify embed for podcast episodes when the URL is a Spotify URL; otherwise an in-modal audio player when an audioUrl is available)
• The full description/summary text (not truncated)
• The publish date and view count (when available)
• A "Subscribe on YouTube" / "Follow on Spotify" CTA and a "View on YouTube" / "Listen on Spotify" CTA

All modal CTAs that represent navigation MUST be implemented as crawlable anchors:

• Each CTA MUST be an <a> element with a non-empty href attribute.
• The UI MUST NOT render placeholder <a> elements without href in the initial HTML.
• If CTA destinations are not known until a user selects an item, the CTA UI MUST be rendered as non-anchor elements until the destinations are known.

Scenario: User clicks a YouTube video card

• WHEN a user clicks a video content card on any listing surface
• THEN a modal dialog opens displaying a YouTube iframe embed, the video title, full description, date, view count (if available), and CTAs for "Subscribe on YouTube" and "View on YouTube"

Scenario: User clicks a podcast episode card with a Spotify URL

• WHEN a user clicks a podcast content card whose URL is a Spotify URL
• THEN a modal dialog opens displaying a Spotify episode embed, the episode title, full description, date, and CTAs for "Follow on Spotify" and "Listen on Spotify"

Scenario: User clicks a podcast episode card with a non-Spotify URL

• WHEN a user clicks a podcast content card whose URL is not a Spotify URL
• THEN the modal dialog opens displaying the episode metadata (title, description, date) and either:
  • an in-modal audio player when an audioUrl is available
  • otherwise, a "Listen on Spotify" outbound link

Scenario: Modal renders with missing optional fields

• WHEN a content item has no view count or no summary
• THEN the modal MUST still render cleanly with those fields omitted

Scenario: Modal CTAs are crawlable anchors

• WHEN the modal is present in the DOM (before any user interaction)
• THEN the document contains no <a> elements in the modal that are missing href

ADDED Requirements

Requirement: Embed fallback is a link only when a destination is available

If an embed fallback is presented as a link to an external page, it MUST be an anchor with a valid href. If no destination is available, the fallback MUST be hidden or rendered as non-link text.

Scenario: Embed fallback does not render a non-crawlable anchor

• WHEN the modal is rendered before any item selection
• THEN the embed fallback is not rendered as an anchor without href