キーボードショートカット
コマンドを実行するキーを、キーの形か文字で表示します。使っているキーボードの修飾キーの記号と名前で描き、読み上げではキーの名前で伝えます。
- カテゴリ
- コミュニケーション
- トークン
comp.keyboard-shortcut- レベル
- 基礎
- Web
tanrei-keyboard-shortcutschedule - SwiftUI
TanreiKeyboardShortcutradio_button_unchecked - Jetpack Compose
TanreiKeyboardShortcutradio_button_unchecked - Flutter
TanreiKeyboardShortcutradio_button_unchecked - React Native
KeyboardShortcutradio_button_unchecked
生成元 docs/status/status.json, specs/keyboard-shortcut.spec.json
キーボードショートカットは、コマンドを実行するキーを表示します。キーキャップの形か、コマンド名の横に置く文字の形で、small と medium の 2 つのサイズがあります。キーは mod、shift、k のような中立の名前で書き、使っているキーボードの流儀で描きます。Apple の記号（⇧⌘K）か、標準の名前（Ctrl+Shift+K）です。流儀はプロダクトが領域ごとに決めることも、プラットフォームに任せることもできます。複数の組み合わせが続くショートカット（Ctrl+K Ctrl+C）は、1 つの並びとして扱います。
キーキャップ、2 つの組み合わせが続く並び、文字の形。お使いのキーボードに合わせて表示します
キーの描画は見た目のためだけのものです。支援技術には、プロダクトが与えた label（プロダクト自身の言葉で書いたショートカット）を読ませます。label がなければ、aria-keyshortcuts の記法（Meta+Shift+K）を読ませます。Tanrei は、どの言語でもキーの名前を持ちません。このコンポーネントはキーを表示するだけです。フォーカスも入力も受け取らず、キーを効かせることもしません。キーの割り当てはプロダクト側で行います。
3 つのコンポーネントが、自身の shortcut プロパティからこのコンポーネントでショートカットを描きます。メニューは項目の末尾に、プレーンなツールチップはテキストの後ろに、検索はバーやトリガーの中のヒントとして描きます。これらの中では、自分で要素を置かずに、そのプロパティを使ってください。ホストは自分のテキストスタイルでキーを描き、コントロールのキーボードショートカットとして伝えます。
keys には、押す順に、組み合わせを 1 つずつ文字列で指定します。組み合わせは、キーの名前を + でつないだものです。名前の大文字と小文字は区別しません。
- 修飾キー：
mod（Apple のプラットフォームでは Command、それ以外では Control）、ctrl、alt、shift。 - 名前のあるキー：
enter、escape、tab、backspace、delete、space、arrow-up、arrow-down、arrow-left、arrow-right、home、end、page-up、page-down、caps-lock、f1〜f24、そして + キーを表すplus。 - それ以外の 1 文字は、その文字のキーです。
k、/、,など。
Web では、keys 属性に組み合わせを空白で区切って書きます（keys="mod+k mod+c"）。プロパティは配列です。SwiftUI、Compose、Flutter、React Native は、このコンポーネントをまだ実装していません。実装されるまで、これらのプラットフォームのメニューは、メニューのページにあるとおり、ショートカットを項目の末尾のテキストに書きます。
<!-- small は、本文の行の高さを変えずに行の中に収まります。 -->
<p><tanrei-keyboard-shortcut keys="mod+k" label="コマンドまたはコントロールと K" size="small"></tanrei-keyboard-shortcut> で検索できます。</p>
<!-- 続けて押す 2 つの組み合わせ。 -->
<tanrei-keyboard-shortcut keys="mod+k mod+c" label="コマンドまたはコントロールと K、続けてコマンドまたはコントロールと C"></tanrei-keyboard-shortcut>
<!-- 文字の形。読み上げはプロダクトの言語で行います。 -->
<tanrei-keyboard-shortcut keys="mod+shift+k" variant="plain" label="コマンド シフト K"></tanrei-keyboard-shortcut>
<!-- 利用者のプラットフォームにかかわらず、1 つのキーボード向けに書く領域。 -->
<section data-tanrei-keyboard-convention="standard">
<tanrei-keyboard-shortcut keys="mod+s" label="コントロール S"></tanrei-keyboard-shortcut>
</section>
<script type="module">
import '@tanrei/web/components/keyboard-shortcut';
// 要素はキーを表示するだけです。キーは利用者側で割り当て、そのキーが属するコントロールで伝えます。
const shown = document.querySelector('tanrei-keyboard-shortcut');
searchButton.setAttribute('aria-keyshortcuts', shown.ariaKeyShortcuts); // "Meta+K" または "Control+K"
</script>import { KeyboardShortcut } from '@tanrei/react';
<p><KeyboardShortcut keys={['mod+k']} label="コマンドまたはコントロールと K" size="small" /> で検索できます。</p>
<KeyboardShortcut keys={['mod+k', 'mod+c']} label="コマンドまたはコントロールと K、続けてコマンドまたはコントロールと C" />
<KeyboardShortcut keys={['mod+shift+k']} variant="plain" label="コマンド シフト K" />
// 利用者のプラットフォームにかかわらず、1 つのキーボード向けに書く領域。
<section data-tanrei-keyboard-convention="standard">
<KeyboardShortcut keys={['mod+s']} label="コントロール S" />
</section>同じキーを Apple のキーボード向けと標準のキーボード向けに。文中の small、名前のあるキー、無効
構成要素
構成要素
keycap-apple の上に描いています。| パーツ | 説明 |
|---|---|
1 container | One key's cap, in the keycap form: a small rounded square that widens with its legend, with a faint fill and, in the default system, no edge. A layer that wants keys with an edge, or with a deeper edge at the bottom, gives the edge its widths. The plain form draws no cap. |
2 label | A key's legend: a modifier's symbol or name (⌘, Ctrl), a named key's symbol or name (↩, Enter), or a character (K). It is text, drawn in the component's text style. |
3 separator · 任意 | The + between two keys of a chord where the keyboard's convention writes one (Ctrl+K). Apple platforms write none (⌘K). |
4 chord | The keys pressed together: the modifiers, in the convention's order, then one other key. |
5 sequence · 任意 | Chords pressed one after the other (Ctrl+K, then Ctrl+C), a wider gap apart. Most shortcuts are one chord. |
寸法
寸法
| 長さ | トークン | 値（px） |
|---|---|---|
container padding-inline | tanrei.comp.keyboard-shortcut.container.padding-inline.medium | 6 |
container height | tanrei.comp.keyboard-shortcut.container.height.medium | 24 |
keycap-apple の上に描いています。プロパティ
| プロパティ | 型 | 既定値 | 説明 |
|---|---|---|---|
keys | strings | | The shortcut: one chord per string, pressed in order. A chord is key names joined by + ("mod+shift+k"). Modifiers: mod (Command on Apple platforms, Control elsewhere), ctrl, alt, shift. Named keys: enter, escape, tab, backspace, delete, space, arrow-up, arrow-down, arrow-left, arrow-right, home, end, page-up, page-down, caps-lock, f1 to f24, plus. Any other single character is that character's key. Names ignore case. |
variant | keycap | plain | "keycap" | How the keys are drawn: keycap puts each key in its own cap; plain writes the shortcut as a line of text, as a menu or a tooltip writes it. A design system may add values. |
size | small | medium | "medium" | Small (20 caps, 12 text) sits in a line of body text or a menu row without making it taller; medium (24 caps, 14 text) sits beside larger text or on its own. A design system may add values. |
convention | auto | apple | standard | "auto" | Whose keyboard the keys are written for. apple: the symbols of macOS, iOS, iPadOS and visionOS (⌃ ⌥ ⇧ ⌘, no separator). standard: the names of Windows, Linux, ChromeOS and Android (Ctrl, Alt, Shift, joined by +). auto: the convention an ancestor sets, else the one of the platform the app runs on. |
label | string | "" | What assistive technology reads in place of the drawn keys: the shortcut in the product's language ("Shift Command K", "Befehl Umschalt K"). The product's: Tanrei has no names for keys. Empty exposes the shortcut in the form of the platform's keyboard shortcut property (KBS-12), which is a standard's notation and not a sentence, and is reported (KBS-11). |
disabled | boolean | false | Fades the legends, for the shortcut of a command that is unavailable. The keys still show; the shortcut takes no input either way. |
状態
振る舞い
EARS 記法による要件です。各プラットフォームの実装は、この ID に対応するテストで検証されます。要件の原文は仕様ファイルのものをそのまま掲載しています。
| ID | 要件 |
|---|---|
KBS-1 | THE keyboard shortcut SHALL read keys as a sequence of chords pressed one after the other, each chord being the key names of one string joined by + and compared without case: mod, ctrl, alt and shift as modifiers, the named keys enter, escape, tab, backspace, delete, space, arrow-up, arrow-down, arrow-left, arrow-right, home, end, page-up, page-down, caps-lock, f1 to f24 and plus, and any other single character as that character's key. |
KBS-2 | WHILE convention is auto THE keyboard shortcut SHALL use the convention its nearest ancestor sets, and without one SHALL use apple on macOS, iOS, iPadOS and visionOS and standard on every other platform; it SHALL NOT choose the convention by the design system, because the keys follow the keyboard a person presses, not the look of the product. |
KBS-3 | WHILE the convention is apple THE keyboard shortcut SHALL write mod as ⌘, ctrl as ⌃, alt as ⌥ and shift as ⇧, in the order ⌃ ⌥ ⇧ ⌘ whatever order keys gives, followed by the chord's other key, with no separator; and SHALL write enter as ↩, escape as ⎋, tab as ⇥, backspace as ⌫, delete as ⌦, space as Space, the arrows as ↑ ↓ ← →, home as ↖, end as ↘, page-up as ⇞, page-down as ⇟, caps-lock as ⇪, a function key as F1 to F24 and plus as +. |
KBS-4 | WHILE the convention is standard THE keyboard shortcut SHALL write mod and ctrl as Ctrl, alt as Alt and shift as Shift, in the order Ctrl, Alt, Shift whatever order keys gives, followed by the chord's other key, each joined to the next by +; and SHALL write enter as Enter, escape as Esc, tab as Tab, backspace as Backspace, delete as Delete, space as Space, the arrows as ↑ ↓ ← →, home as Home, end as End, page-up as PgUp, page-down as PgDn, caps-lock as Caps Lock, a function key as F1 to F24 and plus as +. |
KBS-5 | THE keyboard shortcut SHALL write a letter key as its capital letter in both conventions and any other character key as given, and SHALL NOT add shift for a capital letter: shift is drawn only where keys names it, so mod+k and mod+K both draw ⌘K and mod+shift+k draws ⇧⌘K. |
KBS-6 | WHILE variant is keycap THE keyboard shortcut SHALL draw each key of a chord in its own cap: at least its size's container height tall and at least as wide as it is tall, its legend centered with its size's container padding on each side, corners of its size's container shape eased by sys.shape.corner-smoothing, filled with comp.keyboard-shortcut.container.color, and edged in comp.keyboard-shortcut.outline.color, comp.keyboard-shortcut.outline.width on its top and sides and comp.keyboard-shortcut.outline.bottom-width at its bottom, both inside the cap's size, a width of 0 (both, in the default system) drawing no edge on those sides, so that the cap is its fill alone; the legend SHALL be in its size's label typescale and comp.keyboard-shortcut.keycap.label.color, and two caps of one chord SHALL be its size's chord gap apart, or, where the convention has a separator, the separator in the legend's style and color with the chord gap on each side of it. |
KBS-7 | WHILE variant is plain THE keyboard shortcut SHALL write each chord as one run of text in its size's label typescale and comp.keyboard-shortcut.plain.label.color, the Apple symbols with no separator (⌥⌘⎋) and the standard names joined by + with no spaces (Ctrl+Alt+Delete), and SHALL draw no cap, fill or edge. |
KBS-8 | WHILE keys holds more than one chord THE keyboard shortcut SHALL draw the chords in order, its size's sequence gap apart, in both forms, and SHALL draw nothing else between them. |
KBS-9 | WHILE disabled is true THE keyboard shortcut SHALL draw its legends and separators from the disabled component tokens of its variant, SHALL keep its caps' fill and edges at rest, and SHALL NOT expose a disabled state of its own: it is not a control, and the command it belongs to exposes whether it is available. |
KBS-10 | THE keyboard shortcut SHALL hide its caps, legends and separators from assistive technology and SHALL expose in their place one text, read where the shortcut sits: label where it is not empty, which is the shortcut in the product's own words ("Shift Command K"), and otherwise the text KBS-11 gives. It SHALL NOT expose the symbols themselves, which a screen reader reads by the names of their characters. |
KBS-11 | WHILE label is empty THE keyboard shortcut SHALL have no names for keys of its own and SHALL NOT spell its keys out in the words of any language: it SHALL expose as its text the shortcut in the form of the platform's keyboard shortcut property (KBS-12) — Meta+Shift+K; Control+K Control+C — which is a standard's notation for keys, the same in every language, and in debug builds SHALL report once that the shortcut has no words. The legends it draws (KBS-3 to KBS-5) are the engravings of the two keyboard conventions, what the keys themselves carry, and are not words of Tanrei's; a keyboard engraved otherwise is a convention of its own, and a proposal of its own. |
KBS-12 | THE keyboard shortcut SHALL give a component that hosts it the shortcut in the form of the platform's keyboard shortcut property, which the web writes as aria-keyshortcuts does: each chord's modifiers then its key joined by +, with mod as Meta under apple and Control under standard, ctrl as Control, alt as Alt and shift as Shift, and the chords separated by spaces (Meta+Shift+K; Control+K Control+C). |
KBS-13 | WHERE a component draws the keyboard shortcut in one of its own parts THE keyboard shortcut SHALL draw its legends and separators in that part's text style and color from the host's tokens instead of its own label typescale and label color, SHALL keep its own caps, sizes and gaps, and SHALL expose nothing to assistive technology, because the host exposes the shortcut as its own (a menu item's keyboard shortcut). |
KBS-14 | THE keyboard shortcut SHALL NOT listen for, register or perform the keys it shows, SHALL NOT take focus, and SHALL NOT take pointer, touch or keyboard input of its own: it shows the keys, and the product makes them work. |
KBS-15 | THE keyboard shortcut SHALL lay itself out inline with the text around it, align the baseline of its legends with that text's baseline, never break a line inside a chord, and break a sequence only between chords; WHILE the text size is enlarged THE keyboard shortcut SHALL grow its caps with their legends, keeping container height as a minimum. |
KBS-16 | WHERE the layout direction is right-to-left THE keyboard shortcut SHALL keep the keys of a chord and the chords of a sequence in left-to-right order, isolated from the surrounding direction, as keyboards and the platforms' own menus write them. |
KBS-17 | WHERE the font of its text style has no glyph for a symbol it writes (⌘, ⌥, ⎋) THE keyboard shortcut SHALL draw that symbol from the platform's system font at the same size and baseline, and SHALL NOT draw a missing-glyph box. |
KBS-18 | IF keys is empty THE keyboard shortcut SHALL draw nothing and expose nothing; IF a chord is empty, holds no key other than modifiers, holds more than one key other than modifiers, names a key twice once the convention has written it (ctrl+mod under standard), or names an unknown key of more than one character THE keyboard shortcut SHALL draw what it can (each key once, an unknown name as given, in order) and in debug builds SHALL report the chord. |
KBS-19 | THE keyboard shortcut 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 keyboard shortcut is shown THE keyboard shortcut SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows and its state. |
プラットフォーム別の名前対応
パリティは API が同一であることを意味しません。同じ契約を、各プラットフォームの流儀で表現します。
| 仕様 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| コンポーネント | tanrei-keyboard-shortcut | TanreiKeyboardShortcut | TanreiKeyboardShortcut | TanreiKeyboardShortcut | KeyboardShortcut |
keys · プロパティ | keys | keys | keys | keys | keys |
variant · プロパティ | variant | variant | variant | variant | variant |
size · プロパティ | size | size | size | size | size |
convention · プロパティ | convention | convention | convention | convention | convention |
label · プロパティ | label | label | contentDescription | semanticLabel | accessibilityLabel |
disabled · プロパティ | disabled | disabled | enabled | enabled | disabled |
| 備考 | The keys attribute holds the chords separated by spaces (keys="mod+k mod+c"); the property is an array. The shadow root draws a <kbd> per chord holding a <kbd> per key, as HTML nests keys that are pressed together, all aria-hidden, beside one visually hidden text (KBS-10). Under auto the convention is the nearest ancestor's data-tanrei-keyboard-convention attribute (apple or standard), read when the element connects and when that attribute changes, else apple where navigator.userAgentData.platform or navigator.platform names macOS, iOS or iPadOS. The read-only ariaKeyShortcuts property is KBS-12's form, which the menu sets on its item. The small caps line up with text through vertical-align: baseline on an inline-flex host (KBS-15). Words: the element has no names for keys; without label its text for assistive technology is ariaKeyShortcuts. | TanreiKeyboardShortcut(_ keys: [String], …), with an initializer that takes SwiftUI's own KeyboardShortcut (its key and modifiers, .command as mod), so a product that already registers a shortcut shows the same one. auto reads the \.tanreiKeyboardConvention environment value, else apple. disabled follows SwiftUI's .disabled(_:) environment. The shortcut's text is the view's accessibilityLabel, on an element that combines its children. | TanreiKeyboardShortcut(keys: List<String>, …). Compose idiom is the inverse flag enabled. auto reads LocalTanreiKeyboardConvention, else standard (Android and ChromeOS write Ctrl). The shortcut's text is the contentDescription of semantics merged over the drawn keys, which are cleared. | TanreiKeyboardShortcut(keys: [...]), with a .fromActivator(SingleActivator) constructor so a product that binds Shortcuts shows the same keys (meta on Apple targets and control elsewhere read as mod). A widget that takes no press has no onPressed to null, so the flag is the inverse enabled, as in Compose. auto reads the TanreiKeyboardConvention inherited widget, else apple where defaultTargetPlatform is macOS or iOS. The drawn keys are excluded from semantics under one Semantics(label:). | <KeyboardShortcut keys={['mod+k']} />. auto reads the KeyboardConventionProvider context, else apple where Platform.OS is ios (and macos under React Native macOS). The drawn keys are one accessible element with accessibilityRole="text" and the shortcut's accessibilityLabel. |
トークン
| トークン | 参照先 | 解決値（ライト） |
|---|---|---|
--tanrei-comp-keyboard-shortcut-chord-gap-medium | sys.space.space50 | 4px |
--tanrei-comp-keyboard-shortcut-chord-gap-small | sys.space.space25 | 2px |
--tanrei-comp-keyboard-shortcut-container-color | sys.color.surface-container-highest | |
--tanrei-comp-keyboard-shortcut-container-height-medium | — | 24px |
--tanrei-comp-keyboard-shortcut-container-height-small | — | 20px |
--tanrei-comp-keyboard-shortcut-container-padding-inline-medium | sys.space.space75 | 6px |
--tanrei-comp-keyboard-shortcut-container-padding-inline-small | sys.space.space50 | 4px |
--tanrei-comp-keyboard-shortcut-container-shape-medium | sys.shape.corner.small | 6px |
--tanrei-comp-keyboard-shortcut-container-shape-small | sys.shape.corner.extra-small | 3px |
--tanrei-comp-keyboard-shortcut-keycap-disabled-label-color | — | |
--tanrei-comp-keyboard-shortcut-keycap-label-color | sys.color.on-surface-variant | |
--tanrei-comp-keyboard-shortcut-outline-bottom-width | sys.space.space0 | 0px |
--tanrei-comp-keyboard-shortcut-outline-color | sys.color.outline-variant | |
--tanrei-comp-keyboard-shortcut-outline-width | sys.space.space0 | 0px |
--tanrei-comp-keyboard-shortcut-plain-disabled-label-color | — | |
--tanrei-comp-keyboard-shortcut-plain-label-color | sys.color.on-surface-variant | |
--tanrei-comp-keyboard-shortcut-sequence-gap-medium | sys.space.space150 | 12px |
--tanrei-comp-keyboard-shortcut-sequence-gap-small | sys.space.space100 | 8px |
--tanrei-comp-keyboard-shortcut-label-typescale-medium | sys.typescale.label | 500 14px/1.4286 |
--tanrei-comp-keyboard-shortcut-label-typescale-small | sys.typescale.label-small | 500 12px/1.3333 |
フィクスチャ
基準となる描画パターンです。全プラットフォームが同じ ID でスナップショットを撮り、結果を比較できるようにしています。
variant: keycap (10)
keycap-apple
keys: ["mod+shift+k"] convention: apple label: Shift Command K keycap-standard
keys: ["mod+shift+k"] convention: standard label: Control Shift K small-apple
keys: ["mod+c"] size: small convention: apple label: Command C small-standard
keys: ["mod+c"] size: small convention: standard label: Control C reordered-apple
keys: ["mod+alt+escape"] convention: apple label: Option Command Escape named-keys-standard
keys: ["ctrl+alt+delete"] convention: standard label: Control Alt Delete single-key
keys: ["f2"] convention: standard label: F2 sequence-standard
keys: ["mod+k","mod+c"] convention: standard label: Control K, then Control C plus-key-standard
keys: ["mod+plus"] convention: standard label: Control Plus disabled-keycap
keys: ["mod+shift+k"] convention: apple label: Shift Command K disabled: true variant: plain (4)
plain-apple
keys: ["mod+shift+k"] variant: plain convention: apple label: Shift Command K plain-standard
keys: ["mod+shift+k"] variant: plain convention: standard label: Control Shift K sequence-plain-apple
keys: ["mod+k","mod+c"] variant: plain convention: apple label: Command K, then Command C disabled-plain
keys: ["mod+shift+k"] variant: plain convention: standard label: Control Shift K disabled: true 生成元 specs/keyboard-shortcut.spec.json, tokens/comp/keyboard-shortcut.tokens.json, design/tokens/
コマンドを実行するキーをプロダクトが伝える場所で使います。ヘルプの文中、ショートカットの一覧、空の状態の案内、コマンドパレットのコマンド名の横などです。
メニューの項目、プレーンなツールチップ、検索の中では、代わりにそのコンポーネントの shortcut プロパティを指定します。コマンドやファイル名のような、入力する文字にキーキャップを使わないでください。キャップは「押すキー」を意味します。
| 選択肢 | 描くもの | 用途 |
|---|---|---|
keycap（既定） |
キーを 1 つずつキャップに入れます。標準の流儀では、キャップの間に + を置きます。 | キーそのものが主題になる、ヘルプやドキュメント。 |
plain |
ショートカットをひと続きのテキストで書きます。⌥⌘⎋ や Ctrl+Alt+Delete です。キャップも塗りも縁もありません。 | コマンド名の横。キャップの列が名前と競合する場所で、メニューと同じ書き方をします。 |
medium（既定） |
24 のキャップと 14 の文字。 | 単独で置くとき、または大きめの文字の横。 |
small |
20 のキャップと 12 の文字。 | 本文の行や密な行の中。行の高さを変えません。 |
既定のシステムでは、キャップは縁のない淡い塗りで、文字は控えめなテキストの色です。デザインシステムは、キャップに縁（下側だけ太い縁も）を付けることも、バリアントやサイズを追加することもできます。
- 主な修飾キーは
ctrlではなくmodと書きます。 Apple のキーボードでは Command、それ以外では Control になります。ctrlと書くのは、どのキーボードでも Control であるショートカットだけです。 - 順番は自由です。 修飾キーは、コンポーネントがキーボードの決まった順に書きます。Apple では ⌃ ⌥ ⇧ ⌘、標準の名前では Ctrl、Alt、Shift の順です。
- 英字は大文字で描き、Shift は加えません。
mod+kもmod+Kも ⌘K と描きます。Shift を描くのは、名前で指定したときだけです。 - 1 つの組み合わせに、修飾キー以外のキーは 1 つです。 キーのない組み合わせや、キーが 2 つある組み合わせは、描ける範囲で描き、デバッグビルドで報告します。
- 並びは、複数の組み合わせです。
mod+kに続けてmod+cのように書きます。間隔を空けて描き、間には何も描きません。 - 名前のあるキーもキーボードに従います。
enterは Apple のキーボードでは ↩、標準では Enter です。escapeは ⎋ か Esc、backspaceは ⌫ か Backspace、page-downは ⇟ か PgDn です。矢印はどちらでも ↑ ↓ ← → です。
convention は、どのキーボード向けにキーを書くかを決めます。auto のままにしてください。コンポーネントは、祖先が決めた流儀を使い、なければプラットフォームの流儀を使います。macOS、iOS、iPadOS、visionOS では Apple の記号、それ以外では標準の名前です。
プラットフォームよりもプロダクトのほうがよく知っているときは、領域ごとに流儀を決めます。利用者が選べる設定、2 つのキーボードを並べて示すドキュメント、別のシステムへのリモートセッションなどです。Web では、祖先のどれかに data-tanrei-keyboard-convention 属性（apple または standard）を付けます。その中にあるメニュー、ツールチップ、検索も従います。1 つのショートカットだけに convention を設定するのは、例外の場合だけにします。
流儀がデザインシステムで決まることはありません。キーは、プロダクトの見た目ではなく、実際に押すキーボードに従います。
- 実際に効くショートカットを表示します。キーはプロダクト側で割り当て、表示と割り当てを一致させておきます。
- 読み上げられるショートカットには、必ず
labelを与えます。プロダクトの言葉で書いたショートカットです（「シフト コマンド K」）。なければ、スクリーンリーダーはMeta+Shift+Kという記法を読みます。 convention="auto"では、描かれるキーは利用者のキーボードに合わせて変わりますが、書いたlabelは変わりません。このページのサンプルのように、どちらのキーボードでも正しい言い方にするか（「コマンドまたはコントロール、シフト、K」）、キーボードが分かってからlabelを設定します。- 今は使えないコマンドのショートカットには、そのコマンドの横で
disabledを使います。キーは薄くなりますが、表示されたままです。 - ショートカットは 1 行に収めます。組み合わせの途中で改行されることはなく、並びは組み合わせの間でだけ折り返します。
- 記号を自分で書かない（テキストの中の ⌘K など）。別のキーボードでは誤りになり、スクリーンリーダーが記号を文字の名前で読み上げることがあります。
- ショートカットを、コマンドへの唯一の手段にしない。ショートカットは、ポインターやフォーカスでも届くものへの近道です。
- メニューの項目やツールチップの中に、自分でキーボードショートカットの要素を置かない。ホストの
shortcutプロパティを使います。 - ブランドやテーマで流儀を決めない。
- ロール
none- ラベル付け
- The keyboard shortcut has no role of its own: it is text, read where it sits. Its symbols are hidden; what is read is label, the shortcut in the product's words ("Shift Command K"), or, without one, the notation of KBS-12 (Meta+Shift+K), so a screen reader never says "place of interest sign" for ⌘. Hosted in another component (a menu item), it is hidden entirely, and the host exposes the shortcut as its keyboard shortcut property.
- 最小ターゲット
- 見た目のサイズが小さくても、ヒット領域は最小ターゲットサイズを満たします。 minimum 32px · pointer 44px · spacing 8px · touch 48px
キーボード操作
| キー | 動作 |
|---|
備考
- Not interactive: it takes no focus and no input (KBS-14), so there is no target to size. minimumTarget holds trivially.
- Showing a shortcut does not make it work, and does not tell assistive technology that it works. A control that really answers the keys exposes that itself (aria-keyshortcuts on the web, the platform's keyboard shortcut on the others); a host such as the menu does it with the form KBS-12 gives.
- The keyboard shortcut has no names for keys in any language: a shortcut that should be read as words is given them in label. A table of key names a product sets once, and names taken from the platform, are not built.
- Contrast: the legend's color on the cap's fill is text on a surface and is held to 4.5:1 in the default system (7:1 in its high-contrast schemes); there it is sys.color.on-surface-variant on sys.color.surface-container-highest, 7.52:1 light and 6.09:1 dark at standard contrast. The cap's fill is decorative and is not held to a ratio against what is behind it: the legend alone carries the meaning, and a cap that cannot be told from its background is still a readable legend.
生成元 specs/keyboard-shortcut.spec.json, tokens/sys/measure.tokens.json
- キャップ、文字、区切りは支援技術から隠します。その代わりに、ショートカットのある場所で 1 つのテキストを読ませます。
labelです。⇧⌘K は「シフト コマンド K」のように読まれ、記号の文字の名前で読まれることはありません。labelがなければ、aria-keyshortcutsの記法で書いたショートカットを読ませます。Meta+Shift+K、並びならControl+K Control+Cです。これは標準の記法で、どの言語でも同じです。このとき、コンポーネントは開発時に一度だけ報告します。 - コンポーネントはキーの名前を持ちません。修飾キーも、矢印キーも、句読点のキーも、どの言語の言葉にも直しません。スクリーンリーダーは、カンマのような単独の文字を読み飛ばすことがあります。これも
labelを書く理由の 1 つです。 - ロールを持たず、フォーカスも入力も受け取らず、ターゲットでもありません。テキストです。
- ホスト（メニューの項目、プレーンなツールチップ、検索）の中では、自分では何も伝えません。ホストが、そのコントロールのキーボードショートカットとして伝えます。Web では
aria-keyshortcutsです。 disabledは文字を薄くするだけで、状態は伝えません。使えるかどうかは、ショートカットが属するコマンドが伝えます。- 右から左のレイアウトでも、キーは左から右の順のままで、周りのテキストの方向から切り離されます。キーボードや各プラットフォームのメニューの書き方と同じです。
- 周りのテキストのベースラインにそろい、文字を大きくすると一緒に大きくなります。キャップの高さは最小値です。
- プロダクトの書体にない記号（⌘、⎋）は、同じ大きさのシステムフォントで描き、欠けたグリフを示す箱は描きません。
- 既定のシステムでは、キャップの上の文字はテキストのコントラストを満たします。キャップの塗りは装飾で、意味を伝えるのは文字だけです。
- 空の組み合わせ、修飾キーだけの組み合わせ、キーが 2 つある組み合わせ、書き出すと同じキーが 2 回になる組み合わせ（標準の流儀での
ctrl+mod）、知らないキーの名前、知らない流儀は、デバッグビルドで報告します。
プラットフォームごとの既知の制約：
- SwiftUI、Compose、Flutter、React Native は、キーボードショートカットをまだ実装していません。
- Web：無効として伝わるコマンドの外に単独で置いた無効なショートカットは、コントラストの自動チェックで報告される見込みです。文字が薄くなり、要素自身は無効の状態を伝えないためです。
- キーを効かせます。コンポーネントは表示するだけです。
- キーが属するコントロールで、そのキーをキーボードショートカットとして伝えます。Web では、要素の読み取り専用のプロパティ
ariaKeyShortcutsがaria-keyshortcutsの書式で値を返すので、それを設定します。 - ショートカットが読み上げられるところでは、
labelを渡します。プロダクトの言葉で書いたショートカットです。Tanrei は、言葉もキーの名前も同梱しません。 - どのコマンドにも、ショートカットなしで届くようにしておきます。