Style Your Emacs with the Modus Themes

The Modus Themes are an incredibly configurable pair of high-contrast color themes, one light and one dark, that can make your Emacs experience a lot more enjoyable if you spend the time to learn how to use them.

They were created by Protesilaos Stavrou (also known as Prot) with the goal of producing a set of color themes that conform to the high standards of the Web Content Accessibilty Guidelines’ AAA color contrast rules.

This means that these themes should make it easy to distinguish between important elements on screen, making them much more readable while also reducing eye strain. The themes also provide colors for many useful packages, both built-in and community-authored.

If you’re looking forward to learning about these themes, click 👍 on the video, and if you’ve already used them before, leave a comment letting me know what you think about them!

If you use Emacs 28, the Modus Themes are built in!

Otherwise, the Modus Themes manual has a thorough Installation section which describes multiple ways that you can install it.

The most straightforward way is to use the built-in package.el as this package is available through GNU ELPA:

M-x package-install RET modus-themes RET

The modus-themes package comes with two theme definitions:

• The light theme modus-operandi
• The dark theme modus-vivendi

We can load either of these themes with the load-theme command:

M-x load-theme RET modus-vivendi RET

If you want to make your theme selection permanent, you can open up your init.el file and add the following line:

;; Load modus-vivendi theme and confirm that it is safe
(load-theme 'modus-vivendi t)

If you need more details on how to set up your Emacs configuration file, check out my video The Basics of Emacs Configuration.

Modus Themes Manual: Enable and load

Let’s take a look at the Modus Themes by opening a few different files to see what the default styling looks like. I’ll open an Emacs Lisp file, a file with C language code, and an Org Mode file.

One thing you’ll notice right away is that the theme looks pretty simple! The colors are nice, the styling is subtle, everything using a softer, pastel-like color set while still maintaining good color contrast.

We can easily take a look at the light variant of the theme using the modus-themes-toggle command:

M-x modus-themes-toggle RET

You can use this command any time to switch to the alternate version of the theme!

As I mentioned before, the Modus Themes are highly customizable, unlike many other Emacs themes. Now I’m going to show you how this theme customization works and how to refer to the manual so that you know what to try to find the settings that work best for you.

However, I don’t plan to show you the effect of every possible setting of this theme because the video would be an hour long! I’ll show you a few interesting things you can do as a starting point for your customizations.

The most important thing to keep in mind is that any variables you set to customize the theme must come before the load-theme call in your init.el! This is because the theme pulls values from those variables when it gets loaded. It also means you need to re-load the theme after you change any variables!

Learn more about the Customization Options in the Modus Themes manual.

This is important: The settings available in the built-in version of the Modus Themes in Emacs 28.1 might be different than what you read on the manual website! The themes are constantly being improved so some settings may be different than what I describe in this video.

You have two options:

• When a particular setting doesn’t work, use M-x describe-variable to look at the documentation for the variable, it will tell you what values are supported
• Install the latest version of the package!

One of the easiest ways to make the overall Emacs UI look better is to customize how the Modus Themes styles it.

Some of the things you can easily customize:

• The mode line
• The tab bar
• Buttons (like in the Customization UI)
• Completion interfaces
• Text selections
• Line numbers
• … and a lot more

We will only cover 3 of these in the interest of time!

Let’s face it, the mode line is one of the most ever-present parts of Emacs’ UI, so it makes sense to improve the look of it first.

The modus-themes-mode-line variable makes it possible to customize 3 different aspects of the mode line appearance. Each aspect has specific symbols you use to customize its behavior:

• The border and its appearance: borderless, 3d, moody
• The background color: accented
• The size and padding of the text (some not in 28.1!): height, padding (or padded in 28.1)

You can combine these settings! Other aspects of the Modus Themes are configured in a similar way so it’s important to understand how this works.

;; Using a single aspect
(setq modus-themes-mode-line '(borderless))

;; Using multiple aspects
;(setq modus-themes-mode-line '(accented borderless padded))

I’ll test out these changes by tweaking the setting and then run M-x eval-buffer to re-evaluate all settings and reload the theme.

Let’s also take a look at the UI in the light theme!

Modus Themes Manual: Customizing the mode line

When you select text in Emacs, that is called an “active region.” The Modus Themes provide a variable called modus-themes-region to enable you to change their appearance:

• accented: Use a richer background color for regions
• bg-only: Don’t remove foreground text highlighting inside of active region
• no-extend: Don’t extend the region color to the full width of the window

(setq modus-themes-region '(accented))
;(setq modus-themes-region '(bg-only))
;(setq modus-themes-region '(bg-only no-extend))

Modus Themes Manual: Option for active region

This is a nice option to set if you intend to turn on icomplete-mode for enhanced minibuffer completions or if you want to use community packages like Vertico or Selectrum.

The modus-themes-completions variable can be used to control how completion candidates are highlighted, especially when they match part of your search term:

• nil: No customization
• moderate: Slight customization that isn’t too distracting
• opinionated: Much richer colors

Let’s try these by turning on icomplete-mode to see what they look like:

(setq modus-themes-completions 'minimal)
;(setq modus-themes-completions 'opinionated)

This setting actually allows you to be even more specific about which aspects of the completion UIs you are customizing, so read the manual to learn more about that!

Modus Themes Manual: Options for completion framework aesthetics

Now let’s make the text in our buffers look better too! There are a few useful options to customize here:

• modus-themes-bold-constructs: Set to t to increase the number of bolded syntax elements (like type names)
• modus-themes-italic-constructs: Set to t to increase the number of italicized syntax elements (like comments)
• modus-themes-paren-match: Possible values are bold, intense, underline
• modus-themes-syntax: Possible values are faint, yellow-comments, green-strings, and alt-syntax

I won’t show you the effect of all these possible values, but I will show you the effect of each of the variables so you can decide whether to use them!

(setq modus-themes-bold-constructs t)
;(setq modus-themes-italic-constructs t)
;(setq modus-themes-paren-match '(bold intense underline))
;(setq modus-themes-syntax '(faint))
;(setq modus-themes-syntax '(alt-syntax))
;(setq modus-themes-syntax '(green-strings yellow-comments))

My preference is to not set modus-themes-syntax but to turn on bolded and italicized sections!

There are also a number of interesting ways that you can customize how Org Mode files get displayed:

One of the biggest ways to make your Org Mode files look nicer is to make headings stand out from normal document text using bigger font sizes and different colors.

The modus-themes-headings variable provides a number of ways to customize the display of headers at different levels of the document:

• background: Sets a background color for headings
• overline: Draws a line above the heading
• rainbow: Makes heading text color stand out more and picks a different color per level
• A floating point number that controls the text scale (like 1.5 for 150% of the size of normal text)
• A number of font weight names like bold, semibold, medium, etc (see the documentation for the full list)

You define the set of customizations to use for each heading level and you can also set a default that gets applied to any levels that aren’t specifically configured:

(setq modus-themes-headings
      '((1 . (rainbow overline background 1.4))
        (2 . (rainbow background 1.3))
        (3 . (rainbow bold 1.2))
        (t . (semilight 1.1)))

;; Important!
(setq modus-themes-scale-headings t)

NOTE: You must set modus-themes-scale-headings to t for heading scale factors to work!

Source block colorization can be customized using the modus-themes-org-blocks variable:

• gray-background: Use a subtle gray background for code blocks
• tinted-background: Use colored backgrounds corresponding to source langauge

Let’s a take a look at what code blocks look like before this change and then try out the two settings:

(setq modus-themes-org-blocks 'gray-background)
;(setq modus-themes-org-blocks 'tinted-background)

NOTE: For the tinted-background setting, we’ll need to run M-x org-mode-restart in any Org buffers that are already open to ensure the changes get picked up!

I won’t show examples of this, but I just wanted to make you aware that it’s possible to totally customize the set of colors used by the Modus Themes:

• Overriding specific theme colors
• Override color saturation factors
• Overriding colors by blending with base colors

Keep in mind that some of the techniques discussed in these sections are fairly advanced so I’d try to get as much mileage out of the built-in settings before you dive heavily into automated color overrides.

It’s also worth looking at some of the more advanced customization options to see what else you can do!

There’s plenty more that you can customize with these themes, so do yourself a favor and check out the Modus Themes manual to learn more about all the options.

If you want a quick way to get started, you can copy this configuration as a starting point!

;; Configure the Modus Themes' appearance
(setq modus-themes-mode-line '(accented borderless)
      modus-themes-bold-constructs t
      modus-themes-italic-constructs t
      modus-themes-fringes 'subtle
      modus-themes-tabs-accented t
      modus-themes-paren-match '(bold intense)
      modus-themes-prompts '(bold intense)
      modus-themes-completions 'opinionated
      modus-themes-org-blocks 'tinted-background
      modus-themes-scale-headings t
      modus-themes-region '(bg-only)
      modus-themes-headings
      '((1 . (rainbow overline background 1.4))
        (2 . (rainbow background 1.3))
        (3 . (rainbow bold 1.2))
        (t . (semilight 1.1))))

;; Load the dark theme by default
(load-theme 'modus-vivendi t)

I’d love to see the theme configurations that you come up with! Come share them on the System Crafters Discord or IRC channel! (You may have to accept the SSL certificate warning)