Review modus-themes-diffs; CHANGE fg-only meaning

Please read the report in issue 183 (includes screenshots):
<https://gitlab.com/protesilaos/modus-themes/-/issues/183>.
This commit is contained in:
Protesilaos Stavrou 2021-04-21 13:12:32 +03:00
parent ffa2809c30
commit aaf6bf8b5c
No known key found for this signature in database
GPG key ID: 99BD6459CD5CA3EA
4 changed files with 181 additions and 194 deletions

View file

@ -91,8 +91,8 @@ demonstration:
modus-themes-region 'bg-only-no-extend
;; Options for `modus-themes-diffs': nil, 'desaturated,
;; 'fg-only, 'bg-only, 'deuteranopia,
modus-themes-diffs 'fg-only
;; 'bg-only, 'deuteranopia, 'fg-only-deuteranopia
modus-themes-diffs 'fg-only-deuteranopia
modus-themes-org-blocks nil ; {nil,'grayscale,'rainbow}
modus-themes-org-habit nil ; {nil,'simplified,'traffic-light}
@ -141,5 +141,5 @@ An Info manual should be distributed with the `modus-themes` package.
Evaluate this form to access it directly:
(info "(modus-themes) Top")
Or visit it at: <https://protesilaos.com/modus-themes>.

View file

@ -48,7 +48,7 @@ does not yet form part of the latest tagged commit, is explicitly marked
as such.
Current development target is 1.4.0-dev. This manual was built on
2021-04-20 16:46 +0300.
2021-04-21 12:47 +0300.
* Menu:
@ -538,8 +538,8 @@ of this manual.
modus-themes-region 'bg-only-no-extend
;; Options for `modus-themes-diffs': nil, 'desaturated,
;; 'fg-only, 'bg-only, 'deuteranopia,
modus-themes-diffs 'fg-only
;; 'bg-only, 'deuteranopia, 'fg-only-deuteranopia
modus-themes-diffs 'fg-only-deuteranopia
modus-themes-org-blocks nil ; {nil,'grayscale,'rainbow}
modus-themes-org-habit nil ; {nil,'simplified,'traffic-light}
@ -1113,49 +1113,40 @@ Symbol: modus-themes-diffs
1. nil (default)
2. desaturated
3. fg-only
4. bg-only
5. deuteranopia
3. bg-only
4. deuteranopia
5. fg-only-deuteranopia (part of 1.4.0-dev)
6. fg-only (became an alias of fg-only-deuteranopia—part of
1.4.0-dev)
By default the themes apply rich coloration to the output of diffs,
such as those of diff-mode, ediff, smerge-mode, and Magit. These
are color combinations of an accented background and foreground so that,
for example, added lines have a pronounced green background with an
appropriate shade of green for the affected text. Word-wise or
“refined” changes follow this pattern but use different shades of those
colors to remain distinct.
The default (nil) uses fairly intense color combinations for diffs,
by applying prominently colored backgrounds, with appropriate
foregrounds.
Option desaturated tones down all relevant color values. It still
combines an accented background with an appropriate foreground, yet its
overall impression is fairly subtle. Refined changes are a bit more
intense to fulfil their intended function, though still less saturated
than default.
Option desaturated follows the same principles as with the default
(nil), though it tones down all relevant colors.
Option fg-only will remove most accented backgrounds and instead
rely on color-coded text to denote changes. For instance, added lines
use a green foreground, while their background is the same as the rest
of the buffer. Word-wise highlights still use a background value which
is, nonetheless, more subtle than its default equivalent.
Option bg-only applies a background but does not override the
texts foreground. This makes it suitable for a non-nil value passed to
diff-font-lock-syntax (note: Magit does not support syntax
highlighting in diffs—last checked on 2021-04-21).
Option bg-only applies color-coded backgrounds but does not
override any syntax highlighting that may be present. This makes it
suitable for use with a non-nil value for diff-font-lock-syntax (which
is the default for diff-mode buffers in Emacs 27 or higher).
Option deuteranopia is like the default (nil) in terms of using
prominently colored backgrounds, except that it also accounts for
red-green color defficiency by replacing all instances of green with
colors on the blue side of the spectrum. Other stylistic changes are
made in the interest of optimizing for such a use-case.
Option deuteranopia optimizes for red-green color deficiency. It
replaces all instances of green with blue variants. This is to ensure
that indicators for “removed” and “added” states are not mistaken for
each other.
Concerning Magit, an extra set of tweaks are introduced for the
effect of highlighting the current diff hunk, so as to remain aligned
with the overall experience of that mode. Expect changes that are
consistent with the overall intent of the aforementioned. Note,
however, that the bg-only option will not deliver the intended results
in Magit diffs because no syntax highlighting is used there (last
checked with Magit version 20201116.1057, though upstream has a plan to
eventually support such a feature—this entry shall be updated
accordingly).
Option fg-only-deuteranopia removes all colored backgrounds, except
from word-wise or refined changes. Instead, it only uses color-coded
foreground values to differentiate between added, removed, and changed
lines. If a background is necessary to denote context, a subtle
grayscale value is applied. The color used for added lines is a variant
of blue to account for red-green color defficiency but also because
green text alone is hard to discern in the diffs context (hard for our
accessibility purposes). The fg-only option that existed in older
versions of the themes is now an alias of fg-only-deuteranopia, in the
interest of backward compatibility.

