@d4gger/design-system 3.0.1 → 4.0.0

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

@@ -61,7 +61,7 @@ Rules:
 - 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
 

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/separator.md

@@ -28,7 +28,7 @@ No slots: flat export. The component renders a single Radix `SeparatorPrimitive.
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Sets `data-orientation` on the host and the matching CSS rule. | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Reserved hook for the `data-size` attribute. The current CSS only uses the orientation attribute to size the line; `data-size` is the contract for future per-size thickness overrides. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Retained data-size hook; all sizes paint the canonical 1px non-emphasis divider. | no |
 | `variant` | `'default' \| 'decorative'` | `'default'` | no | When `'decorative'`, applies the `dsx-separator--decorative` modifier class. | no |
 | `color` | `string` | `undefined` | no | Free-form accent color name forwarded to `data-accent-color` on the host. | no |
 | `decorative` | `boolean` | `true` | no | Radix boolean: when true, the host is given `role="none"` and removed from the accessibility tree's semantic structure. When false, the host keeps `role="separator"`. | no |
@@ -39,7 +39,7 @@ Rules that apply to this row:
 
 - The component extends `React.ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>`, so every standard Radix `Separator.Root` attribute is forwarded.
 - `decorative` is the Radix accessibility opt-out. `Separator` defaults to `decorative={true}`; pass `decorative={false}` to expose the separator to assistive tech as a thematic break. The default is intentional: most separators are visual-only and the default should not add noise to the accessibility tree.
-- The CSS file does not yet read `data-size`; the attribute is the public contract for future per-size thickness overrides and is asserted by the test suite.
+- Size does not alter divider thickness; the 1px policy applies at every size.
 
 ## CSS class contract
 
@@ -51,8 +51,8 @@ Rules that apply to this row:
 |---|---|---|---|
 | `data-orientation` | `horizontal`, `vertical` | `.dsx-separator[data-orientation='horizontal']`, `.dsx-separator[data-orientation='vertical']` | `separator.css` |
 | (no attribute) | (presence) | `dsx-separator--decorative` when `variant === 'decorative'` | `separator.css` |
-| `data-size` | `sm`, `md`, `lg` | reserved for future thickness overrides | `separator.css` (no rule yet) |
-| `data-accent-color` | (any accent token name) | reserved for future accent overrides | `separator.css` (no rule yet) |
+| `data-size` | `sm`, `md`, `lg` | retained attribute; fixed 1px paint | `separator.css` |
+| `data-accent-color` | (any accent token name) | decorative accent-border paint | `separator.css` |
 
 **Slot classes:** none.
 
@@ -72,9 +72,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|---|
 | Background (default) | `var(--dsx-control-separator-color-strong)` | Default line color. |
 | Background (decorative) | `var(--dsx-color-separator-muted)` | Muted line color for the `decorative` variant. |
+| Background (explicit color) | `var(--dsx-color-accent-border)` | Decorative accent rule; overrides the neutral variant color. |
 | Margin block (horizontal) | `var(--dsx-space-sm)` | Vertical breathing room around a horizontal line. |
 | Margin inline (vertical) | `var(--dsx-space-xs)` | Horizontal breathing room around a vertical line. |
-| Border width | `var(--dsx-border-width-md)` (default `var(--dsx-border-width-sm)`) | The painted line thickness. |
+| Border width | `var(--dsx-boundary-divider-width)` | The painted line thickness. |
 | Min height (vertical) | `var(--dsx-size-lg)` | Minimum line length for the vertical orientation. |
 
 Rules:
@@ -82,6 +83,7 @@ Rules:
 - No raw color, spacing, radius, or motion values in `separator.css`. The line is a `background` of the host; it is not a border.
 - The default and decorative variants use different tokens. The decorative token is intentionally lighter; the default token is the strong control line color.
 - Alpha is not used. The line colors are solid.
+- Neutral default/decorative dividers deliberately retain their gray colors across accents. Explicit accent dividers use accent-border: step 8 in light appearance and step 11 in dark appearance. Readable ink, focus and selection retain accent-indicator. Neutral aliases rebind to the nearest appearance and gray boundary.
 
 ## Motion contract
 
@@ -120,49 +122,11 @@ Rules:
 
 - The separator does not need an accessible name. The Radix primitive handles `aria-hidden` and `role` based on `decorative`. Pair a non-decorative separator with surrounding landmarks (headings, sections) so the thematic break is announced in context.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders `Separator`. Asserts the host has `dsx-separator`, `data-orientation="horizontal"`, and `role="none"` (the default `decorative` flag strips the semantic role from the accessibility tree).
-
-**Orientation story** (one per orientation):
-
-- Renders Separator with `orientation="horizontal"` and `orientation="vertical"`. Asserts the matching `data-orientation` attribute and the matching CSS rule (width vs height).
-
-**Size story** (one per size):
-
-- Renders Separator with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` value on the host. The current CSS does not switch the painted thickness per size; the story documents that the attribute is the contract for future overrides.
-
-**Variant story** (one per variant):
-
-- Renders Separator with `variant="default"` and `variant="decorative"`. Asserts the `dsx-separator--decorative` modifier class is present on the decorative variant and absent on the default.
-
-**State story:**
+Matrix cells place each orientation between text, rather than rendering a free-floating line. Live examples show horizontal section division, vertical metadata division, decorative tone and the reserved data-accent-color hook.
 
