kōyō

• Introduction
• Features
• CLI Tool
• Layout
• Project Structure
• Prerequisites
• Development
  • Adding New Features
  • Testing
• Roadmap
• Resources
• Contributing
• License

Introduction

kōyō is a sleek, minimalistic keyboard layout, designed with a 36-key split configuration. Its name is inspired by the harmony and elegance of Japanese aesthetics and the calming feeling of autumn leaves.

In Japanese, kōyō (紅葉) translates to "autumn leaves" and is used to describe the phenomenon of leaves changing color in the autumn season. The word is composed of two kanji characters: kō (紅) meaning "crimson" and yō (葉) meaning "leaf".

Note

Note

The layout in its current form is mainly focused for use in combination with MacOS. It can work on other operating systems, but the layout may not be optimized for them. In the future, I (hopefully) will be working on optimizing the layout for other operating systems.

Features

Core Layout

• QWERTY Base: Familiar layout to ease the transition while maintaining efficiency
• Compact 36-Key Design: Optimized for minimal finger movement and maximum ergonomics
• Strategic Alpha Placement: Bottom row alphas remain easily accessible without blocking home row access

Layer Design

• Extended layer under space bar for frequently used tools
• Dual symbol layers (one per hand) with semantic arrangement
• Dedicated number and function key layers

Thumb Cluster Philosophy

• Reserved for high-frequency, single-action keys (Space, Enter, Tab)
• Dual-purpose modifiers (MEH, HYPER) integrated with common actions
• Avoids sequential/repeated actions to prevent thumb fatigue
  • e.g. Backspace implemented as two-finger combo (I+O) to avoid repeated presses of thumb

Navigation & Tools

• Vim-Inspired Navigation:
  • Arrow keys in familiar HJKL pattern
  • Navigation shortcuts following vim metaphors
    • [ & ] for often used navigation bindings are combos on the base layer
  • Extended layer provides quick access to common movements
• Efficient Symbol Access:
  • Symbols arranged in semantic pairs for intuitive access
  • Common programming symbols placed at strongest fingers
  • Consistent access pattern across both hands

Special Features

• Integrated Shortcuts:
  • Quick access to common GUI commands
    • e.g. Put common GUI commands on left hand split to enable one hand use in combination with the right hand on mouse
  • Tab and window management controls
  • Media and system controls in dedicated layer
• Smart Tap Dancing:
  • Dual-function keys for extended capabilities
  • Context-aware modifier combinations
  • Reduced finger travel for common operations

Quality of Life

• Achordion Integration: Smart handling of hold-tap actions
• Cross-Platform Compatibility: Works seamlessly across operating systems
• Customizable Function Layer: Easy access to F-keys and system functions

Layout

CLI Tool

The koyo CLI tool provides a streamlined interface for managing your keyboard configurations:

Installation

# Clone the repository
git clone https://github.com/nikbrunner/koyo.git

# Run the setup script
./setup.sh

Commands

Setup

# Standard setup
koyo setup

# Dry run to see what would happen
koyo setup --dry-run

Keyboard Operations

# Flash Moonlander keyboard
koyo moonlander flash

# Open Moonlander configuration in Oryx
koyo moonlander oryx

# Flash Corne keyboard
koyo crkbd flash

Update Operations

# Update layout SVG
koyo update svg

# Update QMK firmware
koyo update qmk

Debug Mode

Add the --debug or -d flag to any command for verbose output:

koyo --debug moonlander flash

Project Structure

koyo/
└── assets/            # Project assets
├── qmk/               # QMK configurations
│   ├── moonlander/    # Moonlander specific files
│   └── crkbd/         # Corne specific files
├── setup.sh           # Setup script
├── utils.sh           # Utility functions
├── help.sh            # Help documentation
├── update_svg.sh      # SVG update script
├── config.yml         # Configuration file
├── koyo               # koyo command

Prerequisites

• qmk firmware
• keymap-drawer for SVG generation
• yq for YAML processing
• zsh shell
• git

Development

Adding New Features

1. Create a new branch for your feature
2. Implement your changes
3. Update documentation if necessary
4. Submit a pull request

Testing

Before submitting changes:

1. Test all keyboard configurations
2. Verify CLI commands work as expected
3. Run setup script in dry-run mode

Roadmap

• koyo moonlander flash (Flashes the Moonlander Keybaord)
• koyo setup (Sets up Prerequisites)
• DRY up scripts
• koyo moonlander oryx (Opens up Oryx Configurator Page)
• koyo corne flash (Flashes the Corne Keyboard)
• koyo update svg (Updates the SVG files)
• koyo update qmk (Pulls latest Version of QMK firmware)
• Ensure keymap-drawer is installed
• Align layouts & purge unused or redundant stuff
• Document differences between kōyō for CRKBD and Moonlander
• Add note about current optimizations focused on MacOS
• Optimize Home Row Mods for MacOS
• Make Layout SVG OS agnostic
• Script to automatically update SVG
• SSOT for keymap. Script to generate keymap.c files from SSOT.

Resources

• urob: timeless home row mods
• infused-kim
• miryoku_zmk
• ZMK Docs
• Designing a Symbol Layer
• A guide to home row mods
• Callum Mods
• Jonas Hietala: I designed my own keyboard layout. Was it worth it?

Contributing

Contributions are welcome! Please read through the existing issues and pull requests before creating new ones.

License

This project is licensed under the MIT License - see the LICENSE file for details.