@acronis-platform/ui-react 5.5.9 → 6.0.0

package/dist/llms/chart-state.md

@@ -1,6 +1,6 @@
 # ChartState
 
-> 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.
+> Shared loading / empty / warning / error / number visuals for a chart slot. Empty, warning, and error use the Breakpoints visual treatment: a 64px status circle with a 24px glyph and centered message. Number shows a centered KPI value; loading uses the shared spinner. Consumers select the state and may localize its content through `description`. Distinct from `WidgetPlaceholder`, which is the composable skeleton for a non-chart widget.
 
 **Status:** draft · **Category:** data-display · **Since:** v0.58.0
 
@@ -14,190 +14,107 @@ import { ChartState } from '@acronis-platform/ui-react'
 
 ```tsx
 <ChartState state="loading" />
-<ChartState state="empty" variant="bar" description="No results for the selected range" />
-<ChartState
-  state="error"
-  action={<Button variant="ghost" onClick={refetch}>Try again</Button>}
-/>
+<ChartState state="empty" description={t('chart.noData')} />
+<ChartState state="warning" description={t('chart.partialData')} />
+<ChartState state="error" description={t('chart.loadError')} />
+<ChartState state="number" description="0 GB" />
 ```
 
-A shared loading / empty / error placeholder for the chart types. Render it in
-place of a chart — inside the same sized slot — while data is loading, when
-there is nothing to plot, or when the fetch failed.
+A shared visual state for one chart slot. Use it while chart data is loading,
+missing, incomplete, or has failed, or when a KPI should show its numeric empty
+value. Empty, warning, and error share the Breakpoints state circles; number
+uses the centered disabled-style KPI value; loading uses the shared spinner.
 
-> **Design-pending v1.** Ported from the Figma InputSelect dropdown states (the
-> reference node for this task) and kept visually in step with the shipped
-> `InputSelectStatus`. There is no `--ui-chart-*` token tier yet, so it themes
-> from existing semantic tokens directly.
-
-## When to use
-
-- A chart cannot render yet (data in flight), has no data to plot, or failed to
-  load — swap the chart for the matching `ChartState`.
-- You want the same placeholder across every chart type, rather than each chart
-  hand-rolling its own.
-
-## When not to use
-
-- A full-page empty state (illustration, title, description, primary action) —
-  use the larger `Empty` component instead.
-- A bare loading indicator with no surrounding message — use `Spinner` directly.
-
-## Example
+Consumers select the semantic state and pass localized or context-specific
+content through `description`. `ChartState` does not infer the state from data.
 
 ```tsx
-import { ChartState, ChartContainer, Button } from '@acronis-platform/ui-react';
-
-function Sales({ status, data, config, refetch }) {
-  if (status === 'loading') return <ChartState state="loading" />;
-  if (status === 'error')
-    return (
-      <ChartState
-        state="error"
-        action={
-          <Button variant="ghost" onClick={refetch}>
-            Try again
-          </Button>
-        }
-      />
-    );
-  if (!data.length) return <ChartState state="empty" />;
-
-  return (
-    <ChartContainer config={config} className="h-[300px] w-[500px]">
-      {/* …the chart… */}
-    </ChartContainer>
-  );
-}
+import { ChartState } from '@acronis-platform/ui-react';
+
+if (status === 'loading') return <ChartState state="loading" />;
+if (status === 'warning')
+  return <ChartState state="warning" description={t('chart.partialData')} />;
+if (status === 'error')
+  return <ChartState state="error" description={t('chart.loadError')} />;
+if (isEmptyKpi) return <ChartState state="number" description="0 GB" />;
+if (!data.length)
+  return <ChartState state="empty" description={t('chart.noData')} />;
 ```
 
