@d4gger/design-system 2.7.0 → 3.0.0

package/dist/docs/{date-picker.md → components/date-picker.md}

@@ -3,13 +3,6 @@ title: DatePicker
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/datePicker/DatePicker.tsx
-css_path: packages/d4gger-design-system/src/styles/components/datepicker.css
-props_path: packages/d4gger-design-system/src/components/datePicker/datePicker.props.ts
-test_path: packages/d4gger-design-system/src/test/components/DatePicker.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Calendar
   - Popover
@@ -20,7 +13,7 @@ depends_on:
 
 # DatePicker
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{dialog.md → components/dialog.md}

@@ -3,19 +3,12 @@ title: Dialog
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/dialog/Dialog.tsx
-css_path: packages/d4gger-design-system/src/styles/components/dialog.css
-props_path: packages/d4gger-design-system/src/components/dialog/dialog.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Dialog.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: []
 ---
 
 # Dialog
 
-> Source of truth: the package source at `package_path`. The spec mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -351,7 +344,7 @@ Rules:
 
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
-| `<Content frame>` | fill | `var(--dsx-color-surface-overlay)` | Color | `fills` |
+| `<Content frame>` | fill | `var(--dsx-color-panel-translucent)` | Color | `fills` |
 | `<Content frame>` | radius | `var(--dsx-rounded-xl)` | Radius | `borderRadius` |
 | `<Content frame>` | spacing | `var(--dsx-space-lg)` | Spacing | `padding` |
 | `<Title text>` | typography | `var(--dsx-typography-headline-medium-*)` | Typography | `typography` |
@@ -364,7 +357,7 @@ Rules:
 
 | State | Content fill | Content shadow |
 |---|---|---|
-| `default` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-3)` |
+| `default` | `var(--dsx-color-panel-translucent)` | `var(--dsx-shadow-elevation-3)` |
 | `focus-visible (action)` | `var(--dsx-color-primary)` | `var(--dsx-shadow-focus-ring)` |
 
 ### Variant model

package/dist/docs/{direction-provider.md → components/direction-provider.md}

@@ -3,18 +3,12 @@ title: DirectionProvider
 status: canonical
 category: Foundations
 archetype: utility
-package_path: packages/d4gger-design-system/src/components/directionProvider/DirectionProvider.tsx
-props_path: packages/d4gger-design-system/src/components/directionProvider/directionProvider.props.ts
-test_path: packages/d4gger-design-system/src/test/components/DirectionProvider.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: []
 ---
 
 # DirectionProvider
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{drawer.md → components/drawer.md}

@@ -2,22 +2,16 @@
 title: Drawer
 status: canonical
 category: Components
-archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/drawer/Drawer.tsx
-css_path: packages/d4gger-design-system/src/styles/components/drawer.css
-props_path: packages/d4gger-design-system/src/components/drawer/drawer.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Drawer.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
+archetype: adapter-backed
 depends_on:
+  - vaul
   - Dialog
   - Flex
 ---
 
 # Drawer
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{dropdown-menu.md → components/dropdown-menu.md}

@@ -3,26 +3,16 @@ title: DropdownMenu
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/dropdownMenu/DropdownMenu.tsx
-css_path: packages/d4gger-design-system/src/styles/components/dropdown-menu.css
-props_path: packages/d4gger-design-system/src/components/dropdownMenu/dropdownMenu.props.ts
-test_path: packages/d4gger-design-system/src/test/components/DropdownMenu.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:
   - "@radix-ui/react-dropdown-menu (the underlying Radix primitive; `DropdownMenu.Root`, `Trigger`, `Content`, `Label`, `Separator`, `Group`, `Sub`, `RadioGroup`, `CheckboxItem`, `RadioItem`, `SubTrigger`, `SubContent` proxy to it)"
   - "Menu (the internal abstraction; `MenuContent`, `MenuItem`, `MenuPortal`, `MenuRoot`, `MenuSeparator` are wrapped to share the framer-motion content open / close animation and the portal theme mirroring)"
   - "@radix-ui/react-slot (powers `asChild` on `Shortcut` and the prop-def bag on `Item` / `SubTrigger`)"
-  - _internal/BaseDialog (PortalThemeBoundary + PortalThemeWrapper; mirrors the `data-dsx-*` attribute contract into the content portal; `MenuContent` consumes the wrapper)
-  - _internal/motion (MOTION_TRANSITIONS.menu for the content open / close animation, MOTION_TRANSITIONS.reduced for `prefers-reduced-motion: reduce`; consumed by `MenuContent` and inherited by the DropdownMenu content)
-  - _internal/helpers/extractProps (turns the prop defs on `Item`, `SubTrigger`, and `Shortcut` into merged class + style output)
   - Icon (the `chevron-right` glyph on the sub-trigger; the `check` / `minus` glyphs on checkbox items)
 ---
 
 # DropdownMenu
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -168,7 +158,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token. The `dropdown-me
 | Content min-width | `var(--dsx-size-menu-min-width)` | Dropdown minimum width. |
 | Content padding | `var(--dsx-space-xs)` | Content gutter. |
 | Content border radius | `var(--dsx-rounded-lg)` | Content corner roundness. |
