# modus-themes builds Emacs colour themes around WCAG AAA contrast

> modus-themes is a family of Emacs colour themes whose defining constraint is measurable rather than aesthetic: every foreground and background pair is chosen to meet the highest contrast standard, WCAG AAA, and the palettes are additionally tuned for readers with red-green colour deficiency. Six variants ship in the repository, and since version 5.0.0 other packages can build their own themes on top of them.

**protesilaos/modus-themes** — Highly accessible themes for GNU Emacs, conforming with the highest standard for colour contrast between background and foreground values (WCAG AAA).

- Repository: https://github.com/protesilaos/modus-themes
- Website: https://protesilaos.com/emacs/modus-themes
- Stars: 917 · Forks: 78
- Language: Emacs Lisp
- License: GPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/protesilaos-modus-themes

## The contrast rule is the product

Most Emacs themes are a matter of taste. This one starts from a measurable constraint.
The repository description calls them highly accessible themes for GNU Emacs, conforming with the highest standard for colour contrast between background and foreground values, which is WCAG AAA. The README repeats it and adds a second condition: the themes are also optimised for users with red-green colour deficiency.
That second point is what makes the accessibility claim more than a palette contrast exercise. A theme can pass a contrast ratio test and still be unusable for a reader with deuteranopia, because green and red carry the same luminance but different hue, so a syntax highlighting scheme that distinguishes a keyword from a string by hue alone fails for a fixed fraction of users. The repository contains separate theme files for deuteranopia and tritanopia variants, which is the concrete form that takes.
The contrast standard is also what makes the themes defensible over time. A palette picked by eye drifts, especially when someone adds a new face mode for a package and picks a colour that looks fine on their screen. A palette checked against a ratio does not.
The other stated property is that the themes are very customisable and provide support for a very wide range of packages, and that the manual is detailed so that new users can get started while it also provides custom code for all sorts of more advanced customisations. That combination, a strict accessibility floor plus wide coverage, is the position the project occupies.

## Six variants, and the split between light, dark and tinted

The repository root shows the variants as separate files, and the naming makes the scheme clear.
There are modus-operandi-theme.el and modus-vivendi-theme.el, the two originals, plus a tinted variant of each, and a deuteranopia and a tritanopia variant of each. Six files, plus modus-themes.el which is the package itself, and the documentation in doc/.
Operandi is the light one and vivendi the dark one. The tinted variants are the interesting middle ground, a palette that keeps the contrast guarantee while pulling in a tint rather than sitting on a neutral background, which is a common request from people who find pure black and pure white tiring over a long session.
The colour deficiency variants are full parallel palettes rather than adjustments on top of the base, which is the correct approach. Adjusting a hue in place tends to break the contrast relationships that the base palette was built around, so a proper variant has to be designed against the same constraints from scratch.
The manual publishes a separate colour palette page at proteesilaos.com/emacs/modus-themes-colors and sample pictures at proteesilaos.com/emacs/modus-themes-pictures, so you can see the actual values before installing anything. The changelog is at proteesilaos.com/emacs/modus-themes-changelog, and the package name on GNU ELPA is modus-themes.

## Emacs 28 ships them, and the built-in version is behind

The distribution story is unusual and worth reading carefully.
Since August 2020 the original Modus themes, modus-operandi and modus-vivendi, are built into Emacs version 28 or higher. Emacs 28 ships with modus-themes version 1.6.0. Emacs 29 includes version 3.0.0. Emacs 30 provides a newer, refactored version that thoroughly refashions how the themes are implemented and customized.
And here is the caveat the author puts in plain words: such major versions are not backward-compatible due to the limited resources at his disposal to support multiple versions of Emacs and of the themes across the years.
That sentence explains a lot about how Emacs themes evolve in general. A theme that wants to support many Emacs versions has to avoid new APIs, which freezes it at the level of the oldest supported version, and the moment it does use something newer it stops working on the older ones. The built-in themes are therefore always a version or two behind the repository, and Emacs 30's refactored implementation is a different codebase rather than a newer copy of the same one.
So there is a real choice for a user. You can take the themes that ship with your Emacs and get no updates, or you install the package from GNU ELPA and get the current implementation, at the cost of requiring a recent Emacs.

