@sixthshift/design-system 0.6.0 → 0.8.0

package/src/components/FileDropzone/FileDropzone.tsx

@@ -0,0 +1,239 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { Upload } from "lucide-react";
+import * as React from "react";
+
+/**
+ * Geometry only. Every colour reads a `--file-dropzone-*` component token
+ * whose value is decided by src/components/FileDropzone/file-dropzone.recipe.css.
+ *
+ * `size` is the target's footprint: `sm` sits inline in a form row beside other
+ * fields, `md` is a panel of its own (an image manager's "add photos" tile).
+ */
+const fileDropzoneVariants = cva(
+  // One literal, deliberately — see Button.tsx for why a `+` concatenation is a trap.
+  "file-dropzone border-(color:--file-dropzone-border) focus-visible:ring-(color:--file-dropzone-ring) relative flex w-full cursor-pointer flex-col items-center justify-center rounded-lg border-2 border-dashed bg-(--file-dropzone-bg) text-center text-(--file-dropzone-fg) transition-colors hover:bg-(--file-dropzone-bg-hovered) focus-visible:outline-hidden focus-visible:ring-2 data-[disabled=true]:cursor-not-allowed data-[disabled=true]:opacity-50",
+  {
+    variants: {
+      size: {
+        sm: "min-h-20 gap-1 px-4 py-3 text-xs [&_svg]:size-4",
+        md: "min-h-36 gap-2 px-6 py-6 text-sm [&_svg]:size-6",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  }
+);
+
+export type FileDropzoneSize = NonNullable<VariantProps<typeof fileDropzoneVariants>["size"]>;
+
+export type FileDropzoneRejection = {
+  file: File;
+  /** `type` — not in `accept`; `size` — over `maxSize`. */
+  reason: "type" | "size";
+};
+
+export type FileDropzoneProps = Omit<React.HTMLAttributes<HTMLDivElement>, "onDrop" | "children"> &
+  VariantProps<typeof fileDropzoneVariants> & {
+    /** Called with the accepted files from a drop or the file picker. Never called with an empty list. */
+    onFilesChange: (files: File[]) => void;
+    /** Called with files that failed `accept` or `maxSize`, when any did. */
+    onFilesRejected?: (rejections: FileDropzoneRejection[]) => void;
+    /** Same syntax as the native `accept` attribute: `"image/*"`, `".pdf,.docx"`. Also checked on drop. */
+    accept?: string;
+    /** Allow more than one file per drop or pick. */
+    multiple?: boolean;
+    /** Largest accepted file, in bytes. */
+    maxSize?: number;
+    disabled?: boolean;
+    /** Shows a busy state (e.g. while uploading) and blocks new files without disabling the control. */
+    pending?: boolean;
+    /** The main line. Default: "Drop files here or click to browse". */
+    label?: React.ReactNode;
+    /** A secondary line, e.g. accepted types and size limit. */
+    hint?: React.ReactNode;
+    /** Replaces the default upload icon. Pass `null` for none. */
+    icon?: React.ReactNode;
+    /** Input name, for native form submission of the picked files. */
+    name?: string;
+  };
+
+function matchesAccept(file: File, accept: string | undefined): boolean {
+  if (!accept) return true;
+  const rules = accept
+    .split(",")
+    .map((rule) => rule.trim().toLowerCase())
+    .filter(Boolean);
+  if (rules.length === 0) return true;
+  const name = file.name.toLowerCase();
+  const type = file.type.toLowerCase();
+  return rules.some((rule) => {
+    if (rule.startsWith(".")) return name.endsWith(rule);
+    if (rule.endsWith("/*")) return type.startsWith(rule.slice(0, -1));
+    return type === rule;
+  });
+}
+
+/**
+ * A drop target for files that doubles as a file-picker button — product
+ * photos, attachments, imports.
+ *
+ * The whole surface is one control: `role="button"`, a tab stop, and `Enter`
+ * or `Space` opens the native picker, the same as a click. Dragging files over
+ * it sets `data-state="active"`, which the recipe styles. The hidden `<input
+ * type="file">` is the real picker, so `accept`, `multiple` and `name` behave
+ * natively; `accept` and `maxSize` are also enforced on drop, where the
+ * browser does not, and failures go to `onFilesRejected` rather than being
+ * silently dropped. Without `multiple`, a drop of several files keeps the first.
+ *
+ * `pending` shows a spinner-free busy state (`aria-busy`) and ignores new
+ * files while an upload runs, without leaving the tab order — the same split
+ * Switch makes between `pending` and `disabled`.
+ *
+ * The component holds no file list of its own: it reports files and the
+ * caller decides what to show, so there is no value/defaultValue triad.
+ */
+export const FileDropzone = React.forwardRef<HTMLDivElement, FileDropzoneProps>(
+  (
+    {
+      className,
+      size = "md",
+      onFilesChange,
+      onFilesRejected,
+      accept,
+      multiple = false,
+      maxSize,
+      disabled = false,
+      pending = false,
+      label = "Drop files here or click to browse",
+      hint,
+      icon,
+      name,
+      onKeyDown,
+      onClick,
+      ...props
+    },
+    ref
+  ) => {
+    const inputRef = React.useRef<HTMLInputElement>(null);
+    const [active, setActive] = React.useState(false);
+    // dragenter/dragleave fire for every child crossed; count them so the state does not flicker.
+    const depth = React.useRef(0);
+    const labelId = React.useId();
+    const hintId = React.useId();
+
+    const interactive = !disabled && !pending;
+
+    const handleFiles = (list: FileList | null) => {
+      if (!list || !interactive) return;
+      const files = Array.from(list);
+      const accepted: File[] = [];
+      const rejected: FileDropzoneRejection[] = [];
+      for (const file of files) {
+        if (!matchesAccept(file, accept)) rejected.push({ file, reason: "type" });
+        else if (maxSize !== undefined && file.size > maxSize) rejected.push({ file, reason: "size" });
+        else accepted.push(file);
+      }
+      const kept = multiple ? accepted : accepted.slice(0, 1);
+      if (rejected.length > 0) onFilesRejected?.(rejected);
+      if (kept.length > 0) onFilesChange(kept);
+    };
+
+    const openPicker = () => {
+      if (interactive) inputRef.current?.click();
+    };
+
+    const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+      onKeyDown?.(event);
+      if (event.defaultPrevented || event.target !== event.currentTarget) return;
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        openPicker();
+      }
+    };
+
+    const handleDragEnter = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      if (!interactive) return;
+      depth.current += 1;
+      setActive(true);
+    };
+
+    const handleDragLeave = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      depth.current = Math.max(0, depth.current - 1);
+      if (depth.current === 0) setActive(false);
+    };
+
+    const handleDragOver = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      event.dataTransfer.dropEffect = interactive ? "copy" : "none";
+    };
+
+    const handleDrop = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      depth.current = 0;
+      setActive(false);
+      handleFiles(event.dataTransfer.files);
+    };
+
+    return (
+      // biome-ignore lint/a11y/useSemanticElements: the target holds the native file <input>, and interactive content is not allowed inside a <button>; role="button" with Enter/Space handling is the WAI-ARIA button pattern
+      <div
+        ref={ref}
+        role="button"
+        tabIndex={disabled ? -1 : 0}
+        aria-disabled={disabled || undefined}
+        aria-busy={pending || undefined}
+        aria-labelledby={labelId}
+        aria-describedby={hint ? hintId : undefined}
+        data-state={active ? "active" : "idle"}
+        data-disabled={disabled}
+        className={fileDropzoneVariants({ size, className })}
+        onClick={(event) => {
+          onClick?.(event);
+          if (!event.defaultPrevented) openPicker();
+        }}
+        onKeyDown={handleKeyDown}
+        onDragEnter={handleDragEnter}
+        onDragLeave={handleDragLeave}
+        onDragOver={handleDragOver}
+        onDrop={handleDrop}
+        {...props}
+      >
+        {icon === undefined ? <Upload aria-hidden="true" className="text-(--file-dropzone-icon-fg)" /> : icon}
+        <span id={labelId} className="font-medium">
+          {label}
+        </span>
+        {hint && (
+          <span id={hintId} className="text-(--file-dropzone-hint-fg)">
+            {hint}
+          </span>
+        )}
+        <input
+          ref={inputRef}
+          type="file"
+          // `hidden`, not `sr-only`: a rendered input inside role="button" is a nested
+          // interactive control (axe `nested-interactive`). `click()` and form submission
+          // still work on a display:none file input.
+          hidden
+          accept={accept}
+          multiple={multiple}
+          name={name}
+          disabled={disabled}
+          onClick={(event) => event.stopPropagation()}
+          onChange={(event) => {
+            handleFiles(event.target.files);
+            // Reset so picking the same file again still fires change.
+            event.target.value = "";
+          }}
+        />
+      </div>
+    );
+  }
+);
+FileDropzone.displayName = "FileDropzone";
+
+export { fileDropzoneVariants };

