@d4gger/design-system 3.0.1 → 4.0.0

package/dist/docs/components/config-drawer.md

@@ -4,7 +4,7 @@ status: canonical
 category: Foundations
 archetype: composite
 depends_on:
-  - Sheet
+  - Drawer
   - IconButton
   - Icon
   - SegmentedControl
@@ -18,205 +18,106 @@ depends_on:
 
 # ConfigDrawer
 
-> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+> Source of truth: package source; this spec mirrors its public contract.
 
 ## Purpose
 
-A right-anchored preferences drawer that exposes the live theme controls: appearance mode, accent color, gray palette, radius, density, and scaling. `ConfigDrawer` is the editor half of the theme configuration surface; `ThemePanel` is the read-only inspector. The two share a design language but solve different problems. `ConfigDrawer` reads and writes the active `ThemeProvider` context, so it must be rendered inside a `ThemeProvider` tree.
+One preferences drawer inside ThemeProvider, exposing Theme, Accent, Gray,
+Radius, Density, Scaling and Panel BG. Values and persistence belong to
+ThemeProvider; the drawer supplies their controls. Default side is right.
 
 ## Anatomy & slots
 
-**Parent:** `ConfigDrawer`. The root is a `Sheet` (`Sheet.Root` + `Sheet.Trigger` + `Sheet.Content side="right"`). The drawer is a single function component, not a compound; the consumers do not import any `ConfigDrawer.<Slot>` parts. The internal layout is a vertical `Flex` of `SettingRow` instances separated by `Separator`s.
-
-**Internal regions:**
-
-| Region | Element | Renders | Notes |
-|---|---|---|---|
-| Trigger | `Sheet.Trigger` rendered as `IconButton` (default) or consumer-supplied `trigger` | `dsx-config-drawer__trigger` (class is added when the default trigger renders) | Default trigger is an `IconButton variant="ghost" size="md"` with `aria-label="Open preferences"` and a `settings` `Icon` (size `md`). Consumers can pass a `trigger` prop to replace the default. |
-| Header | `Sheet.Header` + `Sheet.Title` | (inherits `Sheet` styles) | "Preferences" title. |
-| Body | `Flex direction="column" gap="lg"` | `dsx-config-drawer__body` | Scrollable column of `SettingRow` + `Separator` regions. |
-| SettingRow | `Flex direction="row" justify="between" align="center" gap="md"` | `dsx-config-drawer__row` | A label / description / control triplet. The label is a `Label` element; the description (when present) is a `Text variant="label-small" tone="muted"`; the control is whatever the consumer passes as `children`. |
-| SettingRow info | `Flex direction="column" gap="1"` | `dsx-config-drawer__row-info` | The left column of the row, containing the `Label` and the description. |
-| SettingRow control wrapper | `<div>` | `dsx-config-drawer__row-control` | The right column of the row, wrapping the control. |
-| Accent preview swatch | `<span aria-hidden="true">` | `dsx-config-drawer__accent-swatch` + `data-tier` | Non-interactive preview of each accent tier. It does not write `data-accent-color`, because the swatch represents a color value rather than consuming theme scope. |
-| Scaling input (specific) | `NumberInput` | `dsx-config-drawer__scaling-input` | The scaling control. Sized to `7ch` so the percentage fits without breaking the row rhythm. |
-
-**Internal layout:**
-
-- The default trigger is a ghost `IconButton` with a `settings` icon. Passing the `trigger` prop replaces it entirely.
-- The body is a single scrollable column. Each `SettingRow` is a `flex-direction: row` with `justify-content: space-between`, so the label and control sit on opposite ends of the row.
-- The six default rows (Theme, Accent, Gray, Radius, Density, Scaling) are separated by `Separator` components from the package. The order is fixed and reflects the dependency direction: appearance first, then accent, then gray, then radius, then density, then scaling.
-- Each row's control is a `SegmentedControl` (for the categorical tokens) or a `NumberInput` (for the scaling percentage). The control is wrapped in a `<div class="dsx-config-drawer__row-control">` so it stays right-aligned without leaking the `gap` into the control itself.
+Flat export composing lazily loaded Drawer, Trigger, Content, Header, Title and
+Description. No ConfigDrawer compound slots. Default trigger is an inline ghost
+IconButton size md, named “Open preferences”, with settings Icon. The host owns
+positioning. Title is “Preferences”; VisuallyHidden wraps the DrawerDescription.
+Body composes Flex, Label, Text, SegmentedControl, NumberInput and Separator.
 
 ## Props contract
 
