Repository navigation
Improve accessibility of OpenAPI specification documents #3946
Description
Recommendation by @stringtheory
- use Google Lighthouse in the Chrome Developer Tools
Findings
- Background and foreground colors do not have a sufficient contrast ratio.
- Syntax highlighting of JSON and YAML: string orange, comment grey, and other colors are too bright
- Fall back to current ReSpec default colors and nudge the problematic ones a little
- The bright green headlines are problematic
- Choose a different green, see this and the following comment for choices
- Syntax highlighting of JSON and YAML: string orange, comment grey, and other colors are too bright
- Links rely on color to be distinguishable.
- RFC references - make them bold and underlined?
Additional findings (not strictly accessibility)
- Inconsistent headline formatting
- h1 and h2 are normal and green
- h3 is bold and black
- h4 is italicized and black
- h5 is small-caps and black
- empty line at start of each code block
Accessible preview: https://ralfhandl.github.io/OpenAPI-Specification/oas/latest-a11y.html
Currently published: https://spec.openapis.org/oas/latest.html
Activity
stringtheory commentedon Jul 10, 2024
Just wanted to throw in some general comments.
@ralfhandl Amazing work using lighthouse and going through.
Agree that the bright green headlines are problematic. Your style guide is also problematic in the way it specs out colors. It is in CMYK - so the colors you are picking from don't even really match. I played with correct conversions here. https://codepen.io/stringtheory/pen/VwJYjWP
I am glad to provide a couple of alternative colors that meet the current spec and also future-proof you to the new spec.
I went up the chain a bit with the Accessibility Spec people - since there is less of a definitive answer on the color formatting for syntax highlighting // and am awaiting to hear back.
For distinguishable links - a very common way to handle them is with an underline. You will have bold for other things in the spec so you don't want to add confusion.
I am swamped until late this week - but glad to go into more detail and help further then - if you don't mind waiting.
ralfhandl commentedon Jul 10, 2024
Thanks, I wondered how the Pantone colors 7737 C, 574 C, and 375 C mentioned in the OpenAPI Style Guide are correctly translated to hex colors.
Trying four different "Pantone to hex" converters on the web I ended up with three different sets of hex colors 😁. The two that agreed are slightly different from your conversion:
So which ones are correct? I don't want to create a user for accessing https://www.pantone.com/color-finder☹️
stringtheory commentedon Aug 1, 2024
In the end, I pulled colors out of the logo graphics file (that did not match the Pantone at all). I have official Pantone conversions - but I actually could not get them to line up with the colors in your graphics files.
https://codepen.io/stringtheory/pen/abgJYmb
I picked 2 options for text options that pass the AA success criteria and work with your color palette.
Different color options read better - but updating your color palette is a bigger discussion / so for now just using a re-colored version of a palette from the logo on your site.
OKLCH: oklch(56% 20% 126)
Hex: #677C46
Contrast Ratio 4.66:1
OKLCH: oklch(45% 36% 129)
Hex: #578000
Contrast Ratio 4.67:1
ralfhandl commentedon Aug 1, 2024
Tried both colors and the current one and put them in the next comments.
You can upvote (👍🏻) which one(s) you like most.
ralfhandl commentedon Aug 2, 2024
Hex: #677C46 https://ralfhandl.github.io/OpenAPI-Specification/oas/latest-a11y-left.html
ralfhandl commentedon Aug 2, 2024
Hex: #578000 https://ralfhandl.github.io/OpenAPI-Specification/oas/latest-a11y-right.html
ralfhandl commentedon Aug 2, 2024
Current: https://ralfhandl.github.io/OpenAPI-Specification/oas/latest.html
lornajane commentedon Aug 8, 2024
The right hand option is chosen.