-The three states share one compact layout: a leading glyph (spinner / inbox /
-warning) over a centered label. Pass `description` to override a state's default
-label, and `action` to add a retry affordance to the error state. Long unbroken
-error descriptions (CTI paths, API URLs) wrap at word boundaries and scroll
-vertically when they exceed the slot height.
+`ChartState` fills the chart's slot. It does not own the containing widget card
+or dashboard composition; see `ChartWidget` for a single chart card.
 
 ## Props
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `state` | `'loading' | 'empty' | 'error'` | — | yes | Which placeholder to show. Drives the leading artwork and the default label (loading → spinner + "Data is loading…"; empty → variant silhouette or no artwork + "No data found"; error → warning glyph + "Something went wrong"). |
-| `variant` | `'area' | 'bar' | 'line' | 'donut' | 'radial' | 'funnel' | 'radar' | 'sankey' | 'scatter' | 'treemap' | 'table' | 'text'` | — | no | Which chart the slot holds. The `empty` state then draws that type's silhouette instead of the generic inbox glyph — the design defines one per chart type. `donut` and `radial` share a ring. Ignored by `loading` and `error`, which share one treatment. |
-| `description` | `ReactNode` | — | no | Text shown below the illustration or glyph. Defaults to `"Data is loading…"` / `"No data found"` / `"Something went wrong"` based on `state`. Pass a value to override for any state. |
-| `action` | `ReactNode` | — | no | Trailing action rendered for the `error` state only (e.g. a "Try again" button). |
+| `state` | `'loading' | 'empty' | 'warning' | 'error' | 'number'` | — | yes | Which state to show. Loading uses the shared spinner; empty, warning, and error use the shared circular status icon; number shows a centered disabled-style KPI value. Error is an assertive alert; other states are polite status messages. |
+| `description` | `ReactNode` | — | no | Localized or context-specific content. For `number`, this is the numeric readout. Defaults to "Data is loading…", "No data found", "Data may be incomplete", "Something went wrong", or "0". |
 
 ## Behavior
 
 ### Rendering per state
 
 - **Given** `state="loading"`, **when** rendered, **then** it shows the shared
