An open source design system that's fully customizable and agent ready
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.ancestor-clamp.a11y.chromium.spec.ts, packages/core/src/Link/tests/Link.hoverColor.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, packages/core/src/Link/tests/Link.wrappedLines.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 | A theme restyles Link's label color through the link target; a text target color no longer reaches it. |
| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A focused link that becomes disabled loses focus, and caller attributes can replace Link's disabled exposure and data-color; both 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; the label inherits the root's color, so a theme restyles
Link's color through the
linktarget, not thetexttarget - 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.
targetandrelsafety and the external-link icon and new-tab text.- Link typography (through Text), color, underline, hover, press, and focus paint.
- The
linktarget.
Does not own / non-goals
- Destination acceptance and custom-router handoff — owned by
family:navigation-destinationsandspec: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. useLinkifyanduseLinkComponent— public hooks without their own module records; uncontracted here beyond their use above.- Button-surface links — owned by
component:Buttonlink 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; for a color the root paints, FR7, the label inherits it), display (default inline), and maxLines (default 0). The root inherits font family, size, weight, line height, and text alignment 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: there its root lays out inline, in the text's lines, unless the Link sets its own display or maxLines or renders as a button, and keeps its visible focus ring (an inset ring, architecture:interaction-modality INV1). A Link whose content is block-level is not supported inside a clamped Text, because it breaks the clamp. Link reads the enclosing Text's clamp, never its children (AV1). |
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 inherits the root's color at rest and on hover; a theme styles Link's color through the link target. On hover-capable pointers an enabled Link underlines on hover, and for primary, secondary, and accent the root color mixes in the hover tint, so the label, the underline, and the icon keep one color. 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.
childrenmay 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, thenLinkProvider, then a native anchor; the disabled anchor form always uses a native anchor. - ORD3 — Target and rel.
isExternalLinkoverridestarget; a_blanktarget then adds the two safety tokens torel.
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
labelannounces that it opens in a new tab through visually hidden text; the icon adds no name (FR3). Withlabel, 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
labelon a text link overrides its visible text. - AR5 — Focus indicator. Keyboard focus paints the shared focus outline;
visibility follows
architecture:interaction-modalityINV1.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Label | Takes the root's color; 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 label, the underline, and
the external icon; the label is a Text that inherits the root's color
(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-destinationsandspec:AST-005own destination handling (FR4); Link is a member and keeps its own disabled semantics (FR7 of the family).spec:AST-085owns 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 withhref(FR5 gap).component:LinkProvidersupplies 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 and clamp-display cases; Link.wrappedLines.a11y.chromium.spec.ts (wrapped text alignment); Link.ancestor-clamp.a11y.chromium.spec.ts (a default Link inside <Text maxLines={2}> is inline and the clamp cuts through it; a Link inside a one- and a two-line clamp shows the top and bottom edges of its inset focus ring; a composed Link outside a clamp keeps its box and focus outline) |
Default body; type="inherit"; wrapped button and anchor forms in a start-aligned, right-to-left and centred line |
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. A button form whose wrapped lines line up differently from the anchor form fails. |
audit:Link/visual |
| FR6, FR7 (paint) | Link.hoverColor.a11y.chromium.spec.ts (the hovered label, root, and icon share one computed color; the resting color returns); evidence gap: the underline and standalone cases assert only that a link renders |
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, ordata-colorreplaces Link's own, againstarchitecture:public-component-apiINV5. - Becoming disabled (FR5). A focused link with
hrefthat becomes disabled is replaced by the plain disabled anchor, or by a<button>when it hasonClick, so keyboard focus falls to the page and the change is not exposed on the focused element, againstspec:AST-085FR4 and FR5. - Consumer docs.
Link.doc.mjsanatomy 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.