Accessibility: Wrapping the entire passage in aria-live polite

[samspot]

Hello!

I noticed while testing my first story for accessibility that Twine defaults to wrapping the entire passage in aria-live="polite":

<tw-passage class="passage" aria-live="polite">

I find this to be an incorrect usage of an aria-live region and I have to cut it out via Javascript in order to get desired screen reader behavior. Not only that, but it actively interferes with other common techniques to get the screen reader to read state changes that don't involve navigation. Basically, I follow the instructions from the orange documentation and do the following:

$(window).on(':passageend', function () {
    $('.passage h1').attr('tabindex', -1)
    $('.passage h1').focus()
    if (window.State) {
        window.$roomName = State.active.title;
        document.title = State.active.title;
    }
});

$('#passages').removeAttr('aria-live');
document.documentElement.lang = 'en-US';

I created this as a discussion instead of a bug or feature because:

1. I'm not sure how much of this is out of the box Twine as opposed to sugarcube. I noticed a Snowman story I made had the same polite behavior.
2. I want to get some feedback from other experts before posting any bugs or requests.
3. I wonder if sugarcube could or should offer some ways to configure these things instead of coding around in javascript (aria-live, language, focus first h1 on nav, automatically update page title). In the interest of making the default version the most accessible.

What do you think?

[greyelf]

I'm not sure how much of this is out of the box Twine as opposed to SugarCube

Each Story Format defines its own default HTML structure and the CSS used to style it in the template it supplies to the Twine 2.x application, all the application basically does when it generates a Story HTML file is to embed the contents of the project's Passages inside a copy of the template.

I find this to be an incorrect usage of an aria-live region

I'm not an Accessibility expert, but I did notice that the Notify the user of updates inside the page section of the Recommendations for Single Page Applications page you linked to contains a reference to a The aria-live attribute and the role alert page. And that that page's Notify the user of updates inside the page section recommends using the aria-live attribute...

to indicate to the screen reader that any modification made to its content will result in vocalization by the screen reader.

...and that the Polite value is used to indicate...

the vocalization will take place when the screen reader has finished the current task

...which seems like the desired outcome after a Passage Transition (task) has finished.
eg. the contents of the visited Passage gets vocalized by the screen reader.

focus first h1 on nav

This might be difficult to do, as currently the story format's default HTML structure doesn't include such an element. And there isn't any guarantee that an Author will include such in the content of the Passage, nor might an Author from a game styling styling point-of-view want to have such a header appear at the top of each Passage visited forced upon then.

But I could be wrong, or misunderstanding the situation, because as I stated earlier I'm not Accessibility expert.

[samspot]

Hi, thanks for your response! That page specifically says to use aria-live for updates inside the page and not to read the entire page on change. I could find some finer-grained articles on recommended usage of aria-live if you are interested. The gist is to use it (and all ARIA) sparingly.

Another issue with wrapping the whole page in aria-live polite is that now the author cannot use a polite aria region to communicate anything unless you first remove it from the container. As an example, I wanted to use it to announce the result of an action like "You ate the crackers" but it doesn't work there. It also means using the recommended techniques like focusing on a new element don't cause the screen reader to read in a timely manner. So until the user notices it's there, all their normal accessibility techniques are quietly defeated. I was scratching my head because I couldn't get NVDA to read anything unless I marked it up as assertive. I only tested with NVDA+chrome so there could be other challenges.

Your point about not all passages having an H1 is a good one. But I'd advocate making this a requirement. It's a requirement according to the WCAG standard. Here's an example of that: https://fae.disability.illinois.edu/rulesets/HEADING_1/. We can't force authors to put in H1's but we can update examples to demonstrate using them. I'm sympathetic to an author not wanting an H1, but we need to let people know that a knowing choice not to include an H1 is a choice to discriminate.