Mechanical Keyboard PCB Design: Custom Board Layout Guide

I’ve been designing keyboard PCBs for over six years now, and I still remember the frustration of my first project. Bad traces, ghosting issues, wrong footprints — you name it, I messed it up. This guide exists because I wish someone had handed me a comprehensive resource back then instead of making me piece together scattered forum posts and outdated tutorials.

Whether you’re building your first macro pad or designing a full-size mechanical keyboard PCB, this guide walks through the entire keyboard PCB design process from schematic creation to manufacturing files.

Why Design Your Own Keyboard PCB?

Off-the-shelf keyboards work fine for most people. But if you’ve ever wanted a specific layout, a particular feature combination, or simply wanted to understand what makes your keyboard tick, designing your own PCB is the path forward.

Custom keyboard PCB design gives you control over switch orientation (north or south facing LEDs), hot-swap socket placement, underglow LED positioning, and layout flexibility that commercial boards simply cannot offer. Plus, there’s something deeply satisfying about typing on a board you designed from scratch.

The custom keyboard community has grown exponentially over the past few years, and PCB manufacturing has become incredibly accessible. Services like JLCPCB and PCBWay will produce five boards for under $10, making experimentation affordable.

Essential Components for Mechanical Keyboard PCB Design

Before opening any design software, you need to understand what goes onto a keyboard PCB. Every component serves a specific purpose in the signal chain from key press to computer input.

Core Components Overview

Component	Purpose	Common Part Numbers
Microcontroller	Processes key matrix, handles USB communication	ATmega32U4, RP2040, STM32F303
Diodes	Prevent ghosting, enable NKRO	1N4148, 1N4148W (SMD)
Crystal Oscillator	Provides clock signal for MCU	16MHz (for ATmega32U4)
USB Connector	Data and power connection	USB-C, USB Mini-B
Decoupling Capacitors	Stabilize power supply	0.1µF, 4.7µF
ESD Protection	Protects against static discharge	PRTR5V0U2X
Reset Switch	Enters bootloader mode	Tactile switch

Switch Footprints and Compatibility

Your PCB needs the correct footprints for your chosen switches. Cherry MX-style switches come in two mounting variants: plate mount (3-pin) and PCB mount (5-pin). The 5-pin variant adds two plastic alignment pins that improve switch stability on plateless builds.

Design your footprints to accommodate both variants. This means including holes for the two extra plastic pins even if you plan to use plate-mounted switches. Future flexibility saves redesign time.

For hot-swap builds, Kailh hot-swap sockets require specific pad dimensions and placement. The socket footprint differs significantly from standard through-hole switch footprints, so verify your library contains the correct version before starting layout.

Understanding the Keyboard Matrix

The matrix is the foundation of any mechanical keyboard PCB design. Without understanding how it works, you’ll struggle to debug problems or optimize your layout.

How a Keyboard Matrix Works

A full-size keyboard has 104 keys. Connecting each key directly to a microcontroller would require 104 GPIO pins — more than any common MCU provides. The matrix solves this by organizing switches into rows and columns.

In a matrix arrangement, the microcontroller scans one column at a time while reading all rows simultaneously. For a 10-column, 10-row matrix, you can detect 100 keys using only 20 pins. The math works out beautifully: pins required equals rows plus columns, not rows times columns.

The Ghosting Problem and Diode Solution

Ghosting occurs when pressing three keys in an L-shaped pattern causes the fourth corner key to register falsely. This happens because current can flow backward through the mechanical switches, creating phantom key presses.

The solution is placing a diode in series with each switch. Diodes conduct current in only one direction, blocking the reverse current path that causes ghosting. This enables N-key rollover (NKRO), meaning every key press registers correctly regardless of how many keys you press simultaneously.

Matrix Configuration	Pins Required	Keys Supported
4×4	8	16
6×6	12	36
6×14	20	84
6×17	23	102

Always orient your diodes consistently — cathode (marked end) toward the row or column, whichever you choose. Just maintain consistency throughout the entire matrix.

Selecting a Microcontroller

The microcontroller choice affects your firmware options, available GPIO pins, and USB implementation complexity. Two families dominate the custom keyboard space: AVR-based ATmega32U4 and ARM-based controllers like the RP2040.

ATmega32U4

The ATmega32U4 has been the workhorse of custom keyboards for over a decade. It features native USB support, 26 GPIO pins, and excellent QMK firmware compatibility. The Pro Micro development board packages this chip in a convenient form factor that’s become a standard in split keyboard designs.

The downside? Stock availability became problematic during recent chip shortages, and its 32KB flash memory limits feature combinations. Enable too many QMK features, and you’ll hit the memory ceiling.

RP2040 (Raspberry Pi Pico)

