---
title: "Link"
description: "Text that leads somewhere, as a phrase in a sentence, a line by itself, or a glyph alone. In the text style of where it sits, underlined as your design system chooses, and marked where it leaves the site."
url: "https://tanrei.chnotchy.com/components/link/"
last_updated: 2026-10-23T21:17:12.000Z
---

# Link

> Text that leads somewhere, as a phrase in a sentence, a line by itself, or a glyph alone. In the text style of where it sits, underlined as your design system chooses, and marked where it leaves the site.

## Overview

The rule a product can apply without a table: **if it has an address it is a link; if it has none it is a button.** A control that does something on the page and leads nowhere is a [Button](https://tanrei.chnotchy.com/components/button/), the text variant where it should read as quietly as text. A destination that should look like a button is a Button with `href`.

### Usage

On the web the link is a class on your own anchor, not an element. The anchor is in the document, so it is a link before any script runs, and a crawler, a search index and a router that works on the page’s anchors all find it. A router’s own link component takes the class. Every anchor inside `.tanrei-prose` is drawn the same way without a class, so rendered Markdown needs nothing.

SwiftUI, Compose, Flutter and React Native are planned: the names beside each platform at the top of this page are the ones the spec gives them, and nothing ships there yet. React has no `Link` component yet either, so use the anchor with the class.

**Web**

```html
<link rel="stylesheet" href="@tanrei/web/tokens.css" />
<link rel="stylesheet" href="@tanrei/web/icons.css" />
<link rel="stylesheet" href="@tanrei/web/link.css" />

<!-- In a sentence. -->
<p>Read <a class="tanrei-link" href="/guides/accessibility/">the accessibility guide</a> first.</p>

<!-- By itself: the hit area reaches the minimum target. -->
<a class="tanrei-link" data-standalone href="/getting-started/">Getting started</a>

<!-- A new tab: the mark is drawn for you. Say it in words too. -->
<a class="tanrei-link" href="https://example.com/" target="_blank" aria-description="opens in a new tab">the source code</a>

<!-- Another site, opening where the person is: an arrow after the label, and the words for it. -->
<a class="tanrei-link" href="https://example.com/" data-external="true" aria-description="external link">the standard</a>

<!-- With that site's icon: an image your own site serves, the anchor's first child. -->
<a class="tanrei-link" href="https://example.com/" data-external="true" aria-description="external link"><img
  class="tanrei-link-site-icon" src="/icons/example-com.png" alt="" width="32" height="32"
  loading="lazy" decoding="async" referrerpolicy="no-referrer">the standard</a>

<!-- One link set apart from the design system's underline: always, hover or never. -->
<a class="tanrei-link" data-standalone data-underline="hover" href="/about/">About</a>

<!-- A region with its own choice: every link inside follows it. -->
<footer style="--tanrei-comp-link-underline-visibility: never">…</footer>

<!-- A glyph, written against the text with no space between them. -->
<a class="tanrei-link" data-standalone href="/tokens.zip"><span class="tanrei-icon" aria-hidden="true">download</span>Download the tokens</a>
<a class="tanrei-link" data-standalone data-icon-position="trailing" href="/tokens/">Next: Tokens<span class="tanrei-icon" aria-hidden="true">arrow_forward</span></a>

<!-- A glyph alone, named by aria-label. -->
<a class="tanrei-link" href="#installation" aria-label="Link to Installation"><span class="tanrei-icon" aria-hidden="true">link</span></a>

<!-- The current page, a link that cannot be followed now, and a link on an inverse surface. -->
<a class="tanrei-link" data-standalone href="/components/" aria-current="page">Components</a>
<a class="tanrei-link" data-standalone role="link" aria-disabled="true">Previous page</a>
<a class="tanrei-link" data-variant="inverse" href="/changes/">what changed</a>

<script type="module">
  // Optional: ripple and dim feedback, noopener, refusals and debug reports. `@tanrei/web` loads it too.
  // It also marks the links that leave the site, where the page was not marked when it was made.
  import { setSiteOrigins, setExternalLabel } from '@tanrei/web/link';
  setSiteOrigins(['https://docs.example.com']); // origins that are part of your own site
  setExternalLabel('external link');            // the words, once for the page, in your language
</script>
```

**React**

```tsx
import '@tanrei/web/link.css';
import '@tanrei/web/link';
import { Link as RouterLink } from 'react-router-dom';

<a className="tanrei-link" href="/guides/accessibility/">the accessibility guide</a>

{/* A router's link renders its own anchor: give it the class. */}
<RouterLink className="tanrei-link" data-standalone to="/getting-started/">Getting started</RouterLink>
```

| Prop | On the web |
| --- | --- |
| `href` | `href` |
| `target: new` | `target="_blank"` |
| `targetLabel` | `aria-description` |
| `variant: inverse` | `data-variant="inverse"` |
| `standalone` | `data-standalone` |
| `iconPosition: trailing` | `data-icon-position="trailing"` |
| `current` | `aria-current="page"` (or another of its values) |
| `disabled` | `role="link" aria-disabled="true"`, and no `href` |
| `label` | `aria-label` |
| `underline` | `data-underline="always"`, `"hover"` or `"never"`; without it, the design system’s choice |
| `external: on`, `off` | `data-external="true"`, `data-external="false"`; without it, the address decides |
| `externalLabel` | `aria-description` |
| `siteIcon` | your own `<img class="tanrei-link-site-icon" alt="">`, the anchor’s first child |

## Specs

A link brings no text style of its own: it takes the family, size, weight and line height of the text it sits in, in a paragraph, a heading, a caption or a table cell alike. Hover, focus and press are drawn behind its text on each line it runs over, and take no room, so nothing around a link moves. A glyph, the site’s icon and the mark are the size of the text and stay on the line of the word beside them.

**When the underline is drawn is a choice** with three values. `always` draws it at rest and in every state. `hover` draws it while the link is hovered, focused from the keyboard or pressed. `never` draws none, and hover, focus and press are still shown by the state layer, the label color and the focus ring. The choice is set at three levels: `sys.behavior.link-underline` for every text link of a design system, `comp.link.underline.visibility` for the Link alone, and the `underline` prop for one link. The default system chooses `always`. On the web the component token is a custom property, so a region such as a footer can carry its own value. The current link and a glyph alone have no underline under any choice, and forced colors draw it under every choice.

**A link that leaves the site says so.** An external link shows the glyph `arrow_outward` after its label and, where you give one, the icon of that site before it. `external` is `auto`, `on` or `off`. Under `auto` an `http` or `https` address of another origin than the page’s is external; a path, a fragment, a mail address, a telephone number and a download never are. Declare the other origins of your own site once, and they are not external either. `comp.link.external.marks` turns the icon off (`arrow`) or both marks off (`none`) for the whole product.

Leaving the site and opening a new tab are two facts. The place after the label holds one glyph: `open_in_new` for a link with `target="_blank"`, external or not, and otherwise `arrow_outward` for an external link. Your own glyph at the trailing side replaces either, and a glyph alone has neither.

**The link never fetches an icon.** `siteIcon` is an image you give: one your own site serves, made when the site is built. A component that asked the destination, or an icon service, for it would tell that party which page each reader is on. Where no icon is given the link shows the arrow alone. An icon that cannot be loaded keeps its room and draws nothing.

- Category: Navigation
- Level: base
- Listing: default
- Page: https://tanrei.chnotchy.com/components/link/
- Spec: https://github.com/chnotchy/tanrei/blob/main/specs/link.spec.json

### Availability

| Design system | Has it | Notes |
| --- | --- | --- |
| Tanrei (`tanrei`) | Yes | — |
| Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — |
| M3 Expressive-like (Material 3 Expressive-inspired) (`m3-expressive-like`) | Yes | — |
| M3-like (Material 3-inspired) (`m3-like`) | Yes | — |

### Platforms

- Web: the class `tanrei-link` on the product's own element, styled by `@tanrei/web/link.css`.

| Platform | Name | Status |
| --- | --- | --- |
| Web | `tanrei-link` | lagging |
| SwiftUI | `TanreiLink` | planned |
| Jetpack Compose | `TanreiLink` | planned |
| Flutter | `TanreiLink` | planned |
| React Native | `Link` | planned |

Names a platform gives in its own idiom:

| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
| --- | --- | --- | --- | --- | --- |
| `href` (prop) | `href` | `destination` | `href` | `href` | `href` |
| `targetLabel` (prop) | `aria-description` | `targetLabel` | `targetLabel` | `targetSemanticLabel` | `targetLabel` |
| `external` (prop) | `data-external` | `external` | `external` | `external` | `external` |
| `externalLabel` (prop) | `aria-description` | `externalLabel` | `externalLabel` | `externalSemanticLabel` | `externalLabel` |
| `siteIcon` (prop) | `img.tanrei-link-site-icon` | `siteIcon` | `siteIcon` | `siteIcon` | `siteIcon` |
| `variant` (prop) | `data-variant` | `variant` | `variant` | `variant` | `variant` |
| `underline` (prop) | `data-underline` | `underline` | `underline` | `underline` | `underline` |
| `standalone` (prop) | `data-standalone` | `TanreiLink` | `TanreiLink` | `TanreiLink` | `standalone` |
| `iconPosition` (prop) | `data-icon-position` | `iconPosition` | `iconPosition` | `iconAlignment` | `iconPosition` |
| `current` (prop) | `aria-current` | `isCurrent` | `current` | `isCurrent` | `current` |
| `disabled` (prop) | `aria-disabled` | `disabled` | `enabled` | `enabled` | `disabled` |
| `label` (prop) | `aria-label` | `label` | `contentDescription` | `semanticLabel` | `accessibilityLabel` |
| `click` (event) | `click` | `action` | `onClick` | `onPressed` | `onPress` |

Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal.

### Anatomy

- `container`: The shape behind the link's text, on each line the link runs over. It has no fill at rest and takes no room in the layout: it is where hover, focus and press are drawn.
- `label` (optional): The link's text, in the text style of the text it sits in. It wraps with that text and is never cut.
- `underline`: The line under the label, in the label's color. When it is drawn is a choice (LNK-27): at rest and in every state, only while the link is pointed at, focused from the keyboard or pressed, or never. In the default system it is drawn at rest, where it is what tells a link from the text beside it. The current link and a link that is a glyph alone have none.
- `icon` (optional): A glyph of the system's icon set that the product names, before or after the label, or alone (a heading's anchor). Decorative beside a label; alone, the link is named by label.
- `site-icon` (optional): A small picture of the site an external link leads to, before the label. The product gives it; the link never fetches one by itself (LNK-32, LNK-35). Decoration: the label names the link.
- `mark` (optional): The one glyph after the label that says where following the link takes the person: open_in_new for a link that opens a new context, arrow_outward for a link that leaves the site and opens where the person is (LNK-31). Never both. Drawn by the link where the product has put no glyph of its own there.
- `focus-ring`: The indicator shown for keyboard focus, around the link's part of each line it runs over.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | `""` | The destination: an address as the platform's links take one (a URL; on the web a path or a fragment as well). A link without a destination is not a link: it is drawn as the text around it and reported (LNK-21). |
| `target` | `enum`: `same`, `new` | `"same"` | Where the destination opens. same: where the person is — the same tab on the web, the app's own handling of the address elsewhere. new: a new context — a new tab or window on the web, outside the current screen elsewhere — which a link with a label marks with the glyph open_in_new after it and says through targetLabel (LNK-13). Whether the destination is another site is a second fact, external's (LNK-30): a link may leave the site without opening a new context, and open one without leaving. |
| `targetLabel` | `string` | `""` | What assistive technology reads after the link's name while target is new ("opens in a new tab"). Tanrei ships no words of its own, so the product gives them in its language. Required while target is new; ignored otherwise. |
| `external` | `enum`: `auto`, `on`, `off` | `"auto"` | Whether the destination is on another site than the one the person is on. auto: the link decides, where the platform can tell (LNK-30) — on the web an address of another origin than the page's and the product's declared own; elsewhere an address outside the hosts the product has declared. on: it is external, whatever the address. off: it is not, and the link shows and says nothing of it. An external link with a label shows an arrow after it and, where siteIcon is given, that site's picture before it (LNK-31, LNK-32); a design system or a product turns either off for every link with comp.link.external.marks. It changes nothing about where or how the destination opens. |
| `externalLabel` | `string` | `""` | What assistive technology reads after the link's name while the link is external and target is same ("external link"), in the product's language. Empty, the words the product has set once for every external link are read (LNK-34). Ignored while target is new: targetLabel is then the link's one description. |
| `siteIcon` | `string` | `""` | The picture of the site an external link leads to: the address of an image as the platform's images take one (on the web a URL the page may load — of the product's own origin, or a data URL), or the platform's own image value. Drawn before the label while the link is external (LNK-32); ignored otherwise. The link never derives it from href and never asks the destination or anyone else for it (LNK-35): the product gives a picture it has, made where the product is built. Empty, the link shows the arrow alone. |
| `variant` | `enum`: `standard`, `inverse` | `"standard"` | Which surface the link is drawn for. standard: the product's ordinary surfaces and its quiet containers. inverse: a surface of the opposite theme (a snackbar's, a tooltip's, a dark band on a light page), where the standard link color is not readable. It changes colors only. A design system may add values. |
| `underline` | `enum`: `auto`, `always`, `hover`, `never` | `"auto"` | When the label is underlined. always: at rest and in every state. hover: while the link is hovered, focused from the keyboard or pressed, and not at rest. never: in no state. Auto takes comp.link.underline.visibility, the design system's answer (always in the default system). hover and never are for a link that stands by itself among other links — a list of navigation, a footer — where its place says what it is; inside running text use them only where the link color stands 3:1 apart from the text's (LNK-29). |
| `standalone` | `boolean` | `false` | False: the link is part of a sentence or a line of text, and its target is its own text (LNK-17). True: the link stands by itself — under a paragraph, in a table cell, in a row of links — and its hit area is extended to the minimum target without changing how it is drawn or laid out. It changes nothing a person sees. |
| `iconPosition` | `enum`: `leading`, `trailing` | `"leading"` | Which side of the label the glyph sits on, in the reading direction. Ignored when the link has no label or no glyph. |
| `current` | `boolean` | `false` | The link names the place the person is already at, in a set of navigation: the current page in a row of site links or a trail of pages, the current section in a table of contents. It is exposed as the current item, drawn without an underline, whatever underline says, at the emphasized weight, and stays a link (LNK-18). At most one link of a set is current; the set, not the link, decides which. |
| `disabled` | `boolean` | `false` | The link cannot be followed now (the previous page of the first page): it keeps the link role with the disabled state and no destination, leaves the focus order and opens nothing (LNK-19). |
| `label` | `string` | `""` | The accessible name of a link that is a glyph alone ("Link to Installation"), in the product's language. Ignored while the link has a label of text, which names it. |