-**Root props (`ConfigDrawer`):**
-
-| Prop | Type | Default | Required | Description | Responsive |
-|---|---|---|---|---|---|
-| `open` | `boolean` | `undefined` | no | Controlled open state. Pass alongside `onOpenChange` to own the open flag. | no |
-| `defaultOpen` | `boolean` | `false` | no | Uncontrolled initial open state. | no |
-| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Callback fired when the underlying `Sheet` open state changes. | no |
-| `trigger` | `ReactNode` | default `IconButton` (see above) | no | Custom trigger element. Rendered through `Sheet.Trigger asChild`. | no |
-
-The root does not accept `asChild` directly; consumers can swap the host element by passing a `trigger` or by wrapping the rendered output themselves. The internal `Sheet.Content` is locked to `side="right"`; left-side drawers are out of scope for this component.
-
-**SettingRow props (internal, not exported):**
-
-| Prop | Type | Default | Required | Description | Responsive |
-|---|---|---|---|---|---|
-| `label` | `string` | (none) | **yes** | The label rendered as a `Label` element on the left. | no |
-| `description` | `string` | `undefined` | no | Optional helper text rendered under the label as a muted `Text`. | no |
-| `children` | `ReactNode` | (none) | **yes** | The control rendered on the right (typically a `SegmentedControl` or `NumberInput`). | no |
-
-`SettingRow` is an internal helper; consumers do not compose their own rows. The six default rows are wired inside the component.
-
-## CSS class contract
-
-**Root class:** none at the component level. The component composes `Sheet` (which owns the panel chrome) and the `dsx-config-drawer__*` classes below.
+| Prop | Type | Default | Description | Responsive |
+|---|---|---|---|---|
+| open | boolean | undefined | Controlled open state. | no |
+| onOpenChange | (open: boolean) => void | undefined | Open-state callback. | no |
+| defaultOpen | boolean | false | Uncontrolled initial state. | no |
+| trigger | ReactNode | inline IconButton | Custom trigger via DrawerTrigger asChild. | no |
+| side | top / right / bottom / left | right | Passed to Drawer direction. | no |
+| children | ReactNode | undefined | Host content after built-in rows. | no |
 
-**Slot classes:**
+Categorical controls are SegmentedControl type single, size sm:
 
-| Slot / region | Class | CSS file |
+| Row | Accessible name | Choices |
 |---|---|---|
-| Body | `dsx-config-drawer__body` | `config-drawer.css` |
-| Default trigger | `dsx-config-drawer__trigger` | (added at the className level on the default `IconButton`; no rule in the CSS file currently) |
-| Setting row | `dsx-config-drawer__row` | `config-drawer.css` |
-| Setting row info column | `dsx-config-drawer__row-info` | `config-drawer.css` |
-| Setting row control wrapper | `dsx-config-drawer__row-control` | `config-drawer.css` |
-| Accent preview swatch | `dsx-config-drawer__accent-swatch` | `config-drawer.css` |
-| Scaling `NumberInput` | `dsx-config-drawer__scaling-input` | `config-drawer.css` |
+| Theme | Theme mode | Light / Dark / System |
+| Accent | Accent color | Rift / Warp / Ray / Astral / Spark |
+| Gray | Gray color | Auto / Neutral |
+| Radius | Border radius | None / Small / Medium / Large / Full |
+| Density | Density | Comfortable / Compact |
+| Scaling | Scaling percentage | NumberInput, 90–110%, rounded to steps of 5 |
+| Panel BG | Panel background | Translucent / Solid |
 
-**Responsive behavior:**
+SettingRow is internal: label, optional description, children. Visible labels
+are visual cues; each control has its own programmatic name.
 
-- The component does not write `@media` rules. On narrow viewports the consumer can swap in a different sheet side or a full-screen `Sheet`; `ConfigDrawer` is fixed to a right-anchored panel.
-
-**Reduced motion:**
+## CSS class contract
 
-- The component itself does not animate. Open / close transitions on the wrapping `Sheet` are owned by the `Sheet` component and respect `prefers-reduced-motion` through the standard `MOTION_TRANSITIONS.sheet` preset.
+| Region | Class |
+|---|---|
+| Body | dsx-config-drawer__body |
+| Row | dsx-config-drawer__row |
+| Information | dsx-config-drawer__row-info |
+| Control | dsx-config-drawer__row-control |
+| Swatch | dsx-config-drawer__accent-swatch |
+| Scaling | dsx-config-drawer__scaling-input |
+
+Rows always wrap. Information has min-width 0; controls have min-width 0 and
+max-width 100%. Long categorical groups retain SegmentedControl's own horizontal
+scrolling, including keyboard reveal. Drawer bounds and vertical scrolling use
+the shared Drawer contract. No package width breakpoints.
 
 ## Token mapping
 
-Every CSS value the component paints is a `var(--dsx-*)` token.
+| Property | Token |
+|---|---|
+| Body gap / padding | --dsx-space-lg / --dsx-space-md |
+| Row gap / minimum height | --dsx-space-md / --dsx-size-lg |
+| Information gap | --dsx-space-2xs |
+| Swatch size / gap / radius | --dsx-space-sm / --dsx-space-xs / --dsx-radius-full |
+| Swatch fill | --dsx-color-accent-{rift,warp,ray,astral,spark}-9 |
+| Scaling width | 7ch |
 
-| Property | Token | Role |
-|---|---|---|
-| Body gap | `var(--dsx-space-lg)` | Vertical gap between rows |
-| Body padding | `var(--dsx-space-md) 0` | Vertical padding around the body |
-| Body overflow | `auto` | Vertical scroll when content overflows |
-| Row min-height | `var(--dsx-size-lg)` | Min hit target |
-| Row gap | `var(--dsx-space-md)` | Horizontal gap between info and control |
-| Row info gap | `var(--dsx-space-2xs)` | Vertical gap inside the info column |
-| Accent preview size | `var(--dsx-space-sm)` | Square preview swatch dimensions |
-| Accent preview spacing | `var(--dsx-space-xs)` | Gap between the preview and tier label |
-| Accent preview radius | `var(--dsx-radius-full)` | Circular preview shape |
-| Accent preview fill | `var(--dsx-runtime-accent-{rift,warp,ray}-9)` | Exact value represented by each theme choice |
-| Scaling input width | `7ch` | Fixed width for the percentage `NumberInput` |
-
-The default trigger is an `IconButton`; its visual contract is owned by `IconButton`. The row labels use the `Label` component; their visual contract is owned by `Label`. The segmented controls use the `SegmentedControl` component; their visual contract is owned by `SegmentedControl`.
+Controls, separators and panel chrome retain their own component token contracts.
 
 ## Motion contract
 
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| Sheet open / close | inherited from `Sheet` (`MOTION_TRANSITIONS.sheet`) | sheet preset | reduced |
+Inherited Drawer motion uses MOTION_TRANSITIONS.drawer and reduced fallback.
+ConfigDrawer adds no animation.
 
