AWDCS

A scope-based keymap system that brings simplicity and clarity to modal editor configurations through mindful organization and purposeful design.

Philosophy

Traditional modal editor keymaps typically organize bindings by tool or function.

But I noticed a pattern in my thinking: I always consider the scope first.

• I want to toggle the App keymaps.
• I want to search the entire Workspace for...
• I want to look in this Document for...
• I want to do something with this Change...
• I want to rename that Symbol...

That's when I decided to adapt my modal editor to this mental model.

This system takes a different approach by organizing mappings based on their scope of operation:

<Scope><?Group?><Operation>

• [A]pp (<leader>a) - Application-level operations
• [W]orkspace (<leader>w) - Operations affecting the entire workspace
• [D]ocument (<leader>d) - Operations on the current document
• [C]hange (<leader>c) - Operations on a change (Hunk)
• [S]ymbol (s) - Operations on code symbols

Design Principles

• Scope First
  • Every operation must clearly belong to a specific scope (workspace, document, symbol)
  • The scope should be immediately obvious from the operation's nature
• Semantic Operations
  • Mappings should represent clear, meaningful operations
  • Focus on frequently used operations that benefit from quick access
  • Focus on what the operation means, not how it's implemented
• Tool & Editor Agnostic:
  • Mappings should be independent of specific tools or editors
  • Use semantic terms (e.g., 'History' instead of 'Git')
  • Implementation details are left to the user's configuration
• Preserve Editor Defaults:
  • Don't replace basic editor operations with custom mappings
  • Focus on operations that enhance rather than replace core functionality
  • Leave common editor commands in their traditional form
• Consistent Patterns:
  • Second key should relate to the action within the scope
  • Related operations should share the same scope
  • Maintain predictable patterns across all mappings
• Single Source:
  • Each operation should have exactly one mapping
  • Avoid duplicate mappings across different key combinations
  • Choose the most appropriate and efficient mapping location

Leader Key

I personally use (and recommend) , as my leader key, but you can use any key you like. This way we use both hands in combination when typing the keymaps, which reduces strain by balancing the workload on the fingers. Also I find that the the middle finger is faster than the thumb, which is generally a good thing, but also very nice to quickly double tap the leader key, to reach the command mode.

Keymap

<leader><leader> - Global

This is a little bit of a special case, as it's not really a keymap, but a global command. This is an alternative way to quickly enter the command mode (same as :), which lends to increased direct usage of the builtin commands without mapping them.

