@d4gger/design-system 2.7.0

package/dist/docs/layout-props.md

@@ -0,0 +1,152 @@
+---
+title: Layout (props)
+status: canonical
+category: Foundations
+archetype: utility
+package_path: packages/d4gger-design-system/src/layout/layout.props.ts
+css_path: packages/d4gger-design-system/src/styles/components/box.css
+props_path: packages/d4gger-design-system/src/layout/layout.props.ts
+test_path: packages/d4gger-design-system/src/test/props/Layout.test.ts
+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:
+  - Box
+  - Shared
+---
+
+# Layout (props)
+
+> 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.
+
+## Purpose
+
+Shared polymorphic style-prop types (`BoxStyleProps`, `FlexStyleProps`, `GridStyleProps`, `ContainerStyleProps`, `SectionStyleProps`, `InsetStyleProps`) and prop defs (`BOX_PROP_DEFS`, `FLEX_PROP_DEFS`, `GRID_PROP_DEFS`, `CONTAINER_PROP_DEFS`, `SECTION_PROP_DEFS`, `INSET_PROP_DEFS`) for DS-local extension. `Layout (props)` is type-only infrastructure. The public surface is the type bundle re-exported from `@d4gger/design-system` and `@d4gger/design-system/foundations`.
+
+## Anatomy & slots
+
+**Parent:** `Layout (props)` (no runtime component; flat type bundle).
+
+**Slots:**
+
+No slots. The bundle exports types, prop defs, and the `extractLayoutProps` helper, plus a small set of value-resolution helpers and a `createResponsiveVariableProp` factory.
+
+## Props contract
+
+`Layout (props)` does not render a component. There are no public runtime props. The exported API is:
+
+| Export | Kind | Description |
+|---|---|---|
+| `BoxStyleProps` | `type` | The combined `Box` style prop shape: `MarginProps & PaddingProps & { width, height, display, position, alignSelf, justifySelf }`. Values are `Responsive<T>` where `T` is a token enum or string. |
+| `FlexStyleProps` | `type` | The `Flex` style prop shape: `direction`, `align`, `justify`, `wrap`, `gap`. |
+| `GridStyleProps` | `type` | The `Grid` style prop shape: `columns`, `rows`, `gap`, `areas`, `flow`, `alignContent`, `justifyItems`, `justifyContent`. |
+| `ContainerStyleProps` | `type` | The `Container` style prop shape: `size`, `inset`. |
+| `SectionStyleProps` | `type` | The `Section` style prop shape: `size`, `space`. |
+| `InsetStyleProps` | `type` | The `Inset` style prop shape: `size`. |
+| `BOX_PROP_DEFS` | `const` | The `Box` responsive prop defs (`width`, `height`, `display`, `position`, `alignSelf`, `justifySelf`, plus `marginPropDef` and `paddingPropDef` spread in). Each entry is a `PropDef` with `customProperties: readonly --dsx-[]`, `parseValue`, and `responsive: true` flags. |
+| `FLEX_PROP_DEFS` | `const` | The `Flex` responsive prop defs (`direction`, `align`, `justify`, `wrap`, `gap`). |
+| `GRID_PROP_DEFS` | `const` | The `Grid` responsive prop defs (`columns`, `rows`, `gap`, `areas`, `flow`, `alignContent`, `justifyItems`, `justifyContent`). |
+| `CONTAINER_PROP_DEFS` | `const` | The `Container` responsive prop defs (`size`, `inset`). |
+| `SECTION_PROP_DEFS` | `const` | The `Section` responsive prop defs (`size`, `space`). |
+| `INSET_PROP_DEFS` | `const` | The `Inset` responsive prop defs (`size`). |
+| `createResponsiveVariableProp` | `function` | Factory for a `PropDef` that writes a single `--dsx-*` custom property and is `responsive: true`. |
+| `extractLayoutProps` | `function` | Wrapper around `extractProps` that ignores `asChild` and merges the resolved class + style output. |
+| `ResponsiveValue<T>` | `type` (re-export from `responsive.props.ts`) | `T \| Partial<Record<ResponsiveCondition, T>>` where `ResponsiveCondition` is `'initial' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`. |
+| `BREAKPOINTS`, `BREAKPOINT_ORDER`, `CONTAINER_WIDTHS`, `DENSITY_MODES` | `const` (re-export from `responsive.props.ts`) | The breakpoint and container width tables. |
+| `BreakpointName`, `BreakpointOrder`, `ContainerWidthName`, `DensityMode`, `ResponsiveBreakpoint`, `ResponsiveCondition` | `type` (re-export from `responsive.props.ts`) | The matching type aliases. |
+| `getBreakpointMinWidth`, `getBreakpointQuery`, `getContainerWidth`, `getDensityMode`, `isResponsiveValue`, `toResponsiveMap`, `assignResponsiveVars` | `function` (re-export from `responsive.props.ts`) | The responsive map, breakpoint query, and density mode helpers. |
+
+Rules:
+
+- `Layout (props)` is exported from `@d4gger/design-system` (the package root) and from `@d4gger/design-system/foundations`.
+- The runtime source for the type bundle is `src/layout/layout.props.ts` and `src/layout/responsive.props.ts`. Tests live in `src/test/props/Layout.test.ts`.
+- The exported types are the public contract. New responsive prop categories land in `src/_internal/props/<name>.prop.ts` and are spread into the matching `*_PROP_DEFS` constant.
+
+## CSS class contract
+
+`Layout (props)` does not own a root class. The custom properties it declares through the prop defs are consumed by the layout primitive CSS files in `src/styles/components/` (`box.css`, `flex.css`, `grid.css`, `container.css`, `section.css`, `inset.css`).
+
+| Custom property group | Token | Consumer CSS file |
+|---|---|---|
+| `--dsx-box-display`, `--dsx-box-position`, `--dsx-box-inset`, `--dsx-box-z-index`, `--dsx-box-min-*`, `--dsx-box-max-*`, `--dsx-box-margin`, `--dsx-box-padding`, `--dsx-box-gap`, `--dsx-box-align-self`, `--dsx-box-justify-self`, `--dsx-box-flex*`, `--dsx-box-order`, `--dsx-box-grid-*` | (see [Box](./box.md)) | `box.css` |
+| `--dsx-flex-direction`, `--dsx-flex-align`, `--dsx-flex-justify`, `--dsx-flex-wrap` | (see [Flex](./flex.md)) | `flex.css` |
+| `--dsx-grid-columns`, `--dsx-grid-rows`, `--dsx-grid-areas`, `--dsx-grid-auto-flow`, `--dsx-grid-align`, `--dsx-grid-justify`, `--dsx-grid-align-content`, `--dsx-grid-justify-items`, `--dsx-grid-justify-content` | (see [Grid](./grid.md)) | `grid.css` |
+| `--dsx-container-max-width`, `--dsx-container-inset` | (see [Container](./container.md)) | `container.css` |
+| `--dsx-section-space` | (see [Section](./section.md)) | `section.css` |
+| `--dsx-inset-size` | (see [Inset](./inset.md)) | `inset.css` |
+
+**Slot classes:** none.
+
+**Responsive behavior:**
+
+- The responsive contract is the breakpoint set in `BREAKPOINTS` (`sm` 640, `md` 768, `lg` 1024, `xl` 1280, `2xl` 1536) plus the `initial` condition. `BREAKPOINTS` is the only place widths are defined.
+- All exported prop defs use `responsive: true`. The runtime resolves them through `extractProps` and the per-breakpoint CSS cascade.
+
+**Reduced motion:**
+
+- N/A. `Layout (props)` is type-only infrastructure and has no motion.
+
+## Token mapping
+
+`Layout (props)` does not paint. The custom properties it declares are the indirection through which layout primitives reach tokens. The actual token resolution lives in the layout primitive spec files and in `foundations/Shared.tsx`.
+
+| Property | Token | Role |
+|---|---|---|
+| Space scale | `var(--dsx-space-{0,1,2,3,4,5,6,7,8,9,xs,sm,md,lg,xl,2xl,3xl,gutter,margin})` | `SpaceToken` resolution. Numeric token strings map to the 4px ramp from 0px through 36px. |
+| Radius scale | `var(--dsx-rounded-{none,sm,md,lg,xl,2xl,full})` | `RadiusToken` resolution |
+| Size scale | `var(--dsx-size-{auto,full,xs,sm,md,lg,xl,2xl,3xl,4xl})` | `parseSizeValue` resolution |
+| Container widths | `var(--dsx-container-width-{content,wide})` | `CONTAINER_WIDTHS` lookup |
+| Density modes | `var(--dsx-density-{comfortable,compact}-{padding,controlHeight})` | `DENSITY_MODES` lookup |
+
+Rules:
+
+- The token list is closed; new tokens are a `DESIGN.md` change first.
+- `parseContainerSizeValue`, `parseSectionSizeValue`, `parseInsetSizeValue`, `parseGridTrackValue`, `parseFlexAlignValue`, `parseFlexJustifyValue`, `parseGridAlignContentValue`, `parseGridJustifyItemsValue`, and `parseLengthValue` are the value-resolution helpers that turn prop enum values into CSS values. They are exported indirectly through the prop defs and may be consumed by DS-local extension code.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+`Layout (props)` is type-only infrastructure. The motion section is intentionally empty.
+
+## Accessibility
+
+`Layout (props)` is type-only infrastructure. There is no runtime surface, no role, no keyboard contract, and no focus management. Consumers of the type bundle are responsible for accessibility on whatever surface they build with the props.
+
+## Playground demo spec
+
+`Layout (props)` is type-only and does not render. The Playground docs surface does not expose a registry entry for this row. The type bundle is documented through the layout primitive spec files ([Box](./box.md), [Flex](./flex.md), [Grid](./grid.md), [Container](./container.md), [Section](./section.md), [Inset](./inset.md)) and through the [Shared](./shared.md) spec when polymorphic infra is the focus.
+
+If a future demo is required, the right shape is a typed table page that lists every responsive prop, the breakpoint map it accepts, and the `--dsx-*` custom property it writes. The registry render fixture in `apps/playground/lib/registry/utility.tsx` would expose the table through a static `metadata` block, not a runtime component.
+
+**Props exposed in the playground controls:** none. `Layout (props)` is type-only.
+
+## Wiring notes
+
+**Composes from:**
+
+- `_internal/props/propDef.ts`: the base `PropDef` type, the `Responsive<T>` type, and the `spaceScaleValues`, `sizeScaleValues`, `spaceUtilityValues`, `parseSpaceValue`, `parseSizeValue` helpers.
+- `_internal/props/margin.prop.ts`, `padding.prop.ts`: the `marginPropDef` and `paddingPropDef` spread into `BOX_PROP_DEFS`.
+- `_internal/helpers/extractProps.ts`: the runtime that turns the prop defs into class + style output.
+- `foundations/Shared.tsx`: `PolymorphicProps`, `SpaceToken`, `RadiusToken`, `SurfaceTone`, `BorderTone`, `ShadowTone`, and the `resolve*` helpers used at the runtime level. The type bundle itself does not depend on `Shared.tsx` at the type level, but the consuming layout primitives do.
+
+**Used by:**
+
+- `Box`, `Flex`, `Grid`, `Container`, `Section`, `Stack`, `Inset`: every layout primitive consumes the matching `*_PROP_DEFS` and the matching `*StyleProps` type. The class + style output is produced by `extractLayoutProps`.
+- DS-local extension components: any package-authoring work that builds a layout-shaped component on top of the existing primitive types.
+
+**State boundaries:**
+
+- Owned by `Layout (props)`: the public type bundle, the public prop defs, and the `extractLayoutProps` helper. The bundle does not own any state.
+- Owned by the consumer: any state on the surface built with the types. The bundle is purely structural.
+
+**Boundary rules:**
+
+- App-owned data: any surface built with the type bundle is owned by the app. The bundle is structural, not behavioral.
+- DS-owned visuals: the custom-property contract (`--dsx-box-*`, `--dsx-flex-*`, `--dsx-grid-*`, `--dsx-container-*`, `--dsx-section-*`, `--dsx-inset-size`) and the responsive map contract (`initial` | `sm` | `md` | `lg` | `xl` | `2xl`). New custom properties require a matching prop def and a matching CSS consumer.
+
+## Penpot build recipe
+
+`Layout (props)` is utility infrastructure. The package code is the only authority. There is no published Penpot build recipe and none is required; the layout primitive boards are the visual reference for the surface shapes this bundle enables.

