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 defines 16 colors (the m… fields). 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	mPrimary	Primary accent for buttons, links, highlights, and active states.
on_primary	mOnPrimary	Text and icons placed on primary.
primary_container	derived from mPrimary	Lower-emphasis tinted fill in the primary hue.
on_primary_container	derived	Text and icons placed on primary_container.
secondary	mSecondary	Secondary accent color.
on_secondary	mOnSecondary	Text and icons placed on secondary.
secondary_container	derived from mSecondary	Lower-emphasis tinted fill in the secondary hue.
on_secondary_container	derived	Text and icons placed on secondary_container.
tertiary	mTertiary	Tertiary accent color.
on_tertiary	mOnTertiary	Text and icons placed on tertiary.
tertiary_container	derived from mTertiary	Lower-emphasis tinted fill in the tertiary hue.
on_tertiary_container	derived	Text and icons placed on tertiary_container.
error	mError	Error and destructive-action color.
on_error	mOnError	Text and icons placed on error.
error_container	derived from mError	Lower-emphasis error fill.
on_error_container	derived	Text and icons placed on error_container.
surface	mSurface	Main shell background color.
on_surface	mOnSurface	Primary text and icon color on shell surfaces.
on_surface_variant	mOnSurfaceVariant	Secondary text and icon color.
surface_container_low	between mSurface and mSurfaceVariant	Slightly raised background.
surface_container	mSurfaceVariant	Background for cards, capsules, and controls.
surface_container_high	derived from mSurfaceVariant	Raised background, one step above surface_container.
surface_container_highest	derived from mSurfaceVariant	Highest raised background.
outline_variant	mOutline	Borders, separators, and subtle outlines.
shadow	mShadow	Shadow color.
scrim	black	Backdrop behind modal content.
hover	mHover	Hover and interactive highlight background.
on_hover	mOnHover	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.

{
  "dark": {
    "mPrimary": "#a6e22e",
    "mOnPrimary": "#272822",
    "mSecondary": "#66d9ef",
    "mOnSecondary": "#272822",
    "mTertiary": "#f92672",
    "mOnTertiary": "#272822",
    "mError": "#f92672",
    "mOnError": "#272822",
    "mSurface": "#272822",
    "mOnSurface": "#f8f8f2",
    "mSurfaceVariant": "#3e3d32",
    "mOnSurfaceVariant": "#a6e22e",
    "mOutline": "#75715e",
    "mShadow": "#272822",
    "mHover": "#3a3a32",
    "mOnHover": "#f8f8f2",
    "terminal": {
      "background": "#272822",
      "foreground": "#f8f8f2",
      "cursor": "#f8f8f2",
      "cursorText": "#272822",
      "selectionBg": "#f8f8f2",
      "selectionFg": "#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": {
    "mPrimary": "#a6e22e",
    "mOnPrimary": "#f8f8f2",
    "mSecondary": "#66d9ef",
    "mOnSecondary": "#f8f8f2",
    "mTertiary": "#f92672",
    "mOnTertiary": "#f8f8f2",
    "mError": "#f92672",
    "mOnError": "#f8f8f2",
    "mSurface": "#f8f8f2",
    "mOnSurface": "#272822",
    "mSurfaceVariant": "#e6e1dc",
    "mOnSurfaceVariant": "#272822",
    "mOutline": "#a6e22e",
    "mShadow": "#d8d8d8",
    "mHover": "#e6e1dc",
    "mOnHover": "#272822",
    "terminal": {
      "background": "#f8f8f2",
      "foreground": "#272822",
      "cursor": "#272822",
      "cursorText": "#f8f8f2",
      "selectionBg": "#272822",
      "selectionFg": "#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.
cursorText	Text under the cursor.
selectionBg	Selection background.
selectionFg	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.