Improve accessibility of OpenAPI specification documents

[ralfhandl]

Recommendation by @stringtheory

• use Google Lighthouse in the Chrome Developer Tools

Findings

• [x] 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
  • [x] Fall back to current ReSpec default colors and nudge the problematic ones a little
  • The bright green headlines are problematic
  • [x] Choose a different green, see this and the following comment for choices
• [x] Links rely on color to be distinguishable.
  • [x] RFC references - make them bold and underlined?

Additional findings (not strictly accessibility)

• [x] 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
• [x] 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

[stringtheory]

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]

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

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:

Pantone	Hex
7737 C	6BA539
574 C	4E5B31
375 C	97D700

So which ones are correct? I don't want to create a user for accessing https://www.pantone.com/color-finder ☹️

[stringtheory]

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]

Tried both colors and the current one and put them in the next comments.

You can upvote (👍🏻) which one(s) you like most.

[ralfhandl]

Hex: #677C46 https://ralfhandl.github.io/OpenAPI-Specification/oas/latest-a11y-left.html

[ralfhandl]

Hex: #578000 https://ralfhandl.github.io/OpenAPI-Specification/oas/latest-a11y-right.html

[ralfhandl]

Current: https://ralfhandl.github.io/OpenAPI-Specification/oas/latest.html

[lornajane]

The right hand option is chosen.