Skip to main content

Choose and Customize a Theme

Picking and tuning a Daintree theme: the theme palette and the Theme Browser with live preview, the Appearance settings and Random theme, overriding the accent color and its contrast warning, matching your system appearance, and the accessibility modes.

Updated
Reviewed

Changing Your Theme

The quickest way to switch is the theme palette (Command-K, then Command-T Control-K, then Control-T Control-K, then Control-T ). For a side-by-side look with each theme's photograph, open the Theme Browser. Both preview every theme live across the whole app before you commit.

Settings > Appearance > App is where the theme's settings live. The App theme section opens on the current theme's hero image with its name and location. Below it:

  • Theme says how many themes there are to browse and offers two buttons. Random theme applies one at random, working through every other theme in a shuffled order before any repeats. Change theme… opens the Theme Browser. A reset button appears beside the row while you are on anything other than Daintree.
  • Match system appearance, with its Dark theme and Light theme choices, covered in Match System Appearance.
  • Accent color, covered in Accent Color Override.
  • Theme files, with Import… and Export… for sharing themes as JSON files.

The Interface section below it holds the Color vision modes and the dock density.

Choose a theme, match system appearance, or change its accent from App theme.

The setup wizard's appearance step offers Daintree and Bondi Beach, auto-selected from your OS appearance (plus the theme you already chose, if you picked a different one first), with a note pointing at Settings → Appearance for the rest.

Live preview

The theme palette and the Theme Browser both repaint the whole app with the theme you are trying, immediately: sidebar, toolbar, panels, dock, everything. In the palette the preview follows the highlighted row, whether you move it with the arrow keys or the pointer. In the Theme Browser only a click or an arrow key moves the preview. Hovering a row does not, so the pointer's way to Set theme cannot change which theme it saves.

Previews are transient. The saved theme does not change until you commit: Enter or a click in the palette, Set theme or Enter in the browser. Escape, Cancel or closing either one reverts to the saved theme.

Applying a theme without a restart

Every theme change re-applies the full token set to the document root in one pass, and this is the mechanism that makes switching reliable rather than something you have to restart for. Applying a theme writes every CSS variable, sets data-theme, data-colorMode, the CSS color-scheme property and the .dark / .light classes. Critically, it also clears stale variables left behind by the previous theme before writing the new ones.

That clearing step matters because component-level overrides are optional. A theme can ship extensions that restyle the toolbar, sidebar, settings dialog or panel grid, and a theme with fewer extensions than its predecessor would otherwise inherit the old theme's component chrome and end up half in one theme and half in the other. Clearing first means what you see after a switch is exactly the new theme, with nothing carried over.

Reveal animation and crossfade

When you pick a theme from Settings (Random theme, or the theme an import just added) or commit one with Set theme in the browser, the UI plays a short directional sweep as the new theme swaps in. The direction follows your click position: clicks on the left half of the window sweep the old theme out to the right, clicks on the right half sweep it left. The wipe runs 400ms and is the signal that encodes where the change came from.

When the app changes the theme on your behalf, it crossfades instead of cutting. An OS appearance switch under match system appearance, or the first-run wizard auto-selecting a theme after the window has already painted, both fade the outgoing theme out rather than snapping. The directional wipe is deliberately not used there: a wipe encodes a gesture's origin, and these paths have no gesture. Startup hydration is not animated at all, because there is no prior theme to fade from.

Rapid changes are handled by a monotonic "latest theme intent" counter. A crossfade defers its DOM write by a frame, so a newer change claimed after it (a second crossfade, a hover preview, an accent tweak) outranks it and the stale callback bails rather than stranding the DOM out of sync with the store.

Both animations are built on document.startViewTransition with a WAAPI animation on the transition pseudo-element, so they composite on the GPU. Both turn off entirely when prefers-reduced-motion: reduce is set, when reduced-animation or performance mode is on, when the document is hidden, or when View Transitions are unavailable, in which case the switch happens instantly.

The Theme Palette

To switch themes from the keyboard without opening Settings, press Command-K, then Command-T Control-K, then Control-T Control-K, then Control-T . It is a chord: press the first combination, then the second. The Theme switcher palette opens on your current theme, with fuzzy search across every available theme, custom ones included. Search matches the theme's name and its place, so japan finds Arashiyama and Hokkaido, and the words dark or light narrow the list to that mode (light japan finds Hokkaido).

Rows are grouped under Dark and Light headings. Each shows the theme's name, its location, a palette strip of its colors, and a check mark on the theme you are running. The arrow keys and the pointer both move the highlight, and the whole app previews the highlighted theme as it moves. Enter or a click commits it and closes; Escape reverts to whatever was active when you opened it. The footer says what Enter will do (to apply Fiordland, or to keep Daintree on the theme you already have) and, once you have moved off it, which theme is current.

The theme palette groups dark and light themes and previews a theme before you keep it.

Toggling dark and light

A Toggle dark/light theme command flips between your preferred dark and light themes, set under Match System Appearance. It ships with no default shortcut: run it from the command palette (Shift-Command-P Control-Shift-P Control-Shift-P , type "toggle") or bind it yourself. See Keyboard Shortcuts.

The Theme Browser

The Theme Browser is a drawer that slides in from the right edge. It is the most spacious way to shop for a theme: a hero at the top showing the previewed theme's photograph with its name and location, a Filter themes field beside a Dark / Light toggle, a scrollable list of rows with thumbnails and color strips, and a bar at the bottom with Cancel and Set theme. Each row shows the theme's name and its location. The theme you are running is marked Current, the one you are previewing is marked Trying, and any theme with validation warnings carries a small warning pill with the warning count.

