Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
49.3 KB
Raw Blame

schema_version: 3 template_version: 3 kind: component id: component:Lightbox authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-31 owners: [cixzhang] review_triggers: [public-api, behavior, interaction, theming, accessibility] verified_by: [ packages/core/src/Lightbox/Lightbox.test.tsx, packages/core/src/Lightbox/LightboxKeyboard.a11y.browser.spec.ts, packages/core/src/Lightbox/LightboxViewport.a11y.browser.spec.ts, packages/core/src/theme/themingTargets.test.ts, scripts/check-knowledge.mjs, ] modules: [] families: [family:overlay-dismissal] design_specs: [design:reduced-motion] architecture: [ architecture:component-theming-surface, architecture:interaction-modality, architecture:layer-runtime, architecture:public-component-api, architecture:react-component-runtime, ] contributing: []

system_specs: [spec:AST-017, spec:AST-020, spec:AST-086, spec:AST-094]

Lightbox component contract

Intent

Lightbox presents one active image or video in a full-viewport viewer and may add gallery navigation, a caption, and a position counter. On a touch screen it behaves like a native photo viewer: a person pinches and double-taps to zoom, swipes between items, drags a photo down or pinches it in to close, and taps to hide the controls. Every gesture has a button, key, or single-pointer alternative, so keyboard, screen-reader, and single-pointer users reach the same actions.

Compatibility and migration

  • Released default preserved: no. Under a coarse primary pointer the touch presentation (FR5–FR10) and the touch exit (FR16) are the default (spec:AST-094 FR13). Under a fine pointer a mouse or pen drag pages and closes the viewer, a ctrl-wheel or trackpad pinch over the photo zooms the photo instead of the page, a trackpad's scroll pans a zoomed photo, and a double-click zooms 2× about the clicked point instead of the centre (FR11). Preserved: a click on the photo keeps the controls, the viewer opens at once under every pointer and closes at once under a fine pointer, keyboard zoom stays 2× about the centre, and video playback and controls are unchanged; a drag on a video item's frame pages (FR7)
  • Compatibility class: additive behavior, released in three kinds under spec:AST-017. [fix] under FR53, as accessibility conformance: Tab containment (FR4), the double-click about the clicked point (AR2), the 0 key (AR3), and position and zoom announcements delivered inside the open viewer with the zoom level (AR4). [feat]: the touch presentation and touch exit (FR5–FR10, FR16) and the fine-pointer gestures (FR11), which are named cross-device consistency under FR59 and need fine-pointer evidence before and after. [experimental]: the thumbnail transition and experimental.sourceFor (FR12, FR21)
  • Controlled/uncontrolled behavior: unchanged; a swipe reports through onIndexChange, and a controlled index the caller refuses springs back
  • Migration decision: none required. hasZoom={false} turns off FR6, FR9, and FR10 (FR13)

Consumer migration instructions belong in consumer docs and release notes.

Current-state impact

The shipped Lightbox does not yet meet every requirement below. Each gap names the requirement it misses and the person it affects.

  • Touch presentation (FR9, FR10, FR12). On a touch screen there is no pinch to close, tap to hide the controls, or thumbnail transition.
  • Drag to close (FR8). Implementation gap: the close is reported when the photo has left the screen, about 0.3–0.5 s after the lift, until the shared exit hold lets the viewer stay up after a reported close.
  • Paging motion roles (FR5). The page settle plays the pager's own UIKit values, which the motion role table does not list as roles.
  • Video controls (FR7). A video's native controls are taken as a 48 px band at its bottom edge, since browsers expose no control geometry; a browser that places controls elsewhere pages from them.
  • Zoom announcement (AR4). A zoom change announces "zoomed in" or "zoomed out" without the zoom level.
  • Fine-pointer gestures (FR11). FR11's drag paging (FR7) and drag to close (FR8) are not built for a mouse, a pen or a trackpad: a drag on a fitted photo does nothing.
  • Double-click listener (FR14). A mouse's or a pen's double-click reaches the zoom through the stage's own dblclick listener, since only the browser knows the system's double-click speed.
  • Press tracker (FR14). The viewer's own pointerdown handler records each press's pointer type and point, which the browser's dblclick and click do not carry, and clears the flag a drag leaves for its click.
  • Touch exit (FR16). On a touch screen the viewer disappears at once when it closes.

