Palette best practices

FIELD NOTE / 01

Contrast first

A theme is a reading surface for eight hours a day. Contrast is not an accessibility checkbox here; it is whether the theme is usable.

• foreground against background: aim for 7:1, treat 4.5:1 as the floor. This is the ratio the Theme Studio enforces on generated palettes.
• dark_foreground against background: at least 4.5:1. Secondary text is still text. Comments below 3:1 are the single most common flaw in community themes.
• accent against background: at least 3:1, and more if the accent ever carries text rather than just a border.
• Every ANSI colour against background: at least 4.5:1. They are syntax highlighting, and a blue that vanishes into a dark background makes code unreadable.
• bright_foreground against selection: at least 4.5:1, because that is the selected-text pairing Omarchy derives.

Measure, do not guess. The Theme Studio reports live ratios for every pair as you edit.

FIELD NOTE / 02

Build the neutral ramp deliberately

The neutral ramp runs from background to bright_foreground. On a dark theme it should read darkest to lightest; on a light theme, lightest to darkest. Seven steps, in this order:

darker_background  →  dark_background  →  background  →  lighter_background
                                        ↓
     dark_foreground  →  foreground  →  light_foreground  →  bright_foreground

• Keep the steps even. A ramp that jumps from one surface to the next and then barely moves looks broken in a card-heavy interface.
• Tint the neutrals. Pure greys next to a saturated accent look dead; carrying a few degrees of the accent’s hue through the ramp is what makes a theme feel designed.
• Do not let lighter_background collide with selection. Both appear behind text, and if they match, selection becomes invisible.
• Leave real distance between background and dark_background. Recessed surfaces that are one or two percent apart read as a rendering artefact.

FIELD NOTE / 03

The sixteen ANSI colours

These are not decoration. They are the terminal, and through it every TUI, diff and syntax highlighter you use.

• Keep the semantics. Red must read as error, green as success, yellow as warning. A green that is actually teal makes git diff lie to you.
• Red and green must be separable for colour-blind users. Differ in lightness as well as hue — do not rely on the hue alone to carry the meaning.
• Make the bright_* variants visibly brighter, not just more saturated. The default derivation mixes 20% toward white; if you write them yourself, at least match that.
• Do not reuse the exact same hex for a colour and its bright variant unless you mean to lose the distinction — some light themes reasonably do, but it flattens bold text in the terminal.
• Check them together, not one at a time. Print a colour table in the terminal and look for two that are hard to tell apart.

FIELD NOTE / 04

Choosing an accent

• Pick one accent and commit. It appears on focused window borders, the active bar element, selected menu rows and links; a second competing accent just reads as noise.
• It usually matches one of your ANSI colours — most bundled themes set accent to the same value as blue or cyan. That is a feature: it keeps the terminal and the desktop consistent.
• It must survive being a thin one-pixel border on a large surface. Very dark or very desaturated accents disappear at that size.
• It must not be so loud that a focused window is uncomfortable to sit in front of. Saturated pure red or pure magenta rarely survive a full day.

FIELD NOTE / 05

Light themes need different thinking

A light theme is not a dark theme with the ends swapped. The most common mistake is taking a dark palette’s ANSI colours unchanged.

• Set mode = "light". Nothing else makes applications pick their light variants reliably.
• Darken and desaturate the ANSI colours. A yellow that is legible on #1a1b26 is invisible on #fffcf0; bundled light themes routinely drop lightness by a third.
• The bright_* colours often cannot be brighter, because brighter means closer to the background. Look at flexoki-light, which sets several of them identical to their base colour and brightens only where it helps.
• Remember that Omarchy’s automatic derivation mixes toward black for dark_background and toward white for the bright colours. Neither rule is right for a light theme, so write those keys explicitly.
• Avoid a pure white background. An off-white such as #fffcf0 or #faf4ed is markedly easier to read for a full day.