-The component itself has no motion. The wrapping `Sheet` handles open / close transitions through the standard sheet preset and the `reduced` fallback.
+Rows explicitly compose Flex with wrap="wrap". Row descriptions use a
+max-content flex basis so they retain readable width when the controls wrap. Controls keep their natural width
+within a 100% cap, move below the row description when needed and retain the
+existing SegmentedControl scroll behavior for long choice rails.
 
 ## Accessibility
 
-**Roles:**
-
-- The panel is a `Sheet`, which renders with the standard `role="dialog"` plus `aria-modal` and a labelled-by pointer to the `Sheet.Title`. The title is "Preferences".
-- Each `SegmentedControl` is a `radiogroup` (for `type="single"`) or a `group` of toggles (for `type="multiple"`). The ConfigDrawer uses `type="single"` for all categorical tokens. The `NumberInput` for scaling is a `textbox` with an `aria-label="Scaling percentage"`.
-- The `SettingRow` `Label` is a `<label>` element. Because the controls sit inside the same row rather than as direct label children of the controls, the `aria-label` on each control is the source of truth for the accessible name. The visible `Label` is a visual cue, not a programmatic association.
-
-**Keyboard:**
-
-| Key | Action |
-|---|---|
-| `Tab` | Moves focus through the trigger, the segmented controls, the scaling input, and the sheet close affordance. |
-| `ArrowLeft` / `ArrowRight` | Navigates within a `SegmentedControl` (radiogroup semantics). |
-| `Enter` / `Space` | Activates the focused segmented option or input. |
-| `Escape` | Closes the `Sheet` and returns focus to the trigger. |
-
-**Focus:**
-
-- The `Sheet` is a modal: focus is trapped inside the drawer while it is open and returned to the trigger on close.
-- Each `SegmentedControl` is a roving-focus radiogroup: arrow keys move between options; the focused option gets a visible ring.
-- The `NumberInput` exposes the standard textbox focus ring.
-
-**Reduced motion:**
-
-- Open / close transitions respect `prefers-reduced-motion` through the standard `Sheet` motion contract.
-
-**Color and meaning:**
-
-- The selected `SegmentedControl` option tracks `--dsx-color-primary`. The control itself does not impose additional color cues.
-- The scaling `NumberInput` is a standard numeric entry; no color meaning.
-
-**Naming:**
-
-- Each `SegmentedControl` and the `NumberInput` carry an `aria-label` ("Theme mode", "Accent color", "Gray color", "Border radius", "Density", "Scaling percentage"). The visual `Label` repeats the same string so sighted and screen-reader users get the same word.
-- The drawer title is "Preferences".
+Drawer supplies modal dialog semantics, title/description, focus trapping and
+Escape dismissal with focus return. SegmentedControl supplies single selection
+and roving keyboard navigation; NumberInput supplies numeric entry. Enter/Space
+activate the trigger. The playground's draggable trigger separately preserves
+keyboard activation and suppresses clicks after pointer dragging.
 
 ## Playground demo spec
 
-**Default story:**
-
-- The playground registry does not render `ConfigDrawer` inline because the drawer is already mounted at the app root and a second instance would conflict with the active one. The registry render shows a description of the usage and the canonical placement (alongside `ThemeProvider` at the app root).
-
-**Variant story:** N/A. The component has no variants; the layout is fixed.
-
-**State story:**
-
-- Renders the drawer with `defaultOpen` and confirms the six rows appear with the correct default selections (`System`, `Rift`, `Auto`, `Medium`, `Comfortable`, `100`).
-- Renders the drawer with `open` (controlled) and confirms the same.
-- Renders a custom `trigger` and confirms the custom trigger is rendered when the drawer is closed.
-
-**Composition story:**
-
-- The component owns its own composition. The composition story is the default render: header + six rows + separators.
-
-**Token story:**
-
-- Renders the default drawer inside a `Theme` wrapper with `accentColor="warp"` and `accentColor="ray"`. Asserts the active segmented option tracks `--dsx-color-primary` while each accent preview continues to show the exact tier it represents.
-
-**A11y story:**
-
-- Uses `vitest-axe` against the rendered default story with the `aria-allowed-attr` rule disabled (the `SegmentedControl` ships a non-standard `variant` attribute on `role="group"`). Asserts no other axe violations.
-
-**Props exposed in the playground controls:**
-
-The playground registry for `config-drawer` does not expose prop controls. The component is mounted live at the app root; the registry render explains that placement and notes the `trigger` prop.
+The registry explains usage and lists all seven rows. The live example is the
+single app-root drawer opened with the bottom-right gear; that host uses side
+bottom. Test Light/Dark, every accent, gray palettes, radius, density, scaling
+and panel background at 1280/390/320, including the last row after scrolling.
+No duplicate drawer is mounted just to obtain a screenshot.
 
 ## Wiring notes
 
