User guide has several accessibility issues

[Bukama]

The JUnit user guide has several, repeating accessibility issues, resulting in not fulfilling the "AA" requirements definied by WCAG (and picked up by laws, e.g. the German BITV 2.0).

According to WAVE analysis there are 205 errors and 1174 contrast errors. After a quick view it seems that all of them go down to two things:

• Empty links: Violates level A requirement "2.4.4 Link Purpose (In Context)" of WCAG
• Very low contrast: Violates level AA requirement "1.4.3 Contrast (Minimum) (Level AA)"

To fix the empty links it's necessary to provide text within the link that describes the functionality and/or target of that link.

To fix the low contrast errors the CSS of the code examples should be adjusted to give a proper contrast. All low contrast errors I randomly checked were located in code examples have a contrast ratio of 4.49:1, but WVAG level AA requires to meet 4.5:1. So only slight adjustments should fix all of these errors. For example changing the current #008080 to #005555 should result in a contrast fulfilling even AAA level.

Of the 98 alerts the 85 layout tables warnings are problematic, as screen readers (like NVDA or JAWS) read out the table structure. also the fact that no valid HTML 5 with navigation and content regions / elements is definied is problematic for users who are in need of screen readers etc. as those tools could not identify the page structure.

[marcphilipp]

Apart from syntax highlighting we're using the default Asiidoctor template/styles. Is there a corresponding issue there (e.g. for the "empty link" issue)?

[Bukama]

