Incorporating best practices for Accessibility in the documentation

[Malvoz]

Accessibility efforts for Leaflet can provide a more accessible baseline for the different features/components, and the map as a whole.

But sometimes it's the responsibility of developers who implement Leaflet maps to take extra steps to ensure their maps are presented in a way that they can be used and make sense to people of all abilites.

This discussion is about the things that Leaflet can't do for developers out-of-the-box, but rather how updates/additions to docs can help developers create more accessible maps. Also things that can be improved to ensure the site is usable for keyboard users and users with assistive technologies.

Areas that can be improved:

• Accessibility best practices and tips in tutorials
• Dedicated tutorial/guideline page for accessibility
• Advisory information in the reference docs
• Plugin Authoring Guide: Content Accessibility
• Misc / General site issues

Feel free to discuss each, and give suggestions.

[Malvoz]

Accessibility best practices and tips in tutorials

For the existing tutorials, check:

1. If they generally follow accessibility guidelines and best practices (so that everyone can use them, and they don't introduce accessibility issues to people's sites if they copy & paste), e.g. that they use valid HTML and appropriate semantics (also run link checks for good measure);
2. If there are opportunities to incorporate specific accessibility tips

---

Reviews of tutorials (in progress)

If you find an unchecked item in the reviews of these tutorials, feel free to send a PR to fix it.

Quick Start Guide

The Quick Start Guide:

• Markers should have descriptive title or alt

Leaflet on mobile

The Leaflet on mobile tutorial:

• Shouldn't disable user-scaling in the recommended meta tag (see Mobile Example Outdated #7342 (comment))

Markers With Custom Icons

The Markers With Custom Icons tutorial:

• The icons should have an accessible name/accessible description, for example "green leaf", "red leaf", "yellow leaf" e.g. via title or alt attributes

Accessible Maps Guide ✔️

The Accessible Maps Guide:

No changes needed.

Using GeoJSON with Leaflet

The Using GeoJSON with Leaflet tutorial:

• Marker should have a descriptive title or alt
• Vectors should be keyboard focusable and have accessible name/accessible description
  (blocked on Accessible vectors #7822)

Interactive Choropleth Map

The Interactive Choropleth Map tutorial:

• A potential accessibility tip is to use ARIA, such that the info is announced when the mouse hovers over the states:

  aria-live="assertive" on <div class="info leaflet-control"> (you may have to unmute the video):

  choropleth-info-assertive.mp4

  (However, for vectors in general, Accessible vectors #7822 would be a better long-term solution.)

  • In the video above, the "/ mi²" (/ mi<sup>2</sup>) is announced as slash, me, group 2. This could be improved with something like <span aria-label="per square mile">/ mi<sup>2</sup></span>.

• Vectors should be keyboard focusable and have accessible name/accessible description
  (blocked on Accessible vectors #7822)

Layer Groups and Layers Control

The Layer Groups and Layers Control tutorial:

• Markers should have descriptive title or alt

Zoom levels

The Zoom levels tutorial:

{TODO}

Non-geographical maps

The Non-geographical maps tutorial:

• Markers should have descriptive title or alt

WMS and TMS ✔️

The WMS and TMS tutorial:

No apparent changes needed.

Working with map panes

The Working with map panes tutorial:

• Vectors should be keyboard focusable and have accessible name/accessible description
  (blocked on Accessible vectors #7822)

Overlays

The Overlays tutorial:

• Vectors should be keyboard focusable and have accessible name/accessible description
  (blocked on Accessible vectors #7822)
• The custom video controls to Play/Pause in A bit of control over the video should have descriptive title/aria-labels.
  Video overlay tutorial: Accessible custom video controls #8017
  Refactor / Extend VideoOverlay (ImageOverlay, SVGOverlay) #8090

Extending Leaflet: Class Theory

• Diagram is not accessible to screen reader users (mentioned in UML diagram is outdated #8086 (comment))

Extending Leaflet: Layers

{TODO}

Extending Leaflet: Handlers and Controls

{TODO}

[Malvoz]

Dedicated tutorial/guideline page for accessibility

Feel free to discuss these items, or suggest new additions to the Guide to basic Leaflet accessibility!

• Always set a unique and descriptive alt or title for markers.
  (Fixed in: New tutorial: Guidelines to basic Leaflet accessibility #8081)

• divIcon accessibility (related: L.divIcon incompatible with marker alt text #3400)
  (Fixed in: New tutorial: Guidelines to basic Leaflet accessibility #8081)

• Always set a unique and descriptive desc or title for vectors.
  (blocked on Make vectors focusable and labellable #8251)

• Describe single maps and/or make multiple maps in a document discernible to screen reader users.
  (relates to Make the leaflet-container a programmatically determinable element #7193, which is intended to make maps recognizable to screen reader users by default.)
  
  A unique and descriptive aria-label, aria-labelledby, aria-description, aria-describedby, title, <figcaption> in <figure>, and headings in <section> for each map may all be potential ways to achieve this.

• Mention that standalone popups and tooltips can be problematic?
  
  The problems are:

  • for keyboard users: Once popups/tooltips are closed, the user can't open them (without reloading the page).
  • for screen reader users: Missing contextual information for the popups/tooltips (that would otherwise be provided via e.g. marker alt or title).

• Provide guidance on when to use tooltips vs popups:

  • Generally, if interactive content is used (links, buttons, forms) use a popup!
    This is to align the user's expectations for Leaflet's tooltips with browsers' native tooltip behaviors (as they can't have interactive content) and ARIA tooltip best practices, but also because only popups should recieve focus when opened (in which case the user can easily tab to the content within).
  • Use tooltips if there is a need to show information on hover (some people may want to compromise though: Binding popup on marker hover #60?)

• Purely decorative maps.
  (Fixed in: New tutorial: Guidelines to basic Leaflet accessibility #8081)

[Malvoz]

Advisory information in the reference docs

Feel free to discuss these items, or suggest new additions to this list!

• For each keyboard option (#map-keyboard, #marker-keyboard) add "Useful for accessibility" with a link to the Preserve useful defaults guideline.
• Add "Useful for accessibility" to description for autoPanOnFocus.
• Changing the default (true) of #control-layers-collapsed results in more Tabs for keyboard-only users (or more swipe gestures for screen reader users on touch devices).
  (This behavior has changed, but is likely to be brought back per Layers control should not expand on focus #7191)

[Malvoz]

Plugin Authoring Guide: Content Accessibility

Feel free to discuss and suggest improvements to the Plugin Authoring Guide's Content Accessibility section here.

[Malvoz]

• Try to shorten the section down
• Following should have links:

  Leaflet/PLUGIN-GUIDE.md

  Line 161 in a3f1ba9

  as well as using a screen reader such as Narrator, NVDA, VoiceOver, or JAWS.

  but maybe it's better to link to the Test your maps guideline

[Malvoz]

Misc / General site issues

Feel free to discuss these items, suggest new additions to this list, or send PR(s) to fix them!

• Should Leaflet have an Accessibility Statement? #7537 (Add an official Accessibility Statement #7900)
• Site accessibility improvements #7899 (Improve site accesibility #7901)
• Remove table semantics from tables used for layout purposes for iframe includes #7948
• Accordions in the Leaflet API reference are not keyboard accessible. See Keyboard accessible accordions Leafdoc#61 for more info.
• Blog posts semantics: Replace <div class="clearfix"> with <article class="clearfix">?
• Remove the duplicate links to tutorials from the thumbnails from the focus order using tabindex="-1", and hide from screen readers using aria-hidden="true".
• Hide the ← (←) character using aria-hidden in the tutorials-back link.
• Remove viewport meta tag's user-scalable everywhere, per this warning (and also because many browsers no longer support it).