Ownership boundary

Owns

  • The Viewer overlay and its current lightbox target.
  • Media presentation, optional Caption and Counter placement, gallery navigation, image zoom and pan, the touch presentation (FR5–FR12), and the touch exit (FR16).
  • The accessible alternative for every gesture it presents (AR1–AR8).

Does not own / non-goals

  • The Close, Previous, and Next button surfaces — delegated to component:Button through IconButton.
  • Caller-provided Caption content.
  • New targets for Media, Caption, or Counter; none exist.
  • Shared layer hosting or dismissal policy — owned by architecture:layer-runtime and family:overlay-dismissal.
  • Touch physics, measured values, and motion roles' values — owned by spec:AST-094 and its measured motion table.

Public concepts

No new stable public concept is introduced. experimental.sourceFor is an experimental option inside the experimental prop object (spec:AST-017 FR21). Consumer props and usage remain documented in Lightbox.doc.mjs.

Behavioral and layout contract

ID Candidate invariant Basis Draft review state
FR1 The viewer contains one active Media item and a Close button; galleries additionally contain Previous and Next buttons plus a Counter, and Caption renders only when supplied. Current source, docs, and tests settled
FR2 Viewer overlay carries the current lightbox target. Media, Caption, and Counter carry no Lightbox public target. Current source and public docs settled
FR3 Close, Previous, and Next button surfaces use Button's button target through IconButton rather than Lightbox-owned button targets. Current source and target docs settled
FR4 The open viewer is a focus region through Core's shared focus-region module (component:Dialog/DEC-2): Tab from its last control moves focus to its first and Shift+Tab from its first moves focus to its last, so focus never leaves the viewer for the browser's own interface. component:Dialog/DEC-2 settled; implementation gap
FR5 Under a coarse primary pointer, after hydration, Lightbox presents FR6–FR10 with no opt-in. Lightbox's main interaction is a gesture, so every move in them (the zoom settle, a double tap's zoom, the page settle, the dismissal, a cancelled drag's return and the pinch close) is a spring on a named motion role read through the motion role table, never a literal, and a release starts at the gesture's velocity; the controls fade is companion motion on the pace of the main spring (spec:AST-094 FR45). The dismissal plays Photos' measured springs, on the roles the Motion section lists (spec:AST-094 FR4). Under reduced motion they follow AR6. spec:AST-094 FR4, FR13 settled; implementation gap
FR6 With hasZoom, on an image, a pinch zooms about the fingers and pans while it zooms; past the minimum or maximum the photo resists and eases back without overshoot. A double tap zooms to the larger of filling the viewer and 2×, about the tapped point; a second double tap returns to the fitted size. A zoomed photo pans with momentum and rubber-band edges. A pinch on the controls or the caption still zooms the page. spec:AST-094 FR3, FR10 settled; implementation gap
FR7 In a gallery, a horizontal drag moves the row of items, which sit apart by the measured gap. The release lands on at most one neighbouring item by spec:AST-094 FR3's paging rule (DEC-25). Paging applies over a video item's frame as over a photo; a drag that starts on the video's own controls, such as its scrubber or volume, stays the video's. A zoomed photo pans to its edge before a new drag pages. A pinch never pages. Previous, Next, and the arrow keys keep paging. A controlled index the caller refuses springs back. onIndexChange reports a swipe. spec:AST-094 FR3, FR14, FR36–FR39, DEC-25 settled; implementation gap
FR8 On a fitted image, a downward drag moves the photo with the finger, shrinks it, and fades the backdrop. The release decides once: a projected travel past the commit point closes the viewer and reports onOpenChange(false) at the lift; a release moving back springs back. Video is unchanged. spec:AST-094 FR4, FR36–FR40, FR45 settled; implementation gap
FR9 With hasZoom, a pinch in from the fitted size is a release decision: below the measured fraction of the fitted size the release closes the viewer; opening the fingers again by the measured amount before the lift is moving back and cancels. A pinch that starts zoomed in never closes the viewer. spec:AST-094 FR36, FR37 settled; implementation gap
FR10 With hasZoom, under a coarse pointer only, a tap on the photo fades the controls and caption and darkens the backdrop. While they are hidden, the next tap on the photo, a tap beside the photo, or a cancelled drag brings them back, and that tap beside the photo does not close the viewer (ORD3). AR5 governs keyboard and assistive-technology access while they are hidden. architecture:public-component-api INV16 settled; implementation gap
FR11 A mouse, a pen, and a trackpad also use FR7's drag paging, FR8's drag to close, a ctrl-wheel or trackpad pinch over the photo for FR6's zoom and FR9's close, and a trackpad's scroll to pan a zoomed photo; a mouse wheel's notches leave it in place (spec:AST-094 FR43); over the photo these replace the browser's page zoom and scroll. A double-click zooms 2× about the clicked point. A click on the photo keeps the controls, and the viewer opens and closes at once. spec:AST-094 FR43; spec:AST-017 FR59 settled; implementation gap
FR12 Inside experimental only, under a coarse pointer, the photo grows out of its source when the viewer opens, and returns into it when it closes, on springs, springs.settle unless the motion table names another role, since Lightbox's main interaction is a gesture (spec:AST-094 FR7, FR45): the element experimental.sourceFor(index) returns, else the opener when it shows a picture. A close reports onOpenChange(false) at the request; the viewer stays only until the photo lands. Pointer input during the entrance is held; keys and assistive technology stay live. Without experimental, opening is unchanged and closing plays FR16. spec:AST-017 FR21; spec:AST-094 FR35 settled; implementation gap
FR13 hasZoom={false} turns off FR6, FR9, and FR10. FR7 and FR8 add to the buttons, keys, and Escape and remove none of them, so Lightbox takes no presentation prop. architecture:public-component-api INV16 settled
FR14 Gestures, paging, motion, and reduced motion run through Core's one shared set of internal touch modules; Lightbox bundles no copy of a module's primitive and adds no gesture listener outside them. architecture:react-component-runtime INV13 settled; implementation gap
FR15 Lightbox supports a Picture-in-Picture window as its only second document; there it ranks Escape and platform close among that window's members. family:overlay-dismissal FR8 settled
FR16 Under a coarse primary pointer, a close that is not a drag down (FR8), a pinch in (FR9), or a return into a source (FR12) plays the touch exit: Close, Escape, a platform close, and a tap beside the photo while the controls are shown (ORD3). The photo shrinks a little and fades out in place with the backdrop and controls, as the native viewer's zoom transition does without a source, on a spring from rest, springs.settle unless the motion table names another role, with the backdrop and controls fading on its pace (spec:AST-094 FR7, FR45). onOpenChange(false) reports at the request, and the viewer takes no input while the exit plays. Under a fine pointer the viewer closes at once (FR11). spec:AST-094 FR7 settled; implementation gap
FR17 For any index, controlled or default, the viewer opens on the nearest valid item: below 0 the first, past the last the last. A fraction rounds to the nearest item, and NaN opens the first. Current source and tests settled
FR18 In a gallery, a video on a neighbouring page stays mounted and paused while another item shows. Paging back to it shows it where it stopped, as the platform photo viewer does: paused, or playing on from there with hasAutoPlay. Current source and tests settled

