@d4gger/design-system 2.7.0

package/dist/docs/floating-panel.md

@@ -0,0 +1,384 @@
+---
+title: FloatingPanel
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/floatingPanel/FloatingPanel.tsx
+css_path: packages/d4gger-design-system/src/styles/components/floating-panel.css
+props_path: packages/d4gger-design-system/src/components/floatingPanel/floatingPanel.props.ts
+test_path: packages/d4gger-design-system/src/test/components/FloatingPanel.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on:
+  - Popover (Radix `@radix-ui/react-popover`; the roster lists `Popover, Dialog` as the composed-from engines; the current runtime does not use either, see Anomalies)
+  - Dialog (Radix `@radix-ui/react-dialog`; not currently used by the runtime, see Anomalies)
+  - Icon (lucide-react `X`; the default close-button glyph)
+  - "@radix-ui/react-slot" (enables `asChild` on Root, Header, Content, and Handle)
+---
+
+# FloatingPanel
+
+> 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 generic floating content surface with drag, resize, and persistent placement. The panel is a `position: fixed` element whose top-left position, width, and height are local state; the header acts as the drag handle, a built-in close button unmounts the panel, and an inline resize handle in the southeast corner (or south / east) adjusts the size.
+
+## Anatomy & slots
+
+**Parent:** `FloatingPanel` (alias of `FloatingPanelRoot`, which is exported as `FloatingPanel`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `FloatingPanel.Root` (alias `FloatingPanel`) | `<div>` (or `Slot` host) | `dsx-floating-panel` | The shell. Owns position, size, drag, and resize state. Hard-codes `position: fixed`. |
+| `FloatingPanel.Header` | `<div>` (or `Slot` host) | `dsx-floating-panel__header` | The drag handle. Carries `data-floating-panel-handle` so the root's drag handler can ignore mouse-downs on it. |
+| `FloatingPanel.Content` | `<div>` (or `Slot` host) | `dsx-floating-panel__content` | The scrollable body region. Flexes to fill the remaining height. |
+| `FloatingPanel.Handle` | `<div>` (or `Slot` host) | `dsx-floating-panel__handle`, `dsx-floating-panel__handle--{direction}` | The resize handle. The root auto-mounts an `se`-direction handle unless `asChild` is set. |
+| (close button, internal) | `<button>` | `dsx-floating-panel__close` | Auto-rendered by the root. Clicking it calls `onClose` and unmounts the panel. |
+
+The `Handle` is internal in practice. The root renders one with `direction="se"` automatically; consumers that pass `asChild` on the root take responsibility for the close button and the resize handle.
+
+## Props contract
+
+### `FloatingPanel.Root` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `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 |
+| `defaultPosition` | `{ x: number; y: number }` | `{ x: 0; y: 0 }` | no | Initial top-left position in viewport pixels. | no |
+| `defaultSize` | `{ width: number; height: number }` | `{ width: 320; height: 240 }` | no | Initial size in viewport pixels. | no |
+| `onDragEnd` | `(position: { x: number; y: number }) => void` | `undefined` | no | Called once when the user releases the mouse after a drag. Receives the final position. | no |
+| `onResize` | `(size: { width: number; height: number }) => void` | `undefined` | no | Called once when the user releases the mouse after a resize. Receives the final size. | no |
+| `onClose` | `() => void` | `undefined` | no | Called when the user closes the panel via the close button or the `Escape` key. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. When set, the root no longer auto-mounts the close button or the resize handle. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Header, Content, and (when `asChild` is set) Handle nodes. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-floating-panel`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the root. The root always writes its own `position`, `left`, `top`, `width`, and `height`; consumer styles merge with the root's. | no |
+
+The Root also accepts every `React.HTMLAttributes<HTMLDivElement>` key (omitting the conflicting `onDragEnd` attribute) via `Omit<React.HTMLAttributes<HTMLDivElement>, 'onDragEnd'>`.
+
+### `FloatingPanel.Header` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the header through `Slot`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-floating-panel__header`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the header. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Header content. | no |
+
+The Header also accepts every `React.HTMLAttributes<HTMLDivElement>` key.
+
+### `FloatingPanel.Content` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the content through `Slot`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-floating-panel__content`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the content. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Body content. | no |
+
+The Content also accepts every `React.HTMLAttributes<HTMLDivElement>` key.
+
+### `FloatingPanel.Handle` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `direction` | `'se' \| 's' \| 'e'` | `'se'` | no | Resize direction. Drives the `dsx-floating-panel__handle--{direction}` modifier class and the cursor style. The Handle is auto-rendered with `direction="se"` when the root is not in `asChild` mode; the `direction` prop is otherwise a public hook. | no |
+| `asChild` | `boolean` | `false` | no | Renders the handle through `Slot`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-floating-panel__handle`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the handle. | no |
+
+The Handle also accepts every `React.HTMLAttributes<HTMLDivElement>` key. The internal `onResize` wiring between the root and the handle is not part of the public `Handle` API; the root supplies the wiring only when it auto-mounts the handle.
+
+Rules that apply to this row:
+
+- The Root is `position: fixed` and overrides any consumer-supplied `position`, `left`, `top`, `width`, and `height` style. The consumer `style` prop is spread into the inline style but the root's own keys win.
+- Open state is internal. The component returns `null` after `onClose` (or after the user clicks the close button or presses `Escape`). There is no `open` / `onOpenChange` prop; once closed, the consumer must remount the component to reopen it.
+- The Header is the drag handle. The root's drag handler ignores mouse-downs on the header only when the consumer provides a `Header` slot. Without a `Header`, every mouse-down starts a drag.
+- `asChild` is the only polymorphic infra. It is exposed on Root, Header, Content, and Handle.
+- The min width for resize is `150` and the min height is `100`. These are raw values in JS, not tokens; see Anomalies.
+
+## CSS class contract
+
+**Root class:** `dsx-floating-panel`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | (no CSS consumer; see Anomalies) | `floating-panel.css` |
+| `data-dragging` | (presence) | `.dsx-floating-panel[data-dragging]` (shadow upgrade + grabbing cursor) | `floating-panel.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `FloatingPanel.Root` | `dsx-floating-panel` | `floating-panel.css` |
+| `FloatingPanel.Header` | `dsx-floating-panel__header` | `floating-panel.css` |
+| `FloatingPanel.Content` | `dsx-floating-panel__content` | `floating-panel.css` |
+| `FloatingPanel.Handle` | `dsx-floating-panel__handle`, `dsx-floating-panel__handle--{direction}` | `floating-panel.css` |
+| (close button, internal) | `dsx-floating-panel__close` | `floating-panel.css` |
+
+**Data attributes from the runtime:**
+
+| Element | Attribute | Allowed values | Class hook | CSS file |
+|---|---|---|---|---|
+| Root | `data-dragging` | (presence) | `.dsx-floating-panel[data-dragging]` | `floating-panel.css` |
+| Header | `data-floating-panel-handle` | (presence) | (not styled; the root's drag handler reads the attribute to ignore mouse-downs) | `floating-panel.css` |
+
+**Data slots** (used by QA and audit tooling, not visual):
+
+| Element | `data-slot` |
+|---|---|
+| Close button | `floating-panel-close` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size is single-value only.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- The shell, close button, and handle each transition properties (box-shadow, color, background, opacity) against `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. The runtime does not import `usePrefersReducedMotion`; rely on the global `prefers-reduced-motion` stylesheet.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Shell radius | `var(--dsx-rounded-xl)` | Panel corner radius. |
+| Shell border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Panel edge. |
+| Shell fill | `var(--dsx-color-surface-overlay)` | Panel surface. |
+| Shell shadow (rest) | `var(--dsx-shadow-md)` | Resting elevation. |
+| Shell shadow (dragging) | `var(--dsx-shadow-xl)` | Active elevation. |
+| Shell overflow | `hidden` (raw) | Contain children. |
+| Shell z-index | `var(--dsx-z-index-overlay-local)` | Above page content. |
+| Header padding | `var(--dsx-space-sm)` block, `var(--dsx-space-md)` inline | Inner gutter. |
+| Header gap | `var(--dsx-space-sm)` | Gap between children. |
+| Header border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline-variant)` | Header divider. |
+| Header fill | `var(--dsx-color-surface-raised)` | Header surface. |
+| Header cursor | `grab` (raw) | Drag affordance. |
+| Header user-select | `none` (raw) | Prevent text selection while dragging. |
+| Header active cursor | `grabbing` (raw) | Dragging state. |
+| Close button size | `var(--dsx-size-md)` square | Tap target. |
+| Close button radius | `var(--dsx-rounded-sm)` | Round affordance. |
+| Close button position | `var(--dsx-space-xs)` from top-right | Edge anchor. |
+| Close button text | `var(--dsx-color-on-surface-variant)` | Resting glyph. |
+| Close button hover fill | `var(--dsx-effect-hover-layer)` | Hover surface. |
+| Close button hover text | `var(--dsx-color-on-surface)` | Hover glyph. |
+| Close button z-index | `var(--dsx-z-index-elevated)` | Above panel content. |
+| Content padding | `var(--dsx-space-md)` | Inner gutter. |
+| Content overflow | `auto` (raw) | Scrollable body. |
+| Handle size (se) | `var(--dsx-space-lg)` square | Resize target. |
+| Handle size (s) | `var(--dsx-space-xl)` wide, `var(--dsx-space-sm)` tall | South edge handle. |
+| Handle size (e) | `var(--dsx-space-sm)` wide, `var(--dsx-space-xl)` tall | East edge handle. |
+| Handle cursor (se) | `nwse-resize` (raw) | Resize affordance. |
+| Handle cursor (s) | `ns-resize` (raw) | Resize affordance. |
+| Handle cursor (e) | `ew-resize` (raw) | Resize affordance. |
+| Handle grip color | `var(--dsx-color-on-surface-variant)` | Grip stroke. |
+| Handle grip opacity | `var(--dsx-opacity-muted)` | Resting fade. |
+| Handle grip border width | `var(--dsx-border-width-md)` | Grip thickness. |
+| Handle z-index | `var(--dsx-z-index-elevated)` | Above panel content. |
+| Motion | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` / `--dsx-motion-easing-in-out` | Shell, close, and handle transitions. |
+
+Rules:
+
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The intentional non-token values are the cursor keywords (`grab`, `grabbing`, `nwse-resize`, `ns-resize`, `ew-resize`), the `none` user-select, the `hidden` and `auto` overflow values, and the resize min dimensions in JS (`150` × `100`).
+- The CSS file imports `../../_internal/baseCard.css`. The import only matches `.dsx-card` and `.dsx-alert` selectors, so the import is a no-op for `FloatingPanel`. See Anomalies.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Shell box-shadow | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Resting → dragging shadow upgrade | None declared in the file. Relies on the global `prefers-reduced-motion` stylesheet. |
+| Close button 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 stylesheet. |
+| Handle grip opacity | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Opacity lift on hover | None declared in the file. Relies on the global stylesheet. |
+
+Rules:
+
+- This row does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts`. All motion is CSS-only.
+- Drag and resize are JS-driven; the drag itself does not animate (the position update is synchronous). The shadow upgrade is the only visual cue during drag.
+- A future promotion that adds framer-motion should pick a preset from `MOTION_TRANSITIONS` and gate it with `usePrefersReducedMotion`. A future CSS-only promotion should add a `@media (prefers-reduced-motion: reduce)` block that sets `transition: none` on the shell, close button, and handle.
+
+## Accessibility
+
+**Roles:**
+
+- The root is a plain `<div>` with no implicit role. Consumers that need a dialog role should add `role="dialog"` and `aria-modal` at the app level (the roster lists this as a "heavy surface" that may need full dialog semantics).
+- The close button is a `<button type="button">` with `aria-label="Close panel"`. The runtime hard-codes the label.
+- The handle is a plain `<div>` with no role. Mouse-only interaction; see Keyboard.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to / from any focusable element inside the panel, and to the close button. |
+| `Escape` | Closes the panel and calls `onClose`. The runtime installs a `document` keydown listener while the panel is open. |
+| `Enter`, `Space` | Activates the focused control (close button, content buttons, etc.). |
+| Arrow keys | The component does not implement keyboard-driven drag or resize. Mouse only. |
+
+**Focus:**
+
+- The runtime does not trap focus inside the panel. Focus management is the consumer's responsibility; for full dialog behavior, wrap in a Radix Dialog or set up focus trapping at the app level.
+- The runtime does not auto-focus the panel on mount. The close button is in the tab order; consumers that want the close button to be the focus target on mount can add `autoFocus` via app-level wrapping.
+
+**Reduced motion:**
+
+- The CSS transitions rely on the global `prefers-reduced-motion` stylesheet. The drag and resize math is synchronous and is not affected by the media query.
+
+**Color and meaning:**
+
+- The drag and resize affordances are communicated by the cursor keyword (`grab` / `grabbing` / `nwse-resize`). Color is not the only signal.
+
+**Naming:**
+
+- The close button is auto-labeled `Close panel`. The runtime hard-codes the label.
+- The panel has no implicit name. Consumers that need a panel name should add `aria-label` or `aria-labelledby` at the app level.
+- The handle is decorative and has no accessible name.
+
+## 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 `FloatingPanel` with a `Header`, a `Content`, and the auto-mounted close + resize handle. Asserts the root class is `dsx-floating-panel` and the close button carries `aria-label="Close panel"`.
+
+**Variant story** (one per size and direction):
+
+- 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).
+- Renders a custom `Handle` with `direction="se"`, `direction="s"`, and `direction="e"`. Asserts the matching `dsx-floating-panel__handle--{direction}` modifier class and the cursor style.
+
+**Composition story** (one per slot):
+
+- Renders the full slot hierarchy: `FloatingPanel` > `Header` > `Content`, with the auto-mounted `Handle`. Asserts each slot renders the right class.
+- Renders `FloatingPanel` with `asChild`. Asserts the close button and the resize handle are no longer auto-mounted.
+
+**State story:**
+
+- Renders the default panel. Mouse-downs on the header, drags, and mouse-ups. Asserts the panel's `left` and `top` inline styles match the final position and that `onDragEnd` was called.
+- Mouse-downs on the resize handle, drags, and mouse-ups. Asserts the panel's `width` and `height` inline styles match the final size and that `onResize` was called.
+- Clicks the close button. Asserts the panel unmounts and `onClose` was called.
+- Opens the panel and presses `Escape`. Asserts the panel unmounts and `onClose` was called.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the panel surface and shadow track the active theme.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default FloatingPanel. Asserts the close button has an accessible name and the panel does not introduce violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `defaultPosition` | text (JSON) | `{ x: 0, y: 0 }` |
+| `defaultSize` | text (JSON) | `{ width: 320, height: 240 }` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Popover` and `Dialog` (declared composed-from engines per the roster; the current runtime does not import either). The current runtime manages open state, position, size, drag, and resize in source. See Anomalies.
+- `Icon` (lucide-react `X`): renders the default close-button glyph.
+- `@radix-ui/react-slot`: enables `asChild` on Root, Header, Content, and Handle.
+
+**Used by:**
+
+- App-level floating surfaces that need persistent placement and resizing: dashboards, design tools, chart inspectors. No DS component currently wraps `FloatingPanel`. The roster classifies this as a heavy surface; the package owns the shell, the token bindings, and the drag / resize plumbing; apps own persistence, the panel registry, and the focus-trap / dialog semantics.
+
+**State boundaries:**
+
+- Owned by FloatingPanel: the open state, the position, the size, the drag delta, the resize delta, the `Escape` keydown listener, the auto-mounted close button, and the auto-mounted resize handle.
+- Owned by the consumer: the Header content, the Content body, the optional custom Handle, the `defaultPosition` and `defaultSize` inputs, the `onDragEnd` / `onResize` / `onClose` callbacks, and the focus / dialog semantics.
+
+**Boundary rules:**
+
+- App-owned data: the panel registry, the persistence of position and size across sessions, the routing integration, and the focus management.
+- DS-owned visuals: token bindings, the `dsx-floating-panel` and slot classes, the `data-size` and `data-dragging` attributes, the close button label, and the resize handle directions.
+- The component does not own a `Dialog` integration. Wrap in a Radix `Dialog` (or set up focus trapping) at the app level for full modal semantics.
+
+**Anomalies** (open items that this spec flags):
+
+1. **Roster says `Popover, Dialog`; runtime uses neither.** The current runtime at `package_path` does not import Radix Popover or Radix Dialog. Open state, focus, and `Escape` are managed in source via `useState` and a `document.addEventListener('keydown')` listener. Promoting to a `BaseDialog`-backed runtime is tracked as a future item.
+2. **`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.
+3. **`baseCard.css` import is a no-op.** The CSS file imports `../../_internal/baseCard.css`, which only targets `.dsx-card` and `.dsx-alert`. The import should be removed or `baseCard.css` should be extended to also match `.dsx-floating-panel`.
+4. **Resize min dimensions are raw JS values.** The resize handler clamps the size to `width >= 150` and `height >= 100`. These are not tokens; the next promotion should add `--dsx-floating-panel-min-width` and `--dsx-floating-panel-min-height` (or fold the constraints into the existing size scale).
+5. **Open state is internal and one-shot.** The runtime does not expose `open` or `onOpenChange` props. The component returns `null` after `onClose`; the consumer must remount to reopen. A future promotion should lift the open state.
+6. **Drag math ignores the resize handle and the close button.** The root's `onMouseDown` starts a drag unless the target is the closest `[data-floating-panel-handle]`. The close button does not have `data-floating-panel-handle`, but the drag handler can still fire on a click that lands inside it because the mouse-up handler is bound to `document`. A future promotion should also bail out of drag on `[data-floating-panel-close]`.
+7. **No `prefers-reduced-motion` block in `floating-panel.css`.** The shell, close button, and handle transitions are not explicitly collapsed on the media query. The next promotion should add a `@media (prefers-reduced-motion: reduce)` block.
+8. **The auto-mounted `Handle` always uses `direction="se"`.** Consumers that need south or east edge handles must render the `Handle` themselves and set `asChild` on the root, which also removes the close button. There is no public API to keep the close button while changing the handle direction.
+
+## 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 FloatingPanel. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / FloatingPanel`.
+- **Dimensions**: `320 × 240` (default), `width × height` driven by `defaultSize`.
+- **Layout**: `Flex` (column, header above content).
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'fix'`. Position is `fixed` with `left` / `top` driven by `defaultPosition`.
+
+### Layer tree
+
+```
+<Root Board: FloatingPanel>
+  ├── <Frame: header (drag handle)>
+  │   └── <Text: title>
+  ├── <Frame: content (scrollable)>
+  │   └── <Text: body>
+  ├── <Button: close (X icon, top-right)>
+  └── <Shape: resize handle (southeast corner)>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Shell | fill | `--dsx-color-surface-overlay` | Color | `fills` |
+| Shell | stroke | `--dsx-color-outline` | Color | `strokes` |
+| Shell | radius | `--dsx-rounded-xl` | Radius | `radius` |
+| Shell | shadow | `--dsx-shadow-md` | Effect | `shadow` |
+| Shell (dragging) | shadow | `--dsx-shadow-xl` | Effect | `shadow` (state) |
+| Header | fill | `--dsx-color-surface-raised` | Color | `fills` |
+| Header | stroke | `--dsx-color-outline-variant` | Color | `strokes` |
+| Content | padding | `--dsx-space-md` | Spacing | `padding` |
+| Close | fill | `transparent` | Color | `fills` |
+| Close (hover) | fill | `--dsx-effect-hover-layer` | Color | `fills` (state) |
+| Close (hover) | text | `--dsx-color-on-surface` | Color | `fills` (state) |
+| Handle | stroke | `--dsx-color-on-surface-variant` | Color | `strokes` |
+| Handle | opacity | `--dsx-opacity-muted` | Effect | `opacity` |
+
+### State transformations
+
+| State | Shell shadow | Header cursor | Close fill | Handle opacity |
+|---|---|---|---|---|
+| `default` | `--dsx-shadow-md` | `grab` | `transparent` | `--dsx-opacity-muted` |
+| `dragging` | `--dsx-shadow-xl` | `grabbing` | `transparent` | `1` |
+| `close-hover` | `--dsx-shadow-md` | `grab` | `--dsx-effect-hover-layer` | `--dsx-opacity-muted` |
+| `handle-hover` | `--dsx-shadow-md` | `grab` | `transparent` | `1` |
+
+### Variant model
+
+- `size`: `sm`, `md`, `lg`. Default `md`. (CSS consumer pending; see Anomalies.)
+- `direction` (handle): `se`, `s`, `e`. Default `se`.
+- Total members for the visual matrix: 3 × 3 = 9 once the `data-size` CSS consumer lands. Today the visual matrix is 3 (handle direction only).
+
+### 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 close button label is `Close panel`; do not treat the label as themable in Penpot.
+- [ ] The close button glyph is the `X` Icon; do not treat the glyph as themable in Penpot.
+- [ ] When the `data-size` CSS consumer lands, 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 panel tracks `data-accent-color` and the rest of the theme contract.
+- [ ] When the resize min dimensions are tokenized, update the JS clamp to read from the token instead of the hard-coded `150` and `100`.

package/dist/docs/font-provider.md

@@ -0,0 +1,170 @@
+---
+title: FontProvider
+status: canonical
+category: Foundations
+archetype: utility
+package_path: packages/d4gger-design-system/src/components/fontProvider/FontProvider.tsx
+props_path: packages/d4gger-design-system/src/components/fontProvider/fontProvider.props.ts
+test_path: packages/d4gger-design-system/src/test/components/FontProvider.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/utility.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on: []
+---
+
+# FontProvider
+
+> 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 root-level font loader that writes the `--dsx-font-family` CSS custom property on `document.documentElement` from the `fontFamily` prop and exposes a `useFont` hook that returns the active font family for downstream typography components.
+
+## Anatomy & slots
+
+**Parent:** `FontProvider` (no compound; flat provider export).
+
+**Slots:**
+
+No slots: flat export. The component renders no wrapper element. It provides a `FontContext` and runs a document side effect that writes or removes `--dsx-font-family` on `html`.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `fontFamily` | `string` | `'var(--dsx-typography-body-medium-font-family, sans-serif)'` | no | Font family value written to the `--dsx-font-family` CSS custom property on `html`. Accepts any CSS font-family expression, including a token reference. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Subtree that reads the active font family through `useFont`. | no |
+
+Rules that apply to this row:
+
+- `FontProvider` is a behavioral provider. It does not run through `extractProps` and does not expose a class contract.
+- The provider snapshots the prior `--dsx-font-family` value on mount, applies the requested value through `style.setProperty`, and restores the prior snapshot on unmount.
+- The `useFont` hook returns the context value when called inside the provider, or the default `var(--dsx-typography-body-medium-font-family, sans-serif)` when called outside. It does not throw.
+
+## CSS class contract
+
+**Root class:** none. The provider renders no host element.
+
+**Modifier classes:** none. The provider only writes the `--dsx-font-family` CSS custom property on `document.documentElement`.
+
+**Slot classes:** none.
+
+**Responsive behavior:**
+
+- The provider does not write `@media` rules. Font family is a document-level setting, not a per-breakpoint value.
+
+**Reduced motion:**
+
+- N/A. The provider has no motion.
+
+## Token mapping
+
+The provider writes the `--dsx-font-family` custom property. The default value is a token reference (`var(--dsx-typography-body-medium-font-family, sans-serif)`) so the package's typography ramp still applies.
+
+| Document property | Token | Role |
+|---|---|---|
+| `--dsx-font-family` | `var(--dsx-typography-body-medium-font-family, sans-serif)` (default) | Active document font family. |
+
+Rules:
+
+- The provider does not introduce a new token. `--dsx-font-family` is a CSS variable the package reads from; the provider is the canonical writer.
+- Consumers that need a custom font ship a `<link rel="preload" as="font">` (or equivalent) at the app entry and pass the family name to `FontProvider`.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+Rules:
+
+- FontProvider has no motion. The motion section is intentionally empty.
+
+## Accessibility
+
+**Roles:**
+
+- The provider renders no host element. It contributes no role.
+
+**Keyboard:**
+
+- The provider has no keyboard contract.
+
+**Focus:**
+
+- The provider has no focusable surface.
+
+**Reduced motion:**
+
+- N/A. The provider has no motion.
+
+**Color and meaning:**
+
+- The font family is a visual choice. The provider does not communicate semantic state.
+
+**Naming:**
+
+- The provider is structural. Accessible names of descendant controls come from the controls themselves.
+
+## Playground demo spec
+
+`FontProvider` is registered in `apps/playground/lib/registry/utility.tsx` under the `font-provider` key. The registry entry's `render` function returns a description block because mounting the provider inside a single demo would shift the font of the entire page. Per-component route: `/docs/font-provider`.
+
+**Default story:**
+
+- The registry render returns a description of the root-level provider. The provider's effect is exercised by the package's typography tokens and by the `dsx-typography-body-medium-font-family` default.
+
+**Variant story:**
+
+- N/A. The provider is a root-level wrapper. Custom font permutations are exercised by apps that mount a real provider at the app root.
+
+**Composition story:**
+
+- The provider composes around the entire app. `useFont` is consumed by `Text`, `Heading`, and other typography primitives that need to read the active family.
+
+**State story:**
+
+- The provider's only state is the `fontFamily` value. The default is the body-medium token reference.
+
+**Token story:**
+
+- The default `fontFamily` is a token reference, so the playground renders all typography with the body-medium ramp by default.
+
+**A11y story:**
+
+- N/A. The provider has no accessible surface of its own.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| (not exposed) | n/a | n/a |
+
+The playground does not expose `FontProvider` controls because the provider mutates `document.documentElement` and a second mount would conflict with the playground's root provider.
+
+## Wiring notes
+
+**Composes from:**
+
+- React `createContext`, `useContext`, `useEffect`, and `useMemo`.
+- The native `document.documentElement.style.setProperty` / `removeProperty` API.
+- No Radix primitive. No portal.
+
+**Used by:**
+
+- The Playground root does not currently mount `FontProvider`; the body-medium token reference is the default.
+- App roots that need a custom font (Fraunces, Manrope, Inter, or any other webfont) wrap the app in `FontProvider fontFamily="Inter, sans-serif"` after preloading the font.
+
+**State boundaries:**
+
+- Owned by FontProvider: the `--dsx-font-family` custom property on `document.documentElement` and the `FontContext` value.
+- Owned by the consumer: the `fontFamily` prop, the font preload, and the `useFont` consumer's response to the value.
+
+**Boundary rules:**
+
+- App-owned data: the chosen font family and the preload strategy.
+- DS-owned visuals: the document-level custom property and the `FontContext` value.
+
+## Penpot build recipe
+
+> Penpot is a visual reference, not a code authority. Skip this section when the component is utility. FontProvider has no visual surface, so this section is intentionally omitted.