First deployment

openspec/changes/archive/2026-02-13-p14-bugs/design.md

@@ -0,0 +1,58 @@
+## Context
+
+Recent usability enhancements introduced regressions in modal consistency, footer/header behavior, and share/contact visibility. The issues are cross-cutting: SPA URL state, modal lifecycle handling, theme contrast, sticky surface behavior, and image relevance heuristics. The fixes must remain incremental and avoid feature re-architecture.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Restore modal parity for hero and feed deep links, including image loading and Escape-close behavior.
+- Ensure contact email is rendered when configured and share controls are visible in light mode.
+- Introduce copy-to-clipboard sharing and remove redundant card permalink affordance.
+- Implement floating Back-to-Top and compact sticky footer.
+- Implement sticky, shrinking, elevated glass header behavior on scroll.
+- Tighten image relevance fallback behavior for finance/market stories.
+
+**Non-Goals:**
+- Full UI redesign.
+- New backend image provider integrations.
+- New analytics taxonomy.
+
+## Decisions
+
+### Decision 1: Normalize deep-link modal resolution path
+Use one resolver for both hero and feed items, and open modal only after item context is guaranteed.
+
+### Decision 2: Decouple modal close from item existence
+Escape and backdrop close should dismiss the modal even if modal item resolution is partially failed.
+
+### Decision 3: Theme-safe icon tokens
+Share icon foreground/background tokens are split per theme to guarantee visibility in light mode.
+
+### Decision 4: Sticky surfaces with conservative footprint
+Header remains sticky and shrinks slightly with blur/elevation on scroll; footer remains sticky with minimal height and readable contrast.
+
+### Decision 5: Finance-aware image fallback guard
+If query contains market/finance intent, reject obviously unrelated animal/person close-up imagery via keyword guards and force finance-safe fallback query.
+
+## Risks / Trade-offs
+
+- **[Risk] Sticky footer could occlude content** -> Mitigation: add bottom spacing to main content and reduce footer height.
+- **[Risk] Header animation jank on low-end devices** -> Mitigation: simple transform/opacity transitions only.
+- **[Risk] Stricter image relevance may reduce variety** -> Mitigation: constrain guardrails to high-confidence finance terms only.
+
+## Migration Plan
+
+1. Patch modal/deep-link lifecycle and close semantics in frontend state handlers.
+2. Patch share/contact visibility and add copy-link control.
+3. Implement sticky header/footer visual behavior.
+4. Patch image-query relevance guard in backend image selection.
+5. Validate with manual regression checklist.
+
+Rollback:
+- Revert header/footer sticky behavior.
+- Revert modal resolver and share changes.
+- Revert image guardrails to prior fallback logic.
+
+## Open Questions
+
+- Should copy-link action include transient toast feedback in this change or next UX pass?