@d4gger/design-system 3.0.0 → 4.0.0

package/dist/docs/components/resizable.md

@@ -17,25 +17,25 @@ A resizable panel group with draggable handles. The package owns the shell, the
 
 ## Anatomy & slots
 
-**Parent:** `Resizable` (alias of `Resizable.PanelGroup`).
+**Parent:** `Resizable` (alias of `ResizablePanelGroup`).
 
 **Slots:**
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `Resizable.PanelGroup` (alias `Resizable`) | `<div>` (the `Group` from `react-resizable-panels`) | `dsx-resizable-group` | Hosts the orientation attribute and the panel layout. Carries `data-orientation` and `data-slot="resizable-group"`. |
+| `ResizablePanelGroup` (alias `Resizable`) | `<div>` (the `Group` from `react-resizable-panels`) | `dsx-resizable-group` | Hosts the orientation attribute and the panel layout. Carries `data-orientation` and `data-slot="resizable-group"`. |
 | `Resizable.Panel` | `<div>` (the `Panel` from `react-resizable-panels`) | `dsx-resizable-panel` | One resizable child. Carries `data-slot="resizable-panel"`. |
 | `Resizable.Handle` | `<div>` (the `Separator` from `react-resizable-panels`) | `dsx-resizable-handle` | The draggable separator between two panels. Carries `data-slot="resizable-handle"` and `data-grip="true"` when `withGrip` is set. When `withGrip` is set, a child `<div>` with `dsx-resizable-handle__grip` is rendered. |
 
 **Adapter host:**
 
-`Resizable.PanelGroup` wraps the `Group` from `react-resizable-panels`. The package translates the DS `direction` prop (`'horizontal'` or `'vertical'`) into the adapter's `orientation` prop. The package also passes `elementRef` through `composeRefs` so the `forwardRef` and any app-supplied ref both see the host element.
+`ResizablePanelGroup` wraps the `Group` from `react-resizable-panels`. The package translates the DS `direction` prop (`'horizontal'` or `'vertical'`) into the adapter's `orientation` prop. The package also passes `elementRef` through `composeRefs` so the `forwardRef` and any app-supplied ref both see the host element.
 
 `Resizable.Handle` wraps the `Separator` from `react-resizable-panels`. `withGrip` adds a visual grip indicator inside the handle; the adapter still owns the drag interaction and the keyboard arrow support.
 
 ## Props contract
 
-### `Resizable.PanelGroup` props
+### `ResizablePanelGroup` props
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
@@ -43,7 +43,7 @@ A resizable panel group with draggable handles. The package owns the shell, the
 | `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Drives `data-orientation` on the group. Mapped to the adapter's `orientation` prop. The CSS file uses the inline `[data-orientation='…']` selectors and the modifier `dsx-resizable-group-direction-horizontal` / `dsx-resizable-group-direction-vertical` class. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-resizable-group`. | no |
 
-The group also accepts the full `GroupProps` from `react-resizable-panels` minus `orientation` (which is replaced by the DS `direction` prop) and `elementRef` (which the package routes through `composeRefs`). `autoSaveId`, `id`, `onLayout`, `storage`, `defaultLayout`, and `keyboardResizeBy` are forwarded verbatim.
+The group also accepts the full `GroupProps` from `react-resizable-panels` minus `orientation` (which is replaced by the DS `direction` prop) and `elementRef` (which the package routes through `composeRefs`). `id`, `defaultLayout`, `onLayoutChange`, `onLayoutChanged`, `disabled`, `groupRef` and `resizeTargetMinimumSize` follow the installed v4 adapter contract. Persistence belongs to the app; v3-only props are not promised.
 
 ### `Resizable.Panel` props
 
@@ -52,7 +52,7 @@ The group also accepts the full `GroupProps` from `react-resizable-panels` minus
 | `asChild` | `boolean` | `false` | no | Extracted from prop defs but the `Panel` host always renders a `<div>`. The prop is reserved for future use. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-resizable-panel`. | no |
 
-The panel also accepts the full `PanelProps` from `react-resizable-panels` minus `elementRef`. `defaultSize`, `minSize`, `maxSize`, `collapsible`, `collapsedSize`, `onCollapse`, `onExpand`, `onResize`, `id`, `order`, and `ref` are forwarded verbatim.
+The panel also accepts the full `PanelProps` from `react-resizable-panels` minus `elementRef`. `defaultSize`, `minSize`, `maxSize`, `collapsible`, `collapsedSize`, `onResize`, `id`, `panelRef` and `groupResizeBehavior` follow the installed v4 adapter contract. Use explicit percentage strings such as "50%"; numeric sizes represent pixels.
 
 ### `Resizable.Handle` props
 
@@ -62,7 +62,7 @@ The panel also accepts the full `PanelProps` from `react-resizable-panels` minus
 | `withGrip` | `boolean` | `false` | no | When `true`, renders a `dsx-resizable-handle__grip` indicator inside the handle and sets `data-grip="true"`. The CSS file uses the `data-grip` attribute and the `dsx-resizable-handle-grip` modifier class to color the indicator. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-resizable-handle`. | no |
 
-The handle also accepts the full `SeparatorProps` from `react-resizable-panels` minus `elementRef` and `withGrip`. `id`, `disabled`, `hitAreaMargins`, and the adapter drag attributes are forwarded verbatim.
+The handle also accepts the full `SeparatorProps` from `react-resizable-panels` minus `elementRef` and `withGrip`. `id`, `disabled` and native attributes follow SeparatorProps. Group resizeTargetMinimumSize controls adapter hit geometry; v3 hitAreaMargins is not promised.
 
 ## CSS class contract
 
@@ -96,12 +96,12 @@ The handle also accepts the full `SeparatorProps` from `react-resizable-panels`
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. None of its prop defs are `responsive: true`.
+- The component has no viewport-width media rules. None of its prop defs are `responsive: true`.
 - The component's CSS file is breakpoint-agnostic.
 
 **Reduced motion:**
 
