@d4gger/design-system 2.7.0

package/dist/docs/toolbar.md

@@ -0,0 +1,234 @@
+---
+title: Toolbar
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/toolbar/Toolbar.tsx
+css_path: packages/d4gger-design-system/src/styles/components/toolbar.css
+props_path: packages/d4gger-design-system/src/components/toolbar/toolbar.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Toolbar.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/navigation.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Button
+  - Toggle
+  - ToggleGroup
+  - Separator
+---
+
+# Toolbar
+
+> 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 dense editor-style action strip with roving-focus arrow-key movement, used for text formatting toolbars, view-mode clusters, and any surface where a small group of related controls needs to live together with shared chrome. Toolbar is built on `@radix-ui/react-toolbar` for the keyboard semantics; the package owns the visual surface and slot classes.
+
+## Anatomy & slots
+
+**Parent:** `Toolbar` (alias of `ToolbarRoot`). The root is `@radix-ui/react-toolbar`'s `Root`, which renders a `<div role="toolbar">`.
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Toolbar` (root) | `<div role="toolbar">` (Radix `Toolbar.Root`) | `dsx-toolbar` | Root. Writes `data-size`. Forwards orientation, dir, and roving-focus props from Radix. |
+| `Toolbar.Button` | Radix `Toolbar.Button` | `dsx-toolbar__button` | Standard action button. |
+| `Toolbar.ToggleButton` | Radix `Toolbar.ToggleItem` | `dsx-toolbar__toggle-button` | Pressed / unpressed button. Reads `pressed` / `defaultPressed` from Radix. |
+| `Toolbar.ToggleGroup` | Radix `Toolbar.ToggleGroup` | `dsx-toolbar__toggle-group` | Co-ordinated group of `ToggleButton`s. Accepts `type="single" \| "multiple"` and `value` / `defaultValue` / `onValueChange` from Radix. Children are visually joined with shared borders and rounded corners. |
+| `Toolbar.Link` | Radix `Toolbar.Link` | `dsx-toolbar__link` | Anchor inside the toolbar. |
+| `Toolbar.Separator` | Radix `Toolbar.Separator` | `dsx-toolbar__separator` | Vertical divider. Renders `var(--dsx-control-separator-color)` and is sized `var(--dsx-size-md)` tall. |
+
+**Internal layout:**
+
+- The root renders an inline-flex row with `gap: var(--dsx-space-sm)`, `padding: var(--dsx-space-xs) var(--dsx-space-sm)`, a `1px` outline, and `box-shadow: var(--dsx-effect-shadow-1)`.
+- A `data-variant="compact"` modifier (declared in CSS) tightens the gap to `var(--dsx-space-xs)` and the padding to `var(--dsx-space-xs)`. The Radix `Root` does not currently write `data-variant`; the modifier is reserved for a future variant prop.
+- `ToggleGroup` children share borders: the first / last child get the rounded corners, and adjacent children overlap by `1px` to produce a single visible border.
+- `Toolbar.Separator` is a `var(--dsx-border-width-sm)` wide, `var(--dsx-size-md)` tall bar with `var(--dsx-control-separator-color)`.
+
+## Props contract
+
+**Root props (`Toolbar`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Density scale. Writes `data-size`. | no |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Inherited from Radix `Toolbar.Root`. Determines roving-focus direction. | no |
+| `dir` | `'ltr' \| 'rtl'` | `undefined` | no | Inherited from Radix `Toolbar.Root`. | no |
+| `loop` | `boolean` | `true` | no | Inherited from Radix `Toolbar.Root`. Whether roving focus wraps. | no |
+| `asChild` | `boolean` | `false` | no | Inherited from Radix. | no |
+
+The root accepts every prop supported by `@radix-ui/react-toolbar`'s `Root`. The `extractProps` call strips `asChild` (Radix handles it) and `size` (consumed for `data-size`); the rest are forwarded.
+
+**Slot props:**
+
+| Slot | Inherited from Radix | Notes |
+|---|---|---|
+| `Toolbar.Button` | `ToolbarPrimitive.Button` props | Standard button props. `asChild` is consumed and not forwarded. |
+| `Toolbar.ToggleButton` | `ToolbarPrimitive.ToggleItem` props | `pressed`, `defaultPressed`, `onPressedChange`, `disabled`. `asChild` is consumed and not forwarded. |
+| `Toolbar.ToggleGroup` | `ToolbarPrimitive.ToggleGroup` props | `type="single" \| "multiple"`, `value`, `defaultValue`, `onValueChange`, `rovingFocus`, `loop`. `asChild` is consumed and not forwarded. The `type` prop is the only variant the slot uses; the Radix branch in the TSX runs the same JSX for both types. |
+| `Toolbar.Link` | `ToolbarPrimitive.Link` props | Anchor props. `asChild` is consumed and not forwarded. |
+| `Toolbar.Separator` | `ToolbarPrimitive.Separator` props | `decorative`, `orientation`. `asChild` is consumed and not forwarded. |
+
+## CSS class contract
+
+**Root class:** `dsx-toolbar`
+
+**Modifier classes** (driven by `data-*` attributes and a reserved `data-variant`):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | (forwarded attribute; size-specific rules live on slot classes) | `toolbar.css` |
+| `data-variant` (reserved) | `compact` | `.dsx-toolbar[data-variant='compact']` | `toolbar.css` |
+| `.dsx-toolbar-variant-compact` | n/a | `.dsx-toolbar-variant-compact` (utility-style class for app-level overrides) | `toolbar.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Toolbar` (root) | `dsx-toolbar` | `toolbar.css` |
+| `Toolbar.Button` | `dsx-toolbar__button` | `toolbar.css` |
+| `Toolbar.ToggleButton` | `dsx-toolbar__toggle-button` | `toolbar.css` |
+| `Toolbar.ToggleGroup` | `dsx-toolbar__toggle-group` | `toolbar.css` |
+| `Toolbar.Link` | `dsx-toolbar__link` | `toolbar.css` |
+| `Toolbar.Separator` | `dsx-toolbar__separator` | `toolbar.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. Responsive layout comes from the layout primitives' responsive classes when the consumer wraps the toolbar in a responsive shell.
+
+**Reduced motion:**
+
+- The component is static. No motion is applied.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token. The base interactive look is inherited from `src/_internal/baseButton.css` (imported at the top of `toolbar.css`), so button and toggle-button surface values come from the base.
+
+| Property | Token | Role |
+|---|---|---|
+| Root gap | `var(--dsx-space-sm)` | Default gap between controls |
+| Root padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Internal gutter |
+| Root border-radius | `var(--dsx-rounded-md)` | Roundness |
+| Root border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Edge |
+| Root background | `var(--dsx-color-surface-raised)` | Toolbar surface |
+| Root shadow | `var(--dsx-effect-shadow-1)` | Elevation |
+| Compact root gap | `var(--dsx-space-xs)` | Compact variant gap |
+| Compact root padding | `var(--dsx-space-xs)` | Compact variant padding |
+| Button / Link / ToggleButton min-height | `var(--dsx-size-lg)` | Min hit target |
+| Button / Link / ToggleButton padding-inline | `var(--dsx-space-sm)` | Horizontal padding |
+| Button / Link / ToggleButton radius | `var(--dsx-rounded-md)` | Roundness |
+| Button / Link / ToggleButton color | `var(--dsx-color-on-surface)` | Default text color |
+| ToggleGroup border | `var(--dsx-border-width-sm)` (used in overlap math) | Shared border |
+| ToggleGroup first / last radius | `var(--dsx-grouped-radius, var(--dsx-rounded-md))` | Group rounding |
+| Separator width | `var(--dsx-border-width-sm)` | Separator thickness |
+| Separator height | `var(--dsx-size-md)` | Separator length |
+| Separator color | `var(--dsx-control-separator-color)` | Separator color |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | none | none | n/a |
+
+The component has no motion. Roving focus and pressed-state transitions are handled by Radix's default styles and by the browser, not by the package CSS.
+
+## Accessibility
+
+**Roles:**
+
+- The root is a Radix `Toolbar.Root`, which renders `<div role="toolbar">`. Roving focus is managed by Radix.
+- `Toolbar.Button`, `Toolbar.ToggleButton`, `Toolbar.Link` render with their native roles (`button`, `button` with `aria-pressed`, `link`).
+- `Toolbar.Separator` renders with `role="separator"` (or is hidden from the a11y tree when `decorative` is set).
+- `Toolbar.ToggleGroup` renders with `role="group"` (or `role="toolbar"` when nested under a `Toolbar`).
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Enters / leaves the toolbar. Focus moves to the first focusable item on entry and back to the trigger on exit. |
+| `ArrowLeft` / `ArrowRight` (horizontal orientation) | Moves focus between focusable items with roving focus. |
+| `ArrowUp` / `ArrowDown` (vertical orientation) | Moves focus between focusable items with roving focus. |
+| `Home` / `End` | Moves focus to the first / last item. |
+| `Enter` / `Space` | Activates the focused button, toggle, or link. |
+| `Escape` | (Reserved for future variants) — Radix does not bind Escape to any default action. |
+
+**Focus:**
+
+- Visible focus ring is provided by the base button styles (`src/_internal/baseButton.css`).
+- The roving-focus ring skips disabled items.
+
+**Reduced motion:**
+
+- No motion is applied by the package CSS. The browser's default pressed-state transitions are unaffected by `prefers-reduced-motion` at the package level.
+
+**Color and meaning:**
+
+- Pressed state is communicated by `aria-pressed` and a visual treatment from the base button. Color is not used alone.
+- Disabled state is communicated by `disabled` attribute and reduced opacity from the base button.
+
+**Naming:**
+
+- Icon-only `Toolbar.Button` / `Toolbar.ToggleButton` slots must carry an accessible name (`aria-label` or visible label text). `Toolbar.Link` carries its anchor text.
+- The toolbar as a whole should have an accessible name via `aria-label` (Radix does not set a default).
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders a `Toolbar` with `aria-label="Editor toolbar"` containing two `Toolbar.Button`s and a `Toolbar.Separator`. Asserts the root has `role="toolbar"` and the matching `aria-label`.
+
+**Variant story:**
+
+- Renders a `Toolbar.ToggleGroup` with `type="multiple"` and two `Toolbar.ToggleButton`s. Asserts the toggle group renders with `role="group"` (or `role="toolbar"` when nested) and the toggle buttons are reachable by roving focus.
+
+**State story:**
+
+- Renders a `Toolbar.ToggleGroup` with one `Toolbar.ToggleButton defaultPressed`. Asserts `aria-pressed="true"` on that button.
+
+**Composition story:**
+
+- Renders a `Toolbar` containing a `Toolbar.Button`, a `Toolbar.Separator`, a `Toolbar.ToggleGroup`, and a `Toolbar.Link`. Asserts all slot classes render.
+
+**Token story:**
+
+- Renders the default toolbar inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the toolbar surface tracks `--dsx-color-surface-raised` and is unaffected by the accent token; pressed toggle buttons track the primary palette through the base button styles.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the default story. Asserts no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `orientation` | select | `horizontal` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-toolbar`: provides the `Root`, `Button`, `ToggleItem` (`ToggleButton`), `ToggleGroup`, `Link`, and `Separator` primitives. The package wraps each one and adds the `dsx-toolbar__*` classes.
+- `Button`, `Toggle`, `ToggleGroup`, `Separator`: referenced as the design language. The toolbar does not compose these by name; it borrows the same base interactive look from `src/_internal/baseButton.css`.
+- `RichTextEditor.Shell` composes `Toolbar` for the formatting strip.
+
+**Used by:**
+
+- `RichTextEditor.Shell` (`src/components/richTextEditor`): the formatting strip composes `Toolbar.ToggleGroup` for text-style / alignment clusters and `Toolbar.Separator` between clusters.
+- App-level editor and view-mode surfaces.
+
+**State boundaries:**
+
+- Owned by Toolbar: `size` and the `dsx-toolbar__*` slot classes. Roving focus and pressed-state are managed by Radix.
+- Owned by the consumer: button labels, icon content, `pressed` / `defaultPressed` / `onPressedChange` on `ToggleButton`, `value` / `defaultValue` / `onValueChange` on `ToggleGroup`, and the `aria-label` on the root.
+
+**Boundary rules:**
+
+- App-owned data: tool definitions, command palette integrations, view-mode state.
+- DS-owned visuals: token bindings, slot classes, separator geometry, and the surface / shadow combination.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. The package source is the only authority. Skip the section when the component is fully covered by the spec above; the spec's CSS class contract and token mapping table are the binding deliverable.

package/dist/docs/tooltip.md

@@ -0,0 +1,303 @@
+---
+title: Tooltip
+status: canonical
+category: Primitives
+archetype: radix-compound
+package_path: packages/d4gger-design-system/src/components/tooltip/Tooltip.tsx
+css_path: packages/d4gger-design-system/src/styles/components/tooltip.css
+props_path: packages/d4gger-design-system/src/components/tooltip/tooltip.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Tooltip.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/overlay.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on: []
+---
+
+# Tooltip
+
+> 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
+
+Brief, non-essential explanatory text that appears on hover or focus next to a trigger element. The DS `Tooltip` is a Radix-backed compound that exposes `Tooltip`, `TooltipTrigger`, `TooltipContent`, and `TooltipProvider`. Use it for keyboard-shortcut hints, icon-button labels, and terse clarifications; do not hide essential information behind a tooltip.
+
+## Anatomy & slots
+
+**Parent:** `Tooltip` (the Radix root). The package re-exports the Radix `Tooltip.Root` as `Tooltip` so apps do not need to reach into `@radix-ui/react-tooltip` directly.
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Tooltip` (Root) | `TooltipPrimitive.Root` | no DS class; owns open/closed state | Pass-through to the Radix root. |
+| `TooltipProvider` | `TooltipPrimitive.Provider` | no DS class; scopes delay and skip behavior | Defaults to `delayDuration={200}`. Wrap the app or a region with it; per-tooltip overrides go on the provider. |
+| `TooltipTrigger` | `TooltipPrimitive.Trigger` | consumer's host element (a `<button>` by default, or a slotted child when `asChild`) | Activates the tooltip on hover or focus. The `asChild` prop def wires through `extractProps`. |
+| `TooltipContent` | `TooltipPrimitive.Content` inside `TooltipPrimitive.Portal` inside `PortalThemeWrapper` | `dsx-tooltip` plus `dsx-tooltip--<variant>`; renders an arrow child with `dsx-tooltip__arrow` | The portal-wrapped content surface. Mirrors the active theme attributes via `PortalThemeWrapper`. |
+
+The compound follows the Radix naming: `Tooltip`, `TooltipProvider`, `TooltipTrigger`, `TooltipContent`. No subcomponents are renamed.
+
+## Props contract
+
+### `Tooltip` (Root)
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `open` | `boolean` | `undefined` | no | Controlled open state, forwarded to the Radix root. | no |
+| `defaultOpen` | `boolean` | `undefined` | no | Initial open state, forwarded to the Radix root. | no |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Open-change handler, forwarded to the Radix root. | no |
+| `delayDuration` | `number` | `undefined` | no | Open delay in ms; only honored when the active `TooltipProvider` allows per-tooltip overrides. | no |
+| `disableHoverableContent` | `boolean` | `undefined` | no | Forwarded to the Radix root. | no |
+
+### `TooltipProvider`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `delayDuration` | `number` | `200` | no | Default open delay in ms for every tooltip inside the provider. | no |
+| `disableHoverableContent` | `boolean` | `undefined` | no | Forwarded to the Radix provider. | no |
+| `skipDelayDuration` | `number` | `undefined` | no | Forwarded to the Radix provider. | no |
+
+### `TooltipTrigger`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the trigger through `Slot` from `@radix-ui/react-slot`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to the trigger. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the trigger. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Trigger body content. | no |
+| `aria-label` | `string` | `undefined` | no | Accessible name override. | no |
+
+### `TooltipContent`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'default' \| 'primary' \| 'error'` | `'default'` | no | Visual treatment; writes `dsx-tooltip--<variant>`. | no |
+| `sideOffset` | `number` | `8` | no | Distance in pixels between the trigger and the content. Forwarded to the Radix `Content`. | no |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `undefined` | no | Forwarded to the Radix `Content`; defaults to the Radix `top`. | no |
+| `align` | `'start' \| 'center' \| 'end'` | `undefined` | no | Forwarded to the Radix `Content`; defaults to the Radix `center`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-tooltip`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the content host. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Tooltip body content. | no |
+| `arrow` | `React.ReactNode` | `<TooltipPrimitive.Arrow .../>` | no | The arrow child. The default is a 8×4 arrow with the `dsx-tooltip__arrow` class. | no |
+
+Rules:
+
+- The Root and Provider are passthroughs; their prop types match the Radix types.
+- `TooltipTrigger` runs its `asChild` prop through `extractProps(tooltipTriggerPropDefs)` before forwarding the rest to the Radix primitive.
+- `TooltipContent` runs the incoming `variant` and `className` through `extractProps(tooltipContentPropDefs)`, then forwards the merged class to the Radix `Content`. The component also defaults `sideOffset` to `8` and renders a default arrow child when the consumer does not supply one.
+- The content portal mirrors the active theme attributes via `PortalThemeWrapper` from `_internal/BaseDialog.tsx`, so accent color, radius, density, and the rest of the `data-dsx-*` contract resolve inside the portal.
+
+## CSS class contract
+
+**Root class:** `dsx-tooltip` (on the content surface). The Radix root and trigger are unstyled; the content is the only element that owns DS classes.
+
+**Modifier classes** (driven by the `variant` prop):
+
+| Variant | Class | CSS file |
+|---|---|---|
+| `default` | `.dsx-tooltip` (root class) | `tooltip.css` |
+| `primary` | `.dsx-tooltip--primary` | `tooltip.css` |
+| `error` | `.dsx-tooltip--error` | `tooltip.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| Content | `dsx-tooltip` | `tooltip.css` |
+| Arrow | `dsx-tooltip__arrow` | `tooltip.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. Tooltip has no `responsive: true` prop defs; the content is positioned by the Radix floating primitives.
+
+**Reduced motion:**
+
+- Tooltip has no motion. The `MOTION_TRANSITIONS` preset `popover` is the closest analog, but the content uses CSS-only styling and does not consume a JS-side motion preset.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Max width | `var(--dsx-tooltip-max-width)` | Content max width |
+| Border radius | `var(--dsx-rounded-sm)` | Content corner roundness |
+| Padding (block) | `var(--dsx-space-xs)` | Vertical padding |
+| Padding (inline) | `var(--dsx-space-sm)` | Horizontal padding |
+| Background (default) | `var(--dsx-color-surface-overlay)` | Default content fill |
+| Background (primary) | `var(--dsx-color-primary)` | Primary content fill |
+| Background (error) | `var(--dsx-color-error)` | Error content fill |
+| Color (default) | `var(--dsx-color-on-surface)` | Default label color |
+| Color (primary) | `var(--dsx-color-on-primary)` | Primary label color |
+| Color (error) | `var(--dsx-color-on-error)` | Error label color |
+| Shadow | `var(--dsx-shadow-elevation-2)` | Content elevation |
+| Font family | `var(--dsx-typography-label-small-font-family)`, sans-serif | Label typeface |
+| Font size | `var(--dsx-typography-label-small-font-size)` | Label font size |
+| Font weight | `var(--dsx-typography-label-small-font-weight)` | Label font weight |
+| Line height | `var(--dsx-typography-label-small-line-height)` | Label line height |
+| Arrow fill | `currentColor` (CSS keyword) | Arrow picks up the content text color |
+
+Rules:
+
+- The arrow uses `currentColor` so it always matches the content's text color. This is the standard pattern for Radix tooltips; the CSS does not introduce a new token.
+- No raw color, spacing, radius, or motion values in the CSS file.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+Rules:
+
+- The content does not declare a transition. Radix's open and close animations are handled by the portal mounting lifecycle, not by a CSS transition. Apps that need an open/close animation should layer `framer-motion` on top of `TooltipContent` (out of scope for this spec).
+- A future motion addition should pick a `MOTION_TRANSITIONS` preset by name and gate it with `usePrefersReducedMotion`.
+
+## Accessibility
+
+**Roles:**
+
+- `role="tooltip"` on the content. The Radix primitive writes the role.
+- The trigger is whatever the consumer renders; the Radix primitive wires `aria-describedby` to the open content.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to or from the trigger. |
+| `Escape` | Closes the open tooltip. |
+| `Enter`, `Space` | Activates the trigger (e.g. clicking a button). |
+
+**Focus:**
+
+- The trigger receives focus on `Tab`. The content surfaces in response. Focus management is the Radix primitive's responsibility.
+
+**Reduced motion:**
+
+- N/A. Tooltip has no motion.
+
+**Color and meaning:**
+
+- The `error` variant is a visual signal, not a stand-in for text. Pair the variant with explicit text content; do not communicate error state by color alone.
+
+**Naming:**
+
+- The trigger must have an accessible name. For icon-only triggers, supply an `aria-label` and a matching tooltip body. Apps that want the tooltip to be the only accessible name should mirror the body into the trigger's `aria-label` (Radix does not promote the tooltip body to the trigger's accessible name).
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `TooltipProvider` wrapping a `Tooltip` with a `TooltipTrigger` (a `<Button>` via `asChild`) and a `TooltipContent` with body text. Asserts the content root class is `dsx-tooltip` after the trigger is hovered or focused.
+
+**Variant story:**
+
+- Renders one `TooltipContent` per `variant` value (`default`, `primary`, `error`). Asserts the matching `dsx-tooltip--<variant>` modifier class is on the content.
+
+**Composition story** (for `asChild`):
+
+- Renders `TooltipTrigger` with `asChild` wrapping a custom host element. Asserts the `asChild` swap happens and the tooltip opens on hover or focus.
+
+**State story:**
+
+- Renders the tooltip in the `closed` and `open` states. Asserts the content is absent from the DOM when closed, and present (with the role) when open. The open check is best driven by `defaultOpen` on the root.
+
+**Token story:**
+
+- Renders `TooltipContent` inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. Asserts the portal-mirrored `data-accent-color` attribute resolves to the active accent on the content root.
+
+**A11y story:**
+
+- Uses `vitest-axe` against a labelled trigger with an open tooltip. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `variant` | select | `default` |
+| `sideOffset` | number | `8` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-tooltip`: source of the root, provider, trigger, content, and arrow primitives, plus the `role="tooltip"` and `aria-describedby` wiring.
+- `@radix-ui/react-slot`: enables `asChild` on the trigger.
+- `_internal/BaseDialog` (`PortalThemeWrapper`): mirrors the active `data-dsx-*` theme attributes into the portal.
+- No DS component composition. Tooltip is a thin styled wrapper over Radix's tooltip anatomy.
+
+**Used by:**
+
+- App-level shortcut hints on toolbars, icon buttons, and command palettes.
+- `Sidebar` lists `Tooltip` as one of its composed slots; the sidebar uses tooltips to label collapsed rail items.
+
+**State boundaries:**
+
+- Owned by Tooltip: the open and closed state, the portal mirroring, the default delay duration (when the provider is the default), the default side offset, and the content visual.
+- Owned by the consumer: the trigger element, the body copy, the trigger's accessible name, and the placement of the provider in the tree.
+
+**Boundary rules:**
+
+- App-owned data: the body text, the trigger element, the trigger's accessible name, the placement of the `TooltipProvider` (at the app root for one shared delay, or scoped to a region for faster or slower responses), and any per-region delay overrides.
+- DS-owned visuals: the `dsx-tooltip` root class, the variant modifier class, the arrow class, the data-attribute contract via `PortalThemeWrapper`, and the token bindings.
+
+## 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 Tooltip. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Primitives / Tooltip`.
+- **Dimensions**: `auto × auto` (sized by content and `max-width`).
+- **Layout**: `Flex` (block-level).
+- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: Tooltip>
+  ├── <Trigger: host element (button or slotted child)>
+  └── <Portal: position-relative wrapper>
+        └── <Content: dsx-tooltip, dsx-tooltip--<variant>>
+              └── <Arrow: dsx-tooltip__arrow, currentColor fill>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Content | max width | `--dsx-tooltip-max-width` | Sizing | `max-width` |
+| Content | border radius | `--dsx-rounded-sm` | Radius | `border-radius` |
+| Content | padding (block) | `--dsx-space-xs` | Spacing | `padding-top` `padding-bottom` |
+| Content | padding (inline) | `--dsx-space-sm` | Spacing | `padding-left` `padding-right` |
+| Content (default) | background | `--dsx-color-surface-overlay` | Color | `fills` |
+| Content (default) | color | `--dsx-color-on-surface` | Color | `text-color` |
+| Content (primary) | background | `--dsx-color-primary` | Color | `fills` (state) |
+| Content (primary) | color | `--dsx-color-on-primary` | Color | `text-color` (state) |
+| Content (error) | background | `--dsx-color-error` | Color | `fills` (state) |
+| Content (error) | color | `--dsx-color-on-error` | Color | `text-color` (state) |
+| Content | shadow | `--dsx-shadow-elevation-2` | Shadow | `shadow` |
+| Content | font | `--dsx-typography-label-small-font-*` | Typography | `typography` |
+| Arrow | fill | `currentColor` | (CSS keyword) | `fills` |
+
+### State transformations
+
+| State | Content fill | Content color | Shadow |
+|---|---|---|---|
+| `default` | `--dsx-color-surface-overlay` | `--dsx-color-on-surface` | `--dsx-shadow-elevation-2` |
+| `primary` | `--dsx-color-primary` | `--dsx-color-on-primary` | `--dsx-shadow-elevation-2` |
+| `error` | `--dsx-color-error` | `--dsx-color-on-error` | `--dsx-shadow-elevation-2` |
+
+### Variant model
+
+- `variant`: `default`, `primary`, `error`. Default `default`.
+- `sideOffset`: number. Default `8`.
+- Total members: 3 variants in the matrix. `sideOffset` is a property on the content, not a member axis.
+
+### 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.
+- [ ] The arrow shape uses `currentColor` so it tracks the variant text color.