§2 Keyboard Interaction

§2.1 Primary Model

CUA is the primary keyboard model for all Monospace TUI applications. Every interactive element MUST be reachable and operable using only the keyboard. Mouse support is OPTIONAL and MUST NOT be required for any workflow. (CUA §1, KLM §5 keyboard efficiency advantage)

§2.2 Standard Key Assignments

Every action in this standard has both a CUA key (F-key tradition) and a common key (non-F-key alternative). Both MUST be bound. Applications MUST NOT require F-keys for any workflow — the common key MUST always work as an equivalent path. This ensures usability on modern laptops where F-keys may require an Fn modifier.

Case-insensitivity rule: All single-letter key bindings MUST be case-insensitive — r and R trigger the same action, d and D trigger the same action, etc. Applications MUST bind both cases but MUST display only the lowercase form in the footer key strip. Displaying both cases is unnecessary clutter. The sole exception is the g / G scrolling pair (see Tier 1 Scrolling below), where case carries distinct meaning from vim convention.

Tier 1 — Global keys (MANDATORY, always active):

Tier 1 — Text entry keys (MANDATORY, active when a text input field is focused):

Applications MUST NOT reassign Tier 1 keys to different actions unless an archetype explicitly overrides specific keys (see §2.7). (CUA §1, lazygit/k9s/ranger/yazi/btop conventions)

Tier 1 — Scrolling keys (MANDATORY in scrollable content when no text input focused):

Tier 2 — Common keys (SHOULD be used when the action exists):

These keys are not mandatory for every application, but when an application provides the listed action, it MUST use the specified key. This prevents every app from inventing its own binding for the same concept.

All Tier 2 letter keys are case-insensitive per the global rule.

Tier 3 — Screen mnemonic keys (application-defined):

Applications with multiple top-level screens SHOULD assign single-letter mnemonics based on the screen name’s first letter. These provide instant navigation without traversing menus.

Rules for Tier 3 keys:

• MUST NOT conflict with any Tier 1 or Tier 2 key.
• MUST be case-insensitive per the global rule (bind both cases, show only lowercase in footer).
• SHOULD prefer the first letter of the screen name.
• If a conflict exists with Tier 1/2, use the second letter or a distinctive letter.
• MUST be shown in the footer key strip.

Common mnemonic patterns (for reference, not prescriptive):

Tier conflict resolution: When a Tier 3 mnemonic would shadow a Tier 2 key, the application MUST either:

1. Use an alternative letter (e.g., t for Settings instead of s), or
2. Use Ctrl+letter (e.g., Ctrl+S for Settings, leaving s for sort), or
3. Use number keys (1–9) for all screen navigation, avoiding letter conflicts entirely.

Key scope rules: Single-letter keys (q, r, /, d, e, a, s, g, n, y, and Tier 3 mnemonics) MUST be suppressed when a text input widget has focus — in that context, keystrokes are literal character input. Only modified keys (Ctrl+, Alt+, F-keys) and Esc remain active during text entry. (CUA §1, vim conventions, lazygit/k9s/ranger/yazi/btop cross-application consensus, ~/projects/ codebase conventions)

§2.3 Footer Key Discoverability

All available keys for the current context MUST be displayed in the footer key strip (§1.4). A key that is not shown in the footer MUST NOT be required to complete a task — though it MAY exist as an accelerator for expert users if the same action is available through a visible path. (CUA §1, Norton Commander §7)

When ? help is provided, it SHOULD be filtered to the focused pane, active keyboard layer, or current object scope rather than showing a global unfiltered command dump.¹ This keeps help aligned with the current task surface and reduces recall burden in dense multi-pane interfaces.

§2.4 Mnemonic Rules

Menu items and labeled controls SHOULD have mnemonic accelerators (underlined letters). Mnemonics:

• MUST be unique within their menu level or control group.
• SHOULD prefer the first letter of the label text.
• MUST NOT be a space character.
• MUST be marked in source with tilde (~F~ile) or ampersand (&File) prefix notation.

Typing the mnemonic character while its menu is active MUST select that item immediately. (CUA §1 mnemonic assignment rules, OS/2 §2)

§2.5 Navigation Order

Tab order MUST follow left-to-right, top-to-bottom visual order for LTR locales, wrapping from last field to first. Arrow keys MUST move only within a single control (e.g., between radio buttons in a group, or characters in a text field) — arrow keys MUST NOT cross control boundaries. (CUA §1)

§2.6 Composable Keyboard Layers

Archetypes MAY add additional keyboard layers beyond the CUA base, provided:

• The current layer MUST be indicated in the status area or footer.
• Esc MUST always return to the base CUA layer.
• Layer-specific keys MUST NOT shadow CUA base keys unless the layer is explicitly activated.
• Prefix layers SHOULD expose available continuations in a lightweight popup, status hint, or other non-blocking surface while the prefix is pending.²

(monospace-design-tui-research.md §7 six keyboard interaction models)

§2.7 Archetype Key Overrides

An archetype (§11) MAY override keys from the Tier 1 or Tier 2 tables when the archetype’s domain conventions are universally established and would cause user confusion if replaced. When an archetype overrides a standard key:

• The override MUST be documented in the archetype’s “Keyboard additions” table with the annotation “(overrides §2.2)”.
• The overridden key’s original action MUST remain accessible through an alternative key binding.
• The footer key strip MUST display the overridden binding, not the standard one.

Example: The File Manager archetype (§11.3) overrides F3 (normally Back/Cancel) with “View file” and F5/r (normally Refresh) with “Copy.” In this archetype, Esc serves as Back/Cancel and Ctrl+R serves as Refresh. The r key is freed for reuse within the archetype since Refresh has moved to Ctrl+R.

(CUA §1, Norton Commander §7 — domain conventions)

§2.8 Key Sets

A key set is a coherent cluster of bindings that are intended to be used together across related screens. Applications SHOULD define one or more key sets and apply them consistently across screens serving the same task family.³

Rules for key sets:

• A key’s meaning MUST remain stable across screens that share a key set.
• Applications MUST NOT remap the same single-letter key to a different domain action on sibling screens within the same key set.
• If a screen changes to a different key set, the change MUST be visible through the footer key strip, status area, or explicit mode/screen labeling.
• Tier 1 keys remain in force unless an archetype override (§2.7) applies.
• Arrow keys MUST remain within one control only (§2.5). Multi-pane or multi-widget switching within a key set MUST use Tab/Shift+Tab, numbered view mnemonics, or another non-arrow binding.

Recommended key sets:

Applications MAY define additional domain-specific key sets, but the set MUST be documented and applied consistently across the screens that claim it.