-- The handle background and the grip indicator transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. The CSS file does not include a `prefers-reduced-motion` gate; the global stylesheet is expected to honor the media query. The adapter's drag interaction is layout-only and does not animate.
+- The handle background and the grip indicator transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. Its own `prefers-reduced-motion` gate disables handle and track transitions. The adapter's drag interaction is layout-only and does not animate.
 
 ## Token mapping
 
@@ -119,7 +119,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Handle active background | `var(--dsx-color-high-contrast-container)` | Active affordance. |
 | Handle cursor | `col-resize` (horizontal), `row-resize` (vertical) | Cursor. |
 | Handle touch action | `none` | Prevent browser scroll on touch. |
-| Handle thickness | `var(--dsx-resizable-handle-thickness-active)` | Visible thickness. |
+| Handle thickness | `max(var(--dsx-size-md), var(--dsx-resizable-handle-thickness-active))` | Actual hit box, at least 24px; the painted line stays thin. |
 | Handle track | `var(--dsx-border-width-md, var(--dsx-resizable-handle-thickness))` | Inactive track thickness. |
 | Handle track color | `var(--dsx-control-separator-color-strong)` | Track color. |
 | Handle track hover color | `var(--dsx-color-high-contrast)` | Hover color. |
@@ -127,6 +127,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Grip width | `var(--dsx-resizable-grip-width)` | Grip indicator width. |
 | Grip height | `var(--dsx-resizable-grip-height)` | Grip indicator height. |
 | Grip radius | `var(--dsx-resizable-grip-radius)` | Grip indicator roundness. |
+| Handle z-index | `var(--dsx-z-index-elevated)` | Preserve the entire target above pane content. |
 | Grip z-index | `var(--dsx-z-index-elevated)` | Grip stack order. |
 | Grip horizontal size | `var(--dsx-space-xs)` × `var(--dsx-size-xs)` | Horizontal handle grip dimensions. |
 | Grip vertical size | `var(--dsx-size-xs)` × `var(--dsx-space-xs)` | Vertical handle grip dimensions. |
@@ -136,8 +137,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Region | Token | Default | Reduced |
 |---|---|---|---|
-| Handle background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Hover and active background transition. | Relies on the global `prefers-reduced-motion` stylesheet. |
-| Handle track and grip | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Track color, grip background, and transform transition. | Relies on the global `prefers-reduced-motion` stylesheet. |
+| Handle background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Hover and active background transition. | Own CSS disables handle transitions under prefers-reduced-motion. |
+| Handle track and grip | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Track color, grip background, and transform transition. | Own CSS disables handle transitions under prefers-reduced-motion. |
 
 ## Accessibility
 
@@ -152,20 +153,20 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|
 | `Tab` | Moves focus to the next focusable element. The handle is focusable by default. |
 | `Enter`, `Space` | Toggles the panel state when the handle supports collapsing. |
-| `Arrow keys` | The adapter handles arrow-key resize by the `keyboardResizeBy` step. |
+| `Arrow keys` | The installed v4 adapter handles arrow-key resizing. |
 | `Home`, `End` | The adapter collapses or expands the panel to its minimum or maximum size when supported. |
 
 **Focus:**
 
-- The handle receives a visible focus ring via the browser default for `[role="separator"]` plus the global focus stylesheet. The DS does not add a custom ring; apps that need a custom ring can target `[role="separator"]:focus-visible` from the host.
+- The DS paints `var(--dsx-shadow-focus-ring)` on `.dsx-resizable-handle:focus-visible`. The handle stays above adjacent pane content so its full target receives input.
 
 **Reduced motion:**
 
-- The handle transitions collapse under the global `prefers-reduced-motion` stylesheet. The drag interaction is layout-only and does not animate.
+- The handle and track transitions are disabled by their own `prefers-reduced-motion` rules. The drag interaction is layout-only and does not animate.
 
 **Color and meaning:**
 
-- The handle and the grip use semantic tokens (`var(--dsx-color-high-contrast-container)` and `var(--dsx-color-on-surface-variant)`) so light and dark themes are covered. The track thickness increases from `var(--dsx-resizable-handle-thickness)` to `var(--dsx-resizable-handle-thickness-active)` on hover to communicate the drag affordance.
+- The handle and the grip use semantic tokens (`var(--dsx-color-high-contrast-container)` and `var(--dsx-color-on-surface-variant)`) so light and dark themes are covered. The thin track keeps its thickness on hover; semantic color changes communicate the drag affordance.
 
 **Naming:**
 
@@ -198,6 +199,13 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 `withGrip` is wired through the composition story rather than the prop table.
 
+## Review examples
+
+The horizontal workspace preserves scrollable outline and draft panes, minimum
+20% panel sizes and a live proportions summary. The vertical example exercises
+its own resize axis. Handles have visible keyboard focus; both directions
+retain a 24px minimum box while the visual divider remains thin.
+
 ## Wiring notes
 
 **Composes from:**
@@ -212,8 +220,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 **State boundaries:**
 
 - Owned by this component: the DS shell class wiring, the `direction` to `orientation` translation, the `withGrip` rendering, the `data-orientation` and `data-slot` attributes, and the `composeRefs` helper.
-- Owned by the adapter: panel math, drag interaction, keyboard arrow resize, the `autoSaveId` persistence, the percentage bookkeeping, and the `role="separator"` semantics.
-- Owned by the consumer: the number of panels, the `defaultSize`, `minSize`, `maxSize`, and `collapsible` configuration, the content of each panel, the `onLayout` callback, and any business policy that wraps the layout state.
+- Owned by the adapter: panel math, drag interaction, keyboard arrow resize, the percentage bookkeeping, and the `role="separator"` semantics.
+- Owned by the consumer: the number of panels, the `defaultSize`, `minSize`, `maxSize`, and `collapsible` configuration, the content of each panel, the adapter layout callbacks, and any business policy that wraps the layout state.
 
 **Boundary rules:**
 

package/dist/docs/components/result.md

