Skip to content

MAPS_ACCESSIBILITY_BEST_PRACTICES.md

Latest commit

 

History

History
526 lines (381 loc) · 23.7 KB

MAPS_ACCESSIBILITY_BEST_PRACTICES.md

File metadata and controls

526 lines (381 loc) · 23.7 KB
title Maps Accessibility Best Practices

Maps Accessibility Best Practices

This document defines accessibility requirements for interactive and static maps on the web, ensuring that all users can access geographic information regardless of visual, motor, or cognitive ability.

Maps present unique accessibility challenges because spatial information is inherently visual. These practices help teams provide meaningful alternatives, make interactive controls operable, and ensure content is understandable for all users.

1. Core Principle

All users must be able to access the essential information conveyed by a map through accessible alternatives, keyboard-operable controls, and clear, structured content. This includes people who are blind or low vision, those who cannot use a mouse, and those with cognitive or learning disabilities.

2. Text Alternatives for Static Maps

Required for all maps that convey meaning

A static map image must have a text alternative that conveys the same information:

  • Use alt for brief descriptions where the map supports a single point of information.
  • Use aria-describedby or a linked long description for complex maps with multiple features.
  • Never leave alt empty for a meaningful map — use alt="" only when the map is purely decorative (rare).

Simple static map

<img
  src="campus-map.png"
  alt="Campus map showing the main entrance on Elm Street, with the library to the north and parking to the east."
/>

Complex map with long description

<figure>
  <img
    src="regional-map.png"
    alt="Regional accessibility map — detailed description below."
    aria-describedby="regional-map-desc"
  />
  <figcaption id="regional-map-desc">
    <p>The map shows three accessible transit routes through the downtown core. Route A runs north–south on Main Street with level boarding at all stops. Route B runs east–west on King Avenue with ramps at each station entrance. Route C is an inner loop connecting the civic centre, library, and hospital, all of which have automatic doors and step-free access.</p>
  </figcaption>
</figure>

What to include in a text alternative

  • The purpose of the map
  • Key features, locations, or routes shown
  • Directional relationships (north, south, adjacent to, across from)
  • Any symbols or color coding used, with their meaning

3. Interactive Map Accessibility

Keyboard operability

All map interactions available by mouse or touch must be reachable and operable by keyboard:

  • Pan/scroll: arrow keys or equivalent keyboard controls
  • Zoom in/out: +/- keys or accessible buttons with visible labels
  • Feature activation: Enter or Space on focused markers or regions
  • Close popups or tooltips: Escape
  • Skip the map: provide a visible-on-focus skip link before the map region
<!-- Skip link before the map -->
<a href="#map-skip-target" class="skip-link">Skip map</a>

<div id="map-container" aria-label="Interactive campus map">
  <!-- map renders here -->
</div>

<div id="map-skip-target" tabindex="-1">
  <h2>Map information as text</h2>
  <!-- structured text equivalent -->
</div>

Focus management

  • Ensure focus is visible at all times on map controls and markers.
  • When a marker popup opens, move focus into the popup.
  • When a popup closes, restore focus to the triggering marker.
  • Do not trap focus inside the map container unless it is a modal experience.

Landmark and ARIA roles

  • Wrap the map in a <section> or use role="application" when custom keyboard behavior is implemented.
  • Provide an accessible name via aria-label or aria-labelledby.
  • Use role="application" sparingly — it suspends standard reading mode in screen readers. Only use it when the map delivers a rich interactive widget experience and includes comprehensive keyboard support.
<section aria-labelledby="map-heading">
  <h2 id="map-heading">Service Area Map</h2>
  <div role="application" aria-label="Interactive service area map">
    <!-- map -->
  </div>
</section>

4. Map Controls

Zoom and navigation controls

  • All map controls (zoom, pan, layer toggles, search) must be reachable by keyboard.
  • Buttons must have accessible names — avoid icon-only buttons without labels.
  • Controls must meet minimum touch target size (44×44 CSS pixels).
<!-- Accessible zoom controls -->
<div role="group" aria-label="Map zoom controls">
  <button type="button" aria-label="Zoom in">+</button>
  <button type="button" aria-label="Zoom out">−</button>
  <button type="button" aria-label="Reset to default view">⟳</button>
</div>

