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:
https://github.com/junit-team/junit5/blob/981c8eca51be2144065d9d97d34079a0f8f48e94/documentation/documentation.gradle.kts#L214

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.