@d4gger/design-system 2.7.0

package/dist/docs/marquee.md

@@ -0,0 +1,274 @@
+---
+title: Marquee
+status: canonical
+category: Components
+archetype: primitive
+package_path: packages/d4gger-design-system/src/components/marquee/Marquee.tsx
+css_path: packages/d4gger-design-system/src/styles/components/marquee.css
+props_path: packages/d4gger-design-system/src/components/marquee/marquee.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Marquee.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on: []
+---
+
+# Marquee
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A horizontally scrolling content strip that animates a duplicated child track across the viewport, with optional pause-on-hover, tokenized edge fade, and configurable speed and direction. Use Marquee for ticker rows, partner/logo rails, and other continuously visible streams; do not use it to surface critical content because the moving strip is not keyboard- or screen-reader-friendly for the full payload.
+
+## Anatomy & slots
+
+**Parent:** `Marquee` (no compound; flat export, but the component owns two internal children).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Marquee` (root) | `<div>` | DS primitive + class | Wrapper that owns the `--dsx-marquee-duration`, `--dsx-marquee-direction`, and `--dsx-marquee-edge-fade-width` CSS variables plus the `data-pause-on-hover` and optional `data-edge-fade` attributes. |
+| internal track | `<div class="dsx-marquee__track">` | internal layout | Flex row that runs the `dsx-marquee-scroll` keyframe. |
+| internal content (x2) | `<div class="dsx-marquee__content">` | internal layout | The original `children` and an `aria-hidden="true"` clone. The duplication is what makes the loop seamless. |
+
+The track and content nodes are internal layout, not public slots. The two `dsx-marquee__content` rows are siblings inside the track.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `speed` | `number` | `30` | no | Animation duration in seconds. Sets the `--dsx-marquee-duration` CSS variable. Higher numbers slow the scroll. | no |
+| `direction` | `'left' \| 'right'` | `'left'` | no | Scroll direction. `'right'` maps to `animation-direction: reverse`; `'left'` maps to `animation-direction: normal`. | no |
+| `pauseOnHover` | `boolean` | `false` | no | When `true`, the track pauses on hover. Writes `data-pause-on-hover` only when the prop is `true`. | no |
+| `edgeFade` | `boolean` | `false` | no | Opts into a tokenized CSS mask at the inline edges. Writes `data-edge-fade` only when true. The mask clears on `:focus-within` and under reduced motion. | no |
+| `asChild` | `boolean` | `false` | no | Renders the wrapper through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-marquee`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. The runtime-injected `--dsx-marquee-duration` and `--dsx-marquee-direction` CSS variables are merged into this style. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Scrolling content. Rendered twice (once as the visible copy, once as an `aria-hidden="true"` clone to keep the loop seamless). | no |
+
+Rules that apply to this row:
+
+- The component extends `React.HTMLAttributes<HTMLDivElement>`. Any standard HTML attribute (`id`, `aria-*`, `onClick`, etc.) is forwarded to the host.
+- `speed` is typed in the `MarqueeProps` interface and consumed at the destructuring site, NOT through `extractProps`. `direction` is left in the props bag so `extractProps` can emit the direction modifier class (`dsx-marquee--left` / `dsx-marquee--right`); the runtime also reads it from `props` for the `--dsx-marquee-direction` CSS variable. The prop def bag declares `asChild`, `direction`, `pauseOnHover`, and `edgeFade`.
+- The runtime default for `pauseOnHover` is also applied in the destructuring (`pauseOnHover = false`), even though the prop def has its own `default: false`. The two defaults agree.
+- The runtime merges `--dsx-marquee-duration` and `--dsx-marquee-direction` into the `style` object via a type cast to `React.CSSProperties`. CSS custom properties on `style` are valid but not part of the React `CSSProperties` type; the cast is a pragmatic escape hatch and should be revisited if React's typing grows custom-property support.
+- The component does not write a `data-pause-on-hover` attribute unless `pauseOnHover={true}`. The CSS targets `.dsx-marquee[data-pause-on-hover] .dsx-marquee__track:hover` and uses the attribute presence as a flag.
+- The component does not write `data-edge-fade` unless `edgeFade={true}`, preserving the 2.4.0 default rendering.
+
+## CSS class contract
+
+**Root class:** `dsx-marquee`
+
+**Modifier classes** (driven by the `direction` prop def and the `data-pause-on-hover` attribute):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| (class) | `left`, `right` | `dsx-marquee--left`, `dsx-marquee--right` | `marquee.css` (class is emitted; CSS does not currently key off it — see Anomalies) |
+| `data-pause-on-hover` | (presence) | `.dsx-marquee[data-pause-on-hover]` | `marquee.css` |
+| `data-edge-fade` | (presence) | `.dsx-marquee[data-edge-fade]` | `marquee.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Marquee` (root) | `dsx-marquee` | `marquee.css` |
+| internal track | `dsx-marquee__track` | `marquee.css` |
+| internal content | `dsx-marquee__content` | `marquee.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `speed` and `direction` are single-value only; the prop defs are not `responsive: true`.
+
+**Reduced motion:**
+
+- A local `prefers-reduced-motion: reduce` rule disables animation and transform, constrains the track to the wrapper width, makes the original content wrap, visually hides the `aria-hidden` duplicate, and removes the edge mask. The complete original payload remains readable without a consumer override.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token or a runtime-injected CSS variable.
+
+| Property | Token | Role |
+|---|---|---|
+| Overflow (root) | `hidden` | Clip the track to the wrapper width. |
+| Width (root) | `100%` | Fill the parent. |
+| Position (root) | `relative` | Stacking context for the track. |
+| Duration | `var(--dsx-marquee-duration, 30s)` (runtime-injected) | Animation duration. Falls back to `30s` if the runtime does not set the variable. |
+| Direction | `var(--dsx-marquee-direction, normal)` (runtime-injected) | Animation direction. Falls back to `normal` if the runtime does not set the variable. |
+| Track display | `flex` | Layout for the duplicated content. |
+| Track width | `max-content` | Make the track wide enough to hold both copies side by side. |
+| Track animation | `dsx-marquee-scroll var(--dsx-marquee-duration, 30s) linear infinite` | The scroll keyframe. |
+| Track animation-direction | `var(--dsx-marquee-direction, normal)` | Reversed for `direction="right"`. |
+| Content display | `flex` | Inline layout for the duplicated children. |
+| Content align | `center` | Center children vertically. |
+| Content flex-shrink | `0` | Do not collapse under flex pressure. |
+| Content gap | `var(--dsx-space-md)` | Spacing between children inside one copy. |
+| Content padding | `0 var(--dsx-space-md)` | Side gutter inside one copy. |
+| Edge fade width | `--dsx-marquee-edge-fade-width: var(--dsx-space-xl)` | Public component custom property; consumers may override it with another package sizing/spacing value. |
+| Edge fade mask | `var(--dsx-color-on-surface)` + `transparent` stops | Tokenized opaque mask stops; only alpha matters, so no consumer background color is required. |
+
+Rules:
+
+- `--dsx-marquee-duration` and `--dsx-marquee-direction` are runtime-injected via `style`. They are not declared in `DESIGN.md` or the generated `tokens.css`; they are local component variables that follow the same `var(--dsx-*, fallback)` pattern. The CSS file ships its own fallbacks (`30s` and `normal`).
+- The keyframe (`dsx-marquee-scroll`) translates from `0` to `-50%`. The duplicate child is what makes the loop seamless: when the first copy scrolls off, the second copy is in the same position the first copy started.
+- The `direction` prop's className (`dsx-marquee-`) is emitted via `extractProps` (so `dsx-marquee--left` and `dsx-marquee--right` are applied to the root), but the CSS file does not currently key off those classes. Direction is animated entirely through the runtime-injected CSS variable. The modifier classes are dead weight in the current CSS (see Anomalies).
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Track scroll (`dsx-marquee-scroll`) | `var(--dsx-marquee-duration, 30s)` + `linear` (hard-coded) + `infinite` | `transform: translateX(0)` to `transform: translateX(-50%)`. | Local CSS removes animation/transform, wraps the original content at `width: 100%`, hides the duplicate, and disables the edge mask. |
+
+Rules:
+
+- The component uses CSS keyframes directly; it does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts` and does not use framer-motion. The local media query owns the static fallback.
+- The component is continuous by design. The CSS `linear` timing and `infinite` iteration count are not exposed as tokens; they are hard-codes that match the marquee semantic.
+
+## Accessibility
+
+**Roles:**
+
+- The component does not currently set `role` on the root. The internal duplicate is marked `aria-hidden="true"` to keep assistive tech from reading the same content twice. The wrapper is effectively a `marquee` or `region` (the source does not pick either).
+
+**Keyboard:**
+
+- Marquee is not interactive. No keyboard contract. The content is visible to keyboard users as a static strip because the track is clipped by the wrapper, not by `tabindex`.
+
+**Focus:**
+
+- Focusable children inside the strip remain focusable. The scroll animation does not move focus. The edge mask clears on `:focus-within` so focus indicators are not clipped. Consumers that include interactive children should ensure those children are not announced twice; the `aria-hidden="true"` clone handles the announcement side.
+
+**Reduced motion:**
+
+- The local reduced-motion rule presents one static wrapping copy, keeps the duplicate hidden from assistive technology and from view, and removes the edge mask.
+
+**Color and meaning:**
+
+- The scrolling animation is decorative. Any state communicated by the moving children is still legible when the animation is paused.
+
+**Naming:**
+
+- The component does not require an accessible name. If the strip carries a meaningful heading (e.g. "Latest news"), put it outside the strip as a sibling `<h2>` or `aria-labelledby` target.
+
+## Playground demo spec
+
+The demo file at `demo_path` exposes the component to the playground. The playground lives at `apps/playground/app/` (Next.js app router, no per-component routes today). The `demo_path` recorded here is the current playground root; the spec assumes a single shared page that renders all components. Per-component routes are an aspirational target and not yet present in the repo.
+
+**Default story:**
+
+- Renders `Marquee` with a row of six placeholder children. Asserts the root class is `dsx-marquee`, the runtime style includes `--dsx-marquee-duration: 30s` and `--dsx-marquee-direction: normal`, the `data-pause-on-hover` attribute is absent, and the inner DOM has a `dsx-marquee__track` with two `dsx-marquee__content` children (one with `aria-hidden="true"`).
+
+**Variant story** (one per direction):
+
+- Renders Marquee with `direction="left"` and `direction="right"`. Asserts the matching `dsx-marquee--{left|right}` class on the root and the matching `--dsx-marquee-direction` value (`normal` or `reverse`).
+
+**State story:**
+
+- Renders Marquee with `pauseOnHover={true}`. Asserts `data-pause-on-hover` is present on the root. The hover behavior itself is interactive and is verified by the test browser.
+- Renders Marquee with `edgeFade={true}`. Asserts `data-edge-fade` is present, focuses an interactive child, and verifies the mask clears.
+- Emulates `prefers-reduced-motion: reduce` and verifies the track is static, the original content wraps, the duplicate is visually hidden, and the fade is removed.
+
+**Speed story:**
+
+- Renders Marquee with `speed={5}` and `speed={60}`. Asserts the matching `--dsx-marquee-duration` value (`5s` and `60s`).
+
+**Composition story** (for `asChild`):
+
+- Renders Marquee with `asChild` wrapping a `<section>` element. Asserts the host element is `section`, the `dsx-marquee` class is preserved, and the internal `dsx-marquee__track` and `dsx-marquee__content` children are still rendered.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. The animation timing is not theme-aware; the story asserts the animation timing is unchanged across the three accents.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default marquee. Asserts there are no axe violations. Browser QA covers the local reduced-motion layout and focus-safe edge mask.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `speed` | number | `30` |
+| `direction` | select | `left` |
+| `pauseOnHover` | boolean | `false` |
+| `edgeFade` | boolean | `false` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-slot`: enables `asChild` for consumer-supplied host elements.
+- No DS component composition. The component is a self-contained scrolling surface; the roster previously listed `Box` as a parent but that was removed after the runtime showed a plain `<div>` wrapper. The wrapper is not a DS `Box`.
+
+**Used by:**
+
+- App-level ticker rows, partner/logo rails, and other continuously visible streams. The roster currently lists no DS components that consume `Marquee`; it is a leaf surface intended for direct app usage. Common composition targets are `Card` rows and `Item` lists, but those compositions are app-owned.
+
+**State boundaries:**
+
+- Owned by Marquee: the root class, the modifier class emitted by the `direction` prop def, the `data-pause-on-hover` and `data-edge-fade` attributes, the runtime-injected `--dsx-marquee-duration` and `--dsx-marquee-direction` variables, the public `--dsx-marquee-edge-fade-width` custom property, the duplicated `dsx-marquee__content` child, the `aria-hidden="true"` on the duplicate, and the local reduced-motion fallback.
+- Owned by the consumer: the children to scroll, the accessible heading (if any), and the host element when `asChild` is set.
+
+**Boundary rules:**
+
+- App-owned data: the ticker content, the news/logo list, and any analytics on visible items.
+- DS-owned visuals: token bindings (`--dsx-space-md`, `--dsx-space-xl`, `--dsx-color-on-surface`, `--dsx-marquee-duration`, `--dsx-marquee-direction`, `--dsx-marquee-edge-fade-width`), the `dsx-marquee` root class, the `dsx-marquee__track` and `dsx-marquee__content` slot classes, the edge mask/focus behavior, the reduced-motion static layout, and the `dsx-marquee-scroll` keyframes.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+The package does not yet publish a Penpot asset for Marquee. Recipe is visual reference only and tracks the CSS contract. The actual scroll animation is generated at runtime by CSS keyframes and is not authored in Penpot.
+
+### Root board
+
+- **Name**: `Components / Marquee`.
+- **Dimensions**: `480 × 64` (default demo height).
+- **Layout**: `Flex` (row, overflow hidden).
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: Marquee>
+  └── <Frame: dsx-marquee__track (clip, animated)>
+        ├── <Frame: dsx-marquee__content (visible copy)>
+        │     └── <Slot: children (logo / ticker item)>
+        └── <Frame: dsx-marquee__content (aria-hidden duplicate)>
+              └── <Slot: children (logo / ticker item, mirrored)>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Root | clip | overflow hidden | Layout | `clip` |
+| Root | width | `100%` | Sizing | `width` |
+| Content | gap | `--dsx-space-md` | Spacing | `gap` |
+| Content | padding | `0 --dsx-space-md` | Spacing | `padding` |
+
+### State transformations
+
+| State | Track animation | Track animation-direction |
+|---|---|---|
+| `default` (left) | `dsx-marquee-scroll 30s linear infinite` | `normal` |
+| `right` | `dsx-marquee-scroll 30s linear infinite` | `reverse` |
+| `pause-on-hover` (hover) | (same) | (same), `animation-play-state: paused` |
+
+### Variant model
+
+- `direction`: `left`, `right`. Default `left`.
+- `speed`: any number. Default `30`.
+- `pauseOnHover`: `true`, `false`. Default `false`.
+- `edgeFade`: `true`, `false`. Default `false`.
+- Total members: infinite (speed is continuous).
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Components`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+- [ ] The track animation is CSS-only; the Penpot recipe is a static snapshot, not an animated board.
+- [ ] Modifier classes `dsx-marquee--left` and `dsx-marquee--right` are emitted by the prop def but not consumed by the CSS; document the redundancy.
+- [ ] Reduced motion is represented as a static wrapping snapshot with one visible content copy.
+- [ ] Edge fade is documented as an opt-in runtime mask and clears for focus/reduced motion.