-- Renders Separator with `decorative={false}`. Asserts the host has `role="separator"` instead of `role="none"`. For a non-decorative vertical separator, asserts `aria-orientation="vertical"` is also on the host.
-
-**Composition story:**
-
-- Renders Separator inside a `Flex` row to verify the vertical orientation has a meaningful min height and does not collapse to zero.
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the line color is unchanged across accents (the current CSS does not read `data-accent-color`; the story documents the contract for future accent overrides).
-
-**A11y story:**
-
-- Uses `vitest-axe` against a rendered default Separator. Asserts there are no axe violations.
-
-**Props exposed in the playground controls:**
+## Playground demo spec
 
-| Prop | Control | Default |
-|---|---|---|
-| `orientation` | select (`horizontal`, `vertical`) | `horizontal` |
-| `size` | select (`sm`, `md`, `lg`) | `md` |
-| `variant` | select (`default`, `decorative`) | `default` |
-| `color` | text | (empty) |
-| `decorative` | boolean | `true` |
+Matrix cells place horizontal or vertical lines between Overview and Details text with a bounded 220px frame. All size hooks remain shown and paint the canonical 1px thickness. The live example includes a horizontal section divider, vertical metadata divider, decorative tone, and an accent line using color="inherit" through the existing data-accent-color hook. The semantic divider uses decorative={false}; the other lines are decorative.
 
 ## Wiring notes
 

package/dist/docs/components/sidebar.md

@@ -74,6 +74,7 @@ The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset`
 | `mobileBreakpoint` | `number` | `768` | no | Viewport width below which the provider treats the device as mobile. The provider also matches `(pointer: coarse)`. | no |
 | `defaultSubmenuMode` | `'click' \| 'hover'` | `'click'` | no | Default toggle mode for every `Sidebar.MenuSubTrigger` under this provider. Individual triggers override per-section. | no |
 | `submenuOpenOnActive` | `boolean` | `true` | no | Default for `openOnActive` on every `Sidebar.MenuSubTrigger` under this provider. | no |
+| `variant` | `'default' \| 'floating'` | `'default'` | no | `floating` draws the inline panel as a rounded, bordered, shadowed glass surface set off from the viewport edge, with a gap around it and between it and the inset, over whatever the page paints behind. It never applies to the mobile drawer: while the sidebar renders as the drawer, the variant has no visual effect and `data-variant` reads `default`. Specified for `collapsible="icon"` and `"none"`; with `"offcanvas"` a collapsed panel hides without a border sliver, and the recovery rail keeps its default look. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-sidebar-provider`. | no |
 | `children` | `React.ReactNode` | `undefined` | no | Provider children. In mobile sheet mode, each Sidebar root preserves its named `<nav>` wrapper, classes, and consumer props inside `Sheet.Content`; sibling inset content remains inline. | no |
 
