Improvements to Accessibility

[dinonuggies1]

Hello, graphiql maintainers!

GitHub's API team provides an integrated client within GitHub's public web documentation for GraphQL. We're big fans of the tool, and use it as a means for integrators to become more familiar with our GraphQL schema. We've recently upgraded to the latest version of the graphiql package (3.0.5 as of September 18, 2023), and thereby many built in features of the client. This client is one of the most utilized aspects of the GraphQL doc set, so it's highly visible for visitors with GraphQL in mind.

Recently, we've placed a stronger focus on making our web experience more accessible as we strive to become the home for all developers. With that in mind, we believe there are a few improvements that would greatly enhance the experience of developers/users with varying disabilities. 🎉

Here are a few accessibility concerns identified by an internal audit here at GitHub:

1. The elements of the Graphiql explorer pane are not focusable:

In other words, when a user tabs through the explorer pane, each schema component/form element should be focusable

2. The focus order is not logical:

In this instance, the user tabs to the "History", hits enter, and instead of the next tab sequence stepping into the History view, the user is directed to the next button (The Explorer button).

3. There isn't appropriate labels for the form elements of the GraphiQL Explorer pane (i.e: fields, queries, or mutation):

Providing the right aria-label helps people who utilize screen readers.

4. Form elements don't include the role attribute for the GraphiQL Explorer:

** screen reader concern

5. Missing associated label 'Add new' along with the query dropdown.

** screen reader concern

6. The luminosity ratio of the ' " _" ' should be greater than or equal to 4.5:1:

** Update - September 27th, 2023

7. The luminosity ratio for the text within the query editor and results pane doesn't meet the contrast ratio of 4.5:1 for the default light mode or dark mode (Although, Dark mode is closer 👍🏽). I've taken a dive into each element of the query editor in hopes that it'll help shed light on the selectors that require adjustments. 🙏🏽

With Default (Light) Theme

class	foreground color - properties	background color - query editor section	contrast ratio	Meets WCAG AA?	background color - results section	contrast ratio	Meets WCAG AA?
.cm-s-graphiql .cm-keyword { color: hsl(var(--color-primary)) }			4.9:1	✅		4.45:1	❌
.cm-s-graphiql .cm-def { color: hsl(var(--color-tertiary)) }			3.15:1	❌		2.86:1	❌
.cm-s-graphiql .cm-punctuation { color: hsla(var(--color-neutral),var(--alpha-tertiary)) }	alpha = .5		8.77:1	✅		7.97:1	✅
.cm-s-graphiql .cm-variable { color: hsl(var(--color-secondary)) }			4.61:1	✅		4.19:1	❌
.cm-s-graphiql .cm-atom { color: hsl(var(--color-tertiary)) }			3.15:1	❌		2.86:1	❌
.cm-s-graphiql .cm-number { color: hsl(var(--color-success)) }			2.9:1	❌		2.64:1	❌
.cm-s-graphiql .cm-string { color: hsl(var(--color-warning)) }			3.16:1	❌		2.86:1	❌
.cm-s-graphiql .cm-builtin { color: hsl(var(--color-success)) }			2.9:1	❌		2.64:1	❌
.cm-s-graphiql .cm-string-2 { color: hsl(var(--color-secondary)) }			4.61:1	✅		4.19:1	❌
.cm-s-graphiql .cm-attribute,.cm-s-graphiql .cm-meta { color: hsl(var(--color-tertiary)) }			3.15:1	❌		2.86:1	❌
.cm-s-graphiql .cm-property { color: hsl(var(--color-info)) }			4.09:1	❌		3.71:1	❌
.cm-s-graphiql .cm-qualifier { color: hsl(var(--color-secondary)) }			4.61:1	✅		4.19:1	❌
.cm-s-graphiql .cm-comment { color: hsla(var(--color-neutral),var(--alpha-secondary)) }	alpha = .76		8.77:1	✅		7.97:1	✅
.cm-s-graphiql .cm-ws { color: hsla(var(--color-neutral),var(--alpha-tertiary)) }	alpha = .5		8.77:1	✅		7.97:1	✅
.cm-s-graphiql .cm-invalidchar { color: hsl(var(--color-error)) }			3.21:1	❌		2.92:1	❌

With Dark Mode Theme