-  `Spinner` (lg) above the label "Data is loading…" and announces the label via
-  its `role="status"` live region (no `aria-busy`, which could defer that
-  announcement).
-- **Given** `state="empty"`, **when** rendered, **then** it shows the label
-  "No data found" (no artwork unless a `variant` is passed).
-- **Given** `state="error"`, **when** rendered, **then** it shows the warning
-  glyph above the label "Something went wrong" and announces as an alert.
-
-### Label override
-
-- **Given** a `description` prop, **when** rendered in any state, **then** the
-  supplied text replaces that state's default label.
-
-### Action
-
-- **Given** an `action` node, **when** `state="error"`, **then** the action is
-  rendered after the label (e.g. a "Try again" button).
-- **Given** an `action` node, **when** `state` is `loading` or `empty`, **then**
-  the action is **not** rendered.
-
-### Layout
-
-- **Given** any state, **when** placed in a sized slot (the same box a chart
-  would occupy), **then** the block fills it (`size-full`) with a `min-h-32`
-  floor so it stays legible in an unsized parent.
-- **Given** `state="loading"` or `state="empty"`, **when** rendered, **then**
-  the content is vertically centered in the slot (`justify-center`).
-- **Given** `state="error"`, **when** the description is short enough to fit,
-  **then** the content is vertically centered via auto margins (`my-auto`).
-- **Given** `state="error"` with a long unbroken `description` (e.g. CTI error
-  paths, API URLs), **when** the text overflows the slot height, **then** the
-  auto margins collapse and the icon stays anchored at the top, with vertical
-  scroll (`overflow-y: auto`) so the full diagnostic text is accessible. Long
-  unbroken strings wrap at word boundaries (`overflow-wrap: break-word`),
-  breaking mid-word only when a single token cannot fit on one line.
-  `overflow-x: hidden` prevents any horizontal scrollbar.
-
-### Per-type empty states
-
-`empty` is the one state the design draws per chart type: an area silhouette for
-an area chart, a ring for a donut, a funnel for a funnel. An empty widget then
-still says what it _would_ have shown, which a single generic glyph can't.
-
-`variant` selects it. `donut` and `radial` share one ring — a radial-bar widget
-with no data has nothing to tell it apart. Without a `variant` the empty state
-shows no artwork — just the text.
-
-The geometry is exported from the Figma instances rather than redrawn, and every
-path is `currentColor`: the tone is set once on the container, so brand and theme
-overrides reach the artwork. Two of the eleven silhouettes use a second, fainter
-tone (the table and metric-list ones tint their header row darker than the body
-rows); that hierarchy is kept as `fill-opacity` on the same colour rather than a
-second token.
-
-The caption is **one line, in one style**. Figma styles it `body/default` on
-`text/onSurface/primary` — 14/24, centred, _not_ muted — which is what the root
-already applies, so the description and the fallback status label read
-identically. For a per-type empty state that line is the `description`: the mockups draw the silhouette over "Widget description" with no
-status label, because the artwork already says "no data" and the sentence worth
-the space is what the widget _would_ show. With no `description` it falls back to
-the status label, so a caller that only sets `variant` still reads sensibly.
-
-`loading` and `error` deliberately keep one shared treatment — the design only
-redesigned `empty`.
-
-### Not `WidgetPlaceholder`
-
-Two components, two jobs, and they are not interchangeable:
-
-- **`ChartState`** is the placeholder _inside_ a chart's slot. It fills whatever
-  gives the slot its height, renders one of three states, and is what a chart
-  widget swaps in for its plot.
-- **`WidgetPlaceholder`** is a composable skeleton with its own header, footer
-  and action parts, plus an `interactive` affordance — for a dashboard widget
-  that isn't a chart, or a whole tile that is still being set up.
-
-`WidgetPlaceholder` predates the per-type empty states and is used by consuming
-MFEs, so it stays.
+  large `Spinner` and the default message "Data is loading…".
+- **Given** `state="empty"`, **when** rendered, **then** it shows the neutral
+  circle with the `CircleMinusGray` glyph and the default message "No data
+  found".
+- **Given** `state="warning"`, **when** rendered, **then** it shows the warning
+  circle with the `TriangleWarningYellow` glyph and the default message "Data
+  may be incomplete".
+- **Given** `state="error"`, **when** rendered, **then** it shows the critical
+  circle with the `DiamondWarningRed` glyph and the default message "Something
+  went wrong".
+- **Given** `state="number"`, **when** rendered, **then** it shows the centered
+  disabled-style numeric value "0" without a state icon.
+- **Given** empty, warning, or error, **when** rendered, **then** the group is
+  centered and uses a 64px state circle, a 24px glyph, 12px separation, and
+  centered 14px / 24px text.
+
+### Copy
+
+- **Given** a `description`, **when** rendered in any state, **then** the supplied
+  content replaces that state's fallback message. Consumers provide localized
+  or context-specific copy.
+
+### Layout and overflow
+
+- **Given** any state, **when** placed in a chart slot, **then** the block fills
+  the slot without forcing a minimum height beyond its content.
+- **Given** loading, empty, or warning, **when** rendered, **then** the content
+  is centered in the slot.
+- **Given** `state="error"` with a short message, **when** rendered, **then**
+  the icon and message are vertically centered.
+- **Given** an error with a long message, **when** it exceeds the slot height,
+  **then** the icon remains fully visible, the state scrolls vertically, and
+  unbroken strings wrap within the available width.
+
+### Composition boundary
+
+`ChartState` controls the state visuals inside one chart slot. It does not set
+the chart-widget card border or arrange a group of widgets; those belong to
+their respective component or consuming application.
 
 ## Accessibility
 
