@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/dialog-footer-default.md

@@ -0,0 +1,142 @@
+# DialogFooterDefault
+
+> A bottom action bar (panel/dialog/sheet footer) — end-aligned actions plus an optional start slot: a truncated description, or a link. The Figma `variant` (default / withDescription / withLink) is structural, following from which slot is passed, not a separate prop.
+
+**Status:** ready · **Category:** layout · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { DialogFooterDefault } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<DialogFooterDefault>
+  <Button variant="secondary">Cancel</Button>
+  <Button>Save</Button>
+</DialogFooterDefault>
+
+<DialogFooterDefault description="Changes are saved automatically as you type.">
+  <Button variant="secondary">Cancel</Button>
+  <Button>Save</Button>
+</DialogFooterDefault>
+
+<DialogFooterDefault link={<Link href="/docs">Learn more</Link>}>
+  <Button variant="secondary">Cancel</Button>
+  <Button>Save</Button>
+</DialogFooterDefault>
+```
+
+A bottom action bar for panels, dialogs, and sheets — end-aligned actions
+plus an optional start slot: a truncated description, or a link.
+
+## When to use
+
+- The bottom action row of a panel/dialog/sheet — e.g. Cancel + Save.
+- When the actions need brief accompanying context (a description) or a
+  related link (e.g. "Learn more").
+
+## When not to use
+
+- For a bulk-action/selection bar above a list or table — use `Toolbar`.
+- For a full app-level bottom bar — compose the layout directly.
+
+## Parts
+
+| Part        | Description                                                            |
+| ----------- | ---------------------------------------------------------------------- |
+| description | Optional truncated text next to the actions.                           |
+| link        | Optional `Link` (or similar) element next to the actions.              |
+| actions     | End-aligned action content — typically a secondary + primary `Button`. |
+
+`description` and `link` are mutually exclusive — pass at most one.
+
+## Example
+
+```tsx
+import { Button, DialogFooterDefault, Link } from '@acronis-platform/ui-react';
+
+<DialogFooterDefault>
+  <Button variant="secondary">Cancel</Button>
+  <Button>Save</Button>
+</DialogFooterDefault>
+
+<DialogFooterDefault description="Changes are saved automatically as you type.">
+  <Button variant="secondary">Cancel</Button>
+  <Button>Save</Button>
+</DialogFooterDefault>
+
+<DialogFooterDefault link={<Link href="/docs">Learn more</Link>}>
+  <Button variant="secondary">Cancel</Button>
+  <Button>Save</Button>
+</DialogFooterDefault>
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `description` | `string` | — | no | Truncated description text next to the actions. Mutually exclusive with `link` — set at most one. |
+| `link` | `ReactNode` | — | no | A `Link` (or similar) element next to the actions. Mutually exclusive with `description` — set at most one. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | End-aligned actions — typically a secondary and a primary `Button`. DialogFooterDefault imposes no button count or order. |
+
+## Behavior
+
+DialogFooterDefault is a pure function of its props — no internal state, no
+interaction of its own (interactivity lives on the composed `Button`/`Link`
+children).
+
+```gherkin
+Scenario: Actions only
+  Given a DialogFooterDefault with no `description` or `link`
+  Then its children render end-aligned (root falls back to justify-end)
+```
+
+```gherkin
+Scenario: With a description
+  Given a DialogFooterDefault with description="Changes are saved automatically as you type."
+  Then the description renders truncated (single line, ellipsis) next to the actions
+  And the actions no longer need the justify-end fallback (the description's
+    flex-1 pushes them to the end)
+```
+
+```gherkin
+Scenario: With a link
+  Given a DialogFooterDefault with link={<Link href="/docs">Learn more</Link>}
+  Then the link renders in a 32px-tall row next to the actions, untruncated
+```
+
+```gherkin
+Scenario: description and link are mutually exclusive
+  Given a DialogFooterDefault with both `description` and `link` set
+  Then both slots render (the component does not validate mutual exclusivity) —
+    callers should pass at most one, matching the single Figma `variant`
+```
+
+## Accessibility
+
+- DialogFooterDefault is a plain layout container — no landmark role of its
+  own. If a DialogFooterDefault's actions form the primary controls for an
+  enclosing dialog/sheet, that ancestor (e.g. `Dialog`, `Sheet`) owns the
+  relevant ARIA (e.g. `role="dialog"`, focus trapping); DialogFooterDefault
+  does not duplicate it.
+- All interactive semantics (focus order, keyboard activation, accessible
+  names) come from the composed `Button`/`Link` children — DialogFooterDefault
+  does not wrap or override them.
+- The `description` text is plain, truncated text — `title`/`aria-label` is
+  the caller's responsibility if the full (untruncated) text should also be
+  available to assistive tech or as a hover tooltip.
+
+## Contrast
+
+`description` uses the shared `text-foreground` token
+(`--ui-text-on-surface-primary`), guaranteed to meet contrast against
+DialogFooterDefault's own `--ui-footer-default-color` background in both
+light and dark (both come from the same semantic surface/text pairing).