@@ -15,6 +15,8 @@ Canonical outcome and list-state surface. `state` is `success`, `failure`, `expi
 
 `Result.Root`, `Result.Icon`, `Result.Title`, `Result.Description`, `Result.Metadata`, `Result.Steps`, and `Result.Actions`. Root class is `dsx-result`; slot classes use `dsx-result__<slot>`. Root writes `data-state` and `data-tone`.
 
+The root shrinks to the available width, direct children stay within that width, and long titles, descriptions, and identifiers wrap without truncation. Actions wrap intrinsically; no viewport query selects a different layout.
+
 ## Wiring notes
 
 `EmptyState` delegates to `Result state="empty"` while preserving its legacy class and props. `DataTable` uses Result for loading, empty, no-results, and error states. Copy, retry behavior, and async work are consumer-owned.
@@ -22,3 +24,7 @@ Canonical outcome and list-state surface. `state` is `success`, `failure`, `expi
 ## Playground demo spec
 
 Show every state, an independently overridden tone, populated slots, and alert/loading semantics.
+
+The live playground example switches between all seven states with actual buttons. Each state has contextual copy, a matching illustration or spinner, and an appropriate recovery action. Success shows connection metadata; loading shows steps. Recovery returns to success and Continue opens the empty saved-server state. The compact default example provides an illustration, title, and description.
+
+The inline live example uses headline-medium for its title and one outlined Result surface, avoiding compounded Card/Result padding. Short state titles preserve whole-word readability at 320px.

package/dist/docs/components/rich-text-editor.md

@@ -8,6 +8,7 @@ depends_on:
   - "@tiptap/starter-kit"
   - Button
   - Icon
+  - VisuallyHidden
 ---
 
 # RichTextEditor
@@ -51,7 +52,7 @@ The `EditorContent` component from `@tiptap/react` renders inside `RichTextEdito
 | Region | Element | Class | Notes |
 |---|---|---|---|
 | Toolbar group | `<div>` | `dsx-rich-text-editor__toolbar-group` | Groups related toolbar buttons. `role="group"` with `aria-label`. |
-| Toolbar label | `<span>` | `dsx-rich-text-editor__toolbar-label` | Group label ("Text", "Blocks", "Insert", "History"). |
+| Optional custom toolbar label | `<span>` | `dsx-rich-text-editor__toolbar-label` | Group label ("Text", "Blocks", "Insert", "History"). |
 | Status bar | `<div>` | `dsx-rich-text-editor__status` | Shows editor status ("Editor loading", "Ready to write", or character count). `data-slot="rich-text-editor-status"`. |
 | Placeholder | `<div>` | `dsx-rich-text-editor__placeholder` | Shown when the editor is empty and a placeholder is provided. `data-slot="rich-text-editor-placeholder"`. |
 | Content host | `EditorContent` | `dsx-rich-text-editor__content` | The Tiptap adapter host. `data-slot="rich-text-editor-content"`. |
@@ -63,7 +64,7 @@ The `EditorContent` component from `@tiptap/react` renders inside `RichTextEdito
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `asChild` | `boolean` | `false` | no | Extracted from prop defs but not used by the root. The root always renders as a `<div>`. | no |
-| `disabled` | `boolean` | `false` | no | Makes the editor non-editable. Drives `data-disabled` and `aria-disabled` on the shell. The CSS file consumes `data-disabled='true'` to change the shell border, background, and text color. | no |
+| `disabled` | `boolean` | `false` | no | Makes the editor non-editable. Drives `data-disabled` and `aria-disabled` on the shell. Changing disabled retains the document and editor instance. The CSS file consumes `data-disabled='true'` to change the shell border, background, and text color. | no |
 | `content` | `unknown` | `''` | no | Initial or controlled editor content. Accepts `string` (HTML), `object` (JSON), or `null`. Validated by `isRichTextEditorContent`. | no |
 | `editorOptions` | `Omit<UseEditorOptions, 'content' \| 'editable' \| 'extensions' \| 'onUpdate'>` | `undefined` | no | Escape hatch for `useEditor` options. Merged with the DS-managed options. | no |
 | `extensions` | `UseEditorOptions['extensions']` | `[StarterKit]` | no | Tiptap extensions. Defaults to `StarterKit`. Apps that need custom schema or extensions pass their own array. | no |
@@ -73,6 +74,11 @@ The `EditorContent` component from `@tiptap/react` renders inside `RichTextEdito
 | `serialize` | `(editor: Editor) => string` | `undefined` | no | Custom serialization function. When provided, `onUpdate` receives the output of this function instead of `editor.getHTML()`. | no |
 | `toolbar` | `RichTextEditorToolbarSlot \| null` | `undefined` | no | Controls the toolbar rendering. `undefined` renders the default `RichTextEditor.Toolbar`. A ReactNode renders that node instead. A function receives `{ disabled, editor }` and returns a ReactNode. `null` hides the toolbar. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-rich-text-editor`. | no |
+| `tools` | `readonly EditorTool[]` | common formatting | no | Visible schema-supported controls. Does not validate document policy. | no |
+| `headingLevels` | `readonly (1..6)[]` | schema levels | no | Levels in the text style menu. | no |
+| `insertItems` | `readonly EditorInsertItem[]` | `[]` | no | Consumer-labelled insertion callbacks. | no |
+| `variables` | `readonly EditorVariable[]` | `undefined` | no | Registry metadata; Root adds key-only atom unless extensions are replaced. | no |
+| `mentions` | `readonly EditorMention[]` | `undefined` | no | User IDs/labels; picker and @ suggestions. Custom schemas add the mention extension. | no |
 
 ### `RichTextEditor.Shell` props
 
