@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Link/Link.spec.md

@@ -1,230 +0,0 @@
----
-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,
-    packages/core/src/Link/__tests__/Link.truncation.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; with `maxLines` above 0 it stops at its container, so its Text truncates inside a constrained line; `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. `Link.truncation.a11y.chromium.spec.ts`: an anchor and a button Link with `maxLines={1}` in a fixed-width line stop at the line and draw an ellipsis. Evidence gap: no test asserts that `size`, `weight`, `color`, or `display` 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.

package/src/Link/LinkProvider.spec.md

@@ -1,167 +0,0 @@
----
-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.