@d4gger/design-system 2.7.0 → 3.0.0

package/dist/docs/{qr-code.md → components/qr-code.md}

@@ -3,18 +3,13 @@ title: QRCode
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/qrCode/QrCode.tsx
-css_path: packages/d4gger-design-system/src/styles/components/qr-code.css
-props_path: packages/d4gger-design-system/src/components/qrCode/qrCode.props.ts
-test_path: packages/d4gger-design-system/src/test/components/QRCode.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - qrcode.react
 ---
 
 # QRCode
 
-> 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
 
@@ -185,7 +180,7 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 - `qrcode.react` `QRCodeSVG`: adapter that renders the SVG QR matrix. The adapter is a `peerDependency`; the package does not own the rendered modules.
 - `@radix-ui/react-slot`: enables `asChild` for consumer-supplied host elements.
-- No DS component composition. The runtime does not import any DS primitives; the surface is a self-contained adapter-backed primitive (the roster labels it `primitive`, but the source is adapter-backed; see Anomalies).
+- No DS component composition. The runtime does not import any DS primitives; the surface is a self-contained adapter-backed primitive, matching the roster archetype.
 
 **Used by:**
 

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

@@ -3,17 +3,12 @@ title: Quote
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/quote/Quote.tsx
-css_path: packages/d4gger-design-system/src/styles/components/quote.css
-props_path: packages/d4gger-design-system/src/components/quote/quote.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Quote.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on: []
 ---
 
 # Quote
 
-> 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
 
@@ -113,7 +108,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.
+`Quote` is registered in `apps/playground/lib/registry/typography.tsx` under the `quote` key. The registry entry imports `quotePropDefs` and renders the component with a sample inline quotation. Per-component route: `/docs/quote`.
 
 **Default story:**
 
@@ -129,7 +124,7 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the italic style is visually unchanged because Quote does not consume `data-accent-color`.
+- Renders inside a `Theme` wrapper with `accentColor="rift"`, `accentColor="warp"`, and `accentColor="ray"`. Asserts the italic style is visually unchanged because Quote does not consume `data-accent-color`.
 
 **A11y story:**
 

package/dist/docs/{radio-cards.md → components/radio-cards.md}

@@ -3,11 +3,6 @@ title: RadioCards
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/radioCards/RadioCards.tsx
-css_path: packages/d4gger-design-system/src/styles/components/radio-cards.css
-props_path: packages/d4gger-design-system/src/components/radioCards/radioCards.props.ts
-test_path: packages/d4gger-design-system/src/test/components/RadioCards.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - RadioGroup (Radix `@radix-ui/react-radio-group`; the `Root` wraps `RadioGroupPrimitive.Root` and the `Item` wraps `RadioGroupPrimitive.Item`, the `data-state='checked'` attribute is the source of the visual selected state)
   - Card (token-aligned surface; the `Item` reuses the `dsx-card` surface tokens through the `baseCard.css` import)
@@ -16,7 +11,7 @@ depends_on:
 
 # RadioCards
 
-> 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/{radio-group.md → components/radio-group.md}

@@ -3,20 +3,13 @@ title: RadioGroup
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/radioGroup/RadioGroup.tsx
-css_path: packages/d4gger-design-system/src/styles/components/radio-group.css
-props_path: packages/d4gger-design-system/src/components/radioGroup/radioGroup.props.ts
-test_path: packages/d4gger-design-system/src/test/components/RadioGroup.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:
   - "@radix-ui/react-radio-group"
 ---
 
 # RadioGroup
 
-> 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/{rating.md → components/rating.md}

@@ -3,20 +3,13 @@ title: Rating
 status: canonical
 category: Components
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/rating/Rating.tsx
-css_path: packages/d4gger-design-system/src/styles/components/rating.css
-props_path: packages/d4gger-design-system/src/components/rating/rating.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Rating.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
 ---
 
 # Rating
 
-> 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/{resizable.md → components/resizable.md}

@@ -3,20 +3,13 @@ title: Resizable
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/resizable/Resizable.tsx
-css_path: packages/d4gger-design-system/src/styles/components/resizable.css
-props_path: packages/d4gger-design-system/src/components/resizable/resizable.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Resizable.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:
   - react-resizable-panels
 ---
 
 # Resizable
 