@@ -84,6 +90,11 @@ The `EditorContent` component from `@tiptap/react` renders inside `RichTextEdito
 | `placeholder` | `string` | `undefined` | no | Placeholder text. | no |
 | `toolbar` | `RichTextEditorToolbarSlot \| null` | `undefined` | no | Toolbar override. Same semantics as `Root`. | no |
 | `className` | `string` | `undefined` | no | Extra classes. | no |
+| `tools` | `readonly EditorTool[]` | common formatting | no | Visible schema-supported controls. Does not validate document policy. | no |
+| `headingLevels` | `readonly (1..6)[]` | schema levels | no | Levels in the text style menu. | no |
+| `insertItems` | `readonly EditorInsertItem[]` | `[]` | no | Consumer-labelled insertion callbacks. | no |
+| `variables` | `readonly EditorVariable[]` | `undefined` | no | Registry metadata; Root adds key-only atom unless extensions are replaced. | no |
+| `mentions` | `readonly EditorMention[]` | `undefined` | no | User IDs/labels; picker and @ suggestions. Custom schemas add the mention extension. | no |
 
 ### `RichTextEditor.Toolbar` props
 
@@ -92,6 +103,11 @@ The `EditorContent` component from `@tiptap/react` renders inside `RichTextEdito
 | `editor` | `Editor \| null` | (required) | yes | The Tiptap editor instance. | no |
 | `disabled` | `boolean` | `false` | no | Disables all toolbar buttons. | no |
 | `className` | `string` | `undefined` | no | Extra classes. | no |
+| `tools` | `readonly EditorTool[]` | common formatting | no | Visible schema-supported controls. Does not validate document policy. | no |
+| `headingLevels` | `readonly (1..6)[]` | schema levels | no | Levels in the text style menu. | no |
+| `insertItems` | `readonly EditorInsertItem[]` | `[]` | no | Consumer-labelled insertion callbacks. | no |
+| `variables` | `readonly EditorVariable[]` | `undefined` | no | Registry metadata; Root adds key-only atom unless extensions are replaced. | no |
+| `mentions` | `readonly EditorMention[]` | `undefined` | no | User IDs/labels; picker and @ suggestions. Custom schemas add the mention extension. | no |
 
 ### `RichTextEditor.Content` props
 
@@ -133,7 +149,7 @@ All other `React.ButtonHTMLAttributes<HTMLButtonElement>` are forwarded to `Rich
 | Root / Shell | `dsx-rich-text-editor` | `rich-text-editor.css` |
 | Toolbar | `dsx-rich-text-editor__toolbar` | `rich-text-editor.css` |
 | Toolbar group | `dsx-rich-text-editor__toolbar-group` | `rich-text-editor.css` |
-| Toolbar label | `dsx-rich-text-editor__toolbar-label` | `rich-text-editor.css` |
+| Optional custom toolbar label | `dsx-rich-text-editor__toolbar-label` | `rich-text-editor.css` |
 | Toolbar button | `dsx-rich-text-editor__toolbar-button` | `rich-text-editor.css` |
 | Content area | `dsx-rich-text-editor__area` | `rich-text-editor.css` |
 | Placeholder | `dsx-rich-text-editor__placeholder` | `rich-text-editor.css` |
@@ -156,12 +172,12 @@ All other `React.ButtonHTMLAttributes<HTMLButtonElement>` are forwarded to `Rich
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. None of its prop defs are `responsive: true`.
+- The component has no viewport-width media rules. None of its prop defs are `responsive: true`.
 - The component's CSS file is breakpoint-agnostic.
 
 **Reduced motion:**
 
-- The shell and toolbar transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. The CSS file does not include a `prefers-reduced-motion` gate; the global stylesheet is expected to honor the media query.
+- The shell and toolbar transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. Its own `prefers-reduced-motion` gate disables these transitions.
 
 ## Token mapping
 
@@ -178,15 +194,15 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Shell focus border | `var(--dsx-color-primary)` | Focus edge. |
 | Shell focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator. |
 | Shell disabled | `var(--dsx-color-disabled-border)`, `var(--dsx-color-disabled-surface)`, `var(--dsx-color-disabled-text)` | Disabled state. |
-| Toolbar gap | `var(--dsx-space-xs)` | Button spacing. |
+| Toolbar gap | `var(--dsx-space-sm)` / `var(--dsx-space-md)` | Space separates tool groups. |
 | Toolbar padding | `var(--dsx-space-sm)` / `var(--dsx-space-md)` | Internal gutter. |
 | Toolbar border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Bottom edge. |
 | Toolbar background | `var(--dsx-color-surface-editor-toolbar)` | Toolbar surface. |
-| Toolbar group border | `var(--dsx-border-width-sm)` + `var(--dsx-color-panel-border-translucent)` | Group edge. |
+| Toolbar group border | none | Groups use proximity. |
 | Toolbar group radius | `var(--dsx-rounded-md)` | Group corner roundness. |
-| Toolbar group background | `var(--dsx-effect-gray-alpha-3)` | Group surface. |
+| Toolbar group background | transparent | No separate frame. |
 | Toolbar label typography | `var(--dsx-typography-label-small-*)` | Group label. |
-| Toolbar button size | `var(--dsx-density-control-height-sm)` | Button tap target. |
+| Toolbar button size | `var(--dsx-density-control-height-lg)` | Button tap target. |
 | Toolbar button active | `var(--dsx-color-high-contrast)` + `var(--dsx-color-on-high-contrast)` | Active background and text. |
 | Content area min-height | `var(--dsx-rich-text-editor-min-height, 220px)` | Minimum editor height. |
 | Content area background | Gradient using `var(--dsx-color-surface-raised)` and `var(--dsx-color-surface)` | Subtle gradient. |
@@ -194,19 +210,20 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | ProseMirror typography | `var(--dsx-typography-body-medium-*)` | Body text. |
 | ProseMirror heading | `var(--dsx-typography-headline-medium-*)` | H1/H2. |
 | ProseMirror H3 | `var(--dsx-typography-label-large-*)` | H3. |