Motion

A drag down that closes the viewer plays Photos' measured dismissal springs. Each is a motion role, so the exit plays at the theme's tempo, as every other move in the viewer does. At tempo 1 it plays the values below exactly (FR5, spec:AST-094 FR4). Every other spring a gesture drives, a cancelled drag's return included, plays springs.settle.

Spring Value Platform source
zoomMedia.dismiss.dismissPositionSpring Mass 1, stiffness 918.09, damping 60.60 Photos, iOS 26.2 simulator, iPhone 17 Pro: a committed drag to dismiss, the zoom view's position animation (CASpringAnimation)
zoomMedia.dismiss.dismissSizeSpring Mass 1, stiffness 947.14, damping 61.55 Photos, iOS 26.2 simulator, iPhone 17 Pro: the same dismissal's bounds and opacity animations (CASpringAnimation)

Allowed variation

  • AV1 — Media mode. Media may be an image or video; zoom, pan, drag down to close, pinch to close, and the tap that hides the controls are available only on images. Paging applies to both (FR7).
  • AV2 — Gallery mode. Previous, Next, and Counter are absent for a single item. Navigation button disabled state follows the current gallery boundary.
  • AV3 — Caption content. Caller-provided Caption content may vary without becoming a Lightbox-owned target.
  • AV4 — Measured values. Thresholds, gaps, commit points, and timings may change with the measured motion table without changing this record.