-| Content background | `var(--dsx-color-surface-overlay)` | Dropdown surface. |
+| Content background | `var(--dsx-color-panel-translucent)` | Dropdown surface. |
 | Content border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Dropdown edge. |
 | Content z-index | `var(--dsx-z-index-dropdown)` | Stack above page. |
 | Item min-height | `var(--dsx-size-lg)` | Item touch target. |
@@ -224,7 +214,7 @@ Rules:
 
 **Focus:**
 
-- The CSS file does not declare a focus ring; the shared menu item style in `_internal/baseMenu.css` paints the focus ring on `:focus-visible`. The ring stays visible on dark and light surfaces.
+- The CSS file does not declare a focus ring; the shared menu item style in `_internal/baseMenu.css` paints the focus ring on `:focus-visible`. The ring is **inset** (`inset 0 0 0 2px`) so it follows the item radius and never collides with the menu frame. The ring stays visible on dark and light surfaces.
 
 **Reduced motion:**
 

package/dist/docs/{editable.md → components/editable.md}

@@ -3,11 +3,6 @@ title: Editable
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/editable/Editable.tsx
-css_path: packages/d4gger-design-system/src/styles/components/editable.css
-props_path: packages/d4gger-design-system/src/components/editable/editable.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Editable.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Text (the visible value uses body-medium typography tokens; the runtime does not import the `Text` component, but the rendered string and placeholder share the same body-medium ramp)
   - Icon (lucide-react `Pencil`, `Check`, `X`)
@@ -17,7 +12,7 @@ depends_on:
 
 # Editable
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -52,6 +47,9 @@ The roster lists `Editable.Root`, `Editable.Preview`, and `Editable.Input` in th
 | `onCancel` | `() => void` | `undefined` | no | Called when the user cancels the edit (Escape, the cancel button). The value is reset to `defaultValue` in uncontrolled mode; in controlled mode the consumer owns the reset. | no |
 | `placeholder` | `string` | `'Enter text...'` | no | Placeholder text shown inside the preview span when the value is empty. | no |
 | `submitOnBlur` | `boolean` | `true` | no | When `true`, blur on the input commits the edit (calls `onSubmit` and exits edit mode). When `false`, blur keeps edit mode open and only the explicit submit / cancel affordances end it. | no |
+| `activationMode` | `'click' \| 'dblclick' \| 'focus'` | `'click'` | no | How the preview enters edit mode. `dblclick` needs a double click (safe for headings); `focus` activates on focus. Keyboard (Enter/Space on the focused preview) always works. | no |
+| `disabled` | `boolean` | `false` | no | Disables preview activation, input, and action buttons; root takes `dsx-editable--disabled` + `data-disabled`. | no |
+| `invalid` | `boolean` | `false` | no | Error state: input paints the error border and carries `aria-invalid`. | no |
 | `variant` | `'default' \| 'ghost'` | `'default'` | no | Visual variant. Writes `data-variant`. The CSS only declares a root-level hook today; visual treatment is reserved. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control padding and font size. Drives `data-size` and the per-size CSS overrides on preview and input. | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius override for the input. Writes `data-radius`; the CSS does not currently declare matching overrides — see the Anomalies section. | no |

