/create-theme

name: create-theme
description: >
  Create custom color themes for Sidecar, including base theme selection,
  color overrides, gradient borders, tab styles, per-project themes,
  community themes, and programmatic theme registration. Use when creating
  or modifying themes, adjusting UI appearance, or debugging color/style
  issues. See references/palette-reference.md for the full color palette
  with all keys and per-theme values.

Create Theme

Configuration Location

Themes are configured in `~/.config/sidecar/config.json`:

{
  "ui": {
    "showFooter": true,
    "showClock": true,
    "nerdFontsEnabled": false,
    "theme": {
      "name": "default",
      "overrides": {
        "primary": "#FF5500",
        "success": "#00FF00"
      }
    }
  }
}

Available Base Themes

• **default** - Dark theme with purple/blue accents
• **dracula** - Dracula-inspired dark theme with vibrant colors
• **molokai** - Vibrant, high-contrast dark theme
• **nord** - Arctic, north-bluish color palette
• **solarized-dark** - Precision color scheme for reduced blue light
• **tokyo-night** - Clean dark theme celebrating Downtown Tokyo

Creating a Custom Theme

Method 1: Override Specific Colors

Start from a base theme and override specific colors:

{
  "ui": {
    "theme": {
      "name": "default",
      "overrides": {
        "primary": "#E91E63",
        "success": "#4CAF50",
        "error": "#F44336",
        "syntaxTheme": "github"
      }
    }
  }
}

Method 2: Full Theme Override

Override all colors for complete control. See `references/palette-reference.md` for every available color key and their default values across themes.

Method 3: Custom Gradient Borders

Panel borders support angled gradients (default 30 degrees) flowing diagonally:

{
  "ui": {
    "theme": {
      "overrides": {
        "gradientBorderActive": ["#FF0000", "#FF7F00", "#FFFF00", "#00FF00", "#0000FF", "#8B00FF"],
        "gradientBorderAngle": 45
      }
    }
  }
}

Gradients support 2+ color stops. If not specified, solid `borderActive`/`borderNormal` colors are fallback.

Tab Styles

Configure with `tabStyle` and `tabColors` in overrides:

**Tab Styles:**

• `gradient` - Colors flow continuously across all tabs (per-character interpolation)
• `per-tab` - Each tab gets a distinct solid color from array (cycles)
• `solid` - Uses theme primary/tertiary colors
• `minimal` - No background, active tab uses underline

**Built-in Presets** (use as `tabStyle` value):

• `rainbow` - Red -> Green -> Blue -> Purple (gradient)
• `sunset` - Orange -> Peach -> Pink (gradient)
• `ocean` - Deep Blue -> Cyan -> Light Blue (gradient)
• `aurora` - Purple -> Dark Purple -> Teal (gradient)
• `neon` - Magenta -> Cyan -> Green (gradient)
• `fire` - Red-Orange -> Orange -> Gold (gradient)
• `forest` - Dark Green -> Mid Green -> Light Green (gradient)
• `candy` - Pink -> Purple -> Turquoise (gradient)
• `pastel` - Pink, Green, Blue, Yellow (per-tab)
• `jewel` - Ruby, Sapphire, Amethyst, Topaz (per-tab)
• `terminal` - Red, Green, Cyan, Yellow (per-tab)
• `mono` - Theme primary color (solid)
• `accent` - Theme accent color (solid)
• `underline` - No background, underlined active (minimal)
• `dim` - No background, dim inactive (minimal)

Examples:

// Use a preset
{ "overrides": { "tabStyle": "sunset" } }

// Custom gradient
{ "overrides": { "tabStyle": "gradient", "tabColors": ["#FF6B35", "#F7C59F", "#FF006E"] } }

// Per-tab distinct colors
{ "overrides": { "tabStyle": "per-tab", "tabColors": ["#FF5555", "#50FA7B", "#8BE9FD", "#F1FA8C"] } }

Color Key Categories

All colors use hex format (`#RRGGBB`). Key categories:

• **Brand**: `primary`, `secondary`, `accent`
• **Status**: `success`, `warning`, `error`, `info`
• **Text**: `textPrimary`, `textSecondary`, `textMuted`, `textSubtle`, `textHighlight`, `textSelection`, `textInverse`
• **Background**: `bgPrimary`, `bgSecondary`, `bgTertiary`, `bgOverlay`
• **Border**: `borderNormal`, `borderActive`, `borderMuted`
• **Gradient border**: `gradientBorderActive`, `gradientBorderNormal` (arrays), `gradientBorderAngle` (number)
• **Tab**: `tabStyle`, `tabColors` (array)
• **Diff**: `diffAddFg`, `diffAddBg`, `diffRemoveFg`, `diffRemoveBg`
• **UI elements**: `buttonHover`, `tabTextInactive`, `link`, `toastSuccessText`, `toastErrorText`
• **Danger**: `dangerLight`, `dangerDark`, `dangerBright`, `dangerHover`
• **Blame age**: `blameAge1` through `blameAge5`
• **Third-party**: `syntaxTheme` (Chroma theme name), `markdownTheme` (`dark`/`light`)

Full color values for all themes: see `references/palette-reference.md`.

Syntax Themes

The `syntaxTheme` value can be any Chroma theme:

• `monokai`, `dracula`, `github`, `github-dark`, `nord`, `onedark`, `solarized-dark`, `solarized-light`, `vs`, `vim`

See [Chroma Style Gallery](https://xyproto.github.io/splash/docs/) for all options.

Color Validation

Colors must be valid hex in `#RRGGBB` format. Invalid colors are ignored.

• Valid: `"#FF5500"`, `"#ff5500"` (lowercase ok)
• Invalid: `"FF5500"` (missing #), `"#F50"` (shorthand), `"red"` (named colors)

Nerd Fonts

When `nerdFontsEnabled` is true: pill-shaped tabs (Powerline chars), pill-shaped buttons. Requires a Nerd Font installed in your terminal.

Community Themes

Press `#` to open theme switcher, then `Tab` to browse 453 community color schemes. Supports search, live preview, color swatches. Press `Enter` to save.

Community themes are converted from iTerm2 color schemes. Stored by scheme name:

{
  "ui": {
    "theme": {
      "name": "default",
      "community": "Catppuccin Mocha",
      "overrides": { "primary": "#ff79c6" }
    }
  }
}

To regenerate community themes from upstream:

git clone https://github.com/mbadolato/iTerm2-Color-Schemes ~/code/iTerm2-Color-Schemes
./scripts/generate-schemes.sh [path-to-repo]

Per-Project Themes

Each project can have its own theme. When switching with