-> 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/{result.md → components/result.md}

@@ -3,8 +3,6 @@ title: Result
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/result/Result.tsx
-css_path: packages/d4gger-design-system/src/styles/components/result.css
 ---
 
 # Result

package/dist/docs/{rich-text-editor.md → components/rich-text-editor.md}

@@ -3,13 +3,6 @@ title: RichTextEditor
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/richTextEditor/RichTextEditor.tsx
-css_path: packages/d4gger-design-system/src/styles/components/rich-text-editor.css
-props_path: packages/d4gger-design-system/src/components/richTextEditor/richTextEditor.props.ts
-test_path: packages/d4gger-design-system/src/test/components/RichTextEditor.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:
   - "@tiptap/react"
   - "@tiptap/starter-kit"
@@ -27,7 +20,7 @@ Import the editor and its composition helper from `@d4gger/design-system/rich-te
 
 Stable attributes are: image `src`, `alt`, optional `caption`; embed canonical `url`; callout `tone`, optional `title`, nested content; code language/content; comparison before/after sources, alt text, optional labels; poll persistent ID and display metadata. Embed HTML never accepts raw iframes. Applications own URL allowlists/oEmbed callbacks, uploads, polling/voting, authentication, storage, and sanitization. Matching read-side exports are `ArticleImage`, `ArticleEmbed`, `BeforeAfterComparison`, and `ArticlePoll`.
 
-> 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/{scroll-area.md → components/scroll-area.md}

@@ -3,13 +3,6 @@ title: ScrollArea
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/scrollArea/ScrollArea.tsx
-css_path: packages/d4gger-design-system/src/styles/components/scroll-area.css
-props_path: packages/d4gger-design-system/src/components/scrollArea/scrollArea.props.ts
-test_path: packages/d4gger-design-system/src/test/components/ScrollArea.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:
   - "@radix-ui/react-scroll-area"
   - "@radix-ui/react-slot"
@@ -17,7 +10,7 @@ depends_on:
 
 # ScrollArea
 
-> 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/{search-bar.md → components/search-bar.md}

@@ -3,13 +3,6 @@ title: SearchBar
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/searchBar/SearchBar.tsx
-css_path: packages/d4gger-design-system/src/styles/components/search-bar.css
-props_path: packages/d4gger-design-system/src/components/searchBar/searchBar.props.ts
-test_path: packages/d4gger-design-system/src/test/components/SearchBar.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:
   - Command (the `SearchBar.Menu` slot renders through the DS `Command` surface for the search-first list and keyboard navigation)
   - Dialog (the `SearchBar.Menu` slot mounts a `Dialog` for the modal palette; the trigger button opens the dialog)
@@ -21,7 +14,7 @@ depends_on:
 
 # SearchBar
 
-> 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
 
@@ -46,9 +39,9 @@ A global search trigger with a command-palette-style results menu. The trigger b
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
-| `variant` | `'default' \| 'ghost'` | `'default'` | no | Trigger style. Writes `data-variant`. The CSS does not currently declare per-variant rules; the attribute is the contract hook. | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Trigger height. Writes `data-size`. The CSS does not currently declare per-size rules; the attribute is the contract hook. | no |
-| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Trigger corner roundness. Writes `data-radius`. | no |
+| `variant` | `'default' \| 'ghost'` | `'default'` | no | Trigger style. Writes `data-variant` on the root and maps onto the trigger `Button` (`default` → `outline`, `ghost` → `ghost`); the paint comes from the Button contract, so `search-bar.css` declares no per-variant rules of its own. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Trigger height. Writes `data-size` on the root and flows into the trigger `Button` `size`; the paint comes from the Button contract. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Trigger corner roundness. Writes `data-radius` on the root and flows into the trigger `Button` `radius`; the paint comes from the Button contract. | no |
 | `compact` | `boolean` | `false` | no | Reduces the container gap. Adds the `dsx-search-bar--compact` modifier class. | no |
 | `openOnShortcut` | `boolean` | `true` | no | When set, the root listens for `Cmd/Ctrl + K` on `window` and toggles the menu. The listener is registered in a `useEffect` and removed on unmount. | no |
 | `defaultOpen` | `boolean` | `false` | no | Initial open state when uncontrolled. | no |
@@ -80,6 +73,7 @@ Rules:
 | `showClose` | `boolean` | `false` | no | Toggles the dialog's close button. | no |
 | `size` | `DialogSize` (the `Dialog` size union) | `'md'` | no | Dialog size. | no |
 | `title` | `string` | `'Search'` | no | Accessible dialog title, rendered via a `VisuallyHidden`-wrapped `DialogTitle`. Fixes the Radix a11y requirement that every `DialogContent` have a `DialogTitle`. | no |
+| `description` | `string` | `undefined` | no | Optional accessible dialog description, rendered via a `VisuallyHidden`-wrapped `DialogDescription` when set. Quiets the Radix missing-`Description` warning for consumers that need a described palette. | no |
 | (Command props) | n/a | n/a | no | All standard `Command` props are forwarded. | no |
 
 `SearchBarMenuProps` is `CommandProps & SearchBarMenuOwnProps`.

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

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

package/dist/docs/components/segmented-control.md

@@ -0,0 +1,253 @@
+---
+title: SegmentedControl
+status: canonical
+category: Components
+archetype: composite
+depends_on:
+  - ToggleGroup
+---
+
+# SegmentedControl
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+A single-select control that renders a row of mutually exclusive options, backed by `ToggleGroup` from Radix. `default` is a sunken track with a sliding softly tinted raised pill behind the active option; `outline` is the same pill inside an outer frame; `subtle` is the borderless treatment with the same selected pill. Used for switching between views, filters, or modes in forms and toolbars.
+
+## Anatomy & slots
+
+**Parent:** `SegmentedControl` (alias of `SegmentedControl.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `SegmentedControl.Root` | `ToggleGroupPrimitive.Root` | Radix ToggleGroup root + class | Single-select container. Writes `data-size`, `data-variant`, `data-activation-mode`, `data-disabled`. Renders the selected indicator pill as its last child. |
+| `SegmentedControl.Item` | `ToggleGroupPrimitive.Item` | Radix ToggleGroup item + class | Individual option. Writes `data-state` (`on`/`off`), `data-disabled`, and opt-in `data-icon-only`. Accepts composed rich content with `space-xs` rhythm. |
+| Indicator | `span.dsx-segmented-control__indicator` | Measured wrapper for the raised pill behind the active item | `aria-hidden="true"`. Positioned by inline `transform: translateX()` + `width` from the root measure pass; its `::before` paint layer is inset by `space-2xs` on every side so edge selections clear the track frame. Not a public slot. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and item padding; writes `data-size` and `dsx-segmented-control--{size}` class. | no |
+| `variant` | `'default' \| 'outline' \| 'subtle'` | `'default'` | no | Container surface treatment; writes `data-variant` and `dsx-segmented-control--{variant}` class. `subtle` keeps the measured selected pill but removes the track surface and frame. | no |
+| `activationMode` | `'manual' \| 'automatic'` | `'manual'` | no | Selection timing; writes `data-activation-mode`. `manual` selects only on activation (click, `Enter`, `Space`). `automatic` selects on item focus, so arrow-key navigation selects without `Enter`. | no |
+| `disabled` | `boolean` | `false` | no | Disables the entire control; writes `data-disabled`. | no |
+| `value` | `string` | `undefined` | no | Controlled selected value. | no |
+| `defaultValue` | `string` | `undefined` | no | Uncontrolled initial selected value. | no |
+| `onValueChange` | `(value: string) => void` | `undefined` | no | Callback when the selected value changes. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-segmented-control`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | `SegmentedControl.Item` children. | no |
+
+**SegmentedControl.Item props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `string` | — | yes | Unique value for this item. | no |
+| `iconOnly` | `boolean` | `false` | no | Declares an icon-only item and gives it a square hit target. Requires an accessible name. | no |
+| `disabled` | `boolean` | `undefined` | no | Disables this item. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-segmented-control__item`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Item label content. Accepts composed rich content (icon, status dot, count badge, tag); items lay children out with `gap: var(--dsx-space-xs)` and icons never shrink. | no |
+
+Rules:
+
+- `size` and `disabled` are wired through `extractProps` and the prop def bag on the Root. `variant` and `activationMode` are destructured with their defaults and kept out of the extract bag (their defs declare no `className`, so they would otherwise leak onto the DOM).
+- `value`, `defaultValue`, and `onValueChange` are passed through to the Radix ToggleGroup root directly.
+- The Root forces `type="single"` and filters empty string values from `onValueChange` to prevent deselection.
+- Deselect guard: the Root owns the selection state. Uncontrolled usage seeds internal state from `defaultValue` and passes the resolved value back into Radix as a controlled `value`, so clicking the active item (which fires `""`) can never clear Radix internal state or render the control with no active item. Controlled usage passes `value` straight through; `""` is still swallowed.
+- Activation mode: in `automatic` mode each item's `onFocus` selects its own value when it differs from the current value (the item reads the mode and the current selection from an internal Root context; Radix strips the `value` prop from the DOM, so the Root cannot recover the focused value from the event target). The focus value goes through the same guarded setter, so focus can never empty the selection and tabbing into the group (which lands on the already-selected item) is a no-op. Disabled items never select on focus. In `manual` mode (default) focus never selects; selection happens only on activation. Consumer `onFocus` handlers on the Root and on items keep working in both modes.
+- Choosing a mode: `automatic` is the radio-faithful choice for lightweight view/filter/mode switching. `manual` is required when `onValueChange` drives expensive side effects (network requests, navigation, heavy recompute) that must not fire on focus or hover.
+- Indicator geometry: the Root measures the active `[data-state="on"]` item with `getBoundingClientRect` in a layout effect (before first paint), re-measures on selection change and via `ResizeObserver` on the root and the active item. The offset is a physical-pixel diff (`active.left - root.left`), which is direction-agnostic and therefore RTL-correct without special-casing. A ready gate holds `transition: none` until the first positioned frame so mount never animates from the origin. Variable-width items are required; the indicator wrapper tracks each item's own width (no equal-width `nth-child` CSS), while its painted `::before` surface keeps a symmetric `space-2xs` inset inside that measured wrapper.
+
+## CSS class contract
+
+**Root class:** `dsx-segmented-control`
+
+**Modifier classes** (driven by `data-*` attributes and class names written by the component):
+
+| Attribute / Class | Allowed values | CSS selector | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-segmented-control--sm`, `.dsx-segmented-control--md`, `.dsx-segmented-control--lg` | `segmented-control.css` |
+| `data-variant` | `default`, `outline`, `subtle` | `.dsx-segmented-control--default`, `.dsx-segmented-control--outline`, `.dsx-segmented-control--subtle` | `segmented-control.css` |
+| `data-disabled` | (present/absent) | `.dsx-segmented-control[data-disabled]` | `segmented-control.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `SegmentedControl.Root` | `dsx-segmented-control` | `segmented-control.css` |
+| `SegmentedControl.Item` | `dsx-segmented-control__item` | `segmented-control.css` |
+| Indicator | `dsx-segmented-control__indicator` | `segmented-control.css` |
+
+**Selector note:**
+
+- Every item uses the same inset-corrected pill radius as the selected indicator, so hover and keyboard focus trace the same shape at every position.
+
+**Responsive behavior:**
+
+- The component does not write viewport `@media` rules. Size and variant are single-value only.
+- The component writes one `@media (prefers-reduced-motion: reduce)` rule that sets the indicator transition to `none`.
+
+**Reduced motion:**
+
+- The indicator pill animates `transform` and `width` with `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`, gated by an explicit `@media (prefers-reduced-motion: reduce) { transition: none }` rule.
+- Item transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)` for background-color and color; the token values collapse to `0` under the global reduced-motion override. Focus ring paint is intentionally immediate and never interpolated.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Container background | `var(--dsx-color-surface-sunken)` | Sunken well; the track recedes, the pill comes forward |
+| Container border | `var(--dsx-boundary-control-width)` with a transparent color, except `outline` which paints `var(--dsx-boundary-control-color)` | Geometry preserved everywhere; only `outline` paints an outer frame |
+| Container radius | `var(--dsx-grouped-radius, var(--dsx-rounded-md))` | Container roundness |
+| Outline dividers | none | Dividers removed: they clipped against the frame and broke rhythm around selection; `outline` is frame-only |
+| Item text color | `var(--dsx-color-on-surface-variant)` | Unselected item label |
+| Item selected background | `transparent` (surface moved to the indicator pill) | Selected item keeps the label color only |
+| Item selected text | `var(--dsx-color-accent-indicator)` | Readable accent text on the pale pill — a raw accent-9 fails contrast on bright accents (spark); indicator is the ramp step designed for text on tints |
+| Indicator surface | `linear-gradient(var(--dsx-effect-pressed-layer), var(--dsx-effect-pressed-layer)), var(--dsx-control-active-background)` | Theme-aware raised surface with a soft accent wash; visibly selected without becoming a solid accent button |
+| Indicator shadow | `var(--dsx-effect-shadow-2)` | Clear pill elevation in light and dark themes; no selected outline, so the focus ring remains unambiguous |
+| Indicator radius | `max(0px, calc(grouped - space-2xs))` | Inset-corrected roundness so the pill never crosses the track corners |
+| Indicator inset | `var(--dsx-space-2xs)` on every side | Symmetric clearance between the selected paint and the track or outline frame |
+| Item hover | `var(--dsx-effect-hover-ghost)` + `var(--dsx-color-primary)` | Pointer-local transient state on an unselected item |
+| Icon-only rhythm | matching density control height via `data-icon-only` | Explicit square hit target at every size |
+| Subtle container | `transparent` (background, border, shadow all cleared) | Borderless track; segments float on the parent surface |
+| Subtle selected fill | Same theme-aware softly tinted indicator surface as the other variants | Keeps selection visible on a transparent track, including icon-only composition |
+| Subtle selected text | `var(--dsx-color-accent-indicator)` | Same readable-accent rule as the pill variants |
+| Item gap | `var(--dsx-space-xs)` | Rhythm between composed children (icon, dot, badge, tag) |
+| Focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator |
+| Disabled opacity | `var(--dsx-opacity-disabled)` | Disabled fade |
+| Item padding (sm) | `var(--dsx-space-sm)` | Small item horizontal padding |
+| Item padding (md) | `var(--dsx-space-md)` | Default item horizontal padding |
+| Item padding (lg) | `var(--dsx-space-lg)` | Large item horizontal padding |
+| Height (sm) | `var(--dsx-density-control-height-sm, var(--dsx-size-lg))` | Small control height |
+| Height (md) | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Default control height |
+| Height (lg) | `var(--dsx-density-control-height-lg, var(--dsx-size-2xl))` | Large control height |
+| Typography | `var(--dsx-typography-label-large-*)`, `var(--dsx-typography-label-small-*)` | Item label type ramp |
+| Transition duration | `var(--dsx-motion-duration-fast, 150ms)` | Item transition speed |
+| Transition easing | `var(--dsx-motion-easing-standard, ease)` | Item transition curve |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Indicator pill slide/resize | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` on `transform, width` | `150ms` ease | `transition: none` via `@media (prefers-reduced-motion: reduce)` |
+| Item background/color transition | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | `150ms` ease | Global `prefers-reduced-motion` override via token layer; focus ring paint is immediate |
+
+## Accessibility
+
+**Roles:**
+
+- `group` (Radix ToggleGroup root). Each item is a `radio` role within the group.
+
+**Keyboard:**
+
+Manual mode (`activationMode="manual"`, default):
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to / from the control. |
+| `Arrow Left`, `Arrow Right` | Moves focus between items; selection is unchanged. |
+| `Space`, `Enter` | Selects the focused item. |
+
+Automatic mode (`activationMode="automatic"`):
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to / from the control. Tabbing in lands on the selected item, so selection is unchanged. |
+| `Arrow Left`, `Arrow Right` | Moves focus between items and selects the newly focused item. `Enter` is unnecessary. |
+| `Space`, `Enter` | No-op on the already-selected item (re-activation is swallowed by the deselect guard). |
+
+**Focus:**
+
+- Keyboard focus uses `box-shadow: var(--dsx-shadow-focus-ring)` on the focused item through `:focus-visible`, so pointer clicks do not add a focus ring.
+- Pointer hover is local to the hovered unselected item and never moves or duplicates the selected pill.
+- Selection and focus remain separate signals: the indicator owns fill and elevation, while the item owns the focus ring. SegmentedControl is the explicit exception to the general selected-boundary rule in `DESIGN.md`.
+
+**Reduced motion:**
+
+- The indicator pill disables its slide/resize transition under `prefers-reduced-motion` via an explicit CSS gate.
+- Item transitions collapse when the global reduced-motion token override sets durations to `0`.
+
+**Decorative nodes:**
+
+- The indicator pill is `aria-hidden="true"` and pointer-transparent; it carries no semantics and never intercepts input.
+
+**Color and meaning:**
+
+- Selected state is communicated by elevation + fill + text color, not by color alone. Focus is communicated by the shared focus ring and is the only outline on a segment.
+
+**Naming:**
+
+- The Root requires an `aria-label` or `aria-labelledby` to name the group.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `SegmentedControl` with three items and `defaultValue="day"`. Asserts the root class is `dsx-segmented-control`, `data-size="md"`, and `data-variant="default"`. The indicator pill renders behind the selected item in every story that sets a value; no fixture change was needed.
+
+**Size story:**
+
+- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute and `dsx-segmented-control--{size}` class.
+
+**Variant story:**
+
+- Renders with `variant="default"`, `variant="outline"`, and `variant="subtle"`. Asserts the matching `data-variant` attribute and `dsx-segmented-control--{variant}` class. In `subtle`, the container is transparent and borderless while the measured raised pill remains the selected signal.
+
+**Subtle composition story:**
+
+- Renders `variant="subtle"` rows: explicit `iconOnly` appearance controls, icon + label + status dot (views), counts (tasks with badges), and an affixed tag (billing with promo). The selected segment uses the same measured fill/elevation indicator as the other variants. Hover stays local to the pointed item and focus uses `:focus-visible`.
+
+**State story:**
+
+- Renders with `disabled={true}`. Asserts `data-disabled` is present and items are not interactive.
+
+**Activation-mode story:**
+
+- Renders Manual (`activationMode="manual"`, the default) and Automatic (`activationMode="automatic"`) side by side with the same Day/Week/Month values. In manual, arrows move focus without selecting; `Enter` selects. In automatic, arrows select without `Enter`. Asserts the root writes the matching `data-activation-mode`.
+
+**Composition story:**
+
+- Renders with each `SegmentedControl.Item` populated. Asserts each item renders with `dsx-segmented-control__item` class and the selected item has `data-state="on"`.
+
+**Token story:**
+
+- Renders inside `Theme` wrappers with alternate accents. SegmentedControl inherits the ambient accent: selected label, focus ring, and soft indicator wash follow it without requiring a component-level accent prop.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default control. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `variant` | select | `default` |
+| `activationMode` | select | `manual` |
+| `disabled` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-toggle-group`: provides the single-select toggle group semantics and keyboard navigation.
+
+**Used by:**
+
+- `ThemePanel`: theme configuration panel uses SegmentedControl for density and mode switching.
+- `ConfigDrawer`: app-config drawer uses SegmentedControl for setting groups.
+
+**State boundaries:**
+
+- Owned by SegmentedControl: the selected value, the `data-size`, `data-variant`, `data-activation-mode`, `data-disabled` attributes, the CSS classes, and the indicator pill geometry (measured offsets, never consumer-provided).
+- Owned by the consumer: the item values, the item labels, the controlled/uncontrolled value, and the `onValueChange` callback.
+
+**Boundary rules:**
+
+- App-owned data: the item values and labels, the selection state semantics.
+- DS-owned visuals: token bindings, slot classes, motion presets, and the container/item layout.

package/dist/docs/{segmented-meter.md → components/segmented-meter.md}

@@ -3,19 +3,12 @@ title: SegmentedMeter
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/segmentedMeter/SegmentedMeter.tsx
-css_path: packages/d4gger-design-system/src/styles/components/segmented-meter.css
-props_path: packages/d4gger-design-system/src/components/segmentedMeter/segmentedMeter.props.ts
-test_path: packages/d4gger-design-system/src/test/components/SegmentedMeter.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: []
 ---
 
 # SegmentedMeter
 
-> 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