Create Theme

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 for all options.

It applies everywhere Sidecar highlights code: raw file previews, git diffs, and fenced code blocks inside rendered Markdown. If the name is not a registered Chroma style, Sidecar falls back deterministically to github for light palettes and monokai for dark ones rather than failing.

Markdown Colors

There is no Markdown-specific color family. Rendered Markdown — Files preview, Notes view mode, conversation bodies, workspace document/issue/resource panes, release notes — is styled by internal/markdown from the same normalized semantic palette every other surface uses, so a new theme gets palette-correct Markdown for free and a live theme preview (#) repaints already-open documents immediately.

The rendered document deliberately paints no background so pane chrome and selection keep owning the canvas; only inline code and the Chroma code-block style carry one.

markdownTheme

markdownTheme is not a color. It has two behaviors:

• dark or light — the normal case. Sidecar takes only structure from that Glamour preset (margins, prefixes, list glyphs, task markers) and then overwrites every color from the table above. Set it to match your background; if it is missing or unusable, Sidecar picks a mode from bgPrimary's luma.
• Any other value — an advanced full-style override: a registered Glamour style name, or a path to a Glamour JSON style file. That file owns the whole Markdown appearance and the palette mapping is skipped entirely. Use this only when you deliberately want Markdown to stop tracking the Sidecar palette.

Curated themes and community conversions must use dark or light; an all-theme audit test (internal/markdown/theme_audit_test.go) fails on a missing semantic color, an unknown syntaxTheme, or a non-structural markdownTheme.