Major changes to the Modus themes (modus-operandi, modus-vivendi)

Major changes to the Modus themes (modus-operandi, modus-vivendi)

[Protesilaos Stavrou]

> branch: master
> commit 8fb33bae32e39f597317eb4857447bb0ea1a4de3
> Author: Protesilaos Stavrou <info@protesilaos.com>
> Commit: Basil L. Contovounesios <contovob@tcd.ie>
> 
>     Pull Modus themes version 1.2.3 from upstream
> 
> branch: master
> commit de602dd7cf76b001244964aa5bbef4d9e08ea62b
> Author: Protesilaos Stavrou <info@protesilaos.com>
> Commit: Basil L. Contovounesios <contovob@tcd.ie>
> 
>     Update Modus themes to their version 1.2.0

Hello everyone,

A few months ago the themes 'modus-operandi' and 'modus-vivendi' became
part of Emacs.  These "Modus themes" are designed to meet the highest
accessibility standard for legibility (WCAG AAA), which is quantified as
a minimum 7:1 rate of contrast in relative luminance between any given
combination of background and foreground colours.  In short: every piece
of text we support should be readable.

The version that was in Emacs until recently was 0.13.0.  In trunk we
now provide the latest release: 1.2.3.  As this is a major transition,
it is pertinent to warn existing users about some breaking yet necessary
changes, as well as inform them about the current state of affairs.


1 Customisation options
-----------------------

In the past the themes were maintained as standalone files.  This meant
that customisations were specific to each theme.  For example:

    (setq modus-operandi-bold-constructs t)
    (setq modus-operandi-slanted-constructs t)

    (setq modus-vivendi-bold-constructs t)
    (setq modus-vivendi-slanted-constructs t)

This was inconvenient for users of both items, while maintaining
separate files was becoming increasingly difficult for development.  The
new version derives the two themes from a common source and thus unifies
their customisation options.  The above variables are replaced by those:

    (setq modus-themes-bold-constructs t)
    (setq modus-themes-slanted-constructs t)

Same principle for all customisations, of which there are plenty (not
everything is a boolean).

The values that could be passed to some older variables have been
revised.  For example, changing the fringe's background intensity used
to be a boolean but now is a choice.  Please consult the themes' manual:

    (info "(modus-themes) Top")

Or go directly to:

    (info "(modus-themes) Customization Options")


2 Palette overrides
-------------------

While all customisation options are unified, there remains one
exception: the alists 'modus-themes-operandi-color-overrides' and
'modus-themes-vivendi-color-overrides'.  Those are specific to the item
they reference.

Both variables are intended for "do-it-yourself" (DIY) cases where the
user wishes to replace some colour values with their own (e.g. to change
the main background colour of 'modus-operandi' from white to a light
ochre).

Again, this topic is expanded upon in the manual and there even are
palette subsets furnished therein that retain the accessibility target,
if one does indeed wish to refashion the themes.


3 Shared functions
------------------

[ All of the following are discussed at length in the manual. ]

Users of both themes can now bind the command 'modus-themes-toggle': it
switches between the two items if either of them is active, else it
prompts with completion for one among them.

To retrieve a single value from the palette of the active Modus theme
one can use 'modus-themes-color'.  There is also a variant called
'modus-themes-color-alts'.  Consult their doc strings.

The macro 'modus-themes-with-colors' can be employed to access all of
the active theme's palette.

The function 'modus-themes-contrast' measures the relative luminance
between two colour values expressed in hexadecimal RGB notation.  It
implements the 'modus-themes-wcag-formula'.[1] Comparing two colours
returns a number which is between 1 and 21.  Our target is 7 or higher.
This is useful on its own, like this:

    (modus-themes-contrast "#ffffff" "#000000")

But also for formulas in Org tables (using 'org-mode' or 'orgtbl-mode'):

    #+begin_src emacs-lisp
    (defalias 'L 'modus-themes-contrast)
    #+end_src

    |         | #ffffff | #f0f0f0 |
    |---------+---------+---------|
    | #8f0075 |    8.66 |    7.60 |
    | #5317ac |   10.07 |    8.83 |
    | #0031a9 |   10.44 |    9.16 |
    #+TBLFM: $2='(L $1 @1$2);%0.2f :: $3='(L $1 @1$3);%0.2f

