Tips for creating a Moonlander/Ergodox keyboard layout.

by waxbanks

I bought a ZSA Moonlander keyboard this spring — it’s incredible, well worth the large expense. In this post I share some Handy Tips and some Things to Look Out For — mostly applicable to the Ergodox keyboard as well. For a logorrheic personal account of using the keyboard, along with the sales pitch for fence-sitting potential Moonlander/Ergodox buyers, read this article.

Here’s my layout for reference.

The default layout sucks, don’t use it

Everything about ZSA’s default layout is bad; as a result it’s actually a great teaching tool, as you’ve got to think on it a bit to understand why it doesn’t work. Imagine hitting Cmd+S to save a document — what does your hand do? On a normal kb you move your left thumb a tiny bit to Cmd, and hit S on the homerow, no stretch at all, or else you hit right Cmd with your right index/thumb for a little more authority. On the default Moonlander layout, you either splay your left hand across most of the keys, or else you reach with your right pinky…gaining nothing in terms of efficiency or comfort.

You want a homerow modifier for this task — stick Cmd under the J and F keys and watch your most oft-used commands get faster and more natural.

Similarly, what kind of psycho wants Space and Backspace both on the left thumb? Share the work, share the wealth! And who splits the arrow keys across two hands?! Who needs redundant L/R arrow keys? Who wants to be layer-toggling with the right pinky? Why do square brackets need dedicated single-function keys an in inconvenient spot?

And by the way, that thumb-cluster Cmd key is way out of normal reach. You really really don’t want to be chording with the most remote key on the board unless you have no choice. (I use mine for a rare layer toggle.)

Ditch the default layout immediately — honestly, you shouldn’t even use it as the foundation for your own setup. Pick something you like, and tweak that instead.

Spacebar on thumb cluster?

For users w/medium or large hands, the top ‘piano’ key on either thumb cluster is a good spot for the spacebar, though you’ll notice the placement at first. It’s big enough to strike with the middle joint of your thumb, or beside the nail if your posture is better. You surely don’t want to map the spacebar to the weird red 2u keys on the thumb cluster unless you have very big hands — the thumb actually has a long stretch to reach those, so they’re ideally suited for special-case work: Escape, Tab, or an oft-used chord.

However, users with smaller hands could profitably map spacebar to the leftmost key on the right bottom row (or its opposite number on the other half of the kb) — where the up/right arrow are, on the terrible default layout. If your thumb naturally curls under like that, and you don’t mind a tiny spacebar, that’s a compelling, characteristically ‘bring the key to your hands’ heterodox option.

Don’t think about specific keys: think in terms of their functions. Build your keyboard layout around the functions you need to perform — the actual characters your keyboard sends — and make performing those functions comfortable and efficient. That’s the whole game.

Where does Escape go?

I use the right-side red 2u key for Escape, along with the leftmost key on row 3. I don’t type Escape, I slap it — often I’m hitting it because I fucked up, or something else did, and it’s time to cancel or back out. Psychically, that weird red key is a good fit, as is the old-fashioned spot at upper-left of the keyboard.

And to be honest, you probably don’t want that key to be coming into play all the time. It’s a special-purpose key, limited use.

So if you’re a vim user, maybe you want Esc right there to get you quickly back to Normal mode. On the default layout, you could use the Hyper/Meh spots — but you probably don’t want to be hitting Esc w/your right index finger if your next keystroke is the same finger doing hjkl navigation. To me, the spot to the left of A makes sense. On conventional keyboards that’s the irritating, largely useless Caps Lock key. Under no circumstances should you have a dedicated Caps Lock key in a high-traffic part of the keyboard.

Homerow mods

My favourite feature of my keyboard, one of the big ergonomic game-changers: asdfg and ;lkjh double, respectively, as Shift-Ctrl-Opt-Cmd-Shift. Being able to hit Shift (and Cmd!) with zero stretching is such an obvious win that you might wonder why it isn’t simply standard on all keyboards. Do you really need three Shift keys on each side of the kb? Probably not. But why should you make do with one?

