@d4gger/design-system 3.0.0 → 4.0.0

package/dist/docs/components/code.md

@@ -8,256 +8,69 @@ depends_on: []
 
 # Code
 
-> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+> Source of truth: the package source at `package_path`. The spec mirrors source in the same change.
 
 ## Purpose
 
-An inline monospace code token that renders a `<code>` element with a `variant` background and border treatment, a `tone` color override, a `size` scale, an optional `color` accent, a `highContrast` toggle, and the shared `asChild` infra. For multi-line code, compose inside a `<pre>`.
+Monospace inline code with four treatments, three genuine sizes, optional accent foreground, tone and high contrast. Multi-line code uses a consumer-owned `pre > Code` composition and an overflow container.
 
 ## Anatomy & slots
 
-**Parent:** `Code` (no compound; flat polymorphic export).
-
-**Slots:**
-
-No slots: flat export. The component renders a single `<code>` host element (or the consumer's host element when `as` or `asChild` is set) with the `dsx-code` root class, the variant modifier class, and any `tone` modifier class.
+A single `<code>` root with `dsx-code`; no compound slots. `asChild` slots a consumer host. Native code attributes and refs are forwarded.
 
 ## Props contract
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'solid' \| 'soft' \| 'outline' \| 'ghost'` | `'soft'` | no | Code treatment. Writes the `dsx-code--{variant}` modifier class and the `data-variant` attribute. `solid` paints a primary background; `soft` paints a sunken surface with an outline; `outline` paints a transparent background with an inset outline; `ghost` paints nothing. | no |
-| `tone` | `'default' \| 'muted' \| 'inverse'` | `'default'` | no | Tone modifier. Writes `dsx-code--{tone}` for `muted` and `inverse`. The CSS combines `dsx-code--solid.dsx-code--muted` and `dsx-code--soft.dsx-code--inverse` for tone-on-variant pairings. | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Code cap size. Writes the `data-size` attribute. | no |
-| `color` | `string` | `undefined` | no | Free-form accent color. Writes the `data-accent-color` attribute. The component is not opinionated about the value; consumers that pass it get the `data-accent-color` attribute for downstream CSS targeting. | no |
-| `highContrast` | `boolean` | `false` | no | When `true`, writes `data-high-contrast="true"`. | no |
-| `asChild` | `boolean` | `false` | no | Renders the host through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
-| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-code`. | no |
-| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
-| `children` | `React.ReactNode` | `undefined` | no | Code body (typically a short token, a function name, or a small literal). | no |
-
-Rules that apply to this row:
-
-- `Code` extends `Omit<ComponentPropsWithoutRef<'code'>, 'color'>` because `color` is redefined by the prop def bag.
-- `variant`, `tone`, `size`, `color`, `highContrast`, and `asChild` flow through `extractProps` and the prop def bag.
-- `data-variant`, `data-size`, `data-accent-color`, and `data-high-contrast` are written alongside the modifier classes so the CSS can target them through attribute selectors.
-- The `color` prop in the prop def has `default: undefined` and an empty `values: [] as const` array, so the runtime accepts any string but the prop def does not enumerate values. The TS type resolves to `string | undefined`.
+| `variant` | `'solid' \| 'soft' \| 'outline' \| 'ghost'` | `'soft'` | no | Writes `dsx-code--{variant}` and `data-variant`. | no |
+| `tone` | `'default' \| 'muted' \| 'inverse'` | `'default'` | no | Non-default tones write `dsx-code--{tone}`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Writes `data-size`; small is 0.85×, default 1× and large 1.15× the code font-size token. Inline gutter remains compact at all sizes; ghost has none. | no |
+| `color` | `'rift' \| 'warp' \| 'ray' \| string` | `undefined` | no | Writes `data-accent-color`; recognized accents resolve semantic tokens, including astral/spark. Unknown strings retain ambient tokens. | no |
+| `highContrast` | `boolean` | `false` | no | Writes `data-high-contrast="true"` and paints a real contrast treatment. | no |
+| `asChild` | `boolean` | `false` | no | Slot the consumer host. | no |
+| `className` | `string` | `undefined` | no | Additional classes. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Forwarded style. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Code content. | no |
 
 ## CSS class contract
 
-**Root class:** `dsx-code`
-
-**Modifier classes** (driven by the `variant` and `tone` prop defs and the `data-*` attributes):
-
-| Attribute | Allowed values | Class | CSS file |
-|---|---|---|---|
-| (class) | `solid`, `soft`, `outline`, `ghost` | `dsx-code--{variant}` | `code.css` |
-| (class) | `muted`, `inverse` | `dsx-code--muted`, `dsx-code--inverse` | `code.css` |
-| `data-variant` | `solid`, `soft`, `outline`, `ghost` | `.dsx-code[data-variant='{variant}']` | `code.css` |
-| `data-size` | `sm`, `md`, `lg` | (CSS contract for size) | n/a |
-| `data-accent-color` | any custom string | (no rule in the source CSS) | n/a |
-| `data-high-contrast` | `true` | (no rule in the source CSS) | n/a |
-
-**Slot classes:** none.
-
-**Responsive behavior:**
-
-- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`. The CSS for `data-size` is left to downstream CSS.
+Root: `dsx-code`. Modifier classes: `dsx-code--solid`, `--soft`, `--outline`, `--ghost`, `--muted`, `--inverse`. Attributes: `data-variant`, `data-size`, `data-accent-color`, `data-high-contrast`. There are no viewport breakpoints.
 
-**Reduced motion:**
-
-- Code has no motion. No transitions or animations are declared in `code.css`.
+- Soft: contextual neutral wash, normal foreground, no outline. It remains an inline text treatment rather than an input frame.
+- Solid: accent-track fill with accent-contrast foreground. Muted and inverse retain that readable filled pairing.
+- Outline: transparent with an inset outline.
+- Ghost: transparent, no outline or padding at every size.
+- A non-solid explicit color uses accent-indicator, except inverse tone, which preserves its inverse foreground.
+- Soft inverse uses the inverse-background / on-inverse-background pair and no shadow.
+- High contrast: soft uses high-contrast-container / high-contrast; solid uses high-contrast / on-high-contrast; outline and ghost use high-contrast ink. Inverse soft/outline/ghost retain their inverse foreground and surface pairing when high contrast is enabled. The inverse context already supplies the contrasting pair; a normal-surface ink must not replace it.
 
 ## Token mapping
 
-Every CSS value the component paints is a `var(--dsx-*)` token.
-
 | Property | Token | Role |
 |---|---|---|
-| Font family | `var(--dsx-typography-code-font-family)` | Monospace stack (token-backed; see rules). |
-| Font size | `var(--dsx-typography-code-font-size)` | Default code size. |
-| Font weight | `var(--dsx-typography-code-font-weight)` | Code weight. |
-| Line height | `var(--dsx-typography-code-line-height)` | Code rhythm. |
-| Letter spacing | `var(--dsx-typography-code-letter-spacing)` | Code tracking. |
-| Border radius | `var(--dsx-rounded-sm)` | Code cap roundness. |
-| Padding | `var(--dsx-space-0-5, 2px) var(--dsx-space-1-5, 6px)` | Inline gutter. |
-| Background (soft) | `var(--dsx-color-surface-sunken)` | Soft surface (Direction #3 Q1 pick: sunken, pressed into the page). |
-| Border (soft) | `var(--dsx-color-outline-variant)` | Soft outline (via `inset 0 0 0 1px`). |
-| Background (solid) | `var(--dsx-color-primary)` | Solid surface. |
-| Color (solid) | `var(--dsx-color-on-primary)` | Solid text. |
-| Outline (outline) | `var(--dsx-shadow-inset-outline)` | Inset outline. |
-| Color (outline) | `var(--dsx-color-on-surface)` | Outline text. |
-| Color (ghost) | `var(--dsx-color-on-surface)` | Ghost text. |
-| Color (muted) | `var(--dsx-color-on-surface-variant)` | Muted tone. |
-| Color (solid + muted) | `color-mix(in srgb, var(--dsx-color-on-primary) 65%, transparent)` | Muted text on solid. |
-| Color (inverse) | `var(--dsx-color-on-inverse-background)` | Inverse-context color. |
-| Background (soft + inverse) | `color-mix(in srgb, var(--dsx-color-on-high-contrast) 15%, transparent)` | Inverse soft surface. |
-| Color (soft + inverse) | `var(--dsx-color-on-high-contrast)` | Inverse soft text. |
+| Typography | `--dsx-typography-code-*` | JetBrains Mono family, font size, weight, line height, tracking, axes, case and decoration. |
+| Small / large font size | code font-size × 0.85 / × 1.15 | Existing scale preserved. |
+| Padding | `--dsx-space-0-5`, `--dsx-space-1-5` | Compact inline gutters at every size; ghost has zero padding. |
+| Radius / outline | `--dsx-rounded-sm` / `--dsx-shadow-inset-outline` | Cap geometry; edge belongs to the outline variant only. |
+| Soft | `--dsx-code-soft-background`, `--dsx-color-on-surface` | Neutral wash from the dedicated gray-alpha-3 effect; also used by the consumer preformatted example. |
+| Solid | `--dsx-color-accent-track`, `--dsx-color-accent-contrast` | Filled code with readable foreground. |
+| Accent / muted / inverse | `--dsx-color-accent-indicator`, `--dsx-color-on-surface-variant`, inverse-background + on-inverse-background | Context roles. |
+| High contrast | high-contrast-container + high-contrast, high-contrast + on-high-contrast | Self-contained soft/solid pairs. |
 
-Rules:
-
-- The monospace font stack resolves from `var(--dsx-typography-code-font-family)` (the `code` node in `tokens/typography.json`); it is token-backed, not a CSS hard-code.
-- The `color-mix` expressions are token-driven; the alpha is encoded in the token, not as a raw value.
+No local alpha mixing or primitive accent ramp reference is authored here. The component bridge references the existing gray-12-at-10% effect and is rebound at local theme/accent/gray boundaries. Soft and ghost stay distinct on page, shell and raised backgrounds.
 
 ## Motion contract
 
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| (none) | `none` | `none` | `none` |
-
-Rules:
-
-- Code has no motion. The motion section is intentionally empty.
+Static typography; no animation or transition.
 
 ## Accessibility
 
-**Roles:**
-
-- The component renders a `<code>` by default (or the consumer's host element when `as` / `asChild` is set). The semantic role of an inline code token is preserved.
-
-**Keyboard:**
-
-- Code is not interactive. No keyboard contract beyond the page-level Tab order.
-
-**Focus:**
-
-- Code has no focusable surface. Focus management is the consumer's responsibility when the code is wrapped in a focusable container.
-
-**Reduced motion:**
-
-- N/A. Code has no motion.
-
-**Color and meaning:**
-
-- The `variant` and `tone` props are visual modifiers. The code body itself carries the meaning.
-
-**Naming:**
-
-- No accessible name is required by default. Consumers that need an announced label for a code token (e.g. an inline icon) should supply `aria-label`.
+Native `<code>` semantics are preserved. The component is non-interactive; no focus or touch target is required. Consumer hosts through `asChild` own their semantics. Surrounding copy explains the snippet. Preformatted content keeps its whitespace and can scroll horizontally in the consumer's bounded overflow region.
 
 ## Playground demo spec
 
-`Code` is registered in `apps/playground/lib/registry/typography.tsx` under the `code` key. The registry entry imports `codePropDefs` and renders the component with a sample code token. Per-component route: `/docs/code`.
-
-**Default story:**
-
-- Renders `Code` with a default code string. Asserts the root class is `dsx-code` and the variant modifier is `dsx-code--soft`. The `data-variant` attribute is `soft` and the `data-size` attribute is `md`. Host element is `CODE`.
-
-**Variant story:**
-
-- Renders Code with each `variant` value. Asserts the matching `dsx-code--{variant}` class and the matching `data-variant` attribute.
-
-**Size story:**
-
-- Renders Code with each `size` value. Asserts the `data-size` attribute on the root.
-
-**Color story:**
-
-- Renders Code with a `color` value (e.g. `color="blue"`). Asserts the `data-accent-color` attribute on the root.
-
-**Composition story** (for `asChild`):
-
-- Renders Code with `asChild` wrapping a `<span>` element. Asserts the host element is `SPAN` and the `dsx-code` class is preserved.
-
-**State story:**
-
-- Renders Code in muted and inverse states, including the variant-on-tone pairings (`solid` + `muted`, `soft` + `inverse`).
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper. Code is not themed by `data-accent-color`; the story documents that the variant surfaces are visually unchanged across accent colors.
-
-**A11y story:**
-
-- The default render passes the `vitest-axe` no-violations check.
-
-**Props exposed in the playground controls:**
-
-| Prop | Control | Default |
-|---|---|---|
-| `variant` | select | `soft` |
-| `tone` | select | `default` |
-| `size` | select | `md` |
-| `color` | text | (empty) |
-| `highContrast` | boolean | `false` |
-| `asChild` | boolean | `false` |
+`/docs/code`, typography registry. Matrix forwards all props. The live example compares all variants and sizes, muted/inverse/high-contrast states, all five accent strings, a slotted host, real inline configuration names and a preformatted snippet, and soft/ghost comparisons on page, shell and raised backgrounds. Inverse code has its paired background. Solid foreground remains readable on every accent in both appearances.
 
 ## Wiring notes
 
-**Composes from:**
-
-- `@radix-ui/react-slot` for `asChild`.
-- `_internal/helpers/extractProps` for the prop def bag.
-- `_internal/props/{asChild,highContrast}.prop` for the shared prop defs.
-- `_internal/cn` (via `classNames`) for class merging.
-- No DS component composition. Code is a leaf primitive.
-
-**Used by:**
-
-- The Playground typography registry, in-product inline code tokens, and any app surface that needs a monospace accent (command palettes, key hints, code samples, file paths).
-
-**State boundaries:**
-
-- Owned by Code: the root class, the variant and tone modifier classes, the `data-variant`, `data-size`, `data-accent-color`, and `data-high-contrast` attributes, and the prop def bag.
-- Owned by the consumer: the code body, the host element when `as` / `asChild` is set, and any extra `className` / `style` applied through prop forwarding.
-
-**Boundary rules:**
-
-- App-owned data: the code string, the surrounding prose context, and the host element when `asChild` is set.
-- DS-owned visuals: the `dsx-code` root class, the variant and tone modifier classes, the data attributes, and the prop def bag.
-
-## Penpot build recipe
-
-> Optional. Penpot is a visual reference, not a code authority. The Code recipe tracks the variant, tone, size, color, and high-contrast contract.
-
-The package does not yet publish a Penpot asset for Code. The recipe is visual reference only and tracks the CSS contract.
-
-### Root board
-
-- **Name**: `Primitives / Code`.
-- **Dimensions**: `auto × auto` (inline token).
-- **Layout**: `Flex` (inline).
-- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
-
-### Layer tree
-
-```
-<Root Board: Code>
-  └── <Text: code body (monospace)>
-```
-
-### Token bindings (Penpot properties)
-
-| Shape | Property | Token | Token type | Penpot property name |
-|---|---|---|---|---|
-| Root | typography | `--dsx-typography-code-*` token family | Typography | `typography` |
-| Root | radius | `--dsx-rounded-sm` | Radius | `radius` |
-| Root (soft) | fill | `--dsx-color-surface-raised` | Color | `fills` (state) |
-| Root (soft) | stroke | `--dsx-color-outline-variant` | Color | `strokes` (state) |
-| Root (solid) | fill | `--dsx-color-primary` | Color | `fills` (state) |
-| Root (solid) | text fill | `--dsx-color-on-primary` | Color | `fills` (state) |
-| Root (outline) | stroke | `--dsx-shadow-inset-outline` | Color | `strokes` (state) |
-
-### State transformations
-
-| State | Root fill | Root stroke | Text fill |
-|---|---|---|---|
-| `soft` (default) | `--dsx-color-surface-raised` | `--dsx-color-outline-variant` | `--dsx-color-on-surface` |
-| `solid` | `--dsx-color-primary` | (none) | `--dsx-color-on-primary` |
-| `outline` | `transparent` | `--dsx-shadow-inset-outline` | `--dsx-color-on-surface` |
-| `ghost` | `transparent` | (none) | `--dsx-color-on-surface` |
-
-### Variant model
-
-- `variant`: `soft`, `solid`, `outline`, `ghost`. Default `soft`.
-- `tone`: `default`, `muted`, `inverse`. Default `default`.
-- `size`: `sm`, `md`, `lg`. Default `md`.
-- `color` and `highContrast` documented in the spec body.
-- Total members: variant × tone × size = 4 × 3 × 3 = 36, plus the high-contrast toggle.
-
-### Validation checklist
-
-- [ ] Token bindings resolve at the values `DESIGN.md` describes.
-- [ ] Component is promoted to Main Component under `Primitives`.
-- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
-- [ ] Monospace font stack resolves from `--dsx-typography-code-font-family`; treat it as token-backed in Penpot.
+Radix Slot implements `asChild`; `extractProps` consumes `codePropDefs`; classnames merges the root/modifiers. Code is a leaf primitive; the token layer scopes accent values. Apps own text, host, code language, syntax highlighting and preformatted overflow layout.

package/dist/docs/components/collapsible.md

@@ -73,7 +73,7 @@ Rules:
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. The motion and layout are single-value only.
+- The component does not use width breakpoints. The motion and layout are single-value only.
 
 **Reduced motion:**
 
@@ -86,7 +86,7 @@ Rules:
     }
   }
   ```
-  The expand/collapse keyframes (`dsx-collapsible-expand`, `dsx-collapsible-collapse`) are gated off when the user prefers reduced motion. The chevron rotation uses `var(--dsx-motion-duration-fast)` and is not explicitly gated at the CSS level; the token layer should map it to `0` under reduced motion.
+  The expand/collapse keyframes (`dsx-collapsible-expand`, `dsx-collapsible-collapse`) are gated off when the user prefers reduced motion. The chevron rotation uses `var(--dsx-motion-duration-fast)` and is disabled in component CSS under reduced motion.
 
 ## Token mapping
 
@@ -98,7 +98,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Trigger padding | `var(--dsx-space-md)` | Internal gutter |
 | Trigger color | `var(--dsx-color-on-surface)` | Closed trigger text |
 | Trigger label type | `var(--dsx-typography-label-large-font-family)`, `var(--dsx-typography-label-large-font-size)` | Trigger text ramp |
-| Trigger open color | `var(--dsx-color-primary)` | Open trigger text |
+| Trigger open color | `var(--dsx-color-accent-indicator)` | Open trigger text |
 | Trigger focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator |
 | Chevron transition | `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-standard, ease)` | Rotate transition |
 | Content padding | `var(--dsx-space-md)` | Inner content gutter |
@@ -107,12 +107,14 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Expand/collapse duration | `var(--dsx-motion-duration-normal)` | Keyframe duration |
 | Expand/collapse easing | `var(--dsx-motion-easing-in-out)` | Keyframe easing |
 
+Content height and vertical padding animate together from zero to their measured/underlying values. This prevents padding from clamping the first animation frames. The underlying endpoint retains consumer padding overrides, including `asChild` hosts. No wrapper is added.
+
 ## Motion contract
 
 | Region | Token | Default | Reduced |
 |---|---|---|---|
-| `dsx-collapsible__content` height + opacity | `var(--dsx-motion-duration-normal)` + `var(--dsx-motion-easing-in-out)` | 200ms in-out (token-dependent) | `animation: none !important` via the runtime-inserted `prefers-reduced-motion` block |
-| `dsx-collapsible__chevron` rotate | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | 150ms standard (token-dependent) | Token-layer override; the chevron transition is not explicitly gated at the CSS level |
+| `dsx-collapsible__content` height + block-axis padding + opacity | `var(--dsx-motion-duration-normal)` + `var(--dsx-motion-easing-in-out)` | motion-duration-normal (token-dependent) | `animation: none !important` via the runtime-inserted `prefers-reduced-motion` block |
+| `dsx-collapsible__chevron` rotate | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | 150ms standard (token-dependent) | Transition disabled in component CSS |
 
 ## Accessibility
 
@@ -126,7 +128,6 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|
 | `Tab` | Moves focus to the trigger. |
 | `Enter`, `Space` | Toggles the open state. |
-| `Escape` | Collapses the content if the content has focus. Behavior is owned by Radix. |
 
 **Focus:**
 
@@ -134,7 +135,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Reduced motion:**
 
-- The runtime-inserted style block disables the expand/collapse keyframes when `prefers-reduced-motion: reduce` matches. The chevron rotation is not explicitly gated; consumers should rely on the global motion token override.
+- The runtime-inserted style block disables the expand/collapse keyframes when `prefers-reduced-motion: reduce` matches. The chevron transition is disabled in component CSS as well.
 
 **Color and meaning:**
 
@@ -144,36 +145,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 - `Collapsible.Trigger` is the interactive element; the consumer's `children` become the button's accessible name.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders a `Collapsible` with a trigger and content. Asserts the root renders as a transparent host and the trigger and content are present.
-
-**State story:**
-
-- Renders with `open`. Asserts the trigger has `data-state="open"` and the content is visible.
-- Renders with `defaultOpen={false}` and triggers a click. Asserts the trigger's `data-state` flips from `closed` to `open`.
-- Renders with `disabled`. Asserts the trigger is disabled and the content does not toggle.
-
-**Composition story:**
+The live example embeds a disclosure and moving footer in a project card. Disabled and initially expanded warp/ray examples remain separate.
 
-- Renders the root wrapped in a `Card` to demonstrate the surface composition pattern. Asserts the trigger and content are present inside the card.
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Collapsible does not track `data-accent-color`; the story asserts the open trigger color continues to resolve through `var(--dsx-color-primary)`.
-
-**A11y story:**
-
-- Uses `vitest-axe` against the rendered default story. Asserts no axe violations.
-
-**Props exposed in the playground controls:**
+## Playground demo spec
 
-| Prop | Control | Default |
-|---|---|---|
-| `open` | boolean | `false` |
-| `disabled` | boolean | `false` |
+The default render is a disclosure within a bounded consumer surface. The live project card includes fixed introductory content, optional project details, and a footer that moves with the disclosure. Separate disabled and initially expanded warp/ray examples expose the behavior and accent state. Normal-motion probes sample expansion and collapse; reduced motion skips both animations.
 
 ## Wiring notes
 

package/dist/docs/components/combobox.md

@@ -158,7 +158,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Content border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Floating menu edge. |
 | Content radius | `var(--dsx-rounded-lg)` | Floating menu corner roundness shared with the menu family. |
 | Content width | `max-content` / `var(--radix-popover-trigger-width)` / `min(--radix-popover-content-available-width, 40rem)` | Mirror-at-minimum with grow-to-fit; past 40rem rows wrap via `data-overflow`. |
-| 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 surface. |
 | Search wrapper border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Bottom divider below the input. |
 | Input height | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Density-aware control height. |
 | List max-height | `var(--dsx-combobox-list-max-height)` | Scroll ceiling. |
@@ -275,6 +275,7 @@ Rules:
 - `@radix-ui/react-slot`: enables `asChild` on every subcomponent.
 - `_internal/usePrefersReducedMotion`: gates the framer-motion transition when the user prefers reduced motion.
 - `_internal/motion`: `MOTION_TRANSITIONS.combobox` and `MOTION_TRANSITIONS.reduced` presets.
+- `_internal/floatingLayer`: `useFloatingLayerHost` tells `Combobox.Content` whether it renders inside a modal-tier host (`Popover.Content` / `Dialog.Content`); when nested, the content adds `dsx-menu__nested` so the panel paints above its host. The signal is read at content level, so a standalone `Combobox` never self-escalates through its own inner `Popover` (see the shared nested floating tier contract in `menu.md`).
 
 **Used by:**
 
@@ -337,6 +338,7 @@ The package does not yet publish a Penpot asset for Combobox. Recipe is visual r
 | Content | fill | `--dsx-color-panel-translucent` | Color | `fills` |
 | Content | stroke | `--dsx-color-outline` | Color | `strokes` |
 | Content | radius | `--dsx-rounded-lg` | Radius | `radius` |
+| Content | shadow | `--dsx-menu-content-elevation` (menu tier, step 3) | Effect | `shadow` |
 | Search wrapper | stroke | `--dsx-color-outline` (bottom only) | Color | `strokes` (state) |
 | Item | typography | `--dsx-typography-body-medium-*` | Typography | `typography` |
 | Item (selected) | font-weight | `--dsx-typography-body-medium-font-weight` | Typography | `typography` |

package/dist/docs/components/command.md

@@ -28,7 +28,7 @@ A search-and-act command palette, cmdk-backed, that lets the user type to filter
 | `Command` | `cmdk.Command` | DS composite + class `dsx-command` | Root palette. Hosts input, list, groups, items, separator, and shortcut. |
 | `CommandDialog` | `Dialog` + `Command` | DS composite | Wraps `Command` in a `Dialog` with a `DialogContent`. Manages open state and the global keyboard shortcut. |
 | `CommandInput` | `cmdk.Input` wrapped in `<div>` | DS composite + class `dsx-command__input` | Search input. Wrapper carries `dsx-command__input-wrapper` and a search icon. |
-| `CommandList` | `cmdk.List` | DS composite + class `dsx-command__list dsx-scroll-area` | Scrollable list of groups and items. |
+| `CommandList` | `cmdk.List` | DS composite + class `dsx-command__list` | Scrollable list of groups and items (native overflow; never the ScrollArea class — its `overflow: hidden` clipped list tails). |
 | `CommandGroup` | `cmdk.Group` | DS composite + class `dsx-command__group` | Grouped section with optional heading. Writes `data-section` when a string heading is present. |
 | `CommandItem` | `cmdk.Item` | DS composite + class `dsx-command__item` | Selectable row. |
 | `CommandSeparator` | `cmdk.Separator` | DS composite + class `dsx-command__separator dsx-separator` | Divider between groups. |
@@ -133,7 +133,7 @@ Rules:
 | `CommandInput` (wrapper) | `dsx-command__input-wrapper` | `command.css` |
 | `CommandInput` (icon) | `dsx-command__input-icon` | `command.css` |
 | `CommandInput` (input) | `dsx-command__input dsx-input` | `command.css` |
-| `CommandList` | `dsx-command__list dsx-scroll-area` | `command.css` |
+| `CommandList` | `dsx-command__list` | `command.css` |
 | `CommandGroup` | `dsx-command__group` | `command.css` |
 | `CommandItem` | `dsx-command__item` | `command.css` |
 | `CommandSeparator` | `dsx-command__separator dsx-separator` | `command.css` |
@@ -236,6 +236,8 @@ The palette has no mount or exit motion. Item selection and hover animate throug
 - `Command` accepts an optional `label` for the palette. When omitted, the input placeholder and surrounding context must provide a meaningful name.
 - Each `CommandItem` needs a meaningful label. The optional `CommandShortcut` is decorative.
 
+`Command.Shortcut` displays a hint; consumers wire the handler. The live playground example implements ⌘P/⌘S and Ctrl+P/Ctrl+S while focus is inside the palette and explains that scope. `Command.Separator` owns the group boundary; headings do not add a second rule.
+
 ## Playground demo spec
 
 **Default story:**

package/dist/docs/components/comment-thread.md

@@ -15,6 +15,56 @@ Controlled one-reply-level discussion UI. Data, relative-time localization, mode
 
 `CommentThread.Root`, `Comment`, `Replies`, `Tombstone`, `Composer`, and `Locked`. Comment renders avatar initials or image, author badge content, semantic `time`, body, and report/reply actions. Composer owns no remote state and exposes value, character limit, locked, and submission state. Tombstones remain visibly present to preserve thread structure.
 
+- Root forwards native div attributes/ref. Comment forwards article attributes/ref;
+  `author` and `dateTime` are strings, `timeLabel`, `badge`, `actions` and body accept
+  React nodes, and `avatarSrc` optionally replaces initials with a decorative image.
+- Replies forwards native div attributes/ref and defaults to role group. One nested
+  reply level is supported; a second Replies inside Replies throws explicitly.
+- Tombstone defaults to `Comment removed`, role status and `data-removed="true"`.
+  Locked defaults to `Comments are locked` and role status. Both accept custom children.
+- Composer forwards form attributes/ref while managing submission. `value` and
+  `onValueChange` are required; `onSubmit`, `maxLength` (default 2000), `locked` and
+  `submitting` are optional. It prevents native navigation and calls onSubmit only
+  for nonblank, within-limit, valid, unlocked, non-submitting content. The app owns asynchronous work.
+- Its controlled native textarea has the default accessible name `Comment` and an
+  associated polite character counter. Locked/submitting disables editing; submitting
+  sets form `aria-busy`. Default submit composes the large DS Button, disabled for
+  empty/locked/submitting content. Custom children replace that default action.
+
+## Paint and containment
+
+Comment uses an avatar column and a zero-minimum content track. Author metadata and
+actions and action labels wrap intrinsically; long body words wrap. Body/actions remain in the content
+column and Replies retains its logical-start indent. No component breakpoint is used.
+
+Composer textarea explicitly fits its parent, uses body-medium typography, keeps
+native vertical resize, and consumes the existing focus ring and disabled roles.
+The `dsx-comment-thread__count` and `dsx-comment-thread__submit` classes identify
+the counter and default action. Button owns focus/pressed/disabled treatment and
+target dimensions (44px at comfortable density). The component adds no motion.
+
 ## Playground demo spec
 
-Show initials and image avatars, badge and time, one reply level, report/reply actions, character count, submitting/locked composers, and a removed tombstone.
+`/docs/comment-thread` composes `blocks-examples.tsx` through the display registry.
+It shows initial/image avatars, author badge/time, one reply level, report/reply
+actions and a removed tombstone. The controlled composer updates its count, shows
+submitting, adds a local comment, and can be locked/unlocked. Separate submitting
+and locked examples remain visible. All demo persistence and action feedback is
+playground-owned; no network or moderation service is implied.
+
+## Discussion enhancement — approved 2026-10-04
+
+`Composer` adds `input(context)` to replace the textarea without duplication,
+`label`, `error`, `status` and `actions`. Context supplies `id`, `value`,
+`onValueChange`, `maxLength`, `disabled`, `describedBy` and `invalid` for accessible
+custom controls. Children retain their existing submit-action override. Count,
+error and status are associated with the input. Blank, over-limit, submitting,
+locked or invalid drafts cannot submit. Consumers own rich-text plain count and
+validation. `Comment.metadata` supports edited state.
+
+`Replies` adds optional `limit`, controlled/uncontrolled `expanded`,
+`onExpandedChange` and `moreLabel`; defaults still show all children. Exactly one
+reply level remains supported. `Tombstone.state` distinguishes `hidden`,
+`removed` and `deleted`, with localized children. Legacy `data-removed` persists.
+Support is demonstrated as a linear composition with a restricted rich editor,
+separate FileUpload/attachments, visibility and failed-send retry, not nested replies.