An open source design system that's fully customizable and agent ready
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-094FR13). 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), the0key (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 andexperimental.sourceFor(FR12, FR21) - Controlled/uncontrolled behavior: unchanged; a swipe reports through
onIndexChange, and a controlledindexthe 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
dblclicklistener, since only the browser knows the system's double-click speed. - Press tracker (FR14). The viewer's own
pointerdownhandler records each press's pointer type and point, which the browser'sdblclickandclickdo 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
lightboxtarget. - 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:Buttonthrough IconButton. - Caller-provided Caption content.
- New targets for Media, Caption, or Counter; none exist.
- Shared layer hosting or dismissal policy — owned by
architecture:layer-runtimeandfamily:overlay-dismissal. - Touch physics, measured values, and motion roles' values — owned by
spec:AST-094and 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, and0returns 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-dismissalAV1). - 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 requiresalt, 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 thespec:AST-086FR14 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-motionDR1–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-094FR43). 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. WithouthasZoom, 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-094owns touch physics, release decisions, measured values, and motion roles; this record names which gestures Lightbox presents and when.spec:AST-017owns experimental isolation (FR21) and fine-pointer preservation (FR59); FR11 and FR12 apply them.spec:AST-020owns the WCAG 2.2 A and AA baseline AR1–AR5, AR7, and AR8 cite.spec:AST-086owns how position and zoom announcements are delivered inside an open modal (FR14).design:reduced-motionowns the reduced-motion representation AR6 applies.architecture:component-theming-surfaceowns anatomy qualification, target mapping, delegation, and factualnonedispositions.architecture:layer-runtimeowns the current native-dialog host and shared layer plumbing; Lightbox retains its media and local backdrop behavior.architecture:react-component-runtimeowns the shared internal touch modules FR14 uses (INV13).architecture:public-component-apiowns the caller's way back from touch defaults (INV16); FR13 applies it.family:overlay-dismissalowns shared Escape and platform-close ordering, including per-document ranking (FR8), and records Lightbox as an adopter.architecture:interaction-modalityowns 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.