File: modus-themes.info, Node: Org mode blocks, Next: Org agenda habits, Prev: Diffs, Up: Customization Options
@ -3944,72 +3935,72 @@ Node: Enable and load11238
Node: Sample configuration for use-package13986
Node: Differences between loading and enabling15355
Node: Customization Options17395
Node: Bold constructs22560
Node: Slanted constructs23149
Node: Syntax styles23696
Node: No mixed fonts25334
Node: Link styles26429
Node: Command prompts28003
Node: Mode line29202
Node: Completion UIs32808
Node: Fringes34640
Node: Language checkers35300
Node: Line highlighting37249
Node: Line numbers38777
Node: Matching parentheses39855
Node: Active region40745
Node: Diffs41963
Node: Org mode blocks44510
Node: Org agenda habits45988
Node: Heading styles47823
Node: Scaled headings51925
Node: Scaled heading sizes52528
Node: UI typeface55662
Node: Headings' typeface56508
Node: Advanced customization (do-it-yourself)57132
Node: Per-theme customization settings (DIY)58397
Node: Case-by-case face specs using the themes' palette (DIY)59743
Node: Face specs at scale using the themes' palette (DIY)64207
Node: Remap face with local value (DIY)69024
Node: Override colors (DIY)71487
Node: Override color saturation (DIY)76377
Node: Font configurations for Org and others (DIY)79665
Ref: Font configurations for Org and others (DIY)-Footnote-182053
Node: Custom Org user faces (DIY)82240
Node: Measure color contrast (DIY)85594
Node: Load theme depending on time of day88361
Node: Backdrop for pdf-tools (DIY)89383
Node: A theme-agnostic hook for theme loading (DIY)92139
Node: Face coverage94529
Node: Supported packages94999
Node: Indirectly covered packages101770
Node: Notes for individual packages102253
Node: Note for dimmerel103007
Node: Note for display-fill-column-indicator-mode104453
Node: Note for mmm-modeel background colors106080
Node: Note for prism108464
Node: Note on company-mode overlay pop-up111712
Ref: Note on company-mode overlay pop-up-Footnote-1112399
Ref: Note on company-mode overlay pop-up-Footnote-2112466
Node: Note for ERC escaped color sequences112521
Ref: Note for ERC escaped color sequences-Footnote-1113952
Node: Note for powerline or spaceline114062
Node: Note on SHR colors114478
Node: Note for EWW and Elfeed fonts (SHR fonts)114914
Node: Note for Helm grep115662
Node: Note on vc-annotate-background-mode117154
Node: Note on pdf-tools link hints118041
Node: Contributing120474
Node: Sources of the themes120874
Node: Issues you can help with121612
Node: Patches require copyright assignment to the FSF122812
Node: Acknowledgements125107
Node: Meta127479
Node: GNU Free Documentation License129476
Node: Indices154828
Node: Function index155007
Node: Variable index156244
Node: Concept index158166
Node: Bold constructs22585
Node: Slanted constructs23174
Node: Syntax styles23721
Node: No mixed fonts25359
Node: Link styles26454
Node: Command prompts28028
Node: Mode line29227
Node: Completion UIs32833
Node: Fringes34665
Node: Language checkers35325
Node: Line highlighting37274
Node: Line numbers38802
Node: Matching parentheses39880
Node: Active region40770
Node: Diffs41988
Node: Org mode blocks44039
Node: Org agenda habits45517
Node: Heading styles47352
Node: Scaled headings51454
Node: Scaled heading sizes52057
Node: UI typeface55191
Node: Headings' typeface56037
Node: Advanced customization (do-it-yourself)56661
Node: Per-theme customization settings (DIY)57926
Node: Case-by-case face specs using the themes' palette (DIY)59272
Node: Face specs at scale using the themes' palette (DIY)63736
Node: Remap face with local value (DIY)68553
Node: Override colors (DIY)71016
Node: Override color saturation (DIY)75906
Node: Font configurations for Org and others (DIY)79194
Ref: Font configurations for Org and others (DIY)-Footnote-181582
Node: Custom Org user faces (DIY)81769
Node: Measure color contrast (DIY)85123
Node: Load theme depending on time of day87890
Node: Backdrop for pdf-tools (DIY)88912
Node: A theme-agnostic hook for theme loading (DIY)91668
Node: Face coverage94058
Node: Supported packages94528
Node: Indirectly covered packages101299
Node: Notes for individual packages101782
Node: Note for dimmerel102536
Node: Note for display-fill-column-indicator-mode103982
Node: Note for mmm-modeel background colors105609
Node: Note for prism107993
Node: Note on company-mode overlay pop-up111241
Ref: Note on company-mode overlay pop-up-Footnote-1111928
Ref: Note on company-mode overlay pop-up-Footnote-2111995
Node: Note for ERC escaped color sequences112050
Ref: Note for ERC escaped color sequences-Footnote-1113481
Node: Note for powerline or spaceline113591
Node: Note on SHR colors114007
Node: Note for EWW and Elfeed fonts (SHR fonts)114443
Node: Note for Helm grep115191
Node: Note on vc-annotate-background-mode116683
Node: Note on pdf-tools link hints117570
Node: Contributing120003
Node: Sources of the themes120403
Node: Issues you can help with121141
Node: Patches require copyright assignment to the FSF122341
Node: Acknowledgements124636
Node: Meta127008
Node: GNU Free Documentation License129005
Node: Indices154357
Node: Function index154536
Node: Variable index155773
Node: Concept index157695

