bsky-social-app/docs/superpowers/specs/2026-04-21-lightbox-refresh-design.md

Lightbox Refresh — Design Spec

Ticket: APP-2046 Figma: https://www.figma.com/design/TqFguaWhkvAPnCth5u7cvE/Everything?node-id=7221-2117 Branch: app-2046 PR strategy: one PR — migration + reskin together

Summary

Refresh lightbox chrome and co-locate all lightbox code under /features/lightbox/. Native gets a new visual treatment (translucent circular buttons, dots pagination, menu-based Share/Save). Web gets a minimal reskin of buttons and menu, no layout changes. All gestures, animations, pager mechanics, and the underlying image viewer are preserved.

Scope

In scope

• Move every lightbox file into /features/lightbox/ with a light reorg.
• Rebuild native chrome (header, footer, pager dots, image menu).
• Reskin web chrome buttons to match native's translucent treatment.
• Add Share image menu item on web (currently only Download image).
• Restyle alt-text strip on both platforms to match.

Out of scope

• Reaction bar (labeled "Inactive" in Figma).
• Web layout changes — keep chevron navigation, keep alt-text expand behavior, keep keyboard shortcuts.
• Gesture code (pinch/pan/zoom/swipe-to-dismiss) — file moves only.
• Open/close spring animation and backdrop fade — file moves only.
• Alt-text interaction model — kept, just restyled.

Target file structure

/src/features/lightbox/
├── index.tsx                       # re-exports Lightbox (platform split)
├── Lightbox.tsx                    # native shell (from view/com/lightbox/Lightbox.tsx)
├── Lightbox.web.tsx                # web impl (from view/com/lightbox/Lightbox.web.tsx)
├── state.tsx                       # from state/lightbox.tsx
├── types.ts                        # from ImageViewing/@types/index.ts
├── chrome/
│   ├── CircleChromeButton.tsx      # NEW — shared primitive for ••• and ✕
│   ├── Header.tsx                  # NEW — replaces ImageDefaultHeader
│   ├── Footer.tsx                  # NEW — replaces LightboxFooter
│   ├── PagerDots.tsx               # NEW — dots indicator (native only)
│   └── ImageMenu.tsx               # NEW — ContextMenu wrapper
└── pager/
    ├── ImagePager.tsx              # from ImageViewing/index.tsx
    ├── transforms.ts               # from ImageViewing/transforms.ts
    └── ImageItem/
        ├── ImageItem.tsx
        ├── ImageItem.ios.tsx
        └── ImageItem.android.tsx

Source-to-destination map

