🎨 KeyCraft

A beautiful, interactive custom keycap designer for mechanical keyboards

Design, customize, and visualize your dream keyboard layout with precision and style.

---

📖 About

KeyCraft is a modern web application that empowers keyboard enthusiasts to design and customize their mechanical keyboard layouts. Whether you're planning a custom build, visualizing keycap sets, or experimenting with different layouts, KeyCraft provides an intuitive, feature-rich interface to bring your keyboard dreams to life.

✨ Key Features

• 🎹 Multiple Layout Support - Design keyboards from compact 40% to full-size 100% layouts
• 🌍 International Standards - Support for both ANSI and ISO keyboard standards
• 🎨 Visual Customization - Customize key colors, legend colors, and keycap profiles
• 🖼️ Image Support - Add custom images to individual keys
• 📐 Precise Positioning - Fine-tune label positioning with offset controls
• 🔄 Undo/Redo - Full history management with keyboard shortcuts
• 🌓 Dark Mode - Beautiful dark and light themes with smooth transitions
• 💾 Export Functionality - Save your designs as JSON for later use
• 🖱️ Interactive Canvas - Click, drag, and select multiple keys with ease
• 📱 Responsive Design - Clean, modern UI with collapsible sidebars

---

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher recommended)
• pnpm (package manager)

Installation

1. Clone the repository

   git clone <repository-url>
   cd KeyCraft

2. Install dependencies

   pnpm install

3. Start the development server

   pnpm dev

4. Open your browser Navigate to http://localhost:5173 (or the port shown in your terminal)

Build for Production

pnpm build

The production build will be in the dist directory.

Preview Production Build

pnpm preview

---

🎮 Usage

Basic Workflow

1. Select a Layout - Choose from the left sidebar (40%, 50%, 60%, 65%, 75%, 80%/TKL, 96%, 100%, 1800-Compact)
2. Choose a Standard - Toggle between ANSI and ISO layouts
3. Select Keys - Click on keys in the canvas to select them (hold Shift for multiple selection)
4. Customize - Use the right sidebar to adjust:
   • Key color
   • Legend color
   • Keycap shape (cylindrical, flat, spherical)
   • Label text and sub-labels
   • Label positioning
   • Custom images
5. Export - Click "Export JSON" in the header to save your design

Keyboard Shortcuts

• Ctrl/Cmd + Z - Undo
• Ctrl/Cmd + Shift + Z - Redo
• Ctrl/Cmd + Y - Redo (alternative)

Features Overview

• Left Sidebar: Layout selection and keyboard standard toggle
• Canvas: Interactive keyboard visualization with drag-to-select
• Right Sidebar: Key customization controls (visible when keys are selected)
• Header: Theme toggle, undo/redo, and export functionality

---

🛠️ Tech Stack

• React 19.2 - Modern UI library
• TypeScript 5.8 - Type-safe development
• Vite 6.2 - Fast build tool and dev server
• Tailwind CSS 4.1 - Utility-first CSS framework
• Lucide React - Beautiful icon library

---

📁 Project Structure

KeyCraft/
├── src/
│   ├── components/          # React components
│   │   ├── AIGenerator.tsx
│   │   ├── Controls.tsx     # Key customization controls
│   │   ├── Key.tsx          # Individual key component
│   │   ├── KeyboardCanvas.tsx # Main canvas component
│   │   ├── SidebarLeft.tsx  # Layout selection sidebar
│   │   └── SidebarRight.tsx # Properties sidebar
│   ├── constants.ts         # Layout definitions and generators
│   ├── types.ts             # TypeScript type definitions
│   ├── App.tsx              # Main application component
│   ├── index.tsx            # Application entry point
│   └── index.css            # Global styles
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

---

🎨 Supported Layouts

• 40% - Ultra-compact layout
• 50% - Preonic-style layout
• 60% - Popular compact layout
• 65% - 60% with arrow keys
• 75% - Compact TKL
• 80% / TKL - Tenkeyless (no numpad)
• 96% - Compact full-size
• 100% - Full-size keyboard
• 1800-Compact - Compact full-size variant

---

📝 License

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

---

🤝 Contributing

Contributions are welcome! We love to see the community getting involved. Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Contribution Guidelines

• Follow the existing code style and conventions
• Add comments for complex logic
• Update documentation as needed
• Test your changes thoroughly
• Be respectful and constructive in discussions

We appreciate all contributions, whether they're bug fixes, new features, documentation improvements, or suggestions!

---

Made with ❤️ for the mechanical keyboard community