-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
User guide has several accessibility issues #3071
Comments
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)? |
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. |
@Bukama Could you make the full report available please or provide instructions how to recreate it? |
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. |
Thanks! The empty links come from using this feature: junit5/documentation/documentation.gradle.kts Line 214 in 981c8ec
I guess we could disable it but it's quite useful for linking to specific sections. |
For your information: I've just created one for this specific issue of the default template. asciidoctor/asciidoctor#4381 |
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. |
I just wanted to leave a comment here as note / entry point:
|
@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? |
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 👼 ) . |
Thanks! |
Tonight I tried all the available themes from the rogue theme repo This is the output:
So the 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
So I thought I have to include it this resources block
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. |
@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. |
Thank you @marcphilipp for helping with the setup! As I wanted to keep visual syntax highlighting in place I decided against the basic The other theme I extended was the 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 |
Team decision: Let's go with the light theme. |
The rouge code formatting themes are used by asciidoc, which is used to create the user guide. But the default theme and all overs, except the "bw" theme, will create low color contrast, which can be problematic for people with visual restrictions. Instead of using rouge's "bw" theme a custom theme was created to tackle these issue, because using the "bw" theme there was no visual switch between regular text and code examples. The created theme is a light themes that solves all contrast errors in the user guide. However it can't fix other accessibility problems of the user guide, like missing link textes. Those other problems have to be fixed seperately. Resolves #3071. Co-authored-by: Marc Philipp <mail@marcphilipp.de>
@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.
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 |
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. |
- comments are now dark green instead of gray - method invocations are now dark blue instead of dark green These changes have been checked with the WAVE Evaluation Tool extension in Google Chrome. See ##3071
FYI: I improved the color palette in 3ab4d51. |
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. |
@sbrannen Yeah I'm not a native speaker (and for me rogue is a class in World of Warcraft 🙈 ) |
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:
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.
The text was updated successfully, but these errors were encountered: