@d4gger/design-system 3.0.1 → 4.0.0

package/dist/docs/components/toggle-tip.md

@@ -12,21 +12,18 @@ depends_on:
 
 # ToggleTip
 
-> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
-
 ## Purpose
 
-A click-to-toggle tooltip variant for touch and keyboard parity. The trigger stays a button; the content opens on click and stays open until the user clicks the trigger again, the content loses focus, or the `Escape` key fires. Pairs with brief, non-essential explanatory copy.
+Click-operated, persistent help for touch and keyboard users. Keep essential
+instructions visible in the page. Click again, click outside or press Escape
+to dismiss. The component has internal open state and no controlled-open API.
 
 ## Anatomy & slots
 
-**Parent:** `ToggleTip` (no compound; flat export).
-
-**Slots:**
-
-No slots: flat export. The component renders a `<div>` (or `Slot` host) that wraps a `Popover.Root`. The Popover wires a `Popover.Trigger` (defaulting to the `Info` Icon) and a portal-mounted `Popover.Content` with a `Popover.Arrow`. The component does not expose named subcomponents; the trigger and content are internal Popover children.
-
-The runtime uses Radix Popover directly rather than the `Tooltip` primitive. The content is a click-toggled floating panel; the visual treatment borrows from the `dsx-tooltip` aesthetic at small size.
+A `dsx-toggle-tip` div (or Slot root) owns a Radix Popover inside
+`PortalThemeBoundary`. Its button is `dsx-toggle-tip__trigger`; its portal
+uses `PortalThemeWrapper` around `dsx-toggle-tip__content` and
+`dsx-toggle-tip__arrow`. There are no public compound parts.
 
 ## Props contract
 
