Make Product Screenshots Theme-Aware Across Light/Dark Modes

[jamespepper81]

Product screenshots on the marketing/landing pages currently appear in a single (likely light) theme regardless of the user’s selected site theme. This breaks visual consistency and reduces the perceived polish of the platform. We want screenshots (app UI, dashboards, wallet views, analytics panels) to adapt so that when a visitor switches themes, showcased imagery matches.

Problem / Motivation

• Mismatch between site theme and screenshot theme can feel jarring.
• Dark mode users may perceive product as not fully dark-mode ready.
• Inconsistent presentation harms brand trust and accessibility.
• Static image management becomes unruly as features evolve.

Goals

• Provide theme-aware screenshots (light + dark variants) for all key product visuals.
• Ensure fast loading and no layout shift during theme toggle.
• Centralize screenshot asset management.
• Allow future automation (e.g., scripted generation from component states).
• Optimize images (format, responsive sizes, compression).

Non-Goals

• Full automated visual regression system (future).
• Dynamic screenshots for arbitrary user-selected accent colors (only light/dark now).

Scope Targets (Initial Asset Inventory to Validate)

• Landing page hero sections (both landing pages).
• Feature highlight blocks (wallet security, key management, bitcoin transparency analytics).
• iOS & Android wallet showcase frames.
• AI-enhanced blockchain analysis panels (if displayed).
• Any carousel/gallery of the product UI.

User Stories

• As a visitor using dark mode, I want screenshots to reflect dark styling so the product feels cohesive.
• As a marketing editor, I want a simple way to add/update both theme variants for a screenshot.
• As a developer, I want a predictable file + component pattern for theme-switchable images.

Acceptance Criteria

• Switching site theme updates all showcased product screenshots within ≤150ms without page reload.
• No visible flicker or placeholder; images either preloaded or gracefully swapped.
• Lighthouse/Pagespeed: no significant regression in LCP due to screenshot handling.
• All targeted screenshots have both light & dark assets verified.
• Fallback: if dark variant missing, gracefully display light version (and log warning in dev).

Technical Approach (Proposed)

1. Asset Strategy
   • Store images under /public/screenshots/{context}/{light|dark}/
   • Naming convention: feature-key_[size?].png (or .webp preferred).
2. Component Wrapper
   • Create <ThemeImage lightSrc="..." darkSrc="..." alt="..."/> that:
     • Uses Next.js Image for optimization.
     • Reads current theme (via context / next-themes).
     • Preloads the alternate variant with <link rel="preload"> on first render.
3. Build-Time Validation (Optional Enhancement)
   • Small script to scan for referenced images and ensure both themes exist.
4. Future-Proofing
   • Optionally adopt playwright script to auto-generate theme screenshots from live Storybook stories (deferred).
5. Performance
   • Use modern formats (webp/avif).
   • Provide width/height to avoid CLS.
   • Consider responsive srcset for mobile hero vs desktop.

Accessibility

• Ensure alt text is meaningful (avoid “Screenshot of dashboard” – prefer “Bitcoin UTXO analysis dashboard showing risk tiers”).
• If dark screenshot has contrast changes, verify minimum WCAG contrast for embedded text in imagery (where critical).

Risks

• Increased bundle/network weight if both variants aggressively requested.
• Manual upkeep if product UI changes frequently.
  • Mitigation: Lazy load non-visible sections; schedule a monthly screenshot audit.

Dependencies / Related

• Theme provider (next-themes or custom) stability.
• Design team sign-off on dark variants styling.
• Any upcoming redesign of landing pages (coordinate to avoid churn).

Open Questions

1. Do we already have dark-mode designs for all showcased screens?
2. Should we prefer automated generation from running the app (to avoid manual exports)?
3. Are mobile (iOS/Android) frames different between themes or static chrome?
4. Any plans for additional themes (e.g., high-contrast) soon?

Labels

• enhancement
• frontend
• design
• accessibility
• marketing

Suggested Milestone
Q4 Polish or Launch Readiness (adjust to your roadmap)