4.6 KiB
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
LATESTand 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
- Update hero CTA and hero readability styles in
frontend/index.html. - Update modal sizing and TL;DR shimmer loading state in
frontend/index.html. - Update backend keyword fallback and generic AI image fallback behavior in
backend/news_service.py. - 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?