-**Composes from:**
-
-- `Sheet` (`src/components/sheet/Sheet`): the entire panel chrome. The drawer uses `Sheet.Trigger asChild` for the trigger, `Sheet.Content side="right"` for the panel, and `Sheet.Header` + `Sheet.Title` for the title row.
-- `IconButton` (`src/components/iconButton/IconButton`): the default trigger.
-- `Icon` (`src/components/icon/Icon`): the default `settings` icon.
-- `Label` (`src/components/label/Label`): the row label.
-- `Text` (`src/components/text/Text`): the row description.
-- `Flex` (`src/layout/Flex`): the row layout and the body layout.
-- `SegmentedControl` (`src/components/segmentedControl/SegmentedControl`): the categorical token pickers. The drawer uses `type="single"` and `size="sm"`.
-- `Separator` (`src/components/separator/Separator`): the row separators.
-- `NumberInput` (`src/components/numberInput/NumberInput`): the scaling percentage input, clamped to the 90 to 110 range in 5% steps.
-- `ThemeProvider` (`src/components/themeProvider/ThemeProvider`): the drawer reads and writes the active theme through `useTheme()`. The drawer must be rendered inside a `ThemeProvider` tree.
-
-**Used by:**
-
-- The playground's app shell mounts a single `ConfigDrawer` alongside `ThemeProvider` so every page can toggle the theme without a dedicated settings route.
-- App-level settings surfaces and onboarding flows.
-
-**State boundaries:**
-
-- Owned by ConfigDrawer: the six default rows, their order, the accent previews, and the `SettingRow` layout.
-- Owned by the consumer: the placement of the drawer, the custom `trigger` (if any), the controlled `open` / `onOpenChange` (if any), and the surrounding `ThemeProvider`.
-- Owned by `useTheme()`: every categorical selection (`theme`, `accentColor`, `grayColor`, `radius`, `density`, `scaling`) is read from and written to the active `ThemeProvider` context. The drawer does not own the value; it surfaces the control.
-
-**Boundary rules:**
-
-- App-owned data: the placement of the drawer, the controlled open state, the custom trigger, and the surrounding `ThemeProvider`.
-- DS-owned visuals: token bindings, slot classes, the `Sheet` panel chrome, the segmented control semantics, the `NumberInput` clamping, and the row layout.
+Drawer owns the portal, bounds and focus. ThemeProvider owns selections,
+persistence and system mode. The host owns placement, custom trigger, side,
+controlled open state and optional children. ConfigDrawer owns fixed row order,
+swatches and the numeric scaling clamp. ThemePanel remains the read-only inspector.

package/dist/docs/components/container.md

@@ -153,6 +153,8 @@ Container has no motion. The motion section is intentionally empty.
 
 ## Playground demo spec
 
+The default container retains its 1080px cap; size 1 and wide show 420px and 1200px caps respectively.
+
 **Default story:**
 
 - Renders `Container` with no extra props and a child node. Asserts the root classes are `dsx-container` and `dsx-box` (the `dsx-flex` class is conditional — it is only written when a flex layout prop such as `direction`, `align`, `justify`, `gap`, or `wrap` is set), the host element is a `div`, and `--dsx-container-max-width` resolves to `1080px`.

package/dist/docs/components/context-menu.md

