Palette

A palette is the set of colors selected by [theme]. The theme config chooses the source and mode; the palette provides the actual color values used by bars, panels, widgets, templates, and other theme-aware UI.

Color Roles

User-facing color settings reference these 28 roles with lowercase snake_case names. Prefer role names so UI colors follow the active palette. Fixed hex colors (#RGB, #RGBA, #RRGGBB, #RRGGBBAA) are supported where a deliberately non-palette color is needed.

A palette file sets 16 of these roles directly, keyed by role name. The remaining roles are derived from them, or come straight from the Material scheme when the palette is generated from a wallpaper.

Role	Source	Description
`primary`	palette file	Primary accent for buttons, links, highlights, and active states.
`on_primary`	palette file	Text and icons placed on `primary`.
`primary_container`	derived from `primary`	Lower-emphasis tinted fill in the primary hue.
`on_primary_container`	derived	Text and icons placed on `primary_container`.
`secondary`	palette file	Secondary accent color.
`on_secondary`	palette file	Text and icons placed on `secondary`.
`secondary_container`	derived from `secondary`	Lower-emphasis tinted fill in the secondary hue.
`on_secondary_container`	derived	Text and icons placed on `secondary_container`.
`tertiary`	palette file	Tertiary accent color.
`on_tertiary`	palette file	Text and icons placed on `tertiary`.
`tertiary_container`	derived from `tertiary`	Lower-emphasis tinted fill in the tertiary hue.
`on_tertiary_container`	derived	Text and icons placed on `tertiary_container`.
`error`	palette file	Error and destructive-action color.
`on_error`	palette file	Text and icons placed on `error`.
`error_container`	derived from `error`	Lower-emphasis error fill.
`on_error_container`	derived	Text and icons placed on `error_container`.
`surface`	palette file	Main shell background color.
`on_surface`	palette file	Primary text and icon color on shell surfaces.
`on_surface_variant`	palette file	Secondary text and icon color.
`surface_container_low`	between `surface` and `surface_container`	Slightly raised background.
`surface_container`	palette file	Background for cards, capsules, and controls.
`surface_container_high`	derived from `surface_container`	Raised background, one step above `surface_container`.
`surface_container_highest`	derived from `surface_container`	Highest raised background.
`outline_variant`	palette file	Borders, separators, and subtle outlines.
`shadow`	palette file	Shadow color.
`scrim`	black	Backdrop behind modal content.
`hover`	palette file	Hover and interactive highlight background.
`on_hover`	palette file	Text and icons placed on `hover`.

The former surface_variant and outline roles are now surface_container and outline_variant, with the same colors. Noctalia rewrites them in your config on load and warns about it; update hand-written config files to the new names. The new names need plugin API 43, so plugins using them should declare plugin_api = 43. Plugins still get the old names mapped to the new roles with a log warning until 5.5.0. Templates are unaffected: they keep the full Material token set, where surface_variant and outline have their Material meaning.

Palette Inspector

Open Settings → Appearance → Theme → Palette Inspector → Inspect Colors to browse the active palette’s template colors in a responsive grid. Each card shows a large color swatch, the canonical token name, and its hex value. Use the All Colors, Palette, and Terminal filters to browse related colors, including normal and bright terminal colors. Search by token name or hex value, then use the copy buttons to copy either value.

The 16 normal and bright terminal colors have badges numbered 1-16, alongside their ANSI 0-15 indices. Normal black is 1 · ANSI 0, normal white is 8 · ANSI 7, bright black is 9 · ANSI 8, and bright white is 16 · ANSI 15. Foreground, background, cursor, and selection colors do not have numbered slots.

The inspector follows Theme Mode, which controls generated templates, and updates when the resolved palette changes. If Shell Theme Mode differs from Theme Mode, the preview can differ from the shell’s own colors. The description shows which mode is being inspected. Missing tokens are shown as Unavailable.

Custom Palette Files

When source = "custom", custom_palette names a JSON file in the Noctalia config directory’s palettes/ folder:

[theme]
source         = "custom"
custom_palette = "MyPalette"

With the default config location, that loads:

~/.config/noctalia/palettes/MyPalette.json

The palette JSON format is the same format v4 called a color scheme. For v5, the concept is called a palette, the file lives under palettes/, and it is selected by custom_palette; v4 used colorschemes/.

If you are migrating a v4 color scheme, copy the JSON payload to the v5 palette location:

~/.config/noctalia/colorschemes/MyScheme/MyScheme.json
-> ~/.config/noctalia/palettes/MyScheme.json

Palette JSON

Each palette can provide dark and light variants. If light is omitted, Noctalia uses the dark variant for both modes.

The top-level version names the palette format. The current format is 2, where every key is the name of the color role or terminal color it sets. A file without version is read as format 1, which used m-prefixed camelCase keys (mOnPrimary, terminal selectionFg) and called surface_container and outline_variant mSurfaceVariant and mOutline; older palette files and v4 color schemes keep working unchanged. Noctalia rejects a palette whose version is newer than it supports. noctalia theme --theme-json also accepts its own generated token maps; it treats a file as a palette when it has a version, or, for format 1, when its variants contain mPrimary.

{
  "version": 2,
  "dark": {
    "primary": "#a6e22e",
    "on_primary": "#272822",
    "secondary": "#66d9ef",
    "on_secondary": "#272822",
    "tertiary": "#f92672",
    "on_tertiary": "#272822",
    "error": "#f92672",
    "on_error": "#272822",
    "surface": "#272822",
    "on_surface": "#f8f8f2",
    "surface_container": "#3e3d32",
    "on_surface_variant": "#a6e22e",
    "outline_variant": "#75715e",
    "shadow": "#272822",
    "hover": "#3a3a32",
    "on_hover": "#f8f8f2",
    "terminal": {
      "background": "#272822",
      "foreground": "#f8f8f2",
      "cursor": "#f8f8f2",
      "cursor_text": "#272822",
      "selection_bg": "#f8f8f2",
      "selection_fg": "#272822",
      "normal": {
        "black": "#272822",
        "red": "#f92672",
        "green": "#a6e22e",
        "yellow": "#f4bf75",
        "blue": "#66d9ef",
        "magenta": "#ae81ff",
        "cyan": "#a1efe4",
        "white": "#f8f8f2"
      },
      "bright": {
        "black": "#75715e",
        "red": "#f92672",
        "green": "#a6e22e",
        "yellow": "#f4bf75",
        "blue": "#66d9ef",
        "magenta": "#ae81ff",
        "cyan": "#a1efe4",
        "white": "#f9f8f5"
      }
    }
  },
  "light": {
    "primary": "#a6e22e",
    "on_primary": "#f8f8f2",
    "secondary": "#66d9ef",
    "on_secondary": "#f8f8f2",
    "tertiary": "#f92672",
    "on_tertiary": "#f8f8f2",
    "error": "#f92672",
    "on_error": "#f8f8f2",
    "surface": "#f8f8f2",
    "on_surface": "#272822",
    "surface_container": "#e6e1dc",
    "on_surface_variant": "#272822",
    "outline_variant": "#a6e22e",
    "shadow": "#d8d8d8",
    "hover": "#e6e1dc",
    "on_hover": "#272822",
    "terminal": {
      "background": "#f8f8f2",
      "foreground": "#272822",
      "cursor": "#272822",
      "cursor_text": "#f8f8f2",
      "selection_bg": "#272822",
      "selection_fg": "#f8f8f2",
      "normal": {
        "black": "#f8f8f2",
        "red": "#f92672",
        "green": "#a6e22e",
        "yellow": "#f4bf75",
        "blue": "#66d9ef",
        "magenta": "#ae81ff",
        "cyan": "#a1efe4",
        "white": "#272822"
      },
      "bright": {
        "black": "#d8d8d2",
        "red": "#f92672",
        "green": "#a6e22e",
        "yellow": "#f4bf75",
        "blue": "#66d9ef",
        "magenta": "#ae81ff",
        "cyan": "#a1efe4",
        "white": "#1e1e19"
      }
    }
  }
}

Terminal Colors

The terminal object provides colors for terminal templates:

Field	Description
`background`	Terminal background.
`foreground`	Default text color.
`cursor`	Cursor color.
`cursor_text`	Text under the cursor.
`selection_bg`	Selection background.
`selection_fg`	Selection foreground.
`normal`	Normal ANSI colors.
`bright`	Bright ANSI colors.

Good terminal colors are important for syntax highlighting. Test both dark and light variants with code, prompts, selections, and diffs.

Tips

Start with a few core colors, then map them to roles.
Keep on_* colors readable on their matching surface or accent.
Test both modes; a good dark palette does not automatically make a good light palette.
Use a contrast checker for text-heavy surfaces such as surface / on_surface.