-- The root is a **live region** so a screen reader announces the state change
-  when a chart swaps its content in:
-  - `loading` / `empty` → `role="status"` with `aria-live="polite"`.
-  - `error` → `role="alert"` with `aria-live="assertive"`.
-- On `loading` the shared `Spinner` is rendered `aria-hidden` so the root's own
-  live region (with the label) announces once, rather than the Spinner's
-  `role="status"` + sr-only "Loading…" nesting inside it and double-announcing.
-- The root does **not** carry `aria-busy`. It is itself the live region, and some
-  screen readers defer announcing a busy region's content until `aria-busy`
-  clears; because this placeholder is unmounted (swapped for the chart) rather
-  than un-busied, a busy flag would risk swallowing the "Data is loading…"
-  announcement. Put `aria-busy` on the chart-slot **container** instead if a busy
-  signal is needed (same guidance as `Skeleton`).
-- The live-region attributes (`role` / `aria-live`) are applied after the prop
-  spread, so the state's a11y contract is not clobbered by a consumer-passed
-  attribute.
-- The label text is a real `<p>`, so the state message is always in the
-  accessible tree — the glyph is decorative and does not need its own label.
-- **Do not rely on the glyph color alone** to convey the state — the label
-  carries the meaning. Icon colors (`--ui-glyph-on-status-info` /
-  `--ui-glyph-on-status-warning`) and the label (`--ui-text-on-surface-primary`)
-  resolve to semantic tokens that meet contrast in both themes.
-- If the error state offers a retry, pass an actual interactive control as
-  `action` (a `Button`) so it is focusable and keyboard-operable.
+- The root is the live region: loading, empty, warning, and number use
+  `role="status"` with `aria-live="polite"`; error uses `role="alert"` with
+  `aria-live="assertive"`.
+- The root live-region attributes are applied after the prop spread, so the
+  selected state's announcement semantics cannot be overwritten by consumer
+  props.
+- The loading Spinner and state glyphs are decorative. The displayed content
+  supplies the state meaning independently of icon color.
+- The root does not carry `aria-busy`. This placeholder is unmounted when the
+  chart replaces it, and some screen readers defer announcements inside a busy
+  region. Put `aria-busy` on the chart-slot container if a busy signal is needed.
+- Long error text can scroll vertically, and long unbroken strings wrap within
+  the available width.
 
 ## Contrast
 
-Label and glyph colors resolve to semantic `--ui-*` tokens that meet contrast on
-the surface in both light and dark themes.
+Message text uses `--ui-text-on-surface-primary`. The state glyphs are the
+multi-color design assets, placed on semantic neutral, warning, and critical
+background tokens. The textual message communicates meaning without relying on
+color.

package/dist/llms/chart-widget.md

@@ -1,6 +1,6 @@
 # ChartWidget
 
-> 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.
+> 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 / warning / error / number state — and re-implements nothing else. The consumer selects the state explicitly; the widget does not infer it from chart data. 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.
 
 **Status:** draft · **Category:** data-display · **Since:** v2.1.0
 
@@ -35,10 +35,11 @@ readout, then the plot. `ChartWidget` is that composition — and only that.
 
 ## What it adds
 
-One thing a `Card` legitimately doesn't know about: **what the body shows while
-there is no plot.** `state="loading" | "empty" | "error"` renders `ChartState` in
-place of the chart, and `error` also gives the Card its error border — one prop,
-not two.
+One thing a `Card` legitimately doesn't know about: **what the body shows for
+an explicitly selected state.** `state="loading" | "empty" | "warning" |
+"error" | "number"` renders `ChartState` in place of the metric and chart. The
+consumer chooses the state; the widget does not infer it from data. Card chrome
+remains consistent for each state.
 
 ## What it doesn't add
 
@@ -63,7 +64,7 @@ the rest of the card. See `behavior.md`.
 | ------------------ | ------------------------------------------------------------------ |
 | `index.yaml`       | Identity, category, status, `since`.                               |
 | `api.yaml`         | The prop contract and the per-framework adapters.                  |
-| `anatomy.yaml`     | Parts, the schematic, and the four body states.                    |
+| `anatomy.yaml`     | Parts, the schematic, and the five widget states.                  |
 | `behavior.md`      | Composition, how the height reaches the plot, state, localization. |
 | `accessibility.md` | Roles, the placeholder's live region, header controls.             |
 | `tokens.yaml`      | The `--ui-*` tokens the widget references.                         |
