|
| 1 | +# Accessible HTML Content Patterns |
| 2 | +A collection of the full [HTML5 Doctor Element Index](http://html5doctor.com/element-index/), minus the `<details>`, `<summary>`, `<command>`, and `<menu>` tags (which have poor browser support), as well as common markup patterns for quick reference. |
| 3 | + |
| 4 | + |
| 5 | +## Motivation |
| 6 | +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. |
| 7 | + |
| 8 | +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. |
| 9 | + |
| 10 | + |
| 11 | +## Installation |
| 12 | +There are a few ways to work with this repo: |
| 13 | + |
| 14 | +- Clone it in its entirety: `https://github.com/ericwbailey/accessible-html-content-patterns.git` |
| 15 | +- Download a zipped copy |
| 16 | + |
| 17 | + |
| 18 | +## Code Concerns |
| 19 | + |
| 20 | +### Classes, IDs, and Attributes |
| 21 | +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. |
| 22 | + |
| 23 | +### Code Style |
| 24 | +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](http://editorconfig.org/) to help make this easier. |
| 25 | + |
| 26 | +### Accessibility Testing |
| 27 | +This page has been tested via the Chrome DevTools [Accessibility Audit](https://chrome.google.com/webstore/detail/accessibility-developer-t/fpkknkljclfencbdbgkenhalefipecmb?hl=en), as well as [WebAIM's WAVE](http://wave.webaim.org/extension/) and [Deque System's aXe](http://www.deque.com/products/axe/#aXeExtensions) accessibility testing browser extensions, as well as [Khan Academy's tota11y bookmarklet](http://khan.github.io/tota11y/). Answers to specific warnings are: |
| 28 | + |
| 29 | +#### DevTools Audit |
| 30 | +| Error | Reasoning | |
| 31 | +| :---- | :-------- | |
| 32 | +| [Warning] role=main should only appear on significant elements | `role="main"` is applied to the sole `<main>` element on the page. | |
| 33 | +| [Warning] The purpose of each link should be clear from the link text | This is good advice. I'm going with brevity in the document for the sake of expediency, but don't do this in a production environment. | |
| 34 | +| [Warning] These elements are focusable but either invisible or obscured by another element | This error is being triggered by the fallback markup for the `<audio>`, `<video>`, etc. elements and should be retained. | |
| 35 | + |
| 36 | +#### aXe |
| 37 | +| Error | Reasoning | |
| 38 | +| :---- | :-------- | |
| 39 | +| Documents must have `<title>` element to aid in navigation | This error is generated from the `about:blank` page in the `<iframe>` example. | |
| 40 | +| `<html> `element must have a valid lang attribute | This error is generated from the `about:blank` page in the `<iframe>` example. | |
| 41 | +| `<ul>` and `<ol>` must only directly contain `<li>`, `<script>` or `<template>` elements | Nested lists are valid markup. | |
| 42 | +| `<video>` elements must have an audio description track | This error won't apply when the provided `track` attribute is linked to a valid subtitle file. | |
| 43 | + |
| 44 | +#### WAVE |
| 45 | +| Error | Reasoning | |
| 46 | +| :---- | :-------- | |
| 47 | +| Suspicious link text. Link text contains extraneous text or may not make sense out of context. | This is good advice. I'm going with brevity in the document for the sake of expediency, but don't do this in a production environment. | |
| 48 | +| Redundant link. Adjacent links go to the same URL. | Links have been given a null value. This error shouldn't appear when actual link `href` values have been indcluded. | |
| 49 | + |
| 50 | +**A note about [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA):** ARIA is a band-aid and not a cure-all. Use semantic markup whenever possible. |
| 51 | + |
| 52 | + |
| 53 | +## Contributing |
| 54 | +Contributions are welcome! Submit a [Pull Request](https://github.com/ericwbailey/accessible-html-content-patterns/pulls) or [raise an issue](https://github.com/ericwbailey/accessible-html-content-patterns/issues). |
| 55 | + |
| 56 | + |
| 57 | +## Credits, Attribution, and Inspiration |
| 58 | +- [Adam Morse](http://mrmrs.cc/)'s [mrmrs/html](https://github.com/mrmrs/html) |
| 59 | +- [HTML5 Doctor](http://html5doctor.com/) |
| 60 | +- [Alistair Duggin](http://alistairduggin.co.uk/)'s [Accessibility Fails](http://aduggin.github.io/accessibility-fails/) |
| 61 | +- [Paul J. Adam](http://pauljadam.com/)'s [WAI-ARIA Landmarks Site Navigation Structure Demo](http://pauljadam.com/demos/landmarks.html) |
| 62 | +- The [Falsehoods Programmers Believe](http://spaceninja.com/2015/12/08/falsehoods-programmers-believe/) series |
| 63 | +- [GOV.UK Elements](http://govuk-elements.herokuapp.com/) |
| 64 | +- [Baymard Institute](http://baymard.com/)'s [Touch Keyboard Types](http://baymard.com/labs/touch-keyboard-types) |
| 65 | +- [Chrome Autofill](https://developers.google.com/web/updates/2015/06/checkout-faster-with-autofill?hl=en) |
| 66 | +- [Nielsen Norman Group](https://www.nngroup.com/)'s [Checklist for Designing Mobile Input Fields](https://www.nngroup.com/articles/mobile-input-checklist/) |
| 67 | + |
| 68 | + |
| 69 | +## License |
| 70 | +MIT License |
0 commit comments