RFC: Update the accessibility plugin
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 12.4k
- Forks
- 2.4k
- PR merge metrics
- No merged PRs in 30d
Description
## What problem are we trying to solve?
@ryanhamley and I have been working together to brainstorm how the [Mapbox GL Accessibility plugin](https://github.com/mapbox/mapbox-gl-accessibility) could be improved to provide a better experience for users with vision impairment or low vision. There are three main issues currently: (1) the location of the map is not described, (2) it’s only possible to tab over existing features randomly because the [tab-index](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) of each feature is [set to zero](https://github.com/mapbox/mapbox-gl-accessibility/blob/publisher-production/src/index.js#L48), and (3) the user isn’t given a way to meaningfully explore or move around the map.

## How does it currently work?
With the plugin, the [addControl](https://docs.mapbox.com/mapbox-gl-js/api/#map#addcontrol) function is used to add an instance of MapboxAccessibility to the map. This allows the user to define all of the layers and the property in those layers that should be used for voiceover purposes.
The plugin adds an invisible HTML button element on top of each feature with an [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) property based on what is defined as the `accessibleLabelProperty`. This allows assistive technology to interpret the symbol as a button with text that is read aloud as the user tabs over the feature.
There are steps at https://github.com/mapbox/mapbox-gl-accessibility#developing to view the demo.
## New implementation proposal
When it comes to accessibility, it’s best to follow standardized practices so that users know what to expect and do not encounter an entirely different experience depending on the mapping provider. A few other mapping providers have already taken the same approach (see [Esri’s a11y map](https://github.com/Esri/a11y-map) and [Google’s Accessibility mode](https://support.google.com/maps/answer/6396990?co=GENIE.Platform%3DDesktop&hl=en)).
This implementation uses a bounding box that can be moved with the arrow keys. The direction the user is moving is read aloud (i.e. “Moving North”) and then the list of POIs in the area are announced. If a user selects a number corresponding to an announced place, the sidebar opens with all of the details available about the POI. This general idea could work with POIs, but also custom data on Mapbox maps.

### Option 1
Add a square div to the top of the map and use the width and height with queryRenderedFeatures. With this option, we could create a div ID parameter for the user to pass when they initialize the plugin so that the functionality can be included in the existing HTML of their page. The direction a user is moving in on the map is announced when an arrow key is pressed which is calculated by retrieving the bearing and assigning the arrow keys accordingly (i.e. “Moving North”, “Moving Southwest”, etc)


_See demo https://bl.ocks.org/malwoodsantoro/ad453549bb3cb77a015c7a7addf19cc6_
_Pros_: Performance is great since it is just a fixed div element that sits on top of the map.
_Cons_: Haven’t run into any yet!
### Option 2
Add a canvas source that sits as a square on top of the map. When the user pans the map, a bbox is calculated using the center point and size of the square (see [demo](https://bl.ocks.org/malwoodsantoro/c80e4bdd4e5a76faa80873247e78aa67)).
_Pros_: Potential for adding more complex rendering on the canvas layer, but not sure when/if that would be useful for this plugin.
_Cons_: Canvas source visibly updates as map moves.
### Options 3
Use a fill layer that is transparent in the center. Each time the map moves, reposition the fill layer to the center of the map and query for the features as described in the approach above.
_Pros_: Very straightforward and simple to implement.
_Cons_: Feature visibly updates as the map moves and changes position on zoom.
## Other features
- Allow the user to provide a string to be used as an aria-label to announce the location of the map along with some context of what is being displayed (i.e. "A map of ice cream shops in Oakland, California" and to announce how to navigate with the keys (arrow keys for panning and +/- for zooming).
- Allow additional properties to be defined for when the user tabs over a div and presses the corresponding number to tab into the feature for more information.
- Give the developer an interactive: false option that would allow them to use the plugin to only return the features in the bbox. They could then write their own custom code to have more control over the way the features are displayed and read aloud with Voiceover.
## Future improvements
- Utilize a circle with the Tilequery API instead of a bounding box so the user could have a better understanding of the geographic area being covered by choosing circle radius from a list of options (in miles or kilometers, for instance).
- Method within the plugin that makes it easier for users to [adjust the font size](https://bl.ocks.org/malwoodsantoro/c073b01083160fbac45739f62928a713) or size of symbols on the map
- Features to accommodate users who experience colorblindness
- Styles using shape and texture instead of color to distinguish between map elements
- Changing colors in style to have a contrast ratio that meets WCAG compliance
- “WCAG 2.1 requires a contrast ratio of at least 3:1 for graphics and user interface components”
@mapbox/gl-js @tristen @andrewharvey would love to hear your thoughts on this.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the mapbox-gl-accessibility plugin, especially src/index.js, its developing steps, and the linked demos using addControl and queryRenderedFeatures. The proposal presents three implementation options plus several additional and future features, so first establish which scope and approach maintainers accept. Done requires an agreed accessibility design and a corresponding implementation with defined behavior for keyboard navigation, announcements, and feature details.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- html, javascript
- Domain
- accessibility, frontend, web-dev
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100