Improve accessibility of tour module

This extension is being deprecated, see 🌱 [Meta] Tasks to deprecate Tour module Fixed . It will be removed from core and moved to a contrib project, 📌 [11.x] [Meta] Tasks to remove Tour Postponed .

This is now Postponed. The status is set according to two policies. The Remove a core extension and move it to a contributed project → and the Extensions approved for removal → policies.

If someone could be kind enough to check 2.0.x

Did some initial testing with 2.0.0 today and noticed already one accessibility related issues. Searching for an existing issue i've stumbled across this one. skimming through the points raised in the issue summary many probably still apply. i can take a more thorough look in the next days. but the detail i've noticed is when the dialog modal for the tour tip is visible for screenreaders the elements in the background of the widget are not excluded from the accessibility object model. if you are using for example the rotor in voiceover you have no way to distinguish which element belongs to the tour tip and which elements belong to the page in the background. a problem the dialog modal in core also had before the upgrade to jquery 0.14.0 in drupal 11.

Let’s have this be a meta and we can open up sub tasks for fixing accessibility findings

will create a summary comment in the meta tomorrow first and then we can see which of the points can already split out as child issues as you suggested. but have to finish the two summaries for todays ux meeting first .

oh and one of the issues should/will probably be directly reported and created upstream adding a dialog modal and or aria-modal attribute to the tip modal. and in that regard how difficult is it to upgrade tour to the latest sheperd release? i think i remember that there was one issue back when tour was still in core and the upgrade seemed not that easy and flawless. i think sheperd is currently already at version 13.x?

In the following i am going through the points listed in the issue summary summarizing what is still relevant and what got fixed meanwhile. At the end i'll add a few additional points i've noticed. After that it, it can be decided how to chop up things up in dedicated child issues.

Tour button in toolbar:

- "tour" label is kind-of informative, but could be better.
- ... an aria-describedby? Maybe to associate some help text like "show tips about important features on this page"

take a tour of this page is what the button label has changed to which is slightly better and less verbose than "show tips about important features on this page". But it is still quite lengthy and what does "take a tour" mean in the context of this button, that might not be necessarily clear?
Maybe to go with something like Show tips for sighted users, which is sort of concise, and be slightly more verbose for screenreader users with aria-described with something like Show tips for this page

... indicate a dialog will appear with aria-has-popup="dialog"

