@d4gger/design-system 2.7.0 → 3.0.0

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

@@ -3,13 +3,6 @@ title: Command
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/command/Command.tsx
-css_path: packages/d4gger-design-system/src/styles/components/command.css
-props_path: packages/d4gger-design-system/src/components/command/command.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Command.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:
   - Input
   - Dialog
@@ -18,7 +11,7 @@ depends_on:
 
 # Command
 
-> 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
 
@@ -61,6 +54,8 @@ A search-and-act command palette, cmdk-backed, that lets the user type to filter
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `shortcut` | `string \| false` | `'meta+k'` | no | Global keyboard shortcut. Pass `false` to disable the listener. | no |
+| `title` | `string` | `'Command menu'` | no | Accessible dialog title, rendered via a `VisuallyHidden`-wrapped `DialogTitle`. Same V-1 class of fix as `SearchBar` (2026-07-03): previously no title path existed at all, so every open palette failed the Radix `DialogContent requires a DialogTitle` requirement. | no |
+| `description` | `string` | `undefined` | no | Optional accessible dialog description, rendered via a `VisuallyHidden`-wrapped `DialogDescription` when set. | no |
 | `open` | `boolean` | `undefined` | no | Controlled open state. | no |
 | `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Fires on every open transition. | no |
 | `children` | `React.ReactNode` | `undefined` | no | Slot content. | no |
@@ -158,7 +153,7 @@ Rules:
 
 | Property | Token | Role |
 |---|---|---|
-| Root background | `var(--dsx-color-surface-overlay)` | Palette surface. |
+| Root background | `var(--dsx-color-panel-translucent)` | Palette surface. |
 | Root border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Edge. |
 | Root border radius | `var(--dsx-rounded-lg)` | Rounded corners (aligned to the dropdown-menu/context-menu/menubar panel recipe). |
 | Root shadow | `var(--dsx-shadow-elevation-3)` | Depth (aligned to the shared popup-family elevation). |
@@ -348,7 +343,7 @@ The palette has no mount or exit motion. Item selection and hover animate throug
 
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
-| `<Root Board>` | fill | `var(--dsx-color-surface-overlay)` | Color | `fills` |
+| `<Root Board>` | fill | `var(--dsx-color-panel-translucent)` | Color | `fills` |
 | `<Root Board>` | radius | `var(--dsx-rounded-md)` | Radius | `borderRadius` |
 | `<Root Board>` | shadow | `var(--dsx-shadow-elevation-2)` | Shadow | `effects` |
 | `<Input field>` | typography | `var(--dsx-typography-body-medium-*)` | Typography | `typography` |

package/dist/docs/{comment-thread.md → components/comment-thread.md}

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

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

@@ -3,13 +3,6 @@ title: ConfigDrawer
 status: canonical
 category: Foundations
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/configDrawer/ConfigDrawer.tsx
-css_path: packages/d4gger-design-system/src/styles/components/config-drawer.css
-props_path: packages/d4gger-design-system/src/components/configDrawer/configDrawer.props.ts
-test_path: packages/d4gger-design-system/src/test/components/ConfigDrawer.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:
   - Sheet
   - IconButton
@@ -25,7 +18,7 @@ depends_on:
 
 # ConfigDrawer
 
-> 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
 
@@ -45,13 +38,14 @@ A right-anchored preferences drawer that exposes the live theme controls: appear
 | SettingRow | `Flex direction="row" justify="between" align="center" gap="md"` | `dsx-config-drawer__row` | A label / description / control triplet. The label is a `Label` element; the description (when present) is a `Text variant="label-small" tone="muted"`; the control is whatever the consumer passes as `children`. |
 | SettingRow info | `Flex direction="column" gap="1"` | `dsx-config-drawer__row-info` | The left column of the row, containing the `Label` and the description. |
 | SettingRow control wrapper | `<div>` | `dsx-config-drawer__row-control` | The right column of the row, wrapping the control. |
+| Accent preview swatch | `<span aria-hidden="true">` | `dsx-config-drawer__accent-swatch` + `data-tier` | Non-interactive preview of each accent tier. It does not write `data-accent-color`, because the swatch represents a color value rather than consuming theme scope. |
 | Scaling input (specific) | `NumberInput` | `dsx-config-drawer__scaling-input` | The scaling control. Sized to `7ch` so the percentage fits without breaking the row rhythm. |
 
 **Internal layout:**
 
 - The default trigger is a ghost `IconButton` with a `settings` icon. Passing the `trigger` prop replaces it entirely.
 - The body is a single scrollable column. Each `SettingRow` is a `flex-direction: row` with `justify-content: space-between`, so the label and control sit on opposite ends of the row.
-- The seven default rows (Theme, Accent, Gray, Radius, Density, Scaling) are separated by `Separator` components from the package. The order is fixed and reflects the dependency direction: appearance first, then accent, then gray, then radius, then density, then scaling.
+- The six default rows (Theme, Accent, Gray, Radius, Density, Scaling) are separated by `Separator` components from the package. The order is fixed and reflects the dependency direction: appearance first, then accent, then gray, then radius, then density, then scaling.
 - Each row's control is a `SegmentedControl` (for the categorical tokens) or a `NumberInput` (for the scaling percentage). The control is wrapped in a `<div class="dsx-config-drawer__row-control">` so it stays right-aligned without leaking the `gap` into the control itself.
 
 ## Props contract
@@ -75,7 +69,7 @@ The root does not accept `asChild` directly; consumers can swap the host element
 | `description` | `string` | `undefined` | no | Optional helper text rendered under the label as a muted `Text`. | no |
 | `children` | `ReactNode` | (none) | **yes** | The control rendered on the right (typically a `SegmentedControl` or `NumberInput`). | no |
 
-`SettingRow` is an internal helper; consumers do not compose their own rows. The seven default rows are wired inside the component.
+`SettingRow` is an internal helper; consumers do not compose their own rows. The six default rows are wired inside the component.
 
 ## CSS class contract
 
@@ -90,6 +84,7 @@ The root does not accept `asChild` directly; consumers can swap the host element
 | Setting row | `dsx-config-drawer__row` | `config-drawer.css` |
 | Setting row info column | `dsx-config-drawer__row-info` | `config-drawer.css` |
 | Setting row control wrapper | `dsx-config-drawer__row-control` | `config-drawer.css` |
+| Accent preview swatch | `dsx-config-drawer__accent-swatch` | `config-drawer.css` |
 | Scaling `NumberInput` | `dsx-config-drawer__scaling-input` | `config-drawer.css` |
 
 **Responsive behavior:**
@@ -112,6 +107,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Row min-height | `var(--dsx-size-lg)` | Min hit target |
 | Row gap | `var(--dsx-space-md)` | Horizontal gap between info and control |
 | Row info gap | `var(--dsx-space-2xs)` | Vertical gap inside the info column |
+| Accent preview size | `var(--dsx-space-sm)` | Square preview swatch dimensions |
+| Accent preview spacing | `var(--dsx-space-xs)` | Gap between the preview and tier label |
+| Accent preview radius | `var(--dsx-radius-full)` | Circular preview shape |
+| Accent preview fill | `var(--dsx-runtime-accent-{rift,warp,ray}-9)` | Exact value represented by each theme choice |
 | Scaling input width | `7ch` | Fixed width for the percentage `NumberInput` |
 
 The default trigger is an `IconButton`; its visual contract is owned by `IconButton`. The row labels use the `Label` component; their visual contract is owned by `Label`. The segmented controls use the `SegmentedControl` component; their visual contract is owned by `SegmentedControl`.
@@ -171,17 +170,17 @@ The component itself has no motion. The wrapping `Sheet` handles open / close tr
 
 **State story:**
 
-- Renders the drawer with `defaultOpen` and confirms the seven rows appear with the correct default selections (`System`, `Amber`, `Auto`, `Medium`, `Comfortable`, `100`).
+- Renders the drawer with `defaultOpen` and confirms the six rows appear with the correct default selections (`System`, `Rift`, `Auto`, `Medium`, `Comfortable`, `100`).
 - Renders the drawer with `open` (controlled) and confirms the same.
 - Renders a custom `trigger` and confirms the custom trigger is rendered when the drawer is closed.
 
 **Composition story:**
 
-- The component owns its own composition. The composition story is the default render: header + seven rows + separators.
+- The component owns its own composition. The composition story is the default render: header + six rows + separators.
 
 **Token story:**
 
-- Renders the default drawer inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the active segmented option tracks `--dsx-color-primary` and is not affected by the accent token.
+- Renders the default drawer inside a `Theme` wrapper with `accentColor="warp"` and `accentColor="ray"`. Asserts the active segmented option tracks `--dsx-color-primary` while each accent preview continues to show the exact tier it represents.
 
 **A11y story:**
 
@@ -213,7 +212,7 @@ The playground registry for `config-drawer` does not expose prop controls. The c
 
 **State boundaries:**
 
-- Owned by ConfigDrawer: the seven default rows, their order, and the `SettingRow` layout.
+- Owned by ConfigDrawer: the six default rows, their order, the accent previews, and the `SettingRow` layout.
 - Owned by the consumer: the placement of the drawer, the custom `trigger` (if any), the controlled `open` / `onOpenChange` (if any), and the surrounding `ThemeProvider`.
 - Owned by `useTheme()`: every categorical selection (`theme`, `accentColor`, `grayColor`, `radius`, `density`, `scaling`) is read from and written to the active `ThemeProvider` context. The drawer does not own the value; it surfaces the control.
 

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

@@ -3,13 +3,6 @@ title: Container
 status: canonical
 category: Foundations
 archetype: layout-primitive
-package_path: packages/d4gger-design-system/src/components/container/Container.tsx
-css_path: packages/d4gger-design-system/src/styles/components/container.css
-props_path: packages/d4gger-design-system/src/components/container/container.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Container.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
@@ -17,7 +10,7 @@ depends_on:
 
 # Container
 
-> 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
 
@@ -113,7 +106,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Max width | `var(--dsx-container-max-width, 1080px)` | Resolved from `size` |
 | Margin | `auto` | CSS keyword |
 | Padding inline | `var(--dsx-container-inset, var(--dsx-space-margin))` | Resolved from `inset` |
-| Display | `var(--dsx-box-display, flex)` | Inherited from `dsx-flex` |
+| Display | `var(--dsx-box-display, flex)` | Conditional: only applies when the `dsx-flex` class is written (a flex layout prop is set); otherwise the host keeps the CSS `block` default |
 | Gap | `var(--dsx-box-gap, 0)` | Inherited from `dsx-flex` |
 | Size ramp | `1`→`420px`, `2`→`640px`, `3`→`768px`, `4`→`1024px`, `content`→`1080px`, `wide`→`1200px`, `full`→`none` | `size` value resolution |
 | Inset ramp | `var(--dsx-space-{xs,sm,md,lg,xl,2xl,3xl,gutter,margin})` | `inset` value resolution (via `SpaceToken`) |
@@ -162,7 +155,7 @@ Container has no motion. The motion section is intentionally empty.
 
 **Default story:**
 
-- Renders `Container` with no extra props and a child node. Asserts the root classes are `dsx-container`, `dsx-flex`, and `dsx-box`, the host element is a `div`, and `--dsx-container-max-width` resolves to `1080px`.
+- Renders `Container` with no extra props and a child node. Asserts the root classes are `dsx-container` and `dsx-box` (the `dsx-flex` class is conditional — it is only written when a flex layout prop such as `direction`, `align`, `justify`, `gap`, or `wrap` is set), the host element is a `div`, and `--dsx-container-max-width` resolves to `1080px`.
 
 **Size story:**
 

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

@@ -3,26 +3,16 @@ title: ContextMenu
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/contextMenu/ContextMenu.tsx
-css_path: packages/d4gger-design-system/src/styles/components/context-menu.css
-props_path: packages/d4gger-design-system/src/components/contextMenu/contextMenu.props.ts
-test_path: packages/d4gger-design-system/src/test/components/ContextMenu.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-context-menu (the underlying Radix primitive; `ContextMenu.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 ContextMenu 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)
 ---
 
 # ContextMenu
 