package/dist/docs/menu.md

@@ -0,0 +1,320 @@
+---
+title: Menu
+status: canonical
+category: Components
+archetype: utility
+package_path: packages/d4gger-design-system/src/components/menu/Menu.tsx
+css_path: packages/d4gger-design-system/src/styles/components/menu.css
+props_path: packages/d4gger-design-system/src/components/menu/menu.props.ts
+test_path: packages/d4gger-design-system/src/test/components/menu-migration.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on:
+  - "@radix-ui/react-dropdown-menu (the underlying Radix primitive; `MenuRoot`, `MenuTrigger`, `MenuItem`, and `MenuSeparator` proxy to it)"
+  - _internal/BaseDialog (PortalThemeBoundary + PortalThemeWrapper for portal theme mirroring; the abstraction does not have its own visual surface but it must mirror the wrapper's `data-dsx-*` attribute contract into the portal)
+  - _internal/motion (MOTION_TRANSITIONS.menu for the content open / close animation, MOTION_TRANSITIONS.reduced for `prefers-reduced-motion: reduce`)
+  - _internal/usePrefersReducedMotion (gates the content motion)
+  - framer-motion (motion + AnimatePresence for the content open / close)
+---
+
+# Menu
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+The internal abstraction shared by `DropdownMenu`, `ContextMenu`, and `Menubar`. `Menu` does not have a public visual surface; it hosts the common Radix dropdown-menu anatomy plus the token-aligned menu styling and the framer-motion content open / close animation. The public menu surfaces wrap `Menu` to expose their own `Root`, `Trigger`, `Content`, `Item`, `Label`, and `Separator` slots, and the `Menu` components are not exported from `src/components/index.ts`.
+
+## Anatomy & slots
+
+**Parent:** `MenuRoot` (the root, wrapped in `PortalThemeBoundary`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `MenuRoot` | `<div>` wrapping Radix `DropdownMenu.Root` | `PortalThemeBoundary` probe + Radix `DropdownMenu.Root` | Hosts the open state. The default Radix root is replaceable via the `root` prop. |
+| `MenuTrigger` | Radix `DropdownMenu.Trigger` (or replacement) | `dsx-menu__trigger` | The element that opens the menu. The default Radix trigger is replaceable via the `trigger` prop. |
+| `MenuPortal` | Radix `DropdownMenu.Portal` (or replacement; can be `null` to skip the portal) | `<DropdownMenuPrimitive.Portal>` or fragment | The portal. The `wrapWithTheme` prop wraps the children in `PortalThemeWrapper` when the consumer does not pass its own portal. `portal === null` short-circuits the portal entirely. |
+| `MenuContent` | Radix `DropdownMenu.Content` wrapping a `motion.div` | `dsx-menu`, `dsx-menu__content` + `data-size` | The popover surface. Animates open / close via `AnimatePresence` and `motion.div`. |
+| `MenuItem` | Radix `DropdownMenu.Item` (or replacement) | `dsx-menu__item` + `data-destructive`, `data-inset` | The selectable row. |
+| `MenuSeparator` | Radix `DropdownMenu.Separator` (or replacement) | `dsx-menu__separator` | The visual divider. |
+| `MenuOverlay` | `<div>` (or replacement) | `dsx-menu__overlay` | Optional scrim layer. `MenuContent` does not render the overlay by default; the public surfaces that need an overlay wrap it. |
+
+The roster's `Parent / Slots` column lists `Menu.Root`, `Menu.Trigger`, `Menu.Content`, `Menu.Item`, `Menu.Separator` for the public-API shape. The runtime in `Menu.tsx` exports the pieces as `MenuRoot`, `MenuTrigger`, `MenuPortal`, `MenuContent`, `MenuItem`, `MenuSeparator`, `MenuOverlay` (no `Object.assign` and no `Menu.Root` accessor on the public surface). The public menu surfaces (`DropdownMenu`, `ContextMenu`, `Menubar`) consume these named exports directly. The spec records the runtime shape; the roster's `Menu.Root` / `Menu.Trigger` style is the would-be public API if the abstraction were promoted.
+
+## Props contract
+
+The public `Menu` components do not ship a `Menu` accessor with attached subcomponents. The following props are on the individual named exports.
+
+### `MenuRoot`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `root` | `React.ElementType` | `DropdownMenuPrimitive.Root` | no | Replacement for the default Radix `DropdownMenu.Root`. Used by `DropdownMenu`, `ContextMenu`, and `Menubar` to swap the underlying primitive without losing the theme boundary. | no |
+| `open` | `boolean` | `undefined` | no | Standard Radix `open` controlled state. | no |
+| `defaultOpen` | `boolean` | `undefined` | no | Standard Radix `defaultOpen` uncontrolled state. | no |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Standard Radix `onOpenChange` callback. | no |
+| `modal` | `boolean` | `undefined` | no | Standard Radix `modal` prop. | no |
+| `dir` | `'ltr' \| 'rtl'` | `undefined` | no | Standard Radix `dir` prop. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The menu content. | no |
+
+### `MenuTrigger`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `trigger` | `React.ElementType` | `DropdownMenuPrimitive.Trigger` | no | Replacement for the default Radix `DropdownMenu.Trigger`. | no |
+| `triggerClassName` | `string` | `undefined` | no | Class appended to the trigger's `dsx-menu__trigger` class. | no |
+| `asChild` | `boolean` | `undefined` | no | Standard Radix `asChild` prop, forwarded to the trigger. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-menu__trigger`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The trigger content. | no |
+
+### `MenuPortal`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `portal` | `React.ElementType \| null` | `DropdownMenuPrimitive.Portal` | no | Replacement for the default Radix `DropdownMenu.Portal`. `null` skips the portal and renders the children inline. | no |
+| `wrapWithTheme` | `boolean` | `false` | no | When `true` and the children are a valid element, wraps them in `PortalThemeWrapper` so the portal's `data-dsx-*` attributes mirror the wrapper. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The portal content. | no |
+
+### `MenuContent`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `content` | `React.ElementType` | `DropdownMenuPrimitive.Content` | no | Replacement for the default Radix `DropdownMenu.Content`. `Menubar` swaps to its own `Content`; `DropdownMenu` uses the Radix one. | no |
+| `contentClassName` | `string` | `undefined` | no | Class appended to the content's `dsx-menu` / `dsx-menu__content` class. | no |
+| `forceMount` | `boolean` | `false` | no | Forwards `forceMount asChild` to the Radix content. Used by `Menubar` to keep submenus mounted. | no |
+| `open` | `boolean` | `true` | no | Internal `AnimatePresence` open flag. When `false`, the content exits the DOM via the animation. | no |
+| `portal` | `React.ElementType \| null` | `DropdownMenuPrimitive.Portal` | no | Portal component. `null` skips the portal. `DropdownMenuSubContent` passes `null` to render the sub-content inline. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Size variant. Writes `data-size` on the content. The CSS does not currently declare matching `[data-size='...']` rules; the prop is the public menu surfaces' size knob. | no |
+| `sideOffset` | `number` | `undefined` | no | Standard Radix `sideOffset`. When set, forwarded to the content; when `undefined`, the prop is not forwarded. | no |
+| `align` | `'start' \| 'center' \| 'end'` | `undefined` | no | Standard Radix `align`. | no |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `undefined` | no | Standard Radix `side`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to the content's `dsx-menu` / `dsx-menu__content` class. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The content. | no |
+
+### `MenuItem`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `destructive` | `boolean` | `false` | no | Marks the item as destructive. Writes `data-destructive="true"`; the CSS does not currently declare a `[data-destructive='true']` rule (the public menu surfaces add their own destructive variant via `dsx-{name}__item--destructive` modifier classes). | no |
+| `inset` | `boolean` | `false` | no | Indents the item to align with items that have a leading icon. Writes `data-inset="true"`; the CSS does not currently declare a `[data-inset='true']` rule. | no |
+| `item` | `React.ElementType` | `DropdownMenuPrimitive.Item` | no | Replacement for the default Radix `DropdownMenu.Item`. | no |
+| `itemClassName` | `string` | `undefined` | no | Class appended to the item's `dsx-menu__item` class. | no |
+| `disabled` | `boolean` | `undefined` | no | Standard Radix `disabled` prop. | no |
+| `onSelect` | `(event: Event) => void` | `undefined` | no | Standard Radix `onSelect` callback. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-menu__item`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The item content. | no |
+
+### `MenuSeparator`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `separator` | `React.ElementType` | `DropdownMenuPrimitive.Separator` | no | Replacement for the default Radix `DropdownMenu.Separator`. | no |
+| `separatorClassName` | `string` | `undefined` | no | Class appended to the separator's `dsx-menu__separator` class. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-menu__separator`. | no |
+
+### `MenuOverlay`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `overlay` | `React.ElementType` | `'div'` | no | Replacement for the default `<div>` host. | no |
+| `overlayClassName` | `string` | `undefined` | no | Class appended to the overlay's `dsx-menu__overlay` class. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-menu__overlay`. | no |
+
+Rules that apply to this row:
+
+- Every named export accepts a `*-ClassName` prop and a `*` (the underlying element) prop. The pattern lets the public menu surfaces apply their own naming convention (e.g. `dsx-dropdown-menu__item`) without re-implementing the Radix wiring.
+- The `Menu` abstraction is internal. Apps should not import the named exports directly; use `DropdownMenu`, `ContextMenu`, or `Menubar` instead. Promote the abstraction to public only if a fourth menu surface appears.
+- `MenuContent`'s `open` prop defaults to `true` so a force-mounted content (e.g. a `Menubar` submenu) renders. `DropdownMenu` passes the actual open state from the `DropdownMenuOpenContext` so the content animates in / out as the menu opens and closes.
+
+## CSS class contract
+
+**Root classes:** `dsx-menu`, `dsx-menu__content` (the content). The trigger is `dsx-menu__trigger`. Items are `dsx-menu__item`. Separators are `dsx-menu__separator`. Overlays are `dsx-menu__overlay`.
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | (no CSS rule declared in `menu.css` today; the public menu surfaces add their own size overrides) | `menu.css` |
+| `data-state` | `open`, `closed` | `.dsx-menu[data-state='open']`, `.dsx-menu__content[data-state='open']` (in animation), `.dsx-menu[data-state='closed']`, `.dsx-menu__content[data-state='closed']` (out animation) | `menu.css` |
+| `data-highlighted` | (presence, written by Radix) | `.dsx-menu__item[data-highlighted]` (hover background; the broader hover state for all menu items lives in `_internal/baseMenu.css`) | `menu.css` (+ `_internal/baseMenu.css`) |
+| `data-disabled` | (presence, written by Radix) | `.dsx-menu__item[data-disabled]` (opacity fade, pointer-events off) | `menu.css` |
+| `data-destructive` | `'true'` | (no CSS rule in `menu.css`; the public menu surfaces add their own destructive variant) | n/a |
+| `data-inset` | `'true'` | (no CSS rule in `menu.css`; the public menu surfaces add their own inset padding) | n/a |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `MenuRoot` | (no class on the root; the boundary is invisible) | n/a |
+| `MenuTrigger` | `dsx-menu__trigger` | `menu.css` |
+| `MenuContent` | `dsx-menu`, `dsx-menu__content` | `menu.css` |
+| `MenuItem` | `dsx-menu__item` | `menu.css` (+ `_internal/baseMenu.css` for hover, focus, selected, disabled) |
+| `MenuSeparator` | `dsx-menu__separator` | `menu.css` |
+| `MenuOverlay` | `dsx-menu__overlay` | `menu.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size` is single-value only and the prop def is not `responsive: true`.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- The content animation uses `MOTION_TRANSITIONS.menu` by default and `MOTION_TRANSITIONS.reduced` when `usePrefersReducedMotion()` returns `true`. The reduced motion path collapses to opacity-only.
+- The CSS `@keyframes dsx-menu-in` and `@keyframes dsx-menu-out` are declared in `menu.css`; they are the fallback when framer-motion is not used (e.g. when the consumer force-mounts the content with `forceMount asChild` and the `motion.div` is the only animated layer).
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token, with three documented exceptions (the Radix CSS variables for `available-height` and `transform-origin`, which are not tokens).
+
+| Property | Token | Role |
+|---|---|---|
+| Trigger gap | `var(--dsx-space-xs)` | Gap between trigger content. |
+| Content max-height | `var(--radix-dropdown-menu-content-available-height)` | Radix-provided sizing variable (not a token). |
+| Content transform origin | `var(--radix-dropdown-menu-content-transform-origin)` | Radix-provided anchor (not a token). |
+| Item gap | `var(--dsx-space-sm)` | Gap between item content. |
+| Item padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Inner gutter. |
+| Item radius | `var(--dsx-rounded-sm)` | Rounded highlight surface. |
+| Item typography | `var(--dsx-typography-body-medium-*` | Body ramp. |
+| Item color | `var(--dsx-color-on-surface)` | Resting text. |
+| Item highlight background | `var(--dsx-effect-hover-ghost)` | Hover / keyboard-focus highlight. |
+| Item disabled opacity | `var(--dsx-opacity-disabled)` | Disabled fade. |
+| Separator height | `1px` | Hard-coded divider height (see Anomalies). |
+| Separator margin | `var(--dsx-space-xs)` calc(-1) | Inset margin. |
+| Separator background | `var(--dsx-color-outline-variant)` | Divider color. |
+| Overlay z-index | `calc(var(--dsx-z-index-dropdown) - 1)` | Just under the content. |
+| Animation duration | `var(--dsx-motion-duration-fast)` | Open / close keyframes. |
+| Animation easing (in) | `var(--dsx-motion-easing-emphasized)` | Open easing. |
+| Animation easing (out) | `var(--dsx-motion-easing-in)` | Close easing. |
+| Motion preset (in) | `MOTION_TRANSITIONS.menu` (`duration.fast`, `ease.emphasized`) | Content open motion. |
+| Motion preset (reduced) | `MOTION_TRANSITIONS.reduced` (`duration: 0`) | Reduced motion fallback. |
+
+Rules:
+
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The `1px` separator height is hard-coded to match the body `1px` baseline.
+- `menu.css` no longer declares `background`, `border`, `border-radius`, `padding`, `min-width`, or `box-shadow` on `.dsx-menu`/`.dsx-menu__content`. Those properties are owned solely by the public surface CSS (`dropdown-menu.css`, `context-menu.css`, `menubar.css`), which already agreed on the same recipe (`--dsx-color-surface-overlay`, `--dsx-rounded-lg`, `--dsx-size-menu-min-width`, `--dsx-shadow-elevation-3`-via-`baseMenu.css`). Previously `menu.css` was imported last in `components.css` and, at equal selector specificity, silently overrode that recipe with a stale one (`surface-raised`, `rounded-md`, hard-coded `8rem`, `shadow-md`/elevation-2) for `DropdownMenu` and `ContextMenu` only — `Menubar` was unaffected because `MenubarContent` never carried the `dsx-menu` class, which is why the three surfaces looked subtly different despite sharing a spec.
+- The Radix CSS variables (`--radix-dropdown-menu-content-available-height`, `--radix-dropdown-menu-content-transform-origin`) are provided by Radix at runtime and are not design tokens. They are the boundary between the Radix positioning layer and the package's visual layer; the spec keeps them explicit so consumers do not treat them as themable.
+- Item hover, focus, selected, and disabled states that are shared across the menu family (DropdownMenu, ContextMenu, Menubar) live in `_internal/baseMenu.css` rather than `menu.css`. The public menu surfaces import `baseMenu.css` to inherit those rules.
+
+## Motion contract
+
+| Region | Token / preset | Default | Reduced |
+|---|---|---|---|
+| Content open / close (via framer-motion `motion.div`) | `MOTION_TRANSITIONS.menu` | `initial: { opacity: 0, y: 4 }`, `animate: { opacity: 1, y: 0 }`, `exit: { opacity: 0, y: 2 }`, `duration: motionDurations.fast`, `ease: motionEasings.emphasized` | `MOTION_TRANSITIONS.reduced` — `initial: { opacity: 0 }`, `animate: { opacity: 1 or 0 }`, `exit: { opacity: 0 }` |
+| Content open / close (CSS keyframes fallback) | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-emphasized)` (in) / `var(--dsx-motion-easing-in)` (out) | `dsx-menu-in` (`opacity 0->1, scale 0.95->1`) and `dsx-menu-out` (`opacity 1->0, scale 1->0.95`) applied via `[data-state='open']` and `[data-state='closed']` | The CSS keyframes are not gated by `prefers-reduced-motion`; the runtime uses `usePrefersReducedMotion` to swap the framer-motion preset, which is the active path. |
+
+Rules:
+
+- `MenuContent` uses `usePrefersReducedMotion` from `src/_internal/usePrefersReducedMotion.ts` to pick the motion preset. The hook returns `true` when the user agent reports `prefers-reduced-motion: reduce`.
+- The framer-motion `motion` and `AnimatePresence` imports are re-exported from `@d4gger/design-system/motion`. The `AnimatePresence` is required to drive the `exit` animation; without it the content unmounts immediately.
+- The CSS keyframes are a safety net. They are declared in `menu.css` but are not the primary animation path. Consumers that bypass framer-motion (by force-mounting the content with `forceMount asChild` and skipping `AnimatePresence`) will see the CSS keyframes instead.
+- The motion preset must be a named entry from `MOTION_TRANSITIONS`; the spec does not allow new presets.
+
+## Accessibility
+
+**Roles:**
+
+- `MenuRoot` is a Radix `DropdownMenu.Root`. It does not set a role; the menu semantically is a `menu` (from `MenuContent`'s underlying Radix primitive).
+- `MenuTrigger` is a `button` (from Radix's default trigger) with `aria-haspopup="menu"` and `aria-expanded` managed by Radix.
+- `MenuContent` is a `menu` (Radix sets `role="menu"`); `MenuItem` is a `menuitem` (Radix sets `role="menuitem"`); `MenuSeparator` is a `separator` (Radix sets `role="separator"`).
+- `MenuOverlay` is decorative by default; it has no role. The public menu surfaces that use it as a scrim layer can add a role or `aria-hidden` at the public-surface level.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Enter`, `Space` (on trigger) | Opens the menu and focuses the first item. |
+| `↓`, `↑` (on trigger) | Opens the menu and focuses the first / last item. |
+| `Esc` (inside menu) | Closes the menu and returns focus to the trigger. |
+| `↓`, `↑` (inside menu) | Moves focus to the next / previous item. Wraps at the ends. |
+| `Home`, `End` (inside menu) | Moves focus to the first / last item. |
+| `Tab` (inside menu) | Closes the menu and moves focus to the next tabbable element on the page. |
+| Type-ahead (inside menu) | Radix type-ahead focuses the item whose leading characters match the typed keys. |
+| `Enter`, `Space` (on item) | Activates the item and closes the menu. |
+
+**Focus:**
+
+- Visible focus ring via the `_internal/baseMenu.css` rule `:where(:focus-visible) { box-shadow: var(--dsx-shadow-focus-ring) }`. The ring must remain visible on dark and light surfaces.
+- Focus management for overlay menus: focus is trapped inside the menu while it is open; focus returns to the trigger on close. This is the standard Radix behavior.
+
+**Reduced motion:**
+
+- `usePrefersReducedMotion` gates the content motion. The CSS keyframes are a fallback only.
+
+**Color and meaning:**
+
+- The destructive state on a `MenuItem` is communicated by the `data-destructive="true"` attribute and the public menu surfaces' own `dsx-{name}__item--destructive` modifier class. The runtime does not declare a CSS rule in `menu.css` for `data-destructive`; the public surfaces own the visual treatment.
+- The disabled state on a `MenuItem` is communicated by the `data-disabled` attribute, the `var(--dsx-opacity-disabled)` opacity, the `pointer-events: none` rule, and the `var(--dsx-color-disabled-text)` color (in `baseMenu.css`).
+
+**Naming:**
+
+- The `MenuTrigger` is responsible for the accessible name of the menu trigger. Apps that render an icon-only trigger must supply `aria-label`.
+- The `MenuItem` content is the accessible name. Apps that render only an icon must supply `aria-label` on the item.
+- The `MenuContent` is named by the `MenuTrigger`'s accessible name (Radix sets `aria-labelledby` automatically).
+
+## Playground demo spec
+
+The `Menu` abstraction does not have a public demo. The public menu surfaces (`DropdownMenu`, `ContextMenu`, `Menubar`) have their own demos. The `demo_path` recorded here points at the shared playground root; the spec assumes the playground page renders the public menu surfaces, not the `Menu` abstraction directly.
+
+The `test_path` is `packages/d4gger-design-system/src/test/components/menu-migration.test.tsx` (the migration test asserts the public menu surfaces still write the expected `data-*` attributes and that the portal theme mirroring works through `PortalThemeBoundary` + `PortalThemeWrapper`). The test exercises `DropdownMenu`, `ContextMenu`, and `Menubar` end to end.
+
+**Default story:** see `DropdownMenu`, `ContextMenu`, and `Menubar` specs.
+
+**Variant story:** see `DropdownMenu`, `ContextMenu`, and `Menubar` specs.
+
+**State story:** the migration test asserts:
+
+- `<DropdownMenu.Item destructive inset>` writes `data-destructive="true"`, `data-inset="true"`, and `dsx-dropdown-menu__item`.
+- `<ContextMenu.Item destructive inset>` writes the same attributes and class.
+- `<Menubar.Item destructive inset>` writes the same attributes and class.
+- The portal content inside a `Theme mode="light"` wrapper receives `data-dsx-theme="light"` through `PortalThemeWrapper` (asserted for all three public surfaces).
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-dropdown-menu`: the underlying Radix primitive. `MenuRoot`, `MenuTrigger`, `MenuItem`, and `MenuSeparator` proxy to it by default; the public menu surfaces swap the underlying primitive via the `root`, `trigger`, `item`, and `separator` props to use the matching Radix primitive (`DropdownMenu`, `ContextMenu`, or `Menubar`).
+- `_internal/BaseDialog`: `PortalThemeBoundary` and `PortalThemeWrapper` for portal theme mirroring. `MenuRoot` always wraps in `PortalThemeBoundary`; `MenuContent` always wraps the content in `PortalThemeWrapper`. `MenuPortal`'s `wrapWithTheme` prop lets a consumer request the wrapper at the portal level too.
+- `_internal/motion`: `MOTION_TRANSITIONS.menu` and `MOTION_TRANSITIONS.reduced` for the content open / close animation.
+- `_internal/usePrefersReducedMotion`: gates the framer-motion preset.
+- `framer-motion` (re-exported from `@d4gger/design-system/motion`): `motion` and `AnimatePresence` for the content animation.
+- `_internal/baseMenu.css`: shared item hover, focus, selected, and disabled rules. The public menu surfaces import `baseMenu.css` to inherit those rules; the `Menu` CSS file does not import it directly.
+
+**Used by:**
+
+- `DropdownMenu` (canonical public surface): consumes `MenuRoot`, `MenuPortal`, `MenuContent`, `MenuItem`, `MenuSeparator`. Swaps `item`, `separator`, and `content` to `DropdownMenuPrimitive.*` and adds `dsx-dropdown-menu__*` classes.
+- `ContextMenu` (canonical public surface): same pattern, with `ContextMenuPrimitive.*` swaps.
+- `Menubar` (canonical public surface): same pattern, with `MenubarPrimitive.*` swaps; also passes `forceMount` on the content to keep submenus mounted.
+
+`Menu` does not have other consumers. The `Menu` abstraction is internal and is not exported from `src/components/index.ts`. Apps should not import the named exports directly.
+
+**State boundaries:**
+
+- Owned by `Menu`: the Radix dropdown-menu wiring, the framer-motion content open / close animation, the `PortalThemeBoundary` and `PortalThemeWrapper` integration, the `usePrefersReducedMotion` gate, the `dsx-menu` and slot classes, and the `data-size` attribute on the content.
+- Owned by the public menu surfaces: the surface-specific `data-*` attribute contracts (for example, `DropdownMenu.Item` adds `dsx-dropdown-menu__item` via `itemClassName`), the surface-specific `data-destructive` and `data-inset` styling, and the surface-specific `data-checked` / `aria-checked` for checkbox and radio items.
+- Owned by the consumer: the open / close state, the menu items, the destructive state on a per-item basis, the inset state on a per-item basis, and the form-row or page-level context that wraps the menu trigger.
+
+**Boundary rules:**
+
+- App-owned data: the menu items, the open / close state model, the action handlers, the destructive semantics, the keyboard chord model (for Menubar), and the surrounding page context.
+- DS-owned visuals: token bindings, the `dsx-menu` and slot classes, the content animation, the portal theme mirroring, the `data-size` attribute on the content, and the shared hover / focus / selected / disabled rules in `baseMenu.css`.
+- The `Menu` abstraction is internal. Public menu surfaces own the public API. Promote `Menu` to public only if a fourth menu surface needs the shared primitive.
+
+## Anomalies
+
+- **`Menu` is not exported from the public surface.** `src/components/index.ts` does not include `export * from './menu/Menu'`. The named exports (`MenuRoot`, `MenuTrigger`, etc.) are only available to other components in the package. The roster's `Parent / Slots` column lists `Menu.Root`, `Menu.Trigger`, `Menu.Content`, `Menu.Item`, `Menu.Separator` — that is the would-be public API if the abstraction were promoted. Until then, the runtime exports are `MenuRoot`, `MenuTrigger`, `MenuPortal`, `MenuContent`, `MenuItem`, `MenuSeparator`, `MenuOverlay` (no `Object.assign` and no `Menu.*` accessor).
+- **`data-destructive` and `data-inset` are not CSS-backed in `menu.css`.** The attributes are written by the runtime on `MenuItem`, but `menu.css` has no `[data-destructive='true']` or `[data-inset='true']` rules. The public menu surfaces add their own visual treatment via `dsx-{name}__item--destructive` and `dsx-{name}__item--inset` modifier classes; the `data-*` attributes are the cross-surface contract that downstream CSS hooks onto.
+- **`data-size` is not CSS-backed in `menu.css`.** The attribute is written on the content; the public menu surfaces add their own size overrides (for example, `dsx-dropdown-menu__content[data-size='sm']` if needed). The CSS file does not declare any size rules today.
+- **No `Menu` accessor is exposed via `Object.assign`.** Sibling compound components (`DropdownMenu`, `ContextMenu`, `Menubar`) attach their subcomponents via `Object.assign`. `Menu` does not. Consumers import the named exports directly.
+- **Separator height is hard-coded.** `height: 1px` is not a token; it matches the body `1px` baseline. A future revision should consider whether this belongs in the token set (for example, `--dsx-separator-height`).
+- **FIXED 2026-07-03 (visual triage V-1): `menu.css` was silently overriding the public surfaces' own recipe.** `.dsx-menu`/`.dsx-menu__content` used to declare `background: var(--dsx-color-surface-raised)`, `border-radius: var(--dsx-rounded-md)`, and `min-width: 8rem`, which — because `menu.css` imports last in `components.css` — won the cascade over `dropdown-menu.css`'s and `context-menu.css`'s own `surface-overlay`/`rounded-lg`/`--dsx-size-menu-min-width` recipe at equal specificity. This made `DropdownMenu` and `ContextMenu` render a duller, smaller-radius panel than `Menubar` (which was unaffected, since it never carries the `dsx-menu` class). Removed the conflicting declarations from `menu.css`; the per-surface CSS is now the single owner of panel visuals. See also the light-mode `--dsx-color-surface-overlay` token fix (was darker than `--dsx-color-background`, read as "muddy"; now lighter, so popovers read as lifted).
+- **CSS keyframes are not gated by `prefers-reduced-motion`.** The `dsx-menu-in` and `dsx-menu-out` keyframes in `menu.css` are declared without a `prefers-reduced-motion: reduce` media query. The runtime prefers the framer-motion path, which is gated by `usePrefersReducedMotion`; the CSS keyframes only fire when a consumer force-mounts the content and bypasses `AnimatePresence`. The CSS keyframes should still be gated for full coverage.
+- **Roster says "utility" but the abstraction is closer to a `radix-wrapper` / `radix-compound`.** The roster's archetype column lists `Menu` as `utility` because it is internal and has no public visual surface. The runtime is a Radix compound (`MenuRoot` + `MenuTrigger` + `MenuContent` + `MenuItem` + `MenuSeparator` + `MenuPortal` + `MenuOverlay`) with a Radix dropdown-menu backend. The spec records the roster's `utility` archetype; the runtime shape is closer to `radix-compound` with an internal-only surface.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+The `Menu` abstraction does not have a published Penpot asset; it is an internal abstraction. The public menu surfaces (`DropdownMenu`, `ContextMenu`, `Menubar`) have their own Penpot assets. The spec marks the Penpot section as not applicable for the `Menu` abstraction itself.
+
+A future promotion of `Menu` to a public surface would track the same Penpot contract as `DropdownMenu.Content` (since that is the canonical menu panel), with `data-size` driving sm / md / lg panels and the `dsx-menu` class as the root.