class	foreground color - properties	background color - query editor section	contrast ratio	Meets WCAG AA?	background color - results section	contrast ratio	Meets WCAG AA?
.cm-s-graphiql .cm-keyword { color: hsl(var(--color-primary)) }			4.82:1	✅		4.07:1	❌
.cm-s-graphiql .cm-def { color: hsl(var(--color-tertiary)) }			6.71:1	✅		5.65:1	✅
.cm-s-graphiql .cm-punctuation { color: hsla(var(--color-neutral)) }			8.02:1	✅		6.76:1	✅
.cm-s-graphiql .cm-variable { color: hsl(var(--color-secondary)) }			4.97:1	✅		4.19:1	❌
.cm-s-graphiql .cm-atom { color: hsl(var(--color-tertiary)) }			6.71:1	✅		5.65:1	✅
.cm-s-graphiql .cm-number { color: hsl(var(--color-success)) }			7.52:1	✅		6.34:1	✅
.cm-s-graphiql .cm-string { color: hsl(var(--color-warning)) }			9.83:1	✅		8.29:1	✅
.cm-s-graphiql .cm-builtin { color: hsl(var(--color-success)) }			7.52:1	✅		6.34:1	✅
.cm-s-graphiql .cm-string-2 { color: hsl(var(--color-secondary)) }			4.97:1	✅		4.19:1	❌
.cm-s-graphiql .cm-attribute,.cm-s-graphiql .cm-meta { color: hsl(var(--color-tertiary)) }			6.71:1	✅		5.65:1	✅
.cm-s-graphiql .cm-property { color: hsl(var(--color-info)) }			7.07:1	✅		5.96:1	✅
.cm-s-graphiql .cm-qualifier { color: hsl(var(--color-secondary)) }			4.97:1	✅		4.19:1	❌
.cm-s-graphiql .cm-comment { color: hsla(var(--color-neutral)) }			8.02:1	✅		6.76:1	✅
.cm-s-graphiql .cm-ws { color: hsla(var(--color-neutral)) }			8.02:1	✅		6.76:1	✅
.cm-s-graphiql .cm-invalidchar { color: hsl(var(--color-error)) }			4.55:1	✅		3.84:1	❌

---

As you can see, most of our accessibility findings stem from the GraphQL Explorer feature, or more specifically, the @graphiql/explorer-plugin package. It could be that these concerns have been addressed in more recent versions of the explorer, however, we encountered some issues upgrading to the latest graphiql package with the explorer package included. We did have success upgrading to version 0.1.4 of the explorer plugin along with 2.0.7 of the graphiql package, but noticed that the same issues remained. If it's confirmed that the above has been addressed in later versions of the explorer plugin, we'd be happy to invest more time into the upgrade, but for the moment, we've decided to omit the explorer feature from the client given the accessibility concerns above.

Lastly, thanks for all the hard work you've put into making this a great tool! 🙏

[Timmmy-nlb]

I would also be happy if the current version is revised and improved again. In the current state, it is simply only aggravated and the simple / fast usability is no longer given.

see too:

https://github.com/orgs/community/discussions/72715#discussioncomment-7408457

[acao]

@dinonuggies1 thank you for this! are you able to do a similar audit of graphiql@2? unfortunately we aren't able to backport these fixes to 1.x because it was a substantial rewrite, and we haven't had a 1.x release in a few years. most of this still applies where the third party explorer is concerned. I have a PR open (#3374) to adopt the explorer into our repo so we can make many of these improvements!

[heiskr]

@acao I believe the GitHub Accessibility team uses https://www.deque.com/axe/devtools/chrome-browser-extension/ to identify accessibility issues.

[acao]

So, we will be rebuilding the explorer components and plugin in the coming months. We did not get permission to inherit the project from the current IP owner, and the original authors are suggesting a rewrite anyways.

A GraphQL Foundation grant came through for someone to work on this explorer rebuild, and we will know if they still can work on it soon.

Until then, I hope to take care of these items this month myself:

1. the 5-10% of items in this list that are not part of the third party graphiql-explorer components
2. any CSS overrides that resolve any of the above issues for graphiql-explorer that can ship via the plugin until the rewrite occurs.

If you would like to help with the explorer rewrite, join us on the discord in the readme!

[xrstf]

Are there any news on this? At the moment the current "explorer" is basically useless to build up queries. What is the alternative I'm supposed to use at the moment?