The RP2040 represents the new generation of keyboard controllers. With 264KB of RAM, 2MB of flash (or more, depending on the board), and 26 GPIO pins, it handles complex firmware without breaking a sweat. QMK added official support in 2022, and the ecosystem has matured significantly.

The RP2040 requires external flash memory since it lacks internal storage, but most development boards include this. The Raspberry Pi Pico, KB2040, and various Pro Micro-compatible RP2040 boards make integration straightforward.

Feature	ATmega32U4	RP2040
Architecture	AVR 8-bit	ARM Dual-Core 32-bit
Clock Speed	16 MHz	133 MHz
Flash Memory	32 KB	2 MB+ (external)
RAM	2.5 KB	264 KB
GPIO Pins	26	26
USB	Native	Native
Price	$3-8	$4-6
QMK Support	Excellent	Good (improving)

Setting Up Your Design Environment

KiCad is the standard choice for keyboard PCB design. It’s free, open-source, cross-platform, and has extensive community support. Version 7 and later offer significant improvements in usability over earlier versions.

Installing KiCad Libraries for Keyboards

Stock KiCad libraries don’t include keyboard-specific components. You’ll need third-party libraries for switch footprints, stabilizers, and hot-swap sockets.

The best keyboard-specific libraries include:

marbastlib — Comprehensive library with MX switches, Kailh hot-swap sockets, Choc low-profile switches, and WS2812B LED footprints. Installs directly through KiCad’s Plugin and Content Manager.

keyswitch-kicad-library — Well-maintained library covering Cherry MX, Alps, Kailh Choc, and hybrid footprints. Includes stabilizer footprints in standard sizes.

ai03 Keyboard Parts — Popular library with MX-Alps hybrid footprints and various controller footprints.

Install libraries as Git submodules if you’re using version control. This keeps your project self-contained and makes sharing easier.

Step-by-Step Keyboard PCB Design Process

Let’s walk through the actual keyboard PCB design workflow. I’ll assume you’re building a 60% layout, but the process scales to any size.

Step 1: Plan Your Layout

Start with Keyboard Layout Editor (keyboard-layout-editor.com). This web tool lets you visually arrange keys and export the layout as JSON. That JSON file can feed into various automation tools that generate KiCad switch placements.

For your first board, stick with a standard layout. Custom layouts add complexity to keycap compatibility and plate design.

Step 2: Create the Schematic

The schematic captures electrical connections without worrying about physical placement. Start with the microcontroller symbol and add:

1. Power section: USB connector, decoupling capacitors, voltage regulation if needed
2. Crystal circuit: Crystal oscillator with load capacitors (for ATmega32U4)
3. Reset circuit: Reset switch with pull-up resistor
4. Key matrix: All switches and diodes organized by rows and columns
5. Optional features: RGB LEDs, OLED display, rotary encoder

Label your matrix rows and columns clearly. Use hierarchical sheets if your schematic becomes unwieldy — a separate sheet for the matrix keeps things organized.

Step 3: Assign Footprints

KiCad separates schematic symbols from physical footprints. After completing your schematic, assign footprints to each component.

For switches, decide on your mounting style:

• MX PCB mount: SW_Cherry_MX_PCB (5-pin holes)
• MX Plate mount: SW_Cherry_MX_Plate (3-pin holes)
• Kailh Hot-swap: Use the appropriate hot-swap socket footprint

Diode footprints depend on your placement strategy. SMD diodes (SOD-123 or SOD-323) fit under switches nicely, while through-hole 1N4148 diodes work better for hand-wired sections.

Step 4: PCB Layout

Now the fun begins. Import your netlist into the PCB editor and start placing components.

Switch placement follows the standard 19.05mm (0.75 inch) spacing for MX-style switches. Set your grid to 9.525mm (0.375 inch) for easy half-unit adjustments. The keyboard-layouter plugin or kicad-kbplacer can automate switch placement from KLE JSON files.

Microcontroller placement matters for USB connector positioning and trace length. Place it near the USB connector location, typically top-center for most layouts.

Diode placement under switches works well for SMD diodes. Orient them consistently and keep them close to their associated switch.

Step 5: Routing Traces

Route power traces first, then matrix connections. Column traces typically run vertically, row traces horizontally. Use the opposite layer for crossing connections.

Key routing guidelines:

• Power traces: 0.4mm minimum, wider for high-current paths
• Signal traces: 0.25mm works fine for matrix connections
• Crystal traces: Keep short and equal length; route directly to MCU pins
• USB data lines: Keep short, roughly equal length, avoid running parallel to noisy signals

A ground plane on the bottom layer simplifies routing and improves EMI performance. Pour copper over the entire bottom layer, connected to GND.

Step 6: Design Rule Check

Run DRC (Design Rule Check) before generating manufacturing files. Fix all errors — most manufacturers reject files with DRC violations.