Since I am using home row mods (really bottom row mods.. See my layout here, I sometimes get missfires for quickly typing :. When quickly dobule tapping the leader key, I quickly and safely reach the command mode, without worrying about typos.

This is of course just personal preference.

For example in Neovim you can create a mapping like so:

vim.keymap.set({ "n", "x" }, "<leader><leader>", function()
    vim.api.nvim_feedkeys(":", "n", true)
end, { desc = "Command Mode" })

Alphabetical Order

All keybindings in each scope are listed alphabetically for easier reference and maintenance, not by frequency of use or importance.

Ergonomic Design

When using , as the leader key, the system naturally creates efficient left-hand finger patterns. The scope key (first key after leader) and the operation key (second key) are often adjacent or nearby on the keyboard (e.g., sa, we, wd), minimizing finger travel and creating comfortable rolling motions for the left hand. This ergonomic benefit is a fortunate consequence of the alphabetical organization combined with the QWERTY layout's letter placement.

<leader>a - [A]pp

Keybinding	Mnemonic	Description	Notes
<leader>aa	App Actions	Show available app actions / commands
<leader>ad	App Document	Open document from any workspace	If available. (e.g. file-surfer.nvim)
<leader>af	App Focus	Focus Mode
<leader>ai	App Intelligence	Show AI tools	If available.
<leader>aj	App Jumps	Show application jump list	If available.
<leader>ak	App Keybindings	Show keybindings
<leader>al	App Languages	Manage language servers
<leader>an	App Notifications	Show notifications
<leader>ag	App Git	Show git module
<leader>ao	App Options	Toggle app options like Background, Line numbers, etc.
<leader>ap	App Plugins	Manage plugins
<leader>ar	App Recent	Open recently visited documents accross all workspace	If available.
<leader>as	App Settings	Toggle app settings	In Neovim this would let us fuzzy find config files, and on a mac app this would lead us to settings.json. (cmd-,)
<leader>at	App Themes	Switch theme or colorscheme
<leader>aw	App Workspace	Open workspace
<leader>az	App Zoom	Zoom Mode
<leader>aI	App Information	Show app information (formatter, lsp, linters, help tags, etc)

<leader>w - [W]orkspace

Keybinding	Mnemonic	Description	Notes
<leader>wd	Workspace Document	Find document in workspace
<leader>we	Workspace Explorer	Open file explorer
<leader>wf	Workspace Find	Find and replace in workspace	Optional: Maybe not needed, if the editor offers a replace field under <leader>wt.
<leader>wg	Workspace Git	Show workspace version control history
<leader>wc	Workspace Changed	Show changed files in workspace
<leader>wp	Workspace Problems	Show workspace diagnostics
<leader>wr	Workspace Recent	Show recently visited documents	Optional: Maybe not needed, if editor merges recently opend documents in <leader>wd.
<leader>ws	Workspace Symbol	Find symbol in workspace
<leader>wt	Workspace Text	Find text in workspace
<leader>wvb	Workspace Version Branches	Show version branches
<leader>wvc	Workspace Version Commits	Show version commits
<leader>wvt	Workspace Version Tags	Show version tags
<leader>ww	Workspace Word	Find word under cursor in workspace	Optional: Maybe not needed if the editor uses the selection under the cursor when using <leader>wt.

<leader>d - [D]ocument

Shortcut	Mnemonic	Description	Notes
<leader>da	Document Associated	Find associated documents
<leader>dc	Document Changes	Show document changes (if available)
<leader>df	Document Find	Find and replace in document
<leader>dg	Document Git	Show document version control history	e.g. Visualization of git log
<leader>dl	Document Last	Switch to last document	<C-^> in Neovim
<leader>dp	Document Problems	Show document diagnostics
<leader>ds	Document Symbol	Find symbol in document
<leader>dt	Document Text	Find text in document
<leader>du	Document Undo	Open undo tree	If available.
<leader>dvr	Document Version Revert	Revert changes
<leader>dvs	Document Version Stage	Stage changes
<leader>dvu	Document Version Utage	Unstage changes
<leader>dw	Document Word	Find word under cursor in document
<leader>dya	Document Yank All	Copy whole document
<leader>dyp	Document Yank Path	Copy path of document	e.g. absolute, relative path, filename etc.
<leader>dyr	Document Yank Remote	Copy remote path of document	e.g. GitHub Perma link

<leader>c - [C]hange

Shortcut	Mnemonic	Description	Notes
<leader>cs	Change Stage	Stage current hunk
<leader>cr	Change Revert	Revert current hunk
<leader>cu	Change Undo	Undo staged hunk
<leader>cd	Change Diff	Show hunk diff
<leader>ca	Change All	Show all changes	If available. (e.g. Snacks.picker.git_diff)

s - [S]ymbol

Note

Unlike other scopes, symbol operations do not use the leader key due to their high frequency of use. This intentional exception optimizes for efficiency while maintaining the semantic meaning of the scope. But of course it is possible to just also use the leader prefix before that!

Caution

If you plan to use it without a leader prefix, and use Neovim, I would recommend to disable the default s Binding. Yes- this goes against the principle not to overwrite editor defaults, but it is (at least for me), not a used keymapping, and is also often overridden by other plugins and systems.

You can disable the default mapping in Neovim like so:

vim.keymap.set("n", "s", "<Nop>")

Shortcut	Mnemonic	Description	Notes
s;	Symbol Actions	Show symbol actions
sd	Symbol Definition	Go to symbol definition
sg	Symbol Git	Show git blame information
si	Symbol Info	Show symbol information	Hover Information
sl	Symbol Log	Insert log for symbol	If available. (e.g. Programmatically log symbol under cursor)
sn	Symbol Name	Rename symbol
sr	Symbol References	Show symbol references
sI	Symbol Inspect	Inspect symbol under cursor

Contributing

Feel free to:

• Suggest improvements to the scope organization
• Propose new scopes for uncovered contexts
• Share your adaptations for different editors

License

MIT License - Feel free to adapt and use in your own configurations.