Keyboard first
Commands
Section titled “Commands”- KBD-01 MUST Every user-facing action is a
Command(id, title, runnable) registered in oneCommandRegistry.- Check (code): menu items, toolbar buttons, palette rows and key bindings run a command id through the registry; no control’s handler does work no command can reach.
- Reference: Editora
command/Command.java,command/CommandRegistry.java.
- 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.
- Check (code): every registered id matches
- KBD-03 MUST A command’s title comes from
command.<id>and its palette description fromcommand.<id>.descin 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>orcommand.<id>.desckey. - 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).
Command Palette
Section titled “Command Palette”- KBD-05 MUST The Command Palette opens with
M-xin the Emacs keymap andCtrl+Shift+P(Cmd+Shift+Pon macOS) in the others.- Check (code): each bundled keymap binds that chord to the palette command.
- Reference: Editora
keymaps/emacs.json(M-x),cua.jsonandvscode.json(C-S-p),cua.mac.json(Cmd-S-p), all topalette.show.
- 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.
- Check (test): a ranking test puts the title match first.
- Reference: Editora
ui/CommandPalette.java,search/FuzzyMatch.java.
- KBD-07 MUST The palette is an in-scene overlay in the window’s root
StackPane, not ajavafx.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 aPopup. - Reference: Editora
ui/CommandPalette.java.
- KBD-08 SHOULD The same picker serves every other list choice: recent files, themes, keymaps, a setting’s
values.
- Check (code): no second list-picker class or
ChoiceDialogfor those choices. - Reference: Editora
ui/QuickOpen.java.
- Check (code): no second list-picker class or



Keymaps
Section titled “Keymaps”- KBD-09 MUST Emacs and CUA keymaps ship as JSON resources, CUA with a
.mac.jsonvariant where Cmd replaces Ctrl.- Check (code):
emacs.json,cua.jsonandcua.mac.jsonare in the app’s resources. - Reference: Editora
src/main/resources/com/editora/keymaps/.
- Check (code):
- KBD-10 SHOULD IntelliJ, VS Code and Sublime keymaps ship the same way, each with its
.mac.jsonvariant.- Check (code):
intellij,vscodeandsublime.jsonand.mac.jsonfiles are in the resources. - Reference: Editora
src/main/resources/com/editora/keymaps/.
- Check (code):
- 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.
- Check (by hand): open Settings → Keymap, search, and bind a chord that is taken.
- Reference: Editora
ui/SettingsKeymapsPage.java; conflicts fromKeybindingEdits.takenDefaults.
- 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’scommand.edit.universalArgumenttitle still carriesC-u.
- Check (code): no message catalog value names a command’s chord (
- 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-xin 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).
- Check (by hand): press



Focus and accessibility
Section titled “Focus and accessibility”- 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;
FocusRingFxTestholds that every control family draws the focus ring when Tab reaches it.
- KBD-16 SHOULD The keyboard focus ring is one layer of
:focus-visiblerules at the end ofapp.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-17 MUST Icon-only buttons are built by one helper that sets both the tooltip and the accessible text.
- Check (code): no icon-only
Buttonis built outside the helper. - Reference: Editora
ui/Icons.java(Icons.button). Editora’s main toolbar doesn’t yet:WindowToolbar.setupButtonandToolbarCoordinator.buildExtraButtonset the tooltip but no accessible text.
- Check (code): no icon-only
- KBD-18 SHOULD On/off rows use a keyboard-operable switch with the
TOGGLE_BUTTONrole.- Why: a bare AtlantaFX
ToggleSwitchis mouse-only. - Check (code): no
new ToggleSwitchoutside the switch class. - Reference: Editora
ui/SettingSwitch.java.
- Why: a bare AtlantaFX
- KBD-19 SHOULD Readable text uses
-color-fg-mutedor stronger;-color-fg-subtle(about 3:1) is for disabled or decorative text only.- Check (test): a pure contrast test over the stylesheets.
- Reference: Editora
StyleContrastTest.
- KBD-20 SHOULD Rows wrap instead of truncating to ”…”.
- Check (by hand): run the app in German at 1024 px wide; no test catches a cut row.
- Reference: Editora
messages_de.properties.
Pauta 2.0.1 · · Changelog · This page in the latest edition