Protesilaos Stavrou

Released Modus themes 0.13.0

Just published version 0.13.0 of the Modus themes. The release notes are reproduced below. This is the largest release to date and also the first one since the themes were incorporated in upstream Emacs.

Packages may take a while to get the update, so please be patient. Contact me in case something is amiss.

Modus Operandi and Modus Vivendi version 0.13.0

By Protesilaos Stavrou info@protesilaos.com on 2020-10-08

This entry documents the changes since version 0.12.0 (2020-08-26). There have been around 150 commits in the meantime, making this the largest release to date (though sheer volume should not be conflated with quality, of which there is plenty).

As always, everything described herein conforms with the overarching accessibility objective of the themes for a minimum contrast ratio of 7:1 between background and foreground values in their given combinations (conformance with the WCAG AAA standard).

Overview

  1. There is a new Info manual that documents the customisation options as well as every other piece of information pertinent to the themes. You will find it in the Info pages inside of Emacs. Or browse it online: https://protesilaos.com/emacs/modus-themes.

  2. New customisation options grant users more power to further adapt the active theme to their preferences.

  3. Extended coverage for even more faces and face groups, adding to the already comprehensive list of directly supported ones.

  4. Lots of tweaks to improve the use of colour and avoid exaggerations (well, “exaggerations” is relative, since the prior state was already carefully designed).

  5. A new page hosts all pictures that demo the themes across a wide range of scenaria: https://protesilaos.com/emacs/modus-themes-pictures.

  6. Similarly, the change log also has its own dedicated web page: https://protesilaos.com/emacs/modus-themes-changelog.

New customisation options

Note that all customisation options are documented at length in the new Info manual. What is offered here is not necessarily exhaustive.

Diff styles

Symbol names (“choice” type):

  • modus-operandi-theme-diffs
  • modus-vivendi-theme-diffs

Possible values:

  1. nil (default)
  2. desaturated
  3. fg-only

DEPRECATED (“boolean” type):

  • modus-operandi-theme-subtle-diffs
  • modus-vivendi-theme-subtle-diffs

This option supersedes older ones while retaining their functionality.

The default remains unaltered, meaning that the diffs will use fairly prominent colour-coded combinations for the various elements (e.g. green text on an unambiguously green backdrop).

A desatured value will tone down the default aesthetic, giving a less vibrant feel.

While fg-only removes almost all coloured backgrounds, opting to apply colour only to the relevant text (this was the case with the now-deprecated options). There are some exceptions, like word-wise or “refined” diffs, which still use coloured backgrounds to convey their meaning.

Modeline styles

Symbol names (“choice” type):

  • modus-operandi-theme-mode-line
  • modus-vivendi-theme-mode-line

Possible values:

  1. nil (default)
  2. 3d
  3. moody

DEPRECATED (“boolean” type):

  • modus-operandi-theme-3d-modeline
  • modus-vivendi-theme-3d-modeline

The default modeline continues to be a two-dimensional rectangle with a border around it. Active and inactive modelines use different colour combinations for their main background and foreground.

Option 3d produces an effect similar to what you get in a generic Emacs session, where the active modeline has a pseudo three-dimensional effect applied to it. This option offers the same functionality as that of the deprecated variables.

Option moody is designed specifically for use with the Moody library, though it can also be used without it. Instead of implementing a box effect, it applies an overline and underline instead, while also toning down the inactive modeline.

Thanks to Nicolas De Jaeghere for the feedback and code samples in issue 80: https://gitlab.com/protesilaos/modus-themes/-/issues/80

Headline styles

Symbol names (“alist” type):

  • modus-operandi-theme-headings
  • modus-vivendi-theme-headings

DEPRECATED (“boolean” type):

  • modus-operandi-theme-rainbow-headings
  • modus-operandi-theme-section-headings
  • modus-vivendi-theme-rainbow-headings
  • modus-vivendi-theme-section-headings

Possible values, which can be specified for each heading level (examples further below):

  1. nil (default fallback option—covers all heading levels)
  2. t (default style for a single heading, when the fallback differs)
  3. no-bold
  4. line
  5. line-no-bold
  6. rainbow
  7. rainbow-line
  8. rainbow-line-no-bold
  9. highlight
  10. highlight-no-bold
  11. rainbow-highlight
  12. rainbow-highlight-no-bold
  13. section
  14. section-no-bold
  15. rainbow-section
  16. rainbow-section-no-bold