-| ProseMirror blockquote | `var(--dsx-color-primary)` (border), `var(--dsx-effect-hover-primary)` (bg) | Blockquote style. |
-| ProseMirror code | `var(--dsx-color-background)` + `var(--dsx-color-primary-container)` | Inline code. |
-| ProseMirror pre | `var(--dsx-color-background)` + `var(--dsx-color-on-background)` | Code block. |
+| ProseMirror blockquote | `var(--dsx-color-accent-border)` (1px border), `var(--dsx-effect-hover-primary)` (bg) | Decorative quotation rule and wash. |
+| ProseMirror code | `var(--dsx-code-soft-background)` + `var(--dsx-color-on-surface)` | Readable inline code. |
+| ProseMirror pre | `var(--dsx-code-soft-background)` + `var(--dsx-color-on-surface)` | Code block. |
 | Status bar | `var(--dsx-color-surface-editor-subtle)` + `var(--dsx-color-on-surface-variant)` | Status surface and text. |
 | Transition | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Hover and focus transitions. |
+| Link popover width | `var(--dsx-rich-text-editor-link-popover-width)` capped by Radix available width | Compact single-field form, independent of density and viewport breakpoints. |
 
 ## Motion contract
 
 | Region | Token | Default | Reduced |
 |---|---|---|---|
-| Shell border, background, shadow, color | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Transition on hover, focus, and disabled | Relies on the global `prefers-reduced-motion` stylesheet. |
-| Toolbar background, border | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Transition on state change | Relies on the global `prefers-reduced-motion` stylesheet. |
-| Content area background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Transition on disabled | Relies on the global `prefers-reduced-motion` stylesheet. |
+| Shell border, background, shadow, color | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Transition on hover, focus, and disabled | Own CSS disables transitions under prefers-reduced-motion. |
+| Toolbar background, border | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Transition on state change | Own CSS disables transitions under prefers-reduced-motion. |
+| Content area background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Transition on disabled | Own CSS disables transitions under prefers-reduced-motion. |
 
 ## Accessibility
 
@@ -220,9 +237,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Key | Action |
 |---|---|
-| `Tab` | Moves focus through the toolbar buttons and into the editor content. |
+| `Tab` | Enters or leaves the toolbar's roving focus group, then reaches editor content. |
 | `Enter`, `Space` | Activates the focused toolbar button. |
-| Arrow keys | The toolbar does not implement arrow-key navigation between buttons. The ProseMirror editor handles its own keyboard shortcuts (Mod-B for bold, Mod-I for italic, etc.). |
+| Arrow keys / Home / End | Existing Toolbar supplies roving focus between enabled actions. ProseMirror keeps its own Mod-B / Mod-I shortcuts. |
 
 **Focus:**
 
@@ -230,7 +247,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Reduced motion:**
 
-- Transitions on the shell, toolbar, and content area are expected to collapse under the global `prefers-reduced-motion` stylesheet.
+- Own `prefers-reduced-motion` rules disable shell, toolbar, group, button and content-area transitions.
 
 **Color and meaning:**
 
@@ -268,6 +285,16 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|---|
 | `disabled` | boolean | `false` |
 
+## Review examples and retained behavior
+
+The default toolbar composes the existing Toolbar and Button. Groups always
+wrap inside narrow hosts; no width breakpoints. Root and ToolbarButton aliases
+are attached as documented. Function-valued editorProps.attributes are evaluated
+and merged with the DS class/slot, retaining app labels and dynamic attributes.
+Images remain bounded; preformatted content scrolls. The live example exposes
+formatting, lock/unlock with retained edits, preview, editable materials, broadcast variables and a
+custom toolbar; app-owned Shell behavior is covered by the functional suite.
+
 ## Wiring notes
 
 **Composes from:**
@@ -291,3 +318,26 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 - App-owned data: the editor schema, the extension set, the serialization format, the content persistence, the `onUpdate` handler, and the toolbar override.
 - DS-owned visuals: token bindings, the `dsx-rich-text-editor` class hierarchy, the `data-disabled` and `data-active` attributes, the toolbar `aria-label` templates, the status bar text, and the placeholder rendering.
+
+## Authoring enhancement — approved 2026-10-04
+
+Root, Shell and Toolbar accept `tools` (formatting tool names), `headingLevels`,
+`insertItems` (`id`, `label`, `insert(editor)`), `variables` (`key`, `label`, optional
+`description`, `type`, `sensitive`) and `mentions` (`id`, `label`). Defaults retain
+common formatting; the text style menu uses headings supported by the schema.
+`tools` configures controls, not document validation. Consumers configure their
+extensions to enforce policy. Link editing uses a labelled DS popover with URL
+validation, save/remove, Escape and selection preservation. Insert entries are
+consumer supplied. Toolbar groups wrap at every width.
+
+The link form uses a label-large title, medium action buttons with a size-2xl
+minimum, and a 320px content width capped by available space. Its explanatory
+description remains accessible through VisuallyHidden; the visible title and URL
+label identify the task. Variable/mention pickers retain their larger layout.
+
+`createVariableExtension({ variables })` and `createMentionExtension({ mentions })`
+are optional editor exports. Inline atoms store `key` / `userId`, preserve HTML/JSON
+and undo, display registry labels, and visibly mark unknown keys. Root adds these
+when registries are provided unless `extensions` is a complete replacement; custom
+schemas add them explicitly. No variable resolution, upload or backend serializer
+is supplied. Registry changes do not recreate the managed editor.

package/dist/docs/components/scroll-area.md

@@ -45,7 +45,7 @@ The `Root` slot mounts the `Viewport`, both `ScrollBar` slots, and the `Corner`
 |---|---|---|---|---|---|
 | `asChild` | `boolean` | `false` | no | Extracted from prop defs but the `Root` host always renders a `<div>`. The prop is reserved for future use. | no |
 | `viewportAsChild` | `boolean` | `false` | no | When `true`, the children passed to the root are rendered directly inside the viewport via `Slot`. When `false`, the children are wrapped in a fragment. Use `true` when the scrollable content needs to be the viewport child directly so the host element's own classes do not block overflow inheritance. | no |
