Skip to content

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

TypeScript

spec(Lightbox): make the record current, with touch gestures and their accessible alternatives (#9158)

Cindy Zhangadda63f8c3d9
diff --git a/packages/core/src/Lightbox/Lightbox.spec.md b/packages/core/src/Lightbox/Lightbox.spec.md
index 0ccf9e0065..c28e10d405 100644
--- a/packages/core/src/Lightbox/Lightbox.spec.md
+++ b/packages/core/src/Lightbox/Lightbox.spec.md
@@ -3,31 +3,34 @@ schema_version: 3
template_version: 3
kind: component
id: component:Lightbox
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
owners: [cixzhang]
-review_triggers: [behavior, theming, accessibility]
+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_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: []
+system_specs: [spec:AST-017, spec:AST-020, spec:AST-086, spec:AST-094]
---
# Lightbox component contract
@@ -35,81 +38,205 @@ system_specs: []
## Intent
Lightbox presents one active image or video in a full-viewport viewer and may
-add gallery navigation, a caption, and a position counter. This draft records
-current consumer anatomy and theming ownership without changing runtime
-behavior, styling, targets, or public API.
+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: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
- targets, aliases, and public API remain unchanged
-- Controlled/uncontrolled behavior: unchanged
-- Migration decision: none
+- 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 wheel 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 (FR5–FR10, FR12).** On a touch screen a pinch zooms the
+ page instead of the photo, a double tap zooms 2× about the centre, and there
+ is no swipe paging, drag or pinch to close, tap to hide the controls, or
+ thumbnail transition.
+- **Tab containment (FR4).** Tab from the viewer's last control can move focus
+ to the browser's own interface.
+- **Single-pointer pan (AR2, FR11).** A double-click zooms 2× about the centre,
+ not about the clicked point, so a single-pointer user can reach a zoomed
+ photo's edge only by dragging.
+- **Zoom reset key (AR3).** `0` does not return a zoomed photo to its fitted
+ size.
+- **Zoom announcement (AR4).** A zoom change announces "zoomed in" or "zoomed
+ out" without the zoom level.
+- **Announcements outside the open viewer (AR4).** Position and zoom messages
+ are sent from above the modal Lightbox renders, so they reach the page body
+ and a screen-reader user does not hear them while the viewer is open
+ (`spec:AST-086` FR14).
+- **Lightbox-owned pan listeners (FR14).** The pan drag registers Lightbox's
+ own `window` pointer listeners instead of using the shared touch modules.
+- **Fine-pointer gestures (FR11).** A mouse drag on a fitted photo does
+ nothing, a ctrl-wheel zooms the page, and a wheel does not pan a zoomed photo.
+- **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,
- and current image zoom and pan behavior.
+- 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 on current `main`.
-- Shared layer hosting or dismissal policy.
+- 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 public concept is introduced. Consumer props and usage remain documented
-in `Lightbox.doc.mjs`.
+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 current 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 | Verified current behavior; no new behavior decided |
-| FR2 | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target. | Current source and public docs | Verified current reachability; no target change |
-| 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 | Verified current delegation; no ownership change |
-| 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` | Owner decision; tests land with the implementation |
+| 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. Every spring, duration, and curve they play is a named motion role (zoom settle, page settle, dismiss, pinch close, controls fade, zoom transition) read through the motion role table, never a literal. 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 the projection rule. 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` FR14, FR36–FR39 | 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` FR36–FR40 | 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 wheel to pan a zoomed photo; 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: 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 its named motion role. `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 |
### Allowed variation
-- **AV1 — Media mode.** Media may be an image or video; zoom and pan are available
- only on the current image path.
+- **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. |
+| 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
-- No new index, zoom, pan, media, or styling precedence rule is introduced.
+- **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
-- No new performance or resource rule is introduced.
+- **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
-Apart from Tab containment (FR4), this draft does not change or extend
-Lightbox's existing dialog naming, focus, media alternatives, announcements,
-button labels, keyboard behavior, or dismissal behavior.
+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 ("<alt>, 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).
## Design relationships
@@ -117,11 +244,12 @@ button labels, keyboard behavior, or dismissal behavior.
| ---------------- | -------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
| 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 |
-| Previous button | Moves gallery presentation to the preceding item. | `component:Button` | Supporting | FR1, FR3 |
-| Next button | Moves gallery presentation to the following item. | `component:Button` | Supporting | FR1, FR3 |
+| 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
@@ -163,37 +291,97 @@ a decision that they must remain unthemeable.
## 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 current media and local backdrop behavior.
-- `family:overlay-dismissal` owns shared Escape and platform-close ordering and
- records Lightbox as a current adopter.
-- `architecture:interaction-modality` and `architecture:public-component-api`
- own their shared modality and API boundaries; this draft changes neither.
+ 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` |
-| 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` |
+| 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` |
+| 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` |
+| FR11 | Fine-pointer browser tests | Double-click, click on the photo, drag, ctrl-wheel, wheel | A double-click that does not zoom 2× about the point, a click that hides the controls, or a fine-pointer close that animates 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` |
+| 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` |
+| 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
-None. This draft records current facts and introduces no component-local design,
-API, theming, or layer-system decision.
+### 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
-- **OQ1 — Should Media, Caption, or Counter gain a stable public theming target?**
- (`human-api`) Their current lack of reachability is an audit gap, not settled
- intent.
+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, media algorithms,
-shared layer rules, current audit results, or implementation steps. It links to
-their owners.
+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.