Common errors include:

• Clearance violations between traces
• Unconnected nets (missing connections)
• Silkscreen over pads
• Drill sizes outside manufacturing tolerances

Step 7: Generate Manufacturing Files

Export Gerber files and drill files for your manufacturer. Most services accept a ZIP containing:

• Copper layers (F.Cu, B.Cu)
• Solder mask layers (F.Mask, B.Mask)
• Silkscreen layers (F.SilkS, B.SilkS)
• Board outline (Edge.Cuts)
• Drill file (.drl)

JLCPCB’s KiCad plugin automates this process and uploads directly to their ordering system.

Read more different PCB Design services:

Hot-Swap Socket Design Considerations

Hot-swap sockets let you change switches without soldering. The two common options are Kailh hot-swap sockets (for MX-style switches) and Mill-Max sockets (universal, requires more effort).

Kailh Hot-Swap Socket Layout

Kailh sockets solder to the PCB surface and grip switch pins through friction. The footprint places two large pads where the switch pins insert, with smaller pads for the socket’s solder tabs.

Important design notes:

• Socket pads require larger clearances than standard through-hole pads
• The socket body extends beyond the switch footprint — account for this in tight layouts
• Switches feel slightly less stable than soldered connections; a plate helps

PCB Thickness for Hot-Swap

Standard 1.6mm PCB thickness works for hot-swap builds. Thinner boards (1.2mm) are possible but may flex more with heavy switches.

Manufacturing Your Keyboard PCB

Several manufacturers specialize in prototype quantities perfect for keyboard projects.

Manufacturer	Minimum Order	Lead Time	Strengths
JLCPCB	5 pcs	3-5 days	Cheap, fast, good quality
PCBWay	5 pcs	3-7 days	Good customer service, flex PCB
OSH Park	3 pcs	~12 days	US-based, excellent quality
AllPCB	5 pcs	3-5 days	Competitive pricing

For your first board, order standard specs: 1.6mm thickness, HASL finish, green solder mask. Fancy options add cost without functional benefit for prototypes.

PCB Specifications Explained

Layer count: Two-layer boards handle most keyboard designs. Four-layer boards add cost but simplify routing for complex layouts with integrated RGB or wireless modules.

Surface finish: HASL (Hot Air Solder Leveling) is cheapest and works fine for hand soldering. ENIG (Electroless Nickel Immersion Gold) costs more but provides flatter pads for fine-pitch components and better corrosion resistance.

Solder mask color: Purely aesthetic for functionality. Black and matte finishes hide traces better if aesthetics matter for your build. White shows fingerprints easily.

PCB thickness: 1.6mm is standard. Use 1.2mm for low-profile builds or where flex is acceptable. Thicker 2.0mm boards add rigidity for plateless designs.

Firmware: Bringing Your Keyboard to Life

A PCB without firmware is just a fancy paperweight. QMK (Quantum Mechanical Keyboard) firmware dominates the custom keyboard space, with VIA providing a graphical configuration layer on top.

QMK Configuration

QMK configuration requires defining your matrix in info.json:

json

{    “keyboard_name”: “my_keyboard”,    “matrix_pins”: {        “cols”: [“B0”, “B1”, “B2”, “B3”],        “rows”: [“D0”, “D1”, “D2”, “D3”]    }}

Pin assignments must match your schematic. Double-check this mapping — wrong pins mean non-functional keys.

VIA Support

VIA allows real-time keymap editing without recompiling firmware. Enable VIA support in your QMK configuration, and you can remap keys through a graphical interface.

Common Design Mistakes to Avoid

After reviewing dozens of first-time keyboard PCB designs, these mistakes appear repeatedly:

Wrong switch orientation: Decide LED orientation (north or south facing) before layout. Cherry-profile keycaps can interfere with north-facing switches.

Insufficient clearance around USB: The USB connector needs space for the plug. Check your case design compatibility.

Missing pull-up/pull-down resistors: The reset pin needs a pull-up resistor. Missing this causes erratic reset behavior.

Crystal placement too far from MCU: Long traces to the crystal cause timing problems. Keep traces under 10mm.

Forgetting mounting holes: Your PCB needs to attach to something. Add M2 or M3 mounting holes in your case’s mounting positions.

Useful Resources and Downloads

Design Software

• KiCad: kicad.org — Free, open-source PCB design suite
• Keyboard Layout Editor: keyboard-layout-editor.com — Visual layout planning tool
• QMK Configurator: config.qmk.fm — Online firmware configuration

KiCad Libraries

• marbastlib: github.com/ebastler/marbastlib
• keyswitch-kicad-library: github.com/kiswitch/keyswitch-kicad-library
• ai03 Keyboard Parts: github.com/ai03-2725/MX_Alps_Hybrid