package/dist/llms/dialog-root.md

@@ -0,0 +1,246 @@
+# DialogRoot
+
+> A modal overlay that interrupts the user to show focused content or request a decision. A set of composable parts (trigger, overlay, content, header, title, close, body, description, footer) built on the Base UI Dialog primitive. Initial version ported from the legacy shadcn-uikit `Dialog`; design reconciliation against Figma is pending. Internal-only as of the Dialog (recipe) merge — not exported from the package root. `Dialog` (sourceDir: dialog, see the `dialog` spec) is the sole public entry point; it composes these parts internally.
+
+**Status:** draft · **Category:** overlays · **Since:** v0.9.0
+
+## Import
+
+```tsx
+Internal-only — NOT exported from '@acronis-platform/ui-react'. `Dialog` (the recipe) is the sole public entry point; these parts are an implementation detail it composes internally (src/components/ui/dialog/dialog.tsx).
+```
+
+## Quick example
+
+```tsx
+// Internal usage only (e.g. inside Dialog or its tests):
+<DialogRoot>
+  <DialogTrigger render={<Button variant="secondary">Open</Button>} />
+  <DialogContent>
+    <DialogHeaderRoot>
+      <DialogTitle>Are you absolutely sure?</DialogTitle>
+      <DialogCloseButton />
+    </DialogHeaderRoot>
+    <DialogBodyRoot>
+      <DialogDescription>This action cannot be undone.</DialogDescription>
+    </DialogBodyRoot>
+    <DialogFooterRoot>
+      <DialogClose render={<Button variant="ghost">Cancel</Button>} />
+      <Button variant="destructive">Delete</Button>
+    </DialogFooterRoot>
+  </DialogContent>
+</DialogRoot>
+```
+
+> **Internal-only.** Not exported from `@acronis-platform/ui-react`. This is
+> the composable primitive `Dialog` (the recipe) is built on — use
+> [`Dialog`](../dialog/README.md) instead. Documented here because its source
+> lives alongside `Dialog`'s (`packages/ui-react/src/components/ui/dialog/`)
+> and other internal code (tests, Storybook VR coverage) still references it
+> directly.
+
+A modal overlay that interrupts the user to show focused content or request a
+decision. Composable from parts; built on the Base UI Dialog primitive.
+
+> **Status: draft (design-pending v1).** Ported from the legacy
+> `@acronis-platform/shadcn-uikit` `Dialog`. There is no `--ui-dialog-*` token
+> tier yet, so colors resolve to the shared semantic tokens. Enter/exit
+> animations use `tw-animate-css` (overlay fade, popup fade + zoom), keyed to
+> Base UI's open/closed state. Reconcile against Figma with
+> `/figma-component Dialog <url> --update` once a mockup lands.
+
+## When to use
+
+- Never directly — it has no public export. Use `Dialog`; if none of its
+  seven canned use-cases (or the `wide` escape hatch) fit, that's a gap to
+  raise with the design system team (a new variant), not a reason to reach
+  for this primitive.
+
+## Parts
+
+| Part                             | Element (default)  | Purpose                                           |
+| -------------------------------- | ------------------ | ------------------------------------------------- |
+| `DialogRoot`                     | —                  | Root; owns the open state (Base UI `Root`).       |
+| `DialogTrigger`                  | `button`           | Opens the dialog.                                 |
+| `DialogContent`                  | `div[role=dialog]` | The portaled, centered popup (+ overlay).         |
+| `DialogHeaderRoot`               | `div`              | Top bar; holds the title and close button.        |
+| `DialogTitle`                    | `h2`               | Accessible dialog name (`aria-labelledby`).       |
+| `DialogCloseButton`              | `button`           | Icon button that dismisses the dialog.            |
+| `DialogBodyRoot`                 | `div`              | Scrollable content region.                        |
+| `DialogDescription`              | `p`                | Supporting copy (`aria-describedby`).             |
+| `DialogFooterRoot`               | `div`              | Right-aligned action bar.                         |
+| `DialogClose`                    | `button`           | Closes the dialog; wrap a Button via `render`.    |
+| `DialogOverlay` / `DialogPortal` | —                  | Lower-level parts (`DialogContent` renders them). |
+
+## Sizes
+
+`DialogContent` takes a `size` prop controlling the popup max-width. `sm`
+(512px, default) has a Figma-defined token (`--ui-dialog-container-size-sm`);
+`large` (832px) is a legacy backward-compatibility size with no design token,
+kept for existing call sites (see the public `Dialog` recipe's `wide` variant).
+
+## Example (internal usage only)
+
+```tsx
+// NOT a public import — './dialog' is an internal module path, shown here
+// only to document what Dialog (the recipe) composes internally.
+import {
+  DialogRoot,
+  DialogTrigger,
+  DialogContent,
+  DialogHeaderRoot,
+  DialogTitle,
+  DialogCloseButton,
+  DialogBodyRoot,
+  DialogDescription,
+  DialogFooterRoot,
+  DialogClose,
+} from './dialog';
+import { Button } from '../button';
+
+<DialogRoot>
+  <DialogTrigger render={<Button variant="secondary">Open dialog</Button>} />
+  <DialogContent>
+    <DialogHeaderRoot>
+      <DialogTitle>Are you absolutely sure?</DialogTitle>
+      <DialogCloseButton />
+    </DialogHeaderRoot>
+    <DialogBodyRoot>
+      <DialogDescription>This action cannot be undone.</DialogDescription>
+    </DialogBodyRoot>
+    <DialogFooterRoot>
+      <DialogClose render={<Button variant="ghost">Cancel</Button>} />
+      <Button variant="destructive">Delete account</Button>
+    </DialogFooterRoot>
+  </DialogContent>
+</DialogRoot>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `open` | `boolean` | — | no | Controlled open state. Pair with the change event. |
+| `default-open` | `boolean` | `false` | no | Initial open state when uncontrolled. |
+| `modal` | `boolean | 'trap-focus'` | `true` | no | Modal behavior — traps focus and locks background scroll while open. `'trap-focus'` keeps the focus trap but allows background interaction. |
+| `size` | `'sm' | 'large'` | `'sm'` | no | Popup max-width (on the content part). `sm` (512px) has a Figma-defined token (`--ui-dialog-container-size-sm`); `large` (832px) is a legacy backward-compatibility size with no design token, kept for existing call sites (see the public `Dialog` recipe's `wide` variant). |
+| `portal` | `boolean` | `true` | no | Render the content inside a portal (the content part). Required by the underlying primitive for correct stacking; disable only when supplying your own portal ancestor. |
+| `render` | `RenderProp` | `undefined` | no | Composition prop available on the trigger, close, title, description, and other primitive parts — replaces the rendered element with another component (e.g. render the trigger as a Button) while merging props. React-only; other frameworks use their own polymorphism. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `open-change` | `boolean` | Fired when the dialog opens or closes (React: `onOpenChange`). Payload is the new open value. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed dialog. Author it from the parts: an optional trigger, plus the content (popup) wrapping an optional header (title + close), a body (with a description), and an optional footer for actions. |
+
+## Behavior
+
+DialogRoot is a modal overlay assembled from composable parts. It owns one
+piece of state — `open` — and the focus/scroll management that comes with
+being modal.
+
+### Opening & closing
+
+```gherkin
+Scenario: Opening from the trigger
+  Given a closed DialogRoot with a DialogTrigger
+  When the user activates the trigger
+  Then the overlay and popup appear
+  And focus moves into the dialog
+  And open-change(true) fires
+```
+
+```gherkin
+Scenario: Closing via the close button
+  Given an open DialogRoot with a DialogCloseButton
+  When the user activates the close button
+  Then the dialog closes
+  And open-change(false) fires
+  And focus returns to the trigger
+```
+
+```gherkin
+Scenario: Dismissing with the keyboard
+  Given an open modal DialogRoot
+  When the user presses Escape
+  Then the dialog closes and open-change(false) fires
+```
+
+```gherkin
+Scenario: Dismissing by clicking outside
+  Given an open DialogRoot
+  When the user presses on the overlay outside the popup
+  Then the dialog closes and open-change(false) fires
+```
+
+### Controlled vs uncontrolled
+
+```gherkin
+Scenario: Uncontrolled with default-open
+  Given a DialogRoot with default-open = true and no open prop
+  When it mounts
+  Then it renders open, and the user can dismiss it without consumer code
+```
+
+```gherkin
+Scenario: Controlled
+  Given a DialogRoot with a fixed open prop
+  When the user attempts to dismiss it
+  Then internal state does NOT change on its own
+  And open-change fires so the consumer can update the open prop
+```
+
+### Modality
+
+```gherkin
+Scenario: Modal locks the background (default)
+  Given an open DialogRoot with modal = true
+  Then background content is inert, scroll is locked, and focus is trapped
+  inside the dialog until it closes
+```
+
+## Accessibility
+
+DialogRoot leans on the Base UI Dialog primitive for its modal semantics,
+focus management, and keyboard handling. The author's job is to provide an
+accessible name and description and to use the parts as intended.
+
+## Roles & semantics
+
+- The popup (`root`) has `role="dialog"` and `aria-modal="true"` when modal.
+- **Name the dialog.** Render a `DialogTitle` — it is wired to the popup via
+  `aria-labelledby`. Without a title the dialog has no accessible name.
+- **Describe it when useful.** A `DialogDescription` is wired via
+  `aria-describedby`, so supporting copy is announced after the name.
+- The close button exposes an accessible name ("Close") via an `sr-only` label
+  alongside the icon.
+
+## Keyboard
+
+- **Tab / Shift+Tab** — focus cycles **within** the dialog only; the focus trap
+  prevents reaching background content while modal.
+- **Escape** — closes the dialog (fires the change event).
+- On open, focus moves into the dialog (the first focusable element, or the
+  popup); on close, focus returns to the element that opened it (the trigger).
+
+## Screen reader
+
+- Entering the dialog announces its role, name (title), and description.
+- While modal, background content is marked inert, so assistive tech stays
+  within the dialog.
+
+## Contrast
+
+- Title/body text use `--ui-text-on-surface-primary`; the description and idle
+  close icon use `--ui-text-on-surface-secondary`; both meet WCAG AA against the
+  `--ui-background-surface-secondary` popup and `--ui-background-surface-primary`
+  header/footer in light and dark themes. The close button shows a 2px
+  `--ui-focus-primary` ring on keyboard focus.
+- This is a design-pending v1 on semantic tokens — re-verify contrast against the
+  final palette once a `--ui-dialog-*` tier and Figma reference exist.

package/dist/llms/dialog-welcome.md

@@ -0,0 +1,223 @@
+# DialogWelcome
+
+> An onboarding dialog with two layouts: `carousel` (a multi-slide feature tour driven by a real Embla carousel engine, with a `DialogFooterCarousel` footer) and `single` (one image/title/description body with a primary action and a `Close` link). Built from scratch — does not reuse any existing carousel implementation in this repo.
+
+**Status:** draft · **Category:** overlay · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { DialogWelcome } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<DialogWelcome
+  variant="carousel"
+  slides={[
+    { title: 'Automated backups', description: 'Your data is backed up on a schedule you control.' },
+    { title: 'Instant recovery', description: 'Restore a full workload in minutes, not hours.' },
+  ]}
+  open={open}
+  onOpenChange={setOpen}
+  onPrimaryAction={() => setOpen(false)}
+/>
+
+<DialogWelcome
+  variant="single"
+  title="You're all set"
+  description="Your workspace is ready to go."
+  primaryLabel="Get started"
+  open={open}
+  onOpenChange={setOpen}
+/>
+```
+
+An onboarding dialog with two layouts: `carousel` (a multi-slide feature tour
+driven by a real Embla carousel engine, with a `DialogFooterCarousel` footer)
+and `single` (one image/title/description body with a primary action and a
+`Close` link). Built from scratch; does not reuse any existing carousel
+implementation in this repo.
+
+## When to use
+
+- A first-run or feature-announcement dialog that walks through several
+  screenshots/highlights one at a time — use `variant="carousel"`.
+- A single-screen announcement or confirmation with one image and one
+  call-to-action — use `variant="single"`.
+
+## When not to use
+
+- An ordinary confirmation/action dialog — use `Dialog`.
+- A content carousel with no dialog chrome — compose `DialogFooterCarousel`
+  (or a plain Embla instance) directly into your own layout.
+
+## Parts
+
+| Part          | Description                                                               |
+| ------------- | ------------------------------------------------------------------------- |
+| container     | The popup card — reuses `Dialog`'s own chrome.                            |
+| image         | Illustration/media for the active slide (or the single body).             |
+| title         | The active slide's title; also the dialog's accessible name.              |
+| description   | The active slide's description; also the dialog's accessible description. |
+| footer        | `DialogFooterCarousel` (`variant="carousel"` only).                       |
+| primaryAction | Call-to-action `Button` (`variant="single"` only).                        |
+| close         | Ghost `Button` that dismisses the dialog (`variant="single"` only).       |
+
+## Example
+
+```tsx
+import { DialogWelcome } from '@acronis-platform/ui-react';
+
+<DialogWelcome
+  variant="carousel"
+  slides={[
+    { title: 'Automated backups', description: 'Your data is backed up on a schedule you control.' },
+    { title: 'Instant recovery', description: 'Restore a full workload in minutes, not hours.' },
+  ]}
+  open={open}
+  onOpenChange={setOpen}
+  onPrimaryAction={() => setOpen(false)}
+/>
+
+<DialogWelcome
+  variant="single"
+  title="You're all set"
+  description="Your workspace is ready to go."
+  primaryLabel="Get started"
+  open={open}
+  onOpenChange={setOpen}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'carousel' | 'single'` | `'carousel'` | no | Selects the Figma-defined layout. |
+| `slides` | `Array<{ image?: ReactNode; title: string; description: string }>` | `3-item placeholder ('Title' / 'Feature description.')` | no | Slides shown one at a time (`variant="carousel"`). |
+| `selected-index` | `number` | — | no | Controls the active slide (`variant="carousel"`). Uncontrolled (starting at `0`) when omitted. |
+| `back-label` | `string` | `'Back'` | no | `Back` button label (`variant="carousel"`). |
+| `next-label` | `string` | `'Next'` | no | `Next` button label (`variant="carousel"`). |
+| `go-to-slide-label` | `(index: number, count: number) => string` | — | no | Builds each carousel dot's accessible name (`variant="carousel"`). |
+| `image` | `ReactNode` | — | no | Illustration/media (`variant="single"`). |
+| `title` | `string` | `'Title'` | no | `variant="single"` title. |
+| `description` | `string` | `'Feature description.'` | no | `variant="single"` description. |
+| `close-label` | `string` | `'Close'` | no | `Close` link label (`variant="single"`). |
+| `primary-label` | `string` | `'Call to action'` | no | Call-to-action button label. |
+| `open` | `boolean` | — | no | Controlled open state. Pair with the change event. |
+| `default-open` | `boolean` | `false` | no | Initial open state when uncontrolled (React `defaultOpen`). |
+| `modal` | `boolean | 'trap-focus'` | `true` | no | Modal behavior — traps focus and locks background scroll while open. |
+| `portal` | `boolean` | `true` | no | Render the popup inside a portal (forwarded to `DialogContent`). |
+| `keep-mounted` | `boolean` | — | no | Keep the popup mounted while closed (forwarded to `DialogContent`). |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `open-change` | `boolean` | Fired when the dialog opens or closes (React `onOpenChange`). |
+| `selected-index-change` | `number` | Fired whenever the active slide changes (React `onSelectedIndexChange`, `variant="carousel"`). |
+| `close-action` | `undefined` | Fired when `Close` is activated, before the dialog closes (React `onCloseAction`, `variant="single"`). |
+| `primary-action` | `undefined` | Fired when the call-to-action button is activated (React `onPrimaryAction`). |
+
+## Behavior
+
+```gherkin
+Scenario: Opening the carousel variant
+  Given a DialogWelcome with variant="carousel" and 3 slides
+  When it opens
+  Then the first slide's image/title/description render
+  And the footer renders with variant="start" (no Back, Next visible)
+  And the dot indicator marks the first dot active
+```
+
+```gherkin
+Scenario: Advancing through the carousel
+  Given an open DialogWelcome carousel on a middle slide
+  When Next is activated
+  Then the carousel scrolls to the next slide
+  And onSelectedIndexChange fires with the new index
+  And the footer's variant updates (start/middle/end) to match the new position
+```
+
+```gherkin
+Scenario: Reaching the last slide
+  Given an open DialogWelcome carousel on the last slide
+  Then the footer renders with variant="end"
+  And its call-to-action button (default "Call to action") replaces Next
+  When the call-to-action button is activated
+  Then onPrimaryAction fires — the dialog does not close automatically
+```
+
+```gherkin
+Scenario: Jumping directly to a slide
+  Given an open DialogWelcome carousel
+  When a dot other than the active one is activated
+  Then the carousel scrolls directly to that slide
+  And onSelectedIndexChange fires with its index
+```
+
+```gherkin
+Scenario: Controlled without a change handler
+  Given an open DialogWelcome carousel with a controlled `selectedIndex`
+    and no `onSelectedIndexChange` wired
+  When Back, Next, or a dot is activated
+  Then nothing happens — these controls only ever call
+    `onSelectedIndexChange`, which is absent, so the carousel cannot move
+  When a drag gesture moves the carousel's physical position directly
+  Then it snaps back to the controlled `selectedIndex` instead of leaving
+    the visible slide out of sync with the slide carrying the dialog's
+    accessible name
+```
+
+```gherkin
+Scenario: Non-active slides are inert
+  Given an open DialogWelcome carousel with more than one slide
+  Then every slide except the active one is `aria-hidden` and `inert` —
+    unreachable by keyboard/screen reader until it becomes active
+```
+
+```gherkin
+Scenario: Opening the single variant
+  Given a DialogWelcome with variant="single"
+  When it opens
+  Then the image/title/description render once, with no footer
+  And a primary call-to-action button and a "Close" link render below it
+```
+
+```gherkin
+Scenario: Closing from the single variant
+  Given an open DialogWelcome with variant="single"
+  When Close is activated
+  Then onCloseAction fires
+  And the dialog closes (Dialog.Close's default behavior)
+```
+
+## Accessibility
+
+- Reuses Base UI `Dialog.Root`/`Dialog.Popup` (via `DialogContent`) for focus
+  trapping, scroll locking, `role="dialog"`/`aria-modal`, and Escape/
+  outside-press dismissal — the same primitive `Dialog` builds on.
+- Exactly one `Dialog.Title`/`Dialog.Description` pair is mounted at a time —
+  the active slide's (`variant="carousel"`) or the single body's
+  (`variant="single"`). This keeps `aria-labelledby`/`aria-describedby`
+  pointed at real, visible content instead of an off-screen duplicate.
+- **Non-active carousel slides are hidden from assistive tech and the
+  keyboard** (`aria-hidden` + `inert`) — a screen reader or Tab press cannot
+  land on a slide that isn't currently shown, which a naive "just clip it
+  visually" carousel would get wrong.
+- The footer's `Back`/`Next`/call-to-action controls and dot indicators
+  inherit `DialogFooterCarousel`'s accessibility contract (see its own
+  `accessibility.md`) — real `<button>`s, explicit dot labels, `aria-current`
+  on the active dot.
+- `variant="single"`'s primary action and `Close` are both real `Button`s;
+  `Close` is wrapped in `Dialog.Close` so Escape and the button both dismiss
+  the same way.
+
+## Contrast
+
+`image`'s placeholder surface (`--ui-background-surface-active`) and
+`title`/`description`'s text (`--ui-text-on-surface-primary`, bridged via
+`text-foreground`) are the same semantic surface/text pairing used across the
+kit — contrast-checked in both light and dark by construction.