Xcode Theme Generator

A conversational CLI tool that generates custom Xcode color themes. Provide a starting color, choose your preferences, and get a complete .xccolortheme file with perceptually uniform colors and proper contrast ratios.

Features

• Conversational flow — Interactive prompts guide you through theme creation
• OKLCH color engine — Perceptually uniform color space for harmonious palettes
• WCAG contrast enforcement — Minimum 4.5:1 contrast ratio for all syntax colors
• Live preview — See your theme rendered with real Swift code in the terminal
• Interactive adjustment — Tweak colors in real-time before finalizing
• Auto-install — Automatically installs to Xcode's themes directory

Installation

Mint (Recommended)

mint install mkuliszkiewicz/xcode-theme-generator

Homebrew

# Coming soon

From Source

git clone https://github.com/mkuliszkiewicz/xcode-theme-generator.git
cd xcode-theme-generator
make install

Download Binary

Grab the latest release from GitHub Releases:

# Download and extract
curl -L https://github.com/mkuliszkiewicz/xcode-theme-generator/releases/latest/download/xcode-theme-generator-macos-arm64.tar.gz | tar xz

# Move to PATH
sudo mv xcode-theme-generator /usr/local/bin/

Usage

Interactive Mode (Recommended)

xcode-theme-generator

This launches the wizard that will:

1. Ask for your starting color (hex like #6366f1 or name like indigo)
2. Ask for dark or light theme
3. Ask for a vibe (vibrant, muted, warm, cool)
4. Open interactive adjustment mode for fine-tuning
5. Generate and optionally install the theme

Quick Mode

Skip the interactive color adjuster:

xcode-theme-generator --quick

Non-Interactive Mode

Generate a theme with command-line arguments:

xcode-theme-generator generate \
  --color "#6366f1" \
  --dark \
  --vibe vibrant \
  --name "My Theme"

Options:

• -c, --color — Starting color (hex or name)
• --dark / --light — Theme mode
• -v, --vibe — Color vibe: vibrant, muted, warm, cool
• -n, --name — Theme name
• --no-install — Save to current directory instead of Xcode
• --quick — Skip interactive adjustment mode

List Existing Themes

xcode-theme-generator list

Interactive Adjustment Mode

After initial selections, you can fine-tune colors in real-time:

Key	Action
h / l or ← / →	Rotate hue
j / k or ↓ / ↑	Adjust chroma (saturation)
v	Cycle through vibes
d	Toggle dark/light mode
1-9	Preset colors (red, orange, yellow, green, cyan, blue, indigo, purple, pink)
Enter / q	Confirm and continue

The preview updates instantly as you adjust.

Available Color Names

red, orange, amber, yellow, lime, green, emerald, teal, cyan,
sky, blue, indigo, violet, purple, fuchsia, pink, rose,
slate, gray, zinc, neutral, stone

How It Works

OKLCH Color Space

Unlike HSL, OKLCH is perceptually uniform — a 30° hue shift looks equally different regardless of the starting color. This enables reliable palette generation:

• L (Lightness): 0–1
• C (Chroma): 0–0.4 (saturation)
• H (Hue): 0–360°

Palette Generation

From your base color, the generator creates a complete palette:

Role	Strategy
Keywords	Base hue, high saturation
Types	+40° hue rotation
Functions	-30° hue rotation
Strings	+150° (complementary warm)
Numbers	+100° hue rotation
Constants	+60° hue rotation
Variables	Near-neutral, foreground-like
Comments	Desaturated, reduced lightness

Contrast Enforcement

All colors are automatically adjusted to meet WCAG AA standards (4.5:1 minimum contrast against the background).

Project Structure

Sources/XcodeThemeGenerator/
├── Commands/
│   └── GenerateCommand.swift     # CLI entry point
├── Color/
│   ├── OKLCHColor.swift          # OKLCH implementation
│   ├── ColorPalette.swift        # Palette generation
│   └── ContrastChecker.swift     # WCAG validation
├── Conversation/
│   ├── Prompter.swift            # Terminal UI
│   ├── ThemeWizard.swift         # Flow orchestration
│   └── ColorAdjuster.swift       # Interactive adjustment
├── Theme/
│   ├── XcodeTheme.swift          # Theme model + plist
│   ├── ThemeGenerator.swift      # Applies rules to palette
│   └── ThemeInstaller.swift      # Installs to Xcode
├── Preview/
│   └── TerminalPreview.swift     # ANSI code preview
└── Rules/
    └── ThemeRules.swift          # Dark/light rules

Makefile Targets

make build         # Build debug version
make release       # Build optimized release
make run           # Run interactive wizard
make run-quick     # Run without color adjuster
make list          # List existing themes
make install       # Install to /usr/local/bin
make uninstall     # Remove from /usr/local/bin
make clean         # Remove build artifacts
make help          # Show all targets

Requirements

• macOS 13.0+
• Swift 5.9+
• Xcode (for using the generated themes)

Theme Location

Generated themes are installed to:

~/Library/Developer/Xcode/UserData/FontAndColorThemes/

After installation, open Xcode → Settings → Themes to select your new theme.

License

MIT