ProjectGallery

Responsive case-study image gallery: a labelled list grid of images (captioned ones render as figures) where each thumbnail opens a built-in lightbox unless enableLightbox is false.

Status: stable. Group: media. Markdown version: /design-system/components/project-gallery.md

When to use

Case-study gallery for project imagery inside work articles. It ships its own Lightbox integration, on by default; with enableLightbox={false} each image renders as a plain image with no button. The list label and button names follow the active language.

When not to use

Do not use this for decorative marquees; it is for case-study imagery.

Look-alikes

The contract names no look-alike with a deciding condition.

Props

ProjectGallery props
Prop	Type	Default	Description	Required
`images`	`GalleryImage[]`	none	Array of images to display.	Yes
`columns`	`2 \| 3 \| 4`	`3`	Number of columns.	No
`gap`	`"sm" \| "md" \| "lg"`	`md`	Gap size between images.	No
`aspectRatio`	`"mixed" \| "video" \| "square"`	`mixed`	Aspect ratio for thumbnails.	No
`enableLightbox`	`boolean`	`true`	Each thumbnail is a button that opens the shared Lightbox. When false the thumbnails render as plain images with no button.	No
`className`	`string`	none	Custom className.	No

Variants

Allowed columns values: 2, 3, 4 (default 3).
Available gaps: sm, md, lg (default md).
Available aspect ratios: square, video, mixed (default mixed).

Invalid combinations

The contract records no invalid combinations.

Keyboard

ProjectGallery keyboard behaviour
Key	Behaviour
Enter/Space	On a thumbnail opens the lightbox; with enableLightbox={false} the thumbnails are plain images and take no focus.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

ProjectGallery rules
Level	Rule	How it is checked
MUST	ARIA: Grid is role=list labelled by the translated "Project gallery" (`projectGallery.label`); each item is a role=listitem wrapper whose inner element is a <figure> with <figcaption> only when the image has a caption, otherwise a plain <div>.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Each thumbnail button names itself with the translated "View {alt} in fullscreen" (`projectGallery.viewFullscreen`) when the lightbox is enabled; with it off there is no button, only the image and its alt text.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Positional, scale, and opacity motion is suppressed under prefers-reduced-motion.	Manual review, last on 2026-11-04. WCAG 2.2.2, 2.3.3.
MUST	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-11-04.
MUST NOT	Maintainers: Do not invent parallel primitives inside this folder.	Release review; not machine-checked.

Install and import

In-repo only. ProjectGallery is not exported from @digitaltableteur/react, so there is no public import path.