Landmarks

This is a browser extension (for Firefox, Chrome, Opera and Edge) that enables navigation of WAI-ARIA landmarks, via the keyboard or a pop-up menu.

Landmark regions broadly signpost the areas of a page (e.g. navigation, search, main content and so on). They can make navigation considerably easier for people who use the keyboard to navigate and those using assistive technologies such as screen-readers, because they make it much quicker to get an overview and to navigate to (and between) areas of interest.

If you're an author or developer and want to learn about landmark regions, check out the information below on why landmarks rock, and how easy they are to put into your site. If you're using HTML5, you most likely already have landmarks on your site, but there are some ways to make them even more helpful, as described below.

Table of contents

• Installation and usage
• This extension's support for landmarks
• Learning about landmark regions
• Development
• Acknowledgements

Installation and usage

Use the installation links on the home page to install the extension. When it's installed, you will find documentation on topics such as:

• How to navigate by shortcut key, and how to change the shortcut keys.
• How to navigate using the toolbar pop-up.
• How to navigate using the sidebar (where supported).
• Border preferences, for landmark highlights and labels whilst navigating.

The rest of this file provides information that may be of help and interest to web authors, designers and developers, accessibility testers and browser extension developers.

This extension's support for landmarks

The Landmarks extension uses the Page Structural Semantics Scanner Tests suite; you can find information on standards support there.

Learning about landmark regions

Landmark regions can really help people get a quick overview of your content, and navigate it much more effectively. This can save them a lot of time, so please consider implementing landmarks on your site. If you're using HTML5, you'll almost certainly have some landmarks already, but there are some things you need to know; the info below will help you ensure your landmarks are as helpful as possible.

• All about landmark regions, and some golden rules (story and slides for my a11yTOConf talk)
• Léonie Watson demonstrates landmarks (video)
• W3C ARIA landmarks example and advice page
• Easy content organisation with HTML5 (The Paciello Group 'blog article)
• Using WAI-ARIA landmarks (The Paciello Group 'blog article)

Please bear in mind the following when implementing landmarks...

• It's important that landmarks are not over-used, because their power comes from providing a concise overview of the content of the page. The heading hierarchy for the page can be relied upon for more fine-grained navigation within a particular area of a page.

  Rule of thumb: Use as few landmarks as possible, but ensure that all of the content on the page is within a landmark region.

• If you're using HTML5 elements such as <header>, <nav>, <main> and others, then your page will inherit some landmarks automagically. However it can be really helpful to label them (especially if there's more than one landmark of the same type on a page, such as a separate site-wide and page-local <nav>). The W3C documentation has all the details, but essentially you would use either the aria-labelledby or aria-label attribute.

  Rule of thumb: If you've more than one landmark of the same type, then be sure to label them, so their purpose is clear.

Development

You can build and run the current code locally as follows.

1. Clone the Landmarks repository on GitHub to your computer.

2. Ensure you have all the required build tools with npm install (you will need Node.js).

3. Run the tests and build script to create versions of the extension for all browsers with npm run build:all.

   Note: You need to run scripts/generate-valid-elements.ts first, and whenever the source code changes. This checks the static HTML for various ids that the code refers to, and tells TypeScript that they exist. Some ids are computed dynamically, though, and can't currently be checked. This step will eventually be integrated into the build process.

   The built versions of the extension are placed in build/<browser>/ directories and ZIP files for each will be created in the root of the checked-out repository.

4. To load and use the extension locally in your browser...

   If you have web-ext installed, issue npm run start:<browser> to open the browser with Landmarks freshly installed. It will keep itself up-to-date when you re-build. To manually temporarily load the built extension in each browser, follow these instructions...

   • Firefox: Temporary installation in Firefox
   • Chrome: Instructions in the "Create the manifest" section of the "Getting started" docs
   • Opera: Testing and Debugging
   • Edge: Sideload an extension

Some further info on the test/build process:

• Automated tests are run as a pre-requisite part of the build process; you can also run them with npm test.

• There's also a script you can use to run various performance tests. For more information, call node scripts/profile.js --help.

• The pre-commit hook is used to ensure only code that passes tests is committed (it does this by running a build, which, in turn, runs the tests). Husky manages this so that a build is run before you are asked for a commit message.

• You can remove the build/<browser>/ directories and ZIP files for all browsers with npm run clean:builds.

• Because the process of rasterising the SVG to variously-sized PNGs is slow, the PNGs are cached so they only need to be re-generated when the SVG changes. They are cached in the build/png-cache/ directory.

• For advanced use, you can run the build script directly (which bypasses the tests, beware) with node scripts/build.js --help.

Test pages

The following pages are incorporated into the automated test suite, but you can also visit them in-browser to try out the extension's UI.

• HTML5Accessibility: ARIA landmarks
• HTML5Accessibility: structural elements

Acknowledgements

This is a fork of the original landmarks extension written by David Todd at IBM. Thanks to Steve Faulkner for encouraging me to work on this, for feature suggestions, help with the relevant specifications and initial test cases (and again to David Todd for supporting my contributions). Thanks also to The Paciello Group for donating my development time when this was a Firefox-specific extension and during the conversion to the WebExtensions API.