Training myself to actually use homerow Shift in normal typing has been difficult, there’s some deep muscle memory holding me back there, but adapting to dual-function keys has been surprisingly easy; homerow Cmd already comes naturally, and has integrated right away into my normal patterns. It seems weird/daunting but you can absolutely implement homerow mods on day 1 and slowly grow into using them. Honestly, if you set them up and don’t use them, you’ll never even notice they’re there…

…because, miraculously, with the default Advanced Settings governing roll-offs and delays and such, I now get zero false positives for homerow mods after just a few weeks. Maybe I’m subconsciously slowing my l-y rolls a little, I doubt it but dunno — yet at this point the dual-function homerow keys Just Work. It’s incredible. (I use the default 200ms delay for dual-function keys.)

Symbol layer

One of the most intriguing notions I’ve seen is a dedicated symbol layer or similar setup, which brings the distant Shift+number symbols like @ and # within easy reach. The idea is never to stretch two rows for anything — this is why you use a numpad layer (see below) — and it’s totally doable if you’re willing to trade, say, Shift+2 (@) for layertoggle+W. If you’re doing heavy data entry or programming and need regular access to those keys, definitely consider a layout that puts number-row symbols under your fingers. It’s potentially a very big change; all the more reason to try it.

That said, I haven’t bothered with this — I work mostly in ordinary prose and haven’t yet found myself needing to hit ‘@’ often enough to justify the additional (short-term) cognitive tax of learning another layer.

Number pad!!!!

I knew I could touch-type on a number pad, but it didn’t occur to me that it’d be useful outside of, er, playing Nethack. Yet for things like typing in phone numbers and doing quick calculations, being able to toggle on a dedicated numpad layer has been an actual time saver, and relaxing to boot. It’ll surely take the edge off of doing my taxes next time — the number row is a pain in the ass to touch-type, not to mention an unnecessary stretch, so the numpad (with jkl mapped to 456, etc.) is a big ergonomic win.

Arrow layer?

This is so hard. But if you master it — and I’m confident you can — it’s one of the biggest timesavers available with a multilayer keyboard.

Here’s the theory: vim-style mode-separation, with arrows on the homerow but hidden in their own dedicated layer. So instead of lifting your hand to get to dedicated arrow keys, you use layers to map them to, say, an inverted T — either WASD for gaming nerds, or IJKL/ESDF for pragmatists. Then surround them, on that navigation layer, with modifiers and other nav keys: Home/End, Opt+Up/Down, PgUp/PgDn, etc. You end up with a clever little cloverleaf formation of navigation commands. The trouble is, selecting text requires some heavy-duty mental remapping. I’m having the devil’s own time with chords like arrowtoggle+Shift+ijkl, though I’ve made good progress just this week.

Of course, it’s been less than two months.

I firmly believe that a dedicated navigation-key layer is exactly right for this keyboard; it’s also necessary, unless you want to cut into row 4 and move the ? key to stick the now-conventional inverted T arrowkey setup at bottom right. (Moving the question mark seems fucked to me. Fucked.) But this is the hardest thing to internalize. Don’t hold it against yourself if adapting to layer-separation takes time.

Typing-only layer

For gaming, this is a must. Just duplicate the base layer, strip out all the fancy dual-function keys, and hide the toggle in a non-base layer, so that you have to toggle a couple of times to get to game mode. I don’t play games on my computer (except Nethack lately) so it hasn’t been a thing for me, but it’s nice to know it’s there.

Dedicated Oryx/firmware keys

For the first month at least, you’ll want a dedicated key for launching Wally (the firmware-flashing program) and need a dedicated key for resetting the kb hardware itself, which would otherwise require a paperclip. If you’re gonna do browser-based Live Training or view a live display of the currently active layer — which doesn’t work in Safari btw — you’ll need a dedicated ‘Oryx’ key. I haven’t used that tool and can never remember where the Oryx key is, but it’s there somewhere. On the ‘Media’ layer I guess?

