Authoring a theme

Write a theme file, iterate on it live, and share it.


A theme is one TOML file. Put it in ~/.config/atlas/themes/ and Atlas picks it up. To build one without writing the file by hand, use the theme editor in Settings.

Start from two colors

This is a whole theme:

~/.config/atlas/themes/my-theme.toml
schema = 1
id = "my-theme"
name = "My Theme"
author = "Your Name"
license = "MIT"

[dark.base]
background = "#101418"
primary = "#7aa2f7"

background, foreground and primary are the seeds. Every other base token is derived from them: surfaces and borders are the background mixed toward the foreground, text on a fill is whichever of your foreground and background reads better on it, and so on. Leave out foreground and it is whichever of white and black reads better on your background. Leave out primary and the theme is monochrome, using the foreground as its accent.

Nothing here is required beyond the header and one variant. The token reference lists the rule behind each derived token.

Pin what you care about

Any base token you write is used exactly as written, and nothing is derived over it. This file pins all 42, with the values the built-in Rosé Pine theme uses. Change the metadata at the top, then replace or delete the colors as you like.

~/.config/atlas/themes/my-theme.toml
schema = 1
id = "my-theme"
name = "My Theme"
author = "Your Name"
license = "MIT"

[dark.base]
background = "#08070a"
foreground = "#e0def4"
card = "#18151e"
card-foreground = "#e0def4"
popover = "#24202c"
popover-foreground = "#e0def4"
primary = "#eb6f92"
primary-foreground = "#16090e"
secondary = "#18151e"
secondary-foreground = "#aaa6c2"
muted = "#1e1a25"
muted-foreground = "#56516a"
accent = "#1e1a25"
accent-foreground = "#e0def4"
destructive = "#eb6f92"
destructive-foreground = "#16090e"
border = "#302a39"
input = "#302a39"
ring = "#eb6f92"
chart-1 = "#31748f"
chart-2 = "#f6c177"
chart-3 = "#c4a7e7"
chart-4 = "#9ccfd8"
chart-5 = "#eb6f92"
sidebar = "#100e14"
sidebar-foreground = "#e0def4"
sidebar-primary = "#eb6f92"
sidebar-primary-foreground = "#16090e"
sidebar-accent = "#18151e"
sidebar-accent-foreground = "#e0def4"
sidebar-border = "#1b1721"
sidebar-ring = "#eb6f92"
radius = "8px"
tracking-normal = "0em"
spacing = "0.25rem"
shadow-2xs = "0 1px 2px rgba(0, 0, 0, 0.35)"
shadow-xs = "0 1px 2px rgba(0, 0, 0, 0.45)"
shadow-sm = "0 1px 3px rgba(0, 0, 0, 0.55)"
shadow-md = "0 4px 12px rgba(0, 0, 0, 0.65)"
shadow-lg = "0 8px 24px rgba(0, 0, 0, 0.75)"
shadow-xl = "0 12px 36px rgba(0, 0, 0, 0.82)"
shadow-2xl = "0 16px 48px rgba(0, 0, 0, 0.9)"

All five fields at the top are required, and so is at least one of [dark] and [light]. id is what Atlas stores in your settings, so keep it stable once you have shared the file.

A theme whose id matches a built-in replaces that built-in in the picker. Choose an id of your own unless overriding one is what you want.

Work at the level you need

There are three levels, and each exists only to take over from the one below it.

Base tokens, starting from the seeds

42 tokens plus three font stacks, all optional. They are the shadcn/ui token names exactly, so they describe surfaces and text rather than particular features: background, card, popover, primary, muted, border, ring, and the rest.

Every color in Atlas can be reached from the three seeds alone. Start there, and pin another base token only where the derived one is not what you want.

A palette, when the derived colors are dull

Eight named hues. Atlas derives syntax highlighting, terminal ANSI colors, diff tints, status colors, and search highlights from them:

[dark.palette]
red = "#eb6f92"
orange = "#ebbcba"
yellow = "#f6c177"
green = "#31748f"
cyan = "#9ccfd8"
blue = "#9ccfd8"
purple = "#c4a7e7"
pink = "#ebbcba"

This is the highest-value eight lines in a theme file. Without a palette, a key such as syntax.string has no hue to come from and falls back to an Atlas default that has nothing to do with your theme. For the syntax roles that default is Pierre's colors.

Set some of the eight and leave the others out if you prefer. Each is looked up on its own.

The names are hues, not slots. Everything downstream trusts them, so a green holding your theme's cyan puts that cyan into ANSI green, added lines, and success messages at once.

Theme keys, for the surfaces you care about

73 named roles. Set one when you want a specific color rather than a derived one:

[dark.keys]
"syntax.comment" = "#6e6a86"
"syntax.keyword" = "#31748f"
"editor.background" = "#191724"
"editor.selection.background" = "#403d52"
"terminal.ansi.red" = "#eb6f92"
"border.subtle" = "#1b1721"

The token reference lists them, with the handful worth setting first separated from the long tail.

Nested tables mean the same thing as dotted keys, so this is equivalent:

[dark.keys.terminal.ansi]
red = "#eb6f92"
green = "#31748f"

A key may be a value or a prefix, never both. Writing terminal.ansi.red and terminal in the same variant is an error and the file will not load. Set the leaf you mean.

An explicit key is the final color. Where Atlas would have applied a transparency or a tint while deriving that key, it does not do so to a value you wrote yourself, so include the alpha you want.

A theme key is a color, and only a color

The value may be written bare or as a one-field table, and the two mean the same thing:

"syntax.keyword" = "#c9a2f5"          # bare
"syntax.string" = { color = "#9ecf8a" }  # the same thing, as a table

There is no font style. Nothing between a resolved key and the editor, the session's code highlighter, or the markdown renderer can carry one, so font_style is refused by name rather than accepted and ignored:

# This does not load.
"syntax.comment" = { color = "#6e6a86", font_style = "italic" }

The error names the key, so a file that picked the field up from a Zed or VS Code theme tells you where to remove it.

Add a light variant

[light.base], [light.palette], and [light.keys] take the same shape, and a file may hold both variants or only one:

[light.base]
background = "#faf4ed"
foreground = "#575279"
primary = "#907aa9"
# anything else you want to pin

[light.palette]
red = "#b4637a"
orange = "#d7827e"
yellow = "#ea9d34"
green = "#286983"
cyan = "#56949f"
blue = "#56949f"
purple = "#907aa9"
pink = "#d7827e"

The two variants are independent. If you set the shadows, give the light one its own values rather than copying the dark ones across, or its surfaces will carry heavy dark halos on a pale background. Tint a light ramp from the theme's own foreground at a much lower alpha. Left out, each variant gets Atlas's ramp for its appearance.

Shipping a light variant is worth doing. Atlas's Light and System modes are available on every platform, and a theme without one falls back to its dark variant when the operating system uses a light appearance.

Write colors Atlas accepts

Hex (3, 4, 6, or 8 digits), rgb(), rgba(), hsl(), hsla(), and oklch(). An 8-digit hex or an alpha channel is the way to set a translucent overlay.

"editor.active_line.background" = "#ffffff0a"
"diff.added.background" = "rgba(34,197,94,0.13)"
"status.info.foreground" = "oklch(0.72 0.12 250)"

CSS color names such as red are not accepted, and neither is anything Atlas cannot resolve to a value on its own, including var() and color-mix().

The non-color base tokens are ordinary CSS values: radius, tracking-normal and spacing are lengths, the font-* tokens are font stacks, and the shadow-* tokens are box-shadow values.

The three font tokens have no derivation rule. Leave them out and your theme uses Atlas's fonts. Set them and they apply to anyone whose font settings are on their defaults; a font someone picked in Settings always wins. Tokens both variants share can go in a top-level [base] table instead of being written twice:

[base]
font-sans = "Inter, sans-serif"
radius = "6px"

Turn on editor autocomplete

Atlas publishes a JSON Schema for the file format. Save a copy next to your theme and point the first line at it:

#:schema ./theme-v1.json
schema = 1
id = "my-theme"

The schema enumerates the whole key set, so a TOML-aware editor completes key names, shows each key's description on hover, and underlines a name Atlas does not have. That catches the one mistake nothing else can: a misspelled key loads without complaint and simply never paints anything.

The schema is stricter than the loader on purpose. Atlas keeps an unknown key with a warning, for the forward compatibility described below; your editor should still tell you about it.

The schema ships in the Atlas repository at crates/atlas-theme/schema/theme-v1.json.

Build one in the theme editor

Settings → Appearance → Themes has a theme editor, so you can make a theme by picking colors instead of writing TOML. Three buttons open it:

  • Create theme, beside Import theme, starts from the background and accent of the theme on screen, in the appearance on screen only. Everything else is derived.
  • Duplicate, on every card, copies every value that theme writes, in both variants.
  • Edit, on a theme of your own, changes it in place. A built-in theme has no Edit; duplicate it instead.

The editor floats over the whole app, and the app is the preview: every change repaints the window as you make it. Drag the panel by its header to uncover what you are judging, or minimise it. It stays open when you close Settings, so you can check the editor, the sidebar and the terminal in the new colors. Close it without saving and Atlas goes back to the theme you had.

Light and Dark switch which variant you are editing. A variant the theme does not have yet is added when you set its first color.

The simple view has two colors, Background and Accent, and derives the rest. If some colors are set by hand, as they are in a duplicated built-in, the editor says how many won't follow these two and offers Let them follow, which unpins them.

Turn on Advanced to see every color slot, grouped by role: Foundation, Surfaces, Text on fills, Sidebar, Status and charts, Palette and Syntax, with a filter. A slot you have not set shows its derived value, dimmed. A slot you have set has a reset button that clears it so it derives again. Radius, spacing and shadows are not in the editor; set those in the file.

Saving writes only the values you set, to ~/.config/atlas/themes/, under an id made from the name. A name already taken by another theme, built-in or yours, is refused. Everything you left alone keeps being derived, so it improves as Atlas's rules do. A new theme becomes your theme for each appearance it has. The editor has Author and Licence fields. A duplicate starts with the original's; a created theme starts with neither. If you share a duplicate, keep the original credit: most theme licences require it.

Iterate while Atlas is running

  1. Save the file in ~/.config/atlas/themes/.
  2. Open Settings → Appearance. The theme is already in the grid.
  3. Click its card to wear it in both appearances, or one of its orbs to wear it in just that one.

Every later edit repaints as you save. Atlas watches the folder, rereads the file, and reapplies the theme you are wearing, so there is no restart, no reinstall, and no switching away and back.

Keep a terminal, a diff, and a file open in the editor while you work. Those three surfaces use most of the palette between them, and they are where a derived color that does not suit your theme shows up first.

What happens when something is wrong

A file that does not parse is skipped. Atlas loads every other theme, so the picker keeps working and the app keeps its current colors. The picker names the file and the reason above the grid, so a theme that never appeared tells you why.

These are the errors that stop a file loading:

  • schema is anything other than 1
  • id or name is empty
  • neither [dark] nor [light] is present
  • a base token or palette name Atlas does not know
  • a value that is not one of the accepted color formats
  • a key used as both a value and a prefix
  • a key that sets font_style

An unknown theme key is a warning, not an error. The theme still loads and the key is kept, and its card in the picker carries a badge with the count. That is deliberate: the key set changes between versions, and a file written against a newer Atlas should still work on an older one rather than failing outright over a key that version has never heard of. The same rule is what lets a key be retired without breaking the themes that set it.

Share a theme

The file is the whole thing. Send the .toml, and whoever receives it drops it in ~/.config/atlas/themes/.

Set author and license before you publish, and if your colors come from an existing theme, credit it there. Every built-in theme in Atlas carries the license of the palette it is based on.

Next

On this page