package/dist/docs/{em.md → components/em.md}

@@ -3,17 +3,12 @@ title: Em
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/em/Em.tsx
-css_path: packages/d4gger-design-system/src/styles/components/em.css
-props_path: packages/d4gger-design-system/src/components/em/em.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Em.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on: []
 ---
 
 # Em
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -110,7 +105,7 @@ Rules:
 
 ## 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.
+`Em` is registered in `apps/playground/lib/registry/typography.tsx` under the `em` key. The registry entry imports `emPropDefs` and renders the component with a sample emphasis span. Per-component route: `/docs/em`.
 
 **Default story:**
 
@@ -126,7 +121,7 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper. Em has no accent-color or surface dependencies, so the story asserts the italic style is visually unchanged between `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`.
+- Renders inside a `Theme` wrapper. Em has no accent-color or surface dependencies, so the story asserts the italic style is visually unchanged between `accentColor="rift"`, `accentColor="warp"`, and `accentColor="ray"`.
 
 **A11y story:**
 

package/dist/docs/{empty-state.md → components/empty-state.md}

@@ -3,13 +3,6 @@ title: EmptyState
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/emptyState/EmptyState.tsx
-css_path: packages/d4gger-design-system/src/styles/components/empty-state.css
-props_path: packages/d4gger-design-system/src/components/emptyState/emptyState.props.ts
-test_path: packages/d4gger-design-system/src/test/components/EmptyState.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Icon
   - Text
@@ -22,7 +15,7 @@ depends_on:
 
 `EmptyState` is deprecated but not removed. Its normal host delegates to `Result state="empty"` while preserving the `dsx-empty-state` class, size/variant attributes, unavailable/staleness behavior, and public import. New list-state work should use Result and distinguish `empty` from `no-results`.
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{field.md → components/field.md}

@@ -3,13 +3,6 @@ title: Field
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/field/Field.tsx
-css_path: packages/d4gger-design-system/src/styles/components/field.css
-props_path: packages/d4gger-design-system/src/components/field/field.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Field.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Label (the `Field.Label` slot renders through the `Label` primitive for accessible `<label htmlFor>` association)
   - Text (the `Field.Description`, `Field.Error`, and `Field.Title` slots render through the `Text` primitive at the `body-medium` ramp; the runtime does not import `Text` as a value, it composes through it for the typography ramp only — see Anomalies)
@@ -18,7 +11,7 @@ depends_on:
 
 # Field
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -49,9 +42,9 @@ The default form-control wrapper for the design repo. Pairs a label, a control r
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
-| `invalid` | `boolean` | `false` | no | Marks the row as invalid. Writes `data-invalid="true"`, derives `data-state="invalid"`, and adds the `dsx-field-invalid` class. | no |
-| `disabled` | `boolean` | `false` | no | Marks the row as disabled. Writes `data-disabled="true"`, derives `data-state="disabled"`, and adds the `dsx-field-disabled` class. | no |
-| `orientation` | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | no | Row layout. Writes `data-orientation` and the `dsx-field-orientation` class. The CSS uses the attribute to swap to a 2-column grid for `horizontal` and a responsive auto-fit grid for `responsive`. | no |
+| `invalid` | `boolean` | `false` | no | Marks the row as invalid. Writes `data-invalid="true"` and derives `data-state="invalid"`. | no |
+| `disabled` | `boolean` | `false` | no | Marks the row as disabled. Writes `data-disabled="true"` and derives `data-state="disabled"`. | no |
+| `orientation` | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | no | Row layout. Writes `data-orientation`. The CSS uses the attribute to swap to a 2-column grid for `horizontal` and a responsive auto-fit grid for `responsive`. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Size of the row. Writes `data-size`. The CSS does not currently declare per-size rules; the attribute is the contract hook. | no |
 | (HTML div props) | n/a | n/a | no | All standard `<div>` attributes are forwarded. | no |
 
