[css-counter-styles] Clarification on use of the term "speak-as" and possible alternatives

[dot-miniscule]

The current spec says:

A counter style can be constructed with a meaning that is obvious visually, but impossible to meaningfully represent via a speech synthesizer, or possible but nonsensical when naively read out. The speak-as descriptor describes how to synthesize the spoken form of a counter formatted with the given counter style.

The speak-as descriptor is essentially providing a description of how to resolve the counter style to present it to AT users, which is often a screenreader outputting speech, but not always (for example, braille displays). The name speak-as is therefore slightly misleading, as it won't always be speech, and in any case we don't directly control the speech that a screenreader outputs. We provide it with some text string it uses to make an announcement.

A different name for this descriptor would be more accurate. One option is to use alt, a well known shorthand for "alternative text", meaning the textual representation or description for some visual UI. Since this is well established nomenclature, most devs will probably understand what they are being asked to provide. However, using alt alone might not be sufficient, as this normally implies a fixed text value, whereas in this case it is more like a translation system (resolving the given value in order to synthesize a textual description of the counter style, rather than announcing the value directly). Therefore, it might be more accurate to use something like alt-text-style or text-alt-style (to keep it similar to counter-style).

CSS Counter Styles are shipped in Firefox, and this feature is shipping soon in Chrome, but without support for the speak-as descriptor. We thought this might be a good opportunity to gain some clarity on the syntax, or understand why this name was chosen.

[xiaochengh]

Some more implementation feedback from Chrome:

The way how speak-as is currently defined seems to aim at providing a vocal hint of the counter, which doesn't match the accessibility framework Chrome is using. Instead, Chrome heavily relies on the "alternative text", as mentioned by @dot-miniscule .

Consequently, the implementation of speak-as in Chrome is reduced to generating the proper alternative text, which is either trivial (but misplaced) or unimplementable for each value:

• bullet: trivial
• number: it appears that we should always use the decimal string of the counter value as the alternative text, regardless of the counter algorithm or the content language; the screenreader will then read the decimal string in the content language. So the implementation is trivial, and the spec text doesn't seem very related
• words: use the same counter text as the alternative text. Seems trivial, but again, we don't really have control on whether it's spoken as a number or words
• spell-out: we don't have a way to provide vocal hints to the screenreader, so this is unimplementable.

So I'm also looking for possibilities to revise speak-as, or introduce another descriptor that targets the alternative text directly.

[MatsPalmgren]

Fwiw, my understanding of speak-as is that the intent is to provide an alternative for speech synthesizers only.
For example, take the spec quote from the OP:

A counter style can be constructed with a meaning that is obvious visually, but impossible to meaningfully represent via a speech synthesizer, or possible but nonsensical when naively read out. The speak-as descriptor describes how to synthesize the spoken form of a counter formatted with the given counter style.

(my emphasis). The rest of the spec contains phrases like "speaks a UA-defined phrase or audio cue", "being read out", "speak it as normal text in the content language", "how to pronounce the symbols", "read out as (in phonetic notation) /a/..." and "pronunciation". I don't see how any of that applies to AT other than speech synthesizers.

Ideally, the UA should provide both the default form and the speak-as form and let the AT pick which to use. (The AT could even provide a way to access both forms.)

[Crissov]

For limitations of the current design, also see #387.

[tabatkins]

The name speak-as is therefore slightly misleading, as it won't always be speech, and in any case we don't directly control the speech that a screenreader outputs. We provide it with some text string it uses to make an announcement.

I've added some clarifying text that this is meant to handle any non-visual rendering medium; it's just hard to talk about these things in generic terms and still make sense. Hopefully the intro paragraph, and Note following the values, clears things up.

If we still need to rename the descriptor, we probably can, but I'd prefer not to churn if we don't have to.

---

• bullet: trivial

Yes.

• number: it appears that we should always use the decimal string of the counter value as the alternative text, regardless of the counter algorithm or the content language; the screenreader will then read the decimal string in the content language. So the implementation is trivial, and the spec text doesn't seem very related

Correct, tho I'm not sure what you mean by "spec text doesn't seem very related". It says to speak out the numeric value; what you just described seems to be exactly that.

• words: use the same counter text as the alternative text. Seems trivial, but again, we don't really have control on whether it's spoken as a number or words

Yup, you've got it right, just feeding the counter-representation to the screen reader is correct.

• spell-out: we don't have a way to provide vocal hints to the screenreader, so this is unimplementable.

You should probably be able to get this to work at least approximately correct by splitting on grapheme clusters and putting spaces between them, then feeding them to the screen reader. Best effort is what we're going for here; it's just wrong to read a list item counter like AB. the 28th item... as literally the word "ab".

[fantasai]

I agree with @MatsPalmgren's comments in #6040 (comment) . The speak-as descriptor is fundamentally about how to read the counter out loud. It may or may not be applicable to other AT output, it really depends on the output and what it's capable of representing.

I pushed some edits to make this clearer. Basically, the idea is that the @counter-style descriptors together define a visual representation, with speak-as defining its speech representation, and AT outputting to another medium should be allowed to use either form or some synthesis informed by both. So I've added the following text to clarify this (r=@tabatkins):

Assistive technologies should use this spoken form when reading out the counter style, and may use the 'speak-as' value to inform transformations to outputs other than speech.

@dot-miniscule @xiaochengh @MatsPalmgren Let us know if this works for you?

[MatsPalmgren]

@fantasai Thanks, that clarifies the intent for me. I agree that it's impossible for the UA to know the exact capabilities of the AT device (and user preference), so ideally the UA would provide an API to let the AT access both forms and use them as it sees fit.