Open Source Keyboard PCB Projects

• GH60: github.com/komar007/gh60 — Classic open-source 60% PCB
• CO60: github.com/jmdaly/CO60 — Modern 60% with STM32 MCU
• Keebio Split Keyboards: github.com/keebio — Various split keyboard designs

PCB Generators and Automation

• klepcbgen: github.com/jeroen94704/klepcbgen — Generates KiCad projects from KLE layouts
• kicad-kbplacer: github.com/adamws/kicad-kbplacer — Switch placement automation
• Keyboard Layouter Plugin: KiCad plugin for switch placement

Firmware Resources

• QMK Firmware: qmk.fm — Main firmware repository and documentation
• VIA: caniusevia.com — Real-time keyboard configuration
• QMK Toolbox: github.com/qmk/qmk_toolbox — Firmware flashing utility

Community Forums

• Deskthority: deskthority.net — Technical keyboard discussions
• Geekhack: geekhack.org — DIY keyboard community
• r/MechanicalKeyboards: reddit.com/r/MechanicalKeyboards — Large enthusiast community
• Keyboard Atelier Discord: Designer-focused community with active help channels

Frequently Asked Questions

What software should I use for keyboard PCB design?

KiCad is the recommended choice for keyboard PCB design. It’s free, open-source, and has excellent community support with keyboard-specific libraries readily available. Professional alternatives like Altium or OrCAD work too, but their cost isn’t justified for hobbyist projects. EasyEDA is another free option with direct JLCPCB integration if you prefer browser-based tools.

How much does it cost to manufacture a custom keyboard PCB?

A single mechanical keyboard PCB prototype typically costs $2-15 for the PCB itself, plus shipping. JLCPCB charges about $2 for five 60% keyboard PCBs with standard specifications. Add $15-25 for economy shipping. Components (switches, diodes, controller) add another $30-100 depending on your choices. Your first complete build typically runs $80-150 total.

Do I need hot-swap sockets in my keyboard PCB design?

Hot-swap sockets add convenience but aren’t required. They let you change switches without soldering, which is great for testing different switches or if you’re not confident in your soldering skills. The tradeoff is slightly reduced switch stability and higher per-unit cost. For your first PCB, I’d recommend designing for hot-swap capability even if you plan to solder — it gives you flexibility.

What’s the best microcontroller for a beginner keyboard PCB?

The ATmega32U4 (via a Pro Micro board) remains the easiest starting point due to extensive documentation and proven QMK support. The RP2040 is increasingly popular and more powerful, but some advanced features are still being refined in QMK. For a first project, either works well. If you’re designing an integrated controller (not using a development board), the RP2040 is actually simpler since it requires fewer external components.

How do I prevent ghosting in my keyboard matrix design?

Place a diode (1N4148 or equivalent) in series with each switch in your matrix. The diode blocks reverse current flow that causes ghosting. Orient all diodes the same direction — cathode toward the row line works as standard convention. This simple addition enables N-key rollover, meaning all simultaneous key presses register correctly. Without diodes, most matrices are limited to 2-key rollover to avoid ghost presses.

Testing Your Completed PCB

Once your PCB arrives from manufacturing, resist the urge to solder everything immediately. A systematic testing approach saves hours of frustrating debugging later.

Visual Inspection

Examine the board for manufacturing defects: bridged traces, missing copper, misaligned silkscreen, or damaged pads. Hold the board up to light and check for any copper traces that look thinner than designed or have breaks.

Continuity Testing

Before populating any components, use a multimeter in continuity mode to verify critical connections. Check that VCC and GND aren’t shorted — a short here will damage your microcontroller. Verify USB data lines aren’t bridged together. Test that matrix row and column traces are isolated from each other since crossed matrix lines cause phantom key presses.

Progressive Assembly

Solder the microcontroller and USB connector first. Flash basic firmware and confirm the board enumerates as a USB device before adding switches. This isolates power and USB issues from matrix problems.

Add switches one row at a time, testing each row before proceeding. If a problem appears, you’ve narrowed it to the most recently added components. This methodical approach turns a frustrating debugging session into a manageable systematic process.

Wrapping Up

Designing your first mechanical keyboard PCB takes time and patience. Expect your first board to have issues — that’s normal. Order extra PCBs (they’re cheap) and treat problems as learning opportunities.

Start simple. A macro pad or numpad teaches the same principles as a full keyboard with less complexity. Once you’ve built confidence with a smaller project, tackling a full keyboard PCB design becomes much less intimidating.

The custom keyboard community is incredibly helpful. When you get stuck, forums and Discord servers have experienced designers willing to review schematics and offer advice. Don’t hesitate to ask for help.

Now close this tab and open KiCad. Your keyboard isn’t going to design itself.