@@ -33,13 +33,13 @@ An object-scoped right-click action menu. The DS `ContextMenu` wraps `@radix-ui/
 | `ContextMenu.Label` | Radix `ContextMenu.Label` | `dsx-context-menu__label` | Non-interactive section label. |
 | `ContextMenu.Separator` | Radix `ContextMenu.Separator` (via `MenuSeparator`) | `dsx-context-menu__separator` | Visual divider. |
 | `ContextMenu.Group` | Radix `ContextMenu.Group` | (no class) | Groups items semantically. |
-| `ContextMenu.Sub` | Radix `ContextMenu.Sub` | (no class) | Submenu owner. |
+| `ContextMenu.Sub` | Radix `ContextMenu.Sub` + `ContextMenuSubOpenContext` | (no class) | Submenu owner; mirrors controlled/uncontrolled state into SubContent. |
 | `ContextMenu.RadioGroup` | Radix `ContextMenu.RadioGroup` | (no class) | Radio selection owner. |
 | `ContextMenu.Portal` | Radix `ContextMenu.Portal` (via `MenuPortal`) | (no class) | Portal wrapper. |
 | `ContextMenu.CheckboxItem` | Radix `ContextMenu.CheckboxItem` | `dsx-context-menu__item` + `dsx-context-menu__item-indicator` | Checkbox row. Renders `check` or `minus` indicator. |
 | `ContextMenu.RadioItem` | Radix `ContextMenu.RadioItem` | `dsx-context-menu__item` + `dsx-context-menu__item-indicator` + `dsx-context-menu__radio-dot` | Radio row. |
 | `ContextMenu.SubTrigger` | Radix `ContextMenu.SubTrigger` | `dsx-context-menu__item` + `dsx-context-menu__sub-trigger` + optional `data-inset` + `chevron-right` | Row that opens the sub-content. |
-| `ContextMenu.SubContent` | Radix `ContextMenu.SubContent` inside `MenuContent` (no portal) | `dsx-context-menu__content` | The submenu panel. `MenuContent` is invoked with `forceMount`, `open`, and `portal === null` so the sub-content renders inline. |
+| `ContextMenu.SubContent` | Radix `ContextMenu.SubContent` inside portalled `MenuContent` | `dsx-context-menu__content` | The submenu panel follows Sub's open state outside the parent's clip box. Explicit `forceMount` is preserved. |
 | `ContextMenu.Shortcut` | `<span>` (or `Slot` child when `asChild`) | `dsx-context-menu__shortcut` | Keyboard hint rendered on the right. |
 
 The roster's `Parent / Slots` column lists `ContextMenu.Root`, `ContextMenu.Trigger`, `ContextMenu.Content`, `ContextMenu.Label`, `ContextMenu.Separator`, `ContextMenu.Item`, `ContextMenu.Group`. The source exports the full Radix part set through `Object.assign`, including `Sub`, `RadioGroup`, `Portal`, `CheckboxItem`, `RadioItem`, `SubTrigger`, `SubContent`, and `Shortcut`. The spec records the full set so the public surface is unambiguous.
@@ -69,7 +69,7 @@ The roster's `Parent / Slots` column lists `ContextMenu.Root`, `ContextMenu.Trig
 
 ### `ContextMenu.Trigger`, `ContextMenu.Label`, `ContextMenu.Separator`, `ContextMenu.Group`, `ContextMenu.Sub`, `ContextMenu.RadioGroup`, `ContextMenu.Portal`, `ContextMenu.CheckboxItem`, `ContextMenu.RadioItem`, `ContextMenu.SubTrigger`, `ContextMenu.SubContent`
 
-These proxy the corresponding Radix props. `ContextMenu.Trigger` accepts the standard Radix trigger props (no class). `ContextMenu.Label` and `ContextMenu.Group` accept the standard Radix props. `ContextMenu.SubContent` accepts the same `align`, `side`, and `sideOffset` props as `Content`; the portal is forced to `null` so the sub-content renders inline.
+These preserve the corresponding Radix props. `ContextMenu.Trigger` accepts standard Radix trigger props and adds the keyboard opening path below. `ContextMenu.Label` and `ContextMenu.Group` accept standard Radix props. `ContextMenu.Sub` preserves controlled `open`, uncontrolled `defaultOpen` and `onOpenChange`. `ContextMenu.SubContent` preserves Radix positioning and `forceMount` props and renders through a theme-preserving portal.
 
 ### `ContextMenu.Item`
 
@@ -194,13 +194,13 @@ Rules:
 - `ContextMenu.Item` is `role="menuitem"`. `ContextMenu.CheckboxItem` is `role="menuitemcheckbox"`; `ContextMenu.RadioItem` is `role="menuitemradio"`. `ContextMenu.SubTrigger` is `role="menuitem"` with `aria-haspopup="menu"`.
 - `ContextMenu.Label` is `role="presentation"` for non-interactive section labels (Radix default).
 - `ContextMenu.Separator` is `role="separator"`.
-- `ContextMenu.Trigger` is the right-click target; it is typically a non-semantic element that owns the context-menu event.
+- `ContextMenu.Trigger` captures right-click and touch long-press. A custom non-interactive host must supply `tabIndex={0}` for keyboard opening. The wrapper forwards the Radix trigger props and ref. Essential touch actions should also have an explicit button/menu composition; long-press alone is not discoverable.
 
 **Keyboard:**
 
 | Key | Action |
 |---|---|
-| `Shift+F10`, context-menu key | Opens the context menu (browser-default). |
+| `Shift+F10`, context-menu key | Opens the menu at the focused trigger's center. The wrapper supplies the context event consistently across browsers; a consumer-cancelled key handler is respected. |
 | `ArrowDown`, `ArrowUp` | Moves through items. |
 | `Enter`, `Space` | Activates the focused item. |
 | `Escape` | Closes the menu. |
@@ -282,3 +282,17 @@ Rules:
 
 - App-owned data: the command set, the disabled reasons, the right-click target, and the keyboard shortcut strings.
 - DS-owned visuals: the `dsx-context-menu__*` slot classes, the token bindings, the data-attribute contract, and the open / close animation.
+
+## Reconciliation stories
+
+`Sub` preserves Radix's controlled `open`, uncontrolled `defaultOpen`, and
+`onOpenChange` contract. `SubContent` follows that state and renders in its own
+theme-preserving portal, outside the root's scroll/clip box. Closed submenus
+are unmounted unless the consumer explicitly requests `forceMount`; they do not
+leave inaccessible menu items behind the parent surface.
+
+The panel's usual minimum width is capped by Radix's available width. A submenu
+can become narrower when neither side has room for the usual menu width; labels
+wrap rather than painting off the viewport. No viewport breakpoint is involved.
+
+The live example uses a real Project actions button for explicit activation, right-click and keyboard opening. It demonstrates selection feedback, a disabled item, a controlled checkbox and radio group, a submenu and a destructive action. Shortcut hints are labels; item callbacks own the action.

package/dist/docs/components/dialog.md

@@ -239,6 +239,8 @@ Rules:
 
 ## Playground demo spec
 