package/src/components/FileDropzone/file-dropzone.recipe.css

@@ -0,0 +1,38 @@
+/**
+ * FileDropzone recipe — the component-token layer for FileDropzone.
+ *
+ * No variant/intent axis: a dropzone is a form control, so like Input every
+ * colour is a fixed semantic token. The one state that changes colour is a
+ * drag in progress, which the component renders as `data-state="active"`
+ * and the recipe keys a cell on — the same way steps.css keys on `data-state`.
+ *
+ * The grammar is `--file-dropzone-[{part}-]{context}[-{state}]`. Parts are
+ * the `icon` and the `hint` line. The surface reads the subtle ground so the
+ * dashed target stands apart from the fields around it, and a drag over it
+ * takes the brand wash — the same pairing Tabs uses for its selected cell.
+ *
+ * `@layer components` is load-bearing, not tidiness — see button.css.
+ */
+
+@layer components {
+  .file-dropzone {
+    --file-dropzone-bg: var(--bg-subtle);
+    --file-dropzone-bg-hovered: var(--bg-subtle-hovered);
+    --file-dropzone-fg: var(--fg-normal);
+    --file-dropzone-border: var(--border-normal);
+    --file-dropzone-ring: var(--focus-ring);
+    --file-dropzone-icon-fg: var(--fg-subtle);
+    --file-dropzone-hint-fg: var(--fg-subtle);
+  }
+
+  /* A drag in progress: the brand wash, hover included, so the target does not
+     flicker back to subtle as the pointer moves across it. */
+  .file-dropzone[data-state="active"] {
+    --file-dropzone-bg: var(--bg-brand-subtle);
+    --file-dropzone-bg-hovered: var(--bg-brand-subtle);
+    --file-dropzone-border: var(--border-brand);
+    --file-dropzone-icon-fg: var(--fg-brand);
+    /* fg-subtle drops below 4.5:1 on the brand wash in light mode. */
+    --file-dropzone-hint-fg: var(--fg-normal);
+  }
+}

