リンク
行き先のあるテキストです。文の中の語句、単独の 1 行、グリフだけの 3 つの形があります。置かれた場所のテキストスタイルで描き、下線はデザインシステムの選択に従い、サイトの外へ出るリンクにはその印を付けます。
- カテゴリ
- ナビゲーション
- トークン
comp.link- レベル
- 基礎
- Web
tanrei-linkschedule - SwiftUI
TanreiLinkradio_button_unchecked - Jetpack Compose
TanreiLinkradio_button_unchecked - Flutter
TanreiLinkradio_button_unchecked - React Native
Linkradio_button_unchecked
生成元 docs/status/status.json, specs/link.spec.json
文の中、単独、グリフだけ
表を引かなくても使える規則が 1 つあります。アドレスがあればリンク、なければボタンです。 ページ上で何かを実行し、どこにも移動しないコントロールはボタンで、テキストのように控えめに見せたいときは text バリアントを使います。ボタンのように見せたい行き先は、href を持つボタンです。
Web では、リンクは要素ではなく、プロダクト側の <a> に付けるクラスです。<a> は文書の中にあるので、スクリプトが動く前からリンクとして働き、クローラー、検索インデックス、ページ内の <a> を扱うルーターのどれからも見つけられます。ルーターのリンクコンポーネントにもこのクラスを付けられます。.tanrei-prose の中の <a> はクラスがなくても同じように描かれるので、Markdown から生成した HTML には何も足す必要がありません。
SwiftUI、Compose、Flutter、React Native は計画中です。このページの冒頭で各プラットフォームに添えた名前は仕様が定めたもので、まだ提供していません。React にもまだ Link コンポーネントはないので、クラスを付けた <a> を使ってください。
<link rel="stylesheet" href="@tanrei/web/tokens.css" />
<link rel="stylesheet" href="@tanrei/web/icons.css" />
<link rel="stylesheet" href="@tanrei/web/link.css" />
<!-- 文の中。 -->
<p>まず<a class="tanrei-link" href="/guides/accessibility/">アクセシビリティガイド</a>をお読みください。</p>
<!-- 単独：ヒット領域が最小ターゲットまで広がります。 -->
<a class="tanrei-link" data-standalone href="/getting-started/">はじめに</a>
<!-- 新しいタブ：印は自動で描かれます。言葉でも伝えます。 -->
<a class="tanrei-link" href="https://example.com/" target="_blank" aria-description="新しいタブで開きます">ソースコード</a>
<!-- 別のサイトへ、いまいる場所で開くリンク：ラベルの後ろに矢印が描かれます。言葉でも伝えます。 -->
<a class="tanrei-link" href="https://example.com/" data-external="true" aria-description="外部リンク">規格書</a>
<!-- そのサイトのアイコンを付ける場合：自分のサイトが配信する画像を、<a> の最初の子として書きます。 -->
<a class="tanrei-link" href="https://example.com/" data-external="true" aria-description="外部リンク"><img
class="tanrei-link-site-icon" src="/icons/example-com.png" alt="" width="32" height="32"
loading="lazy" decoding="async" referrerpolicy="no-referrer">規格書</a>
<!-- デザインシステムの下線の選択から 1 つのリンクだけを外す：always、hover、never。 -->
<a class="tanrei-link" data-standalone data-underline="hover" href="/about/">このサイトについて</a>
<!-- 領域ごとの選択：中のリンクはすべてこれに従います。 -->
<footer style="--tanrei-comp-link-underline-visibility: never">…</footer>
<!-- グリフ。テキストとの間に空白を入れずに書きます。 -->
<a class="tanrei-link" data-standalone href="/tokens.zip"><span class="tanrei-icon" aria-hidden="true">download</span>トークンをダウンロード</a>
<a class="tanrei-link" data-standalone data-icon-position="trailing" href="/tokens/">次へ：トークン<span class="tanrei-icon" aria-hidden="true">arrow_forward</span></a>
<!-- グリフだけ。aria-label で名前を付けます。 -->
<a class="tanrei-link" href="#installation" aria-label="「インストール」へのリンク"><span class="tanrei-icon" aria-hidden="true">link</span></a>
<!-- 現在のページ、いまは移動できないリンク、反転したサーフェスの上のリンク。 -->
<a class="tanrei-link" data-standalone href="/components/" aria-current="page">コンポーネント</a>
<a class="tanrei-link" data-standalone role="link" aria-disabled="true">前のページ</a>
<a class="tanrei-link" data-variant="inverse" href="/changes/">変更点を見る</a>
<script type="module">
// 任意：リップルと dim の押下への応え方、noopener、拒否、デバッグ時の報告。`@tanrei/web` を読み込んでも入ります。
// ページを作るときに印が付けられていない場合は、サイトの外へ出るリンクにここで印を付けます。
import { setSiteOrigins, setExternalLabel } from '@tanrei/web/link';
setSiteOrigins(['https://docs.example.com']); // 自分のサイトに含まれるオリジン
setExternalLabel('外部リンク'); // 文言。ページに 1 回、プロダクトの言語で
</script>import '@tanrei/web/link.css';
import '@tanrei/web/link';
import { Link as RouterLink } from 'react-router-dom';
<a className="tanrei-link" href="/guides/accessibility/">アクセシビリティガイド</a>
{/* ルーターのリンクは自分の <a> を描きます。それにクラスを付けます。 */}
<RouterLink className="tanrei-link" data-standalone to="/getting-started/">はじめに</RouterLink>| プロパティ | 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"（またはほかの値） |
disabled |
role="link" aria-disabled="true"、href なし |
label |
aria-label |
underline |
data-underline="always"、"hover"、"never"。なければデザインシステムの選択 |
external: on、off |
data-external="true"、data-external="false"。なければアドレスで決まります |
externalLabel |
aria-description |
siteIcon |
自分で書く <img class="tanrei-link-site-icon" alt="">。<a> の最初の子にします |
折り返し：下線、ステートレイヤー、フォーカスリングは行ごとに描かれます
グリフと、新しいタブの印
仕様書反転したサーフェスの上
ページを保存しました。 変更点を見る
リンクは自分のテキストスタイルを持ちません。段落、見出し、キャプション、表のセルのどこでも、置かれたテキストの書体、サイズ、太さ、行の高さをそのまま使います。ホバー、フォーカス、押下は、リンクが通る各行のテキストの背後に描かれ、場所を取らないので、リンクの周りは動きません。グリフ、サイトのアイコン、印はテキストと同じ大きさで、隣の語と同じ行にとどまります。
下線をいつ描くかは選択です。 値は 3 つあります。always は、何もしていないときも、どの状態でも下線を描きます。hover は、リンクにホバーしている間、キーボードでフォーカスしている間、押している間に描きます。never は描きません。その場合も、ホバー、フォーカス、押下はステートレイヤー、ラベルの色、フォーカスリングで示されます。この選択は 3 つのレベルで設定します。デザインシステムのすべてのテキストリンクには sys.behavior.link-underline、リンクだけには comp.link.underline.visibility、1 つのリンクには underline プロパティです。既定のシステムの選択は always です。Web ではコンポーネントトークンがカスタムプロパティなので、フッターのような領域に独自の値を持たせられます。現在の項目のリンクとグリフだけのリンクには、どの選択でも下線がありません。強制カラーモードでは、どの選択でも下線を描きます。
サイトの外へ出るリンクは、そのことを伝えます。 外部リンクは、ラベルの後ろに arrow_outward のグリフを描き、アイコンを渡した場合はラベルの前にそのサイトのアイコンを描きます。external の値は auto、on、off です。auto では、ページとは別のオリジンの http または https のアドレスが外部になります。パス、フラグメント、メールアドレス、電話番号、ダウンロードは外部になりません。自分のサイトに含まれるほかのオリジンを 1 回宣言しておけば、それらも外部になりません。comp.link.external.marks は、プロダクト全体でアイコンを消す（arrow）か、両方の印を消します（none）。
サイトの外へ出ることと、新しいタブで開くことは、別々の事実です。ラベルの後ろの場所に入るグリフは 1 つです。target="_blank" のリンクには、外部かどうかにかかわらず open_in_new が入り、それ以外の外部リンクには arrow_outward が入ります。末尾側に自分でグリフを置いた場合はそれが代わりになり、グリフだけのリンクにはどちらもありません。
リンクがアイコンを取りに行くことはありません。 siteIcon は利用者側で渡す画像です。自分のサイトが配信する画像を、サイトをビルドするときに用意します。コンポーネントが行き先のサイトやアイコンのサービスにそれを問い合わせると、読者がどのページを見ているかをその相手に知らせることになります。アイコンを渡さない場合、リンクは矢印だけを描きます。読み込めなかったアイコンは、場所を保ったまま何も描きません。
構成要素
| パーツ | 説明 |
|---|---|
1 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. |
2 label · 任意 | The link's text, in the text style of the text it sits in. It wraps with that text and is never cut. |
3 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. |
4 icon · 任意 | 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. |
5 site-icon · 任意 | 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. |
6 mark · 任意 | 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. |
7 focus-ring | The indicator shown for keyboard focus, around the link's part of each line it runs over. |
プロパティ
| プロパティ | 型 | 既定値 | 説明 |
|---|---|---|---|
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 | 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 | 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 | 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 | 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 | 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. |
スロット
| スロット | 説明 |
|---|---|
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. |
イベント
| イベント | 説明 |
|---|---|
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). |
状態
振る舞い
EARS 記法による要件です。各プラットフォームの実装は、この ID に対応するテストで検証されます。要件の原文は仕様ファイルのものをそのまま掲載しています。
| 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. |
プラットフォーム別の名前対応
パリティは API が同一であることを意味しません。同じ契約を、各プラットフォームの流儀で表現します。
| 仕様 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| コンポーネント | tanrei-link | TanreiLink | TanreiLink | TanreiLink | Link |
href · プロパティ | href | destination | href | href | href |
target · プロパティ | target | target | target | target | target |
targetLabel · プロパティ | aria-description | targetLabel | targetLabel | targetSemanticLabel | targetLabel |
external · プロパティ | data-external | external | external | external | external |
externalLabel · プロパティ | aria-description | externalLabel | externalLabel | externalSemanticLabel | externalLabel |
siteIcon · プロパティ | img.tanrei-link-site-icon | siteIcon | siteIcon | siteIcon | siteIcon |
variant · プロパティ | data-variant | variant | variant | variant | variant |
underline · プロパティ | data-underline | underline | underline | underline | underline |
standalone · プロパティ | data-standalone | TanreiLink | TanreiLink | TanreiLink | standalone |
iconPosition · プロパティ | data-icon-position | iconPosition | iconPosition | iconAlignment | iconPosition |
current · プロパティ | aria-current | isCurrent | current | isCurrent | current |
disabled · プロパティ | aria-disabled | disabled | enabled | enabled | disabled |
label · プロパティ | aria-label | label | contentDescription | semanticLabel | accessibilityLabel |
click · イベント | click | action | onClick | onPressed | onPress |
| 備考 | A class on the product's own anchor, not an element with an anchor in its shadow root: <a class="tanrei-link" href="…">…</a>, styled by a stylesheet of the package (LNK-1). The anchor is in the document, so it is a link before any script runs and for whatever reads the page as built: a crawler, a search index, a framework that prefetches or routes the anchors it finds, and a router's own link component, which takes the class. The props are the anchor's own attributes: href; target in HTML's spelling (_blank is new; target="new" would name a window, so it is not used here); aria-description for targetLabel; aria-current="page" (or another of its values) for current; aria-label for label; and a disabled link is written <a class="tanrei-link" role="link" aria-disabled="true"> with no href. data-variant="inverse", data-standalone and data-icon-position="trailing" are the three that HTML has no attribute for. The glyph is a .tanrei-icon element inside the anchor, before or after the text; the mark is the anchor's ::after (the icon font's open_in_new, mirrored under the anchor's own :dir(rtl)). A standalone link is given the dir of its label's first strong character (a glyph's name aside) by the package's script where the page wrote none, so its direction, and so the side of its glyphs and its mark, is its label's first strong character's (LNK-26, LNK-14); a phrase in a sentence takes the dir the page writes on it, not drawn while data-icon-position is trailing or the anchor has no text (aria-label present). The container and the ring follow wrapped lines through box-decoration-break: clone and outline; the extended hit area of LNK-17 is a pseudo-element that takes no room. The stylesheet alone gives the default system's whole look and every state, including the press-hold (a delayed transition back from :active). The package's script, where it is loaded, adds through one listener on the document what a stylesheet cannot: the shared press primitive (ripple and dim, LNK-9), noopener on a new context, the refusals of LNK-21 and every debug report. The same rules apply to every anchor of a .tanrei-prose that is prose's own (PRS-16), so rendered Markdown needs no class, and a heading's anchor (.tanrei-prose-anchor) is the icon-only form. rel and download are the anchor's own. React: Link renders the same anchor and takes a render prop for a router's link. data-underline="always | hover | never" sets one link apart; without it the anchor follows --tanrei-comp-link-underline-visibility, which the stylesheet reads by a container style query and, where the browser has none, from data-underline-system written on the document's root by the package's script; with neither it is always, the first value. The custom property can be set on any element, so a region (a footer, a navigation list) takes its own choice without an attribute on each link. hover is :hover under (hover: hover), :focus-visible and the pressed state; the line is the text decoration's color, so nothing moves. External: the stylesheet computes nothing about addresses. It draws the marks for data-external that is not false, and that attribute is written by whoever knows the page's address — where the page is made, by markExternalLinks() of @tanrei/web/links (Node; it takes the tree the product's own renderer already has, and parses nothing) or by React's Link, both from the product's site origins; and, for an anchor that carries no data-external, by the package's script, which compares new URL(a.href).origin with location.origin and with setSiteOrigins([…]) and writes data-external="detected" (re-read when href changes; only a value it wrote is ever changed by it). A page with neither shows no external mark: a missing mark, never a wrong one. Marks written by the script arrive after the first paint and take room; marks written where the page is made are in the first paint. The arrow is the same ::after as the mark of a new context, whose content is open_in_new while target="_blank" and arrow_outward otherwise, so the two cannot both be drawn. The site icon is the product's <img class="tanrei-link-site-icon" src="…" alt="" width="…" height="…" loading="lazy" decoding="async" referrerpolicy="no-referrer">, the anchor's first child, placed as a leading glyph is; alt="" and no role keep it from assistive technology; it is an img, never an inline svg, an object or an iframe, so a vector file is drawn and not run (LNK-32). A broken picture keeps its room and draws nothing. externalLabel is aria-description on the anchor, written by the same step that writes data-external where the product set words for every external link (externalLabel of markExternalLinks(), setExternalLabel() of the script). comp.link.external.marks is read as the underline choice is. resolveSiteIcons() of @tanrei/web/links is the build-time helper that turns the external origins of a site into pictures the site serves itself; the component never calls it and nothing of it runs in a browser. Words: the words set once for every external link are the key externalLabel of the product's words, and targetLabel is read the same way; the script's setExternalLabel(text) is setWords({ externalLabel: text }) before it is released. | Two spellings for the two places a link stands. Standalone: the view TanreiLink(_ title: String, destination: URL, target:, targetLabel:, variant:, icon:, iconPosition:, isCurrent:, action:), built on SwiftUI's Link, taking its font from the environment and disabled by .disabled(_:); TanreiLink(label:icon:destination:) is the glyph alone. In text: Text(tanreiLink:) helpers that build an AttributedString run with the link attribute, the underline and the variant's color, for use inside a Text. action runs before the address opens and returns whether the link should still open it (the environment's OpenURLAction does the opening, so an app that routes addresses itself handles it there). The isLink trait; isSelected for current. SwiftUI draws no hover, focus or press on a run inside a Text: an in-text link there has its resting look and the system's own focus and press, and the README says so. Not built on this platform yet: underline: TanreiLinkUnderline? = nil (nil is auto; .always, .hover, .never), read from the generated choice otherwise; hover is the pointer's on iPadOS, macOS and visionOS, and focus from a keyboard. external: Bool? = nil (nil is auto): auto reads the hosts the app declares once in the environment (.tanreiSiteHosts([…])), and with none declared nothing is external. siteIcon: Image? = nil is an image the app already has (an asset, or one it loaded itself); the view loads nothing. externalLabel is the accessibility hint; the words for every external link are an environment value. In a Text run the arrow and the picture are attachments of the attributed string. | Standalone: TanreiLink(text, href, onClick = null, target, targetLabel, variant, icon, iconPosition, current, enabled, contentDescription), drawn with LocalTextStyle. In text: tanreiLinkAnnotation(href, variant, onClick) returns a LinkAnnotation.Url whose TextLinkStyles carry the resting, hovered, focused and pressed tokens, for AnnotatedString.Builder.withLink; a link annotation has the link semantics Compose lacks for a clickable element (the standalone form, a clickable element, still has no link role). enabled is the inverse flag. The address is opened through LocalUriHandler.current after onClick, which returns false to keep it closed. Current is selected semantics. A run of text draws no ripple: LNK-9's fallback. Not built on this platform yet: underline: TanreiLinkUnderline? = null (null is auto). external: Boolean? = null (null is auto), decided against LocalTanreiSiteHosts; with none provided nothing is external. siteIcon: Painter? = null is the app's own painter; the composable loads nothing. externalLabel joins the state description; the words for every external link are a composition local. In an annotated string the arrow and the picture are inline content. | Standalone: TanreiLink(label: …, href: …, onPressed:, target:, targetSemanticLabel:, variant:, icon:, iconAlignment:, isCurrent:, enabled:), in DefaultTextStyle. In text: TanreiLinkSpan(text: …, href: …), an InlineSpan for Text.rich that carries its recognizer and its states. Semantics(link: true), linkUrl where the engine has it; selected for current. The address is opened by the opener the app provides, after onPressed, which returns false to keep it closed. enabled is the inverse flag. Not built on this platform yet: underline: TanreiLinkUnderline? (null is auto). external: bool? (null is auto), decided against the hosts of TanreiLinkScope; with none nothing is external. siteIcon: ImageProvider? is the app's own provider — an asset or a memory image; the widget never builds a network provider from href. externalSemanticLabel is the semantics hint; the words for every external link come from TanreiLinkScope. In a TanreiLinkSpan the arrow and the picture are widget spans. | <Link href="…">text</Link> is a Text with accessibilityRole="link": nested in a Text it is in that text and inherits its style; by itself it takes a style (a text style of the typescale) and standalone extends its hitSlop. onPress receives an event whose preventDefault() keeps the address closed; otherwise Linking.openURL(href). accessibilityHint carries targetLabel; accessibilityState carries disabled and, for current, selected. A nested Text draws no ripple and no hover: LNK-9's fallback. Follows the app's direction where an ancestor's is not known. Not built on this platform yet: underline?: 'always' | 'hover' | 'never' (undefined is auto); hover exists only where the platform reports a pointer. external?: boolean (undefined is auto), decided against the hosts given to the provider; with none nothing is external. siteIcon?: ImageSourcePropType is a source the app already has (a required asset); the component never builds a { uri } from href. externalLabel is accessibilityHint. Nested in a Text, the picture is an inline Image and the arrow a glyph of the icon font. |
トークン
| トークン | 参照先 | 解決値（ライト） |
|---|---|---|
--tanrei-comp-link-container-gap | sys.space.space50 | 4px |
--tanrei-comp-link-container-shape | sys.shape.corner.extra-small | 3px |
--tanrei-comp-link-disabled-container-shape | — | 3px |
--tanrei-comp-link-disabled-opacity | — | 1 |
--tanrei-comp-link-external-marks | — | 0 |
--tanrei-comp-link-focused-container-shape | — | 3px |
--tanrei-comp-link-focused-opacity | — | 1 |
--tanrei-comp-link-hovered-container-shape | — | 3px |
--tanrei-comp-link-hovered-opacity | — | 1 |
--tanrei-comp-link-inverse-container-color | — | |
--tanrei-comp-link-inverse-current-container-color | — | |
--tanrei-comp-link-inverse-current-icon-color | comp.link.inverse.current.label.color | |
--tanrei-comp-link-inverse-current-label-color | sys.color.inverse-on-surface | |
--tanrei-comp-link-inverse-current-state-layer-color | comp.link.inverse.current.label.color | |
--tanrei-comp-link-inverse-disabled-container-color | — | |
--tanrei-comp-link-inverse-disabled-current-container-color | — | |
--tanrei-comp-link-inverse-disabled-current-icon-color | — | |
--tanrei-comp-link-inverse-disabled-current-label-color | — | |
--tanrei-comp-link-inverse-disabled-current-state-layer-color | — | |
--tanrei-comp-link-inverse-disabled-icon-color | — | |
--tanrei-comp-link-inverse-disabled-label-color | — | |
--tanrei-comp-link-inverse-disabled-state-layer-color | — | |
--tanrei-comp-link-inverse-focused-container-color | — | |
--tanrei-comp-link-inverse-focused-current-container-color | — | |
--tanrei-comp-link-inverse-focused-current-icon-color | — | |
--tanrei-comp-link-inverse-focused-current-label-color | — | |
--tanrei-comp-link-inverse-focused-current-state-layer-color | — | |
--tanrei-comp-link-inverse-focused-icon-color | — | |
--tanrei-comp-link-inverse-focused-label-color | — | |
--tanrei-comp-link-inverse-focused-state-layer-color | — | |
--tanrei-comp-link-inverse-hovered-container-color | — | |
--tanrei-comp-link-inverse-hovered-current-container-color | — | |
--tanrei-comp-link-inverse-hovered-current-icon-color | — | |
--tanrei-comp-link-inverse-hovered-current-label-color | — | |
--tanrei-comp-link-inverse-hovered-current-state-layer-color | — | |
--tanrei-comp-link-inverse-hovered-icon-color | — | |
--tanrei-comp-link-inverse-hovered-label-color | — | |
--tanrei-comp-link-inverse-hovered-state-layer-color | — | |
--tanrei-comp-link-inverse-icon-color | sys.color.inverse-on-surface | |
--tanrei-comp-link-inverse-label-color | sys.color.inverse-link | |
--tanrei-comp-link-inverse-pressed-container-color | — | |
--tanrei-comp-link-inverse-pressed-current-container-color | — | |
--tanrei-comp-link-inverse-pressed-current-icon-color | — | |
--tanrei-comp-link-inverse-pressed-current-label-color | — | |
--tanrei-comp-link-inverse-pressed-current-state-layer-color | — | |
--tanrei-comp-link-inverse-pressed-icon-color | — | |
--tanrei-comp-link-inverse-pressed-label-color | — | |
--tanrei-comp-link-inverse-pressed-state-layer-color | — | |
--tanrei-comp-link-inverse-state-layer-color | comp.link.inverse.label.color | |
--tanrei-comp-link-motion-feedback-duration | sys.motion.role.feedback | 450ms |
--tanrei-comp-link-motion-state-duration | sys.motion.role.state.compact | 200ms |
--tanrei-comp-link-motion-state-easing | sys.motion.easing.state | cubic-bezier(0.2, 0, 0, 1) |
--tanrei-comp-link-pressed-container-shape | — | 3px |
--tanrei-comp-link-pressed-opacity | — | 1 |
--tanrei-comp-link-site-icon-disabled-opacity | sys.state.disabled-content-opacity | 0.38 |
--tanrei-comp-link-site-icon-shape | sys.shape.corner.extra-small | 3px |
--tanrei-comp-link-standard-container-color | — | |
--tanrei-comp-link-standard-current-container-color | — | |
--tanrei-comp-link-standard-current-icon-color | comp.link.standard.current.label.color | |
--tanrei-comp-link-standard-current-label-color | sys.color.on-surface | |
--tanrei-comp-link-standard-current-state-layer-color | comp.link.standard.current.label.color | |
--tanrei-comp-link-standard-disabled-container-color | — | |
--tanrei-comp-link-standard-disabled-current-container-color | — | |
--tanrei-comp-link-standard-disabled-current-icon-color | — | |
--tanrei-comp-link-standard-disabled-current-label-color | — | |
--tanrei-comp-link-standard-disabled-current-state-layer-color | — | |
--tanrei-comp-link-standard-disabled-icon-color | — | |
--tanrei-comp-link-standard-disabled-label-color | — | |
--tanrei-comp-link-standard-disabled-state-layer-color | — | |
--tanrei-comp-link-standard-focused-container-color | — | |
--tanrei-comp-link-standard-focused-current-container-color | — | |
--tanrei-comp-link-standard-focused-current-icon-color | — | |
--tanrei-comp-link-standard-focused-current-label-color | — | |
--tanrei-comp-link-standard-focused-current-state-layer-color | — | |
--tanrei-comp-link-standard-focused-icon-color | — | |
--tanrei-comp-link-standard-focused-label-color | — | |
--tanrei-comp-link-standard-focused-state-layer-color | — | |
--tanrei-comp-link-standard-hovered-container-color | — | |
--tanrei-comp-link-standard-hovered-current-container-color | — | |
--tanrei-comp-link-standard-hovered-current-icon-color | — | |
--tanrei-comp-link-standard-hovered-current-label-color | — | |
--tanrei-comp-link-standard-hovered-current-state-layer-color | — | |
--tanrei-comp-link-standard-hovered-icon-color | — | |
--tanrei-comp-link-standard-hovered-label-color | — | |
--tanrei-comp-link-standard-hovered-state-layer-color | — | |
--tanrei-comp-link-standard-icon-color | sys.color.on-surface-variant | |
--tanrei-comp-link-standard-label-color | sys.color.link | |
--tanrei-comp-link-standard-pressed-container-color | — | |
--tanrei-comp-link-standard-pressed-current-container-color | — | |
--tanrei-comp-link-standard-pressed-current-icon-color | — | |
--tanrei-comp-link-standard-pressed-current-label-color | — | |
--tanrei-comp-link-standard-pressed-current-state-layer-color | — | |
--tanrei-comp-link-standard-pressed-icon-color | — | |
--tanrei-comp-link-standard-pressed-label-color | — | |
--tanrei-comp-link-standard-pressed-state-layer-color | — | |
--tanrei-comp-link-standard-state-layer-color | comp.link.standard.label.color | |
--tanrei-comp-link-underline-offset | sys.space.space25 | 2px |
--tanrei-comp-link-underline-visibility | sys.behavior.link-underline | 0 |
--tanrei-comp-link-underline-width | sys.border.hairline | 1px |
フィクスチャ
基準となる描画パターンです。全プラットフォームが同じ ID でスナップショットを撮り、結果を比較できるようにしています。
variant: standard (43)
in-text
href: /components/button/ in-text-wrapping
href: /guides/accessibility/ in-text-wrapping-rtl
href: /guides/accessibility/ direction: rtl in-text-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab in-text-new-rtl
href: https://example.com/tanrei target: new targetLabel: يفتح في علامة تبويب جديدة direction: rtl long-address
href: https://example.com/tanrei/design-system… external: off standalone
href: /getting-started/ standalone: true standalone-leading-icon
href: /tokens.zip standalone: true slots: icon standalone-trailing-icon
href: /foundations/tokens/ standalone: true iconPosition: trailing slots: icon standalone-trailing-icon-rtl
href: /foundations/tokens/ standalone: true iconPosition: trailing direction: rtl slots: icon standalone-wrapping
href: /foundations/tokens/ standalone: true iconPosition: trailing slots: icon standalone-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab standalone: true standalone-new-leading-icon
href: https://example.com/tanrei target: new targetLabel: opens in a new tab standalone: true slots: icon standalone-new-trailing-icon
href: https://example.com/tanrei target: new targetLabel: opens in a new tab standalone: true iconPosition: trailing slots: icon icon-only
href: #installation label: Link to Installation slots: icon icon-only-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab label: Source code slots: icon icon-only-rtl
href: #installation label: رابط إلى التثبيت direction: rtl slots: icon current
href: /components/ standalone: true current: true current-leading-icon
href: /components/ standalone: true current: true slots: icon disabled
href: /page/0/ standalone: true disabled: true disabled-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab disabled: true disabled-icon-only
href: #installation disabled: true label: Link to Installation slots: icon ltr-label-rtl
href: https://example.com/tanrei external: off standalone: true direction: rtl underline-always
href: /components/button/ underline: always underline-hover
href: /components/button/ underline: hover underline-never
href: /components/button/ underline: never standalone-underline-hover
href: /getting-started/ underline: hover standalone: true standalone-underline-never
href: /getting-started/ underline: never standalone: true external
href: https://example.com/tanrei external: on externalLabel: external link external-site-icon
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png external-standalone
href: https://example.com/tanrei external: on externalLabel: external link standalone: true external-standalone-site-icon
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png standalone: true external-standalone-underline-never
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png underline: never standalone: true external-wrapping
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png external-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab external: on siteIcon: fixtures/site-icon.png external-forced
href: /partners/ external: on externalLabel: external link external-suppressed
href: https://example.com/tanrei external: off siteIcon: fixtures/site-icon.png external-mail
href: mailto:[email protected] external-leading-icon
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png standalone: true slots: icon external-trailing-icon
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png standalone: true iconPosition: trailing slots: icon external-site-icon-failed
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/missing.png external-disabled
href: https://example.com/tanrei external: on siteIcon: fixtures/site-icon.png standalone: true disabled: true external-rtl
href: https://example.com/tanrei external: on externalLabel: رابط خارجي siteIcon: fixtures/site-icon.png direction: rtl variant: inverse (7)
inverse
href: /changes/ variant: inverse inverse-new
href: https://example.com/tanrei target: new targetLabel: opens in a new tab variant: inverse inverse-current
href: /components/ variant: inverse standalone: true current: true inverse-disabled
href: /page/0/ variant: inverse standalone: true disabled: true inverse-icon-only
href: #installation variant: inverse label: Link to Installation slots: icon inverse-underline-never
href: /changes/ variant: inverse underline: never external-inverse
href: https://example.com/tanrei external: on externalLabel: external link siteIcon: fixtures/site-icon.png variant: inverse 生成元 specs/link.spec.json, tokens/comp/link.tokens.json, design/tokens/
- テキストの背後のコンテナは、行の高さ全体ではなく、テキスト自体の箱（フォントの高さ）です。
- グリフや印のあるリンクが折り返すと、行の端で切られた 1 つの箱として描かれます。どちらもないリンクは、すべての行で 4 つの角が丸くなります。
- グリフ、印、外部リンクの印のいずれかがある単独のリンクは、ラベルを、ラベル自身の最初の文字の方向ではなく、レイアウトの方向で配置します。
- スタイルシートはアドレスについて何も計算しません。
data-externalに対して印を描くだけです。この属性をページを作るときに書いておけば（Markdown から生成した HTML には、@tanrei/web/linksのビルドステップmarkExternalLinks()が書きます）、印は最初の描画に含まれます。 - パッケージのスクリプトがあれば、
data-externalのない<a>のうち、アドレスがサイトの外へ出るものにブラウザーで印が付きます。この印は最初の描画の後に現れ、1 つごとに、同じ行の後ろにあるものをテキストのサイズと間隔の分だけ動かします。属性もスクリプトもないページには、外部リンクの印は出ません。 - スタイルコンテナクエリのないブラウザーでは、スクリプトが 2 つの選択をページ全体について読み取ります。領域ごとの値は反映されません。スクリプトもなければ、どちらの選択も最初の値（
alwaysと、両方の印）になります。 - 押下への応え方がリップルのデザインシステムでも、複数行にわたるリンクはオーバーレイで応えます。
- パッケージのスクリプトがなくても、スタイルシートだけですべての状態を描きます。このとき、押下への応え方はオーバーレイです。
| 種類 | 何であるか | 使う場面 |
|---|---|---|
| リンク | 行き先のあるテキスト。周りのテキストスタイルで描き、下線はデザインシステムの選択に従います | 文の中の語句、行き先である 1 行のテキスト、見出しの横のグリフ |
| 行き先のあるボタン | ボタンとして描くリンク | 行き先が画面のアクションの 1 つであるとき。「はじめる」「ソースを見る」など |
| テキストボタン | ボタン | 何かを実行し、どこにも移動しないとき。どれほどテキストのように見せたくても同じです |
data-standalone を付けても見た目は変わりません。リンクがテキストの行の一部ではないことを伝えるもので、上下の行に向けた押下を奪うことなく、ヒット領域を最小ターゲットまで広げられます。段落の下のリンク、表のセルの中のリンク、リンクの並びに使います。文の中では付けません。
hover と never は、単独で置かれるリンクのためのものです。ナビゲーションのリスト、フッター、関連ページの並びなどです。リストの中の位置が、それがリンクであることを伝えます。そうしたリンクに data-underline を付けるか、その領域にコンポーネントトークンの独自の値を持たせ、文の中のリンクには下線を残します。
- 周りの文がなくても行き先が分かるラベルにします。「こちら」ではなく「インストールガイド」と書きます。
data-variant="inverse"はsys.color.inverse-surfaceの上だけで使います。控えめなコンテナ（ステータスのコンテナやsecondary-container）の上では標準のリンクが適切です。- ナビゲーションのまとまりの中で現在の項目にするリンクは 1 つまでとし、どれにするかはそのまとまりが決めます。
- 単独のリンクを 2 つ並べるときは
sys.target.spacingを空けるか、行の高さをターゲットの高さにします。 - サイトのアイコンは、自分のサイトが配信するファイルとして渡します。
@tanrei/web/linksのresolveSiteIcons()がサイトのビルド時に用意するので、読者のブラウザーがほかの相手に問い合わせることはありません。 - 外部リンクの文言は、プロダクトの言語で 1 回だけ設定します（
setExternalLabel()、またはビルドステップのexternalLabel）。この文言は、プロダクトの言葉のキーexternalLabelです。setWords({ externalLabel: '…' })でも同じ文言を渡せ、{ lang }を付ければ言語ごとに渡せます。
- リンクの色が本文の色と同じレイヤで、何もしていないときの下線を外さない。既定のシステムではリンクの色は本文の色そのもので、6 つのスキームすべてで本文に対して 1.00:1 です。リンクであることを伝えているのは下線だけです。選択が
hoverかneverで、リンクの色と本文の色の差が 3:1 に満たない場合、ビルドは既定のシステムではエラーにし、プロダクトのレイヤでは警告します。 - タッチスクリーンで
hoverがリンクを見分けさせてくれると考えない。タッチスクリーンにホバーはないので、hoverにはneverと同じ規則が適用されます。 - サイトのアイコンを、ブラウザーからそのサイトやアイコンのサービスに取りに行かない。読者がどのページを見ているかを、読者全員のブラウザーがその相手に知らせることになります。
- 行き先の代わりにクリックハンドラーを付けない。アドレスのない
<a>はただのテキストとして描かれ、デバッグビルドで報告されます。 - 全体を押すコントロール（リンクカード、行き先のあるリストの項目）の中にリンクを置かない。リンクの中にコントロールを置くこともしません。
- 訪問済みのリンクに別のスタイルを付けない。「開いたことがある」ことを示したいプロダクトは、自分のデータをもとにタグやグリフで示します。
- ロール
link- ラベル付け
- 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 32px · pointer 44px · spacing 8px · touch 48px
キーボード操作
| キー | 動作 |
|---|---|
| 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.
生成元 specs/link.spec.json, tokens/sys/measure.tokens.json
- ブラウザー自身のリンクです。リンクのロール、Enter での移動、コンテキストメニュー、新しいタブで開く操作がそのまま働き、スクリプトがなくてもリンクとして動きます。
- 既定のシステムでは、周りのテキストとの違いを、色に頼らず下線で示します。どのスキームでも同じです。強制カラーモードでは、どの選択でも下線を描きます。
- 外部リンクの説明は 1 つで、名前の後に読み上げられます。新しいタブで開くリンクでは
aria-description、それ以外では外部リンクの文言です。矢印とサイトのアイコンは支援技術から隠されます。 - キーボードフォーカスのフォーカスリングは、各行のリンクの部分を囲んで描かれます。
- 単独のリンクとグリフだけのリンクは、ヒット領域を最小ターゲットまで広げます。文の中のリンクは自分のテキストの範囲にとどまります。
- 印と、ラベルの横のグリフは、支援技術から隠されます。
- パッケージのスクリプトがあれば、新しいタブで開くリンクに
noopenerが付き、デバッグビルドでは、名前のないリンク、説明のないリンク、行き先でないアドレスが報告されます。あわせて、文の中にあって何もしていないときに下線がなく、本文との差が 3:1 に満たないリンク、文言のない外部リンク（ページに 1 回）、別のオリジンから読み込まれるサイトのアイコンも報告されます。
- グリフだけのリンクには
aria-labelで名前を付け、すべてのグリフにaria-hidden="true"を付けます。 - 新しいタブで開くことは、プロダクトの言語で
aria-descriptionに書きます。Tanrei は言葉を同梱しません。 - 無効なリンクは、
hrefのない<a>にrole="link"とaria-disabled="true"を付けて書きます。フォーカス順から外れるので、移動できない理由は横のテキストで伝えます。 - いまいるページやセクションを指すリンクに
aria-currentを付けます。 - 文の中で
hoverとneverを使うのは、リンクの色が本文の色から 3:1 以上離れ、かつサーフェスに対して 4.5:1 を保つ場合だけにします。白に近いサーフェスに黒に近い本文を置く場合、これを満たすのは中間のトーンの狭い範囲です。 - サイトの外へ出ることは言葉で伝えます。リンクに
aria-descriptionを書くか、すべての外部リンクに向けて 1 回設定した文言を使います。Tanrei は言葉を同梱しません。外部で、かつ新しいタブで開くリンクでは、1 つの説明に両方の事実を書きます。 - サイトのアイコンは
alt=""で書きます。これは装飾です。リンクの名前はラベルが伝え、印は矢印が担います。