Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): Link records its shipped contract as current (#8455)

Cindy Zhangf042c6ebd08c
diff --git a/packages/core/src/Link/Link.spec.md b/packages/core/src/Link/Link.spec.md
new file mode 100644
index 0000000000..dd0f25242f
--- /dev/null
+++ b/packages/core/src/Link/Link.spec.md
@@ -0,0 +1,229 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Link
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-26
+owners: [cixzhang]
+review_triggers: [public-api, behavior, theming, accessibility, navigation]
+verified_by:
+ [
+ packages/core/src/Link/Link.test.tsx,
+ packages/core/src/Link/__tests__/Link.a11y.test.tsx,
+ packages/core/src/Link/__tests__/Link.a11y.chromium.spec.ts,
+ packages/core/src/Link/__tests__/Link.navigation.a11y.chromium.spec.ts,
+ ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: [design:user-states]
+architecture:
+ [
+ architecture:component-theming-surface,
+ architecture:interaction-modality,
+ architecture:public-component-api,
+ ]
+contributing: []
+system_specs: [spec:AST-005, spec:AST-085]
+---
+
+# Link component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | None changes. Link takes `href`, `as`, `label`, `onClick`, `isDisabled`, `isExternalLink`, `newTabLabel`, `target`, `rel`, `download`, `referrerPolicy`, `hasUnderline`, `isStandalone`, `tooltip`, Text props, and `children`. |
+| Behavior | An enabled Link with `href` is a link rendered by `as`, then `LinkProvider`, then a native anchor. Otherwise it is a link-styled `<button>`, except that an inherited link role renders the link component, and a disabled Link with `href` and no `onClick` renders a plain anchor unless an inherited button role makes it a disabled `<button>` (FR1). A disabled Link stays focusable and inert. |
+| End-user impact | People get one link look for navigation and link-styled actions. Keyboard and screen-reader users can reach a disabled Link and hear that it is disabled. External links without `label` announce that they open a new tab. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A focused link that becomes disabled loses focus, caller attributes can replace Link's disabled exposure and `data-color`, and an ancestor Text line clamp cannot truncate a Link; all are listed under Current-state impact. |
+| Review checks | Reject a disabled Link that navigates, runs `onClick`, or leaves the tab order; a `_blank` target without `noopener noreferrer`; an external link with no new-tab text; or a rejected destination that reaches a router. |
+| Governing rules | `family:navigation-destinations` FR1–FR7; `spec:AST-005`; `spec:AST-085` FR1, FR2, FR4, FR5; `architecture:interaction-modality` INV1; `design:user-states` DR1, DR2. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Link is the styled navigation link. It decides whether it renders a link or a
+link-styled button, keeps a disabled link reachable and inert, adds new-tab
+safety and announcement for external links, and sets link typography and color.
+Consumer usage lives in `Link.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; `color="accent"`, `type="body"`,
+ `display="inline"`, `maxLines={0}`, no underline at rest
+- Compatibility class: records shipped behavior; no public prop, default,
+ export, or DOM change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The rendered element: link component, disabled anchor, or link-styled
+ button.
+- Disabled operability for every element form.
+- `target` and `rel` safety and the external-link icon and new-tab text.
+- Link typography (through Text), color, underline, hover, press, and focus
+ paint.
+- The `link` target.
+
+**Does not own / non-goals**
+
+- Destination acceptance and custom-router handoff — owned by
+ `family:navigation-destinations` and `spec:AST-005`, through the shared link
+ boundary.
+- The subtree link component — owned by `component:LinkProvider`.
+- Text typography and truncation — owned by `component:Text`.
+- Tooltip behavior — owned by `component:Tooltip`.
+- `useLinkify` and `useLinkComponent` — public hooks without their own module
+ records; uncontracted here beyond their use above.
+- Button-surface links — owned by `component:Button` link mode.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------- | ---------------- | --------- | -------------------------------------------------------------------------------------- |
+| Element form | link, disabled anchor, button | What Link renders (FR1). | Derived from `href`, `onClick`, `isDisabled`, and an inherited interactive role. | link when `href` is set | `component:Link` | Stable | A rejected destination renders an inert anchor (`family:navigation-destinations` FR6). |
+| External link | off, on | Opens in a new tab with an icon and new-tab text. | Link and disabled-anchor forms. | off | `component:Link` | Stable | Not applicable. |
+| Color | `primary`, `secondary`, `accent`, `disabled`, `placeholder`, `inherit`, plus augmented Text colors | Link text color. | Every form. | `accent` | `component:Link` | Stable | An augmented color colors the Text only; the root paints no color for it. |
+| Underline | on hover, always | When the underline shows. | Hover underline on enabled forms; `hasUnderline` underlines at rest in every form, disabled included. | on hover | `component:Link` | Stable | Not applicable. |
+| Standalone | off, on | Body font size outside running text. | Every form. | off | `component:Link` | Stable | Not applicable. |
+
+## Behavioral and layout contract
+
+| ID | Invariant | Basis |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| FR1 | Element form, in order: (a) `href` set and enabled → the link component from `as`, then `LinkProvider`, then a native anchor, with `href`, `target`, `rel`, and `onClick`. (b) Otherwise, `onClick` set → `<button type="button">`. (c) Otherwise an inherited interactive role decides: `button` → `<button type="button">`, `link` → the link component, or the disabled anchor of (d) when disabled. (d) Otherwise, `href` set and disabled → a plain `<a role="link">` with no `href`; otherwise `<button type="button">`. | `family:navigation-destinations` FR1, FR2; current source and tests |
+| FR2 | `isExternalLink` sets `target="_blank"`. Whenever `target` is `_blank`, `rel` contains `noopener` and `noreferrer` in addition to every caller token. `download` and `referrerPolicy` reach the element. | `family:navigation-destinations` FR5, AV4; current tests |
+| FR3 | An external Link that is not rendered as a button shows a trailing extra-small external-link icon that inherits the root's color, followed by visually hidden new-tab text: `newTabLabel`, else the localized default. | Current source and tests |
+| FR4 | A destination reaches the link component only through the shared navigation rule; a rejected destination renders an inert anchor and never invokes a router. | `family:navigation-destinations` FR1–FR6; `spec:AST-005` |
+| FR5 | A disabled Link stays focusable with `aria-disabled="true"`, never navigates, and never runs `onClick`. The disabled anchor form omits `href`, `target`, and `rel`, takes a Tab stop, and skips the custom link component. In every form, clicks are cancelled and stopped, Enter and Space are suppressed, other keys reach the caller's `onKeyDown`, and the Link paints at half opacity with no pointer events and no press paint. A focused Link that becomes disabled MUST keep focus and expose the change on that element (`spec:AST-085` FR4, FR5), and a caller `aria-disabled`, `role`, or `tabIndex` MUST NOT replace the disabled exposure (`architecture:public-component-api` INV5). Implementation gap: caller props spread after Link's own, so a caller `aria-disabled`, `role`, or `tabIndex` overrides them. Implementation gap: an enabled link renders through the safe link component and a disabled one as a plain anchor (or a `<button>` when it has `onClick`), so a focused link that becomes disabled (or re-enabled) is replaced and focus falls to the page. | `spec:AST-085` FR1, FR2, FR4, FR5; `family:navigation-destinations` FR7; current tests |
+| FR6 | Children render inside Text with `type` (default `body`), `size`, `weight`, `color` (default `accent`), `display` (default `inline`), and `maxLines` (default `0`). The root inherits font family, size, weight, and line height and lays content out with a small gap; `isStandalone` sets the body size and leading on the root. A Link inside a Text with `maxLines` MUST truncate with that text. Implementation gap: the root is `inline-flex`, so an ancestor Text clamp does not truncate it. | Current source and tests |
+| FR7 | The root paints the chosen color for the six built-in colors, which the underline and the external icon take; the label's color comes from Text (FR6). On hover-capable pointers an enabled Link underlines on hover, and for `primary`, `secondary`, and `accent` the root color mixes in the hover tint. `hasUnderline` underlines at rest. | Current source and tests |
+| FR8 | Press feedback follows `design:user-states` DR1 and DR2 for Link's text surface: an enabled link or button form paints the pressed overlay, and a disabled Link does not. | `design:user-states` DR1, DR2; current tests |
+| FR9 | `label`, when non-empty, becomes `aria-label` and replaces the content as the accessible name; a caller `aria-label` overrides it; otherwise the content is the name. | Current tests |
+| FR10 | With `tooltip`, Link renders inside a Tooltip that opens above it. | Current source and tests |
+| FR11 | The root carries `astryx-link` and reflects `data-color`. `ref`, `className`, `style`, `xstyle`, and other DOM props reach the root. Implementation gap: caller props spread after the theme props, so a caller `data-color` replaces the reflected one. | `architecture:component-theming-surface`; current tests; `architecture:public-component-api` INV5 |
+
+### Allowed variation
+
+- **AV1 — Content.** `children` may be text or caller content such as an icon;
+ Link does not inspect it.
+- **AV2 — Router.** Any link component accepted by the shared boundary may
+ render the link form.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| -------------------- | ----------------------------------------------------------------------------- | ----------------- |
+| Native link | Anchor with `href`; accent color; underline on hover. | Color, underline. |
+| Router link | Link component from `as` or `LinkProvider` receives the accepted destination. | Router. |
+| External link | `_blank`, `noopener noreferrer`, icon, and new-tab text. | `newTabLabel`. |
+| Button form | `<button type="button">` styled as a link; runs `onClick`. | — |
+| Disabled link | `<a role="link" aria-disabled="true" tabindex="0">` with no `href`; inert. | — |
+| Disabled button form | `aria-disabled` button; focusable; inert. | — |
+
+### Transformation and precedence order
+
+- **ORD1 — Element form.** FR1's order (a) → (d).
+- **ORD2 — Link component.** `as`, then `LinkProvider`, then a native anchor;
+ the disabled anchor form always uses a native anchor.
+- **ORD3 — Target and rel.** `isExternalLink` overrides `target`; a `_blank`
+ target then adds the two safety tokens to `rel`.
+
+### Performance and resources
+
+- **PR1 — No per-link listeners.** Link adds no global listener, observer, or
+ measurement; press feedback uses the shared document controller.
+
+## Accessibility contract
+
+- **AR1 — Role.** The link form exposes the link role; the disabled anchor
+ form sets `role="link"` explicitly; the button form exposes the button role.
+- **AR2 — Disabled.** A disabled Link keeps its Tab stop and exposes
+ `aria-disabled="true"` on the focusable element (FR5).
+- **AR3 — New tab.** An external link without `label` announces that it opens
+ in a new tab through visually hidden text; the icon adds no name (FR3). With
+ `label`, the label becomes the whole accessible name (FR9), so the new-tab
+ text is not announced unless the caller's label says it.
+- **AR4 — Name.** FR9. A `label` on a text link overrides its visible text.
+- **AR5 — Focus indicator.** Keyboard focus paints the shared focus outline;
+ visibility follows `architecture:interaction-modality` INV1.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | --------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Label | Text-colored label; underline on hover or always. | Current source and tests | Prominent | FR6, FR7 |
+| External icon | Extra-small trailing icon that inherits the root's color. | Current source and tests | Supporting | FR3 |
+| Disabled | Half opacity; no hover, press, or pointer interaction. | Current source and tests | Supporting | FR5 |
+
+`design:user-states` governs Link's pressed overlay (FR8); no other design record
+governs Link. The root carries the `link` target, which paints the underline and the
+external icon; the label is a Text and takes its color from Text's `text` target
+(`architecture:component-theming-surface` INV5). The consumer anatomy names no root part, so this record
+carries no anatomy-theming map.
+
+## Family and system relationships
+
+- `family:navigation-destinations` and `spec:AST-005` own destination
+ handling (FR4); Link is a member and keeps its own disabled semantics (FR7 of
+ the family).
+- `spec:AST-085` owns disabled focusability; Link meets FR1, FR2, and FR5's
+ steady-state exposure in every form, but not FR4 or FR5's transition clause
+ for a focused link with `href` (FR5 gap).
+- `component:LinkProvider` supplies the subtree link component (ORD2).
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, AR1 | `Link.test.tsx` element-form, `as`, and provider cases; `Link.a11y.chromium.spec.ts` | Native, router, button form, disabled | A wrong element form or role fails. Evidence gap: no test renders Link under an inherited interactive role (FR1 (c)). | `audit:Link/anatomy` |
+| FR2, FR3, AR3 | `Link.test.tsx` external, target, rel, and new-tab cases; `Link.a11y.chromium.spec.ts` external state | External; explicit `_blank`; custom label | A missing safety token, icon, or new-tab text fails. Evidence gap: no test checks the accessible name of an external link with `label`. Evidence gap: no test sets `referrerPolicy` or asserts the external icon's size or color. | `audit:Link/accessibility` |
+| FR4 | `Link.navigation.a11y.chromium.spec.ts` | Rejected and ordinary schemes; native, router, downloads | A rejected destination that navigates or reaches a router fails. | `audit:Link/behavior` |
+| FR5, AR2 | `Link.test.tsx` disabled cases | Disabled anchor; disabled button form; with `onClick` | Navigation, a consumer `onClick`, a lost Tab stop, or a custom component on a disabled link fails. Evidence gap: no test disables a focused link or passes a caller `aria-disabled`, `role`, or `tabIndex`. Evidence gap: no test asserts that other keys reach the caller's `onKeyDown`, or the half-opacity, no-pointer-events paint. | `audit:Link/accessibility` |
+| FR6 (type) | `Link.test.tsx` text-type cases | Default `body`; `type="inherit"` | A dropped Text `type` fails. Evidence gap: no test asserts that `size`, `weight`, `color`, `display`, or `maxLines` reach Text, or the `isStandalone` root size. | `audit:Link/visual` |
+| FR6, FR7 (paint) | Evidence gap: the color, underline, and standalone cases assert only that a link renders; hover paint is untested | Each color; `hasUnderline`; `isStandalone` | — | `audit:Link/visual` |
+| FR8 | `Link.test.tsx` pressed-state suite | Link, button form, disabled | No press paint, or press paint on a disabled Link, fails. | `audit:Link/behavior` |
+| FR9, FR11, AR4 | `Link.test.tsx` label, ref, and theme-class cases | With and without `label`; `data-color` | A missing or extra `aria-label`, target, `data-color`, or ref fails. The accessibility suites assert a passed `data-*` attribute and `aria-current` on the root, and the navigation suite asserts `download`. Evidence gap: no test passes both `label` and `aria-label`, or passes `className`, `style`, or `xstyle`. | `audit:Link/theming` |
+| FR10 | Evidence gap: the tooltip case asserts only that the link renders | Tooltip | — | `audit:Link/accessibility` |
+| ORD1–ORD3 | Covered by the FR1–FR3 rows | — | — | `audit:Link/behavior` |
+| PR1, AR5 | Evidence gap: no test asserts the absence of per-link listeners or the focus indicator | — | — | `audit:Link/accessibility` |
+
+## Current-state impact
+
+- **Caller attributes (FR5, FR11).** A caller `aria-disabled`, `role`,
+ `tabIndex`, or `data-color` replaces Link's own, against
+ `architecture:public-component-api` INV5.
+- **Becoming disabled (FR5).** A focused link with `href` that becomes disabled
+ is replaced by the plain disabled anchor, or by a `<button>` when it has
+ `onClick`, so keyboard focus falls to the page and the change is not exposed
+ on the focused element, against `spec:AST-085` FR4 and FR5.
+- **Ancestor line clamp (FR6).** The root is inline-flex, so an ancestor Text
+ `maxLines` clamp does not truncate a Link inside it.
+- **Consumer docs.** `Link.doc.mjs` anatomy lists Left icon and Right icon
+ parts; Link renders no icon slots, only caller content and the external icon
+ (FR3).
+
+## Decision log
+
+No component-local decision. Link applies `family:navigation-destinations` and
+`spec:AST-085`.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.
diff --git a/packages/core/src/Link/LinkProvider.spec.md b/packages/core/src/Link/LinkProvider.spec.md
new file mode 100644
index 0000000000..bc945f81f3
--- /dev/null
+++ b/packages/core/src/Link/LinkProvider.spec.md
@@ -0,0 +1,167 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:LinkProvider
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-26
+owners: [cixzhang]
+review_triggers: [public-api, behavior, navigation]
+verified_by:
+ [
+ packages/core/src/Link/useLinkComponent.test.tsx,
+ packages/core/src/Link/Link.test.tsx,
+ packages/core/src/Link/__tests__/Link.a11y.chromium.spec.ts,
+ ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: []
+architecture: [architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-005]
+---
+
+# LinkProvider component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract | None changes. LinkProvider takes a required `component` and `children`. |
+| Behavior | Every Astryx link in the subtree that resolves through the shared link boundary renders with `component`, unless a per-component `as` overrides it. The nearest provider wins. |
+| End-user impact | People get the app's client-side routing from Astryx links (no full page reload) where the app's router supports it. Unsafe destinations still never navigate. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. |
+| Review checks | Reject a provider that renders its own element, overrides an explicit `as`, leaks past a nearer provider, or lets a rejected destination reach `component`. |
+| Governing rules | `family:navigation-destinations` FR1, FR2, FR5, FR6, AV2; `spec:AST-005`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+LinkProvider lets an app swap the native anchor for its router's link component
+once, for every Astryx link in a subtree. It is a collaborator of
+`family:navigation-destinations`. Consumer usage lives in
+`LinkProvider.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; without a provider, links render native
+ anchors
+- Compatibility class: records shipped behavior; no public prop, default,
+ export, or DOM change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Supplying `component` to the subtree and its scoping.
+
+**Does not own / non-goals**
+
+- The router-facing `href` and `to` handoff, including the default `to` in FR3
+ — owned by the shared link boundary (`useLinkComponent`) under
+ `family:navigation-destinations`; the same default reaches an `as` component
+ without a provider.
+- Destination checks and inert rendering of rejected destinations — owned by
+ `family:navigation-destinations` FR6 and `spec:AST-005` FR7; FR4 points to
+ them.
+- When a component renders a link at all — owned by each component (for
+ example `component:Link` FR1 and `component:Button` FR11).
+- Imperative navigation from enlarged surfaces — owned by
+ `family:navigation-destinations` through its own hook.
+- The router component's own behavior.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| -------------- | ----------------------- | -------------------------------------------- | ----------------------------------------- | ------------- | ------------------------ | --------- | --------------------------------------------------------- |
+| Link component | any element type | Renders accepted link destinations in scope. | Inside the provider. | native anchor | `component:LinkProvider` | Stable | A component that ignores `href` and `to` cannot navigate. |
+
+## Behavioral and layout contract
+
+| ID | Invariant | Basis |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| FR1 | LinkProvider renders only its children and adds no element. | Current source |
+| FR2 | Inside the provider, a link rendered through the shared link boundary uses `component`. A per-component `as` wins over the provider; with neither, a native anchor renders. The nearest provider wins. | `family:navigation-destinations` FR2, AV2; current tests |
+| FR3 | Through the shared link boundary, `component` receives the accepted `href` and a `to` equal to `href` unless an accepted explicit `to` is supplied, which wins; a native anchor receives no `to`. LinkProvider only selects `component`. | `family:navigation-destinations` FR6; current tests |
+| FR4 | A rejected destination never reaches `component`; the inert rendering and destination checks follow `family:navigation-destinations` FR6 and `spec:AST-005` FR7. | `family:navigation-destinations` FR6; `spec:AST-005` FR7 |
+| FR5 | A component that renders no link in a given state does not use the provider: a disabled `component:Link` never renders the provider's component; which element it renders instead follows `component:Link` FR1 and FR5. | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Router shape.** `component` may be href-based or to-based; both
+ receive FR3's props.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ---------------------- | -------------------------------------------------------- | ----------------- |
+| No provider | Native anchors. | — |
+| Provider | `component` renders accepted links with `href` and `to`. | Router. |
+| Nested providers | The inner provider wins. | — |
+| `as` inside a provider | `as` wins for that link. | — |
+| Rejected destination | Inert native anchor; `component` not rendered. | — |
+
+### Transformation and precedence order
+
+- **ORD1 — Link component.** Per-component `as`, then the nearest
+ LinkProvider, then a native anchor.
+- **ORD2 — Router destination.** An accepted explicit `to`, then `href`.
+
+### Performance and resources
+
+- **PR1 — Stable value.** The provided value changes only when `component`
+ changes, so consumers do not re-render for an unchanged provider.
+
+## Accessibility contract
+
+- **AR1 — No semantics of its own.** LinkProvider adds no role, name, or
+ focus behavior; the link component it supplies is responsible for rendering
+ an accessible link from the props it receives.
+
+## Design relationships
+
+LinkProvider has no visual output. No design record governs it.
+
+## Family and system relationships
+
+- `family:navigation-destinations` names LinkProvider a collaborator; the
+ shared link boundary applies the family's destination rules before
+ `component` sees a destination.
+- Every component that renders a link through the shared link boundary
+ consumes it, for example `component:Link` and `component:Button` link mode.
+ A component that renders a native anchor directly, as the family's adoption
+ table lists, does not.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| --------- | --------------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- |
+| FR2, ORD1 | `useLinkComponent.test.tsx` provider cases; `Link.test.tsx` provider and `as` cases | Provider, nested providers, `as` override | The wrong component, or an outer provider winning, fails. | `audit:LinkProvider/behavior` |
+| FR3, ORD2 | `useLinkComponent.test.tsx` `to` suite | Provider and `as`; href-based and to-based routers | A missing or wrong `to`, or `to` on a native anchor, fails. | `audit:LinkProvider/behavior` |
+| FR4 | `useLinkComponent.test.tsx` scheme, structured, and inert suites | Rejected `href` or `to`; structured destinations | A rejected destination that reaches `component`, or a lost identity, fails. | `audit:LinkProvider/behavior` |
+| FR5 | `Link.test.tsx` disabled custom-component case | Disabled Link under a provider | A disabled Link rendered through `component` fails. | `audit:LinkProvider/behavior` |
+| AR1 | `Link.a11y.chromium.spec.ts` provider-router state | Link under a provider | A router link that loses the link role or name fails. | `audit:LinkProvider/accessibility` |
+| FR1, PR1 | Evidence gap: no test asserts that the provider adds no element or keeps a stable value | — | — | `audit:LinkProvider/behavior` |
+
+## Decision log
+
+No component-local decision. LinkProvider applies
+`family:navigation-destinations`.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.