There are countless little gotchas and quirks to remember when writing markup, even for basic components. This is an attempt to capture and centralize them.
Use this as a starting point when creating your base markup and styling for a stable, progressively enhanced foundation to your site or app, or cherry-pick as needed.
There are a few of ways to work with this repo:
- Clone it in its entirety:
- Download a zipped copy
- Install via NPM:
npm i accessible-html-content-patterns
- Curl just the HTML page (great starting place for a styleguide):
curl -o accessible-html-content-patterns.html https://raw.githubusercontent.com/ericwbailey/accessible-html-content-patterns/master/docs/index.html
- Copy/paste individual elements from the source code
To review any changes you make locally, run
make build from the command line. This will stitch the handlebar templates together to update
Classes and IDs
Are suggestions only, or used for internal navigation/reference. Don't feel you need to include them if they're not relevant to your component's needs.
Tabs, indentation, comments, etc. are my personal preference. It's more important to be consistent than literal when using for your own project. Use EditorConfig to help make this easier.
This page has been tested via the Chrome DevTools Accessibility Audit, as well as WebAIM's WAVE and Deque System's aXe accessibility testing browser extensions, as well as Khan Academy's tota11y bookmarklet.
Answers to specific warnings issues are available on the repo's Wiki.
Contributions are welcome!
Credits, Attribution, and Inspiration
- WebAIM: Three things you should know before using VoiceOver for testing
- Adam Morse's mrmrs/html
- HTML5 Doctor
- Alistair Duggin's Accessibility Fails
- Paul J. Adam's WAI-ARIA Landmarks Site Navigation Structure Demo
- The Falsehoods Programmers Believe series
- GOV.UK Elements
- Baymard Institute's Touch Keyboard Types
- Chrome Autofill
- Nielsen Norman Group's Checklist for Designing Mobile Input Fields
- Why Don’t Screen Readers Always Read What’s on the Screen? Part 1: Punctuation and Typographic Symbols
- LeonieWatson's Accessible emoji
- Nathan Curtis' Buttons in Design Systems
- Filament Group: I Wanted to Type a Number
- CSS-Tricks' Finger-friendly numerical inputs with inputmode