E-mail List Archives
Thread: Is this attempt at increasing contrast for a documentation system any good?
Number of posts in this thread: 6 (In chronological order)
From: Tim Small
Date: Fri, Feb 19 2021 3:18AM
Subject: Is this attempt at increasing contrast for a documentation system any good?
No previous message | Next message →
Sorry if this isn't the best place to ask (if-so, please let me know
what would be!).
I'm trying to improve the accessibility of "mdBook" - which is used to
generate web pages from markdown - mainly for technical documentation.
The system is used extensively to create the documentation for the Rust
programming language, but is also gaining popularity elsewhere.
Unfortunately I personally have no experience of accessibility work (and
very little web or UI work - I mainly work on embedded data collection
devices, and servers), so I'd really appreciate any feedback on this
effort (which is done voluntarily / in my spare time).
Low-contrast text is quite hard for me to read, so initially I'm
focussing on improving the color contrast...
mdBook allows the end-user to choose between a few different color
pallets, but the default "Light" scheme has pretty low contrast.
In the test page below, I've added a "Contrast" theme, which aims to
improve the contrast, without straying far from the "Light" theme||
aesthetic.
Since the system is used for programming language documentation, it
features "syntax highlighting", which uses a variety of colors to
highlight code text blocks. I found it quite challenging making each of
these colors contrast against both the background, and also from each other!
Both themes can be seen on this static html rendering:
https://buttersideup.com/rustbook/ch04-02-references-and-borrowing.html
<https://buttersideup.com/rustbook/ch04-02-references-and-borrowing.html>
... the original "Light" scheme will be displayed by default, and the
"Contrast" theme can be selected with the paintbrush icon (positioned
top-left).
I know that icon itself isn't great (particularly in the "Light" color
scheme!), but the mdBook project maintainer favours making the new
contrast theme the default, so hopefully that will help there too...
Any feedback welcome!
Cheers,
Tim.
From: Patrick H. Lauke
Date: Fri, Feb 19 2021 3:41AM
Subject: Re: Is this attempt at increasing contrast for a documentation system any good?
← Previous message | Next message →
Hey Tim,
had a quick look, and just some random observations:
- yes, it's acceptable to have a style/theme selector to allow users to
switch to a high-contrast set of colors
- if the higher contrast theme is set by default, even better
- even when the other themes are enabled (e.g. Light), the theme
switcher should nonetheless be clearly visible - otherwise, if a user
that has difficulty with low contrast elements lands on a documentation
site where the contrasty theme was not set as default (or somebody else
used the system on that same machine before and set it to something else
with lower contrast), they should be able to find the switch regardless
- otherwise you get into the "yes, we offer a switch to change to better
contrast, but you can't see it because the switch currently has too low
contrast" paradoxical scenarios
- agree that the paintbrush icon may not be immediately clear/obvious to
users
- minor, but the big "The Rust Programming Language" title has slightly
insufficient contrast, even in your higher contrast theme
Unrelated to contrast, might be worth mentioning that this could really
do with a skip link - by default the sidebar seems to be open, meaning
that for a keyboard user reaching the page, they first need to tab
through ALL the links in the left-hand sidebar before reaching the
actual main part / the controls that would allow them to close the
sidebar. Having a skip link before all those links that jumps directly
to the "Toggle the Table of Contents" control would be good (and when
the TOC is closed, that skip link could be removed/made inactive, as
THEN it serves no purpose).
P
--
Patrick H. Lauke
https://www.splintered.co.uk/ | https://github.com/patrickhlauke
https://flickr.com/photos/redux/ | https://www.deviantart.com/redux
twitter: @patrick_h_lauke | skype: patrick_h_lauke
From: glen walker
Date: Fri, Feb 19 2021 10:01AM
Subject: Re: Is this attempt at increasing contrast for a documentation system any good?
← Previous message | Next message →
I was going to point out the same things as Patrick but he's in an earlier
time zone and was able to catch it before me :-)
One other question you asked, or rather, it was a statement and not really
a question:
"Since the system is used for programming language documentation, it
features "syntax highlighting", which uses a variety of colors to highlight
code text blocks. I found it quite challenging making each of
these colors contrast against both the background, and also from each
other!"
Yes, that is a bit tricky. You actually have two accessibility challenges
there. One is the contrast of the various text colors to the light gray
background and the other is that the different colors are conveying
information that a color deficient user might not see. The WCAG
requirement for the use of color might come into play. It's 1.4.1 "Color
is not used as the only visual means of conveying information..." (
https://www.w3.org/TR/WCAG21/#use-of-color).
The code block shows function names in blue, strings in green, declarative
words in purple, etc. Color is being used to convey information but there
are only so many other non-color things you can do. Some could be bold (in
addition to being blue), some could be italic (in addition to being green),
some could be underlined (in addition to being purple), etc. And you could
have combinations, such as bold and italic in addition to dark red. But
the "information" being conveyed by color in the code blocks is not that
important (in my opinion - as a developer myself). While color is nice to
make scanning the code quicker, sometimes I find all the color changes very
distracting and I go back to monochrome.
So I would recommend:
1. Try to have sufficient contrast for the various colors for the different
parts of the language (your "contrast" theme)
2. Provide another theme that has bold, italic, underline, either in
addition to the color or instead of the color (or both - two themes)
3. Provide a theme that doesn't have color (monochrome) in case colors are
distracting. And based on what you do for #2, the monochrome could have
bold, italic, underline.
I like your "contrast" theme. It's easier for me to read.
Glen
From: Tim Small
Date: Mon, Feb 22 2021 3:29AM
Subject: Re: Is this attempt at increasing contrast for a documentation system any good?
← Previous message | Next message →
Hi Patrick,
Thanks for the feedback, much appreciated! The maintainer of the
project currently supports replacing the default 'light' theme entirely
with the new theme, so hopefully the controls issue will be addressed by
that.
For the title, that was a slight nag of mine too, so I'll try either
increasing the contrast a bit further on that item or otherwise changing
the size or weight...
I'll have a dig into the keyboard navigation stuff, thanks!
Tim.
From: Patrick H. Lauke
Date: Mon, Feb 22 2021 4:12AM
Subject: Re: Is this attempt at increasing contrast for a documentation system any good?
← Previous message | Next message →
On 22/02/2021 10:29, Tim Small wrote:
> The maintainer of the
> project currently supports replacing the default 'light' theme entirely
> with the new theme, so hopefully the controls issue will be addressed by
> that.
Just to clarify what I meant: the control for the theme switcher should
have sufficiently strong contrast in *any* theme.
But yeah, sounds good! Great to see this sort of direct involvement on
making the tiny things that make the big difference.
P
--
Patrick H. Lauke
https://www.splintered.co.uk/ | https://github.com/patrickhlauke
https://flickr.com/photos/redux/ | https://www.deviantart.com/redux
twitter: @patrick_h_lauke | skype: patrick_h_lauke
From: Tim Small
Date: Mon, Feb 22 2021 4:41AM
Subject: Re: Is this attempt at increasing contrast for a documentation system any good?
← Previous message | No next message
Hi Glen,
Thanks for the feedback, I'll have a go at creating a less
colour-dependant theme too.
Tim.