-> 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
 
@@ -166,7 +156,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token. The `context-men
 | 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. |

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

@@ -0,0 +1,261 @@
+---
+title: ControlGroup
+status: canonical
+category: Components
+archetype: composite
+depends_on:
+  - Select
+  - ToggleGroup
+  - SegmentedControl
+  - Button
+  - Separator
+---
+
+# ControlGroup
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+Visually groups two or more *unlike* interactive controls (a `Select` next to a `ToggleGroup`, a
+`Button` next to a `SegmentedControl`, etc.) inside one shared bordered frame, so they read as one
+settings cluster instead of separate floating widgets.
+
+## Anatomy & slots
+
+**Parent:** `ControlGroup` (flat export — no compound sub-components).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `ControlGroup` (Root) | `<div>` | Flex container, `role="group"` | Holds any number of DS control children directly — no wrapper slot components. |
+
+No named child slots: unlike `InputGroup` (which wraps its children in `InputGroup.Addon` /
+`InputGroup.Text` / `InputGroup.Button` for input-specific semantics), `ControlGroup`'s children
+are consumed as-is. This is the deliberate distinction from `InputGroup` — see Wiring notes.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Controls the group's height and inner item padding. | no |
+| `radius` | `'md' \| 'full'` | `'full'` | no | Outer corner radius of the group frame and of the first/last child's outer corners. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root as its child via Radix `Slot` instead of a `div`. | no |
+
+Rules:
+
+- Every prop in this table must exist in `controlGroup.props.ts`. The runtime prop def is the source.
+- Every prop in `controlGroup.props.ts` must be in this table. Mismatches fail `qa:contracts`.
+- No `Responsive` column values are `yes` — this component does not vary by breakpoint.
+
+## CSS class contract
+
+**Root class:** `dsx-control-group`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-control-group[data-size="sm"]` | `control-group.css` |
+| `data-group-radius` | `md`, `full` | `.dsx-control-group[data-group-radius="md"]`, `.dsx-control-group[data-group-radius="full"]` | `control-group.css` |
+
+**Not `data-radius`, deliberately (2026-08-26, real bug found live):** `data-radius` is a
+reserved document-theme attribute — `PortalThemeBoundary`'s `getClosestThemeAttribute(el,
+'data-radius')` walks up the nearest ancestor carrying that attribute to mirror the app's global
+radius setting into portaled content (`Select`/`Dialog`/`Popover`/etc). A component that emits
+its own local `data-radius` between a portal trigger and `<html>` gets picked up *instead of* the
+real document-level value. Confirmed live: a `Select` inside a `ControlGroup radius="full"` frame
+opened its dropdown at `9999px` border-radius (`--dsx-rounded-lg` itself resolved to `9999px` on
+the portaled content), while `<html>` still correctly read `data-radius="md"`. Any future
+component with its own per-instance radius axis should avoid the literal `data-radius` name for
+the same reason — this isn't `ControlGroup`-specific.
+
+**Slot classes:** none — flat export, no named slots.
+
+**Corner-radius mechanism:**
+
+The root paints the visible border/background. Direct children get their shared (inner-facing)
+corners squared and outer corners rounded to match the root, via structural selectors
+(`:first-child`, `:last-child`, `:not(:first-child)`) — the same technique `InputGroup` already
+uses, applied here to children that are complete DS components (Select, ToggleGroup, Button,
+SegmentedControl) rather than raw form parts. A child's own border/shadow/background is
+intentionally left alone — `ControlGroup` only manages corner radius on the two outer edges and a
+1px visual seam between children (a `Separator`-style divider, not a border collapse, since
+children are not assumed to share the exact same border width the way stacked inputs do).
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules.
+
+**Reduced motion:**
+
+- No motion — a static layout container.
+
+## Token mapping
+
+| Property | Token | Role |
+|---|---|---|
+| Background | `var(--dsx-color-surface)` | Group frame surface |
+| Border | `var(--dsx-color-outline-variant)` | Group frame edge |
+| Radius (full) | `var(--dsx-rounded-full)` | Pill frame |
+| Radius (md) | `var(--dsx-rounded-md)` | Rectangular frame |
+| Padding | `var(--dsx-space-xs)` | Inner gutter between frame edge and first/last child |
+| Seam | `var(--dsx-color-outline-variant)` | Divider between adjacent children |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in this table or in the CSS file.
+- Accent-driven children (a `ToggleGroup` item's active fill, a `SegmentedControl`'s active
+  state) keep their own accent tokens — `ControlGroup` does not repaint or override a child's own
+  interactive state, only its outer corner radius.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Root | `none` | `none` | `none` |
+
+## Accessibility
+
+**Roles:**
+
+- `group` on the root, so assistive tech announces the contained controls as one related cluster.
+
+**Keyboard:**
+
+- No keyboard handling of its own — each child control owns its own keyboard interaction
+  (`Tab` moves between children exactly as it would without the wrapper).
+
+**Focus:**
+
+- A focused child's own focus ring must remain fully visible — the root's `overflow` stays
+  visible (not `hidden`), so a focus ring is never clipped by the group's rounded corners.
+
+**Reduced motion:**
+
+- N/A — no motion.
+
+**Color and meaning:**
+
+- N/A — a layout container, no semantic state of its own.
+
+**Naming:**
+
+- The root's `aria-label` is left to the consumer when the group's purpose isn't obvious from its
+  children's own labels (e.g. `<ControlGroup aria-label="Currency and language">`).
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `ControlGroup` with a `Select` and a `ToggleGroup` child, no extra props.
+- Asserts the root class is `dsx-control-group`.
+
+**Variant story** (one per `radius` value):
+
+- `radius="full"` and `radius="md"`, asserting `data-group-radius` matches.
+
+**State story:**
+
+- One child focused (via `Tab`) — asserts the focus ring is not clipped.
+
+**Composition story:**
+
+- Three children (`Select`, `Separator`-free two-item `ToggleGroup`, `Button`) to prove the
+  corner-radius mechanism holds for more than two children.
+
+**Token story:**
+
+- Rendered inside `Theme` with `accentColor="silver"` and `accentColor="bronze"` — asserts a
+  `ToggleGroup` child's active-item fill still resolves to the right accent (proving
+  `ControlGroup` doesn't interfere with a child's own accent scoping).
+
+**A11y story:**
+
+- `vitest-axe` on the composition story.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | `select` | `md` |
+| `radius` | `select` | `full` |
+
+## Wiring notes
+
+**Composes from:**
+
+- Any DS interactive component as a direct child — `Select`, `ToggleGroup`, `SegmentedControl`,
+  `Button`, `IconButton` are the ones currently exercised.
+
+**Used by:**
+
+- Landing header's currency + language cluster (`apps/playground/.../landing/_shared/landing-view.tsx`)
+  — the motivating real usage. Previously hand-built as a bordered `Stack` with per-instance CSS
+  overrides for corner radius; migrated to `ControlGroup` in the same change that added this spec.
+
+**State boundaries:**
+
+- Owned by this component: corner-radius/seam geometry only.
+- Owned by the consumer: every child's own value/state — `ControlGroup` never reads or writes a
+  child's `value`/`onValueChange`.
+
+**Boundary rules:**
+
+- App-owned data: which controls are grouped, their values, their change handlers.
+- DS-owned visuals: the group frame's border/background/radius and the inter-child seam.
+
+**Distinction from InputGroup:** `InputGroup`'s purpose is input-centric (a text field with
+leading/trailing addons — "Ideal for search fields, URLs, copy/share flows," per its roster row)
+and its convenience sub-components (`Addon`/`Text`/`Button`/`Input`/`Textarea`) assume the group
+is built around exactly one text-entry control. `ControlGroup` has no such assumption — it exists
+for clusters where no single child is "the" input (e.g. two independent selectors). Using
+`InputGroup` for the landing header (checked before building this) would have stretched it past
+its documented purpose for a resemblance in CSS mechanism alone, not a real semantic fit.
+
+## Penpot build recipe
+
+### Root board
+
+- **Name**: `Components / ControlGroup`.
+- **Dimensions**: `auto × auto` (content-sized).
+- **Layout**: `Flex`.
+- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+ControlGroup
+  ├── Child 1 (e.g. Select instance)
+  ├── Seam (1px divider)
+  └── Child 2 (e.g. ToggleGroup instance)
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Root | fill | `--dsx-color-surface` | Color | fills |
+| Root | stroke | `--dsx-color-outline-variant` | Color | strokes |
+| Root | radius | `--dsx-rounded-full` | Radius | corner-radius |
+| Root | padding | `--dsx-space-xs` | Spacing | padding |
+| Seam | fill | `--dsx-color-outline-variant` | Color | fills |
+
+### State transformations
+
+| State | Root fill | Stroke | Text fill | Shadow |
+|---|---|---|---|---|
+| `default` | `--dsx-color-surface` | `--dsx-color-outline-variant` | n/a (children own their own text) | none |
+
+### Variant model
+
+- `radius`: `full`, `md`. Default `full`.
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- Total members: `6`.
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Components`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.

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

