Theme Authoring
The Daintree theme file format: the palette-first authoring model, the semantic token contract, extensions, import validation and contrast warnings, export, and sharing themes with a team.
A Daintree theme is a JSON file. Export any built-in theme, edit it, import it back, and it appears in the theme palette, the Theme Browser, the Random theme pool and the match-system Dark theme / Light theme choices alongside the built-ins. This page covers the format, the contract you are writing against, and what the importer will and will not accept.
If you are choosing rather than building a theme, see Theme System.
The Three Layers
The theme pipeline has three layers, and knowing which one you are editing is most of the work:
- The palette. Around 50 color inputs: five surface planes, four text tiers, a border ink, an accent (plus an optional secondary accent and overlay tint), four status colors, four activity colors, ten syntax colors, an optional terminal color set, and an optional
strategyobject. This is the layer built-in themes are authored in. - Semantic tokens. The palette compiles into the app-wide token contract: the stable contract every component reads, exposed as
--theme-*CSS variables. You can override individual tokens where the derivation does not give you what you want. - Extensions. Component-level CSS variables for specific regions of the UI: toolbar, sidebar and worktree rows, settings dialog, Project Pulse, panel chrome, panel focus chrome, the dock, the grid background, the welcome screen. These are optional; omit them and the CSS fallbacks apply.
The division of responsibility is deliberate: the app owns layout, spacing and animation timing. A theme owns color, shadow, material and component chrome. Theme files contain data rather than JavaScript. Extension strings are preserved without CSS-value validation and written as custom properties; the importer does not enforce an extension-name allowlist. They can change component appearance, so inspect unfamiliar files and preview their readability before using them.
The File Format
The importer accepts three shapes, and you can mix them. All of them are a single JSON object.
Palette format
The closest thing to how the built-ins are written. Give a palette and let the engine derive everything. A palette needs its type and every color in surfaces, text, status, activity and syntax, plus border and accent. The terminal set, accentSecondary, overlayTint and strategy are optional; any terminal color you leave out is derived from the status colors, text and accent.
{
"name": "My Custom Theme",
"type": "dark",
"location": "Somewhere worth naming",
"palette": {
"type": "dark",
"surfaces": {
"grid": "#0e0e0d",
"sidebar": "#131312",
"canvas": "#19191a",
"panel": "#1d1d1e",
"elevated": "#2b2b2c"
},
"text": {
"primary": "#e4e4e7",
"secondary": "#a1a1aa",
"muted": "#71717a",
"inverse": "#0e0e0d"
},
"border": "#282828",
"accent": "#36ce94",
"status": {
"success": "#36ce94",
"warning": "#d3a343",
"danger": "#d17b72",
"info": "#6ba3d6"
},
"activity": {
"active": "#2eb37c",
"idle": "#585853",
"working": "#2eb37c",
"waiting": "#fbbf24"
},
"syntax": {
"comment": "#74807a",
"punctuation": "#ccd6cf",
"number": "#e2b369",
"string": "#95c879",
"operator": "#8acfd6",
"keyword": "#c89ce8",
"function": "#6fb7e8",
"link": "#5fb8e4",
"quote": "#a9b4ac",
"chip": "#7fd4cf"
}
}
} Leaving out a required palette group (activity or syntax, say) does not fall back to the template. The import fails with a Couldn't import theme error instead. If you only want to change a few colors, use the token format below.
This example imports with one warning, Some terminal colors may be hard to read: with no terminal block, the ANSI colors are derived from the status colors and built-in fallbacks and measured against the canvas, and a few fall short. Add a terminal block to tune them.
Nested token format
Override compiled tokens directly, under a tokens object. Useful for small edits to an exported theme:
{
"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"
}
} Flat format
Token keys can also sit at the top level alongside the metadata fields. Anything that is not a recognized metadata key and not a recognized token key is ignored.
Metadata fields
| Field | What it does |
|---|---|
name | Display name in every picker. Falls back to the filename when omitted. |
type | "dark" or "light". Decides which built-in template fills your gaps, and which polarity's validation rules apply. Omitting it produces a warning. |
id | Optional. Generated from the name as custom-<slug> when omitted. Importing a theme with the same id as an earlier import replaces it. An id that matches a built-in theme never applies, because the built-in wins: an exported built-in keeps its own id (daintree, bondi), so change it before importing the edited file. |
location | A free-text place name. This is what the Theme Browser renders as the caption under the hero image. Stripped on export. |
heroImage | The image the Theme Browser shows at the top of the drawer, and the thumbnail on each row. Validated on import. See below. |
extensions | Optional map of component-level CSS variable overrides, keyed by CSS custom-property names without the leading --. |
Editing an export
An exported file carries both the palette and the full compiled tokens, and tokens always win over the palette. So when you edit an export:
- Change the
idandnamefirst. Otherwise the import keeps the built-in'sid, and selecting it shows the built-in instead of your edit. - Edit token values, not palette values. A palette change under a full token set has no visible effect.
- Token edits are literal. Changing
accent-primarydoes not move the values derived from it (accent-soft,accent-hover,accent-rgband the rest). For a new accent, set it with the accent override before you export: the file then carries the accent and every accent token derived from it. - To author from the palette instead, delete the
tokensobject so the engine derives everything from your palette. Every built-in tunes some tokens by hand on top of its palette, so this also drops that tuning.
Falling Back to the Template
You do not have to define every token. Anything you leave out falls back to the matching built-in theme: Daintree for dark themes, Bondi Beach for light themes. This is not a convenience detail, it is the design principle that keeps custom themes coherent.
Both templates are complete, contrast-validated themes. A handful of core tokens (surfaces, text, accent, borders) is enough to define a distinct look, because every token you did not think about arrives from a theme that has already been audited. It is also why the light-mode rebuild made Bondi Beach the reference light theme rather than just another entry: every light theme anybody imports inherits its decisions wherever they left a gap.
Exporting a built-in theme is the fastest way to start. Export Daintree or Bondi Beach, give the file a new id and name, change the accent and a few surfaces, and import it back: you inherit a fully validated baseline for everything you did not touch. See Editing an export for which part of the file to change.
Non-color Tokens
Not every token is a color. Material blur and saturation, radius scale, scrollbar width, focus-ring offset, shadow profiles, grain opacity and blend, the state-chip and label-pill opacities, and the chrome noise texture are all pass-through values: they are checked for being a non-empty string and otherwise handed to CSS verbatim.
One token is neither: accent-rgb carries a comma-separated RGB triplet like "62, 144, 102", because components composite accent tints as rgba(var(--theme-accent-rgb), …). If your accent-primary is a non-hex color (an oklch() value, say) and you do not supply accent-rgb yourself, it falls back to "0, 0, 0" and every accent tint renders black. The importer warns when that happens.
Import Validation
Imports run through two layers: errors that block the import outright, and warnings that let the theme load with a note. The validator collects every error in a single pass, and the invalid-color error names every failing token or palette field in one message. The Couldn't import theme banner in Settings shows the first error, so a file with two different kinds of problem (a bad color and a bad heroImage, say) reports the second on your next import.
Errors: the import is blocked
- Invalid color values. Any color token or palette color leaf whose value is not a structurally valid CSS color:
Invalid color values for token(s): <list>. Values must be valid CSS colors (hex, rgb/rgba, hsl/hsla, oklch/oklab, color-mix, var, or named color).Palette-format files get the equivalent message naming the failing palette fields. - Invalid
accent-rgb. Must be three integers between 0 and 255, comma-separated. A bad triplet is named in the same invalid-values message as the colors. - Invalid
heroImage. Only adata:image/URL or a path (relative, dot-relative or root-relative) is accepted. Everything carrying a URL scheme is rejected (http:,https:,file:,ftp:,javascript:, and non-imagedata:payloads) along with protocol-relative URLs (//cdn.example.com), Windows absolute paths and UNC paths. A theme file should not be able to make the app fetch from the network or read an arbitrary location on disk. - Nothing recognizable. A file with no known tokens and no palette fails with
No recognized app theme tokens or palette found.
Accepted CSS color formats for any color value:
- Hex: 3-, 4-, 6- and 8-digit (
#abc,#abcd,#aabbcc,#aabbccdd) rgb()andrgba(), legacy comma and modern space syntaxhsl()andhsla()oklch()andoklab()color-mix(), validated one level deepvar()references, optionally with a color fallback- All 147 CSS named colors, plus
transparentandcurrentcolor
This is structural validation rather than full CSS parsing. The goal is to reject obvious garbage like "not-a-color" at the import boundary without rejecting legal CSS the browser would happily render.
Invalid color values block the import. Older theme files that once loaded with warnings on a malformed color need cleaning up before they will import.
Warnings: the import succeeds with a note
Non-fatal. The theme loads and activates, and the import result lists one plain-language line per kind of warning, each with a Technical details disclosure holding the validator's own messages (ratios, token names). A theme carrying warnings also shows a small warning pill on its row in the Theme Browser.
- Inferred type (Theme mode was guessed from the colors): no top-level
typefield, so the polarity came from the palette'stypeor was guessed from the surface colors. Add"type": "dark"or"type": "light"to make it explicit. - Unknown tokens (Some values in this theme weren't recognized): the
tokensobject holds keys Daintree does not recognize. They are ignored. Usually a theme exported from a newer version. - Low contrast (Some colors may be hard to see): a text-on-surface or indicator-on-surface pair falls below its threshold.
- Overlay contrast (Hover highlights may be hard to see): the hover overlay does not move the rendered luminance enough to be perceptible, so hover states read as dead.
- Terminal legibility (Some terminal colors may be hard to read): an ANSI or syntax color does not separate sufficiently from the terminal background.
- Unevaluable (Some colors couldn't be checked): a value the static checker could not resolve to a concrete color: an unresolved
var()or acolor-mix()the runtime will do but the validator cannot. These are skipped rather than failed. accent-rgbfallback (Accent tint colors may not render correctly): a non-hex accent with no explicit triplet, as described above.
The Contrast Validator
The contrast checks are the substantive part of validation, and they run against far more than a single text-on-background pair.
Primary text is checked at 4.5:1 against all five surface planes: grid, sidebar, canvas, panel and elevated. Secondary text is also checked at 4.5:1 against all five. Muted text has a 3.5:1 floor on light themes; dark muted text uses a separate calibration. Every status color (success, warning, danger, info) is checked at 3.0:1 against all five, because status colors render as text in this app rather than as a fill. Search highlight text is checked against its own highlight background. Link text has its own floor, at body-text strength, because a link is readable body text.
Critically, the validator does not stop at opaque hex. Tokens carrying alpha are composited before they are measured: an rgba() value, or a hex value with an alpha channel, is blended over the surface it will actually render on and the resulting concrete color is the one that gets scored. Without that, every translucent overlay, wash and hairline in the theme would pass validation trivially and fail in practice. Where a value genuinely cannot be resolved statically, it is reported as unevaluable rather than silently passing.
Beyond ratio checks there are separation checks, which ask whether two things that must look different actually do: the Project Pulse heat ramp's four levels, the working and waiting activity colors, cards above a dialog body, selected versus unselected filter chips, and the surface ramp itself. These use perceptual distance in OKLCH rather than contrast ratio, because "these two greens are distinguishable" is a different question from "this text is readable".
The built-ins are checked too
The same machinery runs against every shipped theme as part of the test suite, not just against imports. Every built-in theme's ANSI slots and syntax colors are validated for legibility against their own terminal background, every accent is checked for chroma, canvas separation and perceptual distance from every other same-polarity accent, and every surface ramp is checked against the step and span floors. The tests catch regressions in those measured pairs; they do not establish accessibility for every possible component state.
Exporting
- Make the theme you want to export the current one (the theme palette is quickest).
- Open Settings > Appearance > App and click Export… on the Theme files row.
- Choose a location. The filename defaults to the theme's name with characters that are unsafe in filenames stripped, plus
.json.
The exported file is the compiled scheme: id, name, type, the full token set, the palette and extensions when the theme has them, and the heroImage path. The location and builtin fields are stripped. An active accent override is baked in as accent-primary and the accent tokens derived from it. Cancelling the save dialog does nothing, with no error; a failed write shows Couldn't export theme with Retry.
Importing
- Open Settings > Appearance > App and click Import… on the Theme files row.
- Select a
.jsonfile. - The theme parses, validates, is added to your custom themes and becomes active. You will see
Imported "Theme Name".
With non-fatal warnings the message becomes Imported "Theme Name" with 2 warnings., counting the kinds of warning listed beneath it; the theme still loads. With errors the import is blocked and a Couldn't import theme banner shows the first error with Retry. Cancelling the file dialog is silent.
Sharing Themes
Sharing is file-based and works over any transfer you like: Slack, email, or a file committed to a repository. Exports preserve the compiled visual tokens and supported palette and extension data, but strip location and built-in metadata. Check the imported result when sharing a customized theme.
For a team theme, set your brand accent with the accent override and check it against the low-contrast warning, export, give the file its own id and name, adjust any surface tokens, and distribute it. Everyone who imports it gets the same theme values. Their accent override, color vision settings and terminal color scheme can still change the result. Imported themes participate in everything the built-ins do: they appear in the theme palette and the Theme Browser, they can be set as the dark or light theme under match system appearance, and they join the Random theme pool. Sending an updated file with the same id replaces the earlier import.
Custom themes live on the machine that imported them. They are not stored in the project and are not synced, so each person on a team imports the file themselves. Settings has no control for removing an imported theme. To carry your custom themes and theme settings to another of your own machines along with the rest of your preferences, use the configuration export.
Implementation Reference
Use the checked-in token contract, normalizer and palette compilation, and contrast checks when authoring against this version. Those lists are more precise than a fixed token count.