@d4gger/design-system 3.0.0 → 4.0.0

package/dist/docs/components/heading.md

@@ -12,7 +12,7 @@ depends_on: []
 
 ## Purpose
 
-The app-level heading primitive. Renders an `h1`–`h6` host element with token-aligned typography, a token-backed color prop, a `tone` modifier for muted or inverse contexts, a responsive `size` scale, and the shared margin, padding, alignment, wrap, trim, weight, truncate, high-contrast, and `asChild` infra. The host element is derived from the `size` prop when provided, or from the `variant` prop when `size` is unset.
+The app-level heading primitive. Renders an `h1`–`h6` host element with token-aligned typography, a token-backed color prop, a `tone` modifier for muted or inverse contexts, a scalar `size` scale, and the shared margin, padding, alignment, wrap, trim, weight, truncate, high-contrast, and `asChild` infra. The host element is derived from the `size` prop when provided, or from the `variant` prop when `size` is unset.
 
 ## Anatomy & slots
 
@@ -20,7 +20,7 @@ The app-level heading primitive. Renders an `h1`–`h6` host element with token-
 
 **Slots:**
 
-No slots: flat export. The component renders a single `h1`–`h6` host element (or the consumer's host element when `as` or `asChild` is set) with the `dsx-heading` root class, the variant modifier class, and any `tone` modifier class.
+No slots: flat export. The component renders a single `h1`–`h6` host element (or the consumer's host element when `asChild` is set) with the `dsx-heading` root class, the variant modifier class, and any `tone` modifier class.
 
 ## Props contract
 
@@ -28,16 +28,16 @@ No slots: flat export. The component renders a single `h1`–`h6` host element (
 |---|---|---|---|---|---|
 | `variant` | `'display-large' \| 'display-medium' \| 'headline-large' \| 'headline-medium'` | `'headline-medium'` | no | Heading ramp. Writes the `dsx-heading--{variant}` modifier class. Determines the default host element when `size` is unset: `display-large` → `h1`, `display-medium` → `h2`, `headline-large` → `h3`, `headline-medium` → `h4`. | no |
 | `tone` | `'default' \| 'muted' \| 'inverse'` | `'default'` | no | Tone modifier. Writes `dsx-heading--{tone}` for `muted` and `inverse`. | no |
-| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Responsive size scale. Accepts a responsive value (`{ initial, sm, md, lg, xl, 2xl }`). When the base value is set, the host element is derived from it: `9` → `h1`, `8` → `h2`, `7` → `h3`, `6`/`5` → `h4`, `4`/`3` → `h5`, `2`/`1` → `h6`. The `size` axis wins over the `variant` axis for the host element. | yes |
-| `color` | token name string | `undefined` | no | Free-form color token reference. Writes `data-accent-color` and the matching `dsx-r-color-{name}` class. Accepts a responsive value. | yes |
-| `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 |
+| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Scalar size scale. The host is derived from it: `9` → `h1`, `8` → `h2`, `7` → `h3`, `6`/`5` → `h4`, `4`/`3` → `h5`, `2`/`1` → `h6`. Explicit `asChild` supplies the semantic host. | no |
+| `color` | shared semantic color enum | `undefined` | no | Values are listed in the class contract below. Writes `data-accent-color` and the matching `dsx-r-color-{name}` class. | no |
+| `weight` | `'light' \| 'regular' \| 'medium' \| 'bold'` | `undefined` | no | Typography weight. Writes the `dsx-r-weight-{name}` class. | no |
+| `align` | `'left' \| 'center' \| 'right' \| 'justify'` | `undefined` | no | Text alignment. Writes the `dsx-r-ta-{name}` class. | no |
+| `wrap` | `'wrap' \| 'nowrap' \| 'pretty' \| 'balance'` | `undefined` | no | Text wrap. Writes the `dsx-r-tw-{name}` 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 |
+| `trim` | `'normal' \| 'start' \| 'end' \| 'both'` | `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 |
-| `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py` | `string` | `undefined` | no | Padding style props from the `padding.prop` def. | no |
+| `margin`, `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my` | `string` | `undefined` | no | Scalar margin style props from the `margin.prop` def. | no |
+| `padding`, `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py` | `string` | `undefined` | no | Scalar padding style props from the `padding.prop` def. | no |
 | `asChild` | `boolean` | `false` | no | Renders the host through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-heading`. | no |
 | `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
@@ -47,25 +47,25 @@ Rules that apply to this row:
 
 - `Heading` extends `Omit<ComponentPropsWithoutRef<'h1'>, 'color'>` because `color` is redefined by the prop def bag. The component's own `color` prop must not be confused with the native `color` attribute on `<h1>`.
 - `variant`, `tone`, `size`, `color`, `weight`, `align`, `wrap`, `truncate`, `trim`, `highContrast`, and `asChild` flow through `extractProps` and the prop def bag. The margin and padding prop defs spread into the same bag.
-- The host element is `Tag = asChild ? Slot : (baseSize ? getHeadingTagFromSize(baseSize) : getDefaultHeadingTag(variant))`. The `size` axis wins over the `variant` axis. The test `size prop determines semantic heading level over variant` documents this.
+- The host is the consumer slot when `asChild` is set; otherwise `getHeadingTagFromSize(size)` supplies it when size is present, and `getDefaultHeadingTag(variant)` supplies the default. The `size` axis wins over the `variant` axis. The test `size prop determines semantic heading level over variant` documents this.
 - `data-accent-color` is written when `color` is a string. `data-size` is written when `size` is a string. `data-high-contrast` is written when `highContrast` is truthy.
 
 ## CSS class contract
 
 **Root class:** `dsx-heading`
 
-**Modifier classes** (driven by the prop def bag and the responsive helpers):
+**Modifier classes** (driven by the scalar prop def bag and shared class extraction):
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | (class) | `display-large`, `display-medium`, `headline-large`, `headline-medium` | `dsx-heading--{variant}` | `heading.css` |
 | (class) | `muted`, `inverse` | `dsx-heading--muted`, `dsx-heading--inverse` | `heading.css` |
-| `data-size` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` | `dsx-r-heading-size-{n}` (and breakpoint-prefixed `sm:`, `md:`, `lg:`, `xl:`, `2xl:`) | `heading.css` (and `src/styles/responsive/*.css`) |
-| `data-accent-color` | any token name | `dsx-r-color-{name}` (and breakpoint-prefixed variants) | `src/styles/responsive/*.css` |
-| (class) | any weight name | `dsx-r-weight-{name}` (and breakpoint-prefixed variants) | `src/styles/responsive/*.css` |
-| (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` |
+| `data-size` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` | `dsx-r-heading-size-{n}` | `heading.css` |
+| `data-accent-color` | `primary`, `primary-container`, `secondary`, `secondary-container`, `tertiary`, `tertiary-container`, `success`, `success-container`, `error`, `error-container`, `surface`, `surface-raised`, `surface-overlay`, `surface-sunken`, `background`, `outline`, `outline-variant` | `dsx-r-color-{name}` | `src/styles/responsive/*.css` |
+| (class) | `light`, `regular`, `medium`, `bold` | `dsx-r-weight-{name}` | `src/styles/responsive/*.css` |
+| (class) | `left`, `center`, `right`, `justify` | `dsx-r-ta-{name}` | `src/styles/responsive/*.css` |
+| (class) | `wrap`, `nowrap`, `pretty`, `balance` | `dsx-r-tw-{name}` | `src/styles/responsive/*.css` |
+| (class) | `normal`, `start`, `end`, `both` | `dsx-r-lt-{name}` | `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` |
 
@@ -73,13 +73,15 @@ Rules that apply to this row:
 
 **Responsive behavior:**
 
-- `size`, `color`, `weight`, and `align` are `responsive: true` in the prop def bag. The prop def bag applies breakpoint-prefixed classes (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`) through the `responsive/*` style layer.
-- The component itself does not write `@media` rules. The `responsive/*` files are the source of the breakpoint-prefixed classes.
+- All typography and spacing props are scalar. This family emits no breakpoint-prefixed classes and has no viewport rules. Responsive page layout belongs to `Box`, `Flex` and `Grid`.
+- The maintainer approved removing the previous responsive typography API on 2026-10-04: “better to do it best versions from the get go and dont make backwards”. This is a breaking type change; release classification must reflect it.
 
 **Reduced motion:**
 
 - Heading has no motion. No transitions or animations are declared in `heading.css`.
 
+High contrast preserves `on-inverse-background` when `tone="inverse"` is used on its paired surface. Normal-surface high-contrast ink must not replace an inverse foreground.
+
 ## Token mapping
 
 Every CSS value the component paints is a `var(--dsx-*)` token.
@@ -97,12 +99,14 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Color (muted) | `var(--dsx-color-on-surface-variant)` | Muted tone. |
 | Color (inverse) | `var(--dsx-color-on-inverse-background)` | Inverse-context color. |
 | Color (high-contrast) | `var(--dsx-color-high-contrast)` | High-contrast shift. |
-| Responsive size 1–9 | `var(--dsx-typography-*-font-size)` | `dsx-r-heading-size-1` through `dsx-r-heading-size-9` map to the same typography tokens. |
-| Margin / padding | `var(--dsx-r-m*)`, `var(--dsx-r-p*)` | The `margin.prop` and `padding.prop` defs write `--dsx-r-*` variables that the responsive layer consumes. |
+| Scalar size 1–9 | `var(--dsx-typography-*-font-size)` | `dsx-r-heading-size-1` through `dsx-r-heading-size-9` map to the same typography tokens. |
+| Margin / padding | `var(--dsx-r-margin-{top,right,bottom,left})`, `var(--dsx-r-p*)` | Numeric, named and arbitrary spacing utilities resolve the local margins and padding. |
 
 Rules:
 
-- Tokens come from `DESIGN.md` and the generated `tokens.css`. The variant classes are the only modifiers; the responsive size classes are the second axis.
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The variant classes are the only modifiers; the size classes are the second axis.
+
+Spacing custom properties are reset locally so ancestor padding and margins do not leak into this element. Named margins use the same resolved directional variables as numeric and arbitrary values. Weight utilities resolve to 300 / 400 / 500 / 700.
 
 ## Motion contract
 
@@ -118,7 +122,7 @@ Rules:
 
 **Roles:**
 
-- The component renders an `h1`–`h6` by default. The host element is variant-derived when `size` is unset (`display-large` → `h1`, `display-medium` → `h2`, `headline-large` → `h3`, `headline-medium` → `h4`) and size-derived when `size` is set (`9` → `h1`, `8` → `h2`, `7` → `h3`, `6`/`5` → `h4`, `4`/`3` → `h5`, `2`/`1` → `h6`). Consumers that need a different heading level should set `as` to the level they want.
+- The component renders an `h1`–`h6` by default. The host element is variant-derived when `size` is unset (`display-large` → `h1`, `display-medium` → `h2`, `headline-large` → `h3`, `headline-medium` → `h4`) and size-derived when `size` is set (`9` → `h1`, `8` → `h2`, `7` → `h3`, `6`/`5` → `h4`, `4`/`3` → `h5`, `2`/`1` → `h6`). Consumers that need a different heading level should use `asChild` with the heading element they want.
 
 **Keyboard:**
 
@@ -146,7 +150,7 @@ Rules:
 
 **Default story:**
 
-- Renders `Heading` with a default heading string. Asserts the root class is `dsx-heading` and the variant modifier is `dsx-heading--headline-medium`. Host element is `H2` (variant-derived from the default `headline-medium`).
+- Renders `Heading` with a default heading string. Asserts the root class is `dsx-heading` and the variant modifier is `dsx-heading--headline-medium`. Host element is `H4` (variant-derived from the default `headline-medium`).
 
 **Variant story:**
 
@@ -154,15 +158,15 @@ Rules:
 
 **Size story:**
 
-- Renders Heading with each `size` value. Asserts the `data-size` attribute and the `dsx-r-heading-size-{n}` class. The host element is size-derived: `9` → `H1`, `8` → `H2`, `7` → `H3`, `6`/`5` → `H4`, `4`/`3` → `H5`, `2`/`1` → `H6`. Responsive `size` produces breakpoint-prefixed classes.
+- Renders Heading with each `size` value. Asserts the `data-size` attribute and the `dsx-r-heading-size-{n}` class. The host element is size-derived: `9` → `H1`, `8` → `H2`, `7` → `H3`, `6`/`5` → `H4`, `4`/`3` → `H5`, `2`/`1` → `H6`. Size remains unchanged when the viewport changes; responsive maps are rejected by the public type.
 
 **Color story:**
 
-- Renders Heading with each `color` token name. Asserts the `data-accent-color` attribute and the `dsx-r-color-{name}` class. Responsive `color` produces breakpoint-prefixed classes.
+- Renders Heading with each `color` token name. Asserts the `data-accent-color` attribute and the `dsx-r-color-{name}` class. Color is scalar; responsive maps are rejected by the public type.
 
 **Composition story** (for `asChild`):
 
-- Renders Heading with `asChild` wrapping an `<h1>` element. Asserts the host element is `H1` and the `dsx-heading` class is preserved.
+- Renders Heading with `asChild` wrapping appropriate `<h2>` and `<h3>` elements. Asserts the chosen host is preserved and the `dsx-heading` class is preserved.
 
 **State story:**
 
@@ -170,7 +174,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="warp"` and `accentColor="ray"`. Asserts the `data-accent-color` attribute on the wrapper tracks the active accent.
+- Renders inside a `Theme` wrapper with `accentColor="rift"` and `accentColor="warp"`. Asserts the `data-accent-color` attribute on the wrapper tracks the active accent.
 
 **A11y story:**
 
@@ -196,7 +200,6 @@ Rules:
 
 - `@radix-ui/react-slot` for `asChild`.
 - `_internal/helpers/extractProps` for the prop def bag.
-- `_internal/helpers/getResponsiveStyles.isResponsiveObject` to read the base size from a responsive value.
 - `_internal/props/{asChild,color,highContrast,leadingTrim,margin,padding,textAlign,textWrap,truncate,weight}.prop` for the shared prop defs.
 - `_internal/cn` (via `classNames`) for class merging.
 - No DS component composition. Heading is a leaf primitive.
@@ -207,8 +210,8 @@ Rules:
 
 **State boundaries:**
 
-- Owned by Heading: the root class, the variant and tone modifier classes, the responsive size class, the color and weight responsive classes, the alignment, wrap, trim, and truncate classes, the high-contrast attribute, the `data-size` and `data-accent-color` attributes, the prop def bag, and the host-element derivation logic.
-- Owned by the consumer: the heading body, the host element when `as` / `asChild` is set, and any extra `className` / `style` applied through prop forwarding.
+- Owned by Heading: the root class, the variant and tone modifier classes, the size class, the color and weight classes, the alignment, wrap, trim, and truncate classes, the high-contrast attribute, the `data-size` and `data-accent-color` attributes, the prop def bag, and the host-element derivation logic.
+- Owned by the consumer: the heading body, the host element when `asChild` is set, and any extra `className` / `style` applied through prop forwarding.
 
 **Boundary rules:**
 

package/dist/docs/components/hover-card.md

@@ -258,7 +258,7 @@ Rules:
 | `<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` |
+| `<Arrow svg>` | fill | `--dsx-color-panel-translucent` | Color | `fills` |
 
 ### State transformations
 
@@ -278,3 +278,11 @@ Rules:
 - [ ] 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.
+
+## Overlay review constraints
+
+Content uses the popover layer and wraps long words. Arrow fill/color match
+`--dsx-color-panel-translucent`; its stroke uses border-width-sm. The live
+example previews a native link to visible profile content, preserving useful
+navigation on touch without requiring hover. Size and arrow comparisons
+render the same real link/profile composition.

package/dist/docs/components/icon-button.md

@@ -64,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):
 
@@ -127,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/components/item.md

@@ -25,7 +25,7 @@ A generic list-row surface for settings, notifications, or selectable summaries.
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `Item` (root) | `<div>` (or `Slot` host) | Root + class | The row surface. Writes `dsx-item`, `data-variant`, `data-size`, and (when `interactive={true}`) `data-interactive="true"`. |
+| `Item` (root) | `<div>` (or `Slot` host) | Root + class | The row surface. Writes `dsx-item`, a size modifier, a non-default variant modifier, and (when `interactive={true}`) `data-interactive="true"`. |
 | `Item.Media` | `<div>` (or `Slot` host) | Slot class | Leading visual slot (icon, avatar, image). Writes `dsx-item__media`. |
 | `Item.Content` | `<div>` (or `Slot` host) | Slot class | Text + metadata wrapper. Writes `dsx-item__content`. |
 | `Item.Title` | `<h4>` (or `Slot` host) | Slot class | Row title. Writes `dsx-item__title`. |
@@ -40,8 +40,8 @@ The root is a flex row with `gap: var(--dsx-space-md)`. `Item.Media`, `Item.Cont
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` | no | Surface treatment; writes `data-variant`. | no |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | no | Minimum height; writes `data-size`. `xs` and `sm` are row-density; `md` and `lg` are content-density. | no |
+| `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` | no | Surface treatment through modifier classes. | no |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | no | Minimum height and vertical padding through modifier classes. Padding increases from space-xs to space-sm, space-md, and space-lg. | no |
 | `interactive` | `boolean` | `false` | no | When `true`, adds `cursor: pointer` to the root; writes `data-interactive="true"`. The component does not add hover or focus styles; consumers that want a fully interactive row should wrap with their own Button or `asChild` onto a button. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot`; consumer supplies the host element. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-item`. | no |
@@ -57,19 +57,19 @@ Each slot also accepts the standard HTML attributes for its host element.
 
 Rules:
 
-- The component does not emit `data-radius`, `data-accent-color`, or `data-high-contrast`. The contract calls for `data-variant`, `data-size`, and `data-interactive` only.
-- `data-interactive` is emitted only when `interactive={true}`. The CSS does not currently hook it, but the prop is part of the public contract.
+- The component does not emit `data-radius`, `data-accent-color`, or `data-high-contrast`. Variant and size use classes; `data-interactive` is the only owned state attribute.
+- `data-interactive` is emitted only when `interactive={true}`. The CSS hooks it to apply the pointer cursor.
 
 ## CSS class contract
 
 **Root class:** `dsx-item`
 
-**Modifier classes** (driven by `data-*` attributes written by the component):
+**Modifier classes** (written directly by the component):
 
-| Attribute | Allowed values | Class | CSS file |
+| Prop | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-variant` | `default`, `outline`, `muted` | `.dsx-item[data-variant='outline']`, `.dsx-item[data-variant='muted']` | `item.css` |
-| `data-size` | `xs`, `sm`, `md`, `lg` | `.dsx-item[data-size='xs']`, `.dsx-item[data-size='sm']`, `.dsx-item[data-size='md']`, `.dsx-item[data-size='lg']` | `item.css` |
+| `variant` | `default`, `outline`, `muted` | `.dsx-item--outline`, `.dsx-item--muted` | `item.css` |
+| `size` | `xs`, `sm`, `md`, `lg` | `.dsx-item--xs`, `.dsx-item--sm`, `.dsx-item--md`, `.dsx-item--lg` | `item.css` |
 | `data-interactive` | `true` | `.dsx-item[data-interactive='true']` | `item.css` |
 
 **Slot classes:**
@@ -87,6 +87,8 @@ Rules:
 
 - The component does not write `@media` rules. `size` and `variant` are single-value only.
 
+- Content can shrink and long labels wrap. Root and trailing actions wrap intrinsically when their combined width exceeds the row, keeping commands reachable without a breakpoint.
+
 **Reduced motion:**
 
 - The component is static. No motion is applied.
@@ -109,7 +111,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Interactive cursor | `pointer` | Pointer cursor when `interactive={true}` |
 | Min-height (xs) | `var(--dsx-size-lg)` | xs row min-height |
 | Min-height (sm) | `var(--dsx-size-xl)` | sm row min-height |
-| Min-height (md, lg) | `var(--dsx-size-2xl)` | md/lg row min-height |
+| Min-height (md) | `var(--dsx-size-2xl)` | md row min-height |
+| Min-height (lg) | `var(--dsx-size-3xl)` | lg row min-height |
 | Media dimensions | `var(--dsx-size-xl)` | Media slot dimensions |
 | Content display | `grid` | Title + description layout |
 | Content gap | `var(--dsx-space-xs)` | Space between Title and Description |
@@ -161,11 +164,11 @@ The component is static.
 
 **Variant story:**
 
-- Renders three items with `variant="default"`, `variant="outline"`, and `variant="muted"`. Asserts the matching `data-variant` attribute.
+- Renders three items with `variant="default"`, `variant="outline"`, and `variant="muted"`. Asserts the matching non-default variant class.
 
 **Size story:**
 
-- Renders four items with `size="xs"`, `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute.
+- Renders four items with `size="xs"`, `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching size class and measures distinct rendered heights for identical content.
 
 **State story:**
 
@@ -207,10 +210,12 @@ The component is static.
 
 **State boundaries:**
 
-- Owned by Item: the `data-variant`, `data-size`, and `data-interactive` attributes, the flex row layout, and the `dsx-item__*` slot classes.
+- Owned by Item: the variant/size classes and `data-interactive` attribute, the flex row layout, and the `dsx-item__*` slot classes.
 - Owned by the consumer: the row content, the interactive behavior, the surrounding list semantics, and the heading level on `Item.Title`.
 
 **Boundary rules:**
 
 - App-owned data: the row content, the action handlers, the selection state, and the surrounding list semantics.
 - DS-owned visuals: token bindings, slot classes, variant surfaces, and the size min-height.
+
+The playground size comparison uses identical content and aligns row starts, avoiding flex stretch that would make all sizes inherit the largest sibling height. Both the variant gallery and the live example show the density scale.

package/dist/docs/components/kbd.md

@@ -120,6 +120,8 @@ Rules:
 
 ## Playground demo spec
 
+`/docs/kbd` uses static key labels with an application-owned Ctrl/⌘+K listener, both sizes and an inline slotted host.
+
 **Default story:**
 
 - Renders `Kbd` with a short body string (`⌘ K`). Asserts the root class is `dsx-kbd` and the host element is `KBD`.

package/dist/docs/components/label.md

@@ -50,7 +50,7 @@ Rules that apply to this row:
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-size` | `sm`, `md`, `lg` | `.dsx-label[data-size='sm']`, `.dsx-label[data-size='md']`, `.dsx-label[data-size='lg']` | `label.css` |
-| `data-disabled` | (presence) | `.dsx-label--disabled` (applied when the host is disabled) | `label.css` |
+| `data-disabled` | (presence) | `.dsx-label[data-disabled]` (presence selector) | `label.css` |
 
 **Slot classes:** none.
 
@@ -79,10 +79,12 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 Rules:
 
-- No raw color, spacing, radius, or motion values in `label.css`. The label-large type ramp is the only typography set the component consumes.
-- The component does not currently write a different type ramp per `size` value. The `data-size` hook is reserved for future per-size typography overrides; today's CSS only uses the label-large ramp regardless of `data-size`.
+- No raw color, spacing, radius, or motion values in `label.css`. The size mapping uses label-medium, label-large and body-large tokens, with role font variation settings and normal-case labels.
+- Small uses label-medium (12px), default uses label-large (14px), and large uses body-large font size (16px). Small/default role axes are applied; all sizes remain normal case, including when nested under an uppercase utility label.
 - The disabled state is a single combination: `--dsx-color-on-surface-variant` plus `--dsx-opacity-disabled`. Both tokens are theme-aware.
 
+The live example pairs the three label sizes with package Input controls. Clicking an enabled label focuses its associated input; the disabled pair remains disabled. `asChild` demonstrates styling a consumer host.
+
 ## Motion contract
 
 | Region | Token | Default | Reduced |
@@ -137,7 +139,7 @@ Rules:
 
 **State story:**
 
-- Renders Label with `disabled` set. Asserts `data-disabled=""` is on the host and the `dsx-label--disabled` modifier class is applied.
+- Renders Label with `disabled` set. Asserts `data-disabled=""` is on the host and the disabled visual treatment is applied.
 - Renders Label with no `disabled` prop. Asserts `data-disabled` is absent.
 
 **Composition with control:**
@@ -146,7 +148,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Label does not consume `data-accent-color`; the story documents that the label color tracks the on-surface token and is unchanged across accents.
+- Renders inside a `Theme` wrapper with `accentColor="rift"` and `accentColor="warp"`. Label does not consume `data-accent-color`; the story documents that the label color tracks the on-surface token and is unchanged across accents.
 
 **A11y story:**
 
@@ -164,7 +166,7 @@ Rules:
 
 **Composes from:**
 
-- `@radix-ui/react-label` (`Root`): provides the `<label>` host, the `htmlFor` association, and the `data-disabled` reflection when the target control is disabled (Radix wires this through context, but the component still accepts a manual `disabled` prop for visual control).
+- `@radix-ui/react-label` (`Root`): provides the `<label>` host and the native `htmlFor` association. The DS `disabled` prop supplies the visual reflection; consumers mirror disabled onto the paired control.
 - `@radix-ui/react-slot`: enables `asChild` for consumer-supplied host elements.
 
 **Used by:**
@@ -181,7 +183,7 @@ Rules:
 **Boundary rules:**
 
 - App-owned data: the label copy, the target control id, the disabled state of the paired control, and the host element when `asChild` is set.
-- DS-owned visuals: the `dsx-label` root class, the `dsx-label--disabled` modifier class, the label-large typography token set, the on-surface color token, and the disabled opacity token.
+- DS-owned visuals: the `dsx-label` root class, the `data-disabled` hook, the label-large typography token set, the on-surface color token, and the disabled opacity token.
 
 ## Penpot build recipe
 
@@ -221,7 +223,7 @@ The package does not yet publish a Penpot asset for Label. Recipe is visual refe
 
 ### Variant model
 
-- `size`: `sm`, `md`, `lg`. Default `md`. Today's CSS does not switch typography per size; the `data-size` hook is reserved for future per-size overrides.
+- `size`: `sm`, `md`, `lg`. Default `md`. Sizes paint 12px / 14px / 16px.
 - `disabled`: `true`, `false`. Default `false`.
 - `asChild`: `true`, `false`. Default `false`.
 - Total members: 12 (3 × 2 × 2).
@@ -231,4 +233,4 @@ The package does not yet publish a Penpot asset for Label. Recipe is visual refe
 - [ ] Token bindings resolve at the values `DESIGN.md` describes.
 - [ ] Component is promoted to Main Component under `Primitives`.
 - [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
-- [ ] The `data-size` attribute is always written even though today's CSS only uses the label-large ramp.
+- [ ] The `data-size` attribute is always written and resolves distinct typography sizes.