<dl class="switch"> styling is not optimal for screen reader users

[zcorpan]

https://github.com/whatwg/whatwg.org/blob/master/resources.whatwg.org/standard.css#L168

A <dl class="switch"> in specs represents a switch statement in programming languages. For stylistic reasons we use an arrow character as generated content before each dt.

Example: https://dom.spec.whatwg.org/#dom-node-nodetype

This renders as "rightwards arrow with hook" in screen readers, according to @mcking65, which is annoying and makes it hard to follow.

It would be better if it read as "Case:"

Maybe also the <dl> itself could be introduced with "Switch:" (possibly both visually and in screen readers).

So I think there are a few options. Either we change the styling so that the text "Case:" is rendered for everyone. Or, if we don't want to change the visual rendering, we can use a custom font with a ligature that turns "Case:" into a “↪" glyph.

It would be nice to make this change for all specs that use this pattern (I'm aware of WHATWG specs and W3C specs), so they are consistent and accessible. cc @fantasai

[annevk]

Are dt/dd announced in a way that might be sufficient if we consistently lead with "switching"?

[zcorpan]

It probably depends on the screen reader, but I'm under the impression that they typically don't do much to indicate what is what in a dl, so it reads like a flat series of paragraphs.

cc @stevefaulkner

[annevk]

If that's true we might have a bigger issue here.

[stevefaulkner]

Recent testing by @gezlemon on description lists:

I tested description lists using JAWS (with Chrome, Firefox, IE, and Edge), NVDA (with Chrome, Firefox, IE, and Edge), VoiceOver on Safari (OSX and iOS), and TalkBack/Chrome on an Android. They all conveyed the list semantics correctly, with some subtle differences.
JAWS (with all browser combinations except Edge), TalkBack/Chrome, and VoiceOver/Safari on OSX indicate the list size as the number of dt items included in the list.
NVDA (with all browser combinations) and JAWS/Edge announce the sum of the number of dt and dd elements in the list.
VoiceOver/Safari on iOS doesn't announce the number of items in the list, but doesn't for any type of list. It does announce the dt at a higher frequency than the dd to denote the name/value pair relationship.

[mcking65]

The main problem to solve here is that the dt elements, because of the generated content, are all read starting with the phrase "Right arrow with hook". It is really difficult to focus on the actual content when that is announced at the start of each dt. It is also a rather strange thing to hear. I had no idea why I was hearing it until I looked at the code. When I saw class switch, then I got the idea that the dl was meant to represent a switch statement.

I think Simon's idea of substituting the unicode char with the string "case: " for screen reader users would be a significant improvement. I hope we could just go forward with that as a first step.

Beyond that, I don't think we should do anything to the dl element unless you are also doing something visual that makes it more clear to sightees that the dl represents a switch. If that is the case, I'm not sure what you would do. I don't know if we expect all screen reader users to be familiar with the concept of a switch statement in programming. So, using that word, or anything like it, could creat confusion. That said, this dl construct may not be the most effective presentation if the content is intended for an audience that includes people who do not have software development experience.

[domenic]

It looks like this is exactly the case that https://drafts.csswg.org/css-content/#alt is meant to solve. Although browser support there is not great (upcoming Chrome, and a prefixed variant in Safari) it would be very easy to deploy, with just a one or two line change. We could do that ASAP and then work on a custom ligature font or similar afterward?

[sideshowbarker]

So I think there are a few options. Either we change the styling so that the text "Case:" is rendered for everyone.

I believe we should do that. Rationale: it’s objectively a less-ambiguous way to convey the information to everyone (not just screen-reader users) than the “↪" glyph is — and I think we should always place greater weight on any choice that avoids or reduces ambiguity.

Or, if we don't want to change the visual rendering, we can use a custom font with a ligature that turns "Case:" into a “↪" glyph.

Stepping back and thinking about it, Is there anyone who feels strongly the current visual rendering with the “↪" glyph is actually preferable? If so, it’d be useful to have them comment here to say why.

Trying to consider it objectively now, I think the “↪" glyph presentation is just an idiosyncrasy — an unnecessary and unhelpful one. It has always been a quirky (mis)feature of the spec — it doesn’t align with how switch statements are presented in any other specs or documentation I can recall, at least.

A few more comments

It’s not clear to me at least why to begin with, the choice was made to use the “↪" glyph instead of just using as “Case:” prefix. It’s just, that’s the way it’s always been for a long time now. I don’t recall there ever having been a discussion about it originally, where any clear agreement emerged that it as clearly preferable for some reason.

I think it’s worth noting that the places where these switch statements are used in the spec are almost always (or maybe even always, actually) in parts of the spec that are only for implementors — and the implementors understand what the “↪" glyph is meant to convey, including implementors who use screen readers. That is, those parts of the spec really aren’t intended for casual readers, so it could be argued that the ambiguity of what the “↪" glyph is meant to convey doesn’t cause that much confusion in practice.

But even that said, even given the fact that implementors are the intended readers, I can’t say I know of any other place in any programming language or programming-language documentation where I have ever seen this “↪" glyph presentation used.

But another point I want to add is that I have actually had occasion more than once to cite switch-statement parts of spec even to non-implementors.

Specifically, there are times when I’ve come across questions posted to Stack Overflow, from developers who are confused about some browser behavior they’re running into, and wanting to know if it’s a browser bug or instead is actually behavior required by whatever relevant spec — and if so, what spec and what specific part of that spec.

So in responding to those questions, I have sometimes (block)quoted parts of particular switch statements from specs. And there is at least once case I can remember when someone replied to ask what the “↪" glyph meant, and I needed to explain to them that the spec text I quoted was part of a switch statement.

So to me that’s concrete evidence we’d be better off if we changed the presentation to make it more explicit and unambiguous that those spec parts are actually switch statements.

[annevk]

The audience is very much software developers. It's not clear to me we need a glyph or "Case:" though. E.g., https://html.spec.whatwg.org/#update-the-session-history-with-the-new-page has neither at the moment and is also understandable.

Even though we've had this styling and class for over a decade it seems fine to me to reconsider whether we need it at all.

[sideshowbarker]

Even though we've had this styling and class for over a decade it seems fine to me to reconsider whether we need it at all.

Good point. So, to look a concrete case: given https://dom.spec.whatwg.org/#dom-node-nodetype,

The nodeType attribute’s getter, when invoked, must return the first matching statement, switching on the context object:

↪Element

ELEMENT_NODE (1)

↪Attr

ATTRIBUTE_NODE (2);

…

…what would you change there?

---

A couple possibilities at the extremes:

1. Just drop the “↪" glyph but otherwise add nothing else, and change nothing else.

   The nodeType attribute’s getter, when invoked, must return the first matching statement, switching on the context object:

   Element

   ELEMENT_NODE (1)

   Attr

   ATTRIBUTE_NODE (2);

2. Adjust the language of the preface to the list, and add more actual prose to each item:

   The nodeType attribute’s getter, when invoked, must return the node type indicated for the first condition the context object matches in the following list of conditions:

   If the context object is an Element

   Return an ELEMENT_NODE (1)

   If the context object is an Attr

   Return an ATTRIBUTE_NODE (2);

#2 seems like the way to write is that’d be the most clear — but also obviously a lot more verbose, with a lot of redundant language. Kind similar to how, in a programming language, using an if-then-else statement that has lot of else conditions ends up being a lot more verbose than a switch statement.

Given that, maybe a “Case:” prefix can have similar utility for reducing the possible verbosity while at the same time clearly conveying to readers — without readers needing to scroll back to the prefatory text at the top of list — that what they’re looking at is a series of (compactly-stated) conditions:

The nodeType attribute’s getter, when invoked, must return the first matching statement, switching on the context object:

Case: Element

ELEMENT_NODE (1)

Case: Attr

ATTRIBUTE_NODE (2);

[annevk]

Thanks, I hope we can consider 2 a non-starter. (I'm not necessarily sure it's even more clear, as the verbosity makes it harder to scan.)

I guess I'm okay with 3, if we don't have to add "Case:" manually all over as editors, but I personally prefer 1.

[zcorpan]

As for the audience, this construct is used more widely than WHATWG specs. The case that @mcking65 found annoying to read with a screen reader was https://w3c.github.io/aria-practices/#name_calculation (which I wrote), which has web developers as target audience.

I think omitting the symbol or "Case:" is likely clear enough in many cases, but when there are multiple dts for a single dd I think it can help clarify what the intended meaning is (I've witnessed confusion about this recently as well).

So my preference is to change the styling to 3 (for all specs), and editors can decide to drop the switch class when it's clear anyway and it doesn't need to be written as a switch-case construct.

[fantasai]

Styling is ideally optional for understanding a spec; as far as I'm aware, the arrows were intended as a subtle visual hint, not as a replacement for prose that clearly conveys what's going on. If they are removed, the spec should still be understandable. I'd like to avoid spec authors depending on a particular styling and omitting information from the spec prose. (I'd also like to avoid invoking C++'s fall-through semantics.) So I'm not convinced that adding "Case:" in front here is super great.

Wrt multiple DTs per DD, those semantics are defined clearly in the HTML spec, and they apply in many other places, not just switch statements. If someone has a problem understanding what that convention means, it's beyond the scope of how we style switch lists.

If the arrows are objectionable generally, I lean towards either removing the markers entirely or replacing them with some other, less objectionable symbol. If it's just a question of providing a less obnoxious speech rendering, which I sympathize with since visually these markers are intended to be glossed over and reading out the Unicode name is definitely not that, then I'm happy to adjust the styling for speech.

[mcking65]

If it's just a question of providing a less obnoxious speech rendering, which I sympathize with since visually these markers are intended to be glossed over and reading out the Unicode name is definitely not that, then I'm happy to adjust the styling for speech.

If they are basically eye candy, I can definitely say they are not ear candy. Obnoxious is a suitable adjective from my perspective.

One thing that is sad about dl is that screen readers don't really do a good job of conveying the semantics of the structure. So, for this particular class, replacing the unicode character with the string "case: " would make the structure much more understandable for screen reader users.

[annevk]

Except that "case" might make people think of switch constructs in certain languages as fantasai points out, which would be counter-productive.

Maybe if <dl> is bad news in general we should think of alternative constructs.