-| `size` | `'1' \| '2' \| '3'` | `'1'` | no | Drives `data-size` on the root. Reserved for token-driven scrollbar width variants; the default CSS does not consume the value beyond writing the attribute. | no |
+| `size` | `'1' \| '2' \| '3'` | `'1'` | no | Drives `data-size` on the root. Selects scrollbar thickness: 1 uses scroll-thumb-size, 2 uses 8px, 3 uses 10px. | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | no | Drives `data-radius` on the root. The CSS file consumes `data-radius` on `.dsx-scroll-area` to control the corner roundness inherited by the viewport. | no |
 | `viewportClassName` | `string` | `undefined` | no | Extra classes appended to the `Viewport` slot. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-scroll-area`. | no |
@@ -94,7 +94,7 @@ The slot also accepts the full `ComponentPropsWithoutRef<typeof ScrollAreaPrimit
 | `data-state` (Radix) | `visible`, `hidden`, `hover`, `scroll` | `.dsx-scroll-area__scrollbar[data-state='visible']` | `scroll-area.css` |
 | `data-orientation` (Radix) | `vertical`, `horizontal` | `.dsx-scroll-area__scrollbar[data-orientation='vertical']`, `.dsx-scroll-area__scrollbar[data-orientation='horizontal']` | `scroll-area.css` |
 
-The `data-size` and `data-radius` attributes are not consumed by the default CSS; they are forward-looking hooks for token-driven size and radius variants.
+Both size and radius attributes drive the existing CSS variants.
 
 **Slot classes:**
 
@@ -118,12 +118,12 @@ The `data-size` and `data-radius` attributes are not consumed by the default CSS
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. None of its prop defs are `responsive: true`.
+- The component has no viewport-width media rules. None of its prop defs are `responsive: true`.
 - The component's CSS file is breakpoint-agnostic.
 
 **Reduced motion:**
 
-- The scrollbar background and thumb transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. The CSS file does not include a `prefers-reduced-motion` gate; the global stylesheet is expected to honor the media query. The scroll motion itself is owned by the Radix primitive and respects the user's reduced-motion preference.
+- The scrollbar background and thumb transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. Its own `prefers-reduced-motion` gate disables scrollbar and thumb transitions. The scroll motion itself is owned by the Radix primitive and respects the user's reduced-motion preference.
 
 ## Token mapping
 
@@ -152,15 +152,15 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Region | Token | Default | Reduced |
 |---|---|---|---|
-| Scrollbar background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Background transition on visibility change. | Relies on the global `prefers-reduced-motion` stylesheet. |
-| Thumb background and opacity | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Thumb color and opacity transition. | Relies on the global `prefers-reduced-motion` stylesheet. |
+| Scrollbar background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Background transition on visibility change. | Own CSS disables the transition under `prefers-reduced-motion`. |
+| Thumb background and opacity | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Thumb color and opacity transition. | Own CSS disables the transition under `prefers-reduced-motion`. |
 | Scroll motion | owned by Radix | The scroll motion is the user's pointer or keyboard input; the package does not add its own scroll animation. | Honored by the browser and the Radix primitive. |
 
 ## Accessibility
 
 **Roles:**
 
-- The viewport and the scrollbar inherit the `role="region"` and `role="scrollbar"` semantics from `@radix-ui/react-scroll-area`. `aria-orientation` and `aria-valuenow` reflect the current scroll position and orientation.
+- Radix preserves native scrolling; its custom tracks are not ARIA scrollbar widgets. A named root makes its auto-mounted viewport tabIndex=0 with an inset focus ring and forwards aria-label/aria-labelledby to its auto-mounted viewport and gives that viewport role=region. Unnamed composite regions do not gain a tabindex attribute. Explicit Viewport props control their own tabIndex.
 
 **Keyboard:**
 
@@ -173,11 +173,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Focus:**
 
-- Focus on the scrollable content uses the host application's focus styles. The DS does not add a custom focus ring; apps that need a custom ring can target `.dsx-scroll-area__viewport:focus-visible` from the host.
+- The viewport paints an inset `var(--dsx-border-width-md)` ring using `var(--dsx-color-primary)` on `:focus-visible`.
 
 **Reduced motion:**
 
-- The scrollbar transitions collapse under the global `prefers-reduced-motion` stylesheet. The scroll motion is owned by the browser and respects the user's reduced-motion preference.
+- The scrollbar and thumb transitions are disabled by their own `prefers-reduced-motion` rules. The scroll motion is owned by the browser and respects the user's reduced-motion preference.
 
 **Color and meaning:**
 
@@ -214,6 +214,14 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | `radius` | select (`none`, `sm`, `md`, `lg`, `full`) | `md` |
 | `viewportAsChild` | boolean | `false` |
 
+## Review examples
+
+Activity history scrolls vertically; Regional comparison scrolls on both axes.
+Keyboard PageDown/arrows, wheel, named viewport and visible focus are verified
+at desktop and 390/320. Root auto-mounts its viewport; do not nest another one
+unless intentionally composing a second scroll region. Reduced motion disables
+track/thumb transitions in this component CSS.
+
 ## Wiring notes
 
 **Composes from:**

package/dist/docs/components/section.md

@@ -127,46 +127,11 @@ Section has no motion. The motion section is intentionally empty.
 
 - Section is a structural landmark. The accessible name should come from a heading inside the section, an `aria-label`, or an `aria-labelledby` reference.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders `Section` with no extra props and a child node. Asserts the root classes are `dsx-section` and `dsx-box`, the host element is a `section`, and `--dsx-section-space` resolves to `var(--dsx-space-2xl)`.
-
-**Size story:**
-
-- Renders `Section size="1"`, `Section size="2"`, and `Section size="3"`. Asserts the `data-size` attribute and the matching `--dsx-section-space` value (`var(--dsx-space-md)`, `var(--dsx-space-xl)`, `var(--dsx-space-2xl)`).
-
-**Space story:**
-
-- Renders `Section space="md"` and asserts `--dsx-section-space` resolves to `var(--dsx-space-md)`.
-
-**Responsive story:**
-
-- Renders `Section size={{ initial: '1', md: '3' }}` and `Section space={{ initial: 'md', lg: '2xl' }}`. Asserts the per-breakpoint `--dsx-section-space-*` custom property and the matching `padding-block` resolution.
-
-**Composition story:**
+The matrix and live example use the same outlined content bounds. All three sizes clear space overrides and visibly expose 16/32/48px above and below the content.
 