@@ -113,6 +106,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Row gap | `var(--dsx-space-xs)` | Default row gap. |
 | Row min-width | `0` | Allows the grid to shrink. |
 | Horizontal label column | `minmax(var(--dsx-size-field-label-min), var(--dsx-size-field-label-max))` | Label column size for `horizontal` orientation. |
+| Horizontal label alignment | `end` | Label text magnetizes toward the control in `horizontal` orientation. |
 | Horizontal row column gap | `var(--dsx-space-md)` | Row gap for `horizontal` orientation. |
 | Responsive column min | `var(--dsx-size-popover-min-width)` | Min column width for `responsive` orientation. |
 | Label color | `var(--dsx-color-on-surface)` | Default label. |
@@ -166,7 +160,7 @@ Rules:
 
 **Color and meaning:**
 
-- Invalid state is communicated by the `data-state="invalid"` attribute, the `data-invalid="true"` attribute, the `dsx-field-invalid` class, and the `Field.Error` slot. The label color also shifts to the error color, so the row does not rely on color alone.
+- Invalid state is communicated by the `data-state="invalid"` attribute, the `data-invalid="true"` attribute, and the `Field.Error` slot. The label color also shifts to the error color, so the row does not rely on color alone.
 
 **Naming:**
 
@@ -176,11 +170,12 @@ Rules:
 
 **Default story:**
 
-- Renders `Field` with a label, an input, and a description. Asserts the root class is `dsx-field`, the label is bound to the input via `htmlFor`, and the description text is rendered.
+- Renders `Field` with a label, an input, and a description. Asserts the root class is `dsx-field`, the label is bound to the input via `htmlFor`, and the description text is rendered. The matrix demo forwards the row's `size` (as the demo control's `density`), `disabled`, and `invalid` to the demo control so each axis reads visually; `Field` itself never sizes or disables children — that wiring is the consumer's composition.
 
 **Orientation story:**
 
-- Renders `Field` with `orientation="vertical"`, `orientation="horizontal"`, and `orientation="responsive"`. Asserts the matching `data-orientation` attribute is set on the root.
+- Renders `Field` with `orientation="vertical"`, `orientation="horizontal"`, and `orientation="responsive"`. Asserts the matching `data-orientation` attribute is set on the root. The `horizontal` story asserts the label is end-aligned toward the control.
+- The `responsive` orientation is an auto-fit grid: it needs room (wider than twice the 200px column minimum) and sibling controls to reflow. The fixture demonstrates it with a two-control dense row in a 640px container; a single control in a narrow container stacks exactly like `vertical` by design.
 
 **State story:**
 
