4.12 Option for palette overrides

This section describes palette overrides in detail. For a simpler alternative, use the presets we provide (Palette override presets).

Each Modus theme specifies a color palette that declares named color values and semantic color mappings:

• Named colors consist of a symbol and a string that specifies a hexadecimal RGB value. For example: ‘(blue-warmer "#354fcf")’.
• The semantic color mappings associate an abstract construct with a given named color from the palette, like ‘(heading-2 yellow-faint)’. Both elements of the list are symbols, though the cadr (value) can be a string that specifies a color, such as ‘(heading-2 "#354fcf")’.

Both of those subsets can be overridden, thus refashioning the theme. Overrides are either shared, by being stored in the user option modus-themes-common-palette-overrides, or they are specific to the theme they name. In the latter case, the naming scheme of each palette variable is ‘THEME-NAME-palette-overrides’, thus yielding:

• modus-operandi-palette-overrides

• modus-operandi-deuteranopia-palette-overrides

• modus-operandi-tinted-palette-overrides

• modus-operandi-tritanopia-palette-overrides

• modus-vivendi-palette-overrides

• modus-vivendi-deuteranopia-palette-overrides

• modus-vivendi-tinted-palette-overrides

• modus-vivendi-tritanopia-palette-overrides

Theme-specific overrides take precedence over the shared ones. It is strongly advised that shared overrides do NOT alter color values, as those will not be appropriate for both dark and light themes. Common overrides are best limited to the semantic color mappings as those use the color value that corresponds to the active theme (e.g. make the cursor ‘blue-warmer’ in all themes, whatever the value of ‘blue-warmer’ is in each theme).

The value of any overrides’ variable must mirror a theme’s palette. Palette variables are named after their theme as ‘THEME-NAME-palette’. For example, the modus-operandi-palette is like this:

(defconst modus-operandi-palette
    '(
;;; Basic values

      (bg-main     "#ffffff")
      (bg-dim      "#f0f0f0")
      (fg-main     "#000000")

      ;; ...

      (red         "#a60000")
      (red-warmer  "#972500")
      (red-cooler  "#a0132f")
      (red-faint   "#7f0000")
      (red-intense "#d00000")

      ;; ...

;;;; Mappings

      ;; ...

      (cursor fg-main)
      (builtin magenta-warmer)
      (comment fg-dim)
      (constant blue-cooler)
      (docstring green-faint)
      (fnname magenta)
      (keyword magenta-cooler)

      ;; ...
      ))

The modus-operandi-palette-overrides targets the entries that need to be changed. For example, to make the main foreground color a dark gray instead of pure black, use a shade of red for comments, and apply a cyan hue to keywords:

(setq modus-operandi-palette-overrides
      '((fg-main "#333333")
        (comment red-faint)
        (keyword cyan-cooler)))

Changes take effect upon theme reload (Option for reloading the theme on custom change). Overrides are removed by setting their variable to a nil value.

The common accented foregrounds in each palette follow a predictable naming scheme: ‘HUE{,-warmer,-cooler,-faint,-intense}’. ‘HUE’ is one of the six basic colors: red, green, blue, yellow, magenta, cyan.

Named colors that are meant to be used as backgrounds contain ‘bg’ in their name, such as ‘bg-red-intense’. While special purpose foregrounds that are meant to be combined with such backgrounds, contain ‘fg’ in their name, such as ‘fg-removed’ which complements ‘bg-removed’.

Named colors can be previewed, such as with the command modus-themes-list-colors (Preview theme colors).

For a video tutorial that users of all skill levels can approach, watch: https://protesilaos.com/codelog/2022-12-17-modus-themes-v4-demo/.