Twoslash output is inaccessible

[delucis]

(Reposted from shikijs/twoslash#195)

---

Hey there 👋 I noticed that currently TwoSlash produces inaccessible output.

This issue is not a comprehensive accessibility audit, but I wanted to draw attention to some key issues that would need addressing to make TwoSlash code blocks usable by more users.

The references here are to Web Content Accessibility Guidelines (WCAG) 2.2

Key accessibility failures

Guideline 2.1 Keyboard Accessible

All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes

Twoslash tooltips are only available via mouse/pointer hover, so fails most of WCAG Guideline 2.1 regarding keyboard accessibility: it should be possible for users to access the content of tooltips using only the keyboard.

Guideline 4.1 Compatible

Maximize compatibility with current and future user agents, including assistive technologies.

Twoslash tooltips are not available to screen readers: navigating a code sample using Twoslash, there is no way for screenreaders to access the content of tooltips.

Other details

There are some smaller things like the following, but these are kind of moot given the bigger issues:

1.4.13 Content on Hover or Focus

A mechanism is available to dismiss the additional content without moving pointer hover or keyboard focus, unless the additional content communicates an input error or does not obscure or replace other content;

Tooltip content is not dismissible via a mechanism other than moving the pointer’s hover position.

[antfu]

I am not very familiar with a11y myself - I wonder what would be your solutions in mind?

From my personal point of view, tooltips from Twoslash are usually "additional information" but not the main content, which serves as "good to have" but also okay to go without. I imagine myself as a keyboard user or screen reader; I would not want my focus or reader to be "trapped" inside the tons of type information when reading a code snippet. For example, something like:

const a = Math.min(1, 2)

It can be read as

const a | const a: number | = Math | var Math: Math | An intrinsic object that provides basic mathematics functionality and constants. | (method) Math.min(...values: number[]): number | @param values — Numeric expressions to be evaluated. | (1, 2)

If we make tooltips "accessible" (I use | to make it easier to read - but it would not be there in screenreader)

In a way, I consider the experience much worse. I would rather hide some "secondary, optional information" instead of having a bad UX.

I can be very biased. So I'd love to hear what you suggest we improve.

[delucis]

Thank you for the reply @antfu!

I would not want my focus or reader to be "trapped" inside the tons of type information when reading a code snippet

I think the same concerns about not overwhelming the user apply for all interaction types, so I think this is a bit separate from whether or not to expose the tooltips at all. TwoSlash should ideally be applied thoughtfully as an intentional enhancement of specific relevant terms (rather than applied everywhere), but then its content should still be available to all users.

If designed well, accessible tooltips would not “trap” users, but allow them to skip over or dismiss them easily just like a mouse pointer user can.

If there is a concern that there are too many tabs required to move through a code sample, one option would be a “skip” link at the start of the code snippet tab order that allows a keyboard user to jump to the end of the block.

I use | to make it easier to read - but it would not be there in screenreader

It should be possible to have a screenreader read the text as it does currently but also then read tooltip information on focus. That would avoid breaking up the flow as your example does.

In other words, instead of imagining the content + tooltips as a linear stream of <code-token><tooltip><code-token><tooltip><code-token><tooltip>..., think of it more like how a mouse user scans the code:

<full-code-text> (can be read in one go, skipping tooltip content)
	<tooltip> (read on focus)
	<tooltip> (read on focus)
</full-code-text>

I wonder what would be your solutions in mind?

Given there are two major areas of WCAG in my post above, I think there are also at least two chunks of work/focus.

1. Keyboard support. I might be being naïve about how TwoSlash works, but I think this might be a relatively quick win. If the logic currently applied on pointer hover can also be run on element focus, it would go a long way to improving things. (As a side effect, I think it might also improve touch screen support which is currently not great.)

   Some details that might also need considering:

   • As per the 1.4.13 rule linked above, can a user dismiss a tooltip without moving focus? (e.g. via the Escape key)
   • Once a user tabs and reveals a tooltip, can they then tab into the tooltip to e.g. click a link?
   • If they tab into the tooltip and then dismiss it (e.g. via the Escape key), is focus returned correctly to the associated element that triggered the tooltip.
   • Are there other UX polish things needed once this is implemented? (e.g. maybe the “skip link” idea outlined above)

   (As an aside, in case it’s helpful: a lot of these questions align more closely with the “dialog” role/behaviour set. For example, classic tooltips don’t usually include interactive content, but TwoSlash type overlays can include links to further documentation etc.)

2. Screenreader support. As you noted, this might need some more thought and research to arrive at the best solution and it might impact the output structure. Generally speaking, using an ARIA live region to announce the tooltip would make sense, but that might already be the case? In a quick test with macOS Voice Over, tooltips were announced on hover, so it may be that improved keyboard accessibility also helps resolve screenreader support.