Gallery

1import { Gallery, GalleryItem } from '@/ui/Display'23<Gallery columns={{ base: 2, sm: 3, lg: 4 }} ratio="1 / 1" gap={8}>4  {images.map((img) => (5    <GalleryItem6      key={img.id}7      src={img.thumb}8      alt={img.alt}                 // the primary content, not an afterthought9      full={img.full}10    />11  ))}12</Gallery>1314// The lightbox owes the full modal contract: trap, Escape, arrows, and15// focus returning to the exact thumbnail that opened it.16function openAt(index: number) {17  triggerRef.current = tileRefs.current[index]18  setOpen(index)19}20function close() {21  setOpen(null)22  triggerRef.current?.focus()       // not the first tile — the right one23}2425// Preload the neighbours so arrow traversal feels instant.26React.useEffect(() => {27  if (open === null) return28  for (const i of [open - 1, open + 1]) {29    const img = images[(i + images.length) % images.length]30    if (img) new Image().src = img.full31  }32}, [open])3334// One ratio, applied to everything. Mixed ratios leave the grid with no35// alignment in either direction.36<img src={src} alt={alt} loading="lazy" decoding="async"37     className="h-full w-full object-cover" />

<!-- A list, so the count is announced before the user starts exploring. -->
<ul class="ds-gallery" role="list">
  <li>
    <!-- The tile is the button and it carries the description. -->
    <button type="button" aria-label="View: Deployment dashboard showing three healthy regions">
      <img src="/thumbs/1.jpg" alt="" loading="lazy" decoding="async"
           width="400" height="400" />
    </button>
  </li>
</ul>

<div role="dialog" aria-modal="true"
     aria-label="Deployment dashboard showing three healthy regions">
  <p role="status" aria-live="polite">3 of 6</p>

  <!-- contain, never cover: the whole image is why they opened it. -->
  <img src="/full/3.jpg" alt="Deployment dashboard showing three healthy regions" />

  <button type="button" aria-label="Previous image">‹</button>
  <button type="button" aria-label="Next image">›</button>
  <button type="button" aria-label="Close">✕</button>
</div>

.ds-gallery {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(120px, 1fr));
  /* Tight, so the set reads as one field of images rather than a grid of
     separate objects. */
  gap: 8px;
  list-style: none;
  padding: 0;
}

.ds-gallery button {
  position: relative;
  inline-size: 100%;
  /* One ratio for everything: mixed ratios leave no alignment in either
     direction. */
  aspect-ratio: 1 / 1;
  overflow: hidden;
  border-radius: var(--radius-md);
  background: var(--ds-surface-inset);
}

.ds-gallery img { inline-size: 100%; block-size: 100%; object-fit: cover; }

/* A scrim, not a scale transform — scaling a tile in a tight grid overlaps
   its neighbours. */
.ds-gallery button::after {
  content: '';
  position: absolute;
  inset: 0;
  background: rgb(0 0 0 / 0);
  transition: background 120ms;
}
.ds-gallery button:hover::after { background: rgb(0 0 0 / 0.3); }

/* Offset outside the tile, so it survives an arbitrary image beneath it. */
.ds-gallery button:focus-visible {
  outline: 2px solid var(--ds-focus-ring);
  outline-offset: 2px;
}

/* contain: cropping the image the user opened is the one unforgivable bug. */
.ds-lightbox img {
  max-inline-size: 90vw;
  max-block-size: 80vh;
  object-fit: contain;
}

@media (max-width: 480px) {
  /* Three columns at 375px puts tiles below the recognition floor. */
  .ds-gallery { grid-template-columns: repeat(2, 1fr); gap: 4px; }
}