+The live connection-settings example uses the package Select for Region and a nested Popover for display density. Apply closes only the child popover; Save region reports the selected value and returns focus to the dialog launcher. Long-content mode verifies reachable body and footer controls.
+
 **Default story:**
 
 - Renders `DialogRoot` with a `Trigger` and `Content` containing `Header`, `Body`. Asserts the content has `dsx-dialog__content` and `data-size="md"`.
@@ -274,7 +276,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. Asserts the `data-accent-color` attribute on the content wrapper.
+- Renders inside a `Theme` wrapper with `accentColor="rift"` and one with `accentColor="warp"`. Asserts the `data-accent-color` attribute on the content wrapper.
 
 **Props exposed in the playground controls:**
 

package/dist/docs/components/drawer.md

@@ -51,8 +51,6 @@ A mobile or edge-attached modal overlay that slides in from any edge of the view
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Drawer content size; writes `data-size` attribute. | no |
-| `height` | `string` (responsive) | `undefined` | no | Responsive height override via CSS variable. | yes |
-| `width` | `string` (responsive) | `undefined` | no | Responsive width override via CSS variable. | yes |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-drawer__content`. | no |
 
 **Header props:**
@@ -76,7 +74,7 @@ Standard Radix `Title` and `Description` props plus `className`.
 Rules:
 
 - `direction` on Root is wired through `extractProps`.
-- `size`, `height`, and `width` on Content are wired through `extractProps`.
+- `size` on Content are wired through `extractProps`.
 - `asChild` on Header and Footer is wired through `extractProps`.
 - The Root manages open state through a controllable hook (`useControllableDrawerOpenState`) that supports both controlled and uncontrolled modes.
 - The Root provides `DrawerOpenContext` and `DrawerDirectionContext` so Content can access the open state and direction for motion calculations.
@@ -102,12 +100,12 @@ Rules:
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-direction` (on content) | `top`, `right`, `bottom`, `left` | `.dsx-drawer__content[data-direction='...']` | `drawer.css` |
-| `data-size` (on content) | `sm`, `md`, `lg` | (no CSS rules in source; reserved for consumer extension) | n/a |
+| `data-size` (on content) | `sm`, `md`, `lg` | Top/bottom minimum-height and side-panel width bands | n/a |
 | `data-slot` | `drawer-overlay`, `drawer-content`, `drawer-handle`, `drawer-header`, `drawer-footer`, `drawer-title`, `drawer-description` | (CSS hook only) | n/a |
 
 **Responsive behavior:**
 
-- Content `height` and `width` props are responsive via CSS variables (`--dsx-r-height`, `--dsx-r-width`).
+- Content size is single-valued. It does not expose responsive height/width props. Viewport caps and scrolling are intrinsic.
 
 **Reduced motion:**
 
@@ -208,7 +206,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Drawer does not track `data-accent-color` directly; the story asserts the overlay and content surfaces are visually unchanged.
+- Renders inside a `Theme` wrapper with `accentColor="astral"` and `accentColor="spark"`. Drawer does not track `data-accent-color` directly; the story asserts the overlay and content surfaces are visually unchanged.
 
 **A11y story:**
 
@@ -243,3 +241,16 @@ Rules:
 
 - App-owned data: the drawer content, the trigger label, the action handlers, and the open state when controlled.
 - DS-owned visuals: token bindings, the slot CSS classes, the motion presets, and the portal theme mirroring.
+
+## Overlay review containment
+
+Content caps at 100dvh and its containing viewport width, wraps long words,
+and scrolls vertically. Direct content regions do not shrink into each other.
+Left/right content uses height=100dvh with min-height=0 and width bands capped
+at 100%; top/bottom content retains its minimum-height size bands. No width
+media query is required. `/docs/drawer` opens all four directions and offers
+short/long content to verify both the first row and the footer after scrolling.
+
+The package disables Vaul’s offscreen ::after filler on its scrolling shell.
+That pseudo-element otherwise adds blank scroll range and covers bottom-drawer
+footer controls after scrolling; it is unnecessary for the bounded surface.

package/dist/docs/components/dropdown-menu.md