### Events

| Event | Description |
| --- | --- |
| `click` | The link was activated by pointer, touch, Enter or assistive technology. It is emitted before the destination opens; a product that takes the navigation itself (a client-side router) cancels it (LNK-12). |

### Slots

| Slot | Description |
| --- | --- |
| `default` | The label: the text that says where the link goes. Leave it empty for a link that is a glyph alone. |
| `icon` | The glyph: a glyph of the system's icon set, drawn through the platform's icon helper at the size of the link's text. With a label it sits at the side iconPosition names; without one it is the link's only content. At the leading side it stands where an external link would show the site's picture, and at the trailing side where it would show its arrow or the mark of a new context: the product's glyph stands and the link draws nothing of its own there. |

### States

`enabled`, `disabled`, `hovered`, `focused`, `pressed`

### Accessibility

- Role: `link`
- Labeling: A link with a label is named by the label's text, which should say where it goes without the sentence around it ("the installation guide", not "here"). A link that is a glyph alone is named by label, which is required; its glyph is decorative to assistive technology. A link has at most one description: while target is new it is targetLabel ("opens in a new tab"); otherwise, while the link is external and marked, it is externalLabel or the product's words for every external link ("external link"). The mark, the arrow and the site icon are decorative. A current link carries the current state; nothing is added to its name.
- Minimum target size: yes