-- Renders `Section` with two `Box` children showing different surface tones. Asserts the children keep their own `dsx-box` class and inherit the Section's block padding.
-
-**State story:**
-
-- No discrete state. The story renders a default Section with two children.
-
-**Token story:**
-
-- Section does not honor `data-accent-color`. Render inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. The story asserts the layout is unchanged and any surfaces come from the theme.
-
-**A11y story:**
-
-- Use `vitest-axe` against the rendered Section. The default render is a `<section>` with text content; tests assert no violations.
-
-**Props exposed in the playground controls:**
+## Playground demo spec
 
-| Prop | Control | Default |
-|---|---|---|
-| `size` | select | `undefined` |
-| `space` | select | `2xl` |
+The size matrix and live gallery use outlined content bounds with identical horizontal padding. Each explicitly clears space so size 1/2/3 shows 16/32/48px above and below the content. The live content explains what the dashed boundaries mark. Section remains an ordinary named page region, not an interactive control.
 
 ## Wiring notes
 

package/dist/docs/components/segmented-control.md

@@ -13,7 +13,7 @@ depends_on:
 
 ## Purpose
 
-A single-select control that renders a row of mutually exclusive options, backed by `ToggleGroup` from Radix. `default` is a sunken track with a sliding softly tinted raised pill behind the active option; `outline` is the same pill inside an outer frame; `subtle` is the borderless treatment with the same selected pill. Used for switching between views, filters, or modes in forms and toolbars.
+A single-select control that renders a row of mutually exclusive options, backed by `ToggleGroup` from Radix. `default` is a sunken track with a sliding softly tinted raised pill behind the active option; `outline` is the same pill inside an outer frame; `subtle` is the borderless treatment with the same selected pill. Used for switching between views, filters, or modes in forms and toolbars. Boundary rule (F6 brief): exclusive single-select with a thumb is always a SegmentedControl; frameless toolbar button clusters without a thumb are `ToggleGroup`. Never multi-select, never dismissible.
 
 ## Anatomy & slots
 
@@ -34,7 +34,9 @@ A single-select control that renders a row of mutually exclusive options, backed
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and item padding; writes `data-size` and `dsx-segmented-control--{size}` class. | no |
 | `variant` | `'default' \| 'outline' \| 'subtle'` | `'default'` | no | Container surface treatment; writes `data-variant` and `dsx-segmented-control--{variant}` class. `subtle` keeps the measured selected pill but removes the track surface and frame. | no |
 | `activationMode` | `'manual' \| 'automatic'` | `'manual'` | no | Selection timing; writes `data-activation-mode`. `manual` selects only on activation (click, `Enter`, `Space`). `automatic` selects on item focus, so arrow-key navigation selects without `Enter`. | no |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Stacking axis; writes `data-orientation`. Vertical stacks icon columns (ref: view-switcher rails); the sliding indicator measures y/height and arrow keys move up/down via Radix. | no |
 | `disabled` | `boolean` | `false` | no | Disables the entire control; writes `data-disabled`. | no |
+| `fill` | `boolean` | `false` | no | Distributes the track width equally across items; writes `data-fill` and `dsx-segmented-control--fill`; both selectors share the same fill styling. Opt-in for few-item groups that fit (method pickers); the default hug-content root with scroll containment stays for overflowing groups. The sliding indicator measures live boxes, so it tracks fill widths with no change. | no |
 | `value` | `string` | `undefined` | no | Controlled selected value. | no |
 | `defaultValue` | `string` | `undefined` | no | Uncontrolled initial selected value. | no |
 | `onValueChange` | `(value: string) => void` | `undefined` | no | Callback when the selected value changes. | no |
@@ -53,13 +55,13 @@ A single-select control that renders a row of mutually exclusive options, backed
 
 Rules:
 
-- `size` and `disabled` are wired through `extractProps` and the prop def bag on the Root. `variant` and `activationMode` are destructured with their defaults and kept out of the extract bag (their defs declare no `className`, so they would otherwise leak onto the DOM).
+- `size` and `disabled` are wired through `extractProps` and the prop def bag on the Root. `variant`, `activationMode`, and `fill` are destructured with their defaults and kept out of the extract bag (their defs declare no `className`, so they would otherwise leak onto the DOM); `fill` writes `data-fill` plus the `--fill` modifier class manually, same as `variant`.
 - `value`, `defaultValue`, and `onValueChange` are passed through to the Radix ToggleGroup root directly.
 - The Root forces `type="single"` and filters empty string values from `onValueChange` to prevent deselection.
 - Deselect guard: the Root owns the selection state. Uncontrolled usage seeds internal state from `defaultValue` and passes the resolved value back into Radix as a controlled `value`, so clicking the active item (which fires `""`) can never clear Radix internal state or render the control with no active item. Controlled usage passes `value` straight through; `""` is still swallowed.
 - Activation mode: in `automatic` mode each item's `onFocus` selects its own value when it differs from the current value (the item reads the mode and the current selection from an internal Root context; Radix strips the `value` prop from the DOM, so the Root cannot recover the focused value from the event target). The focus value goes through the same guarded setter, so focus can never empty the selection and tabbing into the group (which lands on the already-selected item) is a no-op. Disabled items never select on focus. In `manual` mode (default) focus never selects; selection happens only on activation. Consumer `onFocus` handlers on the Root and on items keep working in both modes.
 - Choosing a mode: `automatic` is the radio-faithful choice for lightweight view/filter/mode switching. `manual` is required when `onValueChange` drives expensive side effects (network requests, navigation, heavy recompute) that must not fire on focus or hover.
