@d4gger/design-system 3.0.1 → 4.0.1

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.md

@@ -40,6 +40,7 @@ Rules:
 - `Icon` extends `Omit<React.ComponentPropsWithoutRef<'svg'>, 'color'>` because `color` is redefined. The runtime uses `LucideComponent` or `SimpleIconComponent` for the underlying SVG; both forward standard SVG attributes.
 - The `name` prop is the only visual contract. The internal `isDSXIconName` guard returns `null` for unknown names so callers do not need to handle a missing icon fallback at the call site.
 - The component always writes `data-size` and `class="dsx-icon"`. The `aria-hidden` and `role` attributes are managed by the runtime based on whether `title` is provided.
+- A name lives in four hand-kept lists: the component map, the `DSXIconName` tuple, `dsxIconCatalog` and one named export in `icons.tsx` (`check` → `CheckIcon`). `Icon.test.tsx` keeps them in step (every catalog name renders an `svg`, and the catalog names and the named exports are the same set). One glyph has one name: `dots-horizontal` is Lucide's `Ellipsis`, and no `ellipsis` alias exists.
 
 ## CSS class contract
 

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.

package/dist/docs/components/link.md

@@ -8,247 +8,69 @@ depends_on: []
 
 # Link
 
-> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+> Source of truth: the package source at `package_path`. The spec mirrors source in the same change.
 
 ## Purpose
 