Layer toggles and filters

  • Layer toggles must use <input type="checkbox"> or role="checkbox" with a visible label.
  • Group related layer controls with <fieldset> and <legend>.
  • Announce layer state changes using a live region when appropriate.
<fieldset>
  <legend>Map layers</legend>
  <label><input type="checkbox" name="layer-transit" checked> Transit routes</label>
  <label><input type="checkbox" name="layer-accessibility"> Accessibility features</label>
  <label><input type="checkbox" name="layer-parking"> Parking areas</label>
</fieldset>

5. Map Markers and Features

Accessible marker names

Every marker, pin, or region must have an accessible name:

<!-- Marker as a button -->
<button type="button" aria-label="City Hall — open weekdays 9am to 5pm">
  <svg aria-hidden="true" focusable="false"><!-- pin icon --></svg>
</button>

Popups and tooltips

  • Popup content must be keyboard-accessible and screen-reader-readable.
  • Use role="dialog" with aria-labelledby for rich popups.
  • Provide a clearly labeled close button.
  • Ensure popup text has sufficient color contrast.
<div role="dialog" aria-labelledby="popup-title" aria-modal="true">
  <h3 id="popup-title">City Hall</h3>
  <p>123 Main Street. Open Monday–Friday, 9am–5pm.</p>
  <a href="/city-hall">More information</a>
  <button type="button" aria-label="Close City Hall popup">✕</button>
</div>

Clusters

  • Marker clusters must announce their count and general location.
  • Expanding a cluster must be keyboard-operable and announce the result.
<button type="button" aria-label="Cluster of 7 locations in downtown — press Enter to expand">
  7
</button>

6. Color and Visual Design

Do not rely on color alone

Maps frequently use color to convey meaning. Every use of color must be accompanied by another visual indicator:

  • Use patterns, shapes, or labels in addition to color for route or zone differentiation.
  • Provide a map legend with text labels for all color-coded elements.
  • Ensure the legend is adjacent to the map and keyboard-accessible.

Color contrast

  • Map text and labels must meet 4.5:1 contrast ratio against their background (WCAG 2.2 AA).
  • UI controls must meet 3:1 contrast ratio for non-text elements.
  • Test maps in forced-colors (Windows High Contrast) mode.

Avoid conveying direction by color alone

For route maps, supplement color with directional arrows or numbered waypoints.

7. Structured Text Alternative

Whenever a map communicates complex spatial data, provide a structured text equivalent alongside it. This can take several forms:

Tabular data

When a map shows a list of locations:

<table>
  <caption>Accessible library branches</caption>
  <thead>
    <tr>
      <th scope="col">Branch</th>
      <th scope="col">Address</th>
      <th scope="col">Accessibility features</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Central Library</td>
      <td>100 Main St</td>
      <td>Step-free entry, elevator, accessible washrooms, assistive listening</td>
    </tr>
    <tr>
      <td>Eastside Branch</td>
      <td>450 Oak Ave</td>
      <td>Step-free entry, accessible washrooms</td>
    </tr>
  </tbody>
</table>

Step-by-step directions

For routing maps, provide turn-by-turn text directions as an alternative:

<ol aria-label="Accessible route from main entrance to conference room">
  <li>Enter through the main doors on Elm Street (automatic doors, level threshold).</li>
  <li>Turn right and proceed to the elevator lobby.</li>
  <li>Take the elevator to the 3rd floor.</li>
  <li>Exit left and follow the corridor to room 310.</li>
</ol>

8. Indoor Maps and Wayfinding

Indoor maps present additional challenges because they often depict multi-level spaces with complex navigation needs.

Key requirements

  • Provide floor-level navigation controls with clear accessible names.
  • Announce floor changes clearly when the map view updates.
  • Provide text-based wayfinding as an alternative to the visual map.
  • Where possible, support integration with indoor positioning systems for real-time navigation assistance.

Floor selector

<label for="floor-select">Select floor</label>
<select id="floor-select">
  <option value="ground">Ground floor (accessible entrance, lobby, café)</option>
  <option value="1">Floor 1 (offices, meeting rooms 101–120)</option>
  <option value="2">Floor 2 (library, training rooms 201–210)</option>
</select>

<!-- Use a live region to announce the floor change to screen readers -->
<div role="status" aria-live="polite" aria-atomic="true" id="floor-announcement"></div>

