FIELD NOTE / 01
A complete palette
This is the shape every bundled theme uses: mode first, then the accents, then backgrounds darkest to lightest, then foregrounds, then the named colours. Nothing is nested; colors.toml has no tables.
mode = "dark"
accent = "#7aa2f7"
selection = "#292e42"
muted = "#414868"
background = "#1a1b26"
dark_background = "#13141c"
darker_background = "#0e0e14"
lighter_background = "#24283b"
foreground = "#a9b1d6"
dark_foreground = "#565f89"
light_foreground = "#b4bee6"
bright_foreground = "#c0caf5"
red = "#f7768e"
yellow = "#e0af68"
orange = "#eb927b"
green = "#9ece6a"
cyan = "#449dab"
blue = "#7aa2f7"
magenta = "#ad8ee6"
brown = "#75493d"
bright_red = "#ff7a93"
bright_yellow = "#ff9e64"
bright_green = "#b9f27c"
bright_cyan = "#0db9d7"
bright_blue = "#7da6ff"
bright_magenta = "#bb9af7"FIELD NOTE / 02
What each key is for
| Key | Role |
|---|---|
mode | "dark" or "light". Decides which variant themed applications use. |
accent | The colour your theme is remembered by: focused borders, active bar elements, links, selected rows. Where it is missing, some surfaces fall back to color4. |
selection | The background behind selected text. Omarchy derives selection_background from it and pairs it with bright_foreground. |
muted | De-emphasised elements — comments, placeholders, dividers. Also serves as ANSI color8. |
background | The primary surface, and ANSI color0. |
dark_background, darker_background | Recessed surfaces. On a light theme these still step away from foreground, so they are lighter, not darker, despite the names. |
lighter_background | Raised surfaces: cards, popovers, the hovered row. |
foreground | Primary readable text, and ANSI color7. |
dark_foreground | Secondary text. |
light_foreground | Emphasised text. |
bright_foreground | The brightest step, ANSI color15. Terminal and editor cursors use it; there is no separate cursor key. |
red … bright_magenta | The sixteen ANSI colours by name. red also populates the shell’s urgent role — there is no urgent key, and one defined in colors.toml is ignored. |
FIELD NOTE / 03
How light and dark are decided
Omarchy takes the first answer it finds, in this order:
- The
modekey. - The legacy
theme_typekey. - A
light.modefile next tocolors.toml, whatever it contains. - Luminance: the three channel bytes of
backgroundare summed, and a total above 382 is treated as light. - Failing all of that, dark.
Set mode explicitly. Auto-detection is a safety net for old themes, and a mid-tone background sits close enough to the 382 threshold to be guessed wrong.
FIELD NOTE / 04
What Omarchy fills in for you
A short palette still produces a complete theme. When a key is absent, Omarchy derives it:
| Missing key | Derived from |
|---|---|
background / foreground | color0 / color7. |
light_foreground | color7, else foreground. |
bright_foreground | color15, else foreground. |
lighter_background | color0, else background. |
dark_foreground | color8, else foreground. |
muted | color8, else dark_foreground. |
selection | selection_background, then color8, color0, background. |
orange | yellow. |
brown | orange mixed 50% toward black. |
dark_background | background mixed 25% toward black. |
darker_background | background mixed 50% toward black. |
Any bright_* colour | Its base colour mixed 20% toward white. |
The derived shades are arithmetic, not taste. They are a reasonable floor, not a substitute for choosing the values yourself — and on a light theme, mixing background toward black for dark_background is very often not what you want.
FIELD NOTE / 05
Legacy and ANSI names
Older themes and templates use short names and numbered ANSI colours. Both still work in either direction, and canonical names win when a theme defines both forms.
| Canonical | Legacy |
|---|---|
background | bg |
dark_background | dark_bg |
darker_background | darker_bg |
lighter_background | lighter_bg |
foreground | fg |
dark_foreground | dark_fg |
light_foreground | light_fg |
bright_foreground | bright_fg |
color0 through color15 map onto the semantic names — color0 is background, color1 is red, color8 is muted, color15 is bright_foreground — and purple is accepted as a synonym for magenta. Write the canonical names in a new theme; read the legacy ones when you are porting somebody else’s.
FIELD NOTE / 06
Template placeholders
Anything in colors.toml is available to a template as {{ key }}. Two modifiers cover applications that want a different format, and every resolved key supports both.
| Placeholder | Output for accent = "#7aa2f7" |
|---|---|
{{ accent }} | #7aa2f7 |
{{ accent_strip }} | 7aa2f7 |
{{ accent_rgb }} | 122,162,247 |
mix, mix_strip and mix_rgb blend two palette keys by a fraction or a percentage — {{ mix background foreground 15% }}, {{ mix_strip background accent 0.35 }}.
Some keys may hold a Hyprland-style gradient instead of a single colour, such as hyprland_active_border = "rgba(33ccffee) rgba(00ff99ee) 45deg". Three helpers format them, and each takes a fallback key as its second argument: {{ hypr_gradient … }} for Hyprland’s Lua config, {{ shell_gradient … }} for shell border tokens, and {{ gradient_start … }} for consumers that accept one flat colour.