Skip to content

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

TypeScript

docs: define safe navigation destinations (#5796)

Cindy Zhangde42f11b516d
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md
index bd4d2fd305..28e925c732 100644
--- a/docs/architecture/public-component-api.md
+++ b/docs/architecture/public-component-api.md
@@ -24,7 +24,7 @@ verified_by:
packages/core/src/docPropLiterals.test.ts,
packages/core/src/docPropReferences.test.ts,
]
-deciding_specs: [spec:AST-002/DEC-1]
+deciding_specs: [spec:AST-002/DEC-1, spec:AST-005/DEC-1]
---
# Public component API
@@ -118,6 +118,9 @@ public promises until promotion.
evidence required by the release process.
- Changes to a family-owned API update the family contract rather than copying
its rule into this record or every component.
+- A component that accepts or derives a navigation destination follows
+ `family:navigation-destinations`. Adding a new sink or destination-bearing
+ component updates that family rather than creating a component-local URL rule.
## Owning code
@@ -131,6 +134,8 @@ public promises until promotion.
- `spec:AST-002/DEC-1` — a new public prop requires caller-owned information the
component cannot derive.
+- `spec:AST-005/DEC-1` — every Astryx-owned navigation exit follows one
+ destination-safety decision.
Transition Action sequencing and pending behavior belong to their component or
family contract. This record links that owner once it is current; it does not
diff --git a/docs/families/navigation-destinations.md b/docs/families/navigation-destinations.md
new file mode 100644
index 0000000000..b720eabec7
--- /dev/null
+++ b/docs/families/navigation-destinations.md
@@ -0,0 +1,204 @@
+---
+schema_version: 1
+template_version: 1
+kind: family
+id: family:navigation-destinations
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-31
+owners: [cixzhang, imdreamrunner]
+review_triggers: [behavior, accessibility, public-api]
+verified_by:
+ [
+ packages/core/src/Markdown/parser.test.ts,
+ packages/core/src/Markdown/Markdown.test.tsx,
+ packages/core/src/Link/useLinkComponent.test.tsx,
+ packages/core/src/ClickableCard/ClickableCard.test.tsx,
+ ]
+members:
+ [
+ component:Avatar,
+ component:BreadcrumbItem,
+ component:Button,
+ component:Citation,
+ component:ClickableCard,
+ component:Item,
+ component:Link,
+ component:ListItem,
+ component:Markdown,
+ component:NavHeadingMenuItem,
+ component:SideNavHeading,
+ component:SideNavItem,
+ component:Tab,
+ component:Token,
+ component:TopNavHeading,
+ component:TopNavItem,
+ component:TopNavMenu,
+ component:TopNavMegaMenuItem,
+ component:TopNavMegaMenuFeaturedCard,
+ component:TreeListItem,
+ ]
+architecture: [architecture:public-component-api]
+contributing: []
+deciding_specs: [spec:AST-005/DEC-1, spec:AST-005/DEC-2]
+---
+
+# Navigation destinations contract
+
+## Intent
+
+People should receive the same safe navigation behavior from every Astryx
+component that accepts or derives a destination. A component's visual role,
+router integration, or enlarged click target must not determine whether a
+blocked destination can execute.
+
+## Membership rule
+
+A component belongs when Astryx accepts or derives a destination that the
+component can render, delegate, or activate as navigation. Membership follows
+that observable responsibility rather than the component's visual category or
+which shared hook it currently uses.
+
+A component that only lays out caller-owned links does not join. A component that
+creates a fixed same-document link from an Astryx-owned ID does not join unless
+it also accepts caller-controlled destination text. Caller-owned JSX, plugin
+renderers, and callbacks are outside the boundary after Astryx hands over
+control.
+
+- **Current members:** Avatar; BreadcrumbItem; Button link mode; Citation;
+ ClickableCard; Item; Link; ListItem; Markdown links; NavHeadingMenuItem;
+ SideNavHeading and SideNavItem; navigation-mode Tab; Token link mode;
+ TopNavHeading, TopNavItem, TopNavMenu, TopNavMegaMenuItem, and
+ TopNavMegaMenuFeaturedCard; and TreeListItem.
+- **Collaborators:** `useLinkComponent`, `LinkProvider`,
+ `useClickableContainer`, React DOM's native-anchor sanitizer, and Markdown's
+ parser/render boundary.
+- **Excluded:** Outline's Astryx-generated `#id` links; AppShell's fixed
+ skip-to-content fragment; arbitrary links supplied as children; Markdown
+ plugin output; image/media/resource URLs; and components that only compose a
+ member without accepting or deriving its destination.
+
+Membership is open-ended. A newly shipped Core component that meets the rule
+must be added here even when it delegates to an existing member or shared hook.
+
+## Shared owner
+
+- `useLinkComponent` owns destination handoff to native and custom link
+ components, including the router-facing `href` and `to` seams.
+- `useClickableContainer` owns imperative navigation from enlarged surfaces,
+ including same-tab, new-tab, modifier-click, and middle-click paths.
+- Markdown owns parsing untrusted source into a destination and preserves the
+ shared navigation policy at its render boundary.
+- React DOM is the supported native-anchor sanitizer. Astryx owns every path
+ React does not mediate.
+
+## Canonical concepts
+
+| Concept | Values or states | Default semantics | Stability |
+| ------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------- |
+| destination source | caller prop, parsed content, Astryx-derived | caller/parsed values require inspection; fixed Astryx fragments are safe by construction | current |
+| sink | native anchor, custom router, imperative browser API | every Astryx-owned sink enforces the same navigation decision | current |
+| decision | accepted or blocked | accepted destinations keep existing behavior; blocked destinations do not navigate | current |
+| activation | plain, new-tab, modified, middle-click, programmatic proxy | activation method does not change the decision | current |
+| resource kind | navigation or embedded/fetched resource | this family owns navigation only | current |
+
+## Cross-component invariants
+
+- **FR1 — Every caller-controlled navigation destination is decided before its
+ sink.** No member may pass a destination to a custom router or imperative
+ browser API before the shared rule runs.
+- **FR2 — Alternate rendering keeps the rule.** Replacing a native anchor through
+ `LinkProvider` or `as` does not bypass destination handling.
+- **FR3 — Alternate activation keeps the rule.** `_blank`, Cmd/Ctrl-click,
+ middle-click, same-tab assignment, and delegated surface clicks produce the
+ same accept/block decision.
+- **FR4 — Blocked schemes cannot execute.** After browser-compatible scheme
+ normalization, `javascript:`, `vbscript:`, and `data:text/html` do not become
+ navigation.
+- **FR5 — Accepted destinations retain browser behavior.** Relative paths,
+ fragments, protocol-relative destinations, and ordinary schemes continue to
+ support native and router navigation, targets, and browser affordances.
+- **FR6 — Both custom-router props are sinks.** A supplied `href` and explicit
+ `to` are checked independently; neither can bypass the rule through prop
+ precedence or rest-prop ordering.
+- **FR7 — Disabled and rejected are distinct.** Members keep their own disabled
+ semantics. Rejecting a destination prevents navigation without inventing a
+ disabled state, label, or visual treatment.
+- **FR8 — Resource handling does not inherit navigation policy.** Images, media,
+ downloads, CSS URLs, and fetch targets use their own sink-specific contracts.
+ A member that handles both navigation and resources applies this family only
+ to its navigation path.
+
+## Allowed component variation
+
+- **AV1 — Rejected presentation.** Markdown may render rejected source as text;
+ a custom-link member may render without destination props; an enlarged surface
+ may simply omit imperative navigation. Each member preserves its own
+ non-navigation structure and accessibility contract.
+- **AV2 — Native versus router navigation.** Members may use React DOM anchors,
+ provider-level router components, per-component `as` overrides, or imperative
+ browser APIs when their public contract requires that mode.
+- **AV3 — Destination vocabulary.** Public APIs may expose `href`, structured
+ item data containing `href`, a Citation `url`, or parsed Markdown syntax. The
+ shared behavior does not require renaming released props.
+- **AV4 — Target and relationship.** Members retain their existing `target`,
+ `rel`, referrer, download, and external-link presentation behavior after a
+ destination is accepted.
+- **AV5 — Embedded resources.** Markdown and Citation may separately own image
+ or resource policy; those decisions do not alter this family's navigation
+ matrix.
+
+## Representative matrix
+
+| Member and state | Shared invariant | Deliberate variation |
+| --------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `component:Link` / native anchor | blocked destination does not execute | React DOM performs the native sink sanitization |
+| `component:Link` / custom provider or `as` | blocked `href`/`to` does not reach the router | router owns accepted client-side navigation |
+| `component:ClickableCard` / plain or modified click | every imperative or delegated exit uses the same decision | visible Card structure and nested-interactive handling remain local |
+| `component:Token` / link with remove action | surface activation and hidden link agree | remove action remains an independent sibling control |
+| `component:Markdown` / parsed link | blocked source does not become navigation | rejected source may render as text; resource policy remains separate |
+| navigation aggregate / member item | item destination uses the shared owner | tree, tab, breadcrumb, side-nav, top-nav, and menu semantics remain local |
+| `component:Citation` / linked source | blocked URL does not execute | native-anchor path and citation presentation remain local |
+
+## Adoption and exceptions
+
+| Components or surface | Adoption | Current deviation or limitation |
+| ------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Markdown parsed and rendered links | shared contract through parser/render checks | parser and renderer maintain separate implementations; conformance must keep navigation decisions aligned |
+| Native React anchors, including Citation | platform owner | relies on the supported React DOM sanitizer rather than the Core predicate |
+| `useLinkComponent` custom provider and `as` paths | pending shared owner | current `main` forwards raw `href`/`to`; #5524 is the accepted implementation |
+| `useClickableContainer` imperative paths | pending shared owner | current `main` sends raw destinations to `window.open`/`window.location`; #5524 is the accepted implementation |
+| Components composing the two shared hooks | inherited | complete only when the relevant shared-owner gap above closes |
+
+The pending rows are adoption gaps against FR1–FR6, not approved exceptions.
+When #5524 lands with exact-head evidence, this table must record shared adoption
+and include the new focused tests in `verified_by`.
+
+## Verification map
+
+| Contract | Verification | Representative members and states | Mutation or failure expectation |
+| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| FR1, FR2, FR6 | `useLinkComponent.test.tsx` | Link, Button, navigation members; provider and `as`; `href` and explicit `to` | A custom link receives a blocked destination or rest-prop order restores it |
+| FR1, FR3, FR4, FR5 | focused `useClickableContainer` tests required by `spec:AST-005` | ClickableCard and Token; plain, target, modified, middle click | A blocked imperative call occurs or an ordinary destination loses an activation mode |
+| FR4, FR5 | `parser.test.ts` and `Markdown.test.tsx` | parsed links, reference links, autolinks, mixed case, controls, relative and ordinary schemes | Markdown accepts a blocked scheme or rejects an ordinary navigation destination |
+| FR1, IR3 | source/member audit required by `spec:AST-005` | every caller-controlled Core navigation destination | A new sink or destination-bearing component ships outside this member snapshot |
+| FR7, FR8 | member-focused behavior and resource suites | disabled link modes; Markdown links versus images; Citation link versus image | Destination rejection changes disabled semantics or navigation policy silently becomes resource policy |
+
+## Decision links
+
+- `spec:AST-005/DEC-1` — destination safety follows every navigation sink.
+- `spec:AST-005/DEC-2` — embedded resources remain a separate policy.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file owns navigation-destination membership, the cross-component
+accept/block result, and adoption of the shared sinks. It does not duplicate
+component prop tables, router implementation details, component-local disabled
+or rendering behavior, embedded-resource policy, current audit results, or the
+system-spec rationale.
diff --git a/docs/specs/AST-005/spec.md b/docs/specs/AST-005/spec.md
new file mode 100644
index 0000000000..8efb42efbd
--- /dev/null
+++ b/docs/specs/AST-005/spec.md
@@ -0,0 +1,198 @@
+---
+schema_version: 1
+template_version: 1
+kind: system-spec
+id: spec:AST-005
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-31
+phase: accepted
+owners: [cixzhang, imdreamrunner]
+affects_architecture: [architecture:public-component-api]
+affects_families: [family:navigation-destinations]
+affects_contributing: []
+affects_consumer_docs:
+ [Link, Button, ClickableCard, Item, List, Token, Markdown]
+---
+
+# Safe navigation destinations
+
+## Intent
+
+A person activating an Astryx link should get the same destination safety no
+matter which component drew it, whether navigation is native or imperative, and
+whether a framework router replaced the native anchor. Component composition
+must not create a path around the shared rule.
+
+This spec accepts the shared navigation-destination contract. Current `main`
+already protects Markdown and native React anchors, but custom `LinkProvider`
+components and `useClickableContainer` imperative navigation do not yet apply the
+same rule. `family:navigation-destinations` records those adoption gaps until the
+implementation and verification land.
+
+## Non-goals
+
+- Validating URL syntax, requiring absolute URLs, or restricting destinations to
+ an allowlist of hosts.
+- Defining policy for image, media, download, CSS, fetch, or other embedded
+ resource URLs. Those sinks have different capabilities and content-type risks.
+- Sanitizing caller-owned JSX, custom Markdown plugin output, or arbitrary
+ consumer callbacks after control has left Astryx.
+- Replacing Content Security Policy, router authorization, server validation, or
+ application-level access control.
+- Adding a public prop that lets a component bypass or configure the rule.
+- Changing link labels, target/rel behavior, disabled semantics, or ordinary URL
+ resolution.
+
+## Requirements
+
+- **FR1 — One rule covers every Astryx-owned navigation exit.** Before Astryx
+ renders, delegates, or imperatively activates a caller-controlled navigation
+ destination, the destination MUST pass the contract in this spec. Moving from
+ a native anchor to a router component or enlarged clickable surface MUST NOT
+ weaken that contract.
+- **FR2 — Inspection follows browser scheme normalization.** Scheme inspection
+ MUST remove ASCII control characters `U+0000–U+001F` and `U+007F`, trim outer
+ whitespace, and compare ASCII scheme text case-insensitively. This prevents a
+ blocked scheme from being hidden by characters the browser ignores.
+- **FR3 — Executable document schemes are blocked.** A normalized navigation
+ destination beginning with `javascript:`, `vbscript:`, or `data:text/html`
+ MUST NOT become executable navigation. The check applies before query, hash,
+ target, modifier-key, or pointer-button differences can select another sink.
+- **FR4 — Ordinary destinations keep working.** Relative paths, same-document
+ fragments, protocol-relative URLs, and ordinary schemes such as `http:`,
+ `https:`, `mailto:`, and `tel:` MUST retain their existing navigation behavior.
+ This contract does not rewrite, resolve, or host-filter accepted destinations.
+- **FR5 — Native, custom, and imperative paths are all covered.** The contract
+ MUST hold for React DOM anchors, a custom component supplied through
+ `LinkProvider` or an `as` seam, and imperative exits including `window.open`
+ and `window.location`. Middle-click and Cmd/Ctrl-click are not exceptions.
+- **FR6 — Rejection fails closed at the navigation boundary.** A blocked
+ destination MUST NOT be handed to a navigation-capable custom-router prop or
+ imperative browser API. The component MAY preserve non-navigation rendering
+ and consumer callbacks when doing so cannot activate the rejected destination.
+- **FR7 — Router destination props are independent sinks.** When a custom link
+ component can receive both `href` and `to`, each supplied value MUST pass the
+ rule independently. An explicit safe `to` MAY retain its documented precedence;
+ an unsafe explicit `to` MUST NOT ride through a rest-prop spread or fall back to
+ an unrelated unchecked value.
+- **FR8 — Parser and rendering checks agree for navigation.** Markdown parsing,
+ Markdown link rendering, and shared Core navigation plumbing MUST reject the
+ same blocked navigation schemes after the same normalization. Markdown MAY use
+ a stricter policy for embedded resource URLs without narrowing this navigation
+ contract.
+- **IR1 — Shared exits use a shared owner.** Core components that delegate links
+ or navigate imperatively MUST use one shared policy owner rather than maintain
+ component-local blocked-scheme lists. Parser-local implementations MAY remain
+ separate only while conformance tests pin the same navigation matrix.
+- **IR2 — Every distinct sink has mutation-sensitive coverage.** Verification
+ MUST fail when the guard is removed from custom `href`, custom `to`, new-tab,
+ modified-click, middle-click, plain imperative navigation, or Markdown link
+ parsing/rendering.
+- **IR3 — New navigation surfaces join the family.** A new component or hook that
+ accepts a caller-controlled navigation destination MUST join
+ `family:navigation-destinations` and reuse the shared owner before shipping.
+
+### Platform support
+
+- Supported feature/engine floor: every browser and framework-link integration
+ supported by Astryx Core.
+- Unsupported behavior: a custom component that ignores the filtered destination
+ props or manufactures a destination from other caller data is outside the
+ guarantee; Astryx MUST NOT claim that caller-owned behavior is sanitized.
+- Browser evidence: real Chromium verifies that blocked native and imperative
+ destinations do not execute and that ordinary relative, external, modified,
+ and middle-click navigation remains available. Unit integration tests verify
+ custom router props without requiring a particular router package.
+
+## Current-state impact
+
+`family:navigation-destinations` is the complete shared owner for the behavior.
+Its membership covers every current Core component that accepts or derives a
+navigation destination, including aggregate component records whose public
+members own the actual `href`.
+
+Current `main` has three implementations:
+
+1. React DOM protects native anchor `href` values.
+2. Markdown checks parsed and rendered destinations before creating links.
+3. Custom `LinkProvider` components and `useClickableContainer` imperative exits
+ currently receive raw destinations; this is the gap addressed by #5524.
+
+Implementation of this accepted spec must:
+
+1. add one shared Core navigation predicate for custom-link and imperative exits;
+2. apply it to `href` and explicit `to` before custom link delegation;
+3. apply it before every `window.open` and `window.location` assignment in
+ `useClickableContainer`;
+4. preserve the existing safe ordinary-destination behavior and the delegated
+ `interactiveRef.click()` path;
+5. keep Markdown's navigation rule conformant while leaving embedded-resource
+ policy separate; and
+6. update `family:navigation-destinations` from partial adoption to shared
+ adoption when exact-head verification is green.
+
+No component-local public prop is added. Consumer documentation should state the
+shared outcome where a component documents an `href` or router seam; it should
+link to the shared rule rather than reproduce a scheme list in every prop row.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| FR2, FR3, FR4, FR8 | Shared predicate and Markdown parser/render suites | mixed case; embedded controls; relative/hash; http(s); mailto/tel; blocked schemes | Removing normalization or changing one blocked prefix makes the navigation matrices disagree |
+| FR5, FR6, FR7 | `useLinkComponent` integration tests | native anchor; provider component; `as`; safe/unsafe `href`; safe/unsafe explicit `to` | A blocked value reaches `href` or `to`, or an ordinary explicit `to` loses precedence |
+| FR1, FR3, FR5, FR6 | `useClickableContainer` integration tests | plain click; `_blank`; Cmd/Ctrl-click; middle-click; delegated interactive ref | A blocked value reaches `window.open`/`window.location`, or an ordinary navigation path stops working |
+| FR1, IR1, IR3 | Family membership and source-usage audit | every current `useLinkComponent`, `useClickableContainer`, Markdown, and direct native-anchor destination owner | A new caller-controlled navigation sink ships outside the family or duplicates a local rule |
+| Browser contract | Real Chromium probe | native anchor, custom-router stand-in, imperative same-tab/new-tab, modified and middle click | Script executes, blocked navigation occurs, or ordinary browser affordances regress |
+
+### Completion criteria
+
+This spec moves from `accepted` to `shipped` only when:
+
+- every adoption gap in `family:navigation-destinations` is closed or documented
+ as an explicit owner-approved exception;
+- exact-head tests cover each distinct custom and imperative sink;
+- a source/member audit finds no caller-controlled Core navigation exit outside
+ the family; and
+- consumer docs describe the shared outcome without implying that embedded
+ resources or caller-owned renderers receive the same policy.
+
+## Decision log
+
+### DEC-1 — Destination safety follows the navigation sink
+
+**Reference:** `spec:AST-005/DEC-1`
+**Decider:** `cixzhang`, `2026-08-31`
+
+Every Astryx-owned path that can activate a caller-controlled navigation
+destination follows one normalized blocked-scheme rule. The guarantee survives
+component composition, custom framework routers, modified clicks, middle clicks,
+and imperative navigation because those are alternate exits for the same user
+intent.
+
+Rejected: relying only on React DOM. React can protect an `href` it renders, but
+it does not inspect props handed to a custom router and does not mediate
+`window.open` or `window.location`.
+
+### DEC-2 — Embedded resources remain a separate policy
+
+**Reference:** `spec:AST-005/DEC-2`
+**Decider:** `cixzhang`, `2026-08-31`
+
+Navigation destinations and embedded resources are separate sink families. This
+spec blocks executable document schemes for navigation without deciding which
+`data:` media types, image sources, downloads, or fetched resources are allowed.
+Markdown may therefore reject a broader resource set while matching the shared
+navigation matrix.
+
+Rejected: one undifferentiated “safe URL” boolean for every URL-shaped value.
+That hides material differences between navigating a document and embedding or
+fetching a resource, and would accidentally broaden or narrow unrelated public
+behavior.
+
+## Open questions
+
+None.
diff --git a/packages/core/src/Markdown/Markdown.spec.md b/packages/core/src/Markdown/Markdown.spec.md
index ca76b34e11..586e54aeaa 100644
--- a/packages/core/src/Markdown/Markdown.spec.md
+++ b/packages/core/src/Markdown/Markdown.spec.md
@@ -16,11 +16,11 @@ verified_by:
packages/core/src/theme/themingTargets.test.ts,
scripts/check-knowledge.mjs,
]
-families: []
+families: [family:navigation-destinations]
design_specs: []
architecture: [architecture:component-theming-surface]
contributing: []
-system_specs: []
+system_specs: [spec:AST-005/DEC-1, spec:AST-005/DEC-2]
---
# Markdown component contract
@@ -166,6 +166,12 @@ and this change preserves the existing spelling exactly.
- `architecture:component-theming-surface` owns anatomy qualification, target
mapping, target-capability state, composition boundaries, and compatibility for
frozen targets.
+- `family:navigation-destinations` owns the shared accept/block result for parsed
+ links and every Astryx-owned navigation sink. `spec:AST-005/DEC-1` requires
+ Markdown navigation to remain conformant with Core link plumbing.
+- `spec:AST-005/DEC-2` keeps embedded-resource policy separate. Markdown may
+ reject a broader set of image/resource URLs without narrowing the shared
+ navigation contract.
- Nested Astryx primitives retain ownership of their own anatomy and targets;
Markdown owns the outer block targets listed here.
diff --git a/packages/core/src/NavMenu/NavHeadingMenu.spec.md b/packages/core/src/NavMenu/NavHeadingMenu.spec.md
index 39191a4758..e37c422e85 100644
--- a/packages/core/src/NavMenu/NavHeadingMenu.spec.md
+++ b/packages/core/src/NavMenu/NavHeadingMenu.spec.md
@@ -18,7 +18,7 @@ verified_by:
packages/core/src/theme/themingTargets.test.ts,
scripts/check-knowledge.mjs,
]
-families: []
+families: [family:navigation-destinations]
design_specs: []
architecture:
[
@@ -28,7 +28,7 @@ architecture:
architecture:public-component-api,
]
contributing: []
-system_specs: []
+system_specs: [spec:AST-005/DEC-1]
---
# NavHeadingMenu component contract
@@ -173,7 +173,11 @@ owns the layer lifecycle and supplies the close callback through context.
heading-provided close callback.
- `architecture:public-component-api` owns the stable props and subcomponent
surface; this documentation adds no API.
-- NavHeadingMenu has no current family contract.
+- `family:navigation-destinations` owns the shared accept/block result for a
+ NavHeadingMenuItem `href`; `spec:AST-005/DEC-1` requires native and
+ custom-router item paths to preserve that result.
+- NavHeadingMenu's current custom-router path inherits the `useLinkComponent`
+ adoption gap recorded by the family until the accepted implementation lands.
## Verification map
diff --git a/packages/core/src/TreeList/TreeList.spec.md b/packages/core/src/TreeList/TreeList.spec.md
index 4014d3e544..877f364bff 100644
--- a/packages/core/src/TreeList/TreeList.spec.md
+++ b/packages/core/src/TreeList/TreeList.spec.md
@@ -16,7 +16,7 @@ verified_by:
packages/core/src/theme/themingTargets.test.ts,
scripts/check-knowledge.mjs,
]
-families: []
+families: [family:navigation-destinations]
design_specs: []
architecture:
[
@@ -25,7 +25,7 @@ architecture:
architecture:public-component-api,
]
contributing: []
-system_specs: []
+system_specs: [spec:AST-005/DEC-1]
---
# TreeList component contract
@@ -183,8 +183,11 @@ authorize a new target.
surface; this documentation adds no API.
- `architecture:interaction-modality` owns shared keyboard and pointer modality;
TreeList continues to own its existing tree focus and activation behavior.
-- TreeList has no current family contract, and no unresolved family or runtime
- record identifier is included.
+- `family:navigation-destinations` owns the shared accept/block result for a
+ TreeListItem `href`; `spec:AST-005/DEC-1` requires native and custom-router
+ item paths to preserve that result.
+- TreeList's current custom-router path inherits the `useLinkComponent` adoption
+ gap recorded by the family until the accepted implementation lands.
## Verification map