Oryx is superb, by the way.

Media keys

If you muck about with music/volume controls throughout the day — and who doesn’t? — you’ll need convenient keys for managing media. I’ve got a dedicated Media layer, which also hosts the function keys (e.g. F5) that I never need. I’ve got a dedicated volume-control knob (yeah, an actual rotary controller)(!) on my home machine, but when I’m at work the kb setup is still pretty handy: lower-left key toggles the Media layer, and the keys around it are mapped to systemwide shortcuts for handling Play/Pause and volume control. I’ve also overwritten my ‘spacebar’ with Play/Pause on the Media layer, but I never actually use it. Which is odd — that was one of the ‘definitely for sure’ mappings I didn’t think I’d have to think about. ‘Hit spacebar to play/pause’ seems like a no-brainer.

Which only goes to show that usage must determine design, and if you’ve been working with a conventional keyboard setup for a long time then you certainly have a distorted view of what’s appropriate for that tool. This is true even if you’re one of those Dvorak/Colemak lunatics — conventional keyboard hardware is suboptimal by design, and swapping alphanumerics around can only go so far to fix it.

‘Mouse’ keys

These seem like such a neat idea — who among us doesn’t dream of completely replacing the stupid mouse with keys that’re right there, literally at our literal fingertips? — but they appear to have no utility to ordinary users outside of dimly lit, cobwebby corner cases. For instance, you might be putting together a complex macro that involves not just keystrokes but mouse clicks/movement…I guess? Or setting up an autoclicker for God knows what reason? Out of the box, the mouse-emulation keys strike me as a cute tech demo and nothing more, but some obsessives are getting use out of them. I think they’re not the way to a mouseless future. Good luck.

Hold for Cmd+letter

This strikes me as insane — the chance for bad trouble from false positives is too high — but some people, e.g. user graemeg, use dual-function keys (separate functions when tapped / held) to implement, say, ‘tap Q for Q, hold Q for Cmd+Q.’ Graeme is even using a 180ms delay, below the default, meaning these single-key chords are happening really quickly. I can’t imagine introducing the possibility of accidentally quitting a program because I was slow to pull my finger off Q, or pasting some arbitrary data into a window because I got lost in thought while typing V. But the ergonomic win is clear: as Cerebus the Aardvark would say, ‘One less mouth to feed is one less mouth to feed,‘ where by ‘mouth to feed’ we mean ‘key to reach for.’ Contorting to play key-chords is bad.

And let’s be clear about this: 200ms is a shockingly long time to hold a key. Think on it:

…a person that types 60 WPM (where words are an average of five chars), is typing 360 characters per minute (which includes spaces between words, but excludes punctuation). This is about six characters per seconds which gives us an average inter-character time of 167 ms. However, this is just an average, it will be higher or lower for different character combinations. (source)

Of course, if the only dual-function keys you’re using are the kind you want to deliberately slow down, you even could crank up that delay another 50ms or so. But if you’re a fast typist, this’ll feel unnatural and weird. I dunno what it’d be like to adapt to that rhythm; YMMV.

Tenting

Look, you should be tenting your keyboard (tilting it outward to reduce wrist strain) — it takes some getting used to but is infinitely more comfortable, because more natural. But the Moonlander uses the thumb cluster as a leg, meaning you can’t tent the keyboard without increasing the distance from the cluster to the main board. That’s a bummer.

I find the Moonlander comfortable even when laying flat, but for daily use I actually put my mousepad on a book and use the book to tent the keyboard. And there are 3D-printable solutions available on Thingiverse etc. Once you’ve gotten comfortable with the layout — give it a few weeks or a month — figure out a tenting solution.

Advertisement