package/src/components/FileDropzone/index.ts

@@ -0,0 +1 @@
+export { FileDropzone, type FileDropzoneProps, type FileDropzoneRejection, type FileDropzoneSize, fileDropzoneVariants } from "./FileDropzone";

package/src/components/HoverCard/HoverCard.tsx

@@ -3,6 +3,7 @@
 import { autoUpdate, flip, offset, type Placement, safePolygon, shift, useDismiss, useFloating, useFocus, useHover, useInteractions } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import type * as React from "react";
+import { closestBrand } from "../../internal/brandScope";
 import { HoverCardContent } from "./components/HoverCardContent";
 import { HoverCardContext } from "./components/HoverCardContext";
 import { HoverCardTrigger } from "./components/HoverCardTrigger";
@@ -67,6 +68,8 @@ const HoverCardRoot = ({
       setFloating: refs.setFloating,
     },
     floatingStyles,
+    // Read at render: `domReference` is state, so this updates once the trigger mounts.
+    inheritedBrand: closestBrand(context.elements.domReference),
     getReferenceProps,
     getFloatingProps,
   };

package/src/components/HoverCard/components/HoverCardContent.tsx

@@ -5,10 +5,17 @@ import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";
 import { useHoverCardContext } from "./HoverCardContext";
 
-export type HoverCardContentProps = React.HTMLAttributes<HTMLDivElement>;
+export type HoverCardContentProps = React.HTMLAttributes<HTMLDivElement> & {
+  /**
+   * Name of a brand the theme defines, rendered as `data-brand`. Omitted, the
+   * body copies the brand scope of its trigger, which the portal would
+   * otherwise leave behind.
+   */
+  brand?: string | undefined;
+};
 
