CheaXheet — Keyboard Shortcut Overlay

The problem with a dense keyboard layout

The X-Type layout I run with OmniWM has over 80 bindings distributed across six modifier layers. The density is intentional — nearly every operation reachable from home row, no mouse required for window management, workspace switching, or app launching. I designed this layout over several months of iteration and I still forget bindings. Not the ones I use hourly, but the ones in layer four or five that handle less-common operations: moving a window to a specific display, adjusting gaps, resizing in a particular axis. When I need one of those, the default way to look it up is to open the Karabiner config file, scan through YAML, find the binding, close the file, and resume.

That lookup defeats the purpose of the layout. The layout exists to reduce friction. Consulting a YAML file mid-task is friction of the worst kind — it interrupts thought, pulls focus to a different application, and takes long enough that you lose the thread. The right solution is obvious once you see the problem clearly: a hotkey that summons a reference panel instantly, searchable, visible without an application switch, dismissed with one key. The requirement wrote itself. The engineering question was what "instantly" required architecturally.

The live SVG diagram as the core interaction

I could have built CheaXheet as six tabs of tables — modifier layer per tab, key on the left, action on the right. That would have taken forty minutes to implement and been technically functional. The problem with tables for a keyboard layout is that spatial position is part of how humans remember keybindings. "That binding is in the bottom-right cluster" is a real and useful memory cue. Tables strip that information out entirely.

The SVG keyboard diagram renders every key on the physical 65% layout. Switching to a modifier tab highlights the keys that have active bindings on that layer — colour changes based on the layer. The interaction that makes the tool genuinely useful is this: when you physically hold a modifier key, CheaXheet detects the keydown event via Tauri's global key listener and auto-switches to the corresponding tab. You are not abstractly browsing a reference document. You are holding the modifier you are about to use, and the diagram lights up to show exactly what is reachable. The lookup becomes part of the gesture rather than a detour from it.

Fuse.js handles fuzzy search across all six modifier layers simultaneously. Searching for "resize" surfaces every resize-related binding regardless of which layer it lives on, with the layer labelled and the matched characters highlighted via Fuse's match index. I added search after realising that the tab structure only helps when you already know which layer a binding is on — which is precisely the situation where you don't need the reference. Search handles the case where you don't know.

The companion parse-karabiner.ts script diffs the live Karabiner config against the binding data stored in the app. Karabiner is the source of truth for what the keyboard actually does. If I add a binding in Karabiner and forget to update CheaXheet, the overlay goes stale and misleads rather than helps. The script runs as a pre-commit hook and lists divergences. A reference tool that can become incorrect is worse than no reference tool.

What 31 minutes actually means

The headline is honest but needs context. The SVG keyboard layout existed — I had drawn it for a separate project. The Tauri v2 boilerplate with Svelte 5 was a template I had used before. The Fuse.js integration pattern was familiar from other search implementations. The ActivationPolicy::Accessory trick that removes CheaXheet from the Dock and Cmd+Tab switcher — so it behaves as a pure overlay rather than an application — required research that happened before the 31 minutes began. tauri-plugin-store for persisting window position and active tab across launches: researched beforehand.

What 31 minutes means is that when the architecture is fully resolved and the components exist, the execution collapses. Every minute of that implementation was keystrokes, not decisions. The preparation — drawing the SVG, learning ActivationPolicy::Accessory, picking Fuse.js over alternatives, designing the modifier-detection interaction — was what made fast execution possible.

This is the pattern I keep returning to across every fast delivery: speed during implementation is a function of decisions made before implementation starts. The 31-minute number is a measurement of execution. The judgment that made it possible was the work before the timer.