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 16 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.

Role	Palette field	Description
`primary`	`mPrimary`	Primary accent for buttons, links, highlights, and active states.
`on_primary`	`mOnPrimary`	Text and icons placed on primary surfaces.
`secondary`	`mSecondary`	Secondary accent color.
`on_secondary`	`mOnSecondary`	Text and icons placed on secondary surfaces.
`tertiary`	`mTertiary`	Tertiary accent color.
`on_tertiary`	`mOnTertiary`	Text and icons placed on tertiary surfaces.
`error`	`mError`	Error and destructive-action color.
`on_error`	`mOnError`	Text and icons placed on error surfaces.
`surface`	`mSurface`	Main shell background color.
`on_surface`	`mOnSurface`	Primary text and icon color on shell surfaces.
`surface_variant`	`mSurfaceVariant`	Secondary background for cards, panels, and lower-emphasis surfaces.
`on_surface_variant`	`mOnSurfaceVariant`	Secondary text and icon color on variant surfaces.
`outline`	`mOutline`	Borders, separators, and subtle outlines.
`shadow`	`mShadow`	Shadow color.
`hover`	`mHover`	Hover and interactive highlight background.
`on_hover`	`mOnHover`	Text and icons placed on hover surfaces.

Settings role pickers expose these role names first. Template files access the same colors through the Template Reference.

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.