Representative states

State Required invariant Allowed variation
Single image Viewer overlay, Media, and Close button render. Caption and zoom may be absent or present.
Gallery boundary Both navigation buttons and Counter remain rendered. Previous or Next is disabled at its boundary.
Video Media renders native video controls without image zoom interaction. Autoplay follows the existing consumer prop.
Captioned media Caption follows the active Media inside the centered media group. Caption content remains caller-provided.
Zoomed image A double tap or double-click, -, or 0 returns to the fitted size. The zoom level and pan position.
Controls hidden Controls stay focusable and in the accessibility tree; focus or a key brings them back. Backdrop shade while hidden.

Transformation and precedence order

  • ORD1 — Zoom before paging. A drag on a zoomed photo pans it until the photo's edge; only a new drag from that edge pages (FR7).
  • ORD2 — Fitted size before closing. A drag down or a pinch in closes the viewer only from the fitted size (FR8, FR9).
  • ORD3 — Hidden controls before closing. While the controls are hidden, the first tap beside the photo only brings them back; only while they are shown does a tap beside the photo close the viewer (FR10, FR16).

Performance and resources

  • PR1 — Settles survive a busy page. Zoom, page, dismiss, and transition settles keep moving while the main thread is busy (spec:AST-094).

Accessibility contract