This supersedes and greatly expands upon what the deprecated variables once offered. It is now possible to (i) benefit from more stylistic choices, and (ii) apply them on a per-level basis.

As always, the defaults remain in tact: headings are just rendered in a bold weight and their colours are not too saturated to offer a plain text impression that relies on typography to convey its meaning.

The info manual explains the details. A few examples:

;; Per-level styles (t means everything else)
(setq modus-operandi-theme-headings
      '((1 . highlight)
        (2 . line)
        (t . rainbow-line-no-bold)))

;; Uniform style for all levels
(setq modus-operandi-theme-headings
      '((t . rainbow-line-no-bold)))

;; Default style for level 1, while others differ
(setq modus-operandi-theme-headings
      '((1 . t)
        (2 . line)
        (t . rainbow-line-no-bold)))

Thanks to Adam Spiers for the feedback in issue 81: https://gitlab.com/protesilaos/modus-themes/-/issues/81. Also thanks to Nicolas De Jaeghere for helping refine relevant stylistic choices: https://gitlab.com/protesilaos/modus-themes/-/issues/90.

No link underlines

Symbol names (“boolean” type):

  • modus-operandi-theme-no-link-underline
  • modus-vivendi-theme-no-link-underline

Possible values:

  1. nil (default)
  2. t

By default, the themes apply an underline effect to links, symbolic links, and buttons. Users can now disable this style by setting the new option to t.

Thanks to Utkarsh Singh for the feedback in issue 94: https://gitlab.com/protesilaos/modus-themes/-/issues/94

No mixed fonts

Symbol names (“boolean” type):

  • modus-operandi-theme-no-mixed-fonts
  • modus-vivendi-theme-no-mixed-fonts

Possible values:

  1. nil (default)
  2. t

By default, the themes configure some spacing-sensitive faces, such as Org tables and code blocks, to always inherit from the fixed-pitch face (documented in the manual). This is to ensure that those constructs remain monospaced when users opt for something like the built-in M-x variable-pitch-mode. Otherwise the layout would break.

The obvious downside with this theme design is that users need to explicitly configure the font family of fixed-pitch in order to apply their desired typeface (how to do this is also covered in the manual). That may be something they do not want to do. Hence this option to disable any kind of font mixing done by the active theme. Set it to t.

Support for new faces or face groups

  • awesome-tray
  • binder
  • cperl-mode
  • eldoc-highlight-function-argument
  • erc escaped colour sequences
  • eshell-syntax-highlighting
  • flycheck-color-mode-line
  • isearch regexp groups (Emacs version >= 28)
  • mpdel
  • objed
  • org 9.4 new faces: org-headline-todo and org-table-header
  • racket-mode
  • typescript-mode

Thanks to:

Refinements to existing faces

  • calfw applies colours and styles in a way that makes it consistent with the rest of the themes’ metaphors.

  • diredfl makes more considerate use of colour. We still apply colour everywhere (the whole point of this package) but make sure to avoid exaggerations.

  • doom-modeline-battery-error face fits better with the rest of the design.

  • elfeed search buffers use less intense colours, while still keeping all elements fairly distinct. The intent is to avoid a “rainbow effect” in such a dense interface.

  • elfeed read and unread items are more distinct.

  • git commit and vc log edit messages benefit from refined colour combinations for their various constructs. The commit’s summary is now rendered in a bold weight, to better convey the idea that this is a quasi heading element.

  • gnus heading colours are more consistent. All information remains clearly distinct, but we now avoid using colours that are on opposite sides of the colour spectrum. Basically to keep things distinct without going over the top.

  • gnus read and unread items are easier to tell apart. Thanks to user “Nick” for reporting the issue: https://gitlab.com/protesilaos/modus-themes/-/issues/97.

  • help-argument-name has a distinct foreground colour, so that it is easier to spot it in “Help” buffers. Its slant is also controlled by the active theme’s customisation option for slanted constructs (nil by default—check the manual).

  • helpful-heading now is consistent with other heading styles. Thanks to Nicolas De Jaeghere for reporting the issue: https://gitlab.com/protesilaos/modus-themes/-/issues/90.

  • icomplete, ido, orderless are all tweaked to work better under various circumstances.

  • info-menu-star uses a red colour to make it easier to select a menu entry by estimating its number. This face applies to every third element and is a nice little extra to have.

  • info quoted strings are configured to always render in fixed-pitch, in line with the themes’ design for mixed fonts (remember to check the relevant customisation option).

  • line numbers work properly with text-scale-adjust. Thanks to user “jixiuf” for reporting the issue: https://gitlab.com/protesilaos/modus-themes/-/issues/98.

  • line-number-current-line no longer applies a bold weight to its text. This is to avoid a certain “jump effect” while moving between lines, where the affected numbers grow and shrink in weight as the line changes (once you see it, you will know what I mean).

  • line-number-major-tick and line-number-minor-tick do use a bold weight because they are fixed on the scale. Their colours are also improved to better complement their intended role (these faces are for Emacs 27 or higher).

  • magit-diff-file-heading-selection, magit-diff-hunk-heading-selection use more appropriate colour combinations.

  • markdown blockquotes and org quote blocks use a different foreground, which is colder than the previous one. Just to make sure that they are not mistaken for inline code.

  • message headers use less exaggerated colour combinations. The differences are fairly minor.

  • message-mml no longer uses a green foreground, as that could potentially cause confusion with quoted text in some cases. A unique, albeit less saturated, foreground is used instead.

  • message-separator uses a more neutral colour combination, while retaining its overall uniqueness within its context (i.e. mail composition).

  • modeline colours are refined to improve the contrast between active and inactive states.

  • mu4e-replied-face has a new colour that accounts for colour distance relative to its context. Thanks to Shreyas Ragavan for reporting the issue: https://gitlab.com/protesilaos/modus-themes/-/issues/69.

  • org agenda date and structure no longer behave like headings in other Org buffers. Instead, they have their own styles to better perform their intended function and to avoid exaggerations.

  • org agenda dimmed to-do items (which have blocked sub-items) are no longer assigned a subtle grey background colour. They are instead rendered with a bold weight and a subtle grey foreground to minimise distractions. Thanks to Roman Rudakov for reporting this in issue 101: https://gitlab.com/protesilaos/modus-themes/-/issues/101.

  • org agenda clocked items are configured to extend their background to the edge of the window. Otherwise they are cut off at the last text character, which creates inconsistencies while using tags: a tag is placed to the right so the background extends further than without them. Based again on the feedback of Roman Rudakov in issue 101: https://gitlab.com/protesilaos/modus-themes/-/issues/101.

  • org agenda current time no longer uses a background. A bold weight and a blue foreground are applied instead. The intent is to keep things clean. This is also covered by Roman Rudakov’s feedback in issue 101: https://gitlab.com/protesilaos/modus-themes/-/issues/101.

  • org-checkbox-statistics-done, org-checkbox-statistics-todo inherit from org-done and org-todo respectively, instead of defining their own properties.

  • org drawers and their data now use fixed-pitch in the interest of consistency with other metadata-like faces. Thanks (yet again!) to Nicolas De Jaeghere for reporting the issue: https://gitlab.com/protesilaos/modus-themes/-/issues/91.

  • org-footnote underlines will now always use the same colour, instead of applying the one of other coloured constructs (e.g. when the footnote is inline and part of the text is rendered as verbatim).

  • org-meta-line is less prominent and, thus, more consistent with other metadata-related constructs.

  • org-roam faces are updated to match the current state of the upstream project. The main colour of org-roam links is now different than that of standard links in an attempt to differentiate between the two (due to their unique semantics). If this is not desired, you can evaluate the following:

    (setq org-roam-link-use-custom-faces nil)

  • org-todo, org-done, as well as relevant faces such as priorities and statistics are reviewed to work better with all heading combinations. Though please read the next section about “adaptive headings”, as such workarounds will no longer be necessary for future stable releases of Org.

  • selectrum uses different styles than before to account for its unique property of overlaying matching characters on top of the current line’s background. We want to avoid scenaria where matches are difficult to discern and the current line is not clear.

  • vc modeline states benefit from improved colour choices. Just minor adjustments to account for the review of the base modeline colours.

  • vterm base colours now are variants of gray to ensure that some tools, such as zsh suggestions work properly. Thanks to user “jixiuf” for reporting this issue and suggesting a possible solution: https://gitlab.com/protesilaos/modus-themes/-/issues/93.