## Configuring it with use-package

The README's configuration example is a use-package block, and it is worth reading as documentation of the feature set rather than copy and paste.
```elisp
(use-package modus-themes
  :ensure t
  :demand t
  :init
  ;; Starting with version 5.0.0 of the `modus-themes', other packages
  ;; can be built on top to provide their own "Modus" derivatives.
  ;; For example, this is what I do with my `ef-themes' and
  ;; `standard-themes' (starting with versions 2.0.0 and 3.0.0,
  ;; respectively).
  ;;
  ;; The `modus-themes-include-derivatives-mode' makes all Modus
  ;; commands that act on a theme consider all such derivatives, if
  ;; their respective packages are available and have been loaded.
  ;;
```
The key bindings are a single group, and the three commands map to the three obvious actions.
```elisp
  :bind
  (("<f5>" . modus-themes-rotate)
   ("C-<f5>" . modus-themes-select)
   ("M-<f5>" . modus-themes-load-random)
```
Rotate cycles through the palette, select opens the chooser, and load random picks one. The comment in the README notes that if you only care about the Modus themes you do not need to enable the derivatives mode and do not need to install the other theme packages.
The customisation block is where the theme exposes its vocabulary, and the ordering requirement is stated in a comment: all customisations must be evaluated before loading the theme.
```elisp
  :config
  ;; Your customizations here.  All customizations must evaluated
  ;; BEFORE loading the theme.
  (setq modus-themes-to-toggle '(modus-operandi modus-vivendi)
        modus-themes-to-rotate modus-themes-items
        modus-themes-mixed-fonts t
        modus-themes-variable-pitch-ui t
        modus-themes-italic-constructs t
        modus-themes-bold-constructs t
        modus-themes-completions '((t . (bold)))
        modus-themes-prompts '(bold)
```

```elisp
        modus-themes-headings
        '((agenda-structure . (variable-pitch light 2.2))
          (agenda-date . (variable-pitch regular 1.3))
          (t . (regular 1.15))))
```
The variables are individually meaningful. Mixed fonts and variable pitch for the user interface give a lighter reading experience, italic and bold constructs let you distinguish types in code without relying on colour alone, which is the same accessibility discipline applied to type, and the headings list shows that the theme treats the Org and Agenda faces individually rather than as one unit.
The theme itself is loaded at the end.
```elisp
  (modus-themes-load-theme 'modus-operandi))
```

## Other packages can take over the Modus themes entirely

Version 5.0.0 introduced an extension mechanism, and the README describes it as the point of the release.
Starting with version 5.0.0 of the modus-themes, other packages can be built on top to provide their own Modus derivative themes. The manual has a section about building on top of Modus, and the author's own ef-themes and standard-themes are done in this way, at versions 2.0.0 and 3.0.0 respectively.
Two mechanisms make this work. The first is modus-themes-include-derivatives-mode, which makes all Modus commands that act on a theme consider all such derivatives, if their respective packages are available and have been loaded. So once the derivative packages are loaded, rotate and select work across the whole family rather than just the two originals.
The second is more aggressive. The README says those packages can even completely take over from the Modus themes, such that modus-themes-rotate only goes through the Ef themes, and the Ef themes provide the ef-themes-take-over-modus-themes-mode while the Standard themes have the standard-themes-take-over-modus-themes-mode equivalent.
That is a well designed extension point. A theme package that hard codes its own colours is a dead end for downstream users, whereas one that exposes its palette as a base for others becomes a platform, and the list of derivative themes in the README shows that it has become one.

## The palette has been ported to other editors