@@ -39,7 +39,7 @@ A button-triggered secondary action menu. The DS `DropdownMenu` wraps `@radix-ui
 | `DropdownMenu.CheckboxItem` | Radix `DropdownMenu.CheckboxItem` | `dsx-dropdown-menu__item` + `dsx-dropdown-menu__item-indicator` | Checkbox row. Renders `check` or `minus` indicator. |
 | `DropdownMenu.RadioItem` | Radix `DropdownMenu.RadioItem` | `dsx-dropdown-menu__item` + `dsx-dropdown-menu__item-indicator` + `dsx-dropdown-menu__radio-dot` | Radio row. |
 | `DropdownMenu.SubTrigger` | Radix `DropdownMenu.SubTrigger` | `dsx-dropdown-menu__item` + `dsx-dropdown-menu__sub-trigger` + optional `data-inset` + `chevron-right` | Row that opens the sub-content. |
-| `DropdownMenu.SubContent` | Radix `DropdownMenu.SubContent` inside `MenuContent` (no portal) | `dsx-dropdown-menu__content` | The submenu panel. `MenuContent` is invoked with `forceMount`, `open`, and `portal === null` so the sub-content renders inline. |
+| `DropdownMenu.SubContent` | Radix `DropdownMenu.SubContent` inside portal-mounted `MenuContent` | `dsx-dropdown-menu__content` | The submenu panel tracks its own Sub open state and uses a portal so the parent scroll frame does not clip it. forceMount remains consumer-controlled. |
 | `DropdownMenu.Shortcut` | `<span>` (or `Slot` child when `asChild`) | `dsx-dropdown-menu__shortcut` | Keyboard hint rendered on the right. |
 
 The roster's `Parent / Slots` column lists `DropdownMenu.Root`, `DropdownMenu.Trigger`, `DropdownMenu.Content`, `DropdownMenu.Label`, `DropdownMenu.Separator`, `DropdownMenu.Item`, `DropdownMenu.Group`. The source exports the full Radix part set through `Object.assign`, including `Sub`, `RadioGroup`, `Portal`, `CheckboxItem`, `RadioItem`, `SubTrigger`, `SubContent`, and `Shortcut`. The spec records the full set so the public surface is unambiguous.
@@ -71,7 +71,7 @@ The roster's `Parent / Slots` column lists `DropdownMenu.Root`, `DropdownMenu.Tr
 
 ### `DropdownMenu.Trigger`, `DropdownMenu.Label`, `DropdownMenu.Separator`, `DropdownMenu.Group`, `DropdownMenu.Sub`, `DropdownMenu.RadioGroup`, `DropdownMenu.Portal`, `DropdownMenu.CheckboxItem`, `DropdownMenu.RadioItem`, `DropdownMenu.SubTrigger`, `DropdownMenu.SubContent`
 
-These proxy the corresponding Radix props. `DropdownMenu.Trigger` accepts the standard Radix trigger props (no class). `DropdownMenu.Label` and `DropdownMenu.Group` accept the standard Radix props. `DropdownMenu.SubContent` accepts the same `align` and `side` props as `Content`; the portal is forced to `null` so the sub-content renders inline.
+These proxy the corresponding Radix props. `DropdownMenu.Trigger` accepts the standard Radix trigger props (no class). `DropdownMenu.Label` and `DropdownMenu.Group` accept the standard Radix props. `DropdownMenu.SubContent` accepts the same `align` and `side` props as `Content`; Sub preserves controlled/uncontrolled open props; SubContent uses the Radix portal and its owning Sub state.
 
 ### `DropdownMenu.Item`
 
@@ -288,3 +288,12 @@ Rules:
 
 - App-owned data: the command set, the disabled reasons, the trigger element, and the keyboard shortcut strings.
 - DS-owned visuals: the `dsx-dropdown-menu__*` slot classes, the token bindings, the data-attribute contract, and the open / close animation.