@@ -87,12 +88,10 @@ chart.
 | `header` | `CardHeaderProps` | — | no | The card header, forwarded verbatim to `CardHeader` — `title`, `description`, `extras` (a filter chip), `actions` (the ⋯ menu), `isDraggable`, `isSwitchable`, `hasAvatar`, `hasRename`, `isCollapsible`. Omit for a header-less widget. |
 | `orientation` | `'vertical' | 'horizontal'` | `vertical` | no | How the `metric` and plot are arranged inside the card body. `vertical` (default) — metric above the plot, full width; the metric takes its natural height and the plot fills the rest. `horizontal` — metric and plot side by side, each `flex-1`; use for compact (sm/288px) widgets where vertical space is at a premium. |
 | `metric` | `ReactNode` | — | no | The readout beside or above the plot (depending on `orientation`), typically a `Metric`. |
-| `variant` | `'area' | 'bar' | 'line' | 'donut' | 'radial' | 'funnel' | 'radar' | 'sankey' | 'scatter' | 'treemap' | 'table' | 'text'` | — | no | Which chart the widget holds. Only used while `state="empty"`, to pick the silhouette for that chart type. Forwarded to `ChartState`. |
-| `state` | `'loading' | 'empty' | 'error'` | — | no | Renders `ChartState` in place of the plot, keeping the header. `error` additionally gives the Card its error border. |
-| `stateDescription` | `ReactNode` | — | no | Text below the placeholder illustration or glyph. Forwarded to `ChartState` as `description`. Defaults to the per-state built-in ("Data is loading…" / "No data found" / "Something went wrong"). |
-| `stateAction` | `ReactNode` | — | no | Trailing action on the `error` placeholder — e.g. a retry button. |
+| `state` | `'loading' | 'empty' | 'warning' | 'error' | 'number'` | — | no | Renders `ChartState` in place of the metric and plot, keeping the header. The consumer selects the state; no state is inferred from the data. Card chrome remains consistent for all states. |
+| `stateDescription` | `ReactNode` | — | no | Localized or context-specific content shown by `ChartState`. For `number`, pass the numeric value and unit. Defaults to per-state fallback content, including `0` for `number`. |
 | `bodyClassName` | `string` | — | no | Class for the card body. Rarely needed — the body already fills the card. For the case where neither the grid nor the content gives a height, e.g. a placeholder-only widget outside a sized cell. |
-| `children` | `ReactNode` | — | no | The chart. Replaced by the placeholder while `state` is set. |
+| `children` | `ReactNode` | — | no | The selected state replaces this chart and the metric while `state` is set. |
 | `render` | `useRender.RenderProp` | — | no | Replace the rendered `<div>` with another element or component (Base UI composition), forwarded to `Card`. How a dashboard gives each widget a landmark role — `render={<section aria-label="Sessions" />}` — which is the one thing the widget can't infer for itself. |
 
 ## Behavior
@@ -142,21 +141,23 @@ design constraint, and hard-coding them would have fought the grid.
 
 ### State
 
-`state` renders `ChartState` **instead of** `children`. The header stays.
+The consumer selects `state` explicitly; the widget does not infer it from chart
+data. When set, `ChartState` replaces both the `metric` and `children`. The
+header stays. The `number` state shows a centered numeric KPI value.
 
-`state="error"` also maps to `Card`'s `hasError`, so the error border and the
-error placeholder come from one prop. A caller can't get one without the other,
-which is what the mockups draw.
+The card surface and border remain the same for loading, empty, warning, error,
+and number. State-specific visuals are contained within `ChartState` in the
+body.
 
-`ChartState` owns the live-region contract (`role="status"` for loading/empty,
-`role="alert"` for error), so the announcement follows the placeholder rather
-than being re-declared on the widget.
+`ChartState` owns the live-region contract (`role="status"` for loading, empty,
+warning, and number; `role="alert"` for error), so the announcement follows
+the state rather than being re-declared on the widget.
 
 ### Localization
 
-Every string is the caller's: the header's `title` / `description`, the metric's
-own labels, `stateDescription`, and the label inside `stateAction`. The only
-literals are `ChartState`'s per-state defaults, which `stateDescription` overrides.
+The header's `title` / `description`, the metric's labels, and
+`stateDescription` can be supplied by the consumer. The `stateDescription`
+prop lets applications localize or contextualize the state content.
 
 ## Accessibility
 