[1]: <https://www.w3.org/TR/WCAG20-TECHS/G18.html>.


4 Further reading
-----------------

The CHANGELOG of the themes is not distributed with Emacs (development
is still done externally).  Please consult the recent entries on my
website (no javascript required):

+ 1.0.0 :: <https://protesilaos.com/codelog/2020-12-05-modus-themes-1-0-0/>.
+ 1.1.0 :: <https://protesilaos.com/codelog/2021-01-24-modus-themes-1-1-0/>.
+ 1.2.0 :: <https://protesilaos.com/codelog/2021-03-04-modus-themes-1-2-0/>.

These amount to around 7500 words, describing changes that unfolded over
the course of ~400 commits.  Though the aforementioned should be enough
to get you started.


5 Packaging
-----------

Thanks to everyone who participated in bug#45068.

Thanks, in particular, to Basil L. Contovounesios who improved the new
'require-theme' function that the Modus themes rely on, as well as for
addressing some packaging-related shortcomings in my code.  Those were
necessary to make this change happen.

[ Any remaining mistakes are my own. ]

My next task is to prepare a patch for elpa.git so that it remains in
sync with emacs.git.

Thank you for your attention!
Protesilaos or "Prot"

-- 
Protesilaos Stavrou
protesilaos.com

Re: Major changes to the Modus themes (modus-operandi, modus-vivendi)

[Stefan Kangas]

Protesilaos Stavrou <info@protesilaos.com> writes:

> A few months ago the themes 'modus-operandi' and 'modus-vivendi' became
> part of Emacs.  These "Modus themes" are designed to meet the highest
> accessibility standard for legibility (WCAG AAA), which is quantified as
> a minimum 7:1 rate of contrast in relative luminance between any given
> combination of background and foreground colours.  In short: every piece
> of text we support should be readable.

Could we use these principles to improve the default Emacs look?
I'm not necessarily saying that we should overhaul all faces to look
like the modus themes, but perhaps there are some glaring usability
issues we could fix.

BTW, what about the relative luminance difference between adjacent
colours?  Is this something covered by the WCAG AAA, or an aspect you
have otherwise looked into?  I know I reported a bug (that you promptly
fixed) where the difference was too small for comfort in one case.
Admittedly this is the only problem with the modus themes I've seen so
far.

> The version that was in Emacs until recently was 0.13.0.  In trunk we
> now provide the latest release: 1.2.3.

Thanks!  Looking forward to start using this.

Re: Major changes to the Modus themes (modus-operandi, modus-vivendi)

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 6 Mar 2021 10:18:32 -0600
> 
> BTW, what about the relative luminance difference between adjacent
> colours?

We have a feature in place to help us and users deal with this: the
:distant-foreground face attribute.

Re: Major changes to the Modus themes (modus-operandi, modus-vivendi)

[Protesilaos Stavrou]

On 2021-03-06, 10:18 -0600, Stefan Kangas <stefankangas@gmail.com> wrote:

> Protesilaos Stavrou <info@protesilaos.com> writes:
>
>> A few months ago the themes 'modus-operandi' and 'modus-vivendi' became
>> part of Emacs.  These "Modus themes" are designed to meet the highest
>> accessibility standard for legibility (WCAG AAA), which is quantified as
>> a minimum 7:1 rate of contrast in relative luminance between any given
>> combination of background and foreground colours.  In short: every piece
>> of text we support should be readable.
>
> Could we use these principles to improve the default Emacs look?
> I'm not necessarily saying that we should overhaul all faces to look
> like the modus themes, but perhaps there are some glaring usability
> issues we could fix.

We could, though I am not sure we should: there probably are a lot of
users who are content with the current styles.  Perhaps though there are
some isolated cases that we could tweak color values in a spirit of not
"breaking" things.

New faces are always easier in that regard.

What I think would be more impactful in the long run is to incorporate
this principle for the :distant-foreground face property (perhaps with a
concomitant option to set a contrast ratio target, say, 7:1).  Now it
relies on 'color-distance' which does not guard against certain
legibility issues, though it still has its uses.

