clawfort/openspec/specs/hero-display/spec.md

Purpose

Canonical specification for hero-display requirements synced from OpenSpec change deltas.

Requirements

Requirement: Hero block display

The system SHALL display the most recent news item as a featured hero block with full attribution and modal-behavior parity, while omitting a dedicated hero permalink affordance.

Scenario: Hero rendering

• WHEN the page loads
• THEN the hero block SHALL display the latest news headline, summary, and featured image
• AND show source attribution (e.g., "Via: TechCrunch")
• AND show image credit (e.g., "Image: DALL-E")

Scenario: Hero update

• WHEN new news is fetched hourly
• THEN the hero block SHALL automatically update to show the newest item
• AND the previous hero item SHALL move to the news feed

Scenario: Hero-origin modal consistency

• WHEN modal opens from hero context (including permalink-triggered entry)
• THEN modal image, content, and close controls behave consistently with feed-origin modal flows

Scenario: Hero action chrome excludes permalink control

• WHEN the hero block is rendered
• THEN no dedicated hero permalink control is displayed
• AND summary open and source-link actions remain available

Requirement: Infinite scroll news feed

The system SHALL display news items in reverse chronological order with infinite scroll pagination and minimal card chrome.

Scenario: Initial load

• WHEN the page first loads
• THEN the system SHALL display the 10 most recent non-archived news items
• AND exclude the hero item from the feed

Scenario: Infinite scroll

• WHEN the user scrolls to the bottom of the feed
• THEN the system SHALL fetch the next 10 news items via API
• AND append them to the feed without page reload
• AND show a loading indicator during fetch

Scenario: End of feed

• WHEN all non-archived news items have been loaded
• THEN the system SHALL display "No more news" message
• AND disable further scroll triggers

Scenario: Card chrome remains minimal

• WHEN feed cards are rendered
• THEN redundant small "Link" affordance is not shown
• AND card still exposes required source and TL;DR interactions

Requirement: News attribution display

The system SHALL clearly attribute all news content and images to their sources.

Scenario: Source attribution

• WHEN displaying any news item
• THEN the system SHALL show the original source name and link
• AND display image credit if available

Scenario: Perplexity attribution

• WHEN displaying aggregated content
• THEN the system SHALL include "Powered by Perplexity" in the footer

Scenario: Analytics tracking

• WHEN Umami analytics is configured via UMAMI_SCRIPT_URL and UMAMI_WEBSITE_ID
• THEN the system SHALL inject Umami tracking script into page head
• AND track page view events on initial load
• AND track scroll depth events (25%, 50%, 75%, 100%)
• AND track CTA click events (news item clicks, source link clicks)
• AND CTA click payload includes both article_id and article_title when article context is available