Wire the change event of the select to update #floor-announcement with a brief human-readable message such as "Showing Ground floor". This approach is more reliably supported across assistive technologies than aria-controls.

Accessible route highlighting

When showing accessible routes indoors, clearly differentiate them from standard routes using both color and pattern (for example, a dashed line in addition to color), and provide a legend.

9. Third-Party Map Embeds

Many projects embed maps from third-party providers (Google Maps, Mapbox, Leaflet, OpenStreetMap). Each has different accessibility characteristics.

Embedding considerations

  • Always provide a non-map alternative (table of locations, directions, or address list) alongside any embedded map.
  • Test the embedded map for keyboard operability and screen reader compatibility.
  • Add a descriptive title to <iframe> embeds.
  • Ensure the map does not create a keyboard trap.
<iframe
  src="https://example-map-provider.com/embed?..."
  title="Interactive map showing our office locations"
  width="600"
  height="450"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade">
</iframe>

<!-- Always provide a text alternative below the embed -->
<details>
  <summary>View office locations as a list</summary>
  <ul>
    <li>Vancouver: 100 Granville Street, V6C 1T2</li>
    <li>Toronto: 200 Bay Street, M5J 2J3</li>
  </ul>
</details>

Leaflet.js accessibility

When using Leaflet, always add keyboard: true to your map initialization and ensure all custom markers and controls have accessible names. When clustering markers is needed, use the Leaflet.markercluster plugin and ensure cluster buttons expose accessible names with counts (see Section 5 — Clusters). Consider Leaflet Accessible for additional keyboard and screen reader improvements.

10. Map Search and Geocoding

If the map includes a search or address lookup:

  • Label the search input clearly.
  • Announce search results using a live region.
  • Announce when no results are found.
  • Ensure result items are navigable by keyboard and operable with Enter.
<label for="map-search">Search for a location</label>
<input
  type="search"
  id="map-search"
  aria-controls="map-search-results"
  autocomplete="off"
  aria-autocomplete="list"
/>

<ul
  id="map-search-results"
  role="listbox"
  aria-label="Search suggestions"
  aria-live="polite"
>
  <!-- dynamically populated results -->
</ul>

11. Mobile and Touch Accessibility

  • All map interactions must be operable with a single pointer (no multi-finger gestures required).
  • Provide button-based alternatives for pinch-to-zoom and two-finger pan.
  • Ensure maps work correctly with iOS VoiceOver and Android TalkBack.
  • Confirm that touch targets are at least 44×44 CSS pixels.

12. Testing Expectations

Minimum checks for each map change:

  • Navigate all controls and markers using keyboard only.
  • Verify visible focus on all focusable elements.
  • Verify screen reader announces marker names, popup content, and control states.
  • Verify color contrast for map text, labels, and UI controls.
  • Verify the map in forced-colors (Windows High Contrast) mode.
  • Verify a text alternative or structured equivalent is present and complete.
  • Verify embedded maps have descriptive title attributes.
  • Check with iOS VoiceOver and Android TalkBack for mobile map interactions.

13. Definition of Done

A map feature is complete only when:

  • All map controls have accessible names.
  • All markers and interactive features are keyboard-operable.
  • A text alternative (table, list, or directions) is present alongside the map.
  • Color is not the only means of conveying information.
  • Color contrast requirements are met for all labels and controls.
  • Manual keyboard and screen reader checks pass.
  • No blocking accessibility defects remain.

14. Equivalent Purpose Evaluation for Digital Maps

WCAG 2.2 SC 1.1.1 requires that non-text content have text alternatives that serve the equivalent purpose. For digital maps, this standard is particularly demanding because maps communicate multi-layered spatial information that cannot be captured by a brief description of visual appearance.

Research on systematically evaluating equivalent purpose for digital maps is presented in Systematically Evaluating Equivalent Purpose for Digital Maps (arXiv:2512.05310). That work highlights the gap between the visual representation of a map — its colors, shapes, and spatial layout — and its semantic representation: the geographic meaning, relationships, and tasks the map supports. An effective text alternative bridges this gap by preserving meaning, not merely describing appearance.

The Visual–Semantic Gap

A map's visual properties and semantic meaning are fundamentally different things:

