Create a theme

Seven steps

1. Copy a bundled theme whose mode matches what you are making. cp -r "$OMARCHY_PATH/themes/tokyo-night" ~/.config/omarchy/themes/yourname for a dark theme, or flexoki-light for a light one.
2. Delete what you are not keeping: the previous theme’s backgrounds/, preview.png, unlock.png and any hand-written application files. Keep colors.toml.
3. Set mode first, then background, foreground and accent. Those three carry most of the character.
4. Fill in the neutral ramp and the sixteen ANSI colours. Palette best practices covers what to aim for.
5. Add at least one wallpaper under backgrounds/. See backgrounds for sizes and licensing.
6. Apply it with omarchy theme set yourname and live with it for a day. Read code in it, read a long document in it, look at it at night.
7. Turn it into a Git repository and publish.

Prefer a visual editor? The Theme Studio does the same work in the browser, shows contrast ratios while you pick, previews against a simulated desktop, and exports a complete repository.

A complete minimal repository

This is a publishable theme. Four files, nothing generated, nothing that gets dropped on install.

omarchy-harbor-theme/
├── colors.toml
├── backgrounds/
│   └── 001-harbor-dusk.jpg
├── README.md
└── LICENSE

The directory name matters: omarchy-harbor-theme installs as harbor, because Omarchy strips a leading omarchy- and a trailing -theme and lowercases the rest.

A full example colors.toml

An original dark palette, written for this guide. Copy it, change the hexes, keep the structure. The comments are legal TOML and Omarchy skips them.

# Harbor — a cold, slightly green dark theme.
mode = "dark"

# The colour the theme is remembered by.
accent = "#4fa3a5"
selection = "#243b42"
muted = "#5d7480"

# Surfaces, from the primary one outward.
background = "#101a1f"
dark_background = "#0c1418"
darker_background = "#070d10"
lighter_background = "#182831"

# Text, from primary to brightest.
foreground = "#c2d2d8"
dark_foreground = "#7d929c"
light_foreground = "#d7e3e8"
bright_foreground = "#f0f6f8"

# The sixteen ANSI colours, by name.
red = "#e0687a"
yellow = "#d7a75c"
orange = "#dd8a5a"
green = "#7fb069"
cyan = "#4fa3a5"
blue = "#5b8fc9"
magenta = "#a887c9"
brown = "#6e4a33"

bright_red = "#f0899a"
bright_yellow = "#efc27e"
bright_green = "#9bc98a"
bright_cyan = "#72c3c4"
bright_blue = "#82aede"
bright_magenta = "#c3a6e0"

Test it before you publish

• omarchy theme set yourname applies it. omarchy theme list confirms Omarchy can see it.
• omarchy theme current prints what is active.
• omarchy dev theme-preview yourname shows the resolved ramp, including the shades Omarchy derived rather than the ones you wrote.
• omarchy theme color --file ~/.config/omarchy/themes/yourname/colors.toml --all prints every key after fallbacks are applied — the fastest way to find a colour you thought you set and did not.
• Test the install path too. Push the repository and run omarchy theme install <url> on a machine that does not already have it, so you see the theme the way other people will.

Want to try somebody else’s theme without committing to it? Open any theme in this gallery and choose “Try on my computer”. The palette previews for 90 seconds and rolls back on its own unless you keep it.