08 Nov 2025

In modus-theme 5.0.0 Prot introduced a structured way to build a theme based on modus. Just a few days ago he released version 5.1.0 with some improvements in this area.

The official documentation of how to build on top of the Modus themes is very good. It’s focused on how to make sure your theme fits in with the rest of the “modus universe”. However, after reading it I still didn’t have a good idea of how to get started with my own theme. In case others feel the same way I thought I’d write down how I ended up getting started.

The resulting theme, modus-catppuccin, can be found here.

A little background

I read about how to create a catppuccin-mocha theme using modus-vivendi through modus’ mechanism of overrides. On Reddit someone pointed out that Prot had been working on basing themes on modus and when I checked the state of it he’d just released version 5.0.0. Since I’m using catppuccin themes for pretty much all software with a GUI I thought it could be interesting to see if I could make a modus-based catppuccin theme to replace my use of catppuccin-theme.

I’m writing the rest as if it was a straight and easy journey. It wasn’t! I made a few false starts, each time realising something new about the structure and starting over with a better idea.

Finding a starting point

When reading what Prot had written about modus-themes in general, and about how to create themes based on it, in particular, I found that he’s ported both standard-themes and ef-themes so they now are based on modus. Instead of just using them for inspiration I decided that since standard-themes is so small I might as well use it as my starting point.

Starting

I copied all files of standard-themes to an empty git repository, then I

• deleted all but one of the theme file
• copied the remaining theme file so I had four in total (one for each of the catppuccin flavours)
• renamed constants, variables, and functions so they would match the theme and its flavours
• put the colours into each catppuccin-<flavour>-palette
• emptied the common palette, modus-catppuccin-common-palette-mappings
• made sure that my use of modus-themes-theme was reasonable, in particular the base palette (I based the light flavour on modus-operandi and the three dark flavours on modus-vivendi)

The result can be seen here.

At this point the three theme flavours contained no relevant mappings of their own, so what I had was in practice modus-operandi under a new name and modus-vivendi under three new names.

Adding mappings for catppuccin

By organising the theme flavours the way outlined above I only need to add mappings to modus-catppuccin-common-palette-mappings because

1. each flavour-specific mapping adds its colour palette using the same name (that’s how catppuccin organises its colors too, as seen here)
2. each flavour-specific mapping is combined with the common one
3. any missing mapping is picked up by the underlying theme, modus-operandi or modus-vivendi, so there will be (somewhat) nice colours for everything

I started out with the mappings in the dark standard theme but then I realised that’s not the complete list of available mappings and I started looking at the themes in modus-themes itself.

Current state of modus-catppuccin

I’ve so far defined enough mappings to make it look enough like catppuccin for my use. There are a lot of possible mappings so my plan is to add them over time and use catppuccin-theme for inspiration.