@@ -187,7 +188,7 @@ name, so a chart inside should not repeat it in its own accessible name.
 ## The placeholder is the live region
 
 While `state` is set, `ChartState` is the live region — `role="status"`
-(`aria-live="polite"`) for loading and empty, `role="alert"`
+(`aria-live="polite"`) for loading, empty, warning, and number; `role="alert"`
 (`aria-live="assertive"`) for error. The widget deliberately does **not** add
 `aria-busy` around it: the placeholder is unmounted and replaced by the plot
 rather than un-busied, and some assistive tech defers announcing a busy region's
@@ -203,7 +204,8 @@ switch, rename button and collapse trigger each take a label prop with a
 default, and the `actions` slot is the caller's own control (an icon button
 needs its own `aria-label` — the mockups' ⋯ menu has no visible text).
 
-## Colour is not the only signal
+## State meaning
 
-`state="error"` changes the card's border colour, but the placeholder also
-carries an icon and a message, so the error is not conveyed by colour alone.
+The widget card border stays consistent across states. `ChartState` supplies a
+state icon and message (or the numeric KPI value), so meaning does not rely on
+color alone.

package/dist/llms/dialog-root.md

@@ -58,19 +58,19 @@ decision. Composable from parts; built on the Base UI Dialog 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). |
+| Part                             | Element (default)  | Purpose                                                                                  |
+| -------------------------------- | ------------------ | ---------------------------------------------------------------------------------------- |
+| `DialogRoot`                     | —                  | Root; owns the open state (Base UI `Root`).                                              |
+| `DialogTrigger`                  | `button`           | Opens the dialog.                                                                        |
+| `DialogContent`                  | `div[role=dialog]` | The portaled popup (+ overlay); centered by default, or top-aligned via `verticalAlign`. |
+| `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
 
@@ -79,6 +79,12 @@ decision. Composable from parts; built on the Base UI Dialog primitive.
 `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).
 
+## Placement
+
+`DialogContent` takes a `verticalAlign` prop: `center` (default) centers the
+popup in the viewport; `top` pins it 48px from the top edge, horizontally
+centered, keeping its content height (still capped at `100dvh - 96px`).
+
 ## Example (internal usage only)
 
 ```tsx
@@ -124,6 +130,7 @@ import { Button } from '../button';
 | `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). |
+| `verticalAlign` | `'center' | 'top'` | `'center'` | no | Vertical placement of the popup (on the content part). `center` (the default) centers it in the viewport; `top` pins it 48px from the top edge of the viewport instead, keeping its content height. A ui-react-only extension beyond the Figma contract, like `size="large"`. |
 | `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. |
 
@@ -205,6 +212,26 @@ Scenario: Modal locks the background (default)
   inside the dialog until it closes
 ```
 
+### Placement
+
+```gherkin
+Scenario: The popup is centered by default
+  Given a DialogRoot whose DialogContent has no verticalAlign (or
+  verticalAlign = "center")
+  When it opens
+  Then the popup is centered in the viewport, horizontally and vertically
+```
+
+```gherkin
+Scenario: verticalAlign = "top" pins the popup near the top edge
+  Given a DialogRoot whose DialogContent has verticalAlign = "top"
+  When it opens
+  Then the popup's top edge sits 48px below the top of the viewport
+  And it stays horizontally centered
+  And it keeps its content height (still capped at 100dvh - 96px), leaving
+  the viewport below it empty
+```
+
 ## Accessibility
 
 DialogRoot leans on the Base UI Dialog primitive for its modal semantics,

package/dist/llms/dialog.md

@@ -97,7 +97,7 @@ name is `Dialog`.
 
 | Part              | Element (default)  | Purpose                                              |
 | ----------------- | ------------------ | ---------------------------------------------------- |
