🎨 Kimi Themes

A curated collection of 228 high-quality, meticulously differentiated themes for the Kimi Code CLI. Featuring optimized palettes for both dark and light modes, strict schema adherence, and zero packaging bloat.

---

🌟 Features

• 228 Curated Themes: 122 Dark and 106 Light themes covering classic editor ports (Dracula, Nord, Tokyo Night, Catppuccin, Monokai, Gruvbox), custom inspirations (miku-cyber-blue), modern synthetics, and organic nature tones.
• Meaningfully Differentiated: Every theme is validated for visual distinctness using CIELAB perceptual color space analysis. No near-duplicate clones.
• Strict Schema & Standards: Consistent token structure across every file for seamless rendering in Kimi Code CLI.
• Backward Compatibility: Includes legacy migration mapping (migrations.json) for seamless fallback of consolidated theme IDs.
• Automated CI Validation: Continuous integration testing ensures 100% valid JSON, unique IDs, unique display names, and WCAG-friendly contrast.
• Clean Packaging: Fully sanitized against OS packaging artifacts (.DS_Store, __MACOSX, and ._* AppleDouble files).

---

🚀 Getting Started

Installation

To install themes for Kimi Code CLI:

1. Create the local themes directory if it doesn't already exist:

   mkdir -p ~/.kimi-code/themes

2. Copy desired theme file(s) into that directory (or $KIMI_CODE_HOME/themes/ when the KIMI_CODE_HOME environment variable is set):

   # Install a specific theme
   cp themes/miku-cyber-blue.json ~/.kimi-code/themes/
   
   # Or install all 228 themes
   cp themes/*.json ~/.kimi-code/themes/

3. Open Kimi Code CLI and activate the theme using the /theme command. Installed custom themes will appear as Custom: <filename>.

Permanent Configuration

You can set your default theme permanently in tui.toml:

# ~/.kimi-code/tui.toml
theme = "miku-cyber-blue"

---

🎨 Theme Catalog Overview

The repository hosts 228 theme definitions divided into dark and light base modes:

Category	Count	Notable Themes
Dark Themes	122	miku-cyber-blue, dracula, dracula-classic, tokyo-night, nord, nord-polar-night, catppuccin-mocha, gruvbox-dark, gruvbox-dark-hard, one-dark-pro, material-theme-ocean, everforest-dark, synthwave-84, neon-vortex, cobalt2
Light Themes	106	catppuccin-latte, github-light, solarized-dark (light base variants), paper-ink, sakura-light, khaki-field, ocean-breeze, emerald-city, ivory-tower, high-contrast-light

---

🔄 Legacy Migrations

Following catalog deduplication and consolidation, 13 near-duplicate themes were retired in favor of canonical variants. If your configuration references any of these legacy theme IDs, they map to the following canonical themes (defined in migrations.json):

Legacy Theme ID	Canonical Replacement
mustard-seed	khaki-field
sand-dune	khaki-field
sapphire-sky	ocean-breeze
sky-high	ocean-breeze
indigo-night	deep-sea
urban-decay	obsidian-night
slate-mountain	obsidian-night
teal-depths	forest-mist
mossy-stone	olive-branch
onyx-stone	charcoal-gray
berry-blast	crimson-tide
ruby-red	crimson-tide
lime-zest	emerald-city

---

🛠 Creating Custom Themes

You do not need to write theme JSON files by hand. Use the built-in /custom-theme workflow in Kimi Code CLI:

/custom-theme Create a warm dark theme with amber accents.
/custom-theme Make a light theme based on Solarized with high-contrast errors.
/custom-theme Tweak my ember theme so diffs have higher contrast.

To manually create a theme, place a .json file in themes/ named <theme-id>.json.

---

📐 Theme Schema

All theme files follow the official Kimi Code CLI schema specification:

{
  "name": "theme-id",
  "displayName": "Theme Name",
  "base": "dark | light",
  "colors": {
    "primary": "#RRGGBB",
    "accent": "#RRGGBB",
    "text": "#RRGGBB",
    "textStrong": "#RRGGBB",
    "textDim": "#RRGGBB",
    "textMuted": "#RRGGBB",
    "border": "#RRGGBB",
    "borderFocus": "#RRGGBB",
    "success": "#RRGGBB",
    "warning": "#RRGGBB",
    "error": "#RRGGBB",
    "diffAdded": "#RRGGBB",
    "diffRemoved": "#RRGGBB",
    "diffAddedStrong": "#RRGGBB",
    "diffRemovedStrong": "#RRGGBB",
    "diffGutter": "#RRGGBB",
    "diffMeta": "#RRGGBB",
    "roleUser": "#RRGGBB"
  }
}

Inheritance & Fallbacks

• base: Determines which built-in palette tokens inherit from if omitted (dark or light).
• Partial Themes: Any omitted token will automatically fall back to its respective value in the base palette.

---

🛠 Validation & Packaging

Run Local Validation

To validate all themes against the schema, ensure unique IDs / display names, and check perceptual similarity:

python scripts/validate_themes.py

Build Deterministic Distribution Archive

To package all themes into a clean zip distribution without OS metadata:

./scripts/archive.sh

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines and Code of Conduct before submitting pull requests.

---

📄 License

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