-- Indicator geometry: the Root measures the active `[data-state="on"]` item with `getBoundingClientRect` in a layout effect (before first paint), re-measures on selection change and via `ResizeObserver` on the root and the active item. The offset is a physical-pixel diff (`active.left - root.left`), which is direction-agnostic and therefore RTL-correct without special-casing. A ready gate holds `transition: none` until the first positioned frame so mount never animates from the origin. Variable-width items are required; the indicator wrapper tracks each item's own width (no equal-width `nth-child` CSS), while its painted `::before` surface keeps a symmetric `space-2xs` inset inside that measured wrapper.
+- Indicator geometry: the Root measures the active `[data-state="on"]` item with `getBoundingClientRect` in a layout effect (before first paint), re-measures on selection change and via `ResizeObserver` on the root and the active item. The offset converts the physical-pixel viewport diff into content coordinates (`active.left - root.left - clientLeft + scrollLeft`, and the equivalent top/clientTop/scrollTop calculation). The pill then moves with the scrolled content instead of shifting twice. Physical coordinates remain independent of writing direction. A ready gate holds `transition: none` until the first positioned frame so mount never animates from the origin. Variable-width items are required; the indicator wrapper tracks each item's own width (no equal-width `nth-child` CSS), while its painted `::before` surface keeps a symmetric `space-2xs` inset inside that measured wrapper.
 
 ## CSS class contract
 
@@ -72,6 +74,8 @@ Rules:
 | `data-size` | `sm`, `md`, `lg` | `.dsx-segmented-control--sm`, `.dsx-segmented-control--md`, `.dsx-segmented-control--lg` | `segmented-control.css` |
 | `data-variant` | `default`, `outline`, `subtle` | `.dsx-segmented-control--default`, `.dsx-segmented-control--outline`, `.dsx-segmented-control--subtle` | `segmented-control.css` |
 | `data-disabled` | (present/absent) | `.dsx-segmented-control[data-disabled]` | `segmented-control.css` |
+| `data-orientation` | `horizontal`, `vertical` | `.dsx-segmented-control[data-orientation='vertical']` (column stack; indicator measures y/height) | `segmented-control.css` |
+| `data-fill` | (present/absent) | `.dsx-segmented-control--fill` (root spans the container, items share width equally) | `segmented-control.css` |
 
 **Slot classes:**
 
@@ -230,6 +234,7 @@ Automatic mode (`activationMode="automatic"`):
 | `variant` | select | `default` |
 | `activationMode` | select | `manual` |
 | `disabled` | boolean | `false` |
+| `fill` | boolean | `false` |
 
 ## Wiring notes
 

package/dist/docs/components/segmented-meter.md

@@ -124,6 +124,8 @@ Rules:
 **Size story:**
 
 - Renders `size="sm"`, `size="md"`, `size="lg"`. Asserts the matching `data-size`.
+- The matrix supplies a bounded 160px consumer host, capped at available width,
+  so every segment has nonzero width. The package continues to fill its parent.
 
 **State story:**
 
@@ -202,3 +204,10 @@ Rules:
 - [ ] Token bindings resolve at the values `DESIGN.md` describes.
 - [ ] Component is promoted to Main Component under `Primitives`.
 - [ ] Segment height matches `Progress`'s height at every `size` exactly.
+
+## Reconciliation stories
+
+The playground manifest includes `segmented-meter` so the registered family is
+reachable from `/docs/segmented-meter` and the documentation index.
+
+The live capacity example shows all three heights for the same controlled value, visible n-of-m text, use/release actions, and empty/full references. The meter is read-only; controls belong to the consumer.

package/dist/docs/components/select.md

@@ -176,7 +176,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Content padding | `var(--dsx-space-sm)` | Floating menu inner gutter. |
 | Content width / min-width / max-width | `max-content` / `var(--radix-select-trigger-width, 200px)` / `min(--radix-select-content-available-width, 40rem)` | Mirror-at-minimum with grow-to-fit; past 40rem (or the viewport edge) rows wrap via `data-overflow` instead of stretching the panel. The 40rem ceiling is a token candidate for the size batch. |
 | Content max-height | `var(--dsx-size-popover-max-width)` | Scroll ceiling (used by the inner ScrollArea). |
-| Content z-index | `var(--dsx-z-index-dropdown)` | Overlay stacking. |
+| Content z-index | `var(--dsx-z-index-dropdown)` standalone; `calc(var(--dsx-z-index-modal, 90) + 2)` when nested inside a modal-tier host (`dsx-menu__nested`, see the shared nested floating tier contract in `menu.md`) | Overlay stacking; nested menus clear their host popup. |
 | Item min-height | `var(--dsx-size-lg)` | Default option height. |
 | Item padding | density-aware block/inline tokens with trailing indicator reservation | Option padding; the right side reserves room for the trailing check indicator. |
 | Item border | `0` | Items are borderless. |
@@ -295,7 +295,8 @@ Rules:
 - `VisuallyHidden` (DS primitive): the hidden native `<select>` host.
 - `Icon` (lucide-react `chevron-down`): the trigger trailing icon. Lucide-react `check` is the item indicator.
 - `_internal/BaseDialog`: `PortalThemeBoundary` (wraps the root) and `PortalThemeWrapper` (wraps the content) so `data-dsx-theme`, `data-dsx-density`, `data-dsx-scaling`, `data-accent-color`, `data-gray-color`, `data-radius`, `data-panel-background`, `data-has-background`, and `colorScheme` resolve inside the content portal.
-- `_internal/baseMenu.css`: the shared menu shell, border, surface, and focus contract.
+- `_internal/baseMenu.css`: the shared menu shell, border, surface, and focus contract — including the nested floating tier rule (`dsx-menu__nested` at `modal + 2`).
+- `_internal/floatingLayer`: `useFloatingLayerHost` tells `Select.Content` whether it renders inside a modal-tier host (`Popover.Content` / `Dialog.Content`); when nested, the content adds `dsx-menu__nested` so the options list paints above its host. Standalone content never carries the class and stays at the dropdown tier, below the modal overlay.
 - `@radix-ui/react-slot`: enables `asChild` on `Select`, `Select.Trigger`, and `Select.Content`.
 
 **Used by:**