It has no default keyboard shortcut. Open it from the Change theme… button in Settings > Appearance > App, or from the command palette (Shift-Command-P Control-Shift-P Control-Shift-P , then Browse themes…). Command-K, then Command-T Control-K, then Control-T Control-K, then Control-T does not open the browser: that is the lighter-weight theme palette.

Clicking a row previews it immediately across the whole app. Arrow keys (including Page Up and Page Down) walk the list with the same instant preview while you keep typing in the filter, which matches theme names. Hovering a row does not preview it. The screen-reader announcement of the previewed theme is debounced by 300ms so a fast scroll does not fire on every step. Switching the Dark/Light toggle reverts any active preview first, so a theme you can no longer see cannot be committed by accident.

Set theme (or Enter) commits: it turns off match-system-appearance if it was on, plays the reveal sweep from the button's position, closes the drawer and saves. Cancel, Escape, the close button on the hero, or clicking the dimmed area all revert and close without saving, except that the first Escape clears a non-empty filter rather than closing.

Preview Fiordland while Daintree remains the current theme.
Note

While the Theme Browser is open, the rest of the app is dimmed, non-interactive and removed from the accessibility tree. Closing the drawer restores everything. Opening the browser also closes the Settings dialog so you can see the preview across the full app. If you opened it from Settings, Settings reopens on the App theme section when the browser closes; opened from the command palette, it does not.

Accent Color Override

The Accent color row in Settings > Appearance > App overrides the active theme's accent with a color you pick. Use it when a theme's surfaces are right but you want a different accent: a team brand color, a personal preference, or more separation for color-vision reasons.

Click the swatch to open your OS color picker. Changes apply live as you drag, with no debounce. While an override is on, the row reads the override and the theme's own value side by side (#3A3A38 · Theme default: #36CE94), and a reset button beside the row clears the override and restores the theme's accent. The override persists across restarts and rides along with whatever theme you switch to, and live previews show the override combined with the previewed theme, so what you see is what you get.

The low-contrast warning

An accent is not a free choice: it is the color that carries primary buttons, focus rings, switch tracks and selection state. Daintree checks the accent you pick against a 4.5:1 floor and shows a Low contrast accent warning under the row when it will not hold up, in one of two forms:

  • Foreground failure: the button text sitting on the accent no longer reads. The warning names the measured ratio: "Button text scores 2.31:1 on this accent. Pick a lighter or darker one."
  • Surface failure: the accent no longer separates from the theme's own surfaces. "The accent scores 1.84:1 on Fiordland surfaces. Pick a more distinct one."

Foreground is checked first, because unreadable text on a primary button is the more severe failure and the one you should fix before discovering the surface problem. The warning is advisory (the override still applies), but it is worth acting on, because a failing accent degrades every primary action in the app at once.

Tip

Exporting a theme while an accent override is active bakes the override into the exported file: accent-primary and the accent tints derived from it. It is the quickest way to make a branded variant. Before you share the file, give it a new id and name, or it will keep resolving to the built-in it came from; see Editing an export.

Match System Appearance

The Match system appearance switch tells Daintree to follow your operating system's dark/light mode. Two choices sit below it, Dark theme and Light theme, defaulting to Daintree and Bondi Beach; they stay greyed out until the switch is on. When the OS flips, the app crossfades to the matching preference.

Picking a theme by hand while matching is on (Random theme, the Theme Browser's Set theme) turns the switch off, and the Theme row says so in advance. That is deliberate: an OS change should not overrule a choice you just made by hand.

Accessibility

Color vision deficiency modes

Under Settings > Appearance > App > Interface, the Color vision row offers three modes, with a Preview row of status and syntax swatches drawn the way the current mode draws them:

  • Default: the theme's own palette, no adjustments.
  • Red-green (deuteranopia and protanopia).
  • Blue-yellow (tritanopia).

Each mode replaces a hand-authored set of tokens chosen for distinguishability under that deficiency, layered on top of the active theme as inline overrides. Across the two modes that is 39 explicitly overridden tokens, plus the status-surface washes and the light-mode diff fills and gutters re-derived from them, for around 50 in total. The set covers status colors (success, warning, danger, info), agent activity states, pull-request states, terminal ANSI slots, syntax highlighting colors and the categorical hue set.

The derived values matter as much as the explicit ones. Status washes and diff fills are baked from the base status colors at theme-build time, so patching only the base color would leave banners, pills, diff backgrounds and diff gutters on the original hue while the text on them moved. They are re-derived alongside the override.

CVD modes do not touch the theme's accent or its surface palette, so your chosen theme still looks like itself. Switching back to Default restores each token to the active theme's value rather than simply unsetting it: the theme tokens have no stylesheet fallback, so unsetting would leave them undefined.

Forced colors and increased contrast

Daintree also responds to the operating system's own contrast settings, independently of which theme you have chosen.

Under Windows High Contrast (forced-colors: active), the UA overrides color, background and border, so Daintree stops relying on theme tokens for the surfaces that need to stay distinguishable and re-expresses them in system colors: sidebar worktree items and their selection state, Project Pulse heat levels (which would otherwise all collapse to the same canvas color and lose their four-level ramp) and the diff viewer, which carries its own forced-colors rules.

macOS "Increase Contrast" fires prefers-contrast: more but not forced-colors: active, so there is a separate block for it, and it is the sole high-contrast surface for Mac users. Panel focus and selection chrome stay hardcoded to system colors in both blocks and deliberately override any theme's own focus-chrome extension, so a theme cannot make focus invisible under high contrast.