@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/wizard.md

@@ -0,0 +1,412 @@
+# Wizard
+
+> The full-page wizard page template — a sticky header band (breadcrumb, title row with the flow's Cancel/Back/Next actions, an optional subtitle, an optional stepper) above a content column capped at 1024px. Layout and slots only: it owns no step index, no navigation, and no button wiring — which actions show on which step is the consuming UI block's decision, the same boundary PageHeader draws around its own actions slot. Mapped to the ui-react Figma "RegionMain" frame (node 10511-61418).
+
+**Status:** ready · **Category:** layout · **Since:** v1.1.0
+
+## Import
+
+```tsx
+import { Wizard, WizardHeader, WizardSubtitle, WizardBody } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Wizard>
+  <WizardHeader>
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem><BreadcrumbLink href="#">Dashboards</BreadcrumbLink></BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem><BreadcrumbPage>Create dashboard</BreadcrumbPage></BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+    <PageHeaderRow>
+      <PageHeaderTitle>Create dashboard</PageHeaderTitle>
+      <PageHeaderActions>
+        <Button variant="secondary">Cancel</Button>
+        <Button variant="secondary">Back</Button>
+        <Button>Next</Button>
+      </PageHeaderActions>
+    </PageHeaderRow>
+    <WizardSubtitle>Name it, pick its widgets, choose who can see it.</WizardSubtitle>
+    <Stepper currentStep={2} totalSteps={3} current="Choose widgets" next="Set permissions">
+      <StepperItem variant="completed" label="Name the dashboard" avatar={<Avatar color="green" className="[box-shadow:none]"><AvatarFallback>1</AvatarFallback></Avatar>} />
+      <StepperItem variant="current" label="Choose widgets" avatar={<Avatar color="blue" className="[box-shadow:none] text-[var(--ui-stepper-item-current-label-color)]"><AvatarFallback>2</AvatarFallback></Avatar>} />
+      <StepperItem variant="future" label="Set permissions" avatar={<Avatar color="gray" className="[box-shadow:none] text-[var(--ui-stepper-item-future-label-color)]"><AvatarFallback>3</AvatarFallback></Avatar>} />
+    </Stepper>
+  </WizardHeader>
+  <WizardBody>
+    <Section>
+      <SectionHeader title="Choose widgets" />
+      <SectionContent>{/* step fields */}</SectionContent>
+    </Section>
+  </WizardBody>
+</Wizard>
+```
+
+The full-page wizard page template — a sticky header band (breadcrumb, title row
+with the flow's actions, an optional subtitle, an optional stepper) above a
+content column capped at 1024px. Mapped to the ui-react Figma "RegionMain" frame
+(node `10511-61418`).
+
+Wizard is a **composition, not a primitive**. Every visual part it needs already
+exists in the kit — `Breadcrumb`, `PageHeaderRow` / `PageHeaderTitle` /
+`PageHeaderActions`, `Stepper` + `StepperItem`, `Section`, `Button` — and Wizard
+reimplements none of them. Its job is the structural skeleton and the slots.
+
+## When to use
+
+- A full-page, multi-step creation or configuration flow (e.g. Create dashboard,
+  Create protection plan) that takes over the page rather than a dialog.
+- A single-page form that still wants the same header band treatment: the stepper
+  is optional.
+
+## When not to use
+
+- A short flow that fits in a modal — use `Dialog` (and `DialogWelcome` for the
+  carousel-style onboarding flow).
+- A normal, non-stepped page — use `PageHeader` + `PageContent`.
+- **Step state or navigation logic.** Wizard has no `step` / `onNext` props by
+  design; see below.
+
+## What Wizard deliberately does not do
+
+Per the design brief, deciding which of Cancel / Back / Next / Submit appears on
+a given step — and what each one does — is a per-flow product decision owned by
+the consuming UI block, not the kit. So Wizard holds no step index, fires no
+navigation events, and renders no buttons; `PageHeaderActions` is a slot the
+consumer fills. This is the same boundary `PageHeader` draws around its own
+actions slot.
+
+That is a statement about these components, not about the implementation
+package: the React adapter also ships an opt-in headless hook (`useWizard`,
+`packages/ui-react/src/hooks/use-wizard.ts`) that holds the step index and
+derives the `Stepper` summary props plus each step's `variant` and avatar
+treatment, so a consumer needn't hand-maintain one `StepperItem` block per step.
+It sits outside this spec's contract — it renders nothing, still leaves button
+visibility to the consumer, and does no validation, branching, skipping or
+persistence.
+
+Likewise there is no `WizardTitle` or `WizardActions`: the title row is
+functionally identical to a page header's, so it is `PageHeaderRow` and friends,
+reused. And there is no `WizardStepper` wrapper — the consumer places a plain
+`Stepper` in the header, or omits it.
+
+The design brief's own reference pairing for which buttons to place in
+`PageHeaderActions`:
+
+| Flow                     | Buttons                  |
+| ------------------------ | ------------------------ |
+| Single-step              | `[Cancel] [CTA]`         |
+| Multi-step — first step  | `[Cancel] [Next]`        |
+| Multi-step — middle step | `[Cancel] [Back] [Next]` |
+| Multi-step — final step  | `[Cancel] [CTA]`         |
+
+"CTA" is the flow's submit action (e.g. "Install agent", "Create migration"),
+never a generic "Submit" label. The final step drops `Back` along with `Next` —
+it is not a three-button state.
+
+## Parts
+
+| Export           | Element | Purpose                                                                                                                                    |
+| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Wizard`         | `div`   | The template root — a full-height flex column.                                                                                             |
+| `WizardHeader`   | `div`   | The sticky header band: breadcrumb, title row, optional subtitle, optional stepper. Owns the surface, divider, padding, and inter-row gap. |
+| `WizardSubtitle` | `p`     | Optional muted supporting line under the title row (same treatment as `PageHeaderDescription`; there is no separate `Subtitle` component). |
+| `WizardBody`     | `div`   | The step's content column, capped at 1024px. Always wraps a `Section`.                                                                     |
+
+All parts accept their native element attributes plus `className`.
+
+## Example
+
+```tsx
+<Wizard>
+  <WizardHeader>
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">Dashboards</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>Create dashboard</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+
+    <PageHeaderRow>
+      <PageHeaderTitle>Create dashboard</PageHeaderTitle>
+      <PageHeaderActions>
+        <Button variant="secondary">Cancel</Button>
+        <Button variant="secondary">Back</Button>
+        <Button>Next</Button>
+      </PageHeaderActions>
+    </PageHeaderRow>
+
+    <WizardSubtitle>
+      Name the dashboard, pick its widgets, and choose who can see it.
+    </WizardSubtitle>
+
+    <Stepper
+      currentStep={2}
+      totalSteps={3}
+      current="Choose widgets"
+      next="Set permissions"
+    >
+      <StepperItem
+        variant="completed"
+        label="Name the dashboard"
+        avatar={
+          <Avatar color="green" className="[box-shadow:none]">
+            <AvatarFallback>1</AvatarFallback>
+          </Avatar>
+        }
+      />
+      <StepperItem
+        variant="current"
+        label="Choose widgets"
+        avatar={
+          <Avatar
+            color="blue"
+            className="[box-shadow:none] text-[var(--ui-stepper-item-current-label-color)]"
+          >
+            <AvatarFallback>2</AvatarFallback>
+          </Avatar>
+        }
+      />
+      <StepperItem
+        variant="future"
+        label="Set permissions"
+        avatar={
+          <Avatar
+            color="gray"
+            className="[box-shadow:none] text-[var(--ui-stepper-item-future-label-color)]"
+          >
+            <AvatarFallback>3</AvatarFallback>
+          </Avatar>
+        }
+      />
+    </Stepper>
+  </WizardHeader>
+
+  <WizardBody>
+    <Section>
+      <SectionHeader
+        title="Choose widgets"
+        description="Widgets you add here appear on the dashboard in the order you pick them."
+        hasDescription
+      />
+      <SectionContent>{/* step fields */}</SectionContent>
+    </Section>
+  </WizardBody>
+</Wizard>
+```
+
+The step markers follow `StepperItem`'s composed-`Avatar` conventions: `Avatar`'s
+2px outset ring is switched off with `[box-shadow:none]` (it would otherwise show
+as a halo on the filled step container), and the `current`/`future` digits are
+recolored to the step's own `--ui-stepper-item-{current,future}-label-color`.
+Wizard's `completed` marker is a digit on a green `Avatar` and carries no digit
+color override, so the digit keeps `Avatar`'s own green-scheme foreground; the
+reference pattern in `StepperItem`'s stories instead puts a fixed checkmark icon
+in the `completed` avatar, where the question doesn't arise. See
+[`stepper-item/README.md`](../stepper-item/README.md) for what each override
+does.
+
+### Short flow — no stepper
+
+```tsx
+<Wizard>
+  <WizardHeader>
+    <PageHeaderRow>
+      <PageHeaderTitle>Create dashboard</PageHeaderTitle>
+      <PageHeaderActions>
+        <Button variant="secondary">Cancel</Button>
+        <Button>Create dashboard</Button>
+      </PageHeaderActions>
+    </PageHeaderRow>
+  </WizardHeader>
+  <WizardBody>
+    <Section>{/* … */}</Section>
+  </WizardBody>
+</Wizard>
+```
+
+### Wider step
+
+```tsx
+<WizardBody className="max-w-[1280px]">
+  <Section>{/* a data table step */}</Section>
+</WizardBody>
+```
+
+## Behavior
+
+```gherkin
+Scenario: Header band above the content column
+  Given a Wizard holding a WizardHeader and a WizardBody
+  Then the header band renders above the content column
+  And the band sits on the secondary surface with a divider along its bottom edge
+```
+
+```gherkin
+Scenario: Header stays put while a long step scrolls
+  Given a WizardBody taller than the viewport
+  When the user scrolls the step's content
+  Then the WizardHeader stays pinned to the top of the scroll container
+  So that the step context and the Cancel/Back/Next actions remain reachable
+```
+
+```gherkin
+Scenario: Header row order
+  Given a WizardHeader
+  Then its children stack vertically in the order the consumer wrote them —
+  breadcrumb, title row, subtitle, stepper — separated by a single fixed gap
+```
+
+```gherkin
+Scenario: Title row is PageHeader's, reused
+  Given a wizard's title and its Cancel/Back/Next actions
+  Then they are composed from PageHeaderRow, PageHeaderTitle and PageHeaderActions
+  And Wizard adds no WizardTitle / WizardActions parts of its own, since the row
+  is functionally identical to a page header's
+```
+
+```gherkin
+Scenario: Which actions show on a step
+  Given a multi-step flow whose last step submits instead of advancing
+  Then the consuming UI block decides which of Cancel / Back / Next / Submit to
+  place in PageHeaderActions on each step
+  And Wizard neither tracks the step index nor renders or wires any of those
+  buttons — it provides only the slot
+```
+
+The design brief's own reference pairing (Figma's "Wizard" documentation page,
+`node-id=11098-18`) for that per-step decision:
+
+| Flow                     | Buttons                  |
+| ------------------------ | ------------------------ |
+| Single-step              | `[Cancel] [CTA]`         |
+| Multi-step — first step  | `[Cancel] [Next]`        |
+| Multi-step — middle step | `[Cancel] [Back] [Next]` |
+| Multi-step — final step  | `[Cancel] [CTA]`         |
+
+"CTA" is the flow's submit action (e.g. "Install agent", "Create migration",
+"Delete device") — its label is never "Submit" generically. Note the final step
+drops `Back` along with `Next`, matching the single-step pairing exactly; only
+the middle steps carry three buttons.
+
+Knowing _where in the flow_ you are is a separate concern from deciding which
+buttons that position shows. The React adapter's opt-in `useWizard` hook answers
+the first (`isFirstStep` / `isLastStep`, plus the `Stepper` props); the pairing
+above stays the consumer's, on every implementation.
+
+```gherkin
+Scenario: Optional subtitle
+  Given a flow that needs a supporting line under its title
+  Then a WizardSubtitle renders it in the muted secondary text color
+  And omitting it leaves no empty row in the header band
+```
+
+```gherkin
+Scenario: Optional stepper
+  Given a wizard of two or three steps
+  Then the flow may omit the Stepper entirely
+  And Wizard neither requires one nor renders a fallback in its place
+```
+
+```gherkin
+Scenario: Stepper collapses on a narrow viewport
+  Given a WizardHeader containing a Stepper
+  When the viewport is narrower than 1024px
+  Then the Stepper itself swaps its item row for its two-line text summary
+  And Wizard's own layout is unchanged — the switch belongs to Stepper
+```
+
+```gherkin
+Scenario: Content column width
+  Given a WizardBody
+  Then its content is capped at 1024px and bottom-padded
+  And a step needing a different width overrides it through className, since
+  there is no width variant
+```
+
+```gherkin
+Scenario: Step content is a Section
+  Given a wizard step's fields
+  Then they live inside a Section rendered as WizardBody's child
+  And WizardBody itself contributes no titling or padding of its own beyond the
+  cap and the bottom pad
+```
+
+```gherkin
+Scenario: Right-to-left
+  Given the wizard renders under dir="rtl"
+  Then the header band's padding, the title row, and the content column mirror
+  Because Wizard uses only symmetric and logical spacing utilities
+```
+
+## Accessibility
+
+Wizard is a layout scaffold: it renders no text and no interactive element of its
+own, so nearly all of its accessibility contract belongs to the components the
+consumer composes into it. What Wizard itself is responsible for is not getting in
+their way.
+
+- **No landmark of its own.** Neither `Wizard` nor `WizardHeader` sets a `role`.
+  `PageHeader`'s root is deliberately **not** reused for the header band —
+  it carries `role="banner"`, and a wizard's header band is not the page banner.
+  Composing `PageHeaderRow` / `PageHeaderTitle` / `PageHeaderActions` directly
+  keeps the landmark structure honest and avoids a second `banner` on a page that
+  already has one (e.g. inside `AppShell`).
+- **Heading outline.** `PageHeaderTitle` is an `<h1>` — one per page, and the
+  only heading the wizard template contributes on its own. `SectionHeader`'s
+  `title` prop renders a `<p>`, not a heading, so a step's `Section` adds
+  nothing to the document outline: an `<h1>` alone is the whole outline. That's
+  fine for a single-section step, where the `<h1>` already names the flow. If a
+  step's body needs navigable structure — several `Section`s, or one a
+  screen-reader user should be able to jump to — `Section` offers an escape
+  hatch: pass a real heading (`h2`, to sit directly under the wizard's `<h1>`)
+  through `SectionHeader`'s `children` slot and omit `title` so the section
+  isn't titled twice; see
+  [`section/accessibility.md`](../section/accessibility.md) for the markup and
+  the styling you have to supply yourself. Wizard's own stories don't use that
+  escape hatch — the multi-`Section` story titles each section with `title`, so
+  those steps contribute no headings beyond the `<h1>`.
+- **The subtitle is a plain `<p>`**, not a heading and not the title's accessible
+  description. If the flow needs it announced with the title, associate it
+  explicitly (`aria-describedby` on the relevant control), since proximity alone
+  conveys nothing to a screen reader.
+- **Step progress** is announced by the composed `Stepper`, which owns that
+  contract (see the Stepper spec). A wizard that omits the stepper — as two- and
+  three-step flows may — leaves the user without a progress cue, so give those
+  flows a title or subtitle that makes the position obvious.
+- **Navigation actions** are plain `Button`s the consumer supplies, so their
+  accessible names come from their own children. Keep them as real buttons in DOM
+  order — Cancel, then `Back` on middle steps only, then Next/CTA — matching the
+  per-step pairing in [`behavior.md`](./behavior.md), rather than reordering
+  visually. Because that pairing genuinely adds and removes `Back` between steps
+  (it is absent, not disabled, on the first and final steps), the action row's
+  composition changes as the flow advances. Wizard tracks no step index and moves
+  no focus, so the consumer owns the transition: after navigating, move focus
+  deliberately — to the new step's first focusable field, since (per the
+  heading-outline bullet above) a step's `Section` title is a `<p>` and
+  contributes no heading to land on by default — so it never lands on a
+  button that has just been removed or shifted position, and never silently
+  falls back to the document body.
+- **Sticky header and focus.** The header band is `position: sticky`, so it can
+  overlay content scrolled under it. Give focusable content inside `WizardBody`
+  enough scroll margin that keyboard focus never lands underneath the band.
+- **RTL.** Wizard uses only symmetric (`p-`) and logical spacing, so the whole
+  template mirrors under `dir="rtl"` with no per-part handling.
+
+## Contrast
+
+The header band pairs `--ui-background-surface-secondary` with the composed
+parts' own on-surface text colors; the subtitle uses
+`--ui-text-on-surface-secondary` (via `text-muted-foreground`). Both meet
+contrast in light and dark. The band's bottom rule is
+`--ui-border-on-surface-divider`, a decorative separator — the header/content
+boundary is also conveyed structurally, not by that line alone.

package/dist/llms.txt

@@ -0,0 +1,142 @@
+# Acronis UI Kit for React — LLM Reference
+
+> `@acronis-platform/ui-react` v4.0.0
+
+Machine-readable component reference compiled from framework-agnostic specs.
+Each entry links to a self-contained markdown file with props, behavior,
+accessibility notes, and usage examples.
+
+## How to reference in CLAUDE.md / project instructions
+
+```
+# Full index (broad overview):
+@node_modules/@acronis-platform/ui-react/dist/llms.txt
+
+# Single component (deep reference):
+@node_modules/@acronis-platform/ui-react/dist/llms/button.md
+```
+
+## Actions
+
+- [Button](./llms/button.md): Triggers an action or event when activated. Five visual styles (default, secondary, ghost, destructive, ai) in a single 32px-tall size.
+- [ButtonGroup](./llms/button-group.md): A compact cluster of related icon-only actions sharing a single box, hairline-separated. Two container styles (outlined, inlined) around a variadic list of 32px-tall items.
+- [ButtonIcon](./llms/button-icon.md): Icon-only button (32×32, 24px glyph) with idle, hover, active, and disabled states. Two variants share the same fill and icon colors: `ghost` (borderless) and `secondary` (a 1px container border). Use when an action is represented by an icon alone.
+- [ButtonIconInput](./llms/button-icon-input.md): A smaller icon-only button (20×20, 16px glyph) meant to live inside an input's box (e.g. a clear or reveal affordance), as opposed to `ButtonIcon`'s standalone 32×32 sizing. `variant` (`normal` / `error`) mirrors the tone of the field it sits in.
+- [ButtonIconMenu](./llms/button-icon-menu.md): The kebab ("more options") trigger: a 32×32 bordered icon-only button holding a fixed 16px ellipsis glyph, across idle, hover, open, disabled, and focus states. Opens a menu of actions where there is no room for a label.
+- [ButtonMenu](./llms/button-menu.md): A button that opens a dropdown menu: a label followed by a chevron that points up while the menu is open. Two visual styles (primary, secondary) across idle, hover, open, and disabled states.
+
+## Data display
+
+- [AreaChart](./llms/area-chart.md): A typed area-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `AreaChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `layout` (single / stacked areas) and `fill` (solid flat fill / vertical gradient); single vs multi area is driven by the number of `dataKeys`. Ported from the apps/demo `AreaChartPlayground`.
+- [Avatar](./llms/avatar.md): A user or entity avatar — a circular badge showing a profile image, initials, or an icon. Eight color schemes; stack several with AvatarGroup for an overlapping row.
+- [BarChart](./llms/bar-chart.md): A typed bar-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `BarChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `orientation` (vertical / horizontal bars) and `layout` (grouped / stacked). Ported from the apps/demo `BarChartPlayground`.
+- [CardFilter](./llms/card-filter.md): A compact stat/filter card: a caption label above a prominent value, with an optional leading icon. Three variants — `static` (presentational), `static-empty` (presentational placeholder with an em-dash), and `clickable` (an interactive filter that renders a button with hover / active / focus states).
+- [CategoryBar](./llms/category-bar.md): A single horizontal bar split into proportional colored segments — one part-to-whole across a handful of categories in one row (onboarding stages, certification status, a pass/fail split). Each segment's width is its value over the sum of all values; segment colors are caller-supplied via `config`. A plain flex composition (not a recharts chart) with one CVA axis (`size`), an optional count/% legend, and per-segment hover tooltips. Design-pending v1 — no chart token tier exists yet.
+- [Chart](./llms/chart.md): A theming layer over recharts — a `ChartContainer` that supplies series colors and recharts class overrides, plus tooltip and legend chrome (`ChartTooltipContent`, `ChartLegendContent`). The chart type (bar / line / area / pie / …) is composed from recharts primitives by the caller. Ported from the legacy shadcn-uikit `chart`.
+- [ChartState](./llms/chart-state.md): A shared loading / empty / error placeholder for the chart types, rendered in place of the chart inside the same sized slot. A compact status block — a leading glyph over a centered label, with an optional retry action for the error state. The `empty` state draws the silhouette the design defines for each chart type (`variant`), plus an optional "Widget description" line; `loading` and `error` share one treatment. Distinct from `WidgetPlaceholder`, which is the composable skeleton for a widget that isn't a chart — see behavior.md.
+- [ChartWidget](./llms/chart-widget.md): The dashboard card a chart sits in: a `Card` with the standard widget header (title, optional filter chip and the ⋯ actions menu) and an optional metric readout above the plot. Adds the one thing a `Card` doesn't know about — the body's loading / empty / error placeholder — and re-implements nothing else: its `header` is `CardHeaderProps`, spread. It declares no size: the grid sizes the card and the widget passes that height down, so a `size-full` chart fills whatever the header leaves. The per-type chart components stay card-less, so a chart is still usable outside a widget.
+- [Chip](./llms/chip.md): A compact, interactive label for a selection, a removable token, or an inline action. The `removable` variant carries a trailing × button; `selectable` is a toggle that shows an active style when selected; `operational` is a plain action chip with a strong-link label. All three accept an optional leading icon.
+- [ComposedChart](./llms/composed-chart.md): A typed composed (mixed) chart over the shared `Chart` primitives. Plots a `series` list over one shared category axis, where each entry picks its own render `type` (bar / line / area), inside a `ChartContainer` with tooltip and legend chrome. No variant axes — the mix is data-driven via `series[].type`. Series render in the caller's `series` order (later entries paint on top). Ported from the apps/demo `ComposedChartPlayground`.
+- [ConfidenceCone](./llms/confidence-cone.md): A forecast confidence-cone over the shared `Chart` primitives: a solid line for the known/actual period, a dashed line for the forecast, and a shaded band (the "cone") between a lower and upper bound that typically widens with the horizon, visualizing growing uncertainty. Distinct from the conversion `FunnelChart`. Design-pending v1 (no `--ui-chart-*` palette, no `apps/demo` playground — built net-new).
+- [DataTable](./llms/data-table.md): A data grid built on TanStack react-table v8, composed over the Table primitives — sorting, filtering (text + per-column), column visibility, row selection, pagination, optional row expansion (row-level or an in-cell expand trigger), column resizing, drag-to-reorder columns, and sticky (pinned) columns. Renders a built-in trailing action column (the column-settings cog in the header, a per-row overflow-actions trigger in each row) and per-header capability-hint tooltips, and navigates rows with a roving tabindex. Ships with companion parts (column header, toolbar, pagination, view options, expand trigger, bulk-actions bar). Also supports server-driven usage: rendering from an externally-built TanStack `table` instance, manual (server-driven) sorting, infinite-scroll pagination, and custom row/empty-state rendering. Ported from the legacy shadcn-uikit `data-table`.
+- [DescriptionList](./llms/description-list.md): A key/value data list — rows of label → value, where the value can be plain text, a status (leading icon + value + a muted description), or action links. Composable, semantic `<dl>`. NOT backed by a shared design-system design: it is the pattern extracted from the "Service status" list in the product-specific Cyber-Compliance Figma file (hc8FRfvlHBqZwNYUsD0DaX), not from the shared ui-react file, so the `figma.node` below is a product mapping rather than a design-system source of truth. Whether to formalize this as a generic kit component is still an open decision.
+- [Empty](./llms/empty.md): A centered empty-state placeholder shown when there is no data or content. A set of composable parts (icon, header, title, description, actions, links). Ported from the legacy shadcn-uikit `Empty`; themed by the shared semantic text tokens.
+- [EmptyOverlay](./llms/empty-overlay.md): A full-bleed empty-state overlay — a colored icon badge over a centered title/description, on a fade-to-solid backdrop. Meant to sit over other content (e.g. a frozen/blurred widget preview); the developer sizes it (typically `absolute inset-0` over a positioned parent).
+- [FilterCards](./llms/filter-cards.md): A horizontal row container (the Figma `FilterCards` component) that lays out a set of `CardFilter` items, stretching each to an equal share of the available width. Pure layout — it owns no visual styling of its own besides the inter-card gap. Figma's nested `ListCards` slot maps to `children`.
+- [FilterChips](./llms/filter-chips.md): A wrapping row that summarises the filters currently applied to a data set (the Figma `FilterChips` component): one removable `Chip` per filter, closed by a ghost "Reset filters" action that clears them all at once. Pure layout — it owns no visual styling of its own besides the two gaps. Figma's nested `ListChips` slot maps to `FilterChipsList`'s children.
+- [FunnelChart](./llms/funnel-chart.md): A typed funnel-chart composition over the shared `Chart` primitives. Plots a single series of stages (rows) as stacked, narrowing segments inside a `ChartContainer`, with a tooltip and on-chart stage labels (no legend — the inline labels name every stage). One variant axis: `lastShape` (the funnel narrows to a `triangle` point or ends `rectangle` flat). Ported from the apps/demo `FunnelChartPlayground`.
+- [Histogram](./llms/histogram.md): A frequency histogram — bins a set of continuous samples (`values`) into equal-width ranges and plots the count of each as contiguous bars. Distinct from `BarChart`, which plots pre-categorized rows: the binning is the component's own job (a pure helper). Built on the shared `Chart` primitives; design-pending v1 (no `--ui-chart-*` palette yet, no `apps/demo` playground).
+- [LineChart](./llms/line-chart.md): A typed line-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `LineChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `curve` (linear / monotone / step interpolation) and `lineStyle` (solid / dashed stroke); single vs multi line is driven by the number of `dataKeys`. Ported from the apps/demo `ChartPlayground`.
+- [Meter](./llms/meter.md): A labelled bar showing a scalar value within a known range — a fractional value / share (`role="meter"`, mirroring the HTML `<meter>` element), as opposed to `Progress` which tracks a task over time. One row: label + `value · %` over a proportional track bar, with a hover tooltip; designed to be stacked into a ranked breakdown (a "bar list"). Design-pending v1 (no `--ui-chart-*` palette; the fill color is caller-supplied per row).
+- [Metric](./llms/metric.md): A presentational stats strip: an optional info-tinted icon badge + primary value + unit on the left, an optional caption on the right, an optional trend row (auto-composed from `trend` + `trendValue` as a `TrendIndicator`), optional supporting text, and an optional `children` body (a chart, Separator, insight line, …). No Card wrapper, no size or status axes — nest inside `ChartWidget` or a `Card` when card chrome is needed. It owns visual hierarchy and layout only; it never computes or formats the value or decides whether a change is good or bad. Design-pending v1.
+- [PieChart](./llms/pie-chart.md): A typed pie/donut-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a `dataKey` (slice value) and `nameKey` (slice label) and renders a themed recharts `PieChart` inside a `ChartContainer`, with tooltip and legend chrome. One variant axis: `shape` (filled pie / hollow-centre donut). Ported from the apps/demo `PieChartPlayground`.
+- [RadarChart](./llms/radar-chart.md): A typed radar-chart composition over the shared `Chart` primitives (the first polar chart type). Plots a set of series `dataKeys` over one shared angular axis (`angleKey`) inside a `ChartContainer`, with a polar grid, tooltip, and legend. One variant axis: `gridType` (the web drawn as straight-edged `polygon` rings or smooth `circle` rings). Ported from the apps/demo `RadarChartPlayground`.
+- [RadialBarChart](./llms/radial-bar-chart.md): A typed radial-bar-chart composition over the shared `Chart` primitives (a polar/radial type). Plots each data row as a concentric arc sized by `dataKey` and colored per `nameKey` — or, with `dataKeys`, one arc per metric — inside a `ChartContainer` with an optional background track, tooltip, and legend. No variant axes: the sweep (start/end angle), radii and centre are plain props. `valueDomain` scales the arcs against a known range, which is what turns a single value into a readable gauge; `segments` draws such a gauge's ring as notched pieces and `centerLabel` puts the reading in the hole. Ported from the apps/demo `RadialChartPlayground`.
+- [SankeyChart](./llms/sankey-chart.md): A typed Sankey flow-diagram composition over the shared `Chart` primitives. Renders a graph of `nodes` + `links` where each link's width is proportional to its flow value, inside a `ChartContainer`, with token-themed node bars and link ribbons plus a tooltip. No axes or grid, and no variant axes; an optional count/% legend (`showLegend`) renders below the chart, and geometry (`nodePadding` / `nodeWidth` / `linkCurvature`) is plain props. Themed through custom node/link renderers (recharts' defaults paint one flat grey and have no token hooks). Built on recharts' `Sankey` primitive (no apps/demo playground existed).
+- [ScatterChart](./llms/scatter-chart.md): A typed scatter-chart composition over the shared `Chart` primitives. Plots each `series[]` entry's points on numeric `xKey` / `yKey` axes inside a `ChartContainer`, with tooltip and legend chrome. Optionally maps a `zKey` to point size (a bubble chart). Scatter has no variant axes — its expressiveness comes from the data mapping, not a visual mode. Ported from the apps/demo `ScatterChartPlayground`.
+- [Table](./llms/table.md): Displays rows and columns of data. A set of composable parts (header, body, footer, row, column header, cell, caption) with sortable column headers, a selected row state, and wrappable cells, plus two TanStack-independent companions — a pagination bar (TablePagination) and a show/hide-columns menu (TableViewOptions) — and two headless hooks (useSortState, useTableUrlState). Ported from the legacy shadcn-uikit `Table` and informed by the pre-release Table design; themed by the `--ui-table-*` token tier. The TanStack-backed data grid (`DataTable`) composes these primitives.
+- [Tag](./llms/tag.md): A compact label that represents, categorizes, or highlights a piece of information — a status, attribute, or keyword. Six status variants across two sizes, with an optional leading icon.
+- [Timeline](./llms/timeline.md): A presentational, chronological tree of events — an activity feed, audit log, or status history. `Timeline` + `Timeline.Item` render a semantic ordered list in which each row pairs an Avatar marker with a Card carrying the title, an optional tag, the timestamp, and a description; rows join their parent through an elbow and their next sibling through a vertical connector. Nesting is flat and explicit — a row declares its own `level` (1-3) — and the root reads those levels to place the connectors and, under `variant="tree"`, to give every row with descendants a disclosure control. It owns structure, connector geometry and branch collapsing only: it never sorts, groups, fetches, or interprets events, holds no tree model of its own, and ships no domain event types or icons. Not a temporal chart.
+- [Timer](./llms/timer.md): An elapsed-time readout paired with a hairline-separated cluster of icon-only actions, in a single bordered 32px box. Displays a caller-formatted value; it does not tick.
+- [Treemap](./llms/treemap.md): A typed treemap composition over the shared `Chart` primitives. Tiles a flat set of leaves into nested rectangles sized by `dataKey` and colored per `nameKey`, inside a `ChartContainer`, with one- or two-line on-cell labels, a tooltip and an opt-in legend. No axes or grid — and no variant axes; `aspectRatio` is a plain prop. Themed through a custom cell renderer (recharts' default has no token hooks). Ported from the apps/demo `TreemapChartPlayground`.
+- [TrendIndicator](./llms/trend-indicator.md): A small presentational trend/delta indicator — a direction glyph, an already-formatted change value, and an optional comparison label. It separates `direction` (what happened mathematically) from `sentiment` (whether that is good or bad), so the kit never assumes up = good. Inline or compact badge, two sizes. Design-pending v1 (no Figma node yet).
+- [WidgetPlaceholder](./llms/widget-placeholder.md): An empty-state placeholder for a dashboard widget — a bordered card with a header (icon + title), a centered illustration / message / action, and an optional footer. Ported from the legacy shadcn-uikit `WidgetPlaceholder`; composable parts, optionally interactive.
+
+## Feedback
+
+- [Alert](./llms/alert.md): An inline status banner: a neutral surface carrying its severity through a status-colored border and a status line down the leading edge, with a fixed status icon per severity, composable title / description / action parts, and an optional dismiss control.
+- [Loading](./llms/loading.md): A composite loading indicator — a spinning ring plus an optional label — for four placement contexts: inline (flush in text flow), two card-like chips for a primary/secondary app surface, and a higher-contrast chip for busy/photo surfaces. Distinct from `Spinner` (the bare ring primitive it reuses for its icon): `Spinner` has no label or container and is unaffected by this addition.
+- [Progress](./llms/progress.md): A horizontal bar showing the completion of a known-length task, or an indeterminate sliding bar when the length is unknown. Ported from the legacy shadcn-uikit `Progress`; wraps the Base UI Progress primitive.
+- [ProgressCircle](./llms/progress-circle.md): A circular (radial) progress indicator — an SVG ring whose arc fills with the value and whose color tracks the level (danger / critical / warning / success), with an optional numeric or icon center. Built from the Cyber-Compliance "Compliance %" design; the sibling of the linear Progress. Design reconciliation against the Figma component master is pending.
+- [Skeleton](./llms/skeleton.md): A pulsing placeholder box for loading states. Shape and size come from the caller's className. Ported from the legacy shadcn-uikit `skeleton`.
+- [Spinner](./llms/spinner.md): An indeterminate loading indicator — a spinning ring in four sizes. Ported from the legacy shadcn-uikit `Spinner`; a CSS spinner (no primitive), colored by the shared brand token via currentColor. As of 0.58.0, deliberately NOT exported from `@acronis-platform/ui-react`'s public entry point — it is an internal primitive consumed by `Loading` (icon) and `Toast` (a small inline icon). Apps building a standalone loading state should use `Loading` instead.
+- [Toast](./llms/toast.md): A transient notification in a corner stack: a neutral card carrying its severity through a status-colored border and a status line down the leading edge, with a fixed status icon per severity, an optional description, and optional action buttons. Triggered imperatively via the `toast(...)` API and rendered by a single `<Toaster>` region.
+
+## Forms
+
+- [Calendar](./llms/calendar.md): A day-grid built on react-day-picker: single / range / multiple date selection across one or more months side by side, with prev/next navigation at the outer edges of the month row. Design-pending v1 ported from ui-legacy — themed off the shared semantic tokens (no `--ui-calendar-*` tier yet).
+- [CalendarPanel](./llms/calendar-panel.md): The Figma "Calendar" panel: a bordered, elevated day-picker panel built on react-day-picker and themed by the dedicated `--ui-calendar-*` token tier. A single `variant` prop selects one of the three selection modes, and each one changes the panel's structure — `single` is one month column with no footer, `multiple` adds a Cancel/Apply footer, and `range` shows two month columns side by side (divided by a vertical rule) sharing one footer. Months are navigated through two `InputSelect` dropdowns in each month's header; there are no prev/next chevrons. `variant` is a plain string union, not a `cva` axis.
+- [Checkbox](./llms/checkbox.md): A control that lets users select or deselect an option. Supports checked, unchecked, and indeterminate states; used individually for a binary choice or in groups where any number of options may be selected.
+- [Combobox](./llms/combobox.md): A searchable select built on Base UI's Combobox primitive — a typeable input that filters a list of items in a dropdown. Reuses the InputSelect token tier so it matches the non-searchable select. The legacy shadcn-uikit `combobox` was only a hardcoded Popover + cmdk demo; this is a real, reusable component.
+- [DateRangePicker](./llms/date-range-picker.md): A range date field: an `InputDatePicker` trigger opens a popover with a dual-month range `CalendarPanel`, whose own Cancel/Apply footer commits or reverts the draft. Edits stay in a draft until Apply commits them (Cancel or dismissing reverts).
+- [Field](./llms/field.md): A form-field wrapper that ties a control to its label, description, and error, built on Base UI's Field primitive so those associations (and the validity state) are wired automatically. Ships structural parts (fieldset, legend, group, content, separator) for composing and grouping fields. Ported from the legacy shadcn-uikit `field`.
+- [Form](./llms/form.md): A native form element with consolidated validation, built on Base UI's Form. It collects values by each Field's name, runs the Fields' validation on submit (or per validationMode), surfaces server errors keyed by field name, and calls onFormSubmit with the values when every field is valid. Ported from the legacy shadcn-uikit `form` (which wrapped react-hook-form); this version drops that dependency and composes the ui-react Field directly.
+- [InputDatePicker](./llms/input-date-picker.md): The date-field trigger: a button box that displays a formatted date (or a start–end range when `pickerType="dateRange"`) and a trailing calendar icon, with an optional label (and required marker) and an optional description or error message. Opens a consumer-owned calendar. Themed by the `--ui-input-date-picker-*` token tier.
+- [InputOTP](./llms/input-otp.md): A bare row of single-character boxes for entering a one-time code. No label/description — like `Input`, field furniture is a future `Field` wrapper. Typing a digit advances focus to the next slot; Backspace on an empty slot clears and moves back; pasting a full code distributes it across the slots.
+- [InputPassword](./llms/input-password.md): A single-line password field: an optional label (with an optional required marker), the value box with a built-in show/hide toggle, and an optional description or error message. Its own `--ui-input-password-*` token tier covers the box down to fill/border (unlike `InputText`, it doesn't build on the bare `Input` primitive).
+- [InputSearch](./llms/input-search.md): A full search field: an optional label (with an optional required marker) above the search box. Builds on the bare `Search` box (leading magnifier, input, and clear button) and the `--ui-input-search-*` token tier.
+- [InputSelect](./llms/input-select.md): The next-gen select field: an optional label (with a required marker), a trigger box showing the value / placeholder and a chevron, an optional description or error message, and a floating dropdown with an in-dropdown search, sections (groups), single or multiple selectable items, and loading / empty / error status. Composes Base UI `Select` and the `--ui-input-select-*` token tier.
+- [InputText](./llms/input-text.md): A full single-line text field: an optional label (with an optional required marker), the text input box, an optional clear button, and an optional description or error message. Builds on the bare `Input` primitive and the `--ui-input-text-*` token tier.
+- [InputTextArea](./llms/input-text-area.md): A full multiline text field: an optional label (with an optional required marker), a `<textarea>` box that grows with vertical resize, and an optional description or error message. For entering and editing longer free-text (notes, comments, descriptions). Themed by the `--ui-input-text-area-*` token tier.
+- [NumberField](./llms/number-field.md): A numeric input with decrement / increment steppers, min/max/step, and scrub support. Built on Base UI's NumberField; the field box reuses the InputText token tier. Ported from the legacy shadcn-uikit `number-field`.
+- [RadioGroup](./llms/radio.md): A group of mutually exclusive options where exactly one can be selected. Selecting an option deselects the previously selected one. Composed from a RadioGroup container and Radio items.
+- [Select](./llms/select.md): A form control that displays the current selection and reveals a list of predefined options when activated. Composed from parts (trigger, value, content, item); supports single or multiple selection. An alias of the next-gen `InputSelect` family, themed with the `--ui-input-select-*` token tier.
+- [Slider](./llms/slider.md): A slider for choosing a number (or a range, with two thumbs) within a min/max by dragging. Built on Base UI's Slider. Ported from the legacy shadcn-uikit `slider`.
+- [Switch](./llms/switch.md): A binary on/off toggle. Wraps the Base UI Switch primitive; the change takes effect immediately (no separate submit).
+- [ToggleGroup](./llms/toggle-group.md): A set of pressable toggle buttons (single or multiple selection) — plus a standalone Toggle. Built on Base UI's Toggle / ToggleGroup. Ported from the legacy shadcn-uikit `toggle-group`.
+
+## Layout
+
+- [Accordion](./llms/accordion.md): A vertical set of disclosure sections — each with a header trigger and a height-animating panel; single or multiple open at once. Built on Base UI's Accordion. Ported from the legacy shadcn-uikit `accordion`.
+- [AccordionContainer](./llms/accordion-container.md): The shared disclosure primitive behind Card's and Section's `isCollapsable` variant. Built directly on Base UI's Collapsible — owns open state, the trigger button, chevron rotation, and panel animation — while imposing no visual styling beyond what the disclosure mechanic itself requires — the two exceptions are its trigger's chevron glyph color (the same neutral treatment Accordion's chevron uses) and, when `collapsible` is true, Root defaulting to `display: contents` so it stays transparent to the consumer's layout. Every other visual decision (header layout, spacing, background, borders) stays owned by the component composing it.
+- [AppShellChat](./llms/app-shell-chat.md): A 3-section, horizontally resizable application scaffold: a sidebar rail (SidebarPrimary, optionally SidebarSecondary) beside a Content page column and a Chat panel. Content and Chat resize against each other by dragging Chat's start border; the sidebars resize Content only (Chat keeps its explicit pixel width). Chat is resize-only: dragging down to its floor width shows an icon-only rail, and dragging up can take it to full width (Content shrinks to 0) since the resize ceiling is measured from the actual available row space. The Chat slot is optional, so the same scaffold also serves an ordinary two-column console screen.
+- [Card](./llms/card.md): A surface that groups related content and actions. A set of composable parts (header, content, footer) on a bordered, rounded container. The header carries the interactive surface: an optional drag handle, toggle switch, avatar, rename button, extras, end-aligned actions, and an optional collapse trigger. Collapsibility is composed by wrapping the header and content/footer in `AccordionContainer`.
+- [CardSection](./llms/card-section.md): A band of content stacked inside a `Card`'s body, below `CardHeader`. Six variants pick the body shape — an arbitrary slot, a wrapping tag row, a title/description list, a flush table with row actions, or a nested `Card` on the primary or secondary surface. An optional 14px mini-header (distinct from `CardHeader`) carries a title, inline extras, and end-aligned actions; an optional bottom divider separates one section from the next.
+- [CarouselDialog](./llms/carousel-dialog.md): The control row inside a `DialogFooterCarousel`: a `Back` button (hidden on the first slide), a dot slide indicator, and a `Next`/call-to-action button. Pure controls — no Embla import; the slide count/index/callbacks are threaded down from `DialogWelcome`, which owns the carousel engine. Deliberately NOT exported from `@acronis-platform/ui-react`'s public entry point — it is an internal primitive consumed only by `DialogFooterCarousel`. Apps building a welcome/onboarding carousel dialog should use `DialogWelcome` instead.
+- [DialogFooterCarousel](./llms/dialog-footer-carousel.md): A bottom action bar for a multi-step (carousel) dialog: a `Back` button (hidden on the first slide), a dot slide indicator, and a `Next`/ call-to-action button. The `variant` (start / middle / end) tracks the active slide's position — see `DialogWelcome`, which owns the actual Embla carousel engine and drives this component's props.
+- [DialogFooterDefault](./llms/dialog-footer-default.md): 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.
+- [FilterSearch](./llms/filter-search.md): A composable toolbar for data tables: arranges a search field, optional filters button, optional tenant/scope switcher, and trailing action buttons in a single horizontal row. Pure layout — no dedicated token tier; child components (Search, ButtonMenu, Select) bring their own tokens. `FilterSearchFilters` (the filter popover: trigger + form + Reset/Cancel/ Apply) is still a design-pending addition — no Figma node yet, unlike the FilterSearch node itself (see `figma:` below, which covers only the root toolbar layout). `FilterSearchAppliedFilters` (the removable-chip row + top-level "Reset filters") is the data-driven wrapper over `FilterChips`, which owns that row's design — see the FilterChips spec.
+- [Grid](./llms/grid.md): A responsive CSS-grid layout primitive — lay children into a column count that steps down at smaller breakpoints, with a configurable gap. Ported 1:1 from the legacy shadcn-uikit `grid`.
+- [PageContent](./llms/page-content.md): The page content region — the padded gutter for a page's body. A <div> meant to nest inside AppShellChatContentBody (so it doesn't duplicate the main landmark). Ported from the legacy shadcn-uikit `page-content`.
+- [PageHeader](./llms/page-header.md): The page header region — a title row (title left, an optional edit icon-button, a tags slot, an actions slot) and an optional description row (text + an optional edit icon-button), capped at 512px. Sits at the top of a page's content; a breadcrumb is a separate sibling above it, not one of its parts. Mapped to the ui-react Figma "PageHeader" master component (node 2905-7678).
+- [Resizable](./llms/resizable.md): A group of panels separated by draggable handles that let the user resize adjacent regions along one axis. Composable parts (panel group, panel, handle); the handle is a thin divider with an optional grab-bar grip and resizes its neighbouring panels on drag or arrow keys.
+- [ScrollArea](./llms/scroll-area.md): A scrollable region with a custom overlay scrollbar built on the Base UI Scroll Area primitive. The bar floats over the content and reserves no layout space, so full-bleed content is never cropped by a scrollbar gutter, on every OS and browser. The bar is revealed on hover/scroll and hidden at rest. Ported from the legacy shadcn-uikit `ScrollArea`.
+- [Section](./llms/section.md): A titled band that groups cards — or a table — on a page. Four content layouts pick the body shape: one full-width column, a 70/30 split, a three-column card grid, or a flush table that bleeds to the page edges. The header carries a title, optional description, an optional toggle switch, inline extras, and end-aligned actions; an optional bottom divider separates one band from the next. Collapsing is a composition with `AccordionContainer`, the same as `Card`.
+- [Separator](./llms/separator.md): A thin rule that visually and semantically divides content. Built on the Base UI Separator primitive (sets the `separator` role + aria-orientation). Ported from the legacy shadcn-uikit `Separator`; uses the shared divider token.
+- [Stack](./llms/stack.md): A flexbox layout primitive — lay children out in a row or column with configurable gap, alignment, justification, and wrapping. Ported 1:1 from the legacy shadcn-uikit `stack`.
+- [Toolbar](./llms/toolbar.md): A horizontal action row — list actions, an optional overflow control (e.g. a ButtonMenu), and an optional trailing area (a status text, or a selection counter + action) — typically shown above/below a list or table when rows are selected or bulk actions are available. Pure layout — no dedicated token tier; every action is an existing Button/ButtonMenu instance that brings its own tokens. Distinct from FilterSearch/DataTableToolbar (search + filter toolbars): Toolbar is a bulk-action/selection bar, not a filter bar.
+- [Wizard](./llms/wizard.md): The full-page wizard page template — a sticky header band (breadcrumb, title row with the flow's Cancel/Back/Next actions, an optional subtitle, an optional stepper) above a content column capped at 1024px. Layout and slots only: it owns no step index, no navigation, and no button wiring — which actions show on which step is the consuming UI block's decision, the same boundary PageHeader draws around its own actions slot. Mapped to the ui-react Figma "RegionMain" frame (node 10511-61418).
+
+## Navigation
+
+- [Breadcrumb](./llms/breadcrumb.md): Displays a hierarchical navigation path showing the user's current location. A set of composable parts (list, item, link, current page, separator, ellipsis) — the last item is a non-link current page; chevron separators sit between items.
+- [Link](./llms/link.md): An inline text link (semibold) that underlines on hover, with an optional trailing external-link icon. Navigates to an href or composes a router link. Themed by the `--ui-link-*` token tier.
+- [Pagination](./llms/pagination.md): Navigation for paged content — previous / next controls, numbered page links with a current-page marker, and an ellipsis for skipped ranges. Markup-only (no Base UI primitive). Ported from the legacy shadcn-uikit `pagination`.
+- [SidebarPrimary](./llms/sidebar-primary.md): The app-level navigation rail. A set of composable parts (header, content, footer, sections, menu, menu items, extras) that reflows between an expanded (256px) and a collapsed (48px icon rail) state. Menu items carry a `selected` variant for the current route; trailing extras add a shortcut, external-link, or tag affordance. The product logo is consumer-slotted into the header.
+- [SidebarSecondary](./llms/sidebar-secondary.md): The contextual second-level navigation panel that sits beside the primary rail. A set of composable parts (header, content, sections with optional labels, menu, fixed and expandable menu items, level-2 sub-items, extras) that reflows between an expanded (256px) panel and a collapsed (48px) rail. In collapsed mode the section list is replaced by a vertical breadcrumb (parent → separator → current page). Expandable rows disclose a level-2 child list via Base UI Collapsible.
+- [Stepper](./llms/stepper.md): The root of a step sequence. It renders the sequence two ways and lets CSS pick one: on wide viewports a start-aligned, wrapping row of `StepperItem` children; on narrow ones a two-line text summary — "Step 3 of 5: <current step>" and "Next: <next step>" — with no items at all. The switch is a real viewport media query (Tailwind's `lg:`, `min-width: 1024px`), not a JS measurement, so both subtrees are always in the DOM and only one is ever displayed. It owns that layout switch and the summary copy only: the steps, their order, which one is current, and all navigation belong to the application.
+- [StepperItem](./llms/stepper-item.md): One step in a stepper — a consumer-composed avatar marker followed by the step name. `variant` is the step's structural role in the sequence (`current`, `completed`, `future`) and drives the container background, border, and label color; `state` is the interaction look and only changes anything on a completed step. The component owns the container and the label only: the marker is supplied and styled entirely by the caller, and the row layout, the step sequence, its ordering, and navigation belong to `Stepper` and the application.
+- [Tabs](./llms/tabs.md): Switches between related panels of content within the same context. A bordered segmented-control tab group (list, trigger, content) built on the Base UI Tabs primitive. Ported from the legacy shadcn-uikit `Tabs`; themed by the shared semantic tokens (no `--ui-tabs-*` tier yet).
+
+## Overlay
+
+- [DialogWelcome](./llms/dialog-welcome.md): 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.
+- [Tooltip](./llms/tooltip.md): A contextual hint that appears on hover or focus of its trigger and disappears when the interaction ends. Used for supplementary information — not for critical content or actions.
+
+## Overlays
+
+- [Dialog](./llms/dialog.md): A higher-level "recipe" dialog built on top of the DialogRoot primitive parts. A single `variant` prop selects one of seven canned use-cases (default, rename, save changes, reset password, discard changes, accept, read-only) — each with its own title, body copy and footer buttons — plus a legacy `wide` escape hatch (no Figma preset, free-form footer via the `footer` prop) kept for backward compatibility with pre-Figma call sites. `children` overrides the body slot and `hasLoading` shows a `Loading` overlay. Colors, typography, and container/header/footer geometry resolve to the `--ui-dialog-*`/`--ui-footer-*` token tier (see tokens.yaml). In Figma the matching component set is named "DialogDefault"; the code-facing name is `Dialog`.
+- [DialogRoot](./llms/dialog-root.md): 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.
+- [DropdownMenu](./llms/dropdown-menu.md): A menu of actions anchored to a trigger (typically a `ButtonMenu`), opened on demand. Composable parts — trigger, content, group (section), item, shortcut, submenu — built on the Base UI Menu primitive. Themed by the `--ui-button-menu-dropdown-*` token tier from @acronis-platform/tokens-pd.
+- [Popover](./llms/popover.md): A floating panel anchored to a trigger, shown on demand for secondary content or quick actions. Built on the Base UI Popover primitive (positioning, focus management, outside-press / Esc dismissal). Ported from the legacy shadcn-uikit `Popover`; container chrome themed by the `--ui-popover-*` tier, with optional `PopoverBody`/`PopoverFooter` parts for the body-rhythm and default action-row recipe shown in Figma.
+- [Sheet](./llms/sheet.md): A modal side panel anchored to a screen edge — for showing or acting on detailed information without leaving the page. Composable parts (trigger, overlay, content, header, title, close, body, description, footer) on the Base UI Dialog primitive, with a slide transition. Was `Details` in the Vue kit (re-exported under `Details*` aliases). Initial version ported from the legacy shadcn-uikit `Sheet`; design reconciliation against Figma (Cyber-Compliance node 3442-31542) is pending.