@@ -221,6 +216,7 @@ Rules:
 
 - `Form` (per the roster's `Composed From` column) uses `Field` as its label, description, and error carrier. The `Form` runtime does not import `Field` directly; it composes the same primitives (`Label`, `Text`).
 - Every DS form-row spec (e.g. `Select`, `Combobox`, `InputOtp`) is intended to live inside `Field.Root` for label, description, and error wiring.
+- See [form-ownership.md](./form-ownership.md) for the Field vs Form ownership diagram and nesting rules.
 
 **State boundaries:**
 

package/dist/docs/{file-upload.md → components/file-upload.md}

@@ -3,13 +3,6 @@ title: FileUpload
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/fileUpload/FileUpload.tsx
-css_path: packages/d4gger-design-system/src/styles/components/file-upload.css
-props_path: packages/d4gger-design-system/src/components/fileUpload/fileUpload.props.ts
-test_path: packages/d4gger-design-system/src/test/components/FileUpload.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Card
   - EmptyState
@@ -17,15 +10,16 @@ depends_on:
   - Progress
   - Button
   - Icon
+  - react-dropzone
 ---
 
 # FileUpload
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
-A card-based file selection surface with a dropzone, a list of file rows, and a progress bar per row. The dropzone is built on `EmptyState` and exposes a `dragging` data attribute, the list wraps `Item` rows that compose a `Progress` bar and an actions block, and the root is a `Card` so the whole surface fits the standard card surface treatment.
+A card-based file selection surface with a dropzone, a list of file rows, and a progress bar per row. The dropzone is built on `EmptyState` and captures files through `react-dropzone` (optional peer) when `onFiles` is set — without `onFiles` it renders a visual-only shell with no file input. It exposes a `dragging` data attribute, the list wraps `Item` rows that compose a `Progress` bar and an actions block, and each row carries a `statusTone` (`muted`/`danger`) so failed uploads read in the error color. The root is a `Card` so the whole surface fits the standard card surface treatment.
 
 ## Anatomy & slots
 
@@ -36,9 +30,9 @@ A card-based file selection surface with a dropzone, a list of file rows, and a
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
 | `FileUpload.Root` | `Card.Root` | card host | The surface container. Writes `data-size`. |
-| `FileUpload.Dropzone` | `EmptyState` (rendered through a `<section>`) | dropzone target with title, description, illustration, and action | Exposes `data-dragging` for the active drop state. |
+| `FileUpload.Dropzone` | `EmptyState` (rendered through a `<section>`) | dropzone target with title, description, illustration, and action | Captures files via `react-dropzone` when `onFiles` is set (hidden input + drag events); visual-only shell otherwise. Exposes `data-dragging` for the active drop state. |
 | `FileUpload.List` | `<div>` | vertical list container | The list of `FileUpload.Item` rows. |
-| `FileUpload.Item` | `Item` | one file row with media, content, and actions | Composes `ItemMedia`, `ItemContent` (title, description, optional progress), and `ItemActions` (status, actions). |
+| `FileUpload.Item` | `Item` | one file row with media, content, and actions | Composes `ItemMedia`, `ItemContent` (title, description, status, optional progress), and `ItemActions` (icon actions only). Writes `data-status-tone="danger"` when `statusTone` is `danger`; omits the attribute when `muted`. |
 | `FileUpload.Progress` | `<div>` wrapping `Progress` | progress bar + optional label | When `showValueLabel` is `true` and no `label` is provided, the progress label is ``${Math.round(value)}%``. |
 
 ## Props contract
@@ -62,6 +56,9 @@ A card-based file selection surface with a dropzone, a list of file rows, and a
 | `action` | `ReactNode` | `undefined` | no | Custom action element. Takes precedence over `actionLabel`. | no |
 | `actionLabel` | `ReactNode` | `undefined` | no | Default action label. When set without an explicit `action`, the dropzone renders a `Button` with `variant="outline"`. | no |
 | `onActionClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined` | no | Default action click handler. | no |
+| `accept` | `Accept` (`react-dropzone`) | `undefined` | no | Accepted MIME types / extensions forwarded to `useDropzone`. | no |
+| `multiple` | `boolean` | `undefined` | no | When `true`, the hidden input and drop accept multiple files. | no |
+| `onFiles` | `(files: File[]) => void` | `undefined` | no | File capture handler. When set, the dropzone mounts the hidden input and forwards drops and picks; when absent, the dropzone is a visual-only shell (`useDropzone` disabled, no input). | no |
 | `dragging` | `boolean` | `false` | no | Active drop state. Drives `data-dragging="true"`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the dropzone through `Slot` from `@radix-ui/react-slot`. | no |
 | Standard `EmptyState` props | `EmptyStateProps` (without `action`, `description`, `illustration`, `title`) | n/a | no | The dropzone omits the four props it owns and forwards the rest. | no |
@@ -83,7 +80,8 @@ A card-based file selection surface with a dropzone, a list of file rows, and a
 | `icon` | `ReactNode` | `undefined` | no | Custom file icon. When `null`, the icon slot is hidden. Default is `Icon name="file" size="sm"`. | no |
 | `progress` | `number` | `undefined` | no | When a number, the item renders a `FileUpload.Progress` with this value. | no |
 | `progressLabel` | `ReactNode` | `undefined` | no | Custom progress label. Overrides the auto `${value}%` label. | no |
-| `status` | `ReactNode` | `undefined` | no | Status text rendered above the actions block. | no |
+| `status` | `ReactNode` | `undefined` | no | Status text rendered in the content column under the description (name → meta → bar, icons alone on the right). | no |
+| `statusTone` | `'muted' \| 'danger'` | `'muted'` | no | Status text tone. `danger` paints the status in the error color and writes `data-status-tone="danger"` on the item; `muted` keeps the quiet label and omits the attribute. | no |
 | `actions` | `ReactNode` | `undefined` | no | Action affordances rendered in the `ItemActions` block. | no |
 | `asChild` | `boolean` | `false` | no | Renders the item through `Slot`. | no |
 | Standard `Item` props | `Omit<ItemProps, 'children'>` | n/a | no | Forwarded. The interface omits `children` because the item composes its own. | no |
@@ -111,7 +109,8 @@ Rules:
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-size` | `sm`, `md`, `lg` | n/a (no size-specific root CSS today) | `file-upload.css` |
-| `data-dragging` | `true` | `.dsx-file-upload__dropzone[data-dragging='true']` border, background, and focus ring | `file-upload.css` |
+| `data-dragging` | `true` | `.dsx-file-upload__dropzone[data-dragging='true']` thicker accent dashed border + active background (no ring) | `file-upload.css` |
+| `data-status-tone` | `danger` (omitted when `muted`) | `.dsx-file-upload__item:where([data-status-tone='danger']) .dsx-file-upload__status` error color | `file-upload.css` |
 
 **Slot classes:**
 
@@ -149,13 +148,13 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Root layout | `display: grid; gap: var(--dsx-space-md); width: 100%` | Surface layout. |
 | Dropzone width | `width: 100%` | Full width. |
 | Dropzone min-height | `calc(var(--dsx-size-4xl) * 2)` | Tall enough to invite a drop. |
-| Dropzone border | `var(--dsx-border-width-sm)` dashed `var(--dsx-color-outline-variant)` | Resting edge. |
+| Dropzone border | `var(--dsx-border-width-md)` dashed `var(--dsx-color-outline)` | Resting edge, visible against the sunken fill. |
 | Dropzone radius | `var(--dsx-rounded-lg)` | Round corners. |
 | Dropzone background | `var(--dsx-color-surface-sunken)` | Sunken surface. |
 | Dropzone transition | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Border, background, and box-shadow transitions. |
-| Dropzone dragging border | `var(--dsx-color-primary)` | Active edge. |
+| Dropzone dragging border | `var(--dsx-border-width-md)` dashed `var(--dsx-color-primary)` | Active edge — thicker and accent-colored, no ring, so the drag state never doubles the outline. |
 | Dropzone dragging background | `var(--dsx-color-high-contrast-container)` | Active fill. |
-| Dropzone dragging shadow | `var(--dsx-shadow-focus-ring)` | Active focus ring. |
+| Dropzone keyboard focus | `var(--dsx-shadow-focus-ring)` on `:focus-visible` | The ring belongs to keyboard focus, not to the drag state. |
 | Dropzone icon color | `var(--dsx-color-primary)` | Active affordance color. |
 | Item icon size | `var(--dsx-size-lg)` square | Round icon slot. |
 | Item icon color | `var(--dsx-color-on-surface-variant)` | Quiet icon. |
@@ -166,6 +165,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Progress width | `width: 100%` | Full row width. |
 | Progress label/status typography | `var(--dsx-typography-label-small-*)` | Small label ramp. |
 | Progress label/status color | `var(--dsx-color-on-surface-variant)` | Quiet label. |
+| Failed status color | `var(--dsx-color-error)` | Error tone, gated behind `data-status-tone="danger"` so `muted` rows never pay for it. |
 
 ## Motion contract
 
@@ -188,7 +188,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Focus:**
 
-- The dropzone relies on the underlying `EmptyState` and `Button` focus rules. The `data-dragging='true'` state adds the focus ring to the dropzone as a visual cue.
+- The dropzone relies on the underlying `EmptyState` and `Button` focus rules. Keyboard focus paints `var(--dsx-shadow-focus-ring)` via `:focus-visible`; the `data-dragging='true'` state instead thickens the dashed border to the accent color, so drag feedback and focus feedback never stack into a double outline.
 
 **Reduced motion:**
 
@@ -200,7 +200,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Naming:**
 
-- The dropzone should expose an accessible name via its `title` prop. The default action button labels itself through the `actionLabel` prop. Each `FileUpload.Item` is named by its `fileName` content.
+- The dropzone should expose an accessible name via its `title` prop. The default action button labels itself through the `actionLabel` prop. Each `FileUpload.Item` is named by its `fileName` content. Row actions are consumer-owned — the recommended pattern is ghost `IconButton`s (`trash` for remove, `redo` for retry) with `aria-label`s naming the file, as the playground fixture demonstrates.
 
 ## Playground demo spec
 
@@ -218,7 +218,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Composition story:**
 
-- Renders the full surface: dropzone, list, two items. The first item has a `progress={42}` and a `progressLabel="Uploading…"`. The second item has a `status="Complete"` and an `actions={<Button>Remove</Button>}`. Asserts each slot renders with the right class, the progress bar renders with the rounded percentage, and the actions block sits at the right edge.
+- Renders the full surface: dropzone, list, three items. The first item has a `progress={42}` with no label (the meta line carries the numbers, as in the reference). The second item has a `status="Complete"` and a ghost `IconButton` trash remove action. The third item has a `status="Upload failed"` with `statusTone="danger"` and ghost `IconButton` redo retry + trash remove actions. Asserts each slot renders with the right class, the progress bar renders, the failed row writes `data-status-tone="danger"`, and the actions block sits at the right edge with icons only.
+
+**Live capture story:**
+
+- Renders `FileUploadLiveCapture`: a `multiple` dropzone with `onFiles` feeding a simulated upload list (interval-driven `progress` with reference-style `"X MB | Y% • Z sec left"` descriptions), an "Or upload from URL" `Input` + `Upload` `Button` composition appending completed rows, ghost `IconButton` row actions (trash remove always, redo retry on failed rows — retry resets the row to 0%), a fail preview (files with "fail" in the name fail at 60%), and a Cancel / Attach-files footer. Covered by `tests/file-upload.spec.ts` (drag capture, browse capture, zero console issues).
 
 **A11y story:**
 
@@ -239,22 +243,27 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 - `Card`: the root extends `CardProps` and renders through `Card.Root`.
 - `EmptyState`: the dropzone extends `EmptyStateProps` and renders through `EmptyState`.
+- `react-dropzone` (optional peer `>=14`, declared in `peerDependencies`): the dropzone forwards `accept`, `multiple`, and `onDrop → onFiles` to `useDropzone`. Consumers install it only when they use file capture; the visual-only shell never touches it. The hidden input carries an `aria-label` derived from the dropzone `title`.
 - `Item` and its subcomponents: the file row composes `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, and `ItemActions`.
 - `Progress`: the progress block composes the package `Progress` primitive.
 - `Button`: the default dropzone action renders through `Button` with `variant="outline"`.
 - `Icon` (lucide-react `upload`, `file`): the default illustrations.
 - `@radix-ui/react-slot`: enables `asChild` on the root, dropzone, list, and item hosts.
 
+**Composed by consumers (not DS slots):**
+
+- URL upload (`Input` + `Button` appending a completed row) and modal shells with Cancel / Attach-files footers are app composition. The playground `FileUploadLiveCapture` fixture demonstrates both against the same list state.
+
 **Used by:**
 
 - Form specs that need a managed file picker. Apps own the file selection pipeline, the upload progress source, the onAction click handler, and the actual upload transport.
 
 **State boundaries:**
 
-- Owned by FileUpload: the root card surface, the dropzone presentation, the file row layout, the progress block, and the auto `${value}%` label derivation.
-- Owned by the consumer: the file list, the upload progress source, the dropzone click handler, the drag state (`dragging` is a controlled boolean), the per-item `fileName` and `description`, and the surrounding form context.
+- Owned by FileUpload: the root card surface, the dropzone presentation, the file capture engine (drag events, keyboard activation, hidden input) while `onFiles` is set, the file row layout, the progress block, the `statusTone` derivation, and the auto `${value}%` label derivation.
+- Owned by the consumer: the file list, the upload progress source and transport, the dropzone click handler, the forced drag state (`dragging` is a controlled boolean layered over the engine's own active state), the per-item `fileName` and `description`, URL fetching, and the surrounding form or dialog context.
 
 **Boundary rules:**
 
-- App-owned data: the files, the upload pipeline, the drag detection (the package does not implement drag-and-drop, only the visual `dragging` state), the validation, and the persisted references.
-- DS-owned visuals: the surface, the dropzone, the list, the item, the progress block, the icons, the labels, and the size token.
+- App-owned data: the files, the upload pipeline, the validation, the persisted references, URL fetching, and transport-level progress.
+- DS-owned visuals and capture: the surface, the dropzone, the drag-and-drop plus browse capture engine, the list, the item, the progress block, the icons, the labels, the `statusTone`, and the size token.

package/dist/docs/{filter-bar.md → components/filter-bar.md}

@@ -3,13 +3,6 @@ title: FilterBar
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/filterBar/FilterBar.tsx
-css_path: packages/d4gger-design-system/src/styles/components/filter-bar.css
-props_path: packages/d4gger-design-system/src/components/filterBar/filterBar.props.ts
-test_path: packages/d4gger-design-system/src/test/components/FilterBar.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Toolbar
   - Button

package/dist/docs/{flex.md → components/flex.md}

@@ -3,20 +3,13 @@ title: Flex
 status: canonical
 category: Foundations
 archetype: layout-primitive
-package_path: packages/d4gger-design-system/src/components/flex/Flex.tsx
-css_path: packages/d4gger-design-system/src/styles/components/flex.css
-props_path: packages/d4gger-design-system/src/layout/layout.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Flex.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/layout.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Box
 ---
 
 # Flex
 
-> Source of truth: the package source at `package_path`. The spec mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -80,7 +73,7 @@ The runtime also produces the same set of classes for the `align`, `justify`, an
 | `data-align` | serialized `ResponsiveValue` of `align` | Visual value |
 | `data-justify` | serialized `ResponsiveValue` of `justify` | Visual value |
 
-The `dsx-flex` selector sets `display: var(--dsx-box-display, flex)` so the default Flex container is `display: flex`.
+The `dsx-flex` selector sets `display: var(--dsx-box-display, flex)` so the default Flex container is `display: flex`. It also consumes the `--dsx-flex-direction`, `--dsx-flex-align`, `--dsx-flex-justify`, and `--dsx-flex-wrap` custom properties written through `FLEX_PROP_DEFS` (for example by `Container` flex props), with `row` / `stretch` / `flex-start` / `nowrap` fallbacks. The canonical `Flex` component itself renders the `dsx-r-fd-*` / `dsx-r-ai-*` / `dsx-r-jc-*` / `dsx-r-fw-*` utility classes, which load after `flex.css` and win at equal specificity; the custom-property path is the fallback for `extractLayoutProps` consumers that do not emit those classes.
 
 **Slot classes:** none. Flex is a flat export.
 

package/dist/docs/{floating-panel.md → components/floating-panel.md}

@@ -3,11 +3,6 @@ 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)
@@ -17,7 +12,7 @@ depends_on:
 
 # 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -150,7 +145,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|---|
 | 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 fill | `var(--dsx-color-panel-translucent)` | 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. |
@@ -343,7 +338,7 @@ The package does not yet publish a Penpot asset for FloatingPanel. Recipe is vis
 
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
-| Shell | fill | `--dsx-color-surface-overlay` | Color | `fills` |
+| Shell | fill | `--dsx-color-panel-translucent` | Color | `fills` |
 | Shell | stroke | `--dsx-color-outline` | Color | `strokes` |
 | Shell | radius | `--dsx-rounded-xl` | Radius | `radius` |
 | Shell | shadow | `--dsx-shadow-md` | Effect | `shadow` |