Visual representation Semantic representation
Blue line running north–south A navigable transit route connecting the train station and the hospital
Green polygon covering a district An administrative boundary with specific planning or zoning significance
Clustered pin icons near the waterfront Multiple related points of interest sharing a category (e.g., accessible parking)
Gradient fill across neighborhoods A relative measure such as population density or flood risk level
Dashed boundary line A proposed or contested boundary, not yet formalized

Describing only the visual representation ("a blue line on a white background") fails the equivalent purpose test. A semantically equivalent alternative describes what the map communicates ("bus route 12, which is fully accessible with step-free boarding at all stops, connecting City Hall and Central Hospital").

Information Taxonomy for Maps

Digital maps communicate information across multiple semantic layers. Text alternatives should address each layer that is relevant to the map's primary purpose:

  1. Spatial/locational — Where features are (proximity, adjacency, coordinates, address)
  2. Directional/navigational — How to move between places (routes, turn-by-turn directions, orientation)
  3. Categorical/typological — What type of feature something is (transit stop, hospital, park, boundary)
  4. Relational — How features relate to each other (connected by, adjacent to, part of, blocked by)
  5. Quantitative/scalar — Relative measures shown visually (density, magnitude, coverage, distance)
  6. Contextual — The frame of reference (geographic scope, scale, time period, data currency)

Not every layer applies to every map. Begin by identifying which layers are essential to the map's purpose, then confirm your text alternative covers each relevant layer.

Example: A transit accessibility map showing accessible bus stops across a city would require layers 1 (spatial — stop locations), 2 (navigational — routes between stops), 3 (categorical — stop type, e.g. accessible vs. not), 4 (relational — which stops connect which routes), and 6 (contextual — city name, date of data). Layer 5 (quantitative) would only apply if the map also encodes something like ridership density.

Systematic Evaluation Criteria

Use the following criteria to evaluate whether a text alternative serves the equivalent purpose for a digital map.

Purpose alignment

  • Does the text alternative enable users to accomplish the same primary tasks as the visual map?
  • Is the core purpose of the map (wayfinding, context-setting, data communication, spatial comparison) fully served by the text alternative?
  • Can a user who cannot see the map form the same understanding of the geographic situation?

Semantic completeness

  • All named features visible on the map are identified in the text alternative.
  • Spatial relationships — adjacency, routes, containment, separation — are expressed in words or structured data.
  • Feature categories or types are identified, not just coordinates or addresses.
  • Any quantitative information (density gradients, distance scales, risk levels) is expressed numerically or descriptively.
  • The legend or key is described, including what each color, symbol, or pattern means.

Navigational fidelity (for route and wayfinding maps)

  • Routes are described in sequence from start through intermediate points to destination.
  • Key decision points, turns, and landmarks are included.
  • Accessibility attributes of routes are stated (step-free, ramp access, kerb cuts, surface type).
  • Where accessible alternatives to inaccessible routes exist, they are described.

Contextual framing

  • The geographic scope and approximate scale of the map are stated.
  • The time period or data currency is noted where relevant (e.g., "as of March 2025").
  • The authority or source of the underlying data is identified for maps used in decision-making.

Selecting the Right Alternative Format

Matching the text alternative format to the map's dominant semantic layer improves comprehension and usability:

Map purpose Recommended alternative format
Show locations of services or facilities Structured table: name, address, accessibility features
Describe a route or navigation path Ordered list of step-by-step directions
Convey spatial and directional relationships Prose with explicit directional language (north, adjacent, across from)
Show quantitative distribution across areas Data table with region names, values, and units
Show administrative or boundary zones List of zones with attributes and what they mean
Show multiple overlapping data layers Separate structured alternative for each layer, plus a combined summary

Applying Equivalent Purpose in Practice

  1. Identify the map's purpose first. What task is the user expected to accomplish with this map? Start from purpose, not visual content.
  2. List the semantic layers present. Which of the six taxonomy layers (spatial, directional, categorical, relational, quantitative, contextual) are active in this map?
  3. Draft the alternative for each layer. Address each relevant layer in the text alternative.
  4. Test task completion. Ask: can a user relying solely on the text alternative complete the same tasks as a user who can see the map?
  5. Iterate with users. Equivalent purpose evaluation is most reliable when tested with blind and low-vision users who navigate by the text alternative alone.

References

Standards

Research

Guidance and Community Resources

Open Source Map Accessibility Projects

Machine-Readable Standards

For AI systems and automated tooling, see wai-yaml-ld for structured accessibility standards: