Skip to content
Pautanext
You are reading Pauta Next: changes waiting for the edition after 6.1.0. They are not an edition yet and may change before one is released. Never cite a rule from these pages or audit an app against them: apps are built and audited to a numbered edition. See the latest edition.

Keyboard first

Every app can be used from the keyboard alone (principle 2), and that rests on one idea: every action is a command with an id (principle 3). Menus, toolbar buttons, the Command Palette and key bindings all run commands, so whatever the mouse can do, the palette or a chord can do too. Keymaps bind chords to those commands in layers, with the user’s own bindings on top, and every control the keyboard reaches shows where the focus is. The palette’s own shape is the Command Palette template; what a screen reader and the OS’s accessibility settings need is Accessibility.

Rules on this page 18
IDLevelRule
Commands
KBD-01MUST
Every user-facing action is a command (an id, a title and a runnable) registered in one command registry (Editora’s Command and CommandRegistry).
KBD-02SHOULD
Command ids are dotted and grouped by area, as in file.open, view.toggleStatusBar and help.reportProblem. A rule that names a command’s id requires that id; these three are examples.
KBD-03MUST
A command’s title comes from command.<id> and its one-line palette description from command.<id>.desc in the message catalogs.
KBD-04SHOULD
A command that cannot run in the current context is shown grayed, with a tooltip that says why, not hidden.
Command Palette
KBD-05MUST
The Command Palette opens with M-x in the Emacs keymap and Ctrl+Shift+P (Cmd+Shift+P on macOS) in the others; the IntelliJ keymap may use IntelliJ’s own Find Action chord, Ctrl+Shift+A (Cmd+Shift+A), instead. An app with one key table and no Emacs keymap, which is a terminal app’s own keymap (KBD-09) or the built-in table of an app that ships no keymap files, counts as one of the others: it binds Ctrl+Shift+P (Cmd+Shift+P on macOS). An app that ships no keymap files owes this chord and fails KBD-09 all the same: KBD-09 requires the files of every app.
KBD-06SHOULD
The palette matches fuzzily over the command’s title and over the words of its id or its keywords; the description is shown, not matched. A query that names a command’s title outranks a fuzzy hit. Each row shows the command’s binding in the active keymap. See the Command Palette template.
KBD-07MUST
The palette and every picker (a card that lists choices to filter and pick one from: QOPEN-01) are in-scene overlays in the window’s root StackPane, never a javafx.stage.Popup.
Keymaps
KBD-09MUST
Except in a terminal app, Emacs and CUA keymaps ship as JSON resources, emacs.json and cua.json, CUA with a cua.mac.json variant where Cmd replaces Ctrl. A terminal’s keys belong to the program it runs (C-a, M-x reach the shell), so a terminal app ships one keymap of its own instead, keymap.json and keymap.mac.json, binding its commands to chords programs don’t use. Neither file binds a plain Ctrl or Alt (Option on macOS) with a letter: off macOS that leaves Ctrl+Shift+T, not Ctrl+T, and on macOS Cmd+T, since no program in the terminal receives Cmd.
KBD-10SHOULD
Except in a terminal app (KBD-09), an app also ships IntelliJ, VS Code and Sublime keymaps as JSON resources beside its Emacs and CUA keymaps: intellij.json, vscode.json and sublime.json, each with its .mac.json variant.
KBD-21MUST
A keymap’s .mac.json variant binds the same commands as the keymap it varies. A chord may differ, to put Cmd where the other has Ctrl, to follow the macOS keymap of the editor it copies, or where macOS keeps the chord for itself (Cmd+Space, Cmd+Tab). See Same on every OS.
KBD-11MUST
Keymaps are applied in layers: base keymap → user overrides → plugin keymaps → the user’s own bindings again. An app without plugins has the first two.
KBD-12SHOULD
A keymap editor in Settings lists every command with its chord, is searchable, and warns of conflicts.
KBD-13SHOULD
No command’s chord is written into translated text. Every other label that shows a chord (a hint, the palette, the status bar) shows the binding from the active keymap; tooltips are TBAR-03 and menu rows MENU-15. Fixed keys of a control (Enter, Tab, Esc, arrows) and keys meant for another program may be written.
KBD-14SHOULD
A multi-key prefix (C-x …) shows a which-key style hint listing the possible next keys.
Focus and accessibility
KBD-15MUST
Every interactive control is reachable with Tab and operable with Space or Enter. A control is the exception when the keyboard does what it does another way: the buttons of a toolbar stay out of the Tab order (TBAR-02, which says what a toolbar is: a bar of labeled buttons is not one, and its buttons are held to this rule), and the find-bar and filter controls that FIND-16 names may leave it. See Accessibility.
KBD-16MUST
Every button, toggle, menu button, link, combo box, check box, radio button and text field shows the focus ring when the keyboard focuses it. The ring is one layer of :focus-visible rules in the app stylesheet, after every rule that sets a border or background on the same controls, since rules of equal specificity are decided by order. Its color and contrast are ICON-12.
KBD-22SHOULD
The focus ring is 2 px wide at the default zoom and sits just outside the control with a 1 px gap: a border with negative insets, which adds nothing to the control’s own, so focusing a control never moves the layout. Two kinds of control draw it inside instead, at the same 2 px and still without moving anything: a text field, whose own focus border is widened, and a control flush with the window’s edge, where a ring outside would be cut off.
KBD-18SHOULD
A row that turns a setting on or off (in Settings, a panel or a dialog) uses a switch the keyboard operates: it takes focus, Space toggles it, and its accessible role is TOGGLE_BUTTON.
  • KBD-01 MUST Every user-facing action is a command (an id, a title and a runnable) registered in one command registry (Editora’s Command and CommandRegistry).
    • Check (code): what a menu item, a toolbar button, a palette row or a key binding does is a registered command: the control runs the command’s id through the registry, or calls what the command’s runnable calls. No button, menu row or key handler does work no command can reach.
    • Reference: Editora command/Command.java, command/CommandRegistry.java. Editora doesn’t hold the rule everywhere yet: the Clear button of its Message Log (ui/MessageLogPopup.java) empties the log in its own handler, and the Previous Run and Save Output buttons of its build console (ui/BuildToolPanel.java) work the same way, with no command behind any of the three. Termina doesn’t either. These buttons, among others, do their work in handlers of their own with no command behind them: Clear in its Message Log (ui/MessageLogWindow.java), Refresh, Copy, Export and Clear in its Debug Log (ui/DebugLogWindow.java), and Import theme in Settings (ui/SettingsWindow.java).
  • KBD-02 SHOULD Command ids are dotted and grouped by area, as in file.open, view.toggleStatusBar and help.reportProblem. A rule that names a command’s id requires that id; these three are examples.
    • Check (code): every registered id is two or more names joined by dots, and the first is the area the command belongs to: file.open, and with a sub-area git.log.checkout.
    • Reference: Editora ui/MenuBarModel.java.
  • KBD-03 MUST A command’s title comes from command.<id> and its one-line palette description from command.<id>.desc in the message catalogs.
    • Why: a registered command is then localized and discoverable without extra work.
    • Check (code): every registered command has a command.<id> and a command.<id>.desc key in the message catalogs, and the registry reads its title and description from them. A catalog parity test that walks the registered commands and fails on a missing key is the surest evidence.
    • Reference: the app template’s CommandSweepFxTest (everyCommandIsLocalizedAndRuns) and Mirada’s CommandCatalogTest (everyCommandHasItsTitleAndDescriptionInTheCatalog) walk the registered commands. Editora i18n/messages.properties; its MessagesTest (everyCommandTitleHasAMatchingDescription) walks the catalog instead, so it finds a title with no description but not a registered command with neither.
  • KBD-04 SHOULD A command that cannot run in the current context is shown grayed, with a tooltip that says why, not hidden.
    • Check (code): the palette and menus list a disabled command with a reason, rather than filtering it out.
    • Reference: Editora ui/Chrome.java (paletteEnabled, disabledReason). The app template’s menu rows of a command that can’t run stay, grayed, with the reason as their tooltip (ui/AppMenus.java, showAvailability; RightClickMenusFxTest, anUnavailableRowStaysAndSaysWhy), and its palette lists such a command with the reason.
  • KBD-05 MUST The Command Palette opens with M-x in the Emacs keymap and Ctrl+Shift+P (Cmd+Shift+P on macOS) in the others; the IntelliJ keymap may use IntelliJ’s own Find Action chord, Ctrl+Shift+A (Cmd+Shift+A), instead. An app with one key table and no Emacs keymap, which is a terminal app’s own keymap (KBD-09) or the built-in table of an app that ships no keymap files, counts as one of the others: it binds Ctrl+Shift+P (Cmd+Shift+P on macOS). An app that ships no keymap files owes this chord and fails KBD-09 all the same: KBD-09 requires the files of every app.
    • Check (code): each bundled keymap binds that chord to the palette command, and so does the one key table of an app that has no keymap files. An app whose chord opens the palette from a handler, with no palette command registered, passes this rule and fails PAL-01 for the missing command.
    • Reference: Editora keymaps/emacs.json (M-x), cua.json and vscode.json (C-S-p), cua.mac.json (Cmd-S-p), all to palette.show; intellij.json binds C-S-a. Termina’s one keymap binds Shortcut+Shift+P, which is Ctrl+Shift+P in keymap.json and Cmd+Shift+P in keymap.mac.json, and nux, which ships no keymap file, binds the same chord in App. Torrenta and Modula don’t yet: Torrenta’s one key table opens the palette with Alt+X alone (ui/Chords.java), and Modula’s key filter tests for Ctrl on every OS, so its chord is Ctrl+Shift+P on macOS too (ui/RadioPane.java).
  • KBD-06 SHOULD The palette matches fuzzily over the command’s title and over the words of its id or its keywords; the description is shown, not matched. A query that names a command’s title outranks a fuzzy hit. Each row shows the command’s binding in the active keymap. See the Command Palette template.
    • Check (code): the palette’s matcher matches the query fuzzily against each command’s title and finds a command by a word of its id or a keyword that its title doesn’t carry; a query that spells a command’s title ranks that command above the fuzzy hits; the description is drawn and never matched, and each row draws the binding the active keymap gives the command. A ranking test that asserts the order is the surest evidence.
    • Reference: Editora ui/CommandPalette.java (orderedMatches), search/FuzzyMatch.java. It scores the title first; when the title doesn’t match, the id’s namespace word as a keyword (Command.keywords); then the names IntelliJ and VS Code give the command (command/OtherIdeNames.java). It doesn’t match the rest of the id or the description, which is shown under the list. CommandPaletteRankTest holds the order (aCommandIsFoundByItsNamespaceWhenItsTitleDoesNotCarryIt, aKeywordMatchRanksBelowEveryTitleMatch, and for a typed title anExactTitleLeadsAnotherCommandsAlias and aWholeOneWordTitleLeads). The app template’s ui/Picker.java (rank, with idWords) matches the title fuzzily and the id’s words, never the description, and puts a title that holds the query first (PickerFxTest, ranksTitlesFirstAndSkipsUnavailableRows).
  • KBD-07 MUST The palette and every picker (a card that lists choices to filter and pick one from: QOPEN-01) are in-scene overlays in the window’s root StackPane, never a javafx.stage.Popup.
    • Why: on Windows a Popup does not reliably take OS keyboard focus, and the whole app can stop receiving keystrokes.
    • Check (code): the palette and every picker add their node to the root StackPane; none creates a Popup.
    • Reference: Editora ui/OverlayHost.java, the one host installed in the scene’s root StackPane, which shows the palette (ui/CommandPalette.java), the picker (ui/QuickOpen.java) and the picker’s relatives (QOPEN-12).

