Theme System

Overview

Canopy's theme system controls the appearance of all app UI chrome: surfaces, text, borders, accents, shadows, and frosted glass effects. Each theme is built from a hand-crafted color palette that gets compiled into over 140 CSS tokens, giving every surface a consistent look.

The app ships with 14 built-in themes, split evenly between dark and light. Daintree is the default dark theme (eucalyptus green accent) and Bondi Beach is the default light theme (deep coastal teal). On first launch, Canopy picks whichever matches your operating system's current appearance.

If none of the built-in options are quite right, you can export any theme as a JSON file, edit the colors, and import it back as a custom theme. See Theme Export and Import below.

Built-in Themes

Every built-in theme draws its palette from a real-world natural ecosystem. The accent color anchors the visual identity, while surface and text colors are tuned to complement it. All 14 themes include frosted glass effects powered by per-theme material blur and saturation values.

Dark Themes

Light Themes

Changing Your Theme

Open Settings → Appearance → App to access the theme picker. The picker shows a large hero image card for the active theme with its name, location, and a strip of palette swatches. Click the dropdown to browse all available themes, grouped into Dark and Light sections.

Each theme in the dropdown shows its own hero image, name, location subtitle, and palette strip so you can compare at a glance. Selecting a new theme applies it immediately across the entire app.

During the first-run welcome dialog, Canopy prompts you to choose between Daintree and Bondi Beach. It auto-selects based on your OS appearance, but you can switch. A note below the choice cards points to Settings → Appearance for access to all 14 themes.

Match System Appearance

The Match system appearance toggle in the theme picker lets Canopy follow your operating system's dark/light mode. When enabled, the app switches automatically whenever your OS appearance changes.

Two sub-pickers appear below the toggle: Preferred dark theme and Preferred light theme. These let you choose which specific theme to use for each mode. The defaults are Daintree for dark and Bondi Beach for light.

One thing to note: manually selecting a theme from the main picker while follow-system is active will automatically disable the toggle. This prevents the OS from overriding a deliberate choice.

Terminal Color Schemes

Terminal color schemes control the ANSI color palette used inside terminal panels: the foreground, background, and 16 ANSI colors that programs use for syntax highlighting, status output, and prompts. They're configured separately from the app theme under Settings → Appearance → Terminal.

The Terminal subtab also includes font size (8–24 px), font family (JetBrains Mono or system monospace), and dock density controls, among others. Color scheme selection is the focus of this section.

Choosing a Color Scheme

The color scheme picker is a two-column scrollable grid. Each card shows a mini terminal mockup rendered with the scheme's actual colors, displaying sample output like $ ls src/, $ git status, and test results so you can see how the scheme looks in practice.

A sticky search input sits at the top of the grid for filtering by name. Light schemes display a small "light" badge on their card. Selecting a scheme applies it immediately to all open terminal and agent panels — both use ANSI rendering.

Match App Theme

Match App Theme is the default selection and keeps your terminal colors in sync with whatever app theme you're using. Rather than a fixed palette, it reads the active theme's terminal color tokens and applies them to the terminal in real time.

Daintree and Bondi Beach have hand-crafted terminal color mappings designed alongside their app themes. All other app themes supply their own terminal colors through CSS custom properties, so every theme gets a distinct terminal palette that complements its UI chrome. There's no generic fallback here: switching from Fiordland to Highlands gives you a genuinely different terminal look.

The hybrid input bar (the command input inside terminal panels) also derives its colors from the active terminal scheme. Background, foreground, cursor, and chip colors all update to match, keeping the input bar visually consistent with the terminal output above it.

Built-in Schemes

Canopy ships with 25 built-in terminal color schemes. Seven are Canopy originals designed to pair with the app's own themes, and eighteen are community favorites ported from popular editor and terminal projects.

Canopy originals

• Match App Theme — dynamic, derives colors from the active app theme
• Daintree — dark, eucalyptus green accent paired with the Daintree app theme
• Fiordland — dark, cold fjord palette with teal cursor
• Canopy Ember — dark, warm terracotta and ember tones
• Redwoods — dark, forest brown and green
• Hokkaido — light, frost-blue winter palette
• Bondi — light, coastal teal paired with the Bondi Beach app theme

Community dark schemes

• Dracula
• One Dark
• Monokai
• Solarized Dark
• GitHub Dark
• Catppuccin Mocha
• Tokyo Night
• Gruvbox Dark
• Everforest Dark
• Oceanic Next
• Kanagawa Dragon
• Tomorrow Night

Community light schemes

• Solarized Light
• Rosé Pine Dawn
• Catppuccin Latte
• Atom One Light
• Gruvbox Light
• Ayu Light

Importing Custom Schemes