@@ -3,13 +3,6 @@ title: CopyButton
 status: canonical
 category: Primitives
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/copyButton/CopyButton.tsx
-css_path: packages/d4gger-design-system/src/styles/components/copy-button.css
-props_path: packages/d4gger-design-system/src/components/copyButton/copyButton.props.ts
-test_path: packages/d4gger-design-system/src/test/components/CopyButton.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
   - Icon
@@ -17,7 +10,7 @@ depends_on:
 
 # CopyButton
 
-> 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
 
@@ -45,7 +38,7 @@ No slots: flat export. The component does not expose named subcomponents. The vi
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner roundness; writes `data-radius` on the button. | no |
 | `color` | `string` | `undefined` | no | Accent color; writes `data-accent-color` on the button. The prop def has an empty enum so any string is accepted. | no |
 | `highContrast` | `boolean` | `false` | no | When `true`, swaps to the high-contrast palette; writes `data-high-contrast="true"` on the button. | no |
-| `asChild` | `boolean` | `false` | no | Renders through `Slot`; forwards to the underlying Button. | no |
+| `asChild` | `boolean` | `false` | no | Renders through `Slot`; forwards to the underlying Button. Styling slot only — the click handler always `preventDefault`s so the copy wins; do not use `asChild` with a navigating anchor. | no |
 | `aria-label` | `string` | `undefined` | no | Accessible name. When omitted and `children` is a string, the component uses that string as the label. Otherwise it falls back to `"Copy value"`. | no |
 | `disabled` | `boolean` | `undefined` | no | Standard button prop. Forwarded to the underlying Button. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-copy-button` on the underlying button. | no |
@@ -94,20 +87,20 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Property | Token | Role |
 |---|---|---|
-| `transition` | `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-in-out, ease-in-out)` | Animate the icon and color swap. |
-| Color (copied state) | `var(--dsx-color-success)` | Success state fill and border. |
-| Icon color (copied state) | `var(--dsx-color-success)` | Success state icon. |
+| `transition` | `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-in-out, ease-in-out)` | Animate the icon swap. |
+| Color (copied state) | (none — inherits the variant fill) | The copied state never repaints (Direction #3 Q2 pick). |
+| Icon color (copied state) | `currentColor` | Check icon inherits the variant text color. |
 
 Rules:
 
 - No raw color, spacing, radius, or motion values in `copy-button.css`.
-- The non-copied state defers entirely to the underlying Button's class contract. CopyButton only overrides the success state.
+- The non-copied state defers entirely to the underlying Button's class contract. CopyButton only swaps the icon and label — no success wash on any variant.
 
 ## Motion contract
 
 | Region | Token | Default | Reduced |
 |---|---|---|---|
-| State transition (`all`) | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-in-out, ease-in-out)` | Animates the icon swap and color change when entering and leaving the success state. | `transition: none` inside `@media (prefers-reduced-motion: reduce)`. |
+| State transition (`all`) | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-in-out, ease-in-out)` | Animates the icon swap when entering and leaving the success state. | `transition: none` inside `@media (prefers-reduced-motion: reduce)`. |
 
 Rules:
 
@@ -132,11 +125,11 @@ Rules:
 
 **Reduced motion:**
 
-- The icon and color swap transition collapses to `none` when `prefers-reduced-motion: reduce` matches.
+- The icon swap transition collapses to `none` when `prefers-reduced-motion: reduce` matches.
 
 **Color and meaning:**
 
-- The success state is communicated by the check icon, copied label, success color, and a polite atomic live region.
+- The success state is communicated by the check icon, the copied label, and a polite atomic live region. No color change.
 
 **Naming:**
 
@@ -206,4 +199,4 @@ Rules:
 **Boundary rules:**
 
 - App-owned data: the copied value, the surrounding code or token surface, the clipboard environment handling, and the user feedback copy.
-- DS-owned visuals: the `dsx-copy-button` wrapper class, the success state modifier class, the success color and icon, the transition timing, and the underlying Button class contract.
+- DS-owned visuals: the `dsx-copy-button` wrapper class, the success state modifier class, the icon swap, the transition timing, and the underlying Button class contract.

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

@@ -3,13 +3,6 @@ title: CopyField
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/copyField/CopyField.tsx
-css_path: packages/d4gger-design-system/src/styles/components/copy-field.css
-props_path: packages/d4gger-design-system/src/components/copyField/copyField.props.ts
-test_path: packages/d4gger-design-system/src/test/components/CopyField.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:
   - Field
   - InputGroup

package/dist/docs/{data-list.md → components/data-list.md}

@@ -3,20 +3,13 @@ title: DataList
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/dataList/DataList.tsx
-css_path: packages/d4gger-design-system/src/styles/components/data-list.css
-props_path: packages/d4gger-design-system/src/components/dataList/dataList.props.ts
-test_path: packages/d4gger-design-system/src/test/components/DataList.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/data.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Item
 ---
 
 # DataList
 
-> 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/{data-table.md → components/data-table.md}

@@ -3,13 +3,6 @@ title: DataTable
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/dataTable/DataTable.tsx
-css_path: packages/d4gger-design-system/src/components/dataTable/dataTable.css
-props_path: packages/d4gger-design-system/src/components/dataTable/dataTable.props.ts
-test_path: packages/d4gger-design-system/src/test/components/DataTable.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/data.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Table
   - Pagination
@@ -21,7 +14,7 @@ depends_on:
 
 # DataTable
 
-> 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