Modus Themes for GNU Emacs

• Overview
• Install and auto-load
  • Install the MELPA packages
    • With `use-package'
  • Manual installation method
  • Load automatically
• Customisation options
• Face coverage
  • Full support
  • Covered but not styled explicitly
  • Help needed
  • Will NOT be supported
• Contributing
• COPYING

Overview

This is a set of accessible themes for GNU Emacs. The contrast ratio between foreground and background values should always be >= 7:1, which conforms with the WCAG AAA accessibility standard. This is the highest standard of its kind.

The Modus themes project consists of two standalone items, one where dark text is cast on a light backdrop (Modus Operandi) and another where light text is displayed against a dark background (Modus Vivendi).

Check the Wiki page with the screen shots. Also note that I demo these themes in my Emacs-related screen casts (though older videos contain earlier, "alpha" versions).

Install and auto-load

Install the MELPA packages

I maintain Modus Operandi (light theme) and Modus Vivendi (dark) as standalone packages in MELPA (and MELPA Stable). Assuming you have configured that repository for your package management needs, you can just run:

M-x package-install RET modus-operandi-theme RET

And/or:

M-x package-install RET modus-vivendi-theme RET

To be clear, that sequence means:

• press `Meta-X'

• type `package-install'

• hit the Return key

• type the name of the package

• hit Return to confirm your choice

With `use-package'

For a declarative approach with use-package, you can write something like this:

(use-package modus-operandi-theme
  :ensure t)

(use-package modus-vivendi-theme
  :ensure t)

Manual installation method

Download the files in this repository ending in *-theme.el and place them in an appropriate directory, such as ~/.emacs.d/themes/. To make sure the filesystem path of your choice is read by Emacs, insert the following in your initialisation file:

(add-to-list 'custom-theme-load-path "~/.emacs.d/themes/")

Load automatically

To load the theme from your Emacs initialisation file use the relevant snippet:

(load-theme 'modus-operandi t)          ; Light theme
(load-theme 'modus-vivendi t)           ; Dark theme

Make sure to remove any other theme that is being loaded, otherwise you might run into unexpected issues.

Customisation options

Both of the Modus themes expose some variables that allow users to tweak the look of the theme. By default, all variables are deactivated, meaning that you need to explicitly opt in.

This is what is available right now (use the ones appropriate to the theme of your choice):

;; Choose to render some code constructs in slanted text (italics).  The
;; default, shown below, is to not use italics, unless it is absolutely
;; necessary.
(setq modus-operandi-theme-slanted-constructs nil)

(setq modus-vivendi-theme-slanted-constructs nil)

;; Use proportionately-spaced fonts (variable-pitch) for headings.  The
;; default is to use whatever font the user has selected, typically a
;; monospaced typeface.
(setq modus-operandi-theme-proportional-fonts nil)

(setq modus-vivendi-theme-proportional-fonts nil)

;; Whether headings should be scaled or have the same height as body
;; text.  The default is to keep everything the same as the base size.
(setq modus-operandi-theme-scale-headings nil)

(setq modus-vivendi-theme-scale-headings nil)

;; Font scale that should apply to headings.  These are the default values.
(setq modus-operandi-theme-scale-1 1.05)
(setq modus-operandi-theme-scale-2 1.1)
(setq modus-operandi-theme-scale-3 1.15)
(setq modus-operandi-theme-scale-4 1.2)

(setq modus-vivendi-theme-scale-1 1.05)
(setq modus-vivendi-theme-scale-2 1.1)
(setq modus-vivendi-theme-scale-3 1.15)
(setq modus-vivendi-theme-scale-4 1.2)

NOTE that all customisation options must be declared before loading the theme, else they will not be parsed and have no effect.

Face coverage

This list will always be updated to reflect the current state of the project. The idea is to offer an overview of the known status of all affected face groups.

Full support

The items with an appended asterisk * tend to have lots of extensions, so the "full support" may not be 100% true…

• all-the-icons

• annotate

• anzu

• apt-sources-list

• artbollocks-mode

• auto-dim-other-buffers

• avy

• ace-window

• calendar

• calfw

• column-enforce-mode

• company-mode*

• company-posframe

• compilation-mode

• completions

• counsel*

• counsel-css

• counsel-notmuch

• counsel-org-capture-string

• cov

• custom (M-x customize)

• dashboard (emacs-dashboard)

• deadgrep

• define-word

• disk-usage

• diff-hl

• diff-mode

• dired

• dired-async

• dired-git-info

• dired-narrow

• dired-subtree

• diredfl

• doom-modeline

• easy-jekyll

• easy-kill

• ediff

• eldoc-box

• elfeed

• emms

• epa

• erc

• eshell

• evil* (evil-mode)

• evil-goggles

• evil-visual-mark-mode

• eww

• eyebrowse

• fancy-dabbrev

• font-lock (generic syntax highlighting)

• flycheck

• flycheck-posframe

• flyspell

• geiser

• git

• git-gutter (and variants)

• gnus

• helm*

• hydra

• ido-mode

• iedit

• info pages

• isearch, occur, etc.

• ivy*

• ivy-posframe

• keycast

• line numbers (display-line-numbers-mode and global variant)

• magit

• markdown-mode

• matching parentheses

• messages

• modeline

• mood-line

• mu4e

• neotree

• org*

• org-journal

• org-noter

• org-recur

• outline-mode

• package (M-x list-packages)

• paren-face

• pass

• persp-mode

• perspective

• powerline

• prodigy

• rainbow-blocks

• rainbow-delimiters

• ruler-mode

• shell-script-mode

• smart-mode-line

• smartparens

• smerge

• speedbar

• swiper

• sx

• term

• transient (pop-up windows like Magit's)

• treemacs

• undo-tree

• vc (built-in mode line status for version control)

• visual-regexp

• wgrep

• which-key

• whitespace-mode

• writegood-mode

• xah-elisp-mode

• xterm-color (and ansi-colors)

• ztree

Plus many other miscellaneous faces that are provided by the out-of-the-box Emacs distribution.

Covered but not styled explicitly

These do not require any extra styles because they are configured to inherit from some basic faces. Please confirm.

• change-log

• comint

• bongo

• log-edit

• rmail

Help needed

These are face groups that I am aware of but do not know how to access or do not actively use. I generally need to see how a face looks in its context before assessing its aesthetics or specific requirements.

Use M-x list-faces-display to get these.

• tty-menu

Note that the themes do provide support for org-mode, but some of these interfaces have been decided based on indirect experience. If you encounter anything that does not "feel right", please let me know.

Will NOT be supported

I have thus far identified a single package that does fit into the overarching objective of this project: solaire. It basically tries to cast a less intense background on the main file-visiting buffers, so that secondary elements like sidebars can have the default (pure white/black) background.

I will only support this package if it ever supports the inverse effect: less intense colours (but still accessible) for supportive interfaces and the intended styles for the content you are actually working on.

Contributing

A few tasks you can help me with, sorted from the most probable to the least likely:

• 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 colour palette.

• Help expand this document or any other piece of documentation.

It would be great if your feedback also includes some screenshots, GIFs, or short videos. Though this is not a requirement.

Whatever you do, please 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 colours. If a compromise is ever necessary between aesthetics and accessibility, it shall always be made in the interest of latter.

COPYING

The Modus Themes are distributed under the terms of the GNU General Public License version 3 or, at your choice, any later version. See the COPYING file distributed in the project's Git repository.