If the built-in options don't cover your preferred palette, you can import custom color schemes from files. The Import color scheme... button sits below the picker grid in the Terminal subtab.

Click the button to open a native file dialog. Select a color scheme file and it's added to your list immediately, becoming the active scheme. Imported schemes persist across app restarts.

Three file formats are supported:

• iTerm2 (.itermcolors) — the XML plist format used by iTerm2 and many other macOS terminals. This is the most widely shared format in the terminal theming community.
• Base16 JSON — JSON files with base00 through base0F keys, following the Base16 convention popular in the Neovim and editor theming ecosystem.
• VS Code JSON — JSON files with terminal.ansiBlack, terminal.background, and similar keys matching VS Code's terminal color token format.

Format detection is automatic based on file extension and key patterns. Any ANSI slots missing from the imported file get filled with sensible defaults.

Theme Export and Import

Canopy supports sharing themes via JSON files. The Export app theme and Import app theme buttons in the theme picker let you save any theme to a file, edit the colors, and share it with others.

Exporting a Theme

Export works on any theme, including the built-in ones. The exported file is a clean JSON document ready for sharing or editing.

1. Open Settings > Appearance and select the theme you want to export
2. Click Export app theme... below the theme picker
3. Choose a save location in the file dialog. The filename defaults to ThemeName.json

The exported file contains the theme's name, type (dark or light), and the full set of color tokens. Internal metadata like location and builtin flags are stripped, so the file is clean for redistribution. Cancelling the save dialog does nothing (no error message).

Importing a Theme

Importing adds a theme to your custom themes list and immediately switches to it.

1. Open Settings > Appearance and click Import app theme... below the theme picker
2. Select a .json theme file from the file dialog
3. The theme loads, validates, and activates. You'll see a confirmation: Imported "Theme Name".

If the file has warnings (see below), the message changes to Imported "Theme Name" with N warning(s). and lists the specific issues. Cancelling the file dialog is silent.

The Theme File Format

Exported themes use a straightforward JSON structure with the theme name, type, and a tokens object containing color values:

{
  "name": "My Custom Theme",
  "type": "dark",
  "tokens": {
    "surface-canvas": "#1a1a2e",
    "surface-sidebar": "#1e1e34",
    "surface-panel": "#232340",
    "text-primary": "#e8e8ed",
    "text-secondary": "#a0a0b0",
    "accent-primary": "#36ce94",
    "border-default": "#2a2a45"
  }
}

You don't need to specify all ~140 token keys. Any tokens you leave out fall back to the defaults from the matching built-in theme: Daintree for dark themes, Bondi Beach for light themes. A handful of core tokens (surfaces, text, accent, borders) is enough to define a distinct look.

The importer also accepts a flat format where token keys sit at the root level alongside metadata fields. Both formats work identically.

If you omit the type field, Canopy infers whether the theme is dark or light from the luminance of the surface colors. Including type explicitly avoids the inference warning.

Import Warnings

Warnings are non-fatal. The theme still imports and activates, but a message appears below the buttons listing anything that might need attention.

• Inferred type — the file didn't include a type field, so Canopy guessed dark or light from the color values. Adding "type": "dark" or "type": "light" to the file makes it explicit.
• Unknown tokens — the tokens object contains keys that Canopy doesn't recognize. These are silently ignored. This can happen when importing a theme from a newer version of Canopy into an older one.
• Contrast issues — certain text/surface color combinations don't meet WCAG contrast ratios. Canopy checks key pairs like text-primary on surface colors (4.5:1 minimum), text-secondary on panels (3.0:1 minimum), and terminal foreground on terminal background. Low-contrast themes will still import but may be difficult to read.

Sharing Themes

Theme sharing is file-based and works with any transfer method. Export a .json file, send it via Slack, email, or commit it to a repo, and the recipient imports it. An exported file can be re-imported without any data loss, so round-tripping works cleanly.

Built-in themes are fully exportable, which makes them a great starting point for team themes. Export a built-in, adjust the accent colors and surfaces to match your team's branding, and distribute the file. Everyone imports the same file and gets an identical setup.

Imported themes appear in the auto-switching picker and the random shuffle pool alongside the built-in options.

Color Vision Accessibility

Canopy offers color vision deficiency (CVD) modes to make status indicators and terminal output more distinguishable. These are available in Settings > Appearance under the Color Vision section.

Three modes are available:

• Default: standard color palette, no adjustments.
• Red-Green (Deuteranopia and Protanopia): remaps red and green status indicators to more distinguishable alternatives.
• Blue-Yellow (Tritanopia): remaps blue and yellow indicators similarly.

CVD modes affect status indicator colors (success, danger, GitHub state colors) and terminal ANSI color mappings. They don't change the overall theme accent color or surface palette, so your chosen theme still looks like itself.