@@ -35,11 +32,11 @@ The runtime uses Radix Popover directly rather than the `Tooltip` primitive. The
 | `content` | `React.ReactNode` | (none) | yes | The popover body. Rendered inside `Popover.Content`. | no |
 | `triggerLabel` | `string` | `'Show information'` | no | Accessible name for the trigger button. The trigger is icon-only by default; this prop supplies the `aria-label`. | no |
 | `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | no | Which side of the trigger the content appears on. Drives the `dsx-toggle-tip--side-{side}` modifier class on `Popover.Content` and the Radix `side` placement. | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Visual scale hint. Drives `data-size` on the root. The CSS does not currently consume `data-size`; see Anomalies. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Trigger and bubble scale. Writes `data-size`; sm/md/lg control boxes are 24/32/40px, with bubble padding 4×8 / 8×16 / 16×24px. Large content uses body-medium; smaller content uses body-small. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-toggle-tip`. | no |
 | `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the root. | no |
-| `children` | `React.ReactNode` | the `Info` Icon | no | Custom trigger content. When omitted, the trigger renders `<Info size={16} />` from `lucide-react`. | no |
+| `children` | `React.ReactNode` | the `Info` Icon | no | Custom trigger content. When omitted, the Info glyph is 12/16/20px for sm/md/lg. | no |
 | `id` | `string` | `undefined` | no | Forwarded to the root. | no |
 
 The component also accepts every `React.ComponentPropsWithoutRef<'div'>` key (omitting the conflicting `content` attribute) via `Omit<React.ComponentPropsWithoutRef<'div'>, 'content'>`.
@@ -53,254 +50,74 @@ Rules that apply to this row:
 
 ## CSS class contract
 
-**Root class:** `dsx-toggle-tip`
-
-**Modifier classes** (driven by `data-*` attributes and the `side` prop def):
-
-| Attribute / prop | Allowed values | Class | CSS file |
-|---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | (no CSS consumer; see Anomalies) | `toggle-tip.css` |
-| `side` | `top`, `right`, `bottom`, `left` | `.dsx-toggle-tip--side-{side}` on the `Popover.Content` element (the prop def's `className: 'dsx-toggle-tip--side-'` drives the prefix; the CSS does not currently define the modifier) | `toggle-tip.css` |
-
-**Slot classes:**
-
-| Slot | Class | CSS file |
+| Element | Class | Data slot |
 |---|---|---|
-| Root | `dsx-toggle-tip` | `toggle-tip.css` |
-| Trigger | `dsx-toggle-tip__trigger` | `toggle-tip.css` |
-| Content | `dsx-toggle-tip__content` | `toggle-tip.css` |
-| Arrow | `dsx-toggle-tip__arrow` | `toggle-tip.css` |
-
-**Data slots** (used by QA and audit tooling, not visual):
+| Root | `dsx-toggle-tip` | `toggle-tip` |
+| Trigger | `dsx-toggle-tip__trigger` | `toggle-tip-trigger` |
+| Content | `dsx-toggle-tip__content` | `toggle-tip-content` |
+| Arrow | `dsx-toggle-tip__arrow` | none |
 
-| Element | `data-slot` |
-|---|---|
-| Root | `toggle-tip` |
-| Trigger | `toggle-tip-trigger` |
-| Content | `toggle-tip-content` |
-
-**Responsive behavior:**
-
-- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size and side are single-value only.
-- The component's CSS file is breakpoint-agnostic.
-
-**Reduced motion:**
-
-- The component does not write a `prefers-reduced-motion` block. The content uses a `dsx-toggle-tip-fade` CSS keyframe animation for opacity + translate. The Popover applies the animation; when the global `prefers-reduced-motion` stylesheet is in place, the animation collapses via the standard CSS rule.
-- The trigger transitions `color` and `background` against `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-in-out)`. No explicit `prefers-reduced-motion` rule in the file.
+`data-size=sm/md/lg` is consumed on the root to size its trigger and on Content to size the bubble. Content
+retains `dsx-toggle-tip--side-{top,right,bottom,left}`; placement and collision
+flipping are owned by Radix, without side-specific CSS rules. All props are
+single values. There are no width media queries.
 
 ## Token mapping
 
-Every CSS value the component paints is a `var(--dsx-*)` token.
-
 | Property | Token | Role |
 |---|---|---|
-| Trigger size | `var(--dsx-size-sm)` square | Tap target. |
-| Trigger radius | `var(--dsx-rounded-full)` | Round affordance. |
-| Trigger fill | `transparent` | Resting surface. |
-| Trigger text | `var(--dsx-color-on-surface-variant)` | Resting glyph. |
-| Trigger hover fill | `var(--dsx-effect-hover-layer)` | Hover surface. |
-| Trigger hover text | `var(--dsx-color-primary)` | Hover glyph. |
-| Content padding | `var(--dsx-space-sm)` block, `var(--dsx-space-md)` inline | Inner gutter. |
-| Content radius | `var(--dsx-rounded-md)` | Panel corner radius. |
-| Content fill | `var(--dsx-color-panel-translucent)` | Panel surface. |
-| Content border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Panel edge. |
-| Content text | `var(--dsx-color-on-surface)` | Body text. |
-| Content typography | `var(--dsx-typography-body-small-*)` | Body type ramp. |
-| Content shadow | `var(--dsx-shadow-3)` | Panel elevation. |
-| Content max-width | `280px` (raw) | Readability cap; not a token target. |
-| Content entry animation | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-out)` | Fade-in. |
-| Content entry distance | `var(--dsx-space-xs)` | Translate offset. |
-| Arrow fill | `var(--dsx-color-panel-translucent)` | Match content surface. |
-| Trigger motion | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Hover transitions. |
-
-Rules:
-
-- Tokens come from `DESIGN.md` and the generated `tokens.css`. The only intentional non-token value is the `280px` content max-width, which is a readability cap rather than a sizing token.
-- The `side` modifier class is emitted by the runtime but the CSS does not currently define a `.dsx-toggle-tip--side-{side}` rule. Side-specific styling (offset, anchor alignment) is owned by Radix Popover.
+| Trigger sm/md/lg | `--dsx-size-md` / `--dsx-size-lg` / `--dsx-size-xl` | 24/32/40px control box |
+| Trigger radius | `--dsx-rounded-full` | Round affordance |
+| Trigger foreground | `--dsx-color-on-surface-variant` | Resting glyph |
+| Hover / open fill and glyph | `--dsx-color-accent-surface` / `--dsx-color-accent-indicator` | Readable accent feedback in all five accents |
+| Focus ring | `--dsx-shadow-focus-ring` | Keyboard focus |
+| Content fill / arrow | `--dsx-color-panel-translucent` | Matching surface |
+| Content border | `--dsx-border-width-sm`, `--dsx-panel-border-color` | Edge |
+| Content radius | `--dsx-rounded-md` | Surface geometry |
+| Content padding sm / md / lg | `--dsx-space-xs` × `--dsx-space-sm` / `--dsx-space-sm` × `--dsx-space-md` / `--dsx-space-md` × `--dsx-space-lg` | Bubble density |
+| Content shadow | `--dsx-shadow-elevation-3` | Overlay elevation |
+| Content width cap | `--dsx-size-popover-max-width` | Capped further by Radix available width |
+| Content layer | `--dsx-z-index-modal` + 1 | Help above a modal |
+
+Content uses border-box sizing and wraps long words. An inner body scrolls within Radix's available height after subtracting padding and borders. The arrow remains outside that scrolling body; it does not create a scrollbar for short help copy. Collision padding is 16px. The portal retains the originating
+Theme's mode, accent, density, radius and related attributes.
 
 ## Motion contract
 
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| Trigger color and background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Hover state swap | None declared in the file. Relies on the global `prefers-reduced-motion` stylesheet. |
-| Content entry | `dsx-toggle-tip-fade` keyframe, `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-out)` | Opacity `0 → 1` and `translateY(var(--dsx-space-xs)) → translateY(0)` | None declared in the file. Relies on the global `prefers-reduced-motion` stylesheet. |
-
-Rules:
-
-- This row does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts`. All motion is CSS-only.
-- A future promotion that uses framer-motion should pick a preset from `MOTION_TRANSITIONS` (likely `popover`) and gate it with `usePrefersReducedMotion`.
-- A future CSS-only promotion should add a `@media (prefers-reduced-motion: reduce)` block that sets `animation: none` on `.dsx-toggle-tip__content` and `transition: none` on `.dsx-toggle-tip__trigger`.
+CSS-only entry uses `dsx-toggle-tip-fade`, motion-duration-fast and
+motion-easing-out; the trigger uses the fast duration and in-out easing.
+The local `prefers-reduced-motion: reduce` rule disables the content animation
+and trigger transition. Pointer activation does not require hover.
 
 ## Accessibility
 
-**Roles:**
-
-- The root is a plain `<div>` with no implicit role.
-- The trigger is a Radix `Popover.Trigger`, which renders a `<button>` with `aria-label={triggerLabel}`. The default label is `'Show information'`. The content is a Radix `Popover.Content` with no implicit role; consumers can supply `aria-label` to name the panel.
-
-**Keyboard:**
-
-| Key | Action |
-|---|---|
-| `Tab` | Moves focus to the trigger (and to any focusable content inside the popover). |
-| `Enter`, `Space` | Toggles the popover open / closed. |
-| `Escape` | Radix Popover closes the content and returns focus to the trigger. |
-| Arrow keys | The component does not implement arrow-key navigation inside the content. |
-
-**Focus:**
-
-- The trigger gets the standard focus ring from the global stylesheet; the runtime does not write a custom focus style.
-- Radix Popover manages focus: opening moves focus to the first focusable element in the content (or keeps it on the trigger if none is focusable); closing returns focus to the trigger.
-
-**Reduced motion:**
-
-- The content entry animation is a CSS keyframe; the runtime does not gate it on `prefers-reduced-motion`. The global `prefers-reduced-motion` stylesheet is expected to collapse it; the component should add an explicit block in the next promotion.
-
-**Color and meaning:**
-
-- The trigger is an icon-only button; meaning is carried by the `aria-label` and the visible `Info` glyph. Color is not the only signal.
-
-**Naming:**
-
-- The trigger's accessible name comes from `triggerLabel`, defaulting to `'Show information'`. Consumers that pass a custom trigger through `children` are responsible for the accessible name on that trigger.
-- The popover content has no implicit name. Consumers that need a panel name should add `aria-label` via app-level wrapping.
+The trigger is a button named by `triggerLabel` (default “Show information”).
+The Popover content has role=dialog and the same accessible name. Its inner
+scrolling region has tabIndex=0 and an accessible name, so Radix focus entry
+allows Arrow/PageDown/End scrolling as well as wheel and touch gestures.
+Overscroll is contained within the help body. Enter/Space
+open it; Escape dismisses it and returns focus to the trigger. Radix owns
+focus entry and dismissal. The trigger has a local visible focus ring.
+The size floor is 24px; sm and md do not claim a 44px 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 `ToggleTip` with `content="Some explanatory text."`. Asserts the root class is `dsx-toggle-tip` and the trigger has `aria-label="Show information"`.
-
-**Variant story** (one per side and size):
-
-- Renders with `side="top"`, `side="right"`, `side="bottom"`, and `side="left"`. Asserts the `Popover.Content` carries the matching `dsx-toggle-tip--side-{side}` modifier (the CSS does not currently define the rule; see Anomalies).
-- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute on the root (the CSS does not currently consume it; see Anomalies).
-
-**Composition story** (for `asChild` and custom triggers):
-
-- Renders `ToggleTip` with `asChild` wrapping a custom host element. Asserts the host element receives the `dsx-toggle-tip` class.
-- Renders `ToggleTip` with a custom `children` (for example, a `HelpCircle` Icon). Asserts the custom trigger renders inside the Radix trigger button.
-
-**State story:**
-
-- Renders the default ToggleTip. Clicks the trigger and asserts the `Popover.Content` mounts with the entry animation.
-- Clicks the trigger again and asserts the content unmounts.
-- Opens the content and presses `Escape`; asserts the content unmounts and focus returns to the trigger.
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the trigger hover glyph tracks `--dsx-color-primary` (which is theme-aware).
-
-**A11y story:**
-
-- Uses `vitest-axe` against the rendered default ToggleTip. Asserts the trigger has an accessible name and the popover content region is announced as a dialog.
-
-**Props exposed in the playground controls:**
-
-| Prop | Control | Default |
-|---|---|---|
-| `content` | text | (empty) |
-| `triggerLabel` | text | `Show information` |
-| `side` | select | `top` |
-| `size` | select | `md` |
-| `asChild` | boolean | `false` |
+`/docs/toggle-tip` compares all three sizes and four requested sides. Its live
+example also places help in all five current nested accents (rift, warp, ray,
+astral, spark). Open these examples to review the portal's surface, accessible
+name, collision placement and focus return. Tests cover naming, theme ownership
+and Escape; browser evidence verifies target ownership and rendered geometry.
 
 ## Wiring notes
 
-**Composes from:**
-
-- `Popover` (Radix `@radix-ui/react-popover`): the trigger, portal, content, and arrow are Radix Popover primitives. The open/close behavior, focus management, and the `Escape` handling come from Radix.
-- `Tooltip` (visual treatment): the trigger and content share the `dsx-tooltip` aesthetic at small size. The TSX does not import the `Tooltip` component.
-- `Icon` (lucide-react `Info`): renders the default trigger glyph.
-- `@radix-ui/react-slot`: enables `asChild` on the root.
-
-**Used by:**
-
-- Form rows and inline help surfaces that need touch and keyboard parity. Pairs with `Field.Description` for sighted-only context, never for essential information. No DS component currently wraps `ToggleTip`.
-
-**State boundaries:**
-
-- Owned by ToggleTip: the open/close state, the default `Info` trigger, the `aria-label` fallback, the Radix Popover wiring, and the `side` / `size` attributes.
-- Owned by the consumer: the `content` body, the optional `triggerLabel`, the optional custom trigger, and the host element when `asChild` is set.
-
-**Boundary rules:**
-
-- App-owned data: the explanatory copy, the trigger label, and the placement of the ToggleTip in the page.
-- DS-owned visuals: token bindings, the `dsx-toggle-tip` and slot classes, the `dsx-toggle-tip--side-{side}` modifier class (reserved), the `data-size` attribute (reserved), the `data-slot` attributes, and the default `aria-label="Show information"`.
-- The component does not forward `data-dsx-*` theme attributes into the portal. Consumers that need the theme contract mirrored into the content region should wrap ToggleTip in a `BaseDialog`-style helper, or accept that the popover content is scoped to the root theme attributes only.
-
-**Anomalies** (open items that this spec flags):
-
-1. **`data-size` attribute has no CSS consumer.** The TSX writes `data-size` on the root and the prop def lists three values (`sm`, `md`, `lg`), but the CSS does not define any `[data-size]` rule. The attribute is a forward-looking hook; the visual treatment today is the same across all three sizes.
-2. **`dsx-toggle-tip--side-{side}` modifier class has no CSS consumer.** The runtime emits the modifier on the `Popover.Content`, but the CSS does not define the rule. Side placement is owned entirely by Radix Popover.
-3. **No `prefers-reduced-motion` block in `toggle-tip.css`.** The content entry animation and the trigger transitions are not explicitly collapsed on the media query. The next promotion should add a `@media (prefers-reduced-motion: reduce)` block.
-4. **Popover does not mirror the `data-dsx-*` theme contract.** The component uses `Popover.Root` / `Popover.Content` directly instead of going through the `BaseDialog` portal helper. The portal content does not receive `data-accent-color`, `data-dsx-density`, etc. The next promotion should route through `BaseDialog` (or an equivalent helper) so the popover content tracks the active theme.
-5. **Open state is internal.** The runtime does not expose `open` or `onOpenChange` props. Consumers that need to react to open state (for example, to dismiss a sibling popover) cannot subscribe.
-6. **`size` is written to the root, but the `side` modifier is written to the content.** The split mirrors the source and is consistent with the Radix Popover placement model, but it means the consumer cannot style a `size` variant on the content region from the parent theme alone.
+Radix Popover owns positioning and focus behavior. The package owns trigger
+size, glyph, styling, internal open state and theme mirroring; the consumer
+owns help copy, placement and trigger label. Custom children remain content
+inside the trigger button. `asChild` applies to the outer host only.
 
 ## 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 ToggleTip. Recipe is visual reference only and tracks the CSS contract.
-
-### Root board
-
-- **Name**: `Components / ToggleTip`.
-- **Dimensions**: `auto × auto` (the root is an inline-flex wrapper; the content panel is a separate popover board).
-- **Layout**: `Flex` (row) for the root; the popover content is its own board positioned relative to the trigger.
-- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
-
-### Layer tree
-
-```
-<Root Board: ToggleTip>
-  ├── <Button: trigger (Info icon)>
-  └── <Popover Content Board (portal-mounted)>
-      ├── <Frame: panel>
-      │   └── <Text: content>
-      └── <Shape: arrow>
-```
-
-### Token bindings (Penpot properties)
-
-| Shape | Property | Token | Token type | Penpot property name |
-|---|---|---|---|---|
-| Trigger | fill | `transparent` | Color | `fills` |
-| Trigger | text | `--dsx-color-on-surface-variant` | Color | `fills` |
-| Trigger (hover) | fill | `--dsx-effect-hover-layer` | Color | `fills` (state) |
-| Trigger (hover) | text | `--dsx-color-primary` | Color | `fills` (state) |
-| Panel | fill | `--dsx-color-panel-translucent` | Color | `fills` |
-| Panel | stroke | `--dsx-color-outline` | Color | `strokes` |
-| Panel | radius | `--dsx-rounded-md` | Radius | `radius` |
-| Panel | shadow | `--dsx-shadow-3` | Effect | `shadow` |
-| Panel | typography | `--dsx-typography-body-small-*` | Typography | `typography` |
-| Panel | text | `--dsx-color-on-surface` | Color | `fills` |
-| Arrow | fill | `--dsx-color-panel-translucent` | Color | `fills` |
-
-### State transformations
-
-| State | Trigger fill | Trigger text | Panel visibility |
-|---|---|---|---|
-| `default` | `transparent` | `--dsx-color-on-surface-variant` | hidden |
-| `hover` | `--dsx-effect-hover-layer` | `--dsx-color-primary` | hidden |
-| `open` | (per hover state) | (per hover state) | visible (with entry animation) |
-
-### Variant model
-
-- `side`: `top`, `right`, `bottom`, `left`. Default `top`. (CSS consumer pending; see Anomalies.)
-- `size`: `sm`, `md`, `lg`. Default `md`. (CSS consumer pending; see Anomalies.)
-- Total members for the visual matrix: 1 today; the size and side axes are reserved for a future promotion.
-
-### 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 trigger default label is `Show information`; do not treat the label as themable in Penpot.
-- [ ] The default trigger glyph is the `Info` Icon; do not treat the glyph as themable in Penpot.
-- [ ] When the `data-size` and `dsx-toggle-tip--side-{side}` CSS consumers land, re-run the spec QA and re-validate the Penpot recipe against the new CSS.
-- [ ] When the `BaseDialog` portal routing lands, re-run the spec QA and confirm the content region tracks `data-accent-color` and the rest of the theme contract.
+No published ToggleTip asset is changed by this package review. A future mirror
+must use the 24/32/40px trigger boxes, matching surface-colored arrow, active
+state and current token bindings above; side is a placement axis, not another
+surface treatment.

package/dist/docs/components/toolbar.md

@@ -29,9 +29,9 @@ A dense editor-style action strip with roving-focus arrow-key movement, used for
 | `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.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 rounded ends. |
 | `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. |
+| `Toolbar.Separator` | Radix `Toolbar.Separator` | `dsx-toolbar__separator` | Divider perpendicular to the root orientation. Uses `var(--dsx-control-separator-color)` and a non-shrinking 1px seam; its length follows control height minus `space-sm`. |
 
 **Internal layout:**
 
@@ -46,13 +46,13 @@ A dense editor-style action strip with roving-focus arrow-key movement, used for
 
 | 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 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Density scale: minimum button/link heights of 24/32/40px for sm/md/lg. Writes `data-size`. | no |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Inherited from Radix `Toolbar.Root`. Determines both visual layout and 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.
+The root accepts every prop supported by `@radix-ui/react-toolbar`'s `Root`. The `extractProps` call consumes and forwards `asChild` to Radix and `size` (consumed for `data-size`); the rest are forwarded.
 
 **Slot props:**
 
@@ -89,7 +89,7 @@ The root accepts every prop supported by `@radix-ui/react-toolbar`'s `Root`. The
 
 **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.
+- The component does not use width breakpoints. Responsive layout comes from the layout primitives' responsive classes when the consumer wraps the toolbar in a responsive shell.
 
 **Reduced motion:**
 
@@ -109,7 +109,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token. The base interac
 | 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 min-height | sm `var(--dsx-size-md)`, md `var(--dsx-size-lg)`, lg `var(--dsx-size-xl)` | 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 |
@@ -149,7 +149,7 @@ The component has no motion. Roving focus and pressed-state transitions are hand
 
 **Focus:**
 
-- Visible focus ring is provided by the base button styles (`src/_internal/baseButton.css`).
+- Visible focus ring is declared on the toolbar button/link/toggle slot classes using the canonical token.
 - The roving-focus ring skips disabled items.
 
 **Reduced motion:**
@@ -158,7 +158,7 @@ The component has no motion. Roving focus and pressed-state transitions are hand
 
 **Color and meaning:**
 
-- Pressed state is communicated by `aria-pressed` and a visual treatment from the base button. Color is not used alone.
+- Pressed state is communicated by `aria-pressed` and an accent-surface treatment on the toggle slot. Color is not used alone.
 - Disabled state is communicated by `disabled` attribute and reduced opacity from the base button.
 
 **Naming:**
@@ -166,38 +166,11 @@ The component has no motion. Roving focus and pressed-state transitions are hand
 - 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.
+The matrix exposes size and orientation. The live formatter has multiple text-style toggles and a single alignment group, separated by the toolbar seam. Its state changes actual sample text. A named vertical action example includes a disabled control.
 
-**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:**
+## Playground demo spec
 
-| Prop | Control | Default |
-|---|---|---|
-| `size` | select | `md` |
-| `orientation` | select | `horizontal` |
+The matrix exposes sm/md/lg and horizontal/vertical orientation. A working formatter uses multiple bold/italic/strikethrough toggles with supported icons, a separator, and single L/C/R alignment with full accessible names. State changes the sample text. A separate vertical action strip includes a disabled control. Seams are perpendicular, non-shrinking and density-aware.
 
 ## Wiring notes
 
@@ -225,3 +198,7 @@ The component has no motion. Roving focus and pressed-state transitions are hand
 ## 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.
+
+Toolbar controls wrap intrinsically within the available container. Vertical orientation stacks controls; explicitly vertical ToggleGroups stack their children with the corresponding joined end radii. Disabled controls use the opacity-disabled token; hover, pressed, selected and focus treatments are declared on toolbar slots. Horizontal separators paint a 1px line when the toolbar is vertical.
+
+Root, Button, ToggleButton, Link, and Separator forward their advertised asChild prop to Radix so consumer hosts retain slot classes and behavior.

package/dist/docs/components/tooltip.md

@@ -112,7 +112,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Property | Token | Role |
 |---|---|---|
-| Max width | `var(--dsx-tooltip-max-width)` | Content max width |
+| Max width | `min(var(--dsx-tooltip-max-width), var(--radix-tooltip-content-available-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 |
@@ -127,11 +127,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | 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 |
+| Arrow fill | `--_tooltip-background` | Arrow matches its surface |
 
 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.
+- The arrow uses the same local background variable as its surface. Default/primary/error resolve to panel-translucent/primary/error. No new public token is introduced.
 - No raw color, spacing, radius, or motion values in the CSS file.
 
 ## Motion contract
@@ -196,7 +196,7 @@ Rules:
 
 **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.
+- Renders `TooltipContent` inside a `Theme` wrapper with `accentColor="astral"` and one with `accentColor="spark"`. Asserts the portal-mirrored `data-accent-color` attribute resolves to the active accent on the content root.
 
 **A11y story:**
 
@@ -253,7 +253,7 @@ The package does not yet publish a Penpot asset for Tooltip. Recipe is visual re
   ├── <Trigger: host element (button or slotted child)>
   └── <Portal: position-relative wrapper>
         └── <Content: dsx-tooltip, dsx-tooltip--<variant>>
-              └── <Arrow: dsx-tooltip__arrow, currentColor fill>
+              └── <Arrow: dsx-tooltip__arrow, surface-colored fill>
 ```
 
 ### Token bindings (Penpot properties)
@@ -272,7 +272,7 @@ The package does not yet publish a Penpot asset for Tooltip. Recipe is visual re
 | 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` |
+| Arrow | fill | Same background token as current variant | Color | `fills` |
 
 ### State transformations
 
@@ -293,4 +293,10 @@ The package does not yet publish a Penpot asset for Tooltip. Recipe is visual re
 - [ ] 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.
+- [ ] The arrow shape matches the variant background.
+
+## Overlay review constraints
+
+The tooltip uses border-box sizing, wraps long words and caps to Radix available
+width. Its layer is modal + 1. `/docs/tooltip` keeps Save usable with or without
+its shortcut hint, and compares three variants and all requested sides.