When I search in their 700+ open issue for accessibility it comes down to 6 open (and 3 closed). One of them ( asciidoctor/asciidoctor#242 ) topics HTML5 but a little bit other to what I've mentioned. There are no issues for the contrast one.

Of course there is none for the links as a style can't know what links you create.

[marcphilipp]

@Bukama Could you make the full report available please or provide instructions how to recreate it?

[Bukama]

1. Install Wave Evaluation Tool (e.g. Chrome extension).
2. Open JUnit User Guide: https://junit.org/junit5/docs/current/user-guide/
3. Open/Activate WAVE extension. It will analyse the page and create the report.

The report is dynamic so you can click on an issue and the plugin jumps to the certain point of the page, where the issue is placed. I don't know away to export it, but havn't checked in detail to be honest to have the dynamic links.

[marcphilipp]

Thanks!

The empty links come from using this feature:

junit5/documentation/documentation.gradle.kts

Line 214 in 981c8ec

"sectanchors" to true,

I guess we could disable it but it's quite useful for linking to specific sections.

[Bukama]

Apart from syntax highlighting we're using the default Asiidoctor template/styles. Is there a corresponding issue there (e.g. for the "empty link" issue)?

For your information: I've just created one for this specific issue of the default template. asciidoctor/asciidoctor#4381

[Bukama]

According to asciidoc team, asciidoc "only" uses 3rd party syntax highlighter and if users want to change the style they can use a different one. They redirected me to https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/rouge/

in which https://github.com/rouge-ruby/rouge/tree/HEAD/lib/rouge/themes is linked for styling themes. From just looking at the theme codes I can't get an impression how it would fit together, so I think it will be try and error to test which theme fits the general user guide layout and has proper contrast values.

[Bukama]

I just wanted to leave a comment here as note / entry point:

• The default code highlighter is rogue (see comment above)
• It's possibel to use other code styles for rogue, see this theme repo. All entries are three years old - meaning from a time, where less people payed attention to accessibility than today. It must be checked if there is an accissble theme in there.
• It's possible to create own code highlighter or extend existing ones. The example from the asciidoc-docs do this for rogue.

[marcphilipp]

@Bukama Thanks for sharing the results of your research! IIRC we switched to Rogue since it had the best support for highlighting in the generated PDF. Would you have time to try out the built-in options from the theme repo?

[Bukama]

Will try to fine some time for refreshing my fork and trying out to generate the user guide (last look into the JUnit project is ... ah .. long time ago 👼 ) .

[marcphilipp]

Thanks! ./gradlew asciidoctor should do the trick.

[Bukama]

Tonight I tried all the available themes from the rogue theme repo

This is the output:

+-----------------+-----------------+
|      theme      | contrast errors |
+-----------------+-----------------+
| base16rb        |            1191 |
| bw              |               0 |
| colorful        |            7541 |
| github          |            1191 |
| gruvbox         |             824 |
| igor_pro        |            1191 |
| magritte        |            1178 |
| molokai         |            5068 |
| monokai         |            5068 |
| monokai_sublime |            1191 |
| pastie          |             807 |
| thankful_eyes   |             150 |
| tulip           |             150 |
+-----------------+-----------------+

So the bw (black and white) theme solves all contrast errors, but it comes with some not that nice side effect. As its defines white (FFFFFF) as back ground you can't really distinguish between switch from regular documentation to code and back

I tried starting to create a custom theme (with a blue blackground at the start to see if my setup is correct), but up to now I fail include the theme file. The docs say that you have to do

asciidoctor -r ./rouge_themes/custom.rb sample.adoc

So I thought I have to include it this resources block

resources {
  from(sourceDir) {
    include("tocbot-*/**")
    include("resources/themes/rogue_junit.rb")
  }
}

But it does not get picked up (yet). As I'm tired and don't have any further idea why I'll leave it for today.

[marcphilipp]

@Bukama Thanks for trying this out! If you push your temporary branch, I'd be happy to take a look if I can get it to be picked up.

[Bukama]

Thank you @marcphilipp for helping with the setup!

As I wanted to keep visual syntax highlighting in place I decided against the basic bw theme and modified to other themes. The github theme is a theme with light code blocks where I only had to change the color for comments as the grey had a low contrast on the light background. So I had to had to darken it which results in that you can hardly (to be honest I can't) distinguish between comments and regular code (not syntax code), but I think this is totally okay in a user guide like this.

The other theme I extended was the Gruvbox theme which has dark code blocks. Here I had to change the red of the import statements and also the grey of the comments. The differences between regular user guide and all code in the code blocks is stronger than in the light theme above:

Of course some creative people may come to an other solution, but I'm not very creative. I just played a bit with the sliders of the accessibility tools ;)

So now it's you to decide. The PR contains both themes at the moment.

edit: About the other issues I'm not sure if we can fix them. For example the NOTE sections are rendered as tables, but there is not attribute to specify to render it in another way.

[marcphilipp]

Team decision: Let's go with the light theme.

[sbrannen]

@Bukama, is it possible to use something like dark green for comments instead of gray?

When I view the User Guide snapshots, it looks like comments are the same color as normal code, which I find confusing.

[Bukama]

@Bukama, is it possible to use something like dark green for comments instead of gray?

When I view the User Guide snapshots, it looks like comments are the same color as normal code, which I find confusing.

As written in my post above I mentioned that.

So I had to had to darken it which results in that you can hardly (to be honest I can't) distinguish between comments and regular code (not syntax code),

I didn't adjusted any colors after Marc didn't ask for changes. But to come back to your question: In general it should be possible. Should be one of the P_GRAY_0 variables in the theme, but I never found any guide about this when I reviewed the themes (and I'm not very creative in such things so most probably just try some of them).

[sbrannen]

Hi @Bukama,

Thanks for the feedback, and sorry for missing your original comments about the "comment" color.

I'll see if I change it to something reasonable.

[sbrannen]

FYI: I improved the color palette in 3ab4d51.

[sbrannen]

Seeing the two of you referring to "rogue" instead of "rouge" made me chuckle. 😄

Rouge is a color or "any of various cosmetics for coloring the cheeks or lips red".

Whereas, rogue means "one whose behavior resembles that of a rogue elephant in being aberrant or independent".

I know, I know... very similar spellings and easy to confuse.

[Bukama]

@sbrannen Yeah I'm not a native speaker (and for me rogue is a class in World of Warcraft 🙈 )
Thank you for adjusting the colors!