Highly Accessible Modus Themes for Neovim

GitHub Release CI License WCAG AAA

Highly accessible themes for Neovim, conforming with the highest standard for color contrast between background and foreground values (WCAG AAA). This is a Neovim port of the original Modus Themes built for GNU Emacs.

Modus Themes Preview

Overview

The Modus Themes are designed for accessible readability. They conform with the highest standard for color contrast between background and foreground values. For small sized text, this corresponds to the WCAG AAA standard, which specifies a minimum contrast ratio of at least 7:1, while large sized and bold text have a contrast ratio of at least 4.5:1. Incidental text that is part of an inactive user interface component, or that are for pure decoration, have no contrast requirement.

This is a Neovim port of the original Modus Themes for GNU Emacs, and follows the design philosophy. It is not intended to be an exact 1:1 correspondence with GNU Emacs, but rather follows the spirit of the design and ensures conformity to the WCAG AAA guidelines.

This project is hosted on GitHub. Any issues and contributions should be directed there.

Features

Requirements

Installation

Install the theme with your preferred package manager.

lazy.nvim

{ "miikanissi/modus-themes.nvim", priority = 1000 }

packer.nvim

use({ "miikanissi/modus-themes.nvim" })

vim-plug

Plug 'miikanissi/modus-themes.nvim'

Usage

Lua

vim.cmd([[colorscheme modus]]) -- modus_operandi, modus_vivendi

Vim Script

colorscheme modus " modus_operandi, modus_vivendi

Configuration

Ensure the configuration is set BEFORE loading the color scheme with colorscheme modus.

By default, the theme will choose between light (modus_operandi) and dark (modus_vivendi) based on the background value set with vim.o.background.

If using the default options, there is no need to explicitly call setup.

-- Default options
require("modus-themes").setup({
	-- Theme comes in two styles `modus_operandi` and `modus_vivendi`
	-- `auto` will automatically set style based on background set with vim.o.background
	style = "auto",
	variant = "default", -- Theme comes in four variants `default`, `tinted`, `deuteranopia`, and `tritanopia`
	transparent = false, -- Transparent background (as supported by the terminal)
	dim_inactive = false, -- "non-current" windows are dimmed
	hide_inactive_statusline = false, -- Hide statuslines on inactive windows. Works with the standard **StatusLine**, **LuaLine** and **mini.statusline**
	styles = {
		-- Style to be applied to different syntax groups
		-- Value is any valid attr-list value for `:help nvim_set_hl`
		comments = { italic = true },
		keywords = { italic = true },
		functions = {},
		variables = {},
	},

	--- You can override specific color groups to use other groups or a hex color
	--- Function will be called with a ColorScheme table
	--- Refer to `extras/lua/modus_operandi.lua` or `extras/lua/modus_vivendi.lua` for the ColorScheme table
	---@param colors ColorScheme
	on_colors = function(colors) end,

	--- You can override specific highlights to use other groups or a hex color
	--- Function will be called with a Highlights and ColorScheme table
	--- Refer to `extras/lua/modus_operandi.lua` or `extras/lua/modus_vivendi.lua` for the Highlights and ColorScheme table
	---@param highlights Highlights
	---@param colors ColorScheme
	on_highlights = function(highlights, colors) end,
})

Example Settings with Color and Highlight Overrides

require("modus-themes").setup({
	style = "modus_operandi", -- Always use modus_operandi regardless of `vim.o.background`
	variant = "deuteranopia", -- Use deuteranopia variant
	styles = {
		functions = { italic = true }, -- Enable italics for functions
	},

	on_colors = function(colors)
		colors.error = colors.red_faint -- Change error color to the "faint" variant
	end,
	on_highlights = function(highlight, color)
		highlight.Boolean = { fg = color.green } -- Change Boolean highlight to use the green color
	end,
})

Extras

Contributing

Contributions are welcome. Feel free to create a pull request on GitHub to add support for any missing plugins, or report an issue.

Please ensure the WCAG AAA contrast requirements are met. You can use this contrast checker for reference.

Extras are generated using a template system.

How to create a new extra template:

  1. Create a file such as lua/modus-themes/extras/extra-app.lua.

  2. Add the name and output file extension to the extras table in lua/modus-themes/extras/init.lua.

  3. Run the following command to generate new extras from the Modus Themes plugin directory:

    ./scripts/extras.sh

  4. Ensure the newly created themes in the extras/ directory are correct. Please DO NOT commit them, as they are already automatically built by the CI.

Acknowledgements