Contributions to the wider community

Sometimes the themes reveal bugs in other packages. It is of paramount importance that we report those to the upstream developers, try to help them reproduce the issue, and, where possible, support them in tracing the problem’s root cause.

Four such cases during this release:

  1. Adaptive Org headings. Solved upstream and documented on my website: https://protesilaos.com/codelog/2020-09-24-org-headings-adapt/. Reported and discussed on the themes’ issue tracker: https://gitlab.com/protesilaos/modus-themes/-/issues/37.

  2. Alignment of Org tags with proportional fonts. Ongoing thread: https://lists.gnu.org/archive/html/emacs-orgmode/2020-09/msg00415.html. Reported and discussed on the themes’ issue tracker: https://gitlab.com/protesilaos/modus-themes/-/issues/85.

  3. Org priority cookie has extra space. Ongoing thread: https://lists.gnu.org/archive/html/emacs-orgmode/2020-09/msg00696.html. Reported and discussed on the themes’ issue tracker, with feedback from Roman Rudakov: https://gitlab.com/protesilaos/modus-themes/-/issues/95.

  4. Company overlay pop-up misaligns items. Reported upstream and acknowledged as a known issue that occurs in certain cases: https://github.com/company-mode/company-mode/issues/1010. Discussion on the themes’ issue tracker, with feedback from Iris Garcia: https://gitlab.com/protesilaos/modus-themes/-/issues/96.

Miscellaneous

  • Belatedly (by about 2 weeks) pushed tag for version 0.12.0. Thanks to Alex Griffin for bringing this to my attention: https://gitlab.com/protesilaos/modus-themes/-/issues/89

  • Fixed a bug with how some older customisation options were declared as obsolete. Thanks to Tassilo Horn for noticing and reporting the problem: https://gitlab.com/protesilaos/modus-themes/-/issues/88.

  • Fixed a misplaced optional prefix argument in the manual for how to switch themes using a custom function. Thanks to Manuel Uberti for catching this omission of mine and reporting it: https://gitlab.com/protesilaos/modus-themes/-/issues/84.

  • Silenced the Elisp package linter for a spurious error on a single eldoc face. Thanks to Steve Purcell for the guidance: https://github.com/purcell/package-lint/issues/187.

  • Defined two new dedicated background colours for exceptional cases. These are intended for internal use in very special circumstances.

  • Reword GuixSD to “Guix System” in the list of package formats currently available.

  • Reviewed the main blue colours for both themes. While the changes are practically impossible to discern upon first sight, the process was far from straightforward. A complete report documents the minutia: https://protesilaos.com/codelog/2020-09-14-modus-themes-review-blues/.

  • Reviewed the “active” palette subset, typically used in the modelines. No report was necessary for those, as the changes were fairly simple.

  • Reviewed the “intense” background colour that comes into effect when users opt for the customisation option for intense paren-match styles (check the manual). Both the hue and the saturation have been changed to better conform with the intended function of this particular entry.

  • Reviewed the fringe-specific accented backgrounds. Commit 7316e3320 contains tables that compare the relative luminance of old and new values.

  • Improved the advice for setting fonts using set-face-attribute. The information is in the manual and is also available as a blog entry: https://protesilaos.com/codelog/2020-09-05-emacs-note-mixed-font-heights/.

  • Rewrote an expression as “(or x y)” instead of “(if x x y)” in one place. Just goes to show that tweaking the code is also part of the deal.

  • Abstracted and simplified heading level properties by using bespoke theme faces. Makes it easier to keep things consistent across the various face groups.

  • Same principle as above for diff-related styles.

  • Users who prefer to do things their own way or who just wish to contribute code to the Modus themes may wish to read my “Notes for aspiring Emacs theme developers”: https://protesilaos.com/codelog/2020-08-28-notes-emacs-theme-devs/.

This has been yet another period of intense work: reviewing faces and applying colours is never easy, adding new customisation options is always tricky, and documenting everything takes a lot of time (unless you do all of those on a whimsy, which hopefully is not the case here).

Thanks again to everyone who helped improve the themes!

Next:
Previous:
See all: Code blog entries