Of course this is easier for me to write---I cannot actually implement
it, especially if it involves C.

> BTW, what about the relative luminance difference between adjacent
> colours?  Is this something covered by the WCAG AAA, or an aspect you
> have otherwise looked into?

Short answer: no, proximity is not accounted for.  So a green piece of
text and a red one presented next to each other will still be checked
relative to their respective background and not as green:red.

Long answer:

+ To achieve a constant contrast against any given background means that
  all foreground colors are fairly close to each other in terms of their
  lumaninance.  This is by virtue of them standing at about the same
  distance away from the background they are compared with.

  We can test this statement with shades of red and green against white:

     (modus-themes-contrast "#b60000" "#fff")
     ;; 7.02

     (modus-themes-contrast "#006800" "#fff")
     ;; 7.04

     (modus-themes-contrast "#b60000" "#006800")
     ;; 1.002

+ To design for contrast in luminance that accounts for proximity means
  that we must make compromises on the extent of the color palette.  Let
  us lower our target from 7:1 which is the AAA standard to 4.5:1, so
  AA.  We have still created the same scenario as above:

     (modus-themes-contrast "#ee0000" "#fff")
     ;; 4.53
     
     (modus-themes-contrast "#008a00" "#fff")
     ;; 4.53

     (modus-themes-contrast "#ee0000" "#008a00")
     ;; 1.00000

+ To push the contrast between two designated foreground colors well
  above 1:1 we must be prepared to render text that is virtually
  unreadable, ceteris paribus.  Check, for example, how pure yellow and
  a shade red contrast well with each other and then notice how the
  yellow compares to the white background:

     (modus-themes-contrast "#ad0000" "#ffff00")
     ;; 7.04

     (modus-themes-contrast "#ffff00" "#fff")
     ;; 1.07

+ Assuming we find some subset of colors that can (i) be fairly legible,
  even at a lower target than 7:1, and (ii) maintain a constant rate of
  difference in luminance between all possible combinations, we still
  have to face practical problems:

  - Suppose that we have an appropriate blue and a yellow.  We want to
    colorise Org's TODO keywords.  We use yellow for the keyword and
    blue for the heading, or vice versa.  Do we also have an appropriate
    green for the DONE state that is equally good against yellow and
    blue?  (I think that is not possible) And what about varying levels
    of headings?  Should they all be blue or whatever?  This means that
    we will likely put our selves in scenaria where there are too many
    constraints for us to deliver something usable.

I am not ruling out the possibility that a design along those lines is
possible.  Though do not expect it to be easy and do not assume that
relative luminance is the right criterion---especially when you as a
designer do not control every single aspect of those interfaces (or
rather every possible combination of the relevant faces).

Those granted, what I do is to apply colors with contrasting hues next
to each other.  This is not about relative luminance, just hueness.  So
something that has more red in it next to something that is more blue.
Such a task is not exact science and I am willing to address any
shortcomings (it is why I posit that design of this sort stands at the
intersection of art and science).

> I know I reported a bug (that you promptly fixed) where the difference
> was too small for comfort in one case.  Admittedly this is the only
> problem with the modus themes I've seen so far.

And I am prepared to fix other such cases, notwithstanding those that
have been reviewed over the last few months.

There was another case with diffs, which typically assign removed and
added states to variants of red and green respectively.  While this is
expected, those combinations are not suitable for red-green color
deficiency.  So I provided the option for deuteranopia in the
'modus-themes-diffs' variable.  Report with screenshots here:
<https://protesilaos.com/codelog/2021-02-25-modus-themes-diffs-deuteranopia/>.

>> The version that was in Emacs until recently was 0.13.0.  In trunk we
>> now provide the latest release: 1.2.3.
>
> Thanks!  Looking forward to start using this.

You are welcome!

-- 
Protesilaos Stavrou
protesilaos.com

Re: Major changes to the Modus themes (modus-operandi, modus-vivendi)

[Gabriel do Nascimento Ribeiro]

Excellent! Thank you, Prot.