Link
The native anchor for navigation; always underlined in the link-underline role, hover fills with the hover surface, the current page carries a 2px indicator bar.
stable · light DOM · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
default
Every value on this page comes from the token tables, which the exports embed by tag.
Example destination: tokens
<j3w1-link id="example-link-default"><p class="link-prose">Every value on this page comes from the <a class="link" href="#example-link-default-tokens">token tables</a>, which the exports embed by tag.</p><p id="example-link-default-tokens" tabindex="-1" class="j3w1-example-target">Example destination: tokens</p></j3w1-link>standalone
Example destination: components
<j3w1-link id="example-link-standalone"><a class="link link-standalone" href="#example-link-standalone-components">Browse every component<svg class="link-icon" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M3 8h9M8.5 4.5L12 8l-3.5 3.5"></path></svg></a><p id="example-link-standalone-components" tabindex="-1" class="j3w1-example-target">Example destination: components</p></j3w1-link>current
Example destination: c link
<j3w1-link id="example-link-current"><a class="link link-standalone" href="#example-link-current-c-link" aria-current="page">Link</a><p id="example-link-current-c-link" tabindex="-1" class="j3w1-example-target">Example destination: c link</p></j3w1-link>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@4.0.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/link.css';
import '@j3w1/ui/register/link';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy link --out ./vendor/j3w1/linkThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
events
| Name | Type / signature | Meaning |
|---|
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Link link
The native anchor for navigation; always underlined in the link-underline role, hover fills with the hover surface, the current page carries a 2px indicator bar.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
root.text | color.text.linkapproveduse | #f73f35 | Strong red link text, distinct from rose body text and headings; retain the underline. |
root.underline | color.text.link-underlineobserveduse | #dc282e | Link underline. |
root.text-hover | color.text.link-hoverobserveduse | #f4eeee | Link text on hover, over interaction.hover.bg-strong. |
root.bg-hover | color.interaction.hover.bgapproveduse | #1c1010 | D-041 interaction.hover.bg: color.primitive.modern.hover. |
root.ring | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
root.text-visited | color.text.linkapproveduse | #f73f35 | Strong red link text, distinct from rose body text and headings; retain the underline. |
root.text-current | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
root.indicator | color.border.selected-indicatorobserveduse | #e53935 | 2px indicator bar on the selected tab or nav item. |
icon.stroke | color.icon.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Inline | Standalone | Current |
|---|---|---|---|
default | Every value on this page comes from the token tables, which the exports embed by tag. | ||
hover | |||
focus-visible | |||
visited | |||
current |
Purpose
Navigation to another document, section or resource; an action on the
current page is a button. A link is recognised by its persistent underline as
well as strong red color.text.link, distinct from rose body text and
headings (D-024).
Anatomy
Parts as listed in the anatomy; the current link has no underline, only its 2px bar.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | color.text.link; 1px color.text.link-underline underline, offset 2px | the underline |
| hover | fill color.interaction.hover.bg (D-027); text color.text.link-hover; underline 2px in the text colour | underline 1px → 2px; cursor: pointer |
| focus-visible | 1px dashed color.interaction.focus.ring at −2px; underline unchanged | the ring |
| visited | as default | the underline still marks navigation |
| current | color.text.bright; a 2px color.border.selected-indicator bottom border replaces the underline; no hover fill | aria-current="page"; the 2px bar |
Precedence: current > hover; focus-visible is always drawn.
Keyboard
As in the key table. An in-page or skip-link target that is not focusable
takes tabindex="-1" so focus moves to it.
Accessibility
Link text names the destination on its own (“Release notes”, never “here”);
same destination, same text. aria-current="page" marks the current document
in navigation and nothing else. A link that opens a new window says so in
text. Text meets 4.5:1 on canvas, panel and raised surfaces; the underline
3:1. Inline links are exempt from the 24×24 target minimum; standalone links
reach it through their line box.
Portability
The arrow is an inline SVG in currentColor. A host that cannot thicken an
underline inverts the link on hover instead and records it. A host without aria-current exposes the current link as
selected.
Non-examples
A link without an underline at rest. Blue or purple links. A hover that only recolours the text. A link that opens a dialog or submits a form. An underline drawn with a border on an inline link. A visited colour that fails 4.5:1. A button styled to look like a link. Text such as “click here”.
Contrast report
12 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| link default text | default | text | color.text.link #f73f35 | color.surface.canvas #000000 | 5.72 | 4.5 | pass |
| link hover text | hover | text | color.text.link-hover #f4eeee | color.interaction.hover.bg #1c1010 | 16.19 | 4.5 | pass |
| link focus-visible text | focus-visible | text | color.text.link #f73f35 | color.surface.canvas #000000 | 5.72 | 4.5 | pass |
| link focus-visible outline | focus-visible | ui | color.interaction.focus.ring #e53935 | color.surface.canvas #000000 | 4.97 | 3 | pass |
| link visited text | visited | text | color.text.link #f73f35 | color.surface.canvas #000000 | 5.72 | 4.5 | pass |
| link current text | current | text | color.text.bright #ffa2a7 | color.surface.canvas #000000 | 10.98 | 4.5 | pass |
| link current border | current | ui | color.border.selected-indicator #e53935 | color.surface.canvas #000000 | 4.97 | 3 | pass |
| underline on the canvas | — | ui | color.text.link-underline #dc282e | color.surface.canvas #000000 | 4.39 | 3 | pass |
| underline on the panel | — | ui | color.text.link-underline #dc282e | color.surface.default #0d0707 | 4.17 | 3 | pass |
| link text on the panel | — | text | color.text.link #f73f35 | color.surface.default #0d0707 | 5.44 | 4.5 | pass |
| link text on raised surfaces | — | text | color.text.link #f73f35 | color.surface.raised #140b0b | 5.28 | 4.5 | pass |
| ring on the hover fill | hover | ui | color.interaction.focus.ring #e53935 | color.interaction.hover.bg #1c1010 | 4.39 | 3 | pass |
Keys
| Key | Action |
|---|---|
| Tab / Shift+Tab | Moves focus to and from the link. |
| Enter | Follows the link (native); Space scrolls the page, never activates. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: button breadcrumbs sidebar-nav skip-link pagination
Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-STATE-MATRIX