*note Sample configuration with and without use-package::.
* Menu:
* The require-theme for built-in Emacs themes::
* Sample configuration with and without use-package::
* Differences between loading and enabling::
File: modus-themes.info, Node: The require-theme for built-in Emacs themes, Next: Sample configuration with and without use-package, Up: Enable and load
3.1 The ‘require-theme’ for built-in Emacs themes
=================================================
The version of the Modus themes that is included in Emacs CANNOT use the
standard ‘require’. This is because the built-in themes are not
included in the ‘load-path’ (not my decision). The ‘require-theme’
function must be used in this case as a replacement. For example:
(require-theme 'modus-themes)
;; All customizations here
(setq modus-themes-bold-constructs t
modus-themes-italic-constructs t)
;; Maybe define some palette overrides, such as by using our presets
(setq modus-themes-common-palette-overrides
modus-themes-preset-overrides-intense)
;; Load the theme of choice (built-in themes are always "safe" so they
;; do not need the `no-require' argument of `load-theme').
File: modus-themes.info, Node: Sample configuration with and without use-package, Next: Differences between loading and enabling, Prev: The require-theme for built-in Emacs themes, Up: Enable and load
3.2 Sample configuration with and without use-package
File: modus-themes.info, Node: Make the active mode line colorful, Next: Make the tab bar more or less colorful, Prev: Make the mode line borderless, Up: Stylistic variants using palette overrides
5.2.2 Make the active mode line colorful
----------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
Here we show some snippets that apply different stylistic variants. Of
course, it is possible to use theme-specific overrides to, say, have a
blue mode line for ‘modus-operandi’ and a red one for ‘modus-vivendi’.
*note Make the mode line borderless::.
*note Add padding to mode line::.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Blue background, neutral foreground, intense blue border
(setq modus-themes-common-palette-overrides
'((bg-mode-line-active bg-blue-intense)
(fg-mode-line-active fg-main)
(border-mode-line-active blue-intense)))
;; Subtle blue background, neutral foreground, intense blue border
(setq modus-themes-common-palette-overrides
'((bg-mode-line-active bg-blue-subtle)
(fg-mode-line-active fg-main)
(border-mode-line-active blue-intense)))
;; Subtle red background, red foreground, invisible border
(setq modus-themes-common-palette-overrides
'((bg-mode-line-active bg-red-subtle)
(fg-mode-line-active red-warmer)
(border-mode-line-active bg-red-subtle)))
File: modus-themes.info, Node: Make the tab bar more or less colorful, Next: Make the fringe invisible or another color, Prev: Make the active mode line colorful, Up: Stylistic variants using palette overrides
5.2.3 Make the tab bar more or less colorful
--------------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
Here we show how to affect the colors of the built-in ‘tab-bar-mode’ and
‘tab-line-mode’.
For consistent theme-wide results, consider changing the mode line,
fringes, and line numbers. These are shown in other sections of this
manual.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Make the `tab-bar-mode' mode subtle while keepings its original
;; gray aesthetic.
(setq modus-themes-common-palette-overrides
'((bg-tab-bar bg-main)
(bg-tab-current bg-active)
(bg-tab-other bg-dim)))
;; Like the above, but the current tab has a colorful background and
;; the inactive tabs have a slightly more noticeable gray background.
(setq modus-themes-common-palette-overrides
'((bg-tab-bar bg-main)
(bg-tab-current bg-cyan-intense)
(bg-tab-other bg-inactive)))
;; Make the tabs colorful, using a monochromatic pattern (e.g. shades
;; of cyan).
(setq modus-themes-common-palette-overrides
'((bg-tab-bar bg-cyan-nuanced)
(bg-tab-current bg-cyan-intense)
(bg-tab-other bg-cyan-subtle)))
;; Like the above, but with a dichromatic pattern (cyan and magenta).
(setq modus-themes-common-palette-overrides
'((bg-tab-bar bg-cyan-nuanced)
(bg-tab-current bg-magenta-intense)
(bg-tab-other bg-cyan-subtle)))
File: modus-themes.info, Node: Make the fringe invisible or another color, Next: Make links use subtle or no underlines, Prev: Make the tab bar more or less colorful, Up: Stylistic variants using palette overrides
5.2.4 Make the fringe invisible or another color
------------------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
Here we show how to make the fringe invisible or how to assign to it a
different color. The “fringe” is a small area to the right and left
side of the Emacs window which shows indicators such as for truncation
or continuation lines.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Make the fringe invisible
(setq modus-themes-common-palette-overrides
'((fringe unspecified)))
;; Make the fringe more intense
(setq modus-themes-common-palette-overrides
'((fringe bg-active)))
;; Make the fringe colorful, but nuanced
(setq modus-themes-common-palette-overrides
'((fringe bg-blue-nuanced)))
File: modus-themes.info, Node: Make links use subtle or no underlines, Next: Make prompts more or less colorful, Prev: Make the fringe invisible or another color, Up: Stylistic variants using palette overrides
5.2.5 Make links use subtle or no underlines
--------------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
In this example, we showcase the special use of the ‘unspecified’ symbol
that underline mappings can read correctly.
;; Subtle underlines
(setq modus-themes-common-palette-overrides
'((underline-link border)
(underline-link-visited border)
(underline-link-symbolic border)))
;; No underlines
(setq modus-themes-common-palette-overrides
'((underline-link unspecified)
(underline-link-visited unspecified)
(underline-link-symbolic unspecified)))
File: modus-themes.info, Node: Make prompts more or less colorful, Next: Make completion matches more or less colorful, Prev: Make links use subtle or no underlines, Up: Stylistic variants using palette overrides
5.2.6 Make prompts more or less colorful
----------------------------------------
This section contains practical examples of overriding the palette of
the themes (*note Option for palette overrides: Palette overrides.). In
the following code block we show how to add or remove color from
prompts.
*note Option for command prompt styles: Command prompts.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Keep the background unspecified (like the default), but use a faint
;; foreground color.
(setq modus-themes-common-palette-overrides
'((fg-prompt cyan-faint)
(bg-prompt unspecified)))
;; Add a nuanced background to prompts that complements their foreground.
(setq modus-themes-common-palette-overrides
'((fg-prompt cyan)
(bg-prompt bg-cyan-nuanced)))
;; Add a yellow background and adjust the foreground accordingly.
(setq modus-themes-common-palette-overrides
'((fg-prompt fg-main)
(bg-prompt bg-yellow-subtle))) ; try to replace "subtle" with "intense"
File: modus-themes.info, Node: Make completion matches more or less colorful, Next: Make comments yellow and strings green, Prev: Make prompts more or less colorful, Up: Stylistic variants using palette overrides
5.2.7 Make completion matches more or less colorful
This section contains practical examples of overriding the palette of
the themes (*note Option for palette overrides: Palette overrides.).
Here we demonstrate how to activate background coloration for completion
matches. We show three different degrees of intensity.
*note Option for completion framework aesthetics: Completion UIs.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Add a nuanced background color to completion matches, while keeping
;; their foreground intact (foregrounds do not need to be specified in
;; this case, but we do it for didactic purposes).
(setq modus-themes-common-palette-overrides
'((fg-completion-match-0 blue)
(fg-completion-match-1 magenta-warmer)
(fg-completion-match-2 cyan)
(fg-completion-match-3 red)
(bg-completion-match-0 bg-blue-nuanced)
(bg-completion-match-1 bg-magenta-nuanced)
(bg-completion-match-2 bg-cyan-nuanced)
(bg-completion-match-3 bg-red-nuanced)))
;; Add intense background colors to completion matches and adjust the
;; foregrounds accordingly.
(setq modus-themes-common-palette-overrides
'((fg-completion-match-0 fg-main)
(fg-completion-match-1 fg-main)
(fg-completion-match-2 fg-main)
(fg-completion-match-3 fg-main)
(bg-completion-match-0 bg-blue-intense)
(bg-completion-match-1 bg-yellow-intense)
(bg-completion-match-2 bg-cyan-intense)
(bg-completion-match-3 bg-red-intense)))
;; Like the above, but with subtle backgrounds.
(setq modus-themes-common-palette-overrides
'((fg-completion-match-0 fg-main)
(fg-completion-match-1 fg-main)
(fg-completion-match-2 fg-main)
(fg-completion-match-3 fg-main)
(bg-completion-match-0 bg-blue-subtle)
(bg-completion-match-1 bg-yellow-subtle)
(bg-completion-match-2 bg-cyan-subtle)
(bg-completion-match-3 bg-red-subtle)))
Adding to the above, it is possible to, say, reduce the number of
colors to two:
;; No backgrounds (like the default) and just use two colors.
(setq modus-themes-common-palette-overrides
'((fg-completion-match-0 blue)
(fg-completion-match-1 yellow)
(fg-completion-match-2 blue)
(fg-completion-match-3 yellow)
(bg-completion-match-0 unspecified)
(bg-completion-match-1 unspecified)
(bg-completion-match-2 unspecified)
(bg-completion-match-3 unspecified)))
;; Again, a two-color style but this time with backgrounds
(setq modus-themes-common-palette-overrides
'((fg-completion-match-0 blue)
(fg-completion-match-1 yellow)
(fg-completion-match-2 blue)
(fg-completion-match-3 yellow)
(bg-completion-match-0 bg-blue-nuanced)
(bg-completion-match-1 bg-yellow-nuanced)
(bg-completion-match-2 bg-blue-nuanced)
(bg-completion-match-3 bg-yellow-nuanced)))
The user can mix and match to their liking.
File: modus-themes.info, Node: Make comments yellow and strings green, Next: Make code syntax use the old alt-syntax style, Prev: Make completion matches more or less colorful, Up: Stylistic variants using palette overrides
5.2.8 Make comments yellow and strings green
--------------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
In previous versions of the themes, we provided an option for yellow-ish
comments and green-ish strings. For some users, those were still not
good enough, as the exact values were hardcoded. Here we show how to
reproduce the effect, but also how to tweak it to one’s liking.
*note Make code syntax use the old alt-syntax style::.
*note Make use of alternative styles for code syntax::.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Yellow comments and green strings like older versions of the Modus
;; themes
(setq modus-themes-common-palette-overrides
'((comment yellow-cooler)
(string green-cooler)))
;; Faint yellow comments and a different shade of green for strings
(setq modus-themes-common-palette-overrides
'((comment yellow-faint)
(string green-warmer)))
;; Green comments and yellow strings, because now the user has the
;; freedom to do it
(setq modus-themes-common-palette-overrides
'((comment green)
(string yellow-cooler)))
File: modus-themes.info, Node: Make code syntax use the old alt-syntax style, Next: Make use of alternative styles for code syntax, Prev: Make comments yellow and strings green, Up: Stylistic variants using palette overrides
5.2.9 Make code syntax use the old alt-syntax style
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
In this section we show how to reproduce what previous versions of the
Modus themes provided as a stylistic alternative for code syntax. The
upside of using overrides for this purpose is that we can tweak the
style to our liking, but first let’s start with its recreation:
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; The old "alt-syntax"
(setq modus-themes-common-palette-overrides
'((builtin magenta)
(comment fg-dim)
(constant magenta-cooler)
(docstring magenta-faint)
(docmarkup green-faint)
(fnname magenta-warmer)
(keyword cyan)
(preprocessor cyan-cooler)
(string red-cooler)
(type magenta-cooler)
(variable blue-warmer)
(rx-construct magenta-warmer)
(rx-backslash blue-cooler)))
The “alt-syntax” could optionally use green strings and yellow
comments (*note Make comments yellow and strings green::):
;; Same as above, but with yellow comments and green strings
(setq modus-themes-common-palette-overrides
'((builtin magenta)
(comment yellow-faint)
(constant magenta-cooler)
(docstring green-faint)
(docmarkup magenta-faint)
(fnname magenta-warmer)
(keyword cyan)
(preprocessor cyan-cooler)
(string green-cooler)
(type magenta-cooler)
(variable blue-warmer)
(rx-construct magenta-warmer)
(rx-backslash blue-cooler)))
The standard “alt-syntax” has red strings. As such, it is
interesting to experiment with faintly red colored comments:
;; Like the old "alt-syntax" but with faint red comments
(setq modus-themes-common-palette-overrides
'((builtin magenta)
(comment red-faint)
(constant magenta-cooler)
(docstring magenta-faint)
(docmarkup green-faint)
(fnname magenta-warmer)
(keyword cyan)
(preprocessor cyan-cooler)
(string red-cooler)
(type magenta-cooler)
(variable blue-warmer)
(rx-construct magenta-warmer)
(rx-backslash blue-cooler)))
The user can always mix and match styles to their liking.
*note Make use of alternative styles for code syntax::.
File: modus-themes.info, Node: Make use of alternative styles for code syntax, Next: Make matching parenthesis more or less intense, Prev: Make code syntax use the old alt-syntax style, Up: Stylistic variants using palette overrides
5.2.10 Make use of alternative styles for code syntax
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
The idea here is to change how named colors are mapped to code syntax.
Each of the following snippets give the ‘modus-themes’ a different feel
while editing code.
Note that my ‘modus-themes’ and ‘ef-themes’ do not use the same
palettes, so some things are different. If you copy from the latter to
the former, double-check that the entries exist in the given Modus theme
palette.
*note Make comments yellow and strings green::.
*note Make code syntax use the old alt-syntax style::.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Mimic `ef-night' theme (from my `ef-themes') for code syntax
;; highlighting, while still using the Modus colors (and other
;; mappings).
(setq modus-themes-common-palette-overrides
'((builtin green-cooler)
(comment yellow-faint)
(constant magenta-cooler)
(fnname cyan-cooler)
(keyword blue-warmer)
(preprocessor red-warmer)
(docstring cyan-faint)
(string blue-cooler)
(type magenta-cooler)
(variable cyan)))
;; Mimic `ef-summer' theme (from my `ef-themes') for code syntax
;; highlighting, while still using the Modus colors (and other
;; mappings).
(setq modus-themes-common-palette-overrides
'((builtin magenta)
(comment yellow-faint)
(constant red-cooler)
(fnname magenta-warmer)
(keyword magenta-cooler)
(preprocessor green-warmer)
(docstring cyan-faint)
(string yellow-warmer)
(type cyan-warmer)
(variable blue-warmer)))
;; Mimic `ef-bio' theme (from my `ef-themes') for code syntax
;; highlighting, while still using the Modus colors (and other
;; mappings).
(setq modus-themes-common-palette-overrides
'((builtin green)
(comment yellow-faint)
(constant blue)
(fnname green-warmer)
(keyword green-cooler)
(preprocessor green)
(docstring green-faint)
(string magenta-cooler)
(type cyan-warmer)
(variable blue-warmer)))
;; Mimic `ef-trio-light' theme (from my `ef-themes') for code syntax
;; highlighting, while still using the Modus colors (and other
;; mappings).
(setq modus-themes-common-palette-overrides
'((builtin magenta-cooler)
(comment yellow-faint)
(constant magenta-warmer)
(fnname blue-warmer)
(keyword magenta)
(preprocessor red-cooler)
(docstring magenta-faint)
(string green-cooler)
(type cyan-cooler)
(variable cyan-warmer)))
File: modus-themes.info, Node: Make matching parenthesis more or less intense, Next: Make box buttons more or less gray, Prev: Make use of alternative styles for code syntax, Up: Stylistic variants using palette overrides
5.2.11 Make matching parenthesis more or less intense
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
In this code block we show how to change the background of matching
delimiters when ‘show-paren-mode’ is enabled. We also demonstrate how
to enable underlines for those highlights.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Change the background to a shade of magenta
(setq modus-themes-common-palette-overrides
'((bg-paren-match bg-magenta-intense)))
;; Enable underlines by applying a color to them
(setq modus-themes-common-palette-overrides
'((bg-paren-match bg-magenta-intense)
(underline-paren-match fg-main)))
File: modus-themes.info, Node: Make box buttons more or less gray, Next: Make TODO and DONE more or less intense, Prev: Make matching parenthesis more or less intense, Up: Stylistic variants using palette overrides
5.2.12 Make box buttons more or less gray
-----------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
By default, the boxed buttons that appear in ‘M-x customize’ and related
are distinct shades of gray. The following set of overrides removes the
gray from the active buttons and amplifies it for the inactive ones.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
(setq modus-themes-common-palette-overrides
'((bg-button-active bg-main)
(fg-button-active fg-main)
(bg-button-inactive bg-inactive)
(fg-button-inactive "gray50")))
File: modus-themes.info, Node: Make TODO and DONE more or less intense, Next: Make headings more or less colorful, Prev: Make box buttons more or less gray, Up: Stylistic variants using palette overrides
5.2.13 Make TODO and DONE more or less intense
----------------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
Here we show how to affect just the ‘TODO’ and ‘DONE’ keywords that we
encounter in Org buffers. The idea is to make those pop out more or to
subdue them.
*note Make headings more or less colorful::.
*note Make inline code in prose use alternative styles::.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Increase intensity
(setq modus-themes-common-palette-overrides
'((prose-done green-intense)
(prose-todo red-intense)))
;; Tone down intensity
(setq modus-themes-common-palette-overrides
'((prose-done green-faint) ; OR replace `green-faint' with `olive'
(prose-todo red-faint))) ; OR replace `red-faint' with `rust'
;; Keep TODO at its default (so no override for it), but make DONE
;; gray.
(setq modus-themes-common-palette-overrides
'((prose-done fg-dim)))
File: modus-themes.info, Node: Make headings more or less colorful, Next: Make Org agenda more or less colorful, Prev: Make TODO and DONE more or less intense, Up: Stylistic variants using palette overrides
5.2.14 Make headings more or less colorful
------------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
Here we show how to alter the looks of headings, such as in Org mode.
Using overrides here offers far more flexibility than what we could
achieve with previous versions of the themes: the user can mix and match
styles at will.
*note Make TODO and DONE more intense: Make TODO and DONE more or
less intense.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Apply more colorful foreground to some headings (headings 0-8).
;; Level 0 is for Org #+title and related.
(setq modus-themes-common-palette-overrides
'((fg-heading-1 blue-warmer)
(fg-heading-2 yellow-cooler)
(fg-heading-3 cyan-cooler)))
;; Like the above, but with gradient colors
(setq modus-themes-common-palette-overrides
'((fg-heading-1 blue)
(fg-heading-2 cyan)
(fg-heading-3 green)))
;; Add color to level 1 heading, but use the main foreground for
;; others
(setq modus-themes-common-palette-overrides
'((fg-heading-1 blue)
(fg-heading-2 fg-main)
(fg-heading-3 fg-main)))
;; Apply colorful foreground, background, and overline (headings 0-8)
(setq modus-themes-common-palette-overrides
'((fg-heading-1 blue-warmer)
(bg-heading-1 bg-blue-nuanced)
(overline-heading-1 blue)))
;; Apply gray scale foreground, background, and overline (headings 0-8)
(setq modus-themes-common-palette-overrides
'((fg-heading-1 fg-main)
(bg-heading-1 bg-dim)
(overline-heading-1 border)))
File: modus-themes.info, Node: Make Org agenda more or less colorful, Next: Make inline code in prose use alternative styles, Prev: Make headings more or less colorful, Up: Stylistic variants using palette overrides
5.2.15 Make Org agenda more or less colorful
--------------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
Here we provide three distinct code blocks. The first adds alternative
and more varied colors to the Org agenda (and related). The second uses
faint coloration. The third makes the agenda use various shades of
blue. Mix and match at will, while also combining these styles with
what we show in the other chapters with practical stylistic variants.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Make the Org agenda use alternative and varied colors.
(setq modus-themes-common-palette-overrides
'((date-common cyan) ; default value (for timestamps and more)
(date-deadline red-warmer)
(date-event magenta-warmer)
(date-holiday blue) ; for M-x calendar
(date-now yellow-warmer)
(date-scheduled magenta-cooler)
(date-weekday cyan-cooler)
(date-weekend blue-faint)))
An example with faint coloration:
;; Make the Org agenda use faint colors.
(setq modus-themes-common-palette-overrides
'((date-common cyan-faint) ; for timestamps and more
;; Make the Org agenda use more blue instead of yellow and red.
(setq modus-themes-common-palette-overrides
'((date-common cyan) ; default value (for timestamps and more)
(date-deadline blue-cooler)
(date-event blue-faint)
(date-holiday blue) ; for M-x calendar
(date-now blue-faint)
(date-scheduled blue)
(date-weekday fg-main)
(date-weekend fg-dim)))
Yet another example that also affects ‘DONE’ and ‘TODO’ keywords:
;; Change dates to a set of more subtle combinations. Deadlines are a
;; shade of magenta, scheduled dates are a shade of green that
;; complements that of the deadlines, weekday headings use the main
;; foreground color while weekends are a shade of gray. The DONE
;; keyword is a faint blue-gray while TODO is yellow.
(setq modus-themes-common-palette-overrides
'((date-deadline magenta-warmer)
(date-scheduled green-cooler)
(date-weekday fg-main)
(date-event fg-dim)
(date-now blue)
(prose-done fg-alt)
(prose-todo yellow)))
File: modus-themes.info, Node: Make inline code in prose use alternative styles, Next: Make mail citations and headers more or less colorful, Prev: Make Org agenda more or less colorful, Up: Stylistic variants using palette overrides
5.2.16 Make inline code in prose use alternative styles
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
In the following code block we show how to affect constructs such as
Org’s verbatim, code, and macro entries. We also provide mappings for
tables, property drawers, tags, and code block delimiters, though we do
not show every possible permutation.
*note Make TODO and DONE more or less intense::.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; These are all the mappings at their default values for didactic
;; purposes
(setq modus-themes-common-palette-overrides
'((prose-block fg-dim)
(prose-code green-cooler)
(prose-done green)
(prose-macro magenta-cooler)
(prose-metadata fg-dim)
(prose-metadata-value fg-alt)
(prose-table fg-alt)
(prose-tag magenta-faint)
(prose-todo red)
(prose-verbatim magenta-warmer)))
;; Make code block delimiters use a shade of red, tone down verbatim,
;; code, and macro, and amplify the style of property drawers
(setq modus-themes-common-palette-overrides
'((prose-block red-faint)
(prose-code fg-dim)
(prose-macro magenta-faint)
(prose-metadata cyan)
(prose-metadata-value green-warmer)
(prose-verbatim fg-dim)))
;; Like the above but with more color variety for the inline code
;; elements
(setq modus-themes-common-palette-overrides
'((prose-block red-faint)
(prose-code blue-cooler)
(prose-macro yellow-warmer)
(prose-metadata cyan)
(prose-metadata-value green-warmer)
(prose-verbatim red-warmer)))
File: modus-themes.info, Node: Make mail citations and headers more or less colorful, Next: Make the region preserve text colors plus other styles, Prev: Make inline code in prose use alternative styles, Up: Stylistic variants using palette overrides
5.2.17 Make mail citations and headers more or less colorful
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
In this section we show how to change the coloration of email message
headers and citations. Before we show the code, this is the anatomy of
a message:
From: Protesilaos <info@protesilaos.com>
To: Modus-Themes Development <~protesilaos/modus-themes@lists.sr.ht>
Subject: Test subject
--- Headers above this line; message and citations below ---
This is some sample text
> > Older quote
> Newer quote
We thus have the following:
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Reduce the intensity of mail citations and headers
(setq modus-themes-common-palette-overrides
'((mail-cite-0 cyan-faint)
(mail-cite-1 yellow-faint)
(mail-cite-2 green-faint)
(mail-cite-3 red-faint)
(mail-part olive)
(mail-recipient indigo)
(mail-subject maroon)
(mail-other slate)))
;; Make mail citations more intense; adjust the headers accordingly
(setq modus-themes-common-palette-overrides
'((mail-cite-0 blue)
(mail-cite-1 yellow)
(mail-cite-2 green)
(mail-cite-3 magenta)
(mail-part magenta-cooler)
(mail-recipient cyan)
(mail-subject red-warmer)
(mail-other cyan-cooler)))
;; Make all citations faint and neutral; make most headers green but
;; use red for the subject lie so that it stands out
(setq modus-themes-common-palette-overrides
'((mail-cite-0 fg-dim)
(mail-cite-1 fg-alt)
(mail-cite-2 fg-dim)
(mail-cite-3 fg-alt)
(mail-part yellow-cooler)
(mail-recipient green-cooler)
(mail-subject red-cooler)
(mail-other green)))
File: modus-themes.info, Node: Make the region preserve text colors plus other styles, Next: Make mouse highlights more or less colorful, Prev: Make mail citations and headers more or less colorful, Up: Stylistic variants using palette overrides
5.2.18 Make the region preserve text colors, plus other styles
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
Here we show how to make the region respect the underlying text colors
or how to make the background more/less intense while combining it with
an appropriate foreground value.
*note Do not extend the region background::.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; A background with no specific foreground (use foreground of
;; underlying text)
(setq modus-themes-common-palette-overrides
'((bg-region bg-ochre) ; try to replace `bg-ochre' with `bg-lavender', `bg-sage'
(fg-region unspecified)))
;; Subtle gray with a prominent blue foreground
(setq modus-themes-common-palette-overrides
'((bg-region bg-dim)
(fg-region blue-cooler)))
;; Intense magenta background combined with the main foreground
(setq modus-themes-common-palette-overrides
'((bg-region bg-magenta-intense)
(fg-region fg-main)))
File: modus-themes.info, Node: Make mouse highlights more or less colorful, Next: Make language underlines less colorful, Prev: Make the region preserve text colors plus other styles, Up: Stylistic variants using palette overrides
5.2.19 Make mouse highlights more or less colorful
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
In the following code block we show how to affect the semantic color
mapping that covers mouse hover effects and related highlights:
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Make the background an intense yellow
(setq modus-themes-common-palette-overrides
'((bg-hover bg-yellow-intense)))
;; Make the background subtle green
(setq modus-themes-common-palette-overrides
'((bg-hover bg-green-subtle)))
File: modus-themes.info, Node: Make language underlines less colorful, Next: Make line numbers use alternative styles, Prev: Make mouse highlights more or less colorful, Up: Stylistic variants using palette overrides
5.2.20 Make language underlines less colorful
---------------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
Here we show how to affect the color of the underlines that are used by
code linters and prose spell checkers.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Make the underlines less intense
(setq modus-themes-common-palette-overrides
'((underline-err red-faint)
(underline-warning yellow-faint)
(underline-note cyan-faint)))
;; Change the color-coding of the underlines
(setq modus-themes-common-palette-overrides
'((underline-err yellow-intense)
(underline-warning magenta-intense)
(underline-note green-intense)))
File: modus-themes.info, Node: Make line numbers use alternative styles, Next: Make diffs use only a foreground, Prev: Make language underlines less colorful, Up: Stylistic variants using palette overrides
5.2.21 Make line numbers use alternative styles
-----------------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
In this section we show how to affect the ‘display-line-numbers-mode’.
;; These overrides are common to all Modus themes. We also provide
;; theme-specific options, such as `modus-operandi-palette-overrides'.
;;
;; In general, the theme-specific overrides are better for overriding
;; color values, such as redefining what `blue-faint' looks like. The
;; common overrides are best used for changes to semantic color
;; mappings, as we show below.
;; Make line numbers less intense
(setq modus-themes-common-palette-overrides
'((fg-line-number-inactive "gray50")
(fg-line-number-active fg-main)
(bg-line-number-inactive unspecified)
(bg-line-number-active unspecified)))
;; Like the above, but use a shade of red for the current line number
(setq modus-themes-common-palette-overrides
'((fg-line-number-inactive "gray50")
(fg-line-number-active red-cooler)
(bg-line-number-inactive unspecified)
(bg-line-number-active unspecified)))
;; Make all numbers more intense, use a more pronounce gray
;; background, and make the current line have a colored background
(setq modus-themes-common-palette-overrides
'((fg-line-number-inactive fg-main)
(fg-line-number-active fg-main)
(bg-line-number-inactive bg-inactive)
(bg-line-number-active bg-cyan-intense)))
File: modus-themes.info, Node: Make diffs use only a foreground, Next: Make deuteranopia diffs red and blue instead of yellow and blue, Prev: Make line numbers use alternative styles, Up: Stylistic variants using palette overrides
5.2.22 Make diffs use only a foreground
---------------------------------------
This is one of our practical examples to override the semantic colors of
the Modus themes (*note Stylistic variants using palette overrides::).
In this section we show how to change diff buffers (e.g. in ‘magit’) to
only use color-coded text without any added background. What we
basically do is to disable the applicable backgrounds and then intensify
the foregrounds. Since the deuteranopia-optimized themes do not use the
red-green color coding, we make an extra set of adjustments for them by
overriding their palettes directly instead of just using the “common”
overrides.
;; Diffs with only foreground colors. Word-wise ("refined") diffs
;; have a gray background to draw attention to themselves.
(setq modus-themes-common-palette-overrides
'((bg-added unspecified)
(bg-added-faint unspecified)
(bg-added-refine bg-inactive)
(fg-added green)
(fg-added-intense green-intense)
(bg-changed unspecified)
(bg-changed-faint unspecified)
(bg-changed-refine bg-inactive)
(fg-changed yellow)
(fg-changed-intense yellow-intense)
(bg-removed unspecified)
(bg-removed-faint unspecified)
(bg-removed-refine bg-inactive)
(fg-removed red)
(fg-removed-intense red-intense)
(bg-diff-context unspecified)))
;; Because deuteranopia cannot use the typical red-yellow-green
;; combination, we need to arrange for a yellow-purple-blue sequence.
;; Notice that the above covers the "common" overrides, so we do not
File: modus-themes.info, Node: Make deuteranopia diffs red and blue instead of yellow and blue, Next: Make the themes look like what the maintainer uses, Prev: Make diffs use only a foreground, Up: Stylistic variants using palette overrides
5.2.23 Make deuteranopia diffs red and blue instead of yellow and blue
File: modus-themes.info, Node: Make the themes look like what the maintainer uses, Prev: Make deuteranopia diffs red and blue instead of yellow and blue, Up: Stylistic variants using palette overrides
5.2.24 Make the themes look like what the maintainer uses
;; Make line numbers less intense and add a shade of cyan
;; for the current line number.
(fg-line-number-inactive "gray50")
(fg-line-number-active cyan-cooler)
(bg-line-number-inactive unspecified)
(bg-line-number-active unspecified)
;; Make the current line of `hl-line-mode' a fine shade of
;; gray (though also see my `lin' package).
(bg-hl-line bg-dim)
;; Make the region have a cyan-green background with no
;; specific foreground (use foreground of underlying text).
;; "bg-sage" refers to Salvia officinalis, else the common
;; sage.
(bg-region bg-sage)
(fg-region unspecified)
;; Make matching parentheses a shade of magenta. It
;; complements the region nicely.
(bg-paren-match bg-magenta-intense)
;; Make email citations faint and neutral, reducing the
;; default four colors to two; make mail headers cyan-blue.
(mail-cite-0 fg-dim)
(mail-cite-1 blue-faint)
(mail-cite-2 fg-dim)
(mail-cite-3 blue-faint)
(mail-part cyan-warmer)
(mail-recipient blue-warmer)
(mail-subject magenta-cooler)
(mail-other cyan-warmer)
;; Change dates to a set of more subtle combinations.
(date-deadline magenta-cooler)
(date-scheduled magenta)
(date-weekday fg-main)
(date-event fg-dim)
(date-now blue-faint)
;; Make tags (Org) less colorful and tables look the same as
;; the default foreground.
(prose-done cyan-cooler)
(prose-tag fg-dim)
(prose-table fg-main)
;; Make headings less colorful (though I never use deeply
;; nested headings).
(fg-heading-2 blue-faint)
(fg-heading-3 magenta-faint)
(fg-heading-4 blue-faint)
(fg-heading-5 magenta-faint)
(fg-heading-6 blue-faint)
(fg-heading-7 magenta-faint)
(fg-heading-8 blue-faint)
;; Make the active mode line a fine shade of lavender
;; (purple) and tone down the gray of the inactive mode
;; lines.
(bg-mode-line-active bg-lavender)
(border-mode-line-active bg-lavender)
(bg-mode-line-inactive bg-dim)
(border-mode-line-inactive bg-inactive)
;; Make the prompts a shade of magenta, to fit in nicely with
;; the overall blue-cyan-purple style of the other overrides.
;; Add a nuanced background as well.
(bg-prompt bg-magenta-nuanced)
(fg-prompt magenta-cooler)
;; Tweak some more constructs for stylistic constistency.
(name blue-warmer)
(identifier magenta-faint)
(keybind magenta-cooler)
(accent-0 magenta-cooler)
(accent-1 cyan-cooler)
(accent-2 blue-warmer)
(accent-3 red-cooler)))
;; Make the active mode line have a pseudo 3D effect (this assumes
;; you are using the default mode line and not an extra package).
(custom-set-faces
'(mode-line ((t :box (:style released-button)))))
File: modus-themes.info, Node: More accurate colors in terminal emulators, Next: Range of color with terminal emulators, Prev: Stylistic variants using palette overrides, Up: Advanced customization
5.3 More accurate colors in terminal emulators
==============================================
[ This is based on partial information. Please help verify and/or
expand these findings. ]
The graphical version of Emacs can reproduce color values accurately.
Whereas things get more tricky when Emacs is used in a terminal
emulator, because the terminals’ own capabilities determine the number
of colors that may be displayed: the Modus themes don’t look as good in
that case.
There is, however, a way to instruct supported terminal emulators to
use more accurate colors. In a shell prompt type ‘toe -a | grep direct’
to get a list of relevant terminfo entries. There should be items such
as ‘xterm-direct’, ‘alacritty-direct’, ‘kitty-direct’. Once you find
the one that corresponds to your terminal, call Emacs with an
environment variable like ‘TERM=xterm-direct’. Example that can be
adapted to shell aliases:
TERM=xterm-direct emacsclient -nw
Another example that can be bound to a key:
TERM=xterm-direct uxterm -e emacsclient -nw
File: modus-themes.info, Node: Range of color with terminal emulators, Next: Preview theme colors, Prev: More accurate colors in terminal emulators, Up: Advanced customization
5.4 Range of color with terminal emulators
==========================================
[ This is based on partial information. Please help verify and/or
expand these findings. ]
When Emacs runs in a non-windowed session its color reproduction
capacity is framed or determined by the underlying terminal emulator
(*note More accurate colors in terminal emulators::). Emacs cannot
produce a color that lies outside the range of what the terminal’s color
palette renders possible.
This is immediately noticeable when the terminal’s first 16 codes do
not include a pure black value for the ‘termcol0’ entry and a pure white
for ‘termcol15’. Emacs cannot set the correct background (white for
‘modus-operandi’; black for ‘modus-vivendi’) or foreground (inverse of
the background). It thus falls back to the closest approximation, which
seldom is appropriate for the purposes of the Modus themes.
In such a case, the user is expected to update their terminal’s color
palette such as by adapting these resources (*note Preview theme
colors::):
! Theme: modus-operandi
! Description: XTerm port of modus-operandi (Modus themes for GNU Emacs)
File: modus-themes.info, Node: Preview theme colors, Next: Per-theme customization settings, Prev: Range of color with terminal emulators, Up: Advanced customization
5.5 Preview theme colors
========================
The command ‘modus-themes-list-colors’ uses minibuffer completion to
select an item from the Modus themes and then produces a buffer with
previews of its color palette entries. The buffer has a naming scheme
that reflects the given choice, like ‘modus-operandi-list-colors’ for
the ‘modus-operandi’ theme.
The command ‘modus-themes-list-colors-current’ skips the minibuffer
selection process and just produces a preview for the current Modus
theme.
When called with a prefix argument (‘C-u’ with the default key
bindings), these commands will show a preview of the palette’s semantic
color mappings instead of the named colors. In this context, “named
colors” are entries that associate a symbol to a string color value,
such as ‘(blue-warmer "#354fcf")’. Whereas “semantic color mappings”
associate a named color to a symbol, like ‘(string blue-warmer)’, thus
making the theme render all string constructs in the ‘blue-warmer’ color
value (*note Option for palette overrides: Palette overrides.).
Aliases for those commands are ‘modus-themes-preview-colors’ and
‘modus-themes-preview-colors-current’.
Each row shows a foreground and background coloration using the
underlying value it references. For example a line with ‘#a60000’ (a
shade of red) will show red text followed by a stripe with that same
color as a backdrop.
The name of the buffer describes the given Modus theme and what the
contents are, such as ‘*modus-operandi-list-colors*’ for named colors
and ‘=*modus-operandi-list-mappings*’ for the semantic color mappings.
File: modus-themes.info, Node: Per-theme customization settings, Next: Get a single color from the palette, Prev: Preview theme colors, Up: Advanced customization
5.6 Per-theme customization settings
====================================
If you prefer to maintain different customization options between the
two themes, it is best you write your own functions that first set those
options and then load the relevant theme. The following code does
exactly that by simply differentiating the two themes on the choice of
bold constructs in code syntax (enabled for one, disabled for the
Then assign ‘my-demo-modus-themes-toggle’ to a key instead of the
equivalent the themes provide.
For a more elaborate design, it is better to inspect the source code
of ‘modus-themes-toggle’ and relevant functions.
File: modus-themes.info, Node: Get a single color from the palette, Next: Use theme colors in code with modus-themes-with-colors, Prev: Per-theme customization settings, Up: Advanced customization
5.7 Get a single color from the palette
=======================================
*note Use theme colors in code with modus-themes-with-colors::.
The fuction ‘modus-themes-get-color-value’ can be called from Lisp to
return the value of a color from the active Modus theme palette. It
takea a ‘COLOR’ argument and an optional ‘OVERRIDES’.
‘COLOR’ is a symbol that represents a named color entry in the
palette.
*note Preview theme colors::.
If the value is the name of another color entry in the palette (so a
mapping), this function recurs until it finds the underlying color
value.
With an optional ‘OVERRIDES’ argument as a non-‘nil’ value, it
accounts for palette overrides. Else it reads only the default palette.
*note Option for palette overrides: Palette overrides.
With optional ‘THEME’ as a symbol among ‘modus-themes-items’ (alias
‘modus-themes-collection’), use the palette of that item. Else use the
current Modus theme.
If ‘COLOR’ is not present in the palette, this function returns the
‘unspecified’ symbol, which is safe when used as a face attribute’s
value.
An example with ‘modus-operandi’ to show how this function behaves
with/without overrides and when recursive mappings are introduced.
;; Here we show the recursion of palette mappings. In general, it is
;; better for the user to specify named colors to avoid possible
;; confusion with their configuration, though those still work as
;; expected.
(setq modus-themes-common-palette-overrides
'((cursor red)
(fg-mode-line-active cursor)
(border-mode-line-active fg-mode-line-active)))
;; Ignore the overrides and get the original value.
File: modus-themes.info, Node: Use theme colors in code with modus-themes-with-colors, Next: Do not extend the region background, Prev: Get a single color from the palette, Up: Advanced customization
5.8 Use theme colors in code with modus-themes-with-colors
The ‘modus-themes-with-colors’ has access to the whole palette of the
active theme, meaning that it can instantiate both (i) named colors like
‘blue-warmer’ and (ii) semantic color mappings like ‘warning’. We
provide commands to inspect those (*note Preview theme colors::).
Others sections in this manual show how to use the aforementioned
macro (*note Advanced customization::).
Because the ‘modus-themes-with-colors’ will most likely be used to
customize faces, note that any function that calls it must be run at
startup after the theme loads. The same function must also be assigned
to the ‘modus-themes-after-load-theme-hook’ for its effects to persist
and be updated when switching between Modus themes (e.g. to update the
exact value of ‘blue-warmer’ when toggling between ‘modus-operandi’ to
‘modus-vivendi’.
File: modus-themes.info, Node: Do not extend the region background, Next: Add padding to mode line, Prev: Use theme colors in code with modus-themes-with-colors, Up: Advanced customization
5.9 Do not extend the region background
=======================================
By the default, the background of the ‘region’ face extends from the end
of the line to the edge of the window. To limit it to the end of the
line, we need to override the face’s ‘:extend’ attribute. Adding this
to the Emacs configuration file will suffice:
;; Do not extend `region' background past the end of the line.
(custom-set-faces
'(region ((t :extend nil))))
*note Make the region preserve text colors, plus other styles: Make
the region preserve text colors plus other styles.
File: modus-themes.info, Node: Add padding to mode line, Next: Remap face with local value, Prev: Do not extend the region background, Up: Advanced customization
5.10 Add padding to mode line
=============================
Emacs faces do not have a concept of “padding” for the space between the
text and its box boundaries. We can approximate the effect by adding a
‘:box’ attribute, making its border several pixels thick, and using the
mode line’s background color for it. This way the thick border will not
stand out and will appear as a continuation of the mode line.
*note Use theme colors in code with modus-themes-with-colors::.
The reason we no longer provide this option is because it depends on
a non-‘nil’ value for ‘x-underline-at-descent-line’. That variable
affects ALL underlines, including those of links. The effect is
intrusive and looks awkard in prose.
As such, the Modus themes no longer provide that option but instead
offer this piece of documentation to make the user fully aware of the
state of affairs.
File: modus-themes.info, Node: Remap face with local value, Next: Font configurations for Org and others, Prev: Add padding to mode line, Up: Advanced customization
5.11 Remap face with local value
================================
There are cases where we need to change the buffer-local attributes of a
face. This might be because we have our own minor mode that re-uses a
face for a particular purpose, such as a line selection tool that
activates ‘hl-line-mode’, but we wish to keep it distinct from other
buffers. This is where ‘face-remap-add-relative’ can be applied and may
be combined with ‘modus-themes-with-colors’ to deliver consistent
results.
*note Use theme colors in code with modus-themes-with-colors::.
In this example we will write a simple interactive function that
adjusts the background color of the ‘region’ face. This is the sample
code:
(defvar my-rainbow-region-colors
(modus-themes-with-colors
`((red . ,bg-red-subtle)
(green . ,bg-green-subtle)
(yellow . ,bg-yellow-subtle)
(blue . ,bg-blue-subtle)
(magenta . ,bg-magenta-subtle)
(cyan . ,bg-cyan-subtle)))
"Sample list of color values for `my-rainbow-region'.")
(defun my-rainbow-region (color)
"Remap buffer-local attribute of `region' using COLOR."
(interactive
(list
(completing-read "Pick a color: " my-rainbow-region-colors)))
Whenever we enter a ‘diff-mode’ buffer, we now get a magenta-colored
region.
Perhaps you may wish to generalize those findings in to a set of
functions that also accept an arbitrary face. We shall leave the
experimentation up to you.
File: modus-themes.info, Node: Font configurations for Org and others, Next: Configure bold and italic faces, Prev: Remap face with local value, Up: Advanced customization
5.12 Font configurations for Org and others
===========================================
The themes are designed to optionally cope well with mixed font
configurations. This mostly concerns ‘org-mode’ and ‘markdown-mode’,
though expect to find it elsewhere like in ‘Info-mode’.
*note Option for font mixing: Mixed fonts.
In practice it means that the user can safely opt for a more
prose-friendly proportionately spaced typeface as their default, while
spacing-sensitive elements like tables and inline code always use a
monospaced font, by inheriting from the ‘fixed-pitch’ face.
Users can try the built-in ‘M-x variable-pitch-mode’ to see the
effect in action.
To make everything use your desired font families, you need to
configure the ‘variable-pitch’ (proportional spacing) and ‘fixed-pitch’
(monospaced) faces respectively. It may also be convenient to set your
main typeface by configuring the ‘default’ face the same way.
[ The ‘fontaine’ package on GNU ELPA (by Protesilaos) is designed to
handle this case. ]
Put something like this in your initialization file (also consider
reading the doc string of ‘set-face-attribute’):
;; Main typeface
(set-face-attribute 'default nil :family "DejaVu Sans Mono" :height 110)
The next section shows how to make those work in a more elaborate
setup that is robust to changes between the Modus themes.
*note Configure bold and italic faces::.
Note the differences in the ‘:height’ property. The ‘default’ face
must specify an absolute value, which is the point size × 10. So if you
want to use a font at point size ‘11’, you set the height to ‘110’.(1)
Whereas every other face must either not specify a height or have a
value that is relative to the default, represented as a floating point.
If you use an integer, then that means an absolute height. This is of
paramount importance: it ensures that all fonts can scale gracefully
when using something like the ‘text-scale-adjust’ command which only
operates on the base font size (i.e. the ‘default’ face’s absolute
height).
*note Note for EWW and Elfeed fonts: Note on SHR fonts.
---------- Footnotes ----------
(1) ‘:height’ values do not need to be rounded to multiples of ten:
the likes of ‘115’ are perfectly valid—some typefaces will change to
account for those finer increments.
File: modus-themes.info, Node: Configure bold and italic faces, Next: Custom Org todo keyword and priority faces, Prev: Font configurations for Org and others, Up: Advanced customization
5.13 Configure bold and italic faces
====================================
The Modus themes do not hardcode a ‘:weight’ or ‘:slant’ attribute in
the thousands of faces they cover. Instead, they configure the generic
faces called ‘bold’ and ‘italic’ to use the appropriate styles and then
instruct all relevant faces that require emphasis to inherit from them.
This practically means that users can change the particularities of
what it means for a construct to be bold/italic, by tweaking the ‘bold’
and ‘italic’ faces. Cases where that can be useful include:
• The default typeface does not have a variant with slanted glyphs
(e.g. Fira Mono/Code as of this writing on 2021-07-07), so the
user wants to add another family for the italics, such as Hack.
• The typeface of choice provides a multitude of weights and the user
prefers the light one by default. To prevent the bold weight from
being too heavy compared to the light one, they opt to make ‘bold’
use a semibold weight.
• The typeface distinguishes between oblique and italic forms by
providing different font variants (the former are just slanted
versions of the upright forms, while the latter have distinguishing
features as well). In this case, the user wants to specify the
font that applies to the ‘italic’ face.
To achieve those effects, one must first be sure that the fonts they
use have support for those features. It then is a matter of following
the instructions for all typeface tweaks.
*note Font configurations for Org and others::.
In this example, we set the default font family to Fira Code, while
we choose to render italics in the Hack typeface (obviously you need to
To measure color contrast one needs to start from a known value.
This typically is the background. The Modus themes define an expanded
palette in large part because certain colors are only meant to be used
in combination with some others. Consult the source code for the
minutia and relevant commentary.
Such knowledge may prove valuable while attempting to customize the
theme’s color palette.
File: modus-themes.info, Node: Load theme depending on time of day, Next: Backdrop for pdf-tools, Prev: Measure color contrast, Up: Advanced customization
5.18 Load theme depending on time of day
========================================
While we do provide ‘modus-themes-toggle’ to manually switch between the
themes, users may also set up their system to perform such a task
automatically at sunrise and sunset.
This can be accomplished by specifying the coordinates of one’s
location using the built-in ‘solar.el’ and then configuring the
File: modus-themes.info, Node: Backdrop for pdf-tools, Next: Toggle themes without reloading them, Prev: Load theme depending on time of day, Up: Advanced customization
5.19 Backdrop for pdf-tools
===========================
Most PDF files use a white background for their page, making it
impossible to discern the file’s boundaries in the buffer while using
the Modus Operandi theme. To introduce a distinction between the
buffer’s backdrop and the PDF page’s background, the former must be
rendered as some shade of gray. Ideally, ‘pdf-tools’ would provide a
face that the themes could support directly, though this does not seem
to be the case for the time being. We must thus employ the face
remapping technique that is documented elsewhere in this document to
change the buffer-local value of the ‘default’ face.
*note Remap face with local value::.
To remap the buffer’s backdrop, we start with a function like this
(_ (error "No Modus theme is loaded; evaluate `modus-themes-load-themes' first"))))
*note Differences between loading and enabling::.
Recall that ‘modus-themes-toggle’ uses ‘load-theme’.
File: modus-themes.info, Node: A theme-agnostic hook for theme loading, Next: Use more spacious margins or padding in Emacs frames, Prev: Toggle themes without reloading them, Up: Advanced customization
5.21 A theme-agnostic hook for theme loading
============================================
The themes are designed with the intent to be useful to Emacs users of
varying skill levels, from beginners to experts. This means that we try
to make things easier by not expecting anyone reading this document to
be proficient in Emacs Lisp or programming in general.
Such a case is with the use of ‘modus-themes-after-load-theme-hook’,
which runs after the ‘modus-themes-load-theme’ function (used by the
command ‘modus-themes-toggle’). We recommend using that hook for
advanced customizations, because (1) we know for sure that it is
available once the themes are loaded, and (2) anyone consulting this
manual, especially the sections on enabling and loading the themes, will
be in a good position to benefit from that hook.
Advanced users who have a need to switch between the Modus themes and
other items will find that such a hook does not meet their requirements:
it only works with the Modus themes and only with the aforementioned
This creates the ‘after-enable-theme-hook’ and makes it run after
each call to ‘enable-theme’, which means that it will work for all
themes and also has the benefit that it does not depend on functions
such as ‘modus-themes-toggle’ and the others mentioned above.
‘enable-theme’ is called internally by ‘load-theme’, so the hook works
everywhere.
The downside of the theme-agnostic hook is that any functions added
to it will likely not be able to benefit from macro calls that read the
active theme, such as ‘modus-themes-with-colors’. Not all Emacs themes
have the same capabilities.
In this document, we cover ‘modus-themes-after-load-theme-hook’
though the user can replace it with ‘after-enable-theme-hook’ should
they need to (provided they understand the implications).
File: modus-themes.info, Node: Use more spacious margins or padding in Emacs frames, Next: Custom hl-todo colors, Prev: A theme-agnostic hook for theme loading, Up: Advanced customization
5.22 Use more spacious margins or padding in Emacs frames
Users of older versions of Emacs can read the entry herein about
defining their own theme-agnostic hook (*note A theme-agnostic hook for
theme loading::).
File: modus-themes.info, Node: Custom hl-todo colors, Next: Add support for solaire-mode, Prev: Use more spacious margins or padding in Emacs frames, Up: Advanced customization
5.23 Custom hl-todo colors
==========================
The ‘hl-todo’ package provides the user option ‘hl-todo-keyword-faces’:
it specifies a pair of keyword and corresponding color value. The Modus
themes configure that option in the interest of legibility. While this
works for our purposes, users may still prefer to apply their custom
values, in which case the following approach is necessary:
;; The default marks the Saturday and Sunday as the weekend
(setq calendar-weekend-days '(0 6))
For changes to take effect, the Calendar buffer needs to be generated
anew.
File: modus-themes.info, Node: Note on git-gutter in Doom Emacs, Next: Note on php-mode multiline comments, Prev: Note on calendarel weekday and weekend colors, Up: Notes on individual packages
7.2 Note on git-gutter in Doom Emacs
====================================
The ‘git-gutter’ and ‘git-gutter-fr’ packages default to drawing bitmaps
for the indicators they display (e.g. bitmap of a plus sign for added
lines). In Doom Emacs, these bitmaps are replaced with contiguous lines
which may look nicer, but require a change to the foreground of the
relevant faces to yield the desired color combinations.
Since this is Doom-specific, we urge users to apply changes in their
local setup. Below is some sample code, based on what we cover at
length elsewhere in this manual:
*note Advanced customization::.
*note Use theme colors in code with modus-themes-with-colors::.
(defun my-modus-themes-custom-faces ()
(modus-themes-with-colors
(custom-set-faces
;; Make foreground the same as background for a uniform bar on
;; Doom Emacs.
;;
;; Doom should not be implementing such hacks because themes
File: modus-themes.info, Node: Note on php-mode multiline comments, Next: Note on underlines in compilation buffers, Prev: Note on git-gutter in Doom Emacs, Up: Notes on individual packages
7.3 Note on php-mode multiline comments
=======================================
Depending on your build of Emacs and/or the environment it runs in,
multiline comments in PHP with the ‘php-mode’ package use the
‘font-lock-doc-face’ instead of ‘font-lock-comment-face’.
This seems to make all comments use the appropriate face:
As always, re-load the theme for changes to take effect.
File: modus-themes.info, Node: Note on underlines in compilation buffers, Next: Note on inline Latex in Org buffers, Prev: Note on php-mode multiline comments, Up: Notes on individual packages
7.4 Note on underlines in compilation buffers
=============================================
Various buffers that produce compilation results or run tests on code
apply an underline to the file names they reference or to relevant
messages. Users may consider this unnecessary or excessive.
To outright disable the effect, use this (buffers need to be
generated anew):
(setq compilation-message-face nil)
If some element of differentiation is still desired, a good option is
to render the affected text with the ‘italic’ face:
(setq compilation-message-face 'italic)
*note Configure bold and italic faces::.
File: modus-themes.info, Node: Note on inline Latex in Org buffers, Next: Note on dimmerel, Prev: Note on underlines in compilation buffers, Up: Notes on individual packages
7.5 Note on inline Latex in Org buffers
=======================================
Org can work with inline latex and related syntax. To actually fontify
those constructs, set the variable ‘org-highlight-latex-and-related’ to
the desired list of values (per its doc string). For example:
Remember to use ‘M-x org-mode-restart’ for changes to take effect.
File: modus-themes.info, Node: Note on dimmerel, Next: Note on display-fill-column-indicator-mode, Prev: Note on inline Latex in Org buffers, Up: Notes on individual packages
7.6 Note on dimmer.el
=====================
The ‘dimmer.el’ library by Neil Okamoto can be configured to
automatically dim the colors of inactive Emacs windows. To guarantee
consistent results with the Modus themes, we suggest some tweaks to the
default styles, such as in this minimal setup:
(use-package dimmer
:config
(setq dimmer-fraction 0.3)
(setq dimmer-adjustment-mode :foreground)
(setq dimmer-use-colorspace :rgb)
(dimmer-mode 1))
Of the above, we strongly recommend the RGB color space because it is
the one that remains faithful to the hueness of the colors used by the
themes. Whereas the default CIELAB space has a tendency to distort
colors in addition to applying the dim effect, which can be somewhat
disorienting.
The value of the ‘dimmer-fraction’ has been selected empirically.
Users might prefer to tweak it further (increasing it makes the dim
effect more pronounced).
Changing the ‘dimmer-adjustment-mode’ is a matter of preference.
Though because the Modus themes use black and white as their base
colors, any other value for that variable will turn the main background
gray. This inadvertently leads to the opposite of the intended utility
of this package: it draws too much attention to unfocused windows.
File: modus-themes.info, Node: Note on display-fill-column-indicator-mode, Next: Note on highlight-parenthesesel, Prev: Note on dimmerel, Up: Notes on individual packages
7.7 Note on display-fill-column-indicator-mode
==============================================
The ‘display-fill-column-indicator-mode’ uses a typographic character to
draw its line. This has the downside of creating a dashed line. The
dashes are further apart depending on how tall the font’s glyph height
is and what integer the ‘line-spacing’ is set to.
At the theme level we eliminate this effect by making the character
one pixel tall: the line is contiguous. Users who prefer the dashed
line are advised to change the ‘fill-column-indicator’ face, as
explained elsewhere in this document. For example:
File: modus-themes.info, Node: Note for prism, Next: Note on company-mode overlay pop-up, Prev: Note on mmm-modeel background colors, Up: Notes on individual packages
7.10 Note on prism.el
=====================
This package by Adam Porter, aka “alphapapa” or “github-alphapapa”,
implements an alternative to the typical coloration of code. Instead of
highlighting the syntactic constructs, it applies color to different
levels of depth in the code structure.
As ‘prism.el’ offers a broad range of customizations, we cannot style
it directly at the theme level: that would run contrary to the spirit of
the package. Instead, we may offer preset color schemes. Those should
offer a starting point for users to adapt to their needs.
In the following code snippets, we employ the
‘modus-themes-with-colors’ macro: *note Use theme colors in code with
modus-themes-with-colors::.
These are the minimum recommended settings with 16 colors:
(setq prism-num-faces 16)
(prism-set-colors
:desaturations '(0) ; do not change---may lower the contrast ratio
:lightens '(0) ; same
:colors (modus-themes-with-colors
(list fg-main
magenta
cyan-cooler
magenta-cooler
blue
magenta-warmer
cyan-warmer
red-cooler
green
fg-main
cyan
yellow
blue-warmer
red-warmer
green-cooler
yellow-faint)))
With 8 colors:
(setq prism-num-faces 8)
(prism-set-colors
:desaturations '(0) ; do not change---may lower the contrast ratio
:lightens '(0) ; same
:colors (modus-themes-with-colors
(list blue
magenta
magenta-cooler
cyan-cooler
fg-main
blue-warmer
red-cooler
cyan)))
And this is with 4 colors, which produces results that are the
closest to the themes’ default aesthetic:
(setq prism-num-faces 4)
(prism-set-colors
:desaturations '(0) ; do not change---may lower the contrast ratio
:lightens '(0) ; same
:colors (modus-themes-with-colors
(list blue
magenta
magenta-cooler
green-warmer)))
If you need to apply desaturation and lightening, you can use what
the ‘prism.el’ documentation recommends, like this (adapting to the
examples with the 4, 8, 16 colors):
(prism-set-colors
:desaturations (cl-loop for i from 0 below 16 collect (* i 2.5))
:lightens (cl-loop for i from 0 below 16 collect (* i 2.5))
:colors (modus-themes-with-colors
(list fg-main
cyan-cooler
magenta-cooler
magenta)))
File: modus-themes.info, Node: Note on company-mode overlay pop-up, Next: Note on ERC escaped color sequences, Prev: Note for prism, Up: Notes on individual packages
7.11 Note on company-mode overlay pop-up
========================================
By default, the ‘company-mode’ pop-up that lists completion candidates
is drawn using an overlay. This creates alignment issues every time it
is placed above a piece of text that has a different height than the
default.
The solution recommended by the project’s maintainer is to use an
alternative front-end for drawing the pop-up which draws child frames
File: modus-themes.info, Node: Note on ERC escaped color sequences, Next: Note on powerline or spaceline, Prev: Note on company-mode overlay pop-up, Up: Notes on individual packages
7.12 Note on ERC escaped color sequences
========================================
The built-in IRC client ‘erc’ has the ability to colorize any text using
escape sequences that start with ‘^C’ (inserted with ‘C-q C-c’) and are
followed by a number for the foreground and background.(1) Possible
numbers are 0-15, with the first entry being the foreground and the
second the background, separated by a comma. Like this ‘^C1,6’. The
minimum setup is this:
(add-to-list 'erc-modules 'irccontrols)
(setq erc-interpret-controls-p t
erc-interpret-mirc-color t)
As this allows users the chance to make arbitrary combinations, it is
impossible to guarantee a consistently high contrast ratio. All we can
we do is provide guidance on the combinations that satisfy the
accessibility standard of the themes:
Modus Operandi
Use foreground color 1 for all backgrounds from 2-15. Like so:
‘C-q C-c1’ where ‘N’ is the background.
Modus Vivendi
Use foreground color 0 for all backgrounds from 2-13. Use
foreground ‘1’ for backgrounds 14, 15.
Colors 0 and 1 are white and black respectively. So combine them
together, if you must.
---------- Footnotes ----------
(1) This page explains the basics, though it is not specific to
Emacs: <https://www.mirc.com/colors.html>
File: modus-themes.info, Node: Note on powerline or spaceline, Next: Note on SHR colors, Prev: Note on ERC escaped color sequences, Up: Notes on individual packages
7.13 Note on powerline or spaceline
===================================
Both Powerline and Spaceline package users will likely need to use the
command ‘powerline-reset’ whenever they make changes to their themes
and/or mode line setup.
File: modus-themes.info, Node: Note on SHR colors, Next: Note on SHR fonts, Prev: Note on powerline or spaceline, Up: Notes on individual packages
7.14 Note on SHR colors
=======================
Emacs’ HTML rendering library (‘shr.el’) may need explicit configuration
to respect the theme’s colors instead of whatever specifications the
webpage provides.
Consult the doc string of ‘shr-use-colors’.
File: modus-themes.info, Node: Note on SHR fonts, Next: Note on Ement colors and fonts, Prev: Note on SHR colors, Up: Notes on individual packages
7.15 Note on SHR fonts
======================
By default, packages that build on top of the Simple HTML Remember
(‘shr’) use proportionately spaced fonts. This is controlled by the
user option ‘shr-use-fonts’, which is set to non-‘nil’ by default. To
use the standard font instead, set that variable to ‘nil’.
*note Font configurations for Org and others::.
Packages affected by this are:
• elfeed
• ement
• eww
This is a non-exhaustive list.
File: modus-themes.info, Node: Note on Ement colors and fonts, Next: Note on pdf-tools link hints, Prev: Note on SHR fonts, Up: Notes on individual packages
7.16 Note on Ement colors and fonts
===================================
The ‘ement.el’ library by Adam Porter (also known as “alphapapa”)
defaults to a method of colorizing usernames in a rainbow style. This
is controlled by the user option ‘ement-room-prism’ and can be disabled
with:
(setq ement-room-prism nil)
The contrast ratio of these colors is governed by another user
option: ‘ement-room-prism-minimum-contrast’. By default, it is set to 6
which is slightly below our nominal target. Try this instead:
(setq ement-room-prism-minimum-contrast 7)
With regard to fonts, Ement depends on ‘shr’ (*note Note on SHR
fonts::).
Since we are here, here is an excerpt from Ement’s source code:
(defcustom ement-room-prism-minimum-contrast 6
"Attempt to enforce this minimum contrast ratio for user faces.
This should be a reasonable number from, e.g. 0-7 or so."
;; Prot would almost approve of this default. :) I would go all the way
;; to 7, but 6 already significantly dilutes the colors in some cases.
:type 'number)
Yes, I do approve of that default. Even a 4.5 (the WCAG AA rating)
would be a good baseline for many themes and/or user configurations.
Our target is the highest of the sort, though we do not demand that
everyone conforms with it.
File: modus-themes.info, Node: Note on pdf-tools link hints, Next: Note on the Notmuch logo, Prev: Note on Ement colors and fonts, Up: Notes on individual packages
7.17 Note on pdf-tools link hints
=================================
Hints are drawn by ImageMagick (https://imagemagick.org/), not Emacs,
i.e., ImageMagick doesn’t know about the hint face unless you tell
ImageMagick about it. By default, only the foreground and background
color attributes are passed. The below snippet adds to those the
various font attributes. As it queries various faces, specifically
‘pdf-links-read-link’ and the faces it inherits, it needs to be added to
your initialization file after you’ve customized any faces.
File: modus-themes.info, Node: Note on the Notmuch logo, Next: Note on goto-address-mode faces, Prev: Note on pdf-tools link hints, Up: Notes on individual packages
7.18 Note on the Notmuch logo
=============================
By default, the “hello” buffer of Notmuch includes a header with the
programs’ logo and a couple of buttons. The logo has the effect of
enlarging the height of the line, which negatively impacts the shape of
those buttons. Disabling the logo fixes the problem:
(setq notmuch-show-logo nil)
File: modus-themes.info, Node: Note on goto-address-mode faces, Prev: Note on the Notmuch logo, Up: Notes on individual packages
7.19 Note on goto-address-mode faces
====================================
The built-in ‘goto-address-mode’ uses heuristics to identify URLs and
email addresses in the current buffer. It then applies a face to them
to change their style. Some packages, such as ‘notmuch’, use this
minor-mode automatically.
The faces are not declared with ‘defface’, meaning that it is better
that the theme does not modify them. The user is thus encouraged to
consider including (or equivalent) this in their setup:
(setq goto-address-url-face 'link
goto-address-url-mouse-face 'highlight
goto-address-mail-face 'link
goto-address-mail-mouse-face 'highlight)
My personal preference is to set ‘goto-address-mail-face’ to ‘nil’,
as it otherwise adds too much visual noise to the buffer (email
addresses stand out more, due to the use of the uncommon ‘@’ character
but also because they are often enclosed in angled brackets).
File: modus-themes.info, Node: Frequently Asked Questions, Next: Contributing, Prev: Notes on individual packages, Up: Top
8 Frequently Asked Questions
****************************
In this section we provide answers related to some aspects of the Modus
themes’ design and application.
* Menu:
* Is the contrast ratio about adjacent colors?::
* What does it mean to avoid exaggerations?::
* Why are colors mostly variants of blue, magenta, cyan?: Why are colors mostly variants of blue magenta cyan?.
* What is the best setup for legibility?::
* Are these color schemes?::
* Port the Modus themes to other platforms?::
File: modus-themes.info, Node: Is the contrast ratio about adjacent colors?, Next: What does it mean to avoid exaggerations?, Up: Frequently Asked Questions
8.1 Is the contrast ratio about adjacent colors?
================================================
The minimum contrast ratio in relative luminance that the themes conform
with always refers to any given combination of background and foreground
colors. If we have some blue colored text next to a magenta one, both
against a white background, we do not mean to imply that blue:magenta is
7:1 in terms of relative luminance. Rather, we state that blue:white
and magenta:white each are 7:1 or higher.
The point of reference is always the background. Because colors have
about the same minimum distance in luminance from their backdrop, they
necessarily are fairly close to each other in this measure. A possible
blue:magenta combination would naturally be around 1:1 in contrast of
the sort here considered.
To differentiate between sequential colors, we rely on hueness by
mapping contrasting hues to adjacent constructs, while avoiding
exaggerations. A blue next to a magenta can be told apart regardless of
their respective contrast ratio against their common background.
Exceptions would be tiny characters in arguably not so realistic cases,
such as two dots drawn side-by-side which for some reason would need to
be colored differently. They would still be legible though, which is
the primary objective of the Modus themes.
File: modus-themes.info, Node: What does it mean to avoid exaggerations?, Next: Why are colors mostly variants of blue magenta cyan?, Prev: Is the contrast ratio about adjacent colors?, Up: Frequently Asked Questions
8.2 What does it mean to avoid exaggerations?
=============================================
The Modus themes are designed with restraint, so that their default
looks do not overdo it with the application of color.
This is the non-quantifiable aspect of the themes’ design: the
artistic part, if you will. There are a lot of cases where color can be
used inconsiderately, without accounting for layout, typographic, or
other properties of the presentation. For example, two headings with
distinct markers, such as leading asterisks in Org buffers, do not have
to have highly contrasting hues between them in order to be told apart:
the added element of contrast in hueness does not contribute
significantly more to the distinction between the headings than colors
whose hues are relatively closer to each other in the color space.
Exaggerations can be hard to anticipate or identify. Multiple shades
of blue and magenta in the same context may not seem optimal: one might
think that it would be better to use highly contrasting hues to ensure
that all colors stand out, such as by placing blue next to yellow, next
to magenta, and green. That would, however, be a case of design for its
own sake; a case where color is being applied without consideration of
its end results in the given context. Too many contrasting hues in
close proximity force an erratic rate to how the eye jumps from one
piece of text to the next. Whereas multiple shades of, say, blue and
magenta can suffice to tell things apart and avoid excess coloration: a
harmonious rhythm.
File: modus-themes.info, Node: Why are colors mostly variants of blue magenta cyan?, Next: What is the best setup for legibility?, Prev: What does it mean to avoid exaggerations?, Up: Frequently Asked Questions
8.3 Why are colors mostly variants of blue, magenta, cyan?
Due to the innate properties of color, some options are better than
others for the accessibility purposes of the themes, the stylistic
consistency between ‘modus-operandi’ and ‘modus-vivendi’, and the
avoidance of exaggerations in design.
*note What does it mean to avoid exaggerations?::
What we describe as color is a function of three distinct channels of
light: red, green, blue. In hexadecimal RGB notation, a color value is
read as three pairs of red, green, and blue light: ‘#RRGGBB’. Of those
three, the most luminant is green, while the least luminant is blue.
The three basic colors represent each of the channels of light. They
can be intermixed to give us six colors: red and green derive yellow,
green and blue make cyan, red and blue turn into magenta.
We can test the luminance of each of those against white and black to
get a sense of how not all colors are equally good for accessibility
(white is ‘#ffffff’, which means that all three light channels are fully
luminated, while black is ‘#000000’ meaning that no light is present
(notwithstanding display technology)).
| Name | | #ffffff | #000000 |
|---------+---------+---------+---------|
| red | #ff0000 | 4.00 | 5.25 |
| yellow | #ffff00 | 1.07 | 19.56 |
| green | #00ff00 | 1.37 | 15.30 |
| cyan | #00ffff | 1.25 | 16.75 |
| blue | #0000ff | 8.59 | 2.44 |
| magenta | #ff00ff | 3.14 | 6.70 |
*note Measure color contrast::.
By reading this table we learn that every color that has a high level
of green light (green, yellow, cyan) is virtually unreadable against a
white background and, conversely, can be easily read against black.
We can then infer that red and blue, in different combinations, with
green acting as calibrator for luminance, will give us fairly moderate
colors that pass the 7:1 target. Blue with a bit of green produce
appropriate variants of cyan. Similarly, blue combined with some red
and hints of green give us suitable shades of purple.
Due to the need of maintaining some difference in hueness between
adjacent colors, it is not possible to make red, green, and yellow the
main colors, because blue cannot be used to control their luminance and,
thus the relevant space will shrink considerably.
*note Is the contrast ratio about adjacent colors?::
This phenomenon is best illustrated by the following table that
measures the relative luminance of shades of red, yellow, magenta
against white:
| | #ffffff |
|---------+---------|
| #990000 | 8.92 |
| #995500 | 5.75 |
| #990099 | 7.46 |
We notice that equal values of red and blue light in ‘#990099’
(magenta shade) do not lead to a considerable change in luminance
compared with ‘#990000’ (red variant). Whereas less amount of green
light in ‘#995500’ leads to a major drop in luminance relative to white.
It follows that using the green channel of light to calibrate the
luminance of colors is more effective than trying to do the same with
either red or blue (the latter is the least effective in that regard).
When we need to work with several colors, it is always better to have
sufficient manoeuvring space, especially since we cannot pick arbitrary
colors but only those that satisfy the accessibility objectives of the
themes.
As for why we do not mostly use green, yellow, cyan for the dark
theme, it is because those colors are far more luminant than their
counterparts on the other side of the spectrum, so to ensure that they
all have about the same contrast ratios we would have to alter their
hueness considerably. In short, the effect would not be optimal as it
would lead to exaggerations. Plus, it would make ‘modus-vivendi’ look
completely different than ‘modus-operandi’, to the effect that the two
could not be properly considered part of the same project.
File: modus-themes.info, Node: What is the best setup for legibility?, Next: Are these color schemes?, Prev: Why are colors mostly variants of blue magenta cyan?, Up: Frequently Asked Questions
8.4 What is the best setup for legibility?
==========================================
The Modus themes can be conceptually simplified as combinations of color
values that account for relative luminance and inner harmony. Those
qualities do not guarantee that every end-user will have the same
experience, due to differences between people, but also because of
variances in hardware capabilities and configurations. For the purposes
of this document, we may only provide suggestions pertaining to the
latter case.
‘modus-operandi’ is best used outdoors or in a room that either gets
direct sunlight or has plenty of light. Whereas ‘modus-vivendi’ works
better when there is not a lot of sunshine or the room has a source of
light that is preferably a faint and/or warm one. It is possible to use
‘modus-operandi’ at night and ‘modus-vivendi’ during the day, though
that will depend on several variables, such as one’s overall perception
of color, the paint on the walls and how that contributes to the
impression of lightness in the room, the sense of space within the eye’s
peripheral vision, hardware specifications, and environmental factors.
In general, an additional source of light other than that of the
monitor can help reduce eye strain: the eyes are more relaxed when they
do not have to focus on one point to gather light.
The monitor’s display settings must be accounted for. Gamma values,
in particular, need to be calibrated to neither amplify nor distort the
perception of black. Same principle for sharpness, brightness, and
contrast as determined by the hardware, which all have an effect on how
text is read on the screen.
There are software level methods on offer, such as the XrandR utility
for the X Window System (X.org), which can make gamma corrections for
each of the three channels of light (red, green, blue). For example:
Typography is another variable. Some font families are blurry at
small point sizes. Others may have a regular weight that is lighter
(thiner) than that of their peers which may, under certain
circumstances, cause a halo effect around each glyph.
The gist is that legibility cannot be fully solved at the theme
level. The color combinations may have been optimized for
accessibility, though the remaining contributing factors in each case
need to be considered in full.
File: modus-themes.info, Node: Are these color schemes?, Next: Port the Modus themes to other platforms?, Prev: What is the best setup for legibility?, Up: Frequently Asked Questions
8.5 Are these color schemes?
============================
No, the Modus themes are not color schemes.
A color scheme is a collection of colors. A good color scheme is a
combination of colors with an inner logic or abstract structure.
A theme is a set of patterns that are applied across different
contexts. A good theme is one that does so with consistency, though not
uniformity.
In practical terms, a color scheme is what one uses when, for
example, they replace the first sixteen escape sequences of a terminal
emulator with color values of their preference. The terminal offers the
option to choose, say, the exact value of what counts as “red”, but does
not provide the means to control where that is mapped to and whether it
should also have other qualities such as a bold weight for the
underlying text or an added background color. In contradistinction,
Emacs uses constructs known as “faces” which allow the user/developer to
specify where a given color will be used and whether it should be
accompanied by other typographic or stylistic attributes.
By configuring the multitude of faces on offer we thus control both
which colors are applied and how they appear in their context. When a
package wants to render each instance of “foo” with the “bar” face, it
is not requesting a specific color, which makes things considerably more
flexible as we can treat “bar” in its own right without necessarily
having to use some color value that we hardcoded somewhere.
Which brings us to the distinction between consistency and uniformity
where our goal is always the former: we want things to look similar
across all interfaces, but we must never force a visual identity where
that runs contrary to the functionality of the given interface. For
instance, all links are underlined by default yet there are cases such
as when viewing listings of emails in Gnus (and Mu4e, Notmuch) where (i)
it is already understood that one must follow the indicator or headline
to view its contents and (ii) underlining everything would make the
interface virtually unusable.
Again, one must exercise judgement in order to avoid discrimination,
where “discrimination” refers to:
• The treatment of substantially different magnitudes as if they were
of the same class.
• Or the treatment of the same class of magnitudes as if they were of
a different class.
(To treat similar things differently; to treat dissimilar things
alike.)
If, in other words, one is to enforce uniformity without accounting
for the particular requirements of each case—the contextual demands for
usability beyond matters of color—they are making a not-so-obvious error
of treating different cases as if they were the same.
The Modus themes prioritize “thematic consistency” over abstract
harmony or regularity among their applicable colors. In concrete terms,
we do not claim that, say, our yellows are the best complements for our
blues because we generally avoid using complementary colors
side-by-side, so it is wrong to optimize for a decontextualised
blue+yellow combination. Not to imply that our colors do not work well
together because they do, just to clarify that consistency of context is
what themes must strive for, and that requires widening the scope of the
design beyond the particularities of a color scheme.
Long story short: color schemes and themes have different
requirements. Please do not conflate the two.
File: modus-themes.info, Node: Port the Modus themes to other platforms?, Prev: Are these color schemes?, Up: Frequently Asked Questions
8.6 Port the Modus themes to other platforms?
=============================================
There is no plan to port the themes to other platforms or text editors.
I (Protesilaos) only use GNU Emacs and thus cannot maintain code that
targets software I am either not familiar with or am not using on a
daily basis.
While it is possible to produce a simulacrum based on a given
template, doing so would run contrary to how this project is maintained
where details matter greatly.
Each program has its own requirements so it won’t always be
possible—or indeed desirable—to have 1:1 correspondence between what
applies to Emacs and what should be done elsewhere. No port should ever
strive to be a copy of the Emacs implementation, as no other program is
an Emacs equivalent, but instead try to follow the spirit of the design.
For example, some of the customization options accept a list as their
value, or an alist, which may not be possible to reproduce on other
platforms.
*note Customization options::.
In other words, if something must be done differently on a certain
editor then that is acceptable so long as (i) the accessibility
standards are not compromised and (ii) the overall character of the
themes remains consistent.
The former criterion should be crystal clear as it pertains to the
scientific foundations of the themes: high legibility and taking care of
the needs of users with red-green/blue-yellow color deficiency
(deuteranopia and tritanopia) by avoiding red+green color coding
paradigms and/or by providing yellow+blue variants for deuteranopia and
red+cyan for tritanopia (*note Overview::).
The latter criterion is the “je ne sais quoi” of the artistic aspect
of the themes, which is partially fleshed out in this manual.
*note Frequently Asked Questions::.
With regard to the artistic aspect (where “art” qua skill may amount
to an imprecise science), there is no hard-and-fast rule in effect as it
requires one to exercize discretion and make decisions based on
context-dependent information or constraints. As is true with most
things in life, when in doubt, do not cling on to the letter of the law
but try to understand its spirit.
For a trivial example: the curly underline that Emacs draws for
spelling errors is thinner than, e.g., what a graphical web browser has,
so if I was to design for an editor than has a thicker curly underline I
would make the applicable colors less intense to counterbalance the
typographic intensity of the added thickness.
With those granted, if anyone is willing to develop a port of the
themes, they are welcome to contact me and I will do my best to help
• Backronym: My Old Display Unexpectedly Sharpened ... themes
File: modus-themes.info, Node: Issues you can help with, Next: Patches require copyright assignment to the FSF, Prev: Sources of the themes, Up: Contributing
9.2 Issues you can help with
============================
A few tasks you can help with by sending an email to the general
modus-themes public mailing list
(https://lists.sr.ht/~protesilaos/modus-themes).
• Suggest refinements to packages that are covered.
• Report packages not covered thus far.
• Report bugs, inconsistencies, shortcomings.
• Help expand the documentation of covered-but-not-styled packages.
• Suggest refinements to the color palette.
• Help expand this document or any other piece of documentation.
• Send patches for code refinements (if you need, ask me for help
with Git—we all start out as beginners).
*note Patches require copyright assignment to the FSF::.
It is preferable that your feedback includes some screenshots, GIFs,
or short videos, as well as further instructions to reproduce a given
setup. Though this is not a requirement.
Whatever you do, bear in mind the overarching objective of the Modus
themes: to keep a contrast ratio that is greater or equal to 7:1 between
background and foreground colors. If a compromise is ever necessary
between aesthetics and accessibility, it shall always be made in the
interest of the latter.
File: modus-themes.info, Node: Patches require copyright assignment to the FSF, Prev: Issues you can help with, Up: Contributing
9.3 Patches require copyright assignment to the FSF