-export const HoverCardContent = React.forwardRef<HTMLDivElement, HoverCardContentProps>(({ className, children, ...props }, forwardedRef) => {
-  const { open, refs, floatingStyles, getFloatingProps } = useHoverCardContext();
+export const HoverCardContent = React.forwardRef<HTMLDivElement, HoverCardContentProps>(({ className, brand, children, ...props }, forwardedRef) => {
+  const { open, refs, floatingStyles, inheritedBrand, getFloatingProps } = useHoverCardContext();
 
   if (!open) return null;
 
@@ -21,6 +28,7 @@ export const HoverCardContent = React.forwardRef<HTMLDivElement, HoverCardConten
           else if (forwardedRef) forwardedRef.current = node;
         }}
         style={floatingStyles}
+        data-brand={brand ?? inheritedBrand}
         className={cn("z-popover w-80 rounded-lg border border-border-normal bg-bg-normal p-4 shadow-lg", className)}
         {...getFloatingProps(props)}
       >

package/src/components/HoverCard/components/HoverCardContext.tsx

@@ -9,6 +9,8 @@ export type HoverCardContextValue = {
     setFloating: (node: HTMLElement | null) => void;
   };
   floatingStyles: React.CSSProperties;
+  /** The trigger's brand scope, re-stamped on the portalled body. */
+  inheritedBrand: string | undefined;
   getReferenceProps: (props?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
   getFloatingProps: (props?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
 };

package/src/components/ImageGallery/ImageGallery.tsx

@@ -0,0 +1,285 @@
+"use client";
+
+import { useControllableState } from "@sixthshift/design-system/hooks";
+import { cn } from "@sixthshift/design-system/utils";
+import { cva, type VariantProps } from "class-variance-authority";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import * as React from "react";
+
+/**
+ * Geometry only. Every colour reads an `--image-gallery-*` component token
+ * whose value is decided by src/components/ImageGallery/image-gallery.recipe.css.
+ *
+ * `ratio` is the frame's shape, not the images': every slide is cropped to it
+ * with `object-cover`, so a mixed set of uploads still produces a steady
+ * frame that does not jump as you swipe. `portrait` is 4:5, the tallest crop
+ * Instagram allows in a feed — photography shot for the feed lands on it
+ * uncropped.
+ */
+const frameVariants = cva("relative overflow-hidden rounded-lg bg-(--image-gallery-bg)", {
+  variants: {
+    ratio: {
+      square: "aspect-square",
+      portrait: "aspect-[4/5]",
+      landscape: "aspect-[4/3]",
+      wide: "aspect-video",
+    },
+  },
+  defaultVariants: {
+    ratio: "square",
+  },
+});
+
+export type ImageGalleryRatio = NonNullable<VariantProps<typeof frameVariants>["ratio"]>;
+
+export type ImageGalleryImage = {
+  src: string;
+  /** Required: describe the photo. The gallery adds position ("2 of 5") on its own. */
+  alt: string;
+  srcSet?: string;
+  sizes?: string;
+  width?: number;
+  height?: number;
+};
+
+export type ImageGalleryProps = Omit<React.HTMLAttributes<HTMLElement>, "onChange"> &
+  VariantProps<typeof frameVariants> & {
+    images: readonly ImageGalleryImage[];
+    /** Controlled index of the image shown. */
+    index?: number;
+    /** Initial index in uncontrolled mode. */
+    defaultIndex?: number;
+    /** Called when the shown image changes — by swipe, arrow, key or thumbnail. */
+    onIndexChange?: (index: number) => void;
+    /**
+     * What sits under the frame: a strip of `thumbnails`, a row of `dots`, or
+     * `none`. Only rendered when there is more than one image.
+     */
+    indicator?: "thumbnails" | "dots" | "none";
+    /** Accessible name for the carousel, e.g. the product's name. */
+    label?: string;
+    /** Accessible name for the previous-image button. */
+    previousLabel?: string;
+    /** Accessible name for the next-image button. */
+    nextLabel?: string;
+    /** Shown in the frame when `images` is empty. */
+    placeholder?: React.ReactNode;
+  };
+
+function prefersReducedMotion(): boolean {
+  return typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+}
+
+/**
+ * A product photo carousel: one frame, swipeable on touch, with previous/next
+ * buttons, arrow-key navigation and an optional thumbnail strip or dots.
+ *
+ * Swiping is native scrolling — a horizontal `scroll-snap` track, not a
+ * pointer-event reimplementation — so it has the platform's own momentum and
+ * edge behaviour on phones. The shown index follows the scroll position, and
+ * setting the index (by button, key, thumbnail or a controlled `index`)
+ * scrolls the track. Both directions meet at one rule: the effect only scrolls
+ * when the track is not already showing the index, so a swipe that updates
+ * the index never fights itself.
+ *
+ * Controlled or uncontrolled through `index`/`defaultIndex`/`onIndexChange`.
+ *
+ * Follows the WAI-ARIA carousel pattern: the root is a `<section>` with
+ * `aria-roledescription="carousel"` (a landmark region once `label` names
+ * it), each slide a group named "n of total", and slides out of view are
+ * `aria-hidden`. The first image loads eagerly and
+ * the rest lazily, so a gallery of ten costs one download up front.
+ */
+export const ImageGallery = React.forwardRef<HTMLElement, ImageGalleryProps>(
+  (
+    {
+      className,
+      images,
+      index: controlledIndex,
+      defaultIndex = 0,
+      onIndexChange,
+      ratio = "square",
+      indicator = "thumbnails",
+      label,
+      previousLabel = "Previous image",
+      nextLabel = "Next image",
+      placeholder,
+      onKeyDown,
+      ...props
+    },
+    ref
+  ) => {
+    const count = images.length;
+    const [rawIndex, setIndex] = useControllableState({
+      value: controlledIndex,
+      defaultValue: defaultIndex,
+      onChange: onIndexChange,
+    });
+    const index = count === 0 ? 0 : Math.min(Math.max(rawIndex, 0), count - 1);
+
+    const trackRef = React.useRef<HTMLDivElement | null>(null);
+    // The slide a programmatic scroll is heading for. While set, the slides it
+    // passes on the way are not reported — jumping from 1 to 4 reports 4, not
+    // 2, 3 and 4. Any touch, wheel or pointer on the track hands control back.
+    const scrollTargetRef = React.useRef<number | null>(null);
+
+    // Index → scroll. Skipped when the track already shows `index`, which is
+    // always the case right after a swipe reported it.
+    React.useEffect(() => {
+      const track = trackRef.current;
+      if (!track || track.clientWidth === 0) return;
+      if (Math.round(track.scrollLeft / track.clientWidth) === index) return;
+      scrollTargetRef.current = index;
+      track.scrollTo({ left: index * track.clientWidth, behavior: prefersReducedMotion() ? "auto" : "smooth" });
+    }, [index]);
+
+    // Scroll → index. Rounds, so the index flips at the halfway point of a swipe.
+    const handleScroll = () => {
+      const track = trackRef.current;
+      if (!track || track.clientWidth === 0) return;
+      const shown = Math.round(track.scrollLeft / track.clientWidth);
+      if (scrollTargetRef.current !== null) {
+        if (shown !== scrollTargetRef.current) return;
+        scrollTargetRef.current = null;
+      }
+      if (shown !== index && shown >= 0 && shown < count) setIndex(shown);
+    };
+
+    const releaseScroll = () => {
+      scrollTargetRef.current = null;
+    };
+
+    const go = (next: number) => {
+      if (next >= 0 && next < count && next !== index) setIndex(next);
+    };
+
+    const handleKeyDown = (event: React.KeyboardEvent<HTMLElement>) => {
+      onKeyDown?.(event);
+      if (event.defaultPrevented) return;
+      const targets: Record<string, number> = { ArrowLeft: index - 1, ArrowRight: index + 1, Home: 0, End: count - 1 };
+      const target = targets[event.key];
+      if (target === undefined) return;
+      event.preventDefault();
+      go(target);
+    };
+
+    const controlClass =
+      "image-gallery-control focus-visible:ring-(color:--image-gallery-control-ring) absolute top-1/2 flex size-9 -translate-y-1/2 cursor-pointer items-center justify-center rounded-full bg-(--image-gallery-control-bg) text-(--image-gallery-control-fg) shadow transition-opacity hover:bg-(--image-gallery-control-bg-hovered) focus-visible:outline-hidden focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-0 max-sm:hidden [&_svg]:size-5";
+
+    return (
+      <section
+        ref={ref}
+        aria-roledescription="carousel"
+        aria-label={label}
+        className={cn("image-gallery flex flex-col gap-3", className)}
+        onKeyDown={handleKeyDown}
+        {...props}
+      >
+        <div className={frameVariants({ ratio })}>
+          {count === 0 ? (
+            <div className="flex h-full w-full items-center justify-center text-(--image-gallery-placeholder-fg) text-sm">{placeholder}</div>
+          ) : (
+            <div
+              ref={trackRef}
+              onScroll={handleScroll}
+              onPointerDown={releaseScroll}
+              onTouchStart={releaseScroll}
+              onWheel={releaseScroll}
+              // Focusable so the arrow keys work without first reaching a button,
+              // and because a scrollable region must be keyboard-reachable.
+              // biome-ignore lint/a11y/noNoninteractiveTabindex: scrollable regions must be focusable (axe `scrollable-region-focusable`)
+              tabIndex={0}
+              className="focus-visible:ring-(color:--image-gallery-control-ring) flex h-full w-full snap-x snap-mandatory overflow-x-auto overscroll-x-contain [scrollbar-width:none] focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-inset [&::-webkit-scrollbar]:hidden"
+            >
+              {images.map((image, i) => (
+                // biome-ignore lint/a11y/useSemanticElements: the WAI-ARIA carousel pattern names each slide a `group`; a <fieldset> is for form controls
+                <div
+                  // biome-ignore lint/suspicious/noArrayIndexKey: slides are positional — "2 of 5" is their identity, and the same photo may appear twice
+                  key={i}
+                  role="group"
+                  aria-roledescription="slide"
+                  aria-label={`${i + 1} of ${count}`}
+                  aria-hidden={i !== index}
+                  className="h-full w-full shrink-0 snap-center snap-always"
+                >
+                  <img
+                    src={image.src}
+                    srcSet={image.srcSet}
+                    sizes={image.sizes}
+                    width={image.width}
+                    height={image.height}
+                    alt={image.alt}
+                    loading={i === 0 ? "eager" : "lazy"}
+                    decoding="async"
+                    draggable={false}
+                    className="h-full w-full select-none object-cover"
+                  />
+                </div>
+              ))}
+            </div>
+          )}
+          {count > 1 && (
+            <>
+              <button type="button" aria-label={previousLabel} disabled={index === 0} onClick={() => go(index - 1)} className={cn(controlClass, "left-2")}>
+                <ChevronLeft aria-hidden="true" />
+              </button>
+              <button type="button" aria-label={nextLabel} disabled={index === count - 1} onClick={() => go(index + 1)} className={cn(controlClass, "right-2")}>
+                <ChevronRight aria-hidden="true" />
+              </button>
+            </>
+          )}
+        </div>
+
+        {count > 1 && indicator === "thumbnails" && (
+          <div className="flex gap-2 overflow-x-auto p-0.5">
+            {images.map((image, i) => (
+              <button
+                // biome-ignore lint/suspicious/noArrayIndexKey: slides are positional — "2 of 5" is their identity, and the same photo may appear twice
+                key={i}
+                type="button"
+                aria-label={`Show image ${i + 1} of ${count}`}
+                aria-current={i === index ? "true" : undefined}
+                data-selected={i === index}
+                onClick={() => go(i)}
+                className="image-gallery-thumb border-(color:--image-gallery-thumb-border) focus-visible:ring-(color:--image-gallery-control-ring) hover:border-(color:--image-gallery-thumb-border-hovered) size-16 shrink-0 cursor-pointer overflow-hidden rounded-md border-2 transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-offset-2"
+              >
+                <img
+                  src={image.src}
+                  srcSet={image.srcSet}
+                  sizes="64px"
+                  alt=""
+                  loading="lazy"
+                  decoding="async"
+                  draggable={false}
+                  className="h-full w-full object-cover"
+                />
+              </button>
+            ))}
+          </div>
+        )}
+
+        {count > 1 && indicator === "dots" && (
+          <div className="flex justify-center gap-1.5">
+            {images.map((_, i) => (
+              <button
+                // biome-ignore lint/suspicious/noArrayIndexKey: slides are positional — "2 of 5" is their identity, and the same photo may appear twice
+                key={i}
+                type="button"
+                aria-label={`Show image ${i + 1} of ${count}`}
+                aria-current={i === index ? "true" : undefined}
+                data-selected={i === index}
+                onClick={() => go(i)}
+                className="image-gallery-dot focus-visible:ring-(color:--image-gallery-control-ring) flex size-6 cursor-pointer items-center justify-center rounded-full focus-visible:outline-hidden focus-visible:ring-2"
+              >
+                <span aria-hidden="true" className="block size-2 rounded-full bg-(--image-gallery-dot-bg) transition-colors" />
+              </button>
+            ))}
+          </div>
+        )}
+      </section>
+    );
+  }
+);
+ImageGallery.displayName = "ImageGallery";
+
+export { frameVariants as imageGalleryFrameVariants };

package/src/components/ImageGallery/image-gallery.recipe.css

@@ -0,0 +1,50 @@
+/**
+ * ImageGallery recipe — the component-token layer for ImageGallery.
+ *
+ * No variant/intent axis. The one selectable cell is `data-selected` on a
+ * thumbnail or dot, the same shape tabs.css uses for its selected trigger.
+ *
+ * The grammar is `--image-gallery-[{part}-]{context}[-{state}]`. Parts:
+ *
+ *   control      the previous/next buttons floating over the photo. They sit
+ *                on arbitrary imagery, so they take the page's resting surface
+ *                with an elevation shadow rather than a transparent ghost —
+ *                legible over a white cake and a chocolate one alike.
+ *   thumb        a thumbnail button's frame.
+ *   dot          a dot indicator's fill.
+ *   placeholder  the text shown when there are no images.
+ *
+ * `--image-gallery-bg` shows while a lazy image loads and behind an empty
+ * gallery, so it is the subtle surface, not the page's.
+ *
+ * `@layer components` is load-bearing, not tidiness — see button.css.
+ */
+
+@layer components {
+  .image-gallery {
+    --image-gallery-bg: var(--bg-subtle);
+    --image-gallery-placeholder-fg: var(--fg-subtle);
+    --image-gallery-control-bg: var(--bg-normal);
+    --image-gallery-control-bg-hovered: var(--bg-normal-hovered);
+    --image-gallery-control-fg: var(--fg-normal);
+    --image-gallery-control-ring: var(--focus-ring);
+  }
+
+  .image-gallery-thumb {
+    --image-gallery-thumb-border: transparent;
+    --image-gallery-thumb-border-hovered: var(--border-strong);
+  }
+
+  .image-gallery-thumb[data-selected="true"] {
+    --image-gallery-thumb-border: var(--border-brand);
+    --image-gallery-thumb-border-hovered: var(--image-gallery-thumb-border);
+  }
+
+  .image-gallery-dot {
+    --image-gallery-dot-bg: var(--border-strong);
+  }
+
+  .image-gallery-dot[data-selected="true"] {
+    --image-gallery-dot-bg: var(--bg-brand);
+  }
+}

package/src/components/ImageGallery/index.ts

@@ -0,0 +1,7 @@
+export {
+  ImageGallery,
+  type ImageGalleryImage,
+  type ImageGalleryProps,
+  type ImageGalleryRatio,
+  imageGalleryFrameVariants,
+} from "./ImageGallery";