Every other list choice (recent files, themes, keymaps, a setting’s values) uses the same picker: QOPEN-01.

Editora's command palette filtered to Git commands
Editora: M-x over the editor; typing git lists every Git command.
Torrenta's command palette listing Rename, Remove and Force Resume with shortcuts
Torrenta: the same palette, filtered to torrent actions with their shortcuts.
Termina's command palette over a terminal listing tab commands
Termina: the palette over a shell session, filtered to tab commands.
  • KBD-09 MUST Except in a terminal app, Emacs and CUA keymaps ship as JSON resources, emacs.json and cua.json, CUA with a cua.mac.json variant where Cmd replaces Ctrl. A terminal’s keys belong to the program it runs (C-a, M-x reach the shell), so a terminal app ships one keymap of its own instead, keymap.json and keymap.mac.json, binding its commands to chords programs don’t use. Neither file binds a plain Ctrl or Alt (Option on macOS) with a letter: off macOS that leaves Ctrl+Shift+T, not Ctrl+T, and on macOS Cmd+T, since no program in the terminal receives Cmd.
    • Why: an Emacs keymap in a terminal would take the shell’s own keys away from it: Ctrl+W deletes a word, Ctrl+C interrupts, Alt+F and Alt+B move by word. The shell reads the same keys on macOS, where Option with a letter also types a character.
    • Check (code): emacs.json, cua.json and cua.mac.json are in the app’s resources. In a terminal app, keymap.json and keymap.mac.json are there instead, and no default binding in either file is Ctrl alone or Alt alone with a letter. Read each chord as the OS reads it: a modifier that stands for the OS’s own shortcut key (JavaFX’s Shortcut, as Termina writes it) is Ctrl in keymap.json and Cmd in keymap.mac.json.
    • Reference: Editora src/main/resources/com/editora/keymaps/; Termina’s keymaps/, whose KeymapTest (offMacOsAnApplicationChordNeverTakesPlainCtrlAndALetter) holds the Ctrl half off macOS; no test holds the Alt half or reads keymap.mac.json, where every chord carries Cmd today.
  • KBD-10 SHOULD Except in a terminal app (KBD-09), an app also ships IntelliJ, VS Code and Sublime keymaps as JSON resources beside its Emacs and CUA keymaps: intellij.json, vscode.json and sublime.json, each with its .mac.json variant.
    • Check (code): intellij, vscode and sublime .json and .mac.json files are in the resources. An app that ships a terminal’s keymap, keymap.json and keymap.mac.json with no emacs.json and no cua.json (KBD-09), needs none of them.
    • Command: [ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; has() { find src/main/resources -name "$1" | grep -q .; }; if has keymap.json && has keymap.mac.json && ! has emacs.json && ! has cua.json; then exit 0; fi; ! for k in intellij vscode sublime; do for f in "$k.json" "$k.mac.json"; do has "$f" || echo "missing $f"; done; done | grep .
    • Reference: Editora src/main/resources/com/editora/keymaps/. Termina ships the terminal’s two files only (keymaps/). The app template ships all five, each IDE keymap with its .mac.json (PRESETS in command/Keymap.java). Mirada ships Emacs and CUA and none of these three yet; Torrenta, Modula and nux ship no keymap file.
  • KBD-21 MUST A keymap’s .mac.json variant binds the same commands as the keymap it varies. A chord may differ, to put Cmd where the other has Ctrl, to follow the macOS keymap of the editor it copies, or where macOS keeps the chord for itself (Cmd+Space, Cmd+Tab). See Same on every OS.
    • Why: a command with no chord on one OS is a command that user never finds from the keyboard.
    • Check (code): each keymap file and its .mac.json variant bind the same set of command ids: no command is bound in one and missing from the other. An app that ships no keymap files has no pair to compare and fails with KBD-09. A test that loads both and compares the commands they bind is the surest evidence.
    • Reference: Editora KeymapsTest (guiKeymapsBindSameCommandSetOnBothPlatforms), Termina’s KeymapTest (bothPlatformsBindTheSameCommands) and the app template’s KeybindingsTest (cuaHasAMacVariantWhereCmdReplacesCtrl). Mirada’s cua.json and cua.mac.json bind the same commands, with no test that compares the two.
  • KBD-11 MUST Keymaps are applied in layers: base keymap → user overrides → plugin keymaps → the user’s own bindings again. An app without plugins has the first two.
    • Why: the user always has the last word, and a plugin can still use a chord the user freed.
    • Check (code): one place applies the layers in that order.
    • Reference: Editora ui/KeymapLayers.java.
  • KBD-12 SHOULD A keymap editor in Settings lists every command with its chord, is searchable, and warns of conflicts.
  • KBD-13 SHOULD No command’s chord is written into translated text. Every other label that shows a chord (a hint, the palette, the status bar) shows the binding from the active keymap; tooltips are TBAR-03 and menu rows MENU-15. Fixed keys of a control (Enter, Tab, Esc, arrows) and keys meant for another program may be written.
    • Check (code): no message catalog value names a command’s chord (Ctrl+, Cmd+, C-x, M-x); chords are rendered by one formatter.
    • Reference: Editora command/ChordFormat.java, the one place a binding is rendered. Editora’s command.edit.universalArgument title still carries C-u.
  • KBD-14 SHOULD A multi-key prefix (C-x …) shows a which-key style hint listing the possible next keys.
    • Check (by hand): press C-x in the Emacs keymap and wait.
    • Reference: no app lists the next keys yet. Editora echoes only the pending prefix (C-x -) in the status bar (command/KeyDispatcher.java).
Editora's keymap picker
Keymap: Select… offers Emacs, CUA, Sublime Text, Visual Studio Code and IntelliJ IDEA.
Editora's palette filtered to kill commands with Emacs chords
M-x kill: each command shows its chord from the active keymap.
Termina's keyboard shortcuts window
Termina's shortcuts reference: every key, grouped by menu.
  • KBD-15 MUST Every interactive control is reachable with Tab and operable with Space or Enter. A control is the exception when the keyboard does what it does another way: the buttons of a toolbar stay out of the Tab order (TBAR-02, which says what a toolbar is: a bar of labeled buttons is not one, and its buttons are held to this rule), and the find-bar and filter controls that FIND-16 names may leave it. See Accessibility.
    • Why: a control that Tab can’t reach is one a keyboard-only or screen-reader user can’t use at all.
    • Check (by hand): first in the source, find every control the keyboard cannot focus: one the app takes out of the Tab order (setFocusTraversable(false) in the code, -fx-focus-traversable: false in a stylesheet), and a label or a pane that acts on a click. The keyboard does all that each one does another way: it is a button of a toolbar as The toolbar defines one (TBAR-02; a bar of labeled buttons, such as nux’s, is not one), a find-bar or filter control that FIND-16 lets leave the Tab order (one that fails FIND-16, such as an option’s toggle that no command toggles, fails here too), a list whose text field moves its selection with the arrow keys, or a control whose every action, the rows of its right-click menu included, a registered command also runs. A control only the mouse can work fails the rule, and the source alone shows it. Then in the running app, Tab reaches every other control of each window and dialog, and Space or Enter works it.
    • Reference: the app template, where each control the keyboard cannot focus has its other way: the status bar’s echo area, error count and update notice run commands (view.messageLog, help.openNewRelease: ui/StatusBar.java), its toolbar’s buttons are TBAR-02’s (Icons.toolbarButton in ui/Icons.java), a tool window’s header buttons run commands (ui/ToolWindowManager.java), the find bars’ buttons are FIND-16’s (ui/FindBar.java), and the picker’s list is moved from its field (ui/Picker.java). Editora doesn’t hold the rule everywhere yet: the Clear button of its Message Log (ui/MessageLogPopup.java) and the Previous Run and Save Output buttons of its build console (ui/BuildToolPanel.java) are out of the Tab order with no command and no key behind them. Modula doesn’t either: it takes every control of its window out of the Tab order (RadioPane.keepOutOfFocus) and gives most of what they do a key or a palette row, but a preset’s Rename and Remove are rows of its chip’s right-click menu alone (ui/PresetBar.java). Termina doesn’t either: the regular-expression toggle of its find bar is out of the Tab order, and no command and no key toggles it (ui/SearchBar.java; FIND-16 fails for it too).
  • KBD-16 MUST Every button, toggle, menu button, link, combo box, check box, radio button and text field shows the focus ring when the keyboard focuses it. The ring is one layer of :focus-visible rules in the app stylesheet, after every rule that sets a border or background on the same controls, since rules of equal specificity are decided by order. Its color and contrast are ICON-12.
    • Why: a keyboard user who can’t see where focus is can’t use the window; the ring’s color is a MUST, and so is drawing it.
    • Check (code): the app stylesheet holds the ring as one block of :focus-visible rules that covers each of these kinds of control the app uses (buttons, toggles, menu buttons, links, combo boxes, check boxes, radio buttons, text fields), and no rule after the block, of the same or higher specificity, sets again what the block sets on those controls (the border; on a text field, the background insets). A test that tabs to each control family and asserts the ring is the surest evidence.
    • Reference: Editora app.css (Keyboard focus, one layer for every control), held by FocusRingFxTest, which tabs to each control family. Termina’s app.css and Mirada’s mirada.css end with a layer of the same kind; neither app has a test that tabs to a control.
  • KBD-22 SHOULD The focus ring is 2 px wide at the default zoom and sits just outside the control with a 1 px gap: a border with negative insets, which adds nothing to the control’s own, so focusing a control never moves the layout. Two kinds of control draw it inside instead, at the same 2 px and still without moving anything: a text field, whose own focus border is widened, and a control flush with the window’s edge, where a ring outside would be cut off.
    • Why: a ring drawn on the control’s own border is lost on a flat or filled button, and one that takes room makes the row jump as Tab moves along it. A text field already draws an accent border on focus, so a second ring around it would be one too many.
    • Check (code): in the :focus-visible rules of KBD-16, the one for the controls that take the outside ring (buttons, toggles, menu buttons, links, combo boxes, the boxes of check boxes and radio buttons, as many of them as the app has) sets -fx-border-width: 2 and -fx-border-insets: -3; the one for text fields widens the field’s focus border to 2 px instead (-fx-background-insets: 0, 2px); and a rule that draws the ring inside a control at the window’s edge keeps the 2 px width and takes the room back out of the control’s padding.
    • Reference: Editora app.css (Keyboard focus), Termina’s app.css and Mirada’s mirada.css: the same outside ring, and the same text-field rule (Mirada’s covers text areas too). Editora alone has the second exception: .tool-stripe-button:focus-visible draws the ring at -fx-border-insets: 1 and gives 3 px of padding back, since the stripes sit against the window’s edge. The app template’s app.css has the same outside ring and text-field rule; its check boxes and radio buttons take the ring around the whole control, label included, not around the box alone.
  • KBD-18 SHOULD A row that turns a setting on or off (in Settings, a panel or a dialog) uses a switch the keyboard operates: it takes focus, Space toggles it, and its accessible role is TOGGLE_BUTTON.
    • Why: a bare AtlantaFX ToggleSwitch is mouse-only.
    • Check (code): every row that turns a setting on or off uses a switch that takes focus, toggles on Space and sets AccessibleRole.TOGGLE_BUTTON (Editora has one class for it, SettingSwitch); a row that uses AtlantaFX’s ToggleSwitch as it comes fails.
    • Reference: Editora ui/SettingSwitch.java.

Related rules on other pages: every icon-only button gets its name from one helper, TBAR-01; rows wrap instead of being cut short in every language, INTL-04; readable text and its contrast are one rule, ICON-09.

Pauta Next · unreleased changes after 6.1.0 · Changelog · This page in the latest edition