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
  • [ ] Who knows a syntax highlighting scheme that is accessible and similar to the current one?
  • [x] Or fall back to current ReSpec default colors and nudge the problematic ones a little
  • The bright green headlines are problematic
  • [ ] The green is not exactly the one required by the style guide
  • [ ] Switch to plain black (boring) or OAI olive green (military)?
  • [x] We could keep the title in bright green
• [x] Links rely on color to be distinguishable.
  • [x] RFC references - make them bold and underlined?
• [ ] Links do not have a discernible name
  • [ ] Only affects respec-generated Table-of-Content arrows in bottom left corner
• [ ] Touch targets do not have sufficient size or spacing.
  • [ ] Table-of-Content entries for fifth section level are too small

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

Current preview: https://ralfhandl.github.io/OpenAPI-Specification/oas/latest-a11y.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 ☹️