+
+## Overlay review interaction
+
+Submenus are absent while closed unless forceMount is requested. Sub owns
+controlled/uncontrolled state and SubContent receives that state through a
+private context; it is no longer forced open. Portalling matches the
+[Radix submenu anatomy](https://www.radix-ui.com/primitives/docs/components/dropdown-menu)
+and keeps the submenu outside the parent’s overflow frame. The live example
+demonstrates working Profile/Settings, Autosave and Share project actions.

package/dist/docs/components/em.md

@@ -105,7 +105,7 @@ Rules:
 
 ## Playground demo spec
 
-`Em` is registered in `apps/playground/lib/registry/typography.tsx` under the `em` key. The registry entry imports `emPropDefs` and renders the component with a sample emphasis span. Per-component route: `/docs/em`.
+`Em` is registered in `apps/playground/lib/registry/typography.tsx` under the `em` key. The registry entry imports `emPropDefs` and renders the component with a sample emphasis span. Per-component route: `/docs/em`. The live example uses English and Russian sentence context plus a slotted span.
 
 **Default story:**
 

package/dist/docs/components/file-upload.md

@@ -41,7 +41,7 @@ A card-based file selection surface with a dropzone, a list of file rows, and a
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Card-level size token. Drives `data-size`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Card-level size; `sm` uses a wrapping inline attachment layout, `md`/`lg` use a centered drop area. Drives `data-size`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the card through `Slot` from `@radix-ui/react-slot`. | no |
 | Standard `Card` props | `CardProps` | n/a | no | The root extends `CardProps`, so variant, radius, and standard card attributes pass through. | no |
 | `children` | `React.ReactNode` | `undefined` | no | `FileUpload.Dropzone`, `FileUpload.List`, and `FileUpload.Item` children. | no |
@@ -109,7 +109,7 @@ Rules:
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | n/a (no size-specific root CSS today) | `file-upload.css` |
+| `data-size` | `sm`, `md`, `lg` | Root controls dropzone layout, minimum height and padding | `file-upload.css` |
 | `data-dragging` | `true` | `.dsx-file-upload__dropzone[data-dragging='true']` thicker accent dashed border + active background (no ring) | `file-upload.css` |
 | `data-status-tone` | `danger` (omitted when `muted`) | `.dsx-file-upload__item:where([data-status-tone='danger']) .dsx-file-upload__status` error color | `file-upload.css` |
 
@@ -135,6 +135,8 @@ Rules:
 **Responsive behavior:**
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size is single-value only.
+- The `sm` dropzone places illustration, text and action in a wrapping row. Consumers choose this attachment composition for narrow forms; `md`/`lg` retain the centered drag area. All sizes grow with content and localized labels.
+- FileUpload owns its dropzone minimum height and typography; it does not inherit EmptyState's standalone empty-page minimum height.
 
 **Reduced motion:**
 
@@ -148,7 +150,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|---|
 | Root layout | `display: grid; gap: var(--dsx-space-md); width: 100%` | Surface layout. |
 | Dropzone width | `width: 100%` | Full width. |
-| Dropzone min-height | `calc(var(--dsx-size-4xl) * 2)` | Tall enough to invite a drop. |
+| Dropzone min-height | `var(--dsx-size-4xl)` / `calc(var(--dsx-size-4xl) * 2)` / `calc(var(--dsx-size-4xl) * 2.5)` | sm/md/lg content-growing minimums. |
+| Dropzone padding / gap | `var(--dsx-space-sm)` / `var(--dsx-space-md)` / `var(--dsx-space-lg)`; gap `var(--dsx-space-sm)` | sm/md/lg padding and compact internal spacing. |
+| Dropzone illustration | `var(--dsx-size-lg)` square | Upload affordance rather than an empty-page illustration. |
+| Dropzone title | `var(--dsx-typography-label-large-*)` | Form-level title, independent of EmptyState headline typography. |
 | Dropzone border | `var(--dsx-border-width-md)` dashed `var(--dsx-color-outline)` | Resting edge, visible against the sunken fill. |
 | Dropzone radius | `var(--dsx-rounded-lg)` | Round corners. |
 | Dropzone background | `var(--dsx-color-surface-sunken)` | Sunken surface. |
@@ -160,9 +165,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Item icon size | `var(--dsx-size-lg)` square | Round icon slot. |
 | Item icon color | `var(--dsx-color-on-surface-variant)` | Quiet icon. |
 | Item content min-width | `min-width: 0` | Allows the title to ellipsis. |
+| Item content flex / row gap | `flex: 1 1 0`; `var(--dsx-space-sm)` | A short file row can shrink its text column before wrapping media/actions. FileUpload overrides Item's prose-oriented content basis. |
 | Item title overflow | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` | Long file names truncate. |
 | Item media color | `var(--dsx-color-on-surface-variant)` | Quiet media. |
-| Item actions alignment | `margin-left: auto; flex-direction: column; align-items: flex-end; gap: var(--dsx-space-xs)` | Right-aligned, stacked. |
+| Item actions alignment | `margin-left: auto; flex-direction: column; flex-wrap: nowrap; align-items: flex-end; gap: var(--dsx-space-xs)` | Right-aligned, stacked. Consumer wrappers may define their own inner layout. |
 | Progress width | `width: 100%` | Full row width. |
 | Progress label/status typography | `var(--dsx-typography-label-small-*)` | Small label ramp. |
 | Progress label/status color | `var(--dsx-color-on-surface-variant)` | Quiet label. |
@@ -219,11 +225,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Composition story:**
 
-- Renders the full surface: dropzone, list, three items. The first item has a `progress={42}` with no label (the meta line carries the numbers, as in the reference). The second item has a `status="Complete"` and a ghost `IconButton` trash remove action. The third item has a `status="Upload failed"` with `statusTone="danger"` and ghost `IconButton` redo retry + trash remove actions. Asserts each slot renders with the right class, the progress bar renders, the failed row writes `data-status-tone="danger"`, and the actions block sits at the right edge with icons only.
+- One compact live capture surface populates dropzone, list, item, progress and working remove/retry actions after selection. An expandable row-state gallery shows progress, completed and failed rows, followed by forced drag feedback and Rift/Warp token stories. Size comparisons stay in the matrix rather than duplicating three large surfaces in the live example.
 
 **Live capture story:**
 
-- Renders `FileUploadLiveCapture`: a `multiple` dropzone with `onFiles` feeding a simulated upload list (interval-driven `progress` with reference-style `"X MB | Y% • Z sec left"` descriptions), an "Or upload from URL" `Input` + `Upload` `Button` composition appending completed rows, ghost `IconButton` row actions (trash remove always, redo retry on failed rows — retry resets the row to 0%), a fail preview (files with "fail" in the name fail at 60%), and a Cancel / Attach-files footer. Covered by `tests/file-upload.spec.ts` (drag capture, browse capture, zero console issues).
+- Renders `FileUploadLiveCapture` with `size="sm"`, `variant="filled"`, a short title/description and a working Browse files action. A `multiple` dropzone with `onFiles` feeds a simulated upload list (interval-driven progress). Compact rows use the existing `size="sm"` and `icon={null}` options, a file-size description, progress/completion/error status and stacked md ghost icon actions (trash remove always, redo retry on failed rows — retry resets the row to 0%). Files with "fail" in the name fail at 60%. Selection count is announced through a status region. Covered by `tests/file-upload.spec.ts` and `tests/sweep-polish.spec.ts` (drag/browse/keyboard capture, retry/remove, mobile geometry, zero console issues).
 
 **A11y story:**
 
@@ -253,7 +259,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Composed by consumers (not DS slots):**
 
-- URL upload (`Input` + `Button` appending a completed row) and modal shells with Cancel / Attach-files footers are app composition. The playground `FileUploadLiveCapture` fixture demonstrates both against the same list state.
+- URL fetching and modal shells with Cancel / Attach-files footers are app composition. The primary playground story focuses on file capture and rows; it does not imply FileUpload supplies a URL transport or an attach-to-record action.
 
 **Used by:**