9b41d51231
Some checks are pending
Auto-update PR branches / Update open PR branches (push) Waiting to run
CI / Frontend Static Quality Checks (push) Waiting to run
CI / Frontend Tests & Coverage (push) Waiting to run
CI / Rust Tests & Quality Checks (push) Waiting to run
CI / Linux build verification (push) Waiting to run
Deploy docs / Build VitePress site (push) Waiting to run
Deploy docs / Deploy to GitHub Pages (push) Blocked by required conditions
Release (Alpha) / Compute alpha version (push) Waiting to run
Release (Alpha) / Build release artifacts (push) Blocked by required conditions
Release (Alpha) / GitHub Release (alpha) (push) Blocked by required conditions
Release (Alpha) / Update docs and release pages (push) Blocked by required conditions
Source snapshot: 514ab1975951d94342ea38e64101d5a0f1c51c77
2.0 KiB
2.0 KiB
type, id, title, status, date
| type | id | title | status | date |
|---|---|---|---|---|
| ADR | 0020 | Keyboard-first design principle | active | 2026-03-01 |
Context
Laputa is a productivity tool for knowledge workers who spend most of their time typing. Mouse-heavy interactions interrupt flow. Every feature should be reachable without touching the mouse, and the app must be fully testable via keyboard events (important for Playwright automation and accessibility).
Decision
Every feature must be reachable via keyboard. Every command palette entry must also appear in the macOS menu bar (File / Edit / View / Note / Vault / Window). This is both a design principle and a QA requirement. Navigation, note switching, panel toggling, search, and all commands work via keyboard shortcuts or the Cmd+K command palette.
Options considered
- Option A (chosen): Keyboard-first with menu bar parity — full keyboard accessibility, menu bar for discoverability, testable via Playwright keyboard events. Downside: more work per feature (must wire shortcut + menu item + command palette entry).
- Option B: Mouse-primary with some shortcuts — faster to implement. Downside: poor flow for power users, harder to automate testing.
- Option C: Keyboard-only (no menu bar) — simplest. Downside: poor discoverability, macOS HIG violation.
Consequences
useCommandRegistry+useAppCommandsbuild a centralized command registry with labels, shortcuts, and handlers.CommandPalette(Cmd+K) fuzzy-searches all registered commands.menu.rsdefines the native macOS menu bar with accelerators matching keyboard shortcuts.useAppKeyboardregisters global keyboard shortcuts.useMenuEventsbridges menu bar clicks to command handlers.- QA uses
osascriptkeyboard events for native testing — no mouse, nocliclick. - macOS gotcha:
Option+Nproduces special characters — usee.codeorCmd+Ninstead. - Re-evaluation trigger: if a non-macOS platform (Windows, Linux) is supported and needs different menu/shortcut conventions.