| Keys | Action |
| --- | --- |
| Tab | Moves focus to the link. A disabled link is passed. |
| Enter | Follows the link. Space does what it does on any link (on the web it scrolls the page). |

- A link in running text is told from the words beside it by more than color (WCAG 1.4.1). In the default system the link color is the primary's, which is the color of the text itself — 1.00:1 against sys.color.on-surface in all six schemes — so the underline is the only thing that says "link": the default system's choice is always, and the build fails if it is changed while the colors stand as they are.
- When the underline may be left out at rest. A design system or a product may choose hover or never where its link color stands 3:1 or more apart from its text color in every scheme and still keeps its own contrast on the surfaces; a cue then remains for the pointer and the keyboard — the line itself under hover, the state layer and the focus ring under never. The build checks the ratio for the system-wide choice and for the component's own (an error in the default system, a warning in a product's layer). It cannot check one link set apart by the underline prop: that is the product's to judge, and a debug build reports an in-text link that fails it (LNK-29). hover is not a weaker never on a touch screen: there is no pointer to bring the line back, so the two are held to the same ratio.
- Links that stand by themselves — a list of navigation, a footer, a row of related pages — are what hover and never are for: their place in a list says what they are, and no word beside them competes. Set underline on those links, or give the region its own value of the component token, and leave the links of sentences underlined.
- Forced colors draw the underline whatever was chosen (LNK-22): the link color is then the platform's, and nothing the design system measured still holds.
- An external link says so twice, once for the eye and once in words: the arrow after the label, and a description read after the name (LNK-34). The arrow is not the mark of a new context: a link that leaves the site and opens where the person is shows arrow_outward; one that opens a new tab or window shows open_in_new, external or not, and its description is targetLabel. A link never shows both, and is never described twice.
- The site's picture is decoration: it has no text alternative and no role, it is never the only thing that marks a link as external (the arrow is always there with it), and a link without one loses nothing a person needs. It is a picture someone else drew, so its contrast against the surface is not the design system's to hold; a picture that cannot be seen on a dark or a light surface is given a ground where it is made, not by the link.
- A link calls no one. It draws only what the product gave it and reaches no other site before the person follows it (LNK-35): reading a page that links to a site tells that site nothing.
- The target. A link inside a sentence or a line of text takes WCAG 2.5.8's exception for inline targets: its hit area is its text, and extending it would take presses meant for the lines above and below. A link that stands by itself (standalone) and a link that is a glyph alone are not in a sentence, so their hit area is extended to sys.target without changing what is drawn (LNK-17); the product leaves sys.target.spacing between two of them, or lets their rows be a target high.
- A link is not a button. What leads nowhere and does something on the page is a Button — the text variant where it should read as quietly as text — and it is activated by Space as well as Enter. A link is never given a press handler in place of a destination (LNK-21).
- No visited state (LNK-20). A product whose content is a list of places people work through (search results, a reading list) marks what was opened from its own data, with a Tag or a glyph, which every platform can draw and assistive technology can read.
- The current link stays a link: it can be focused and followed, and leads to the top of the page the person is on. It is told from its neighbours by having no underline and a heavier weight, and by its state for assistive technology. A set that should not let its current item be followed (the last item of a trail) draws it as text, not as a link.
- A disabled link is not in the focus order, as a disabled Button is not. Where people must learn why a place cannot be reached, say so in text beside it.
- A link does not hold another link, a button or any other control, and is not placed inside one. Inside an element that is pressed as a whole (a link card, a list item with a destination) the text is that element's, not a second link.
- Text must remain readable at 200% text size: the link is text and grows and wraps with it; nothing about it has a fixed size (LNK-23).
- Contrast in the default system: sys.color.link on every surface role is held to 4.5:1 (7:1 in the high-contrast schemes) by the token invariants, and sys.color.inverse-link on sys.color.inverse-surface likewise. On the quiet containers (secondary-container and the four status containers) the link color measures 4.6:1 or more in every scheme today; that pair is not yet an invariant. The focus ring is held to 3:1 against every surface.
- How a state looks is a value decision of the active design system (a state-layer mix in Tanrei, a dim or no hover at all elsewhere). The link reads the state's tokens and never computes the effect itself.