package/dist/docs/link.md

@@ -0,0 +1,261 @@
+---
+title: Link
+status: canonical
+category: Primitives
+archetype: primitive
+package_path: packages/d4gger-design-system/src/components/link/Link.tsx
+css_path: packages/d4gger-design-system/src/styles/components/link.css
+props_path: packages/d4gger-design-system/src/components/link/link.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Link.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/typography.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on: []
+---
+
+# Link
+
+> 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.
+
+## 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 (amber, silver, or bronze), an optional responsive `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.
+
+## 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.
+
+## 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` shows the underline on hover (and on focus-visible by browser default); `always` shows it unconditionally; `hover` never shows it; `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` | `'amber' \| 'silver' \| 'bronze' \| string` | `undefined` | no | Accent color. The three canonical values are amber, silver, and bronze; 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 | Responsive size scale. Writes the `data-size` attribute. Accepts a responsive value (`{ initial, sm, md, lg, xl, 2xl }`). | yes |
+| `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 `['amber', 'silver', 'bronze']`. 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`.
+
+## 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` | `amber`, `silver`, `bronze` (or any custom string) | `.dsx-link[data-accent-color='amber']`, `.dsx-link[data-accent-color='silver']`, `.dsx-link[data-accent-color='bronze']` | `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` |
+
+**Slot classes:** none.
+
+**Responsive behavior:**
+
+- `size` is `responsive: true` in the prop def bag. The component writes `data-size` for the base value; the responsive class application is left to downstream CSS or the consumer.
+
+**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.
+
+## 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 amber, silver, and bronze. |
+| 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 amber, silver, and bronze.
+- 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.
+
+## 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.
+
+## 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.
+
+## 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 silver and bronze` documents amber, silver, and bronze.
+
+**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="silver"` and `accentColor="bronze"`. 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` |
+
+## 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=amber` | `--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`: `amber`, `silver`, `bronze`, 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 amber, silver, and bronze.