Keyboard mnemonics

Alt+letter access keys ("mnemonics") for menus, menu bars, dialog buttons, and form labels — the underlined-letter convention that lets keyboard users jump to a control without a pointer. Distinct from global accelerators (Ctrl/Cmd+key). First-class on the Linux/GNOME desktop; the KoderMnemonicLabel primitive carries the underline + Alt binding. GNOME HIG parity — critical for Koder apps not looking "foreign" on the Koder Kodix (GNOME) shell.

Status: v0.1.0 — Draft. Promoted from the GNOME HIG parity scan (metadocsstack #082); the umbrella's #1 risk-callout for the Koder Kodix ISO. Source: https://developer.gnome.org/hig/guidelines/keyboard.html

R1 — Mnemonic vs accelerator (distinct concepts)

  • Mnemonic (this spec): an Alt+letter access key tied to a *visible

    label*, surfaced as an underlined character. Contextual — active while its surface (menu, dialog, form) is focused. Discovered visually.

  • Accelerator: a global Ctrl/Cmd+key shortcut to an action,

    independent of any visible label (e.g. Save = Ctrl+S). Out of scope here (separate shortcuts spec).

A control may have both (a mnemonic to reach it, an accelerator to invoke its action).

R2 — KoderMnemonicLabel

The mnemonic is carried by a KoderMnemonicLabel primitive (or label property), NOT hand-drawn underlines:

  • Source marks the mnemonic character in the label string (e.g. a leading

    _ before the letter, _File); the primitive renders the underline and registers the Alt+letter binding.

  • The underline draws on the chosen letter only; if the letter is absent

    from a (translated) label, R5 applies.

R3 — Scope & uniqueness

  • Mnemonics are unique within their activation scope (one menu, one

    menu bar level, one dialog's buttons, one form). The same letter may recur across different scopes.

  • On collision within a scope, the author reassigns; the primitive MAY

    warn in dev builds but never silently double-binds (first-wins is a bug, not a policy).

R4 — Discoverability

  • Underlines are shown when the user signals keyboard intent — on Alt

    press/hold, or always when a "show shortcuts" accessibility preference is on. They MAY be hidden during pure pointer use (GNOME behavior) but MUST be revealable; never permanently hidden.

  • A menu bar opened by Alt moves focus and shows its mnemonics.

R5 — i18n (mnemonics are per-locale)

  • The mnemonic letter is a property of the translated label, not the

    source: "File" (en) vs "Arquivo" (pt-BR) may pick different letters.

  • Translators choose mnemonics per locale; the i18n contract

    (specs/i18n/contract.kmd) carries the marked label per language, and per-locale uniqueness (R3) is validated at build/lint time.

  • Never hardcode the English mnemonic across locales.

R6 — Accessibility

  • The binding is exposed to assistive tech via the platform a11y layer

    (AT-SPI on Linux; aria-keyshortcuts on web) so it is announced, not just visual.

  • Mnemonics complement, never replace, full tab-order focusability — every

    mnemonic-bearing control is also reachable by Tab.

  • The underlined letter meets normal label contrast; the underline is not

    the sole indicator for screen-reader users (the a11y binding is).

Não-escopo

  • Global accelerators / keyboard shortcuts (Ctrl/Cmd+key) — separate spec.
  • Single-key type-ahead/first-letter navigation in lists (a list behavior).
  • Platform chrome shortcuts owned by the OS/WM.