-A styled anchor element that renders an `<a>` (or the consumer's host element) with token-aligned typography, an `underline` policy, a `tone` color override, an optional `color` accent (rift, warp, or ray), an optional single-value `size` scale, a `highContrast` toggle, and the shared `asChild` infra. Internal versus external routing is a consumer choice: the component renders an `<a>` and forwards `href`, `target`, `rel`, and every other native anchor attribute through prop forwarding.
+A native inline anchor with readable accent foreground, explicit underline policy and a single-value font-size scale. Apps own destination, routing, target and rel. `asChild` supplies a consumer host.
 
 ## Anatomy & slots
 
-**Parent:** `Link` (no compound; flat polymorphic export).
-
-**Slots:**
-
-No slots: flat export. The component renders a single `<a>` host element (or the consumer's host element when `as` or `asChild` is set) with the `dsx-link` root class, the `underline` modifier class, and any `tone` modifier class.
+Single `<a>` root with `dsx-link`; no compound slots. Native anchor attributes and refs are forwarded. `asChild` uses Radix Slot.
 
 ## Props contract
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `underline` | `'auto' \| 'always' \| 'hover' \| 'none'` | `'auto'` | no | Underline policy. Writes the `dsx-link--{underline}` modifier class. `auto` is unstyled at rest, underline on hover (same hover treatment as `hover`); `always` shows it unconditionally; `hover` is unstyled at rest, underline on hover; `none` removes it for both `a` and `button` hosts. | no |
-| `tone` | `'default' \| 'muted' \| 'inverse'` | `'default'` | no | Tone modifier. Writes `dsx-link--{tone}` for `muted` and `inverse`. | no |
-| `color` | `'rift' \| 'warp' \| 'ray' \| string` | `undefined` | no | Accent color. The three canonical values are rift, warp, and ray; the prop also accepts a free-form string. Writes the `data-accent-color` attribute. | no |
-| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Single-value size scale. Writes the `data-size` attribute. Not responsive: the source writes the value directly with no base-value resolution. | no |
-| `highContrast` | `boolean` | `false` | no | When `true`, writes `data-high-contrast="true"`. | 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-link`. | no |
-| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
-| `children` | `React.ReactNode` | `undefined` | no | Link body. | no |
-
-Rules that apply to this row:
-
-- `Link` extends `Omit<ComponentPropsWithoutRef<'a'>, 'color'>` because `color` is redefined by the prop def bag.
-- `underline`, `tone`, `color`, `size`, `highContrast`, and `asChild` flow through `extractProps` and the prop def bag. The component forwards every other native anchor attribute (`href`, `target`, `rel`, `download`, `aria-*`, etc.) when `asChild` is `false`.
-- `data-accent-color` is written when `color` is set. `data-size` is written when `size` is set. `data-high-contrast` is written when `highContrast` is truthy.
-- The `color` prop in the prop def has `type: 'enum | string'` and a `values` list of `['rift', 'warp', 'ray']`. The runtime accepts any string; the canonical values are the accent palette.
-- Internal versus external routing is not a prop. Apps wrap `Link` in their router's link primitive (or use `asChild` with the router's link) when they need client-side navigation; `Link` itself renders a native anchor and forwards `href`.
+| `underline` | `'auto' \| 'always' \| 'hover' \| 'none'` | `'auto'` | no | Writes `dsx-link--{underline}`; see affordance policy below. | no |
+| `tone` | `'default' \| 'muted' \| 'inverse'` | `'default'` | no | Non-default tones write `dsx-link--{tone}`. | no |
+| `color` | `'rift' \| 'warp' \| 'ray' \| string` | `undefined` | no | Writes `data-accent-color`; the global token layer resolves recognized accents, including astral and spark. Unknown strings retain the ambient tokens. | no |
+| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Writes `data-size` and applies the existing role-derived font-size mapping. | no |
+| `highContrast` | `boolean` | `false` | no | Writes `data-high-contrast="true"` and uses high-contrast foreground. | no |
+| `asChild` | `boolean` | `false` | no | Slot the consumer host. | no |
+| `className` | `string` | `undefined` | no | Additional classes. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Forwarded style. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Accessible link content. | no |
+
+`href`, `target`, `rel`, `download`, `id` and `aria-*` are native anchor props. There is no routing or external-link prop and no `as` prop.
 
 ## CSS class contract
 
-**Root class:** `dsx-link`
-
-**Modifier classes** (driven by the `underline` and `tone` prop defs and the `data-*` attributes):
-
-| Attribute | Allowed values | Class | CSS file |
-|---|---|---|---|
-| (class) | `auto`, `always`, `hover`, `none` | `dsx-link--{underline}` | `link.css` |
-| (class) | `muted`, `inverse` | `dsx-link--muted`, `dsx-link--inverse` | `link.css` |
-| `data-accent-color` | `rift`, `warp`, `ray` (or any custom string) | `.dsx-link[data-accent-color='rift']`, `.dsx-link[data-accent-color='warp']`, `.dsx-link[data-accent-color='ray']` | `link.css` |
-| `data-size` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` | (CSS contract for size) | n/a |
-| `data-high-contrast` | `true` | `.dsx-link[data-high-contrast='true']` | `link.css` |
+Root: `dsx-link`. Modifier classes: `dsx-link--auto`, `--always`, `--hover`, `--none`, `--muted`, `--inverse`. Attributes: `data-size`, `data-accent-color`, `data-high-contrast`.
 
-**Slot classes:** none.
+The root uses native inline flow; multiline links share line boxes with surrounding text. `overflow-wrap: anywhere` allows long identifiers to wrap. SVG children align vertically with a token gutter. Layout primitives can still position a Link as a flex/grid child.
 
-**Responsive behavior:**
+Underline policy:
 
-- `size` is single-value only (`responsive` is unset in the prop def bag and the source writes `data-size` directly). Unlike Heading/Text, Link has no responsive class pipeline for size — no breakpoint-prefixed size classes exist in the CSS.
+- `auto`: no underline at desktop rest; underline on hover, focus-visible or pressed. On devices without hover it is underlined at rest.
+- `always`: underline at rest and through interaction.
+- `hover`: no underline at rest; underline on hover, focus-visible or pressed.
+- `none`: no underline through interaction; focus ring remains visible.
 
-**Reduced motion:**
-
-- The component transitions `color` over `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-standard, ease)`. The transition is a color change only; it is not gated by `prefers-reduced-motion` in the source CSS. The default fast duration is short enough that the transition is acceptable for most reduced-motion users.
+Underlines use `currentColor`, including muted, inverse and high-contrast tones. High contrast preserves the inverse foreground on an inverse surface. Thickness and offset preserve the existing font-relative browser heuristics.
 
 ## Token mapping
 
-Every CSS value the component paints is a `var(--dsx-*)` token.
-
 | Property | Token | Role |
 |---|---|---|
-| Color (default) | `var(--dsx-color-primary)` | Default link color. |
-| Color (accent override) | `var(--dsx-color-accent-9)` | Override for rift, warp, and ray. |
-| 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. |
-| Text decoration color | `var(--dsx-color-primary)` (or `var(--dsx-color-accent-9)` on accent, or `var(--dsx-color-high-contrast)` on high-contrast) | Underline color. |
-| Gap | `var(--dsx-space-xs)` | Inner gap for icon-plus-label layouts. |
-| Border radius (focus) | `var(--dsx-rounded-sm)` | Focus ring roundness. |
-| Outline (focus) | `2px solid var(--dsx-effect-ring-focus)` | Focus ring width. |
-| Outline offset (focus) | `var(--dsx-focus-ring-offset, 2px)` | Focus ring offset. |
-| Motion duration | `var(--dsx-motion-duration-fast, 150ms)` | Color transition. |
-| Motion easing | `var(--dsx-motion-easing-standard, ease)` | Color transition. |
-
-Rules:
-
-- Tokens come from `DESIGN.md` and the generated `tokens.css`. The accent override is the only place a brand color is used directly; the default link color tracks `var(--dsx-color-primary)` so it follows `data-accent-color` for rift, warp, and ray.
-- The text-decoration thickness and offset use the browser-native heuristics `min(2px, max(1px, 0.05em))` and `calc(0.025em + 2px)`. These are CSS values, not tokens; the spec records them as the canonical underline rhythm.
+| Default foreground | `--dsx-color-accent-indicator` | Readable text, independently scoped through all five accents. |
+| Muted / inverse / high contrast | `--dsx-color-on-surface-variant` / `--dsx-color-on-inverse-background` / `--dsx-color-high-contrast` | Existing tone and contrast roles. |
+| Icon gutter / focus radius | `--dsx-space-xs` / `--dsx-rounded-sm` | Inline icon and focus geometry. |
+| Focus outline / offset | `--dsx-border-width-lg` + `--dsx-effect-ring-focus` / `--dsx-space-0-5` | Visible 2px keyboard outline, 2px offset. |
+| Size 1–9 | label-small, label-medium, body-medium, body-large, label-large, headline-medium, headline-large, display-medium, display-large font-size tokens | Existing mapping preserved; omitted size inherits context. |
 
 ## Motion contract
 
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| Color transition | `var(--dsx-motion-duration-fast) var(--dsx-motion-easing-standard)` | `150ms ease` | (no explicit reduced override in the source CSS) |
-
-Rules:
-
-- The color transition is a token-driven property. A future `prefers-reduced-motion` override would either zero the duration or remove the transition entirely; the spec leaves that decision to a future spec change.
+Color transitions use `--dsx-motion-duration-fast` and `--dsx-motion-easing-standard`. `prefers-reduced-motion: reduce` removes the transition. Modality queries are not viewport breakpoints; no responsive prop or width query is added.
 
 ## Accessibility
 
-**Roles:**
-
-- The component renders an `<a>` by default (or the consumer's host element when `as` / `asChild` is set). The semantic role of a link is preserved.
-
-**Keyboard:**
-
-- Links are focusable. `Tab` moves focus to and from the link. `Enter` activates the link. The browser's focus ring renders through `dsx-link:focus-visible`.
-
-**Focus:**
-
-- Visible focus ring via `2px solid var(--dsx-effect-ring-focus)` with `outline-offset: var(--dsx-focus-ring-offset, 2px)`. The ring is rendered only on `:focus-visible` so mouse-driven focus does not show it.
-
-**Reduced motion:**
-
-- The color transition is short (150ms). Apps that need a strict reduced-motion fallback should layer a global rule that disables the transition inside `@media (prefers-reduced-motion: reduce)`.
-
-**Color and meaning:**
-
-- The `color`, `tone`, and `underline` props are visual modifiers. The link's href and label carry the meaning.
-
-**Naming:**
-
-- Every link needs an accessible name. The default render uses the body text as the accessible content. Consumers should supply `aria-label` when the body is an icon or another non-text node.
+Body prose should use `underline="always"` where link color does not have a 3:1 luminance distinction from surrounding text; the live paragraph demonstrates that policy. A named anchor with href receives native Tab/Enter behavior. Focus-visible always paints the outline. Touch and keyboard affordances do not depend on hover. Inline prose links use the WCAG 2.5.8 inline exception. When a link is blockified by flex/grid layout, its minimum inline/block size is a physical 24px (`size-md / density-scale`); density must not shrink the floor. Standalone icon actions should use the appropriate control component. Inverse tone requires an inverse surface. Apps supply accessible labels for icon-only content and their router host through `asChild`.
 
 ## Playground demo spec
 
-`Link` is registered in `apps/playground/lib/registry/typography.tsx` under the `link` key. The registry entry imports `linkPropDefs` and renders the component with a sample href. Per-component route: `/docs/link`.
-
-**Default story:**
-
-- Renders `Link` with a default href and body. Asserts the root class is `dsx-link` and the `underline` modifier is `dsx-link--auto`. Host element is `A` and the `href` attribute is forwarded.
-
-**Underline story:**
-
-- Renders Link with each `underline` value. Asserts the matching `dsx-link--{underline}` class.
-
-**Color story:**
-
-- Renders Link with each `color` value. Asserts the `data-accent-color` attribute on the root. The test `renders data-accent-color for warp and ray` documents rift, warp, and ray.
-
-**Composition story** (for `asChild`):
-
-- Renders Link with `asChild` wrapping a Next.js-style `<a>` element. Asserts the host element is `A` and the `dsx-link` class is preserved.
-
-**State story:**
-
-- Renders Link in muted, inverse, and high-contrast states. Asserts the matching modifier class or `data-high-contrast` attribute.
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper with `accentColor="rift"` and `accentColor="warp"`. Asserts the `data-accent-color` attribute tracks the active accent.
-
-**A11y story:**
-
-- The default render passes the `vitest-axe` no-violations check. The focus-visible ring test is covered by the `:focus-visible` selector in the CSS.
-
-**Props exposed in the playground controls:**
-
-| Prop | Control | Default |
-|---|---|---|
-| `underline` | select | `auto` |
-| `tone` | select | `default` |
-| `color` | select | (none) |
-| `size` | select | (none) |
-| `highContrast` | boolean | `false` |
-| `asChild` | boolean | `false` |
+`/docs/link`, typography registry. Matrix render forwards all props; controls expose underline, tone, color, size and highContrast. The live example has real local hash navigation, all four underline policies, muted/inverse/high-contrast references, all five accent strings and a slotted native anchor. Tab/Enter navigates to the labelled destination. The nine size values remain available in the matrix.
 
 ## Wiring notes
 
-**Composes from:**
-
-- `@radix-ui/react-slot` for `asChild`.
-- `_internal/helpers/extractProps` for the prop def bag.
-- `_internal/props/{asChild,highContrast}.prop` for the shared prop defs.
-- `_internal/cn` (via `classNames`) for class merging.
-- No DS component composition. Link is a leaf primitive.
-
-**Used by:**
-
-- The Playground typography registry, in-product navigation, in-line references, footer links, and any app surface that needs a styled anchor.
-
-**State boundaries:**
-
-- Owned by Link: the root class, the `underline` and `tone` modifier classes, the `data-accent-color`, `data-size`, and `data-high-contrast` attributes, the focus-visible ring, and the prop def bag.
-- Owned by the consumer: the href, target, rel, the body content, the host element when `as` / `asChild` is set, the click navigation behavior, and any extra `className` / `style` applied through prop forwarding.
-
-**Boundary rules:**
-
-- App-owned data: the destination, the link copy, the open-in-new-tab and rel behavior (`target="_blank"` requires `rel="noopener noreferrer"` for security), and the routing strategy.
-- DS-owned visuals: the `dsx-link` root class, the `underline` and `tone` modifier classes, the accent color, the focus ring, and the prop def bag.
-
-## Penpot build recipe
-
-> Optional. Penpot is a visual reference, not a code authority. The Link recipe tracks the `underline`, `tone`, `color`, `size`, and `highContrast` contract.
-
-The package does not yet publish a Penpot asset for Link. The recipe is visual reference only and tracks the CSS contract.
-
-### Root board
-
-- **Name**: `Primitives / Link`.
-- **Dimensions**: `auto × auto` (inline).
-- **Layout**: `Flex` (inline).
-- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
-
-### Layer tree
-
-```
-<Root Board: Link>
-  └── <Text: link body (anchor)>
-```
-
-### Token bindings (Penpot properties)
-
-| Shape | Property | Token | Token type | Penpot property name |
-|---|---|---|---|---|
-| Root | text fill | `--dsx-color-primary` (default) | Color | `fills` |
-| Root (accent) | text fill | `--dsx-color-accent-9` | Color | `fills` (state) |
-| Root (muted) | text fill | `--dsx-color-on-surface-variant` | Color | `fills` (state) |
-| Root (inverse) | text fill | `--dsx-color-on-inverse-background` | Color | `fills` (state) |
-| Root (always) | text decoration | `--dsx-color-primary` | Color | `textDecoration` |
-| Root (focus-visible) | outline | `--dsx-effect-ring-focus` | Color | `outline` |
-
-### State transformations
-
-| State | Root text fill | Text decoration |
-|---|---|---|
-| `default` | `--dsx-color-primary` | (none on `auto`) |
-| `muted` | `--dsx-color-on-surface-variant` | (none) |
-| `inverse` | `--dsx-color-on-inverse-background` | (none) |
-| `highContrast` | `--dsx-color-high-contrast` | (none) |
-| `accent=rift` | `--dsx-color-accent-9` | `--dsx-color-accent-9` on `always` |
-| `always` | (per tone) | `underline` solid `--dsx-color-primary` |
-| `hover` (auto) | (per tone) | `underline` solid `--dsx-color-primary` |
-
-### Variant model
-
-- `underline`: `auto`, `always`, `hover`, `none`. Default `auto`.
-- `tone`: `default`, `muted`, `inverse`. Default `default`.
-- `color`: `rift`, `warp`, `ray`, or a free-form string. Default unset.
-- `size`, `highContrast` documented in the spec body.
-- Total members: underline × tone × color = 4 × 3 × 4 = 48, plus the high-contrast toggle.
-
-### Validation checklist
-
-- [ ] 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 accent override is the only place a brand color is used directly; the default link color tracks `data-accent-color` for rift, warp, and ray.
+Radix Slot implements `asChild`; `extractProps` consumes `linkPropDefs`; classnames merges the root and modifiers. No DS component composition inside Link. The token layer owns accent rescoping; Link consumes semantic roles. Apps own link content, destination and navigation.