@d4gger/design-system 2.7.0 → 3.0.1

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,9 +145,9 @@ 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 shadow (rest) | `var(--dsx-shadow-md)` | Resting elevation. |
-| Shell shadow (dragging) | `var(--dsx-shadow-xl)` | Active elevation. |
+| Shell fill | `var(--dsx-color-panel-translucent)` | Panel surface. |
+| Shell shadow (rest) | `var(--dsx-shadow-elevation-2)` | Resting elevation. |
+| Shell shadow (dragging) | `var(--dsx-shadow-elevation-5)` | 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. |
@@ -343,11 +338,11 @@ 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` |
-| Shell (dragging) | shadow | `--dsx-shadow-xl` | Effect | `shadow` (state) |
+| Shell | shadow | `--dsx-shadow-elevation-2` | Effect | `shadow` |
+| Shell (dragging) | shadow | `--dsx-shadow-elevation-5` | 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` |
@@ -361,10 +356,10 @@ The package does not yet publish a Penpot asset for FloatingPanel. Recipe is vis
 
 | 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` |
+| `default` | `--dsx-shadow-elevation-2` | `grab` | `transparent` | `--dsx-opacity-muted` |
+| `dragging` | `--dsx-shadow-elevation-5` | `grabbing` | `transparent` | `1` |
+| `close-hover` | `--dsx-shadow-elevation-2` | `grab` | `--dsx-effect-hover-layer` | `--dsx-opacity-muted` |
+| `handle-hover` | `--dsx-shadow-elevation-2` | `grab` | `transparent` | `1` |
 
 ### Variant model
 

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

@@ -3,22 +3,16 @@ 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## 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.
+A root-level font coordinator that writes the body and display typography-family variables on `document.documentElement` and `document.body`, optionally loads the canonical Science Gothic and JetBrains Mono hosted families, and exposes a `useFont` hook for the active body family.
 
 ## Anatomy & slots
 
@@ -26,26 +20,29 @@ A root-level font loader that writes the `--dsx-font-family` CSS custom property
 
 **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`.
+No slots: flat export. The component renders no wrapper element. It provides a `FontContext` and runs document side effects that write or restore every display/headline and body/label family token on `html` and `body`. When `loadGoogleFonts` is true, it also manages one deduplicated default-font stylesheet link.
 
 ## 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 |
