bulk commit changes!

openspec/changes/archive/2026-02-13-p10-ui-fixes/design.md

@@ -0,0 +1,88 @@
+## Context
+
+`frontend/index.html` currently renders the hero CTA as an external redirect (`window.open(item.source_url)`), and modal sizing is constrained by `max-w-2xl` with `max-h-[90vh]`. TL;DR content does not expose a dedicated loading placeholder, and hero badges can lose readability over bright images. On the backend, `backend/news_service.py` already performs keyword extraction and provider fallback, but defaults remain too generic (`"news technology"`) and do not explicitly prioritize AI-topic fallback behavior.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Keep users on-site by making the hero primary CTA open the existing TL;DR modal flow.
+- Ensure `LATEST` and relative timestamp remain legible over all hero images in light/dark themes.
+- Increase modal usable area (width and near-full-height scrolling behavior) without breaking mobile usability.
+- Add a small horizontal shimmer placeholder for TL;DR bullets while modal content initializes.
+- Improve image relevance with stronger AI-focused keyword fallback and deterministic generic AI-image fallback when lookup fails.
+
+**Non-Goals:**
+- Rebuilding the full feed card architecture.
+- Replacing existing provider integrations or adding new third-party image providers.
+- Introducing backend sentiment ML models.
+- Reworking scheduler or ingestion cadence.
+
+## Decisions
+
+### Decision: Reuse existing modal interaction path for hero CTA
+**Decision:** Wire hero CTA to the same `openSummary(item)` behavior used by feed cards.
+
+**Rationale:**
+- Reuses existing event tracking and modal rendering logic.
+- Avoids duplicate interaction models and reduces regression risk.
+
+**Alternatives considered:**
+- Add a second hero-only modal implementation: rejected due to duplicate UI state and maintenance cost.
+
+### Decision: Enforce readability with layered overlay + contrast-safe tokens
+**Decision:** Strengthen hero overlay and badge/text color tokens so metadata remains visible independent of image luminance.
+
+**Rationale:**
+- Solves visibility issues without image preprocessing.
+- Keeps responsive behavior in CSS instead of JS image analysis.
+
+**Alternatives considered:**
+- Dynamic luminance detection per image: rejected as unnecessary complexity for current scope.
+
+### Decision: Expand modal dimensions with responsive constraints
+**Decision:** Use a wider desktop container (minimum half viewport intent) while preserving mobile full-width behavior and near-full-height scrolling.
+
+**Rationale:**
+- Improves readability for summary blocks and TL;DR bullets.
+- Keeps accessibility of close controls and keyboard escape path.
+
+**Alternatives considered:**
+- Full-screen modal only: rejected due to excessive visual disruption on desktop.
+
+### Decision: Treat TL;DR loading as explicit skeleton state
+**Decision:** Add a low-height horizontal shimmer placeholder visible when TL;DR is not yet available.
+
+**Rationale:**
+- Reduces perceived latency ambiguity.
+- Matches existing skeleton design language already used for images/cards.
+
+### Decision: Improve fallback query semantics for AI-news image retrieval
+**Decision:** Enhance keyword fallback to AI-focused defaults (`ai machine learning deep learning`) and add explicit generic AI image fallback contract.
+
+**Rationale:**
+- Reduces irrelevant imagery when topic extraction is weak or providers return noisy results.
+- Keeps behavior deterministic and testable.
+
+## Risks / Trade-offs
+
+- **[Risk] Wider modal may crowd smaller laptops** -> Mitigation: use responsive width caps with mobile-first breakpoints and overflow handling.
+- **[Risk] Hero overlay could darken images too much** -> Mitigation: tune gradient opacity and preserve theme-specific token overrides.
+- **[Risk] Fallback image monotony if providers fail frequently** -> Mitigation: keep provider chain first; generic AI fallback only as terminal fallback.
+- **[Trade-off] Stronger AI default keywords may reduce non-AI niche relevance** -> Mitigation: apply defaults only when extracted keywords are insufficient.
+
+## Migration Plan
+
+1. Update hero CTA and hero readability styles in `frontend/index.html`.
+2. Update modal sizing and TL;DR shimmer loading state in `frontend/index.html`.
+3. Update backend keyword fallback and generic AI image fallback behavior in `backend/news_service.py`.
+4. Verify behavior manually on desktop/mobile and run relevant checks.
+
+Rollback:
+- Revert hero CTA to external link behavior.
+- Revert modal class and shimmer additions.
+- Revert keyword/default fallback updates in image pipeline.
+
+## Open Questions
+
+- Should generic AI fallback be local static asset only, or deterministic remote URL with local optimization?
+- Do we need separate fallback keyword sets per language now, or keep English-focused defaults in this change?