@@ -186,10 +187,11 @@ Standard React HTML attributes plus the `role="separator"` and `aria-orientation
 
 ### `useSidebar` hook
 
-Returns the `SidebarContext` value or a no-op fallback (`expanded: true`, `setExpanded: () => {}`, `mobileSheetOpen: false`, `setMobileSheetOpen: () => {}`, `isMobile: false`) when the consumer renders a sidebar slot outside `Sidebar.Provider`.
+Returns the `SidebarContext` value or a no-op fallback (`expanded: true`, `setExpanded: () => {}`, `mobileSheetOpen: false`, `setMobileSheetOpen: () => {}`, `isMobile: false`, `variant: 'default'`) when the consumer renders a sidebar slot outside `Sidebar.Provider`.
 
 Rules:
 
+- `variant` is the variant in effect, not the raw prop: `floating` only while the sidebar renders inline. The provider and the root write it as `data-variant`; `Sidebar.Inset` is deliberately unmarked and keeps no surface of its own, so the page behind the panel shows through.
 - The `data-state` and `data-collapsed` attributes are written by `getSidebarDataAttributes` and applied to the `Provider`, the `Root`, and every slot that reads from `useSidebar()`. The `data-state` value is `expanded` or `collapsed`.
 - `Sidebar.MenuButton` and `Sidebar.MenuSubButton` write `data-active` when `isActive` is `true` and wrap string or number children in `<span class="dsx-sidebar__menu-button-text">`. The wrapping span is omitted when `asChild` is set.
 - `Sidebar.Provider` registers a `keydown` listener on `document` for the toggle shortcut. The listener is removed on cleanup and is a no-op when `toggleShortcut` is `false`. The shortcut is `Ctrl+B` on Windows and Linux, `Cmd+B` on macOS.
@@ -215,7 +217,8 @@ Rules:
 | `data-pinned-state` | `expanded`, `collapsed` | Records the persisted/manual state while `data-state` may temporarily be `expanded` for a preview. | `sidebar.css` |
 | `data-transitions-ready` | `true`, `false` | Prevents persisted state hydration from replaying panel motion on route remount. | `sidebar.css` |
 | `data-effect` | `none`, `ambient` | Selects the Sidebar surface effect. | `sidebar.css` |
-| `data-variant` | `ring`, `accent` | Marks a proportional ring or quiet accent `MenuBadge`; text badges omit the attribute. | `sidebar.css` |
+| `data-variant` (provider, root) | `default`, `floating` | `.dsx-sidebar-provider:where([data-variant='floating'])`, `.dsx-sidebar[data-variant='floating']`: glass panel, offset and gap. Always written; `floating` only while the sidebar renders inline. | `sidebar.css` |
+| `data-variant` (`MenuBadge`) | `ring`, `accent` | Marks a proportional ring or quiet accent `MenuBadge`; text badges omit the attribute. | `sidebar.css` |
 | `data-active` | `true` | `.dsx-sidebar__menu-button[data-active='true']`, `.dsx-sidebar__menu-sub-button[data-active='true']` | `sidebar.css` |
 | `data-state` (sub-trigger) | `open`, `closed` | `:where(.dsx-sidebar__menu-sub-trigger[data-state='open']) > .dsx-sidebar__menu-sub-trigger-chevron { transform: rotate(90deg) }` with `transition-transform` (`:where` keeps it at 0,1,0) | `sidebar.css` |
 | `data-show-icon` | `true`, `false` | (icon visibility inside the skeleton) | `sidebar.css` |
@@ -287,6 +290,13 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Panel ambient effect | `var(--dsx-color-accent-9)` mixed with transparency | Optional subscription-aware accent wash without a literal starfield. |
 | Panel border | `none` (CSS keyword) | The slim shell uses surface contrast and elevation instead of a boxed edge. |
 | Panel shadow | `var(--dsx-effect-shadow-1)` | Panel elevation. |
+| Floating: provider padding and gap | `var(--dsx-space-3)` | The space around the panel and between the panel and the inset. Never a sidebar margin: the preview and pin-docking motion animate `margin-inline-end` and `width`. |
+| Floating: panel offset and height | `var(--dsx-space-3)` (`top`), `calc(100dvh - var(--dsx-space-3) - var(--dsx-space-3))` (`height`) | Keeps the sticky panel inside the same inset on every side. |
+| Floating: panel background | `var(--dsx-color-panel-translucent)` | Glass surface; the ambient effect's gradient still paints over it. |
+| Floating: panel backdrop | `var(--dsx-effect-panel-glass-backdrop-filter)` | Glass blur. |
+| Floating: panel border | `var(--dsx-border-width-sm) solid var(--dsx-panel-border-color)` | Glass edge; dropped (`border-width: 0`) when an `offcanvas` panel is collapsed so a zero-width panel leaves no sliver. |
+| Floating: panel radius | `var(--dsx-rounded-xl)` | Follows the global radius setting. |
+| Floating: panel shadow | `var(--dsx-panel-shadow)` | Floating elevation. |
 | Panel motion duration | `var(--dsx-motion-duration-normal, 250ms)` | Width transition. |
 | Panel motion easing | `var(--dsx-motion-easing-standard, ease)` | Width easing. |
 | Inset flex | `1` (CSS keyword) | Fill remaining width. |
@@ -392,6 +402,8 @@ Rules:
 
 - The panel landmark has a default `aria-label="Sidebar"`. The rail and trigger have default `aria-label` values (`Expand sidebar` / `Collapse sidebar`). Override the labels when the panel needs product-specific copy.
 
+Submenu parent triggers use `--dsx-rounded-sm`, matching navigation rows rather than the Button pill radius. The playground lab composes Sidebar.Inset with content that changes on navigation and utility actions, so active state has a visible result. The demo bounds its navigation height to 560px and reserves header clearance for the mobile menu control. Routing remains app-owned.
+
 ## Playground demo spec
 
 **Default story:**
@@ -402,6 +414,7 @@ Rules:
 
 - Renders the provider with `defaultExpanded={false}`. Asserts `data-state="collapsed"`, `data-collapsed="true"`, and the `dsx-sidebar-default-expanded` class on the panel.
 - Renders a composed fixture with `effect="ambient"` alongside the default `none` surface so the optional token-driven accent wash is visible in the Playground.
+- Renders the provider with `variant="floating"` and asserts `data-variant="floating"` on the provider and the root, no `data-variant` on `Sidebar.Inset`, and `data-variant="default"` while the sidebar renders as the mobile drawer. The docs lab toggles `default` / `floating` over the brand haze (`dsx-brand-ambient`), because a glass panel only reads as glass over something.
 
 **State story:**
 
@@ -427,6 +440,7 @@ Rules:
 | `defaultExpanded` | boolean | `true` |
 | `hoverExpand` | boolean | `false` |
 | `previewOpen` | boolean | `false` |
+| `variant` | select | `default` |
 
 ## Wiring notes
 
@@ -447,7 +461,7 @@ Rules:
 
 **State boundaries:**
 
-- Owned by `Sidebar`: the expanded / collapsed state, the temporary hover/focus preview, the persisted state in localStorage or cookies, the mobile detection, the global `Ctrl+B` / `Cmd+B` shortcut, the active menu button flag, the `data-state`, `data-collapsed`, `data-preview-expanded`, and `data-pinned-state` attributes, and the `data-active` attribute.
+- Owned by `Sidebar`: the expanded / collapsed state, the temporary hover/focus preview, the persisted state in localStorage or cookies, the mobile detection, the global `Ctrl+B` / `Cmd+B` shortcut, the active menu button flag, the `data-state`, `data-collapsed`, `data-preview-expanded`, `data-pinned-state` and `data-variant` attributes, and the `data-active` attribute.
 - Owned by the consumer: the route map, the active-page detection, the disabled reasons, the auth and permissions policy, and the persistence target.
 
 **Boundary rules:**