J3W1 / DESIGN SYSTEM
Link
The native anchor for navigation; always underlined in the link-underline role, hover fills with the strong hover surface, the current page carries a 2px indicator bar.
stable · LIGHT DOM · 1.1.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@1.1.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@1.1.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
Purpose
Navigation to another document, section or resource. A link never performs
an action on the current page; that is a button. Links are recognisable by
the persistent underline as well as strong red color.text.link, distinct
from rose body text and headings (D-024).
Anatomy
A native <a href>. Inline: text plus the 1px underline. Standalone: the
same with a trailing arrow icon and a little horizontal padding so the hover
fill has room. Current: aria-current="page", brighter text and a 2px bar
replacing the underline.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | color.text.link; underline 1px color.text.link-underline offset 2px | the underline |
| hover | background → color.interaction.hover.bg-strong; text → color.text.link-hover; underline 2px in the text colour | underline thickens 1px → 2px; cursor: pointer |
| focus-visible | ring 1px dashed color.interaction.focus.ring at −2px; no change to the underline | the ring |
| visited | color.text.link; underline unchanged | the underline continues to mark navigation; browsing history does not reduce its visibility |
| current | text → color.text.bright; the underline becomes a 2px color.border.selected-indicator bottom border; no hover fill | aria-current="page"; the bar’s 2px weight |
Precedence: current > hover; focus-visible is always drawn.
Keyboard
Native. Enter follows the link; Space never does. Skip links and in-page
links move focus to their target, which needs tabindex="-1" when it is not
focusable.
Accessibility
The link text describes 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. Links that open a new
window say so in text. Link text meets 4.5:1 on canvas, panel and raised
surfaces; the underline meets 3:1. The generated contrast report records exact
ratios for the current profile, including hover text and focus. Inline targets are exempt
from the 24×24 minimum; standalone links reach it through their line box.
Portability
Colour, underline thickness, background and outline; the arrow is an inline
SVG in currentColor. Hosts that cannot thicken an underline invert the link on
hover instead and record it. Hosts without aria-current expose 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”.