### Behaviour

Requirements in EARS form, each with its stable id.

- **LNK-1** WHILE href is a destination THE link SHALL be the platform's own link to it (the web's anchor element in the document itself, not in a shadow root; SwiftUI's Link; on Compose, Flutter and React Native an element or a run of text with the platform's link semantics whose address is opened by the platform's opener), so that whatever the platform gives a link — on the web its context menu, opening in a new tab or window, copying and dragging its address, the address shown before it is followed, a crawler and a search index that read it, and a link that works before any script has run — is the platform's, and not the link's to draw or to take over; and SHALL expose the link role.
- **LNK-2** THE link SHALL draw its label in the text style of the text it sits in — that text's family, size, weight, line height and letter spacing — bringing no text style of its own, in the label color of its variant (comp.link.standard.label.color for standard, comp.link.inverse.label.color for inverse), on the baseline of the text beside it, and SHALL NOT make its line taller than that text makes it.
- **LNK-3** WHILE its underline is shown (LNK-27, LNK-28) THE link SHALL draw it comp.link.underline.width thick, comp.link.underline.offset below the text's baseline, in the label's color of that state, under the text only and not under a glyph, the site icon or the mark. WHILE its underline is always — the default system's choice — THE link SHALL draw it at rest and in every state, so that a link is told from the text around it without relying on color. A current link (LNK-18) and a link that is a glyph alone (LNK-16) draw none, whatever the choice.
- **LNK-4** THE link SHALL wrap its label with the text it sits in, breaking where that text's language allows a break and, for a run with no such place that is longer than the line (an address), inside the run rather than overflowing; it SHALL NOT cut its label, draw an ellipsis or scroll; and on every line it runs over it SHALL draw its underline, its container and its focus ring for its own part of that line.
- **LNK-5** THE link SHALL draw its container as the box of its content on each line it runs over — as wide as its part of the line and as high as the text's own box, never the line's whole height where that would touch a neighbouring line's text — filled with the container color of its variant and state, with corners comp.link.container.shape, and SHALL NOT let the container take room, move the text beside it or change a line's height.
- **LNK-6** WHILE hovered, keyboard-focused or pressed THE link SHALL render its container, label, icon and opacity from the component tokens of the highest-precedence active state, with precedence pressed over focused over hovered; focus gained by pointer or touch SHALL NOT select the focused state.
- **LNK-7** WHEN the link receives keyboard focus THE link SHALL show the focus ring without animation — the system's focus indicator, sys.focus.offset from the container, sys.focus.outer-width wide in the focus-ring color, with the inner stroke of sys.focus.inner-width where the system has one — around its part of each line it runs over, never as one box around the lines between its first word and its last; focus gained by pointer or touch SHALL NOT show it.
- **LNK-8** WHEN the link is pressed by pointer, touch or Enter THE link SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner.
- **LNK-9** WHILE pressed THE link SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; label, icon, opacity and shape still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.link.motion.feedback-duration with motion.state-easing, fades over motion.state-duration with motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced.
- **LNK-10** THE link SHALL ease its container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show its keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README.
- **LNK-11** THE link SHALL change between its states over comp.link.motion.state-duration with comp.link.motion.state-easing, and at once where motion is reduced.
- **LNK-12** WHEN the user activates the link by pointer, touch or Enter THE link SHALL emit click exactly once and then open href where target names, unless the product cancelled that click, in which case it SHALL open nothing: the product's own router has taken the navigation. It SHALL NOT hold the navigation back for sys.motion.duration.press-hold. THE link SHALL NOT be activated by Space, which on the web scrolls the page as it does on any link, and SHALL NOT show the pressed state for it; WHERE the platform gives its links other keys or gestures (on the web a modified or a middle click that opens a new tab, on Apple platforms a long press that previews) THE link SHALL leave them to the platform.
- **LNK-13** WHILE target is new THE link SHALL open href in a new context — on the web a new tab or window that is given no handle to the page that opened it; on the other platforms outside the screen the person is on, as the platform's opener decides — and, WHILE it has a label and no glyph of the product's after it, SHALL draw the glyph open_in_new of the system's icon set after the label as LNK-14 draws a trailing glyph — at the end of the label in the link's own direction, right after its last word — in the label color of its variant and state, through the icon helper, which mirrors it where the link's own direction is right-to-left because the icon set marks its name, and hidden from assistive technology. It SHALL draw that glyph whether or not the link is external, and then no arrow (LNK-31): the place after the label holds one glyph. WHILE the link holds the product's own glyph at its trailing side, or has no label, THE link SHALL draw no mark of its own: the product has chosen what that place shows. Whether a mark is drawn or not THE link SHALL expose targetLabel as its description, read after its name and role — its one description, so externalLabel is not read with it (LNK-34) — and WHILE targetLabel is empty SHALL still render and in debug builds report that a link that opens a new context does not say so. WHILE target is same THE link SHALL draw no open_in_new and SHALL ignore targetLabel.
- **LNK-14** WHILE the link has both a label and a glyph THE link SHALL draw the glyph at the side iconPosition names in the link's own direction — the direction LNK-26 lays its label out in: a standalone link's label's own, and a phrase's the sentence's unless the product marks the phrase with a direction of its own — leading before the label's first word, trailing after its last word, both mirrored where that direction is right-to-left in a box as large as the font size of the link's text, comp.link.container.gap from the label, centred on the line of the word beside it, in the label color of its variant and state, with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, hidden from assistive technology; and SHALL keep the glyph on the line of the word next to it, so that a leading glyph never ends a line and a trailing glyph or the mark never begins one.
- **LNK-15** WHILE the link has a label THE link SHALL expose the label's text as its accessible name and ignore the label prop; WHILE it has a glyph and no label THE link SHALL expose the label prop as its accessible name and keep the glyph from assistive technology; WHILE it has a glyph, no label and an empty label prop THE link SHALL still render, and in debug builds report that it has no accessible name. THE link SHALL add nothing to its name: neither its address, nor that it opens a new context (LNK-13), nor that it leaves the site (LNK-34), nor that it is current (LNK-18); the site icon and the arrow are kept from assistive technology and name nothing.
- **LNK-16** WHILE the link has a glyph and no label THE link SHALL draw the glyph alone, in a box as large as the font size of the text it sits in, in the icon color of its variant and state (comp.link.standard.icon.color for standard, comp.link.inverse.icon.color for inverse), with its container a square one line of that text high around it, and SHALL draw no underline and no mark; it SHALL answer hover, focus and press and extend its hit area as LNK-6 to LNK-10 and LNK-17 say. Where it stands and when it is seen are the layout's that places it: a heading's anchor is placed and revealed by prose and is this link showing the glyph link.
- **LNK-17** WHILE standalone is false and the link has a label THE link SHALL take input on its own text and container and nowhere else: its hit area is its part of each line and SHALL NOT reach over the text of a neighbouring line or of the same line. WHILE standalone is true, or the link is a glyph alone, and its visual size is below the minimum target THE link SHALL extend its hit area on both axes to sys.target.touch for touch input and sys.target.pointer for fine pointers, without changing its visual size or the room it takes in the layout; a platform that cannot tell the input type SHALL use sys.target.touch.
- **LNK-18** WHILE current is true THE link SHALL expose itself as the current item of its set (on the web the current page; a platform without that state, the selected state) and stay a link that can be focused and followed; it SHALL draw its container, label and glyph from the parts of its variant prefixed with current (comp.link.standard.current.label.color, comp.link.standard.current.icon.color, and inverse's tokens of the same names), SHALL draw no underline, and SHALL draw its label at the emphasized weight of the text style it sits in — that style's weight plus sys.typescale.emphasis.body in running text and a label, plus sys.typescale.emphasis.heading in a heading — so that it is told from the links beside it by more than its color.
- **LNK-19** WHILE disabled is true THE link SHALL NOT be a link that can be followed: it SHALL render its container, label, icon and opacity from the disabled component tokens of its variant, its underline, where its choice draws one at rest (a disabled link is neither hovered nor focused, so under hover it has none), the mark of LNK-13 and the arrow of LNK-31 in the disabled label color, the site icon at comp.link.site-icon.disabled-opacity, SHALL expose the link role with the disabled state and no destination, SHALL NOT be focusable, SHALL NOT emit click, and SHALL open nothing by any means the platform gives a link (on the web the anchor carries no href, so there is no context menu entry, no drag and no new tab for it).
- **LNK-20** THE link SHALL draw no state for a destination already visited: its colors say what it is and what state it is in, and are the same before and after it has been followed.
- **LNK-21** IF href is empty or only white space, or names a script to run rather than a place to go (the web's javascript: scheme), or cannot be read as an address by the platform, THE link SHALL NOT be a link: it SHALL draw its content as the text around it, with no underline, no state, no mark, no arrow and no site icon, SHALL expose no role, SHALL NOT be focusable and SHALL emit nothing, and in debug builds report it — a link without a destination has nothing else to be, and a press that does something on the page is a button's. WHEN target or variant names a value the link or the active design system does not have THE link SHALL behave as same and render with the default variant's tokens, WHEN underline or external names a value the link does not define THE link SHALL treat it as auto, and in each case in debug builds report the unknown value.
- **LNK-22** WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE link SHALL draw its label, its glyph, its mark or arrow and its underline in the platform's link color and, WHILE disabled, in its disabled text color; SHALL draw the underline at rest whatever underline and the tokens it follows say, except on a current link and a glyph alone — the colors are then the person's and not the design system's, so nothing any longer holds the link's color apart from the text's (LNK-29), and the line is what the platform itself gives a link; SHALL draw the site icon as the picture it is, unchanged; and SHALL draw its focus ring in the platform's highlight color.
- **LNK-23** WHILE the text size is enlarged THE link SHALL grow with the text it sits in — its label, its glyph box, the box of its site icon, its container and its hit area — and SHALL keep comp.link.underline.width, comp.link.underline.offset, comp.link.container.gap and comp.link.site-icon.shape.
- **LNK-24** THE link SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the link is shown THE link SHALL draw itself for the new direction at once, without a motion of its own, keeping its focus.
- **LNK-25** WHERE the layout direction is right-to-left THE link SHALL draw the glyph of its icon slot mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place, size, color and fill nor the order LNK-14 gives. THE link SHALL NOT mirror a glyph itself, and SHALL NOT mirror content the product gives as an image or a view of its own rather than by a glyph's name — the site icon among it (LNK-32).
- **LNK-26** WHILE standalone is true THE link SHALL lay out its label as text of its own direction, isolated from the text around it: it takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right word, a number with its sign or unit, a telephone number and an address keep their own order in a right-to-left layout and reorder nothing beside them; THE link SHALL still place the label and align its lines by the layout direction, not by the text's own. WHILE standalone is false THE link SHALL lay out its label as part of the sentence it is in, in that sentence's direction, isolated only so that it reorders nothing beside it: a phrase of a sentence is that sentence's text, and what direction a block of text has is that block's to say.
- **LNK-27** THE link SHALL show its underline as its underline prop names: WHILE underline is auto, as comp.link.underline.visibility names, which follows sys.behavior.link-underline unless a design system sets the link apart; WHILE underline is always, hover or never, as that value names, whatever the tokens say. WHEN underline, or the token it follows, changes THE link SHALL draw the other form at once, moving no text and keeping its focus. A platform that cannot draw a choice SHALL fall back to the first value, always, and state that in its README.
- **LNK-28** WHILE its underline is hover THE link SHALL draw no underline at rest and SHALL draw it, as LNK-3 says, WHILE the link is hovered, keyboard-focused or pressed, the line arriving and leaving with that state as LNK-11 times it and moving no text; the focus ring of LNK-7 is drawn as under every choice, so keyboard focus shows the ring and the line together. WHERE the input has no hover (touch) the line is therefore seen for the length of a press and no longer, and THE link SHALL put nothing in its place at rest: a link under hover has to be told from the text beside it as a link that is never underlined has to be (LNK-29). WHILE its underline is never THE link SHALL draw no underline in any state, and SHALL still show hover, focus and press by its container, its label color and its focus ring (LNK-6, LNK-7).
- **LNK-29** WHILE its underline is not always, standalone is false, current is false and it has a label THE link SHALL, in debug builds on a platform that can read both colors, report a label color whose contrast against the color of the text the link sits in is under 3:1, and SHALL still render: a phrase in running text that is not underlined at rest is told from the words beside it by color alone, which people who do not see that difference cannot do (WCAG 1.4.1). THE link SHALL report nothing for a standalone link, a current link or a glyph alone, which are not phrases among other words. The same ratio is held for the design system's own choice by the build, not by the link: where sys.behavior.link-underline or comp.link.underline.visibility is not always, the link color is held 3:1 apart from the text color in every scheme.
- **LNK-30** THE link SHALL treat its destination as external as its external prop names: WHILE external is on, as external, whatever href is; WHILE it is off, as not external; WHILE it is auto, as external exactly when the platform can tell that the destination is on another site than the one the person is on. On the web that is: href, read against the document's address, has the scheme http or https, its origin is neither the document's nor one the product has declared as part of its own site, and the anchor does not ask for a download. A path, a fragment, an address of any other scheme (a mail address, a telephone number) and a download are never external under auto. On the other platforms, where a screen has no address of its own, that is: the product has declared the hosts that are its own, and href is an http or https address outside them; WHILE it has declared none, nothing is external under auto. THE link SHALL change nothing but what it shows and says for being external (LNK-31 to LNK-34): where the destination opens is target's alone, and nothing is added to how the address is requested.
- **LNK-31** WHILE the link is external, has a label, holds no glyph of the product's after it, target is same and comp.link.external.marks is not none THE link SHALL draw the glyph arrow_outward of the system's icon set after the label as LNK-14 draws a trailing glyph — at the end of the label in the link's own direction (LNK-14), right after its last word, in a box as large as the font size of its text, comp.link.container.gap from the label, on the line of the last word and never beginning a line, not underlined — in the label color of its variant and state, through the icon helper, which mirrors it where the link's own direction is right-to-left because the icon set marks its name, and hidden from assistive technology. WHILE target is new THE link SHALL draw the mark of LNK-13 in that place and no arrow: the place holds one glyph, and that the page the person is on stays open is what they need to know first. WHILE the link holds the product's own glyph at its trailing side, or has no label, THE link SHALL draw no arrow.
- **LNK-32** WHILE the link is external, has a label, siteIcon names a picture, the link holds no glyph of the product's before its label and comp.link.external.marks is all THE link SHALL draw that picture before the label as LNK-14 places a leading glyph: in a square box as large as the font size of the link's text, comp.link.container.gap from the label, centred on the line of the first word and never ending a line, the whole picture scaled to fit the box with its proportions kept, its corners comp.link.site-icon.shape eased as LNK-10 eases the container's, not underlined, never mirrored, in every state as it is at rest, and hidden from assistive technology with no text alternative: it is decoration, and the label names the link. THE link SHALL keep the box's room from the first frame, so that nothing moves when the picture arrives, and IF the picture cannot be loaded or decoded SHALL draw nothing in the box — no broken-picture mark, no alternative text, no glyph in its place — and in debug builds report it. WHILE siteIcon is empty THE link SHALL draw no picture and keep no room for one: an external link without a picture shows the arrow alone. WHILE the link holds the product's own glyph before its label THE link SHALL draw that glyph and no picture. THE link SHALL draw the picture as a picture only: whatever the file holds, nothing in it is run, laid out as markup or opened as a document.
- **LNK-33** THE link SHALL draw the marks of an external link as comp.link.external.marks names: all, the site icon where one is given (LNK-32) and the arrow (LNK-31); arrow, the arrow alone, with no picture drawn and no room kept for one; none, neither, and the link then exposes nothing of being external (LNK-34). The choice is the design system's or the product's layer's and holds for every link; one link is set apart by external (off shows and says nothing) and by leaving siteIcon empty. It SHALL change nothing about the mark of a new context (LNK-13). WHEN the choice changes THE link SHALL draw the other form at once. A platform that cannot read the choice SHALL fall back to the first value, all, and state that in its README.
- **LNK-34** WHILE the link is external, has a label, target is same and comp.link.external.marks is not none THE link SHALL expose as its description, read after its name and role, externalLabel or, WHILE externalLabel is empty, the words the product has set once for every external link (on the web where the page is made or through the package's script; a setting of the package elsewhere), whether the arrow is drawn or the product's own trailing glyph stands in its place; WHILE both are empty THE link SHALL still render and in debug builds report, once for the page or the screen and not once for each link, that external links do not say so. WHILE target is new THE link SHALL expose targetLabel alone (LNK-13): a link has one description, and the product words it for both facts where both should be said ("opens example.com in a new tab"). WHILE the link has no label it SHALL expose nothing of being external. Tanrei ships no words of its own.
- **LNK-35** THE link SHALL request nothing by itself for what it draws: it SHALL NOT derive a picture's address from href, SHALL NOT ask the destination or any other party for an icon, a title or a preview, and SHALL NOT reach the destination in any way before the person follows the link. The one address it loads is siteIcon, exactly as the product gave it; on the web it loads that picture without sending the page's address with the request, and in debug builds reports a siteIcon whose origin is not the document's — every reader's browser would then tell that other party which page is being read.

### Tokens

As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.link.…` → `--tanrei-comp-link-…`).

#### `tanrei.comp.link`

| Token | Type | Value |
| --- | --- | --- |
| `comp.link.container.shape` | `dimension` | `{tanrei.sys.shape.corner.extra-small}` |
| `comp.link.container.gap` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.link.underline.width` | `dimension` | `{tanrei.sys.border.hairline}` |
| `comp.link.underline.offset` | `dimension` | `{tanrei.sys.space.space25}` |
| `comp.link.underline.visibility` | `number` | `{tanrei.sys.behavior.link-underline}` |
| `comp.link.external.marks` | `number` | `0` |
| `comp.link.site-icon.shape` | `dimension` | `{tanrei.sys.shape.corner.extra-small}` |
| `comp.link.site-icon.disabled-opacity` | `number` | `{tanrei.sys.state.disabled-content-opacity}` |
| `comp.link.standard.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` |
| `comp.link.standard.label.color` | `color` | `{tanrei.sys.color.link}` |
| `comp.link.standard.icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.link.standard.state-layer.color` | `color` | `{tanrei.comp.link.standard.label.color}` |
| `comp.link.standard.current.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` |
| `comp.link.standard.current.label.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.link.standard.current.icon.color` | `color` | `{tanrei.comp.link.standard.current.label.color}` |
| `comp.link.standard.current.state-layer.color` | `color` | `{tanrei.comp.link.standard.current.label.color}` |
| `comp.link.inverse.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` |
| `comp.link.inverse.label.color` | `color` | `{tanrei.sys.color.inverse-link}` |
| `comp.link.inverse.icon.color` | `color` | `{tanrei.sys.color.inverse-on-surface}` |
| `comp.link.inverse.state-layer.color` | `color` | `{tanrei.comp.link.inverse.label.color}` |
| `comp.link.inverse.current.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` |
| `comp.link.inverse.current.label.color` | `color` | `{tanrei.sys.color.inverse-on-surface}` |
| `comp.link.inverse.current.icon.color` | `color` | `{tanrei.comp.link.inverse.current.label.color}` |
| `comp.link.inverse.current.state-layer.color` | `color` | `{tanrei.comp.link.inverse.current.label.color}` |
| `comp.link.motion.state-duration` | `duration` | `{tanrei.sys.motion.role.state.compact}` |
| `comp.link.motion.state-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` |
| `comp.link.motion.feedback-duration` | `duration` | `{tanrei.sys.motion.role.feedback}` |

Per-state tokens, valued by the design system's pattern rules (not written by hand):

- `comp.link.<variant>.<state>.<property>` for the variants `standard`, `inverse`, the states `hovered`, `focused`, `pressed`, `disabled` and the properties `container.color`, `label.color`, `icon.color`, `state-layer.color`, `current.container.color`, `current.label.color`, `current.icon.color`, `current.state-layer.color`.
- `comp.link.<state>.<property>` for the states `hovered`, `focused`, `pressed`, `disabled` and the properties `opacity`, `container.shape`.

### What the web draws differently

- The container behind a link’s text is the box of the text itself (the font’s own height), not the full line height.
- A link with a glyph or the mark that wraps is drawn as one box cut at the line ends. A link without them has all four corners on every line.
- A standalone link with a glyph, the mark or the marks of an external link lays its label out in the direction of the layout, not of the label’s own first letter.
- The stylesheet computes nothing about an address: it draws the marks for `data-external`. Write the attribute where the page is made (the build step `markExternalLinks()` of `@tanrei/web/links` does it for rendered Markdown), and the marks are in the first paint.
- With the package’s script, an anchor without `data-external` whose address leaves the site is marked in the browser. These marks arrive after the first paint, and each moves what follows it on its line by the size of the text and the gap. A page with neither the attribute nor the script shows no external mark.
- In a browser without style container queries the script reads the two choices for the whole page. A region’s own value is not seen there, and without the script each choice is its first value: `always`, and both marks.
- Under a design system whose press feedback is a ripple, a link that runs over several lines answers with the overlay instead.
- Without the package’s script the stylesheet draws every state, with the overlay as the press feedback.

## Guidelines

### Link, or Button

| Component | What it is | Use it when |
| --- | --- | --- |
| **Link** | Text that leads somewhere, in the text style around it, underlined as the design system chooses | A phrase in a sentence, a line of text that is a destination, a glyph beside a heading |
| **Button with a destination** | A link that is drawn as a button | The destination is one of the screen’s actions: “Get started”, “View source” |
| **Text Button** | A button | It does something and leads nowhere, however much it should look like text |

### In a sentence, or by itself

`data-standalone` changes nothing a person sees. It says the link is not part of a line of text, so its hit area can reach the minimum target without taking presses meant for the lines above and below. Use it for a link under a paragraph, in a table cell or in a row of links. Leave it off inside a sentence.

Links that stand by themselves are what `hover` and `never` are for: a list of navigation, a footer, a row of related pages. Their place in a list says what they are. Set `data-underline` on those links, or give the region its own value of the component token, and leave the links of your sentences underlined.

### Do

- Write a label that says where the link goes without the sentence around it: “the installation guide”, not “here”.
- Use `data-variant="inverse"` only on `sys.color.inverse-surface`. On a quiet container (a status container, `secondary-container`) the standard link is right.
- Mark at most one link of a set of navigation as current, and let the set decide which.
- Leave `sys.target.spacing` between two standalone links, or let their rows be a target high.
- Give the icon of a site as a file your own site serves. `resolveSiteIcons()` of `@tanrei/web/links` makes them when the site is built, so no reader’s browser calls another party.
- Set the words for external links once (`setExternalLabel()`, or `externalLabel` of the build step), in your product’s language. They are the key `externalLabel` of [your product’s words](https://tanrei.chnotchy.com/foundations/words/): `setWords({ externalLabel: '…' })` gives the same words, per language with `{ lang }`.

### Don’t

- Don’t remove the underline at rest in a layer whose link color is its text color. In the default system the link color is the text color itself, 1.00:1 against it in all six schemes, so the underline is the only thing that says “link”. The build fails the default system, and warns a product’s layer, where the choice is `hover` or `never` and the link color is under 3:1 from the text color.
- Don’t count on `hover` to reveal a link on a touch screen. There is no hover there, so `hover` is held to the same rule as `never`.
- Don’t load a site’s icon from that site, or from an icon service, in the browser. Every reader’s browser would then tell that party which page is being read.
- Don’t give a link a click handler in place of a destination. An anchor without an address is drawn as plain text and reported in debug builds.
- Don’t put a link inside a control that is pressed as a whole (a link card, a list item with a destination), or a control inside a link.
- Don’t style visited links. A product that needs “already opened” marks it from its own data, with a Tag or a glyph.

## Accessibility

### What the component handles

- It is the browser’s own link: the link role, Enter to follow, the context menu, opening in a new tab, and a link that works without script.
- In the default system the underline tells it from the text beside it without relying on color, in every scheme. In forced colors the underline is drawn whatever was chosen.
- An external link has one description, read after its name: `aria-description` for a new tab, otherwise the words for an external link. The arrow and the site’s icon are hidden from assistive technology.
- The keyboard focus ring is drawn around the link’s part of each line.
- A standalone link and a glyph alone extend their hit area to the minimum target. A link in a sentence keeps to its own text.
- The mark and a glyph beside a label are hidden from assistive technology.
- With the package’s script, a link that opens a new tab gets `noopener`, and a debug build reports a missing name, a missing description and an address that is not a destination. It also reports a link in a sentence that is not underlined at rest and stands under 3:1 from its text, external links that have no words (once for the page), and a site’s icon that is loaded from another origin.

### What you need to do

- Give a glyph alone its name with `aria-label`, and put `aria-hidden="true"` on every glyph.
- Say that a link opens a new tab with `aria-description`, in your product’s language. Tanrei ships no words of its own.
- Write a disabled link as the anchor without `href`, with `role="link"` and `aria-disabled="true"`. It leaves the focus order, so say in text beside it why the place cannot be reached.
- Set `aria-current` on the link that names the page or section the person is at.
- Use `hover` and `never` inside running text only where the link color stands 3:1 or more apart from the text color, and still 4.5:1 from the surface. With near-black text on a near-white surface that is a narrow band of mid tones.
- Say that a link leaves the site in words: `aria-description` on the link, or the words you set once for every external link. Tanrei ships no words of its own. For a link that is external and opens a new tab, word the one description for both facts.
- Write the site’s icon with `alt=""`. It is decoration: the label names the link, and the arrow marks it.