Every expectation below cites its WCAG 2.2 Level A or AA success criterion under spec:AST-020 FR1; reduced motion cites design:reduced-motion.

  • AR1 — Every multipoint or path gesture has a single-pointer alternative (WCAG 2.2 2.5.1). Pinch zoom has the double tap or double-click (FR6, FR11); swipe paging has the Previous and Next buttons (FR7); drag down and pinch in to close have the Close button (FR8, FR9).
  • AR2 — Every drag has a non-drag alternative (WCAG 2.2 2.5.7). Drag to close has the Close button; drag paging has the Previous and Next buttons; a zoomed photo's pan has the double tap or double-click, which returns to the fitted size, and a double tap or double-click on a point, which zooms in about that point (FR6, FR11).
  • AR3 — Keyboard operation (WCAG 2.2 2.1.1, 2.1.2, 2.4.3). Escape closes the viewer. ArrowLeft and ArrowRight page in the logical direction, so in a right-to-left page ArrowLeft moves to the next item. With hasZoom, + zooms in, - zooms out, and 0 returns to the fitted size; while zoomed, the arrow keys pan the photo. Focus stays inside the viewer (FR4), and on close returns to the element that opened the viewer when that element is still connected and can receive focus (family:overlay-dismissal AV1).
  • AR4 — Screen-reader semantics and announcements (WCAG 2.2 1.1.1, 4.1.2, 4.1.3). The viewer is a modal dialog named by the active item's alt, or a localized "Media viewer" when it has none. Every item requires alt, which reaches the image's alternative text or the video's accessible name. Moving to another item in an open viewer, by button, key, or swipe, announces the item and its position (", 3 of 12") once, through the spec:AST-086 FR14 route. Every zoom change, by any input, announces the new zoom level once when it settles, or that the photo is back at its fitted size.
  • AR5 — Hidden controls stay reachable (WCAG 2.2 2.1.1, 2.4.11, 4.1.2). FR10 hides the controls visually only: they stay focusable and in the accessibility tree. Focus reaching a control, from the keyboard or from assistive technology, and any key press inside the viewer bring them back. A zoom from the keyboard never hides them.
  • AR6 — Reduced motion (design:reduced-motion DR1–DR3). Under reduced motion, the thumbnail transition, the touch exit, the page settle, the dismiss and pinch-close settles, and the controls fade change opacity only and finish within 200 ms when the primary pointer is coarse or when the release of a touch drag starts them (DR2), including a mouse, pen, or trackpad release where the primary pointer is coarse (spec:AST-094 FR43). Otherwise they complete at once (DR3). The momentum coast of a thrown zoomed photo is direct movement and continues (DR2). These motions read the named motion roles (FR5), which carry the reduced-motion path.
  • AR7 — Focus visible and not obscured (WCAG 2.2 2.4.7, 2.4.11). Every focusable control and the zoom target show the shared focus indicator. A focused control is never hidden by FR10 (AR5), and the caption or counter never covers it.
  • AR8 — The page keeps its own zoom (WCAG 2.2 1.4.4). A pinch on the controls or the caption zooms the page, so their text stays resizable (FR6).
  • AR9 — The controls keep their contrast over a zoomed photo (WCAG 2.2 1.4.3, 1.4.11). With hasZoom, a photo can lie under Close, Previous, Next, and the Counter, so each sits on a translucent backing: the buttons keep 3:1 and the Counter's text 4.5:1 over any photo content beneath them. In a zoomable Lightbox, Close, Previous, Next and the Counter sit on Lightbox's own backing, and their icons and text use the on-dark colour, so a theme's restyling of these controls can't remove their contrast over a photo. Without hasZoom, the controls have no backing.

Design relationships

Anatomy or state Design requirement Representation authority Hierarchy role Component contract
Viewer overlay Presents the full-viewport dialog and surrounding overlay treatment. Current source and public docs Supporting FR1, FR2
Media Presents the active image or video. Current source and public docs Prominent FR1, FR2
Close button Provides the persistent viewer dismissal action. component:Button Supporting FR1, FR3, AR1
Previous button Moves gallery presentation to the preceding item. component:Button Supporting FR1, FR3, AR1
Next button Moves gallery presentation to the following item. component:Button Supporting FR1, FR3, AR1
Caption Presents caller-provided context below the active Media. Current source and public docs Context-dependent FR1, FR2
Counter Presents current gallery position and total. Current source and tests Supporting FR1, FR2
Reduced motion design:reduced-motion/DR1–DR3 prescribed Supporting AR6

Media, Caption, and Counter are stable visible parts, but no current public target reaches them. Their none dispositions record factual reachability, not a decision that they must remain unthemeable.

Theming anatomy

{
  "Viewer overlay": {"target": "lightbox"},
  "Media": {
    "none": {
      "reason": "reachability-gap: No current public target is applied to the active image or video"
    }
  },
  "Close button": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  },
  "Previous button": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  },
  "Next button": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  },
  "Caption": {
    "none": {
      "reason": "reachability-gap: No current public target is applied to the caption container"
    }
  },
  "Counter": {
    "none": {
      "reason": "reachability-gap: No current public target is applied to the gallery counter"
    }
  }
}