End Tag Table

View file

@ -419,8 +419,8 @@ this manual.
modus-themes-region 'bg-only-no-extend
;; Options for `modus-themes-diffs': nil, 'desaturated,
;; 'fg-only, 'bg-only, 'deuteranopia,
modus-themes-diffs 'fg-only
;; 'bg-only, 'deuteranopia, 'fg-only-deuteranopia
modus-themes-diffs 'fg-only-deuteranopia
modus-themes-org-blocks nil ; {nil,'grayscale,'rainbow}
modus-themes-org-habit nil ; {nil,'simplified,'traffic-light}
@ -999,48 +999,39 @@ Possible values:
1. ~nil~ (default)
2. ~desaturated~
3. ~fg-only~
4. ~bg-only~
5. ~deuteranopia~
3. ~bg-only~
4. ~deuteranopia~
5. ~fg-only-deuteranopia~ (part of {{{development-version}}})
6. ~fg-only~ (became an alias of ~fg-only-deuteranopia~---part of
{{{development-version}}})
By default the themes apply rich coloration to the output of diffs, such
as those of ~diff-mode~, ~ediff~, ~smerge-mode~, and Magit. These are
color combinations of an accented background and foreground so that, for
example, added lines have a pronounced green background with an
appropriate shade of green for the affected text. Word-wise or
"refined" changes follow this pattern but use different shades of those
colors to remain distinct.
The default (~nil~) uses fairly intense color combinations for diffs, by
applying prominently colored backgrounds, with appropriate foregrounds.
Option ~desaturated~ tones down all relevant color values. It still
combines an accented background with an appropriate foreground, yet its
overall impression is fairly subtle. Refined changes are a bit more
intense to fulfil their intended function, though still less saturated
than default.
Option ~desaturated~ follows the same principles as with the default
(~nil~), though it tones down all relevant colors.
Option ~fg-only~ will remove most accented backgrounds and instead rely
on color-coded text to denote changes. For instance, added lines use a
green foreground, while their background is the same as the rest of the
buffer. Word-wise highlights still use a background value which is,
nonetheless, more subtle than its default equivalent.
Option ~bg-only~ applies a background but does not override the text's
foreground. This makes it suitable for a non-nil value passed to
~diff-font-lock-syntax~ (note: Magit does not support syntax highlighting
in diffs---last checked on 2021-04-21).
Option ~bg-only~ applies color-coded backgrounds but does not override
any syntax highlighting that may be present. This makes it suitable for
use with a non-nil value for ~diff-font-lock-syntax~ (which is the
default for ~diff-mode~ buffers in Emacs 27 or higher).
Option ~deuteranopia~ is like the default (~nil~) in terms of using
prominently colored backgrounds, except that it also accounts for
red-green color defficiency by replacing all instances of green with
colors on the blue side of the spectrum. Other stylistic changes are
made in the interest of optimizing for such a use-case.
Option ~deuteranopia~ optimizes for red-green color deficiency. It
replaces all instances of green with blue variants. This is to ensure
that indicators for "removed" and "added" states are not mistaken for
each other.
Concerning Magit, an extra set of tweaks are introduced for the effect
of highlighting the current diff hunk, so as to remain aligned with the
overall experience of that mode. Expect changes that are consistent
with the overall intent of the aforementioned. Note, however, that the
~bg-only~ option will not deliver the intended results in Magit diffs
because no syntax highlighting is used there (last checked with Magit
version 20201116.1057, though upstream has a plan to eventually support
such a feature---this entry shall be updated accordingly).
Option ~fg-only-deuteranopia~ removes all colored backgrounds, except from
word-wise or refined changes. Instead, it only uses color-coded
foreground values to differentiate between added, removed, and changed
lines. If a background is necessary to denote context, a subtle
grayscale value is applied. The color used for added lines is a variant
of blue to account for red-green color defficiency but also because
green text alone is hard to discern in the diff's context (hard for our
accessibility purposes). The ~fg-only~ option that existed in older
versions of the themes is now an alias of ~fg-only-deuteranopia~, in the
interest of backward compatibility.
** Option for org-mode block styles
:properties:

View file

@ -5,7 +5,7 @@
;; Author: Protesilaos Stavrou <info@protesilaos.com>
;; URL: https://gitlab.com/protesilaos/modus-themes
;; Version: 1.3.2
;; Last-Modified: <2021-04-20 16:24:50 +0300>
;; Last-Modified: <2021-04-21 12:46:54 +0300>
;; Package-Requires: ((emacs "26.1"))
;; Keywords: faces, theme, accessibility
@ -2046,42 +2046,48 @@ background instead of the standard shade of gray."
:link '(info-link "(modus-themes) Mode line"))
(defcustom modus-themes-diffs nil
"Adjust the overall styles of diffs.
"Adjust the overall style of diffs.
Nil means to use fairly intense color combinations for diffs.
For example, you get a rich green background with a green
foreground for added lines. Word-wise or 'refined' diffs follow
the same pattern but use different shades of those colors to
remain distinct.
The default (nil) uses fairly intense color combinations for
diffs, by applying prominently colored backgrounds, with
appropriate foregrounds.
A `desaturated' value follows the same principles as with the nil
option, while it tones down all relevant colors.
Option `fg-only' will remove all accented backgrounds, except
from word-wise changes. It instead uses color-coded foreground
values to differentiate between added/removed/changed lines. If
a background is necessary, such as with `ediff', then a subtle
grayscale value is used.
Option `desaturated' follows the same principles as with the
default (nil), though it tones down all relevant colors.
Option `bg-only' applies a background but does not override the
text's foreground. This makes it suitable for a non-nil value
passed to `diff-font-lock-syntax' (note: Magit does not support
syntax highlighting in diffs as of 2020-11-25, version
20201116.1057).
syntax highlighting in diffs---last checked on 2021-04-21).
Option `deuteranopia' accounts for red-green color defficiency by
replacing all instances of green with colors on the blue side of
the spectrum. Other stylistic changes are made in the interest
of optimizing for such a use-case."
Option `deuteranopia' is like the default (nil) in terms of using
prominently colored backgrounds, except that it also accounts for
red-green color defficiency by replacing all instances of green
with colors on the blue side of the spectrum. Other stylistic
changes are made in the interest of optimizing for such a
use-case.
Option `fg-only-deuteranopia' removes all colored backgrounds,
except from word-wise or refined changes. Instead, it only uses
color-coded foreground values to differentiate between added,
removed, and changed lines. If a background is necessary to
denote context, a subtle grayscale value is applied. The color
used for added lines is a variant of blue to account for
red-green color defficiency but also because green text alone is
hard to discern in the diff's context (hard for our accessibility
purposes). The `fg-only' option that existed in older versions
of the themes is now an alias of `fg-only-deuteranopia', in the
interest of backward compatibility."
:group 'modus-themes
:package-version '(modus-themes . "1.2.0")
:package-version '(modus-themes . "1.4.0")
:version "28.1"
:type '(choice
(const :format "[%v] %t\n" :tag "Intensely colored backgrounds (default)" nil)
(const :format "[%v] %t\n" :tag "Slightly accented backgrounds with tinted text" desaturated)
(const :format "[%v] %t\n" :tag "No backgrounds, except for refined diffs" fg-only)
(const :format "[%v] %t\n" :tag "Apply color-coded backgrounds; keep syntax colors in tact" bg-only)
(const :format "[%v] %t\n" :tag "Optimized for red-green color defficiency" deuteranopia))
(const :format "[%v] %t\n" :tag "Like the default (nil), though optimized for red-green color defficiency" deuteranopia)
(const :format "[%v] %t\n" :tag "No backgrounds, except for refined diffs" fg-only-deuteranopia)
(const :format "[%v] %t\n" :tag "Alias of `fg-only-deuteranopia' for backward compatibility" fg-only))
:link '(info-link "(modus-themes) Diffs"))
(defcustom modus-themes-completions nil
@ -2714,6 +2720,7 @@ Optional BG-ONLY-FG applies ALTFG else leaves the foreground
unspecified."
(pcase modus-themes-diffs
('fg-only (list :background fg-only-bg :foreground fg-only-fg))
('fg-only-deuteranopia (list :background fg-only-bg :foreground fg-only-fg))
('desaturated (list :background altbg :foreground altfg))
('deuteranopia (list :background (or deuteranbg mainbg) :foreground (or deuteranfg mainfg)))
('bg-only (list :background altbg :foreground (if bg-only-fg altfg 'unspecified)))
@ -2723,20 +2730,12 @@ unspecified."
"Determine whether the DEUTERAN or MAIN color should be used.
This is based on whether `modus-themes-diffs' has the value
`deuteranopia'."
(if (eq modus-themes-diffs 'deuteranopia)
(if (or (eq modus-themes-diffs 'deuteranopia)
(eq modus-themes-diffs 'fg-only-deuteranopia)
(eq modus-themes-diffs 'fg-only))
(list deuteran)
(list main)))
(defun modus-themes--diff-text (fg-only-fg default-fg)
"Like `modus-themes--diff', but only for foregrounds.
FG-ONLY-FG is the foreground that is used when diffs are styled
using only foreground colors. DEFAULT-FG covers all other
cases."
(pcase modus-themes-diffs
('fg-only (list :foreground fg-only-fg))
('bg-only (list :foreground 'unspecified))
(_ (list :foreground default-fg))))
(defun modus-themes--standard-completions (mainfg subtlebg intensebg intensefg)
"Combinations for `modus-themes-completions'.
@ -3054,7 +3053,7 @@ by virtue of calling either of `modus-themes-load-operandi' and
;; intended for `diff-mode' or equivalent
`(modus-themes-diff-added
((,class ,@(modus-themes--diff
bg-main green
bg-main blue-alt-other
bg-diff-focus-added fg-diff-focus-added
green-nuanced-bg fg-diff-added
bg-diff-focus-added-deuteran fg-diff-focus-added-deuteran))))
@ -3070,7 +3069,7 @@ by virtue of calling either of `modus-themes-load-operandi' and
red-nuanced-bg fg-diff-removed))))
`(modus-themes-diff-refine-added
((,class ,@(modus-themes--diff
bg-diff-added fg-diff-added
bg-diff-added-deuteran fg-diff-added-deuteran
bg-diff-refine-added fg-diff-refine-added
bg-diff-focus-added fg-diff-focus-added
bg-diff-refine-added-deuteran fg-diff-refine-added-deuteran))))
@ -3086,7 +3085,7 @@ by virtue of calling either of `modus-themes-load-operandi' and
bg-diff-focus-removed fg-diff-focus-removed))))
`(modus-themes-diff-focus-added
((,class ,@(modus-themes--diff
bg-dim green
bg-dim blue-alt-other
bg-diff-focus-added fg-diff-focus-added
bg-diff-added fg-diff-added
bg-diff-focus-added-deuteran fg-diff-focus-added-deuteran))))
@ -3102,7 +3101,7 @@ by virtue of calling either of `modus-themes-load-operandi' and
bg-diff-removed fg-diff-removed))))
`(modus-themes-diff-heading
((,class ,@(modus-themes--diff
bg-main blue
bg-alt fg-main
bg-diff-heading fg-diff-heading
cyan-nuanced-bg cyan-nuanced-fg
bg-header fg-main
@ -3724,11 +3723,11 @@ by virtue of calling either of `modus-themes-load-operandi' and
;;;;; diff-mode
`(diff-added ((,class :inherit modus-themes-diff-added)))
`(diff-changed ((,class :inherit modus-themes-diff-changed :extend t)))
`(diff-context ((,class ,@(modus-themes--diff-text fg-main fg-unfocused))))
`(diff-context ((,class :foreground ,fg-alt)))
`(diff-error ((,class :inherit modus-themes-intense-red)))
`(diff-file-header ((,class :inherit (bold diff-header))))
`(diff-function ((,class :inherit modus-themes-diff-heading)))
`(diff-header ((,class ,@(modus-themes--diff-text cyan-faint fg-main))))
`(diff-header ((,class :foreground ,fg-main)))
`(diff-hunk-header ((,class :inherit (bold modus-themes-diff-heading))))
`(diff-index ((,class :inherit bold :foreground ,blue-alt)))
`(diff-indicator-added ((,class :inherit (diff-added bold)
@ -4980,7 +4979,7 @@ by virtue of calling either of `modus-themes-load-operandi' and
;; not the highlighted ones. This is because Magit's interaction
;; model relies on highlighting the current diff hunk.
`(magit-diff-added ((,class ,@(modus-themes--diff
bg-main green
bg-main blue-alt-other
bg-diff-added fg-diff-added
green-nuanced-bg fg-diff-added
bg-diff-added-deuteran fg-diff-added-deuteran))))
@ -4994,17 +4993,23 @@ by virtue of calling either of `modus-themes-load-operandi' and
`(magit-diff-context-highlight ((,class ,@(modus-themes--diff
bg-dim fg-dim
bg-inactive fg-inactive
bg-dim fg-alt
bg-dim fg-alt))))
`(magit-diff-file-heading ((,class :inherit bold :foreground ,fg-special-cold)))
`(magit-diff-file-heading-highlight ((,class :inherit (modus-themes-special-cold bold))))
`(magit-diff-file-heading-selection ((,class :inherit modus-themes-refine-cyan)))
;; NOTE: here we break from the pattern of inheriting from the
;; modus-themes-diff-* faces.
`(magit-diff-hunk-heading ((,class :inherit bold :background ,bg-active
:foreground ,fg-inactive)))
`(magit-diff-hunk-heading ((,class :inherit bold
,@(modus-themes--diff
bg-alt fg-alt
bg-active fg-inactive
bg-inactive fg-inactive
bg-inactive fg-inactive
t))))
`(magit-diff-hunk-heading-highlight
((,class :inherit bold
:background ,@(modus-themes--diff-deuteran bg-region bg-diff-heading)
:background ,@(modus-themes--diff-deuteran bg-active bg-diff-heading)
:foreground ,@(modus-themes--diff-deuteran fg-main fg-diff-heading))))
`(magit-diff-hunk-heading-selection ((,class :inherit modus-themes-refine-blue)))
`(magit-diff-hunk-region ((,class :inherit bold)))