-| `container`       | `div[role=dialog]` | The portaled, centered popup card.                   |
+| `container`       | `div[role=dialog]` | The portaled popup card; centered (or top-aligned).  |
 | `header`          | `div`              | Top bar; title + close button.                       |
 | `title`           | `h2`               | Accessible dialog name (`aria-labelledby`).          |
 | `close-button`    | `button`           | Icon button that dismisses the dialog.               |
@@ -146,6 +146,11 @@ import { Dialog } from '@acronis-platform/ui-react';
   <p>Body-only content — no title bar, no close button.</p>
 </Dialog>;
 
+// Pin the popup 48px from the top of the viewport instead of centering it
+<Dialog variant="default" verticalAlign="top" open>
+  <p>Any custom body content.</p>
+</Dialog>;
+
 // Legacy wide variant — free-form footer, kept for backward compatibility
 import { Button, DialogClose } from '@acronis-platform/ui-react';
 
@@ -185,6 +190,7 @@ import { Button, DialogClose } from '@acronis-platform/ui-react';
 | `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. `'trap-focus'` keeps the focus trap but allows background interaction. |
 | `size` | `'sm' | 'large'` | `'sm'` | no | Popup max-width (forwarded to the underlying content). Defaults to `sm` (512px, the Figma-defined size), or to `large` (832px) when `variant` is `wide`. `large` predates the Figma node and has no design token — a legacy backward-compatibility size, not a design-system width scale. |
+| `verticalAlign` | `'center' | 'top'` | `'center'` | no | Vertical placement of the popup (forwarded to the underlying content). `center` (the default) centers it in the viewport; `top` pins it 48px from the top edge of the viewport instead, keeping its content height. A ui-react-only extension beyond the Figma contract, like `size="large"`. |
 | `portal` | `boolean` | `true` | no | Render the content inside a portal (forwarded to the underlying content). Required for correct stacking; disable only when supplying your own portal ancestor. |
 | `keepMounted` | `boolean` | — | no | Keep the content mounted while closed (forwarded to the underlying content's portal). |
 
@@ -241,6 +247,25 @@ Scenario: The wide variant is a free-form escape hatch
   secondary/primary pair
 ```
 
+### Placement
+
+```gherkin
+Scenario: The popup is centered by default
+  Given a Dialog with no verticalAlign (or verticalAlign = "center")
+  When it opens
+  Then the popup is centered in the viewport, horizontally and vertically
+```
+
+```gherkin
+Scenario: verticalAlign = "top" pins the popup near the top edge
+  Given a Dialog with verticalAlign = "top"
+  When it opens
+  Then the popup's top edge sits 48px below the top of the viewport
+  And it stays horizontally centered
+  And it keeps its content height (still capped at 100dvh - 96px), leaving
+  the viewport below it empty
+```
+
 ### Body slot
 
 ```gherkin

package/dist/llms.txt

@@ -1,6 +1,6 @@
 # Acronis UI Kit for React — LLM Reference
 
-> `@acronis-platform/ui-react` v5.5.9
+> `@acronis-platform/ui-react` v6.0.0
 
 Machine-readable component reference compiled from framework-agnostic specs.
 Each entry links to a self-contained markdown file with props, behavior,
@@ -34,8 +34,8 @@ accessibility notes, and usage examples.
 - [CardWidgetCarousel](./llms/card-widget-carousel.md): A horizontal scroll carousel that holds a row of action-widget cards and exposes floating Previous/Next chevron buttons to navigate the view. The carousel shell manages scroll; the individual cards are passed as `children`. Ships with a companion `CardWidget` component (same barrel) — a status-colored card with icon box, optional skeleton, and footer slot.
 - [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.
+- [ChartState](./llms/chart-state.md): Shared loading / empty / warning / error / number visuals for a chart slot. Empty, warning, and error use the Breakpoints visual treatment: a 64px status circle with a 24px glyph and centered message. Number shows a centered KPI value; loading uses the shared spinner. Consumers select the state and may localize its content through `description`. Distinct from `WidgetPlaceholder`, which is the composable skeleton for a non-chart widget.
+- [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 / warning / error / number state — and re-implements nothing else. The consumer selects the state explicitly; the widget does not infer it from chart data. 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).