-._protesilaos-s-_modus_themes_.-/README.org

#+TITLE: Modus Themes for GNU Emacs
#+AUTHOR: Protesilaos Stavrou
#+EMAIL: public@protesilaos.com

* Overview
  :PROPERTIES:
  :CUSTOM_ID: h:d42d56a4-9252-4858-ac8e-3306cdd24e19
  :END:

Accessible themes for GNU Emacs.  The contrast ratio between foreground
and background values should always be >= 7:1, which conforms with the
WCAG AAA accessibility standard.  This is the highest standard of its
kind.

The /Modus/ project consists of two themes, one where dark text is cast
on a light backdrop (Modus Operandi) and another where light text is
displayed against a dark background (Modus Vivendi).

*Check the [[https://gitlab.com/protesilaos/modus-themes/wikis/Screenshots][Wiki page with the screen shots]].* Also note that I demo these
themes in [[https://protesilaos.com/code-casts][my Emacs-related screen casts]] (though older videos contain
earlier "alpha" versions).

* Installation and configuration
  :PROPERTIES:
  :CUSTOM_ID: h:25c3ecd3-8025-414c-9b96-e4d6266c6fe8
  :END:

Packages for MELPA are in the works: one for each theme.  The pull
requests were submitted on 2019-10-31 ([[https://github.com/melpa/melpa/pull/6516][#6516]] and [[https://github.com/melpa/melpa/pull/6517][#6517]]).  This README
will be updated with the relevant instructions once the packages become
available through MELPA.

** Manual method
   :PROPERTIES:
   :CUSTOM_ID: h:0317c29a-3ddb-4a0a-8ffd-16c781733ea2
   :END:

Download the files ending in =*-theme.el= and place them in an
appropriate directory, such as =~/.emacs.d/themes/=.  Then to make sure
that path is read by Emacs, insert the following in your initialisation
file (=.emacs= or =init.el=):

#+BEGIN_SRC emacs-lisp
(add-to-list 'custom-theme-load-path "~/.emacs.d/themes/")
#+END_SRC

** Load automatically
   :PROPERTIES:
   :CUSTOM_ID: h:ae978e05-526f-4509-a007-44a0925b8bce
   :END:

To load the theme of your choice automatically upon Emacs startup add
this to your init file, replacing =NAME= with either =operandi= or
=vivendi=:

#+BEGIN_SRC emacs-lisp
(load-theme 'modus-NAME t)
#+END_SRC

* Face coverage
  :PROPERTIES:
  :CUSTOM_ID: h:944a3bdf-f545-40a0-a26c-b2cec8b2b316
  :END:

This list will be updated to reflect the current state of the project.
The idea is to offer an overview of the /known status/ of all affected
face groups.

** Full support
   :PROPERTIES:
   :CUSTOM_ID: h:5ea98392-1376-43a4-8080-2d42a5b690ef
   :END:

Those with an appended asterisk =*= tend to have lots of extensions, so
the "full support" may not be 100% true…

+ all-the-icons
+ anzu
+ artbollocks-mode
+ auto-dim-other-buffers
+ avy
+ aw
+ company-mode*
+ compilation-mode
+ completions
+ custom (M-x customize)
+ deadgrep
+ diff-hl
+ diff-mode
+ dired-async
+ dired-subtree
+ diredfl
+ elfeed
+ emms
+ epa
+ eshell
+ eww
+ fancy-dabbrev
+ flyspell
+ git/magit
+ git-gutter (and variants)
+ gnus
+ helm*
+ hydra
+ ido-mode
+ info pages
+ isearch, occur, etc.
+ ivy*
+ markdown-mode
+ matching parentheses
+ messages
+ modeline
+ mu4e
+ neotree
+ org-mode*
+ outline-mode
+ pass
+ rainbow-blocks
+ rainbow-delimiters
+ smerge
+ speedbar
+ swiper
+ term
+ treemacs
+ undo-tree
+ visual-regexp
+ which-key
+ whitespace-mode
+ writegood-mode
+ xterm-color (and ansi-colors)
+ ztree

** Covered but not styled explicitly
   :PROPERTIES:
   :CUSTOM_ID: h:8ada963d-046d-4c67-becf-eee18595f902
   :END:

These do not require any extra styles because they are configured to
inherit from some basic faces.  Please confirm.

+ calendar
+ change-log
+ comint
+ bongo
+ log-edit
+ package menu
+ rmail

** Partially supported (need manual intervention)
   :PROPERTIES:
   :CUSTOM_ID: h:4a6831ea-e3ea-47cc-afc4-31ff1215dc2a
   :END:

This section documents known cases where the Modus themes will not be
used to their maximum potential.  Solutions are suggested in context.

*** Ibuffer
    :PROPERTIES:
    :CUSTOM_ID: h:5acef24c-f470-4f91-ab98-b720a2b4e696
    :END:

The default =ibuffer= configurations for denoting the mark and delete
flags are not good enough.  My recommended tweak for those is to let
them inherit the styles of Dired.  Place something like this in your
initialisation file.

#+BEGIN_SRC emacs-lisp
(setq ibuffer-deletion-face 'dired-flagged)
(setq ibuffer-marked-face 'dired-marked)
#+END_SRC

** Help needed
   :PROPERTIES:
   :CUSTOM_ID: h:bcc3f6f9-7ace-4e2a-8dbb-2bf55574dae5
   :END:

These are face groups that I am aware of but do not know how to access
or do not actively use.  I generally need to see how a face looks in its
context before assessing its aesthetics or specific requirements.

Use =M-x list-faces-display= to get these.

+ transient-{argument,key,value}…
+ tty-menu
+ vc-{conflict-state,state-base}…

Note that the themes do provide support for =org-mode=, but some of
these interfaces have been decided based on indirect experience.  If you
encounter anything that does not "feel right", please let me know.

* Contributing
  :PROPERTIES:
  :CUSTOM_ID: h:25ba8d6f-6604-4338-b774-bbe531d467f6
  :END:

A few tasks you can help me with, sorted from the most probable to the
least likely:

+ Suggest refinements to packages that are covered.
+ Report packages not covered thus far.
+ Report bugs, inconsistencies, shortcomings.
+ Help expand the documentation of covered-but-not-styled packages.
+ Suggest refinements to the colour palette.
+ Help expand this document or any other piece of documentation.

It would be great if your feedback also includes some screenshots, GIFs,
or short videos.  Though this is not a requirement.

Whatever you do, please bear in mind the overarching objective of the
Modus themes: to keep a contrast ratio that is greater or equal to 7:1
between background and foreground colours.  If a compromise is ever
necessary between aesthetics and accessibility, it shall always be made
in the interest of latter.

* COPYING
  :PROPERTIES:
  :CUSTOM_ID: h:66652183-2fe0-46cd-b4bb-4121bad78d57
  :END:

The Modus Themes are distributed under the terms of the GNU General
Public License version 3 or, at your choice, any later version.  See the
COPYING file distributed in the [[https://gitlab.com/protesilaos/modus-themes][project's Git repository]].