@d4gger/design-system 3.0.0 → 4.0.0

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

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

package/dist/docs/components/container.md

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

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

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

package/dist/docs/components/copy-field.md

@@ -42,7 +42,7 @@ Root `dsx-copy-field`; value input `dsx-copy-field__input`; action `dsx-copy-fie
 
 ## Token mapping
 
-CopyField paints no new colors. Its only local sizing uses `var(--dsx-copy-field-action-min-width)` and spacing inherited from Field/InputGroup.
+CopyField paints no new colors. Its only local sizing uses `var(--dsx-copy-field-action-min-width)` and spacing inherited from Field/InputGroup. The copy action is a direct InputGroup child: join, radii, and height are group-owned, and it inherits the field-shell outline token (`--dsx-boundary-control-color`) at rest and hover, so the group reads as one frame. The read-only value half invites no hover: shell keeps its resting border/background under hover, cursor stays default.
 
 ## Motion contract
 
@@ -54,7 +54,7 @@ The label is connected with generated IDs. The input is read-only rather than di
 
 ## Playground demo spec
 
-Show default, all sizes, disabled, with/without description, full composition, clipboard success, light/dark, and alternate accents. Test clipboard success/failure and `vitest-axe`.
+Show default, all sizes, disabled, with/without description, full composition, clipboard success, light/dark. Theme/accent switching belongs to the config drawer — no per-component theme/accent stories. Test clipboard success/failure and `vitest-axe`.
 
 ## Wiring notes
 

package/dist/docs/components/data-list.md

@@ -9,6 +9,8 @@ depends_on:
 
 # DataList
 
+Content regions use an intrinsic `8rem` flex basis, so sibling label/value regions wrap as readable blocks when they cannot fit together. The consumer can override the basis through ordinary style composition for a compact media row. No viewport breakpoint selects the arrangement.
+
 > Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
@@ -47,7 +49,7 @@ A structured list surface for metadata, attributes, or settings rows that render
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` | no | Item surface treatment; writes `data-variant`. | no |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | no | Item min-height; writes `data-size`. | no |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | no | Item min-height and vertical padding; writes `data-size`. | no |
 | `interactive` | `boolean` | `false` | no | When `true`, adds pointer cursor and hover styles; writes `data-interactive="true"`. | no |
 | `text` | `React.ReactNode` | `undefined` | no | Structured primary text content. | no |
 | `metadata` | `React.ReactNode` | `undefined` | no | Structured secondary text content. | no |
@@ -68,7 +70,9 @@ Rules:
 - `listType` and `asChild` on Root are wired through `extractProps`.
 - `variant`, `size`, and `interactive` on Item are wired through `extractProps`.
 - When `text`, `metadata`, `icon`, or `badge` props are provided on Item, the component renders structured content automatically. Otherwise, `children` are rendered directly.
-- Ordered lists use a CSS counter (`dsx-data-list-counter`) for markers; unordered lists use a bullet (`\2022`).
+- Ordered lists use a CSS counter (`dsx-data-list-counter`) for markers; unordered lists use a drawn dot (see below).
+- Item body wraps intrinsically and centers its slots vertically; `Media` keeps top alignment (`align-self: flex-start`) so icons/avatars anchor against multi-line text while text, badge, marker, and actions share one center line.
+- The unordered marker is a drawn dot (radial fill at a fixed fraction of the marker box), so it scales with item size for free; ordered numerals stay text (counter) at natural size. A text bullet glyph was tried and rejected: growing `font-size` compounds (the box's `em` resolves against the pseudo-element's own font-size), and the glyph renders font-dependent small.
 
 ## CSS class contract
 
@@ -107,6 +111,8 @@ Rules:
 
 - The component does not write `@media` rules. Size and variant are single-value only.
 
+- Primary and secondary text use `overflow-wrap: anywhere` so emails and identifiers stay inside their content column at narrow widths. The centered slot alignment and top-anchored media remain unchanged.
+
 **Reduced motion:**
 
 - Item body transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)` for background-color, box-shadow, and color. No explicit `prefers-reduced-motion` gate in the CSS.
@@ -198,7 +204,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Composition story:**
 
-- Renders items using children-based composition with `DataList.Media`, `DataList.Content`, `DataList.Text`, `DataList.Metadata`, `DataList.Badge`, and `DataList.Actions` slots all populated.
+- Renders items using children-based composition with `DataList.Media`, `DataList.Content`, `DataList.Text`, `DataList.Metadata`, `DataList.Badge`, and `DataList.Actions` slots all populated. The profile example includes a working CopyButton for its email; a consumer-owned content basis keeps media and content together at narrow widths.
 
 **Token story:**
 
@@ -236,3 +242,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 - App-owned data: the list items, the item content, the action handlers, and the host element when `asChild` is set.
 - DS-owned visuals: token bindings, the `dsx-data-list` root class, the slot classes, and the `data-*` attribute contract.
+
+## Maintainer follow-up, 2026-10-03
+
+DataList represents ordered/unordered entries, not a semantic description list. The roster keeps Description List as a separate candidate. Playground examples show one primary text and subordinate metadata inside one Content slot per entry, with meaningful team and connection-priority lists. Two equal Content siblings are not the default example. The media/badge/action composition remains available.
+
+Item vertical padding scales with xs/sm/md/lg through space-xs/sm/md/lg, so identical content reveals actual density differences instead of masking the minimum-height scale.