From	To
src/state/lightbox.tsx	src/features/lightbox/state.tsx
src/view/com/lightbox/Lightbox.tsx	src/features/lightbox/Lightbox.tsx
src/view/com/lightbox/Lightbox.web.tsx	src/features/lightbox/Lightbox.web.tsx
src/view/com/lightbox/ImageViewing/index.tsx	src/features/lightbox/pager/ImagePager.tsx
src/view/com/lightbox/ImageViewing/transforms.ts	src/features/lightbox/pager/transforms.ts
src/view/com/lightbox/ImageViewing/@types/index.ts	src/features/lightbox/types.ts
src/view/com/lightbox/ImageViewing/components/ImageItem/*	src/features/lightbox/pager/ImageItem/*
src/view/com/lightbox/ImageViewing/components/ImageDefaultHeader.tsx	deleted — replaced by chrome/Header.tsx

Consumer import updates

All the imports that must move from #/state/lightbox → #/features/lightbox/state or #/view/com/lightbox/Lightbox → #/features/lightbox:

State (LightboxStateProvider, useLightbox, useLightboxControls, type Lightbox):

• src/App.native.tsx
• src/App.web.tsx
• src/state/util.ts
• src/screens/Profile/Header/Shell.tsx
• src/components/Post/Embed/ImageEmbed.tsx
• src/view/com/profile/ProfileSubpageHeader.tsx
• src/view/com/util/List.tsx

Lightbox component itself:

• src/view/shell/index.tsx
• src/view/shell/index.web.tsx

Internal imports within the lightbox files themselves will also update (e.g., ImagePager.tsx importing the type from sibling state.tsx).

Native chrome design

chrome/CircleChromeButton.tsx

• Shared primitive used by ••• and ✕ triggers, and reused on web.
• 36 × 36 pressable circle.
• Background: rgba(0, 0, 0, 0.45) — fixed, not theme-driven, because it sits over arbitrary images.
• Icon: white, 20px.
• hitSlop: 10.

chrome/Header.tsx

• Absolutely-positioned row, top: insets.top, px_md, py_sm.
• Left slot: ImageMenu trigger (•••).
• Right slot: CircleChromeButton with XIcon, closes lightbox.
• Show/hide driven by the existing showControls shared value in ImagePager.tsx (opacity + translateY). No new gesture logic.

chrome/ImageMenu.tsx

• Wraps ContextMenu.Outer + ContextMenu.Trigger.
• Trigger child renders CircleChromeButton with DotsHorizontal icon.
• onTap handler calls control.open('full') so single tap opens — no press-and-hold.
• Two items:
  • Share image → ShareIcon, calls existing share util.
  • Save image → Download, calls existing save util.
• Menu card surface is theme-aware (white in light mode, dark in dark mode) — inherited from ContextMenu's defaults.

chrome/Footer.tsx

• Absolutely-positioned, bottom: insets.bottom, px_md, pb_sm.
• Renders AltTextStrip (if current image has alt text) above PagerDots.
• AltTextStrip:
  • Translucent dark surface: rgba(0, 0, 0, 0.45).
  • White text, text_sm.
  • Tap expands/collapses (port the expand/collapse state logic from Lightbox.web.tsx lines 227-245).

chrome/PagerDots.tsx

• Renders only when images.length > 1.
• Bottom-center row.
• Active dot: 6 × 6, bg: white.
• Inactive dot: 6 × 6, bg: rgba(255,255,255,0.4).
• Gap: 4px.
• Active index driven by the existing imageIndex shared value the pager exposes.

Web chrome design

Changes in Lightbox.web.tsx are visual only:

• Replace the existing menu trigger button (lines 251-296) and close button (lines 297-312) with CircleChromeButton from the native chrome folder. (It's a plain styled Pressable — platform-agnostic.)
• Menu items:
  • Existing Download image stays.
  • NEW Share image — uses Web Share API when available, falls back to copy-link-to-clipboard.
• Restyle alt-text strip to match native's translucent treatment. Keep expand/collapse behavior.

Web out of scope (confirmed)

• Left/right chevron navigation (lines 184-225).
• Screen-reader "Image N of M" announcement (line 246-250).
• Keyboard shortcut registration / hotkey scope management.
• No dots indicator on web (chevrons + "Image N of M" already serve this role).

Preserved behaviors

Both platforms keep:

• Tap-to-toggle chrome visibility.
• Swipe-down-to-dismiss (native).
• Pinch/pan/double-tap zoom.
• Horizontal pager between images.
• Open/close spring from source thumbnail.
• expo-screen-orientation lock on open, unlock on close.
• Hotkey scope disable while lightbox is open.

Boundaries

• chrome/ depends only on #/components and the state module. It knows nothing about gestures or pager internals.
• pager/ owns gestures, layout, animation. Chrome is rendered via props/slots.
• state.tsx exports are unchanged — pure move with updated import paths.
• CircleChromeButton is reused across native header and web chrome — one visual source of truth.

Testing & verification

• Visual inspection on iOS simulator, Android emulator, web.
• Verify open/close animation unchanged from main.
• Verify tap-to-toggle chrome still works.
• Verify share and save still work end-to-end from the new menu.
• Verify alt text still displays and expands.
• Confirm no new TypeScript errors: yarn typecheck.
• Confirm no new lint errors: yarn lint.
• Confirm Jest still passes: yarn test.