Skip to content
Pauta4.4.0

Keyboard first

Rules on this page 17
IDLevelRule
Commands
KBD-01MUST
Every user-facing action is a Command (id, title, runnable) registered in one CommandRegistry.
KBD-02SHOULD
Command ids are dotted and grouped by area: file.open, view.toggleStatusBar, help.reportProblem.
KBD-03MUST
A command’s title comes from command.<id> and its 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.
KBD-06SHOULD
The palette matches fuzzily over title, id and description; 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 is an in-scene overlay in the window’s root StackPane, not a javafx.stage.Popup.
Keymaps
KBD-09MUST
Emacs and CUA keymaps ship as JSON resources, CUA with a .mac.json variant where Cmd replaces Ctrl.
KBD-10SHOULD
IntelliJ, VS Code and Sublime keymaps ship the same way, 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 label shows the binding from the active keymap. 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-15SHOULD
Every interactive control is reachable with Tab and operable with Space or Enter. Toolbar buttons are the exception: they stay out of the Tab order (see Toolbars and tooltips).
KBD-16SHOULD
The keyboard focus ring is one layer of :focus-visible rules at the end of app.css.
KBD-18SHOULD
On/off rows use a keyboard-operable switch with the TOGGLE_BUTTON role.
  • KBD-01 MUST Every user-facing action is a Command (id, title, runnable) registered in one CommandRegistry.
  • KBD-02 SHOULD Command ids are dotted and grouped by area: file.open, view.toggleStatusBar, help.reportProblem.
    • Check (code): every registered id matches <area>.<camelCaseName>.
    • Reference: Editora ui/MenuBarModel.java.
  • KBD-03 MUST A command’s title comes from command.<id> and its palette description from command.<id>.desc in the message catalogs.
    • Why: a registered command is then localized and discoverable without extra work.
    • Check (test): a catalog parity test fails when a registered command has no command.<id> or command.<id>.desc key.
    • Reference: Editora i18n/messages.properties, MessagesTest.
  • 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).
  • 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.
  • KBD-06 SHOULD The palette matches fuzzily over title, id and description; 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-07 MUST The palette is an in-scene overlay in the window’s root StackPane, not 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/CommandPalette.java.

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 Emacs and CUA keymaps ship as JSON resources, CUA with a .mac.json variant where Cmd replaces Ctrl.
  • KBD-10 SHOULD IntelliJ, VS Code and Sublime keymaps ship the same way, each with its .mac.json variant.
  • 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 (test): a test loads each keymap and its .mac.json variant and compares the commands they bind.
    • Reference: Editora KeymapsTest (guiKeymapsBindSameCommandSetOnBothPlatforms).
  • 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 label shows the binding from the active keymap. 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 SHOULD Every interactive control is reachable with Tab and operable with Space or Enter. Toolbar buttons are the exception: they stay out of the Tab order (see Toolbars and tooltips).
    • Check (by hand): Tab through every window and dialog without the mouse.
    • Reference: Editora; FocusRingFxTest holds that every control family draws the focus ring when Tab reaches it.
  • KBD-16 SHOULD The keyboard focus ring is one layer of :focus-visible rules at the end of app.css.
    • Check (test): an FX test tabs to each control family and asserts the ring.
    • Reference: Editora app.css (Keyboard focus, one layer for every control), FocusRingFxTest.
  • KBD-18 SHOULD On/off rows use a keyboard-operable switch with the TOGGLE_BUTTON role.
    • Why: a bare AtlantaFX ToggleSwitch is mouse-only.
    • Check (code): no new ToggleSwitch outside the switch class.
    • 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 4.4.0 · · Changelog · This page in the latest edition