aria-haspopup is a good idea (might be even worth to consider for other parts in Core for links and buttons that expand a dialog modal). at the moment the tour button has an aria-pressed attribute. problem with that, for screenreader user that doesn't have much benefit, cuz technically as soon as the button is pressed everything except the tip dialog modal gets "hidden" behind the greyed out svg. well at the moment the dialog modal is missing the dialog element and or an aria-modal attribute so that everything in the background of the dialog modal gets removed from the accessibility object model. therefore if sheperd would support that the toggle button would be unavailable anyway and the purpose of a "toggle" button would be obsolet plus aria-haspopup doesn't work with aria-pressed on the same element - aria-pressed overrides aria-haspopup so only the pressed state gets announced (I've manually tested with voiceover). so don't think that aria-pressedmakes sense here at all. we have a dialog modal and the rest of the page should be in background excluded from the AOM. plus all necessary controls are available in the dialog to close it. so my suggestion would be to drop aria-pressed and use aria-haspopup instead? (i've raised the topic at the last a11y office hour and folks were in agreement with the suggestion). Aside removing the aria-pressed and adding the aria-haspopup it might be necessary to create an issue upstream for adding either the dialog element and or aria-modal attribute to sheperd.

when it has keyboard focus, activatin the button makes the tooltip appear, but focus is still on hte toolbar button. Sighted keyboard user can see the first tip, but effectively cannot advance to the next tip. Focus will move from tour toolbar button to user acount link. The actual tips are at the end of the document.

Does not apply anymore - focus is first on the Next-button. The only problem with that is, the dialog modal title gets announced when the modal gets into focus, but the description is placed before the Next-button in the DOM and the initial focus is on the Next-button so there should be an easy way to get the announcement of the description as well.

Should move focus to start of dialog.

yes i agree. at the moment the initial focus is technically at the "end" of the tip where you strictly speaking skip to the next tip. It is not directly clear that there is also a description. In the worst case one could think there is only the title and the Previous and Next buttons.

For assitive tech, there's no indication that anything has happened. There is an aria-pressed="false", but this DOES NOT CHANGE when pressing it. With screen reader, when you arrive at the button, it says "tour, button, not pressed". Press it, the dialog appears, but focus remoans on the toolbar button, and the screen reader says "button, not pressed". Note, if

Does not apply anymore - focus is on the Next-button on the first tip within the dialog when the tour starts and aria-modal changes to true.

We would expect it to announce a "dialog". Actually it has a dialog role, but it isn't announced because focus hasn't moved there. If you use a mouse when running a screen reader, you can hear the dilaog being announced. Press the toolbar button, then click inside the tooltip. The dialog role will be announced. So this will hopefully be OK if we move the focus when the tour is invoked.

does not apply anymore - dialog is announced and with aria-haspopup it could be improved even further

Tip dialogs:

- There's no indication to assistive tech for "what is this tip pointing to?" The tooltip association is purely a visual indication. Not easy to solve this...
- basically, we're looking for the opposite of aria-descibedby. "This dialog describe such-and-such control".
- If a programatic associuation is not possible, then an invisible span could say this, e.g. the tooltip is pointing to the file upload button.
- If we can implement dialog role semantics, then the invisible "describes file upload button" could be at the start of the dialog, and maybe the ting that gets focus when a new tip appears.

I would vote for the invisible span. Could be easily accomplished with a second body field on a tip edit page. So the first body field would be the “alt text" for the tip describing the page and the ui element in focus, while the second is the actual tip. And I heavily doubt that things would work out nicely with any kind of programmatic association. With the description of the visual context it helps screenreader users way more. plus that description could be skipped and jumped off any time by the screenreader user.

- on dismissing dialog, where should focus go?
- return focus to where it was when tour was first invoked?
- or move focus to whatever thing is being described by the current tip? Would need to make it clear for assistive tech. Does the tip always point to a focusable control?
- WOuld expect ESCAPE key to dismiss a dialog. If a sighted keyboard user invokes the tour, they can't get past the first tip, and they can't dismiss it either.

ESC is closing the dialog modal. only problem the focus isnt returning to the element that triggered opening the diloag modal and i am not sure if returning to the element in focus in the tip might be too confusing to the user?

Idea:

- indicate tour milestones in the UI, even when tour is not active. Like, some "what's this?" markers. Clicking one of those would invoke to tour, starting mid-way though, at the relevant tip. Metaphor: sightseeing bus tours in cities sell tickets which are valid for "hop on, hop off" use. This would be an alternative route to access the tour tips, whcih could be a lot easier to access for assistive tech users. (Compare with WCAG 2.0 "multiple ways", which isn't really about this scenario, but the principle still applies somewhat).

Do i read that correctly, the idea is to have aside the general button for starting a tour also "milestone buttons" to start a tour at specific steps? I am not sure if the UI wouldn't be too overloaded that way?

- It's only possible to move forward in the tour. Should moving backwards be an option? It would make sense to do this if we allow users to join the tour half-way though.

Does not apply anymore, a Previous button got already added. And I think it is not only good to have a Previous button for the case of joining a tour half ways, but you also have to consider the case that someone has a small working memory and needs to go back to the previous step for reassurance because a detail was forgotten or not read closely.

TODO:

- assess how this works with browser zoom, including mobile. Does it re-flow nicely, and preserve the visual association, with the speech-bubble-stalk in the right place? Go maximum zoom.

I've tested zoomed in on desktop (used the maximum possible number of "command +" tabs), that works. If i zoom on iOS, either with two finger pinch or activating the device zoom in the accessibility setting (with three finger tab you are able to zoom in then), then the experience is lets call it a bumpy ride. I am sort of unable to scroll properly also the svg has issues properly marking the background. On desktop the interface remains responsive with no vertical scroll), while on mobile you zoom in and you have to scroll then and that as well as the proper display of the dialog modal which also seems not completely responsive seems off. But might be in part also a problem for Core in general?
Plus as soon as you are zoomed in and you press the Next or Previous-button you get scrolled to the section of the screen the next tip is about, counter to the fact that in my case the Reduce motion setting in my operating system is set. There should be a jump not a scrolling in that particular case. That is in conflict with WCAG2.2 SC2.3.3 C39. A from my perspective slightly more elegant solution, in contrast to the approach described in C39, is the one @joshuami proposed in https://drupal.slack.com/archives/C2ANFUGGG/p1697041118213939?thread_ts=... . By using

@media (prefers-reduced-motion: no-preference) {
}

you are able to add any animation related rules within the media query. that way you keep everything in relation to animation contained and achieve a progressive enhancement for the animation minding the operating system settings in regards of Reduce motion.

- assess how well this works for screen magnifiers

I dont have a screen magnifier available to test

- CONFIRM: does WCAG 2.1 Content on Hover or Focus apply here? Seems it's neither of these things, since it's invoked with an explicit button press, and dismissed with an explicit button

i think SC1.4.13 doesnt apply here since the invocation of the dialog modal is neither on hover nor on focus. you have to press a button to open the dialog modal and you then have the close button and the ESC key press available to close the modal https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html

- Compare with tooltip-dialog pattern in W3C WAI-ARIA authoring practices - is this relevant? If so, is there any behaviour we'd need to implement?
- Various forms of balloon help have been around in desktop OS for ages. Review how these work, to see if there are any a11y features that can be implemented in a webpage tour?

Still a TODO.

- assess whether each improvement needs changes in Drupal code, versus fixes in the upstream Joyride library.

That is something that has to be assessed in the case of sheperd now. The one thing i can say for now is that the change for the dialog element/aria-modal attribute should be moved upstream. The rest is TBD.

- Add a focus style for the tour tip close button. We'll need that once we have the keyboard accessibility working. Use a square outline like the ones for our other dialogs, per #2863354: Add border to dialog [x] close button for hover and focus states

Does not apply anymore. The close button has a focus outline meanwhile.

Addition:

• The button styling. The dark blue of the button with an aria-pressed state of false has 2.3:1 against the black on the left border. SC1.4.11 states The visual presentation of the following have a contrast ratio of at least <code>3:1 against adjacent color(s). Meaning the color contrast against the white background of the secondary toolbar with a color contrast of 8.2:1 which is ok, but against the other adjacent color with 2.3:1 is not enough. Same for the redish button if no tour is available. Against white it has 9.8:1 but against the black (#0f0f0f) it only has 2:1.
• The focus outline color that is used for the dialog tour modals isn't in line with the Drupal Design System. Instead of the Claro green it is using some blueish color, plus that used color also has a too low color contrast of 2.3:1 for #52B3EA against #FFFFFF. To meet SC2.4.7 at least 3:1 would be necessary. In addition to that due to the nature of simultaneous contrast the blue of the outline and the blue of the button look even closer, it is only slightly eased due to the fact an outline offset is used.
• If the white dialog modal is over an highlighted white focus area you are unable to distinguish the outlines and the extent of the dialog modal which is not in line with SC1.4.11. The user has to be able to recognize an interface component.
• As mentioned above, create an issue upstream for adding either a dialog element and or an aria-modal attribute to the dialog modal in Sheperd. Because at the moment the background of a dialog modal is not removed from the AOM. As soon as a dialog modal is open and a user is using the for example rotor in voiceover it is impossible to distinguish which element is in the background and which is within the dialog modal.
• At the moment the title of the dialog modal is an h3. Did some extensive research in the context of the dialog modal for drupal in general a few weeks ago. At the moment in Drupal Core just a span is used for the title which is simply wrong and unsemantic. So having an heading element is a good thing and not "technical" wrong to just have an h3. But based on the fact that with a dialog element and or aria-modal all the elements in the background are excluded, it is more or less a different context and therefore justifies making the heading a h1. https://github.com/mui/material-ui/issues/34250 and https://github.com/w3c/wcag/discussions/2722#discussioncomment-3842484 . in the latter Patrick Lauke summarizes: "h1 would be the most “correct” but h2 and h3 would also perfectly fine you just have to make sure that headings within the dialog modal coming after the title dont have a heading gap" but as seen in the other link, James Scholes who argued there is one of the main advocates for using an h1 here. He is an accessibility professional as well as a blind screenreader user.
• In that context, currently it is not directly available for screenreader users in which step the user currently is and how many there are. One suggestion might be to move the "1 of 6" to the title instead. So you have for example 1 of 6: Site appearance. That would provide the overall context of the current tip, the overall number of tips and the actual title right within the heading. that might improve things against SC2.4.2 https://www.w3.org/WAI/WCAG21/Understanding/page-titled.html even though i dont consider the current state a violation.
• Improve the descriptions of all the tours and tips the tour module is shipping with. At the moment those contain sometimes directional language which requires the visual context as well as abbreviations - and try to get towards using plain language here. I would go through those, only question should i open a meta issue and create a child issue for each of the tours or keep everything in a single issue?
• And one idea, aside providing the option to the user to start a tour by pressing the tour button it might be also helpful for advanced users and screenreader users in particular to add an hot key for starting a tour. That way if a screenreader user gets to a page and presses the hot key either the tour starts or you could add an announcement, something like that there is no tour for this page available. That way there is no need to get to the "start tour"-button and the entire process is streamlined.

One detail i forgot to add, the page title and the h1 for all the tours is identical. it should reflect the tour name (WCAG 2.2 SC2.4.2)

Added a remaining tasks section with the child issues listed in the sidebar. #23 🌱 [META] Improve accessibility of tour module Active has still to be rechecked and reevaluated another round if there are more child issues to be created

changed the parent meta issue to #3475279: [Meta] Audit each module to be included into Drupal CMS for accessibility issues → . idea is to add and or create a meta issue for improving the accessibility for every contrib module in consideration being added to the drupal cms (and even in case a module doesnt make it in it isnt a lost and useless effort)

So tour queue is down to like 10 and rkoller has done a great job opening new tickets. Don't think we need a full meta tracking stuff now.