/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

Sidecar ships with 21 modern, contrast-compliant themes designed around a 7-step neutral ramp and single signature chrome accent:

• **sidecar-modern** - Modern default with signature gold accent (`#c0982f`) and dark neutral ramp
• **catppuccin-mocha** - Soothing lavender/blue (`#89b4fa`) with dark mantle
• **tokyonight-storm** - Tokyo neon night blue (`#7aa2f7`)
• **gruvbox-dark** - Retro warm gold (`#fabd2f`) & aqua (`#8ec07c`)
• **dracula** - Refined vampire violet (`#bd93f9`)
• **nord** - Arctic frost cyan (`#88c0d0`)
• **atom-one-dark** - Balanced editor cyan/blue (`#61afef`)
• **kanagawa-wave** - Woodblock print wave blue (`#7e9cd8`)
• **rose-pine** - Soho rose (`#eb6f92`) & pine cyan (`#9ccfd8`)
• **everforest-dark** - Earthy forest green (`#a7c080`) & warm amber (`#dbbc7f`)
• **solarized-dark** - Precision amber/yellow (`#b58900`) & cyan (`#2aa198`)
• **monokai-pro** - Crisp gold (`#ffd866`) & green (`#a6e22e`)
• **night-owl** - Deep navy blue (`#82aaff`)
• **ayu-mirage** - Warm sunset gold (`#6dcbfa`) on slate
• **github-dark** - Crisp GitHub cobalt (`#58a6ff`)
• **synthwave** - 80s retrowave fuchsia (`#ff77ff`)
• **cobalt2** - High-contrast Wes Bos cobalt yellow (`#ffe50a`)
• **horizon** - Cyberpunk apricot/red (`#ed718e`)
• **shades-of-purple** - High-contrast magenta/violet (`#ff77ff`)
• **spacegray-eighties** - Muted classic warm gray & blue (`#7ba1cf`)
• **zenburn** - Low-contrast soft green (`#90cbae`)

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`, `selectionBg`
• **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.gi