+| `fontFamily` | `string` | `'Science Gothic, ui-sans-serif, system-ui, sans-serif'` | no | Family written to every body and label typography family token on `html` and `body`. Accepts any CSS font-family expression. | no |
+| `displayFontFamily` | `string` | `'Science Gothic, Arial Narrow, ui-sans-serif, system-ui, sans-serif'` | no | Family written to every display and headline typography family token on `html` and `body`. | no |
+| `loadGoogleFonts` | `boolean` | `false` | no | Injects a deduplicated Google Fonts stylesheet for the canonical Science Gothic and JetBrains Mono Cyrillic/Latin families. | 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.
+- The provider snapshots the prior body and display properties on mount, applies the requested values through `style.setProperty`, and restores both snapshots on unmount.
+- `loadGoogleFonts` creates `link#dsx-font-provider-default-fonts` only when needed and removes the link it created on cleanup.
+- The `useFont` hook returns the context value when called inside the provider, or the canonical Science Gothic body stack 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`.
+**Modifier classes:** none. The provider writes the family variables consumed by the typography role tokens on `document.documentElement` and `document.body`, and may manage a stylesheet link in `document.head`.
 
 **Slot classes:** none.
 
@@ -59,15 +56,16 @@ Rules that apply to this row:
 
 ## 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.
+The provider writes the body/label and display/headline family properties. Its defaults match the canonical token families, while the rest of the typography ramp continues to come from generated tokens.
 
-| Document property | Token | Role |
+| Document properties | Default | Role |
 |---|---|---|
-| `--dsx-font-family` | `var(--dsx-typography-body-medium-font-family, sans-serif)` (default) | Active document font family. |
+| `--dsx-typography-body-*-font-family`, `--dsx-typography-label-*-font-family` | `Science Gothic, ui-sans-serif, system-ui, sans-serif` | Active body and UI family. |
+| `--dsx-typography-display-*-font-family`, `--dsx-typography-headline-*-font-family` | `Science Gothic, Arial Narrow, ui-sans-serif, system-ui, sans-serif` | Active display and heading 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.
+- The provider does not introduce new tokens. It overrides the generated family properties directly and leaves size, weight, spacing, and variable-axis presets intact.
 - 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
@@ -112,7 +110,7 @@ Rules:
 
 **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.
+- The registry render returns a description of the root-level provider. The provider's effect is exercised by the package's canonical Science Gothic family values.
 
 **Variant story:**
 
@@ -124,11 +122,11 @@ Rules:
 
 **State story:**
 
-- The provider's only state is the `fontFamily` value. The default is the body-medium token reference.
+- The provider state is the body/display family pair plus the optional canonical hosted-font loader flag.
 
 **Token story:**
 
-- The default `fontFamily` is a token reference, so the playground renders all typography with the body-medium ramp by default.
+- The default `fontFamily` matches the canonical body family, while size, weight, spacing, and variable-axis values continue to come from the role tokens.
 
 **A11y story:**
 
@@ -148,17 +146,18 @@ The playground does not expose `FontProvider` controls because the provider muta
 
 - React `createContext`, `useContext`, `useEffect`, and `useMemo`.
 - The native `document.documentElement.style.setProperty` / `removeProperty` API.
+- The native document head/link API when `loadGoogleFonts` is enabled.
 - 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.
+- The Playground root does not currently mount `FontProvider`; generated typography tokens provide the default family and role presets.
+- App roots that need a custom family wrap the app in `FontProvider fontFamily="Inter, sans-serif"` after preloading it.
 
 **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.
+- Owned by FontProvider: the body/display family properties, the `FontContext` value, and lifecycle of its optional default-font link.
+- Owned by the consumer: the body/display family props, primary font loading strategy, and the `useFont` consumer's response to the value.
 
 **Boundary rules:**
 

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

@@ -3,13 +3,6 @@ title: Form
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/form/Form.tsx
-css_path: packages/d4gger-design-system/src/styles/components/form.css
-props_path: packages/d4gger-design-system/src/components/form/form.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Form.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:
   - react-hook-form (the `Form` composite wires its submission through `useForm`'s `handleSubmit`; the `FormField` slot is a thin wrapper around `Controller`)
   - Field (per the roster's `Composed From` column; the runtime does not import `Field` directly — `Form` is an orchestration layer around the same primitives `Field` composes, see Anomalies)
@@ -19,7 +12,7 @@ depends_on:
 
 # Form
 
-> 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
 
@@ -54,7 +47,7 @@ An orchestration layer for form-level submission and field validation. `Form` wi
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
-| `layout` | `'standard' \| 'compact'` | `'standard'` | no | Row-gap profile. Writes `data-layout` and the `dsx-form-layout` class. The CSS uses the attribute to swap between `var(--dsx-space-lg)` and `var(--dsx-space-md)`. | no |
+| `layout` | `'standard' \| 'compact'` | `'standard'` | no | Row-gap profile. Writes `data-layout`. The CSS uses the attribute to swap between `var(--dsx-space-lg)` and `var(--dsx-space-md)`. | no |
 | `form` | `UseFormReturn<TFieldValues>` | `undefined` | no | The `react-hook-form` instance. When provided together with `onSubmit`, the root wires `onSubmit={form.handleSubmit(onSubmit)}`. | no |
 | `onSubmit` | `(values: TFieldValues) => void \| Promise<void>` | `undefined` | no | The submission handler. Only wired when `form` is also provided. | no |
 | (HTML form props) | n/a | n/a | no | All standard `<form>` attributes are forwarded. `onSubmit` is omitted from the forwarded bag because the root owns it. | no |
@@ -215,7 +208,7 @@ Rules:
 
 **Layout story:**
 
-- Renders `Form` with `layout="standard"` and `layout="compact"`. Asserts the matching `data-layout` attribute is set on the root.
+- Renders `Form` with `layout="standard"` and `layout="compact"`. Asserts the matching `data-layout` attribute is set on the root. The fixture must not set an inline `gap` on these forms — an inline gap overrides the token row-gap the story is demonstrating (standard 24px vs compact 16px).
 
 **State story:**
 
@@ -225,6 +218,7 @@ Rules:
 **Composition story:**
 
 - Renders a full form with `Form.Header > Form.Title`, `Form.Body > Form.Item > Form.Label + Form.Control + Form.Description + Form.Message`, and `Form.Actions` with submit / cancel buttons. Asserts every slot has the right class and the right `data-slot` attribute.
+- Renders a reference composition: `Form.Header` section, a two-column `Grid` of `Field.Root` rows (the canonical multi-column recipe — `Grid` + `Form.Item`/`Field.Root`, never a form-owned grid slot), a row with an inline action button, and `FormActions` footer. Multi-column layout, sections, and inline actions are app composition from existing primitives; `Form` owns no grid, section, or inline-action slot.
 
 **A11y story:**
 
@@ -251,6 +245,7 @@ Rules:
 
 - `Field` does not import `Form`. `Form` is the orchestration surface; `Field` is the canonical row surface. Apps compose `Form` and `Field` at the row level: `Form.Field` for the controller wiring, then `Form.Item > Form.Label + <Field.Root><Field.Label /><Field.Content><Input /></Field.Content><Field.Description /><Field.Error /></Field.Root> + Form.Message` if a richer row is needed.
 - App-level auth, profile, and settings forms use `Form` directly.
+- See [form-ownership.md](./form-ownership.md) for the Field vs Form ownership diagram and nesting rules.
 
 **State boundaries:**
 

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

@@ -3,20 +3,13 @@ title: Grid
 status: canonical
 category: Foundations
 archetype: layout-primitive
-package_path: packages/d4gger-design-system/src/components/grid/Grid.tsx
-css_path: packages/d4gger-design-system/src/styles/components/grid.css
-props_path: packages/d4gger-design-system/src/layout/layout.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Grid.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
 ---
 
 # Grid
 
-> 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
 
@@ -89,6 +82,7 @@ The `dsx-grid` selector wires the grid-template custom properties:
   grid-template-rows: var(--dsx-grid-rows, none);
   grid-template-areas: var(--dsx-grid-areas, none);
   grid-auto-flow: var(--dsx-grid-auto-flow, row);
+  align-items: var(--dsx-grid-align, stretch);
   align-content: var(--dsx-grid-align-content, normal);
   justify-items: var(--dsx-grid-justify-items, legacy);
   justify-content: var(--dsx-grid-justify-content, normal);

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

@@ -3,19 +3,12 @@ title: Heading
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/heading/Heading.tsx
-css_path: packages/d4gger-design-system/src/styles/components/heading.css
-props_path: packages/d4gger-design-system/src/components/heading/heading.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Heading.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/typography.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Heading
 
-> 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
 
@@ -40,7 +33,7 @@ No slots: flat export. The component renders a single `h1`–`h6` host element (
 | `weight` | `string` | `undefined` | no | Typography weight. Writes the `dsx-r-weight-{name}` class. Accepts a responsive value. | yes |
 | `align` | `string` | `undefined` | no | Text alignment. Writes the `dsx-r-ta-{name}` class. Accepts a responsive value. | yes |
 | `wrap` | `string` | `undefined` | no | Text wrap. Writes the `dsx-r-wrap-{name}` class. | no |
-| `truncate` | `boolean` | `undefined` | no | When set, writes the `dsx-r-truncate` class. | no |
+| `truncate` | `boolean` | `undefined` | no | When set, writes the `dsx-truncate` class. | no |
 | `trim` | `string` | `undefined` | no | Leading-trim behavior. Writes the `dsx-r-lt-{name}` class. | no |
 | `highContrast` | `boolean` | `false` | no | When `true`, writes `data-high-contrast="true"`. | no |
 | `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my` | `string` | `undefined` | no | Margin style props from the `margin.prop` def. | no |
@@ -73,7 +66,7 @@ Rules that apply to this row:
 | (class) | any align name | `dsx-r-ta-{name}` (and breakpoint-prefixed variants) | `src/styles/responsive/*.css` |
 | (class) | any wrap name | `dsx-r-wrap-{name}` | `src/styles/responsive/*.css` |
 | (class) | any trim name | `dsx-r-lt-{name}` | `src/styles/responsive/*.css` |
-| (class) | `true` (truncate) | `dsx-r-truncate` | `src/styles/responsive/*.css` |
+| (class) | `true` (truncate) | `dsx-truncate` | `src/styles/responsive/truncate.css` |
 | `data-high-contrast` | `true` | `.dsx-heading[data-high-contrast='true']` | `heading.css` |
 
 **Slot classes:** none.
@@ -177,7 +170,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the `data-accent-color` attribute on the wrapper tracks the active accent.
+- Renders inside a `Theme` wrapper with `accentColor="warp"` and `accentColor="ray"`. Asserts the `data-accent-color` attribute on the wrapper tracks the active accent.
 
 **A11y story:**
 
@@ -222,6 +215,8 @@ Rules:
 - App-owned data: the prose context, the surrounding copy, and the host element when `asChild` is set.
 - DS-owned visuals: the `dsx-heading` root class, the variant, tone, size, color, weight, align, wrap, trim, truncate, and high-contrast classes and attributes, and the prop def bag.
 
+> Caution (foundation vs app tone axes): the foundation `FoundationHeading` tone axis is `default | muted | primary | secondary | success | error` painted through the `--dsx-heading-color` CSS variable, while this app-level `Heading` tone axis is `default | muted | inverse` painted through modifier classes. The two contracts are not interchangeable — do not pass a foundation tone to `Heading` or expect `dsx-heading--inverse` from `FoundationHeading`.
+
 ## Penpot build recipe
 
 > Optional. Penpot is a visual reference, not a code authority. The Heading recipe tracks the variant, tone, size, color, weight, align, wrap, trim, truncate, and high-contrast contract.

package/dist/docs/{hover-card.md → components/hover-card.md}

@@ -3,20 +3,13 @@ title: HoverCard
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/hoverCard/HoverCard.tsx
-css_path: packages/d4gger-design-system/src/styles/components/hover-card.css
-props_path: packages/d4gger-design-system/src/components/hoverCard/hoverCard.props.ts
-test_path: packages/d4gger-design-system/src/test/components/HoverCard.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:
   - Popover
 ---
 
 # HoverCard
 
-> 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
 
@@ -262,7 +255,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-lg)` | Radius | `borderRadius` |
 | `<Content frame>` | spacing | `var(--dsx-space-md)` | Spacing | `padding` |
 | `<Arrow svg>` | fill | `currentColor` | Color | `fills` |
@@ -271,8 +264,8 @@ Rules:
 
 | State | Content fill | Content shadow |
 |---|---|---|
-| `default` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-2)` |
-| `hover` (trigger) | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-3)` |
+| `default` | `var(--dsx-color-panel-translucent)` | `var(--dsx-shadow-elevation-2)` |
+| `hover` (trigger) | `var(--dsx-color-panel-translucent)` | `var(--dsx-shadow-elevation-3)` |
 
 ### Variant model
 

package/dist/docs/{icon-button.md → components/icon-button.md}

@@ -3,13 +3,6 @@ title: IconButton
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/iconButton/IconButton.tsx
-css_path: packages/d4gger-design-system/src/styles/components/icon-button.css
-props_path: packages/d4gger-design-system/src/components/iconButton/iconButton.props.ts
-test_path: packages/d4gger-design-system/src/test/components/IconButton.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/actions.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Button
   - Spinner
@@ -18,7 +11,7 @@ depends_on:
 
 # IconButton
 
-> 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
 
@@ -71,7 +64,7 @@ Rules:
 | `data-high-contrast` | `true` | `.dsx-icon-button:where([data-variant='outline'])[data-high-contrast='true']` etc. (variant-specific HC overrides) | `icon-button.css` |
 | `data-loading` | `true` | `.dsx-icon-button[data-loading='true']` | `icon-button.css` |
 | `data-disabled` | `true` | `.dsx-icon-button[data-disabled='true']` | `icon-button.css` |
-| `aria-pressed` | `true` | n/a (CSS does not target this attribute) | n/a |
+| `aria-pressed` | `true` | pressed overlay for `primary`/`secondary` (same layers as Button) | n/a |
 
 **Internal classes** (implementation detail, not public slots):
 
@@ -134,6 +127,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Text (destructive) | `var(--dsx-color-on-error)` | Destructive icon. |
 | Border (destructive) | `var(--dsx-color-error)` | Destructive edge. |
 | Background (destructive hover) | `linear-gradient(var(--dsx-effect-hover-secondary), var(--dsx-effect-hover-secondary)), var(--dsx-color-error)` | Destructive hover overlay. |
+| Background (primary pressed) | `linear-gradient(var(--dsx-effect-pressed-primary), var(--dsx-effect-pressed-primary)), var(--dsx-color-accent-track)` | Primary pressed overlay (Button parity). |
+| Background (secondary pressed) | `linear-gradient(var(--dsx-effect-pressed-layer), var(--dsx-effect-pressed-layer)), var(--dsx-color-secondary)` | Secondary pressed overlay (Button parity). |
+| Box shadow (halo) | `var(--dsx-shadow-accent-ring)` | Resting halo on every variant (`data-halo`), locked 2026-09-22 — same model as Button. |
 | Background (destructive HC) | `var(--dsx-color-error)` | High-contrast destructive fill. |
 | Border (destructive HC) | `var(--dsx-color-high-contrast-border)` | High-contrast destructive edge. |
 | Focus ring | `var(--dsx-shadow-focus-ring)` | Visible focus ring on `:focus-visible`. |

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

@@ -3,19 +3,12 @@ title: Icon
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/icon/Icon.tsx
-css_path: packages/d4gger-design-system/src/components/icon/Icon.tsx
-props_path: packages/d4gger-design-system/src/components/icon/icon.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Icon.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: []
 ---
 
 # Icon
 
-> 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/{input-group.md → components/input-group.md}

@@ -3,13 +3,6 @@ title: InputGroup
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/inputGroup/InputGroup.tsx
-css_path: packages/d4gger-design-system/src/styles/components/input-group.css
-props_path: packages/d4gger-design-system/src/components/inputGroup/inputGroup.props.ts
-test_path: packages/d4gger-design-system/src/test/components/InputGroup.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:
   - Input
   - TextArea
@@ -18,7 +11,7 @@ depends_on:
 
 # InputGroup
 
-> 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/{input-otp.md → components/input-otp.md}

@@ -3,22 +3,14 @@ title: InputOtp
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/inputOtp/InputOtp.tsx
-css_path: packages/d4gger-design-system/src/styles/components/input-otp.css
-props_path: packages/d4gger-design-system/src/components/inputOtp/inputOtp.props.ts
-test_path: packages/d4gger-design-system/src/test/components/InputOtp.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:
   - input-otp (the `OTPInput` primitive, `OTPInputContext`, and the `RenderProps` type come from the `input-otp` package; the runtime is a thin DS wrapper around it)
-  - "_internal/baseInput.css (shared border, hover, focus, disabled, and autofill contract; the OTP shell imports it for parity with `Input`)"
   - "@radix-ui/react-slot (asChild on the root and on the group slot)"
 ---
 
 # InputOtp
 
-> 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
 
@@ -50,6 +42,9 @@ A verification-code and short-PIN entry control. The user types into a hidden ab
 | `containerClassName` | `string` | `undefined` | no | Extra classes appended to `dsx-input-otp`. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-input-otp__hidden-input`. | no |
 | `maxLength` | `number` | `6` | no | Maximum number of characters. The OTP input enforces the cap. The runtime forwards this to `OTPInput`. | no |
+| `pattern` | `string` | `undefined` | no | Native input predicate, forwarded to `OTPInput` (e.g. `"^\d+$"` for a digits-only PIN; the `input-otp` v1 `REGEXP_ONLY_DIGITS` constant is this string). | no |
+| `aria-invalid` | `boolean` | `undefined` | no | Forwarded to the hidden input; slots paint the error border via `:has([aria-invalid='true'])`. | no |
+| `disabled` | `boolean` | `undefined` | no | Forwarded to the hidden input; slots take the shared disabled treatment from `_internal/baseInput.css`. | no |
 | (other `OTPInput` props) | n/a | n/a | no | All other `OTPInput` props (except `children`, `maxLength`, and `render`, which the runtime owns) are forwarded. | no |
 
 `InputOTPProps` is `Omit<BaseOTPInputProps, 'children' \| 'maxLength' \| 'render'> & InputOTPOwnProps & { children: React.ReactNode; maxLength?: number }`. The runtime requires `children` (a slot tree of groups and slots) and provides its own `render` strategy through the slot composition.
@@ -81,7 +76,8 @@ Rules:
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | (attribute written on root; no per-size CSS rule today) | `input-otp.css` |
+| `data-size` | `sm`, `md`, `lg` | Slot scale follows `:has([data-size])` rules (sm 0.8×, lg 1.15×). | `input-otp.css` |
+| `aria-invalid` | `true` (on the hidden input) | Slots paint `var(--dsx-color-error)` borders via `:has([aria-invalid='true'])`. | `input-otp.css` |
 | `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (attribute written on root; CSS reads `--dsx-radius-*` for the slot border-radius) | `input-otp.css` |
 | `data-active` | `true` | (attribute written on the active slot; CSS uses it to drive the focus border) | `input-otp.css` |
 | `data-filled` | `true` | (attribute written on filled slots) | `input-otp.css` |

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

@@ -3,20 +3,13 @@ title: Input
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/input/Input.tsx
-css_path: packages/d4gger-design-system/src/styles/components/input.css
-props_path: packages/d4gger-design-system/src/components/input/input.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Input.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:
   - Icon (consumer-supplied, optional)
 ---
 
 # Input
 
-> 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/{inset.md → components/inset.md}

@@ -3,20 +3,13 @@ title: Inset
 status: canonical
 category: Foundations
 archetype: layout-primitive
-package_path: packages/d4gger-design-system/src/layout/Inset.tsx
-css_path: packages/d4gger-design-system/src/styles/components/inset.css
-props_path: packages/d4gger-design-system/src/layout/inset.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Inset.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
 ---
 
 # Inset
 
-> 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