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`
  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
  ---@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
  ---@param highlights Highlights
  ---@param colors ColorScheme
  on_highlights = function(highlights, colors) end,
})

Example Settings and Color 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,
})

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:

    nvim --headless "+lua require('modus-themes.extras').setup()" +qa

  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