Family and system relationships

  • spec:AST-094 owns touch physics, release decisions, measured values, and motion roles; this record names which gestures Lightbox presents and when.
  • spec:AST-017 owns experimental isolation (FR21) and fine-pointer preservation (FR59); FR11 and FR12 apply them.
  • spec:AST-020 owns the WCAG 2.2 A and AA baseline AR1–AR5, AR7, and AR8 cite.
  • spec:AST-086 owns how position and zoom announcements are delivered inside an open modal (FR14).
  • design:reduced-motion owns the reduced-motion representation AR6 applies.
  • architecture:component-theming-surface owns anatomy qualification, target mapping, delegation, and factual none dispositions.
  • architecture:layer-runtime owns the current native-dialog host and shared layer plumbing; Lightbox retains its media and local backdrop behavior.
  • architecture:react-component-runtime owns the shared internal touch modules FR14 uses (INV13).
  • architecture:public-component-api owns the caller's way back from touch defaults (INV16); FR13 applies it.
  • family:overlay-dismissal owns shared Escape and platform-close ordering, including per-document ranking (FR8), and records Lightbox as an adopter.
  • architecture:interaction-modality owns shared modality boundaries; this record changes none.

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
FR1 Lightbox.test.tsx render, gallery, caption, media, and zoom suites Single image, gallery edges, caption, video Removing a documented part fails existing role, content, media, or navigation assertions. audit:Lightbox/anatomy
FR2 Source inspection and themingTargets.test.ts Viewer overlay, Media, Caption, and Counter Removing the root target or documenting an unshipped child target fails evidence or inventory. audit:Lightbox/theming
FR3 Source inspection plus Button and IconButton public composition Close and gallery navigation controls Re-owning a control surface requires the delegated owner and this map to change. audit:Lightbox/theming
FR4, AR3 Browser keyboard test: Tab and Shift+Tab at both ends, Escape, arrows in LTR and RTL, +, -, 0, close focus Single image, gallery, zoomed image, removed opener Focus leaving the viewer, a key without its action, or focus not returning to a connected opener fails. audit:Lightbox/accessibility
AR3 Lightbox.test.tsx "Lightbox unmounting while open" suite Viewer rendered only while open and removed by the page, with the opener still on the page; a page control that removes it keeps its focus; StrictMode Focus left on the page body after an open viewer unmounts fails. audit:Lightbox/accessibility
FR5–FR10 Interaction tests on synthetic touch streams with explicit timestamps; Reduce Motion; a busy main thread Below and past each commit point; a release moving back; a drag on a video's frame and on its scrubber; a tap beside the photo with the controls hidden A literal timing, a second decision during a settle, a gesture that pages while pinching, a drag on a video's frame that does not page, a drag on its controls that pages, or a tap beside the photo that closes while the controls are hidden fails. audit:Lightbox/touch
Motion zoomStage.test.ts case listing the dismissal's springs in this record; selfRegistration.test.ts zoom case; interaction case at tempo 2 The dismissal's position spring, and its size and opacity spring, at tempo 1 and tempo 2 A spring the dismissal plays that the Motion section does not list with its value fails. An exit that takes as long at tempo 2 as at tempo 1 fails. audit:Lightbox/touch
FR11 Fine-pointer browser tests Double-click, click on the photo, drag, ctrl-wheel, trackpad scroll, mouse wheel notch A double-click that does not zoom 2× about the point, a click that hides the controls, a fine-pointer close that animates, or a mouse wheel's notch that pans a zoomed photo fails. audit:Lightbox/touch
FR6, AR1 Touch test double-tapping a photo shaped like the screen and a landscape photo 9:16 photo on a phone viewport, 3:2 photo A double tap that zooms less than 2×, or not about the tapped point, fails. audit:Lightbox/touch
FR16 Touch tests closing by Close, Escape, platform close, and a tap beside the photo with the controls shown; Reduce Motion With and without experimental; controls shown and hidden A touch close without the exit, a literal timing, input reaching the viewer during the exit, or a tap beside the photo that closes while the controls are hidden fails. audit:Lightbox/touch
FR17 Lightbox.test.tsx index cases An index below 0 and past the end, NaN, and an in-range fraction (1.5, 0.4, 1.2), controlled and default An index that opens an empty viewer, or any item but the nearest, fails. audit:Lightbox/anatomy
FR18 Lightbox.test.tsx video paging cases (pause, keep, autoplay) A playing video paged away from and back to A neighbouring video that unmounts, keeps playing, or starts again from its beginning fails. audit:Lightbox/anatomy
FR12 Opener and sourceFor tests, with and without experimental Image opener, text-button opener, mid-entrance close Any change to opening or closing without experimental fails. audit:Lightbox/touch
FR13 hasZoom={false} tests under a coarse pointer Gallery, single image A zoom, a pinch close, or a tap that hides the controls with hasZoom={false} fails. audit:Lightbox/touch
FR14 Source boundary check and bundle analysis A page with Lightbox and another touch component A second copy of a touch module or a Lightbox-owned gesture listener fails. audit:Lightbox/touch
AR1, AR2 Browser tests that complete every gesture's action with one pointer and no drag Zoom, page, close, reach a zoomed photo's edge An action reachable only by a multipoint, path, or drag gesture fails. audit:Lightbox/accessibility
AR4 Accessibility-tree and announcement tests Open, page by button, key, and swipe, zoom by every input A missing dialog name or alt, a repeated or missing position announcement, a message not exposed inside the open viewer, or a zoom without its level fails. audit:Lightbox/accessibility
AR5, AR7 Browser tests with the controls hidden Tab, assistive-technology focus, a key press, keyboard zoom A hidden control that is unfocusable, absent from the tree, or still hidden when focused fails. audit:Lightbox/accessibility
AR6 Reduced-motion tests under a coarse and a fine pointer Transition, page settle, dismiss, pinch close, controls fade Travel, scaling, or a cross-fade over 200 ms under reduced motion fails. audit:Lightbox/accessibility
AR8 Touch test pinching on the controls and on the caption Single image, gallery A pinch on the controls or caption that does not zoom the page fails. audit:Lightbox/accessibility
AR9 Touch test zooming a white photo under the controls and measuring their contrast in every shipped theme, butter's recoloured buttons and gothic's hovered Next included Gallery with zoom: Close, Previous, Next, and the Counter, in each shipped theme A control under 3:1, or the Counter's text under 4.5:1, over the zoomed light photo fails. audit:Lightbox/accessibility
Theming anatomy map scripts/check-knowledge.mjs Canonical anatomy and current target Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. audit:Lightbox/theming