The README keeps a section of links to other projects, split into three groups, and it is worth reading because it shows how far the palette travels.
The first group is Emacs themes based on Modus, and it is long. There is ef-themes and standard-themes by the author, modus-ewal-theme by Oliwier Czerwiński, modus-flexoki and modus-alabaster by Derek Passen, faff-theme since version 4 by James Ferguson, modus-catpuccin by Magnus Therning, pixel-themes by Lucas, modus-nordic with its night and midnight variants by Ashton Wiersdorf, folio-theme by kn66, modus-vague by Ashish Panigrahi, peppers-theme by Joar von Arndt, foxglove-themes by Vegas Harmon and au-themes by Szymon Wilczek. The list is not exhaustive and new projects are added at the bottom.
The second group is other Emacs packages based on Modus, currently modus-themes-exporter by the author.
The third group is projects inspired by Modus, and here the palette has left Emacs entirely. There is hugo-modus, a theme for the Hugo static site generator that uses colours from the Modus themes. There is modus-themes.nvim, a port for Neovim by Miika Nissi and others. There is zed-modus-themes for the Zed editor by Vitaly Slobodin. There is word-smith, a distraction-free writing setup for Obsidian that includes ports of the Modus themes. There is omarchy-modus-themes, and modus-themes-vim.
The author is careful to say that in linking to these projects he is not endorsing anybody's views, which is the right disclaimer for a list of other people's work.
The spread matters more than the count. A palette that meets a contrast standard in one editor becomes more useful as more editors adopt it, because more people get the accessibility benefit by default.

## GPL version 3, an activity trail, and files aimed at coding agents

The licence is GPL-3.0, with the COPYING file at the root of the tree.
The repository has no GitHub releases, which is normal for a package distributed through GNU ELPA. The last push was on 2026-10-17 and the repository is not archived, so the themes are being worked on.
Two files in the root are worth noting for anyone who works with AI tooling on Emacs configuration. There is an AGENTS.md and a CLAUDE.md, both at the top level, alongside a CHANGELOG.org, a .dir-locals.el and a tests/ directory.
The presence of tests is notable for a theme package, because a theme is mostly data and colour ratios, and colour ratios are exactly the kind of thing a test can assert. The contrast guarantee is a property that can be checked automatically, and a repository with a tests/ directory is a repository where somebody does check it.
The package is available on GNU ELPA, the manual is at proteesilaos.com/emacs/modus-themes, and the source is mirrored on GitHub and GitLab, which is a small courtesy to users whose network or organisation blocks one of the two.

## Conclusion

Adopt modus-themes if you need Emacs colour schemes with a verifiable contrast guarantee, or if you read code with red-green colour deficiency and want a palette that was designed for it rather than adjusted after the fact. Do not expect the version bundled with your Emacs to be current, because Emacs 28 ships 1.6.0 and Emacs 29 ships 3.0.0, and the README states that major versions are not backward-compatible. Before you install, decide whether you want the built-in themes or the package from GNU ELPA, and if you enable modus-themes-include-derivatives-mode, check which derivative theme packages you have loaded, since a take-over mode can change what modus-themes-rotate actually cycles through.

## FAQ

### What is modus-themes?

It is a family of Emacs colour themes built around a single constraint: the themes conform with the highest standard for colour contrast between background and foreground values, WCAG AAA, and are also optimised for users with red-green colour deficiency.

### Which variants does modus-themes ship?

The repository contains modus-operandi and modus-vivendi, each with a tinted variant, a deuteranopia variant and a tritanopia variant, for six theme files in total, alongside modus-themes.el which is the package itself.

### Is modus-themes already included in Emacs?

Yes. Since August 2020 the original Modus themes are built into Emacs version 28 or higher, with version 1.6.0 in Emacs 28 and version 3.0.0 in Emacs 29. Emacs 30 provides a newer, refactored implementation, and the README notes that such major versions are not backward-compatible.

### Can another package build a theme on top of modus-themes?

Yes. Starting with version 5.0.0 other packages can be built on top to provide their own Modus derivative themes, with a section in the manual about building on top of Modus. The ef-themes and standard-themes packages are done that way.

### Where can I find the Modus colours and previews?

The README links a colour palette page at proteesilaos.com/emacs/modus-themes-colors and sample pictures at proteesilaos.com/emacs/modus-themes-pictures, with the manual at proteesilaos.com/emacs/modus-themes and the changelog at proteesilaos.com/emacs/modus-themes-changelog.

## Sources

- [Issues](https://github.com/protesilaos/modus-themes/issues)
- [License: GPL-3.0](https://github.com/protesilaos/modus-themes/blob/main/LICENSE)
- [Project website](https://protesilaos.com/emacs/modus-themes)
- [protesilaos/modus-themes on GitHub](https://github.com/protesilaos/modus-themes)
- [README](https://github.com/protesilaos/modus-themes/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/protesilaos-modus-themes