Decision log

DEC-1 — The touch presentation is the native photo viewer

Reference: component:Lightbox/DEC-1 Decider: cixzhang, 2026-10-31

On a touch screen people compare Lightbox with the photo viewer on their own phone, so Lightbox presents its gestures by default (FR5–FR10), each close or page decided once at the release.

DEC-2 — Fine pointers get the gestures and keep the desktop look

Reference: component:Lightbox/DEC-2 Decider: cixzhang, 2026-10-31

Mouse, pen, and trackpad get the gestures spec:AST-094 FR43 gives every pointer, while a double-click zooms 2× about the clicked point, a click keeps the controls, and the viewer opens and closes at once (FR11), so the viewer keeps its desktop look.

Rejected: filling the viewer on a double-click, which barely zooms a landscape photo in a wide window.

DEC-3 — The thumbnail transition is experimental

Reference: component:Lightbox/DEC-3 Decider: cixzhang, 2026-10-31

The thumbnail transition, experimental.sourceFor, and the close that waits for the landing stay inside experimental (FR12), so their API can still change.

DEC-4 — hasZoom is the way back

Reference: component:Lightbox/DEC-4 Decider: cixzhang, 2026-10-31

hasZoom={false} turns off the zoom-related touch behaviors, and the other gestures only add to existing controls, so Lightbox needs no presentation prop (FR13).

Open questions

None. Media, Caption, and Counter keep no public target; adding one is a change to this record.

Content boundary

This file does not duplicate consumer prop tables/examples, measured values, media algorithms, shared layer rules, current audit results, or implementation steps. It links to their owners.