What I've Learned About Web Accessibility as a Dyslexic, Sighted, Mouse User

Headings

Headings are one of the most important HTML elements for improving accessibility, particularly for screen reader users. They are the main structure used to navigate page content based on topic.

Because screen reader users use headings to navigate, they should not be used just to make text look large and bold (if its not a heading). Likewise CSS styling should not be the only thing that indicates a portion of text is a heading, as screen reader users won't know its a heading and won't be able to navigate by using them.

h1 - the page title

The largest and most important heading, h1, should only be used once in the page, as the title of the page.

If your page is small or has only one type of content (ex. a gallery) you may only need to use the h1 heading. However, if your content would benifit from being broken down into smaller sections, you should use smaller headings accordingly.

h2 - the second heading and navigation

h2 is the second most important heading, which is often used to section articles into their major points or topics.

For example, the "Preface," "Table of Contents," "Headings," and "Semantic HTML" headings on this page are h2 headings.

Not only can h2 be used for article headings, but they can also be used to label sections like the following examples:

• navigation
• links
• notices
• updates
• comments

Basically, any content that is separated into its own section should have an h2 heading.

h2 headings help screen reader users know right away what is in a section, so they can know if it is something they want to read or not, without having to listen to a whole chunk first.

h3 to h6 subheadings

h2 sections can be split up further into subsections using h3 headings. Likewise, h3 sections can be split into subsections using h4, h4 sections can be split into subsections using h5, and h5 sections can be split into subsections using h6.

Headings should only jump down in importance by 1 step.

The next heading after the h1 heading should be an h2 heading, not an h3, h4, h5, nor h6 heading. The next heading after an h2 heading should be an h3 heading, and so on.

The opposite is not true. You can jump up in importance by any amount. So if you finish the content under an h6 heading, and you're ready to move onto the next major topic in the article, you can use an h2 heading next.

Headings smaller than h6?

There aren't any smaller heading elements than h6, but if you have subsections within your h6 section, you can add two attributes to an element to make it function as an h7 element for screen readers!

<div aria-role="heading" aria-level="7">
  Example of a Seventh Level Heading
</div>

This method can be used for as many subsection headings as needed (ex. h8, h9, h10, etc). You will probably want to create a class for these to style, since they do not come pre styled.

Semantic HTML

Semantic HTML refers to HTML elements that indicate what they contain, so basically all HTML elements except span and div!

Some of these elements have preset styling and functions, like button and a, while others just indicate what part of a page something is (header) or what its purpose is (figure). They are very helpful for letting screen readers know what an element is, thus how they can interact with it. You can absolutely use span and div (very useful for CSS styling), but try to use semantic elements where they make sense.

You already use semantic elements like p and img (p holds a paragraph, and img holds an image)! But some semantic elements are less known. For a large list of semantic elements, check out the HTML semantics cheat sheet!

Landmark Elements

Landmark elements are among some of the lesser known semantic elements, but they provide important navigational tools for screen reader users, and help filter out unimportant content for reader mode users! These include:

• main
• aside
• header
• footer
• nav
• section

Heres a guide about landmark regions but I will also cover them.

Nav Element

If you have a div containing your page/site navigation links, use a nav instead! This allows screen readers to jump directly to the navigation to find the page they want, or skip navigation they are already familiar with.

Note that not every section containing links should be in a nav element, only links to your own pages or within your page. Links to other peoples websites or articles should not be in a nav element.

<div class="nav">
  <ul>
    <li><a href="home.html">home</a></li>
    <li><a href="about.html">about</a></li>
    <li><a href="blog.html">blog</a></li>
  </ul>
</div>

<nav class="nav">
  <ul>
    <li><a href="home.html">home</a></li>
    <li><a href="about.html">about</a></li>
    <li><a href="blog.html">blog</a></li>
  </ul>
</nav>

Both of the above examples would produce the same effect for a sighted user:

But since the second example in green has a nav element instead of a div element, screen reader users know what it is right away. This is extra helpful if a site has the same navigation on all pages, and the user wants to quickly jump to or past the navigation.

Sometimes you may have more than one nav element in a page, usually for a site navigation and a page navigation. To differentiate these you can use an aria-label attribute in the nav element like so:

<nav aria-label="site">

<nav aria-label="page">

You do not need to put the word "navigation" in the aria label, since the screen reader already announces "navigation" for the nav element.

Note: aria-label should be used sparingly, usually just for multiple nav elements on one page, and interactive form elements. For more information read the article, Aria-Label is Not Always the Answer.

Header and Footer

Headers are the bars at the top of some websites, usually containing the site navigation/menu and the organization's logo. Personal sites don't always have a header, so if you don't have one, you don't need to use the header element.

Likewise, footers are at the bottom of a page and more common on professional sites. They tend to contain copyright information and site links.

Since both headers and footers are usually the same on each page across a single site, screen reader users usually skip them so they dont have to hear the same information over and over. This is easier to do if they are actually in header and footer elements.

Main and Aside (and Reader Mode)

It can be helpful to determine what goes in the main and aside elements by considering reader mode. Reader mode is a browser feature designed to hide distracting content and make articles easier to read by displaying them in plain font with minimal styling. This is helpful for readers with learning or cognitive disabilities, and anyone who wants to read news articles without all the ads and article previews on the side.

So with that in mind, the main element should contain only important content on the page.

This excludes headers, footers, some side bars, comment sections, or anything that isn't the main point of the page.

Like the h1 element, there should be only one main element in a page.

Unimportant content that isn't in a header or footer should be put in an aside element.

This is true whether its actually on the side or not. Reader mode hides aside elements from the reader, so if content is needed to understand the article, don't put an aside element. Read more about aside.

According to Owl in Please Let Me Use Reader Mode, your page should have its main content in an article tag nested in a main tag, have p elements, and have at least a sentance's worth of text in order for your article to show in reader mode. Note that this is true for articles, blogs, guides, or any text heavy pages. Reader mode is less relevant for pages with minimal text.

Unfortunately each browser's reader mode works a bit differently, and if a page does not meet the reader mode's (unpublished) requirements, the reader won't be able to use reader mode on it. Thus, its best to use semantic HTML and make sure your page content is understandable without CSS styling. Its also a good idea in general to style text heavy articles or guides with minimal distractions and easy to read font.

Section

The section element is a rather generic element compared to the other landmark elements. They are typically used to create different sections in an article. Section elements are not for content that can be presented on its own page (use an article for this).

Sections should be labeled with a heading element.

Not only can they be used in articles, but they can also house specific seperate content.

• widgets
• comment sections

You would usually use h2 to label these.

I would advise using section elements carefully (rather than for every single heading). Section elements are landmark elements, which describe major parts of a page, and too many section elements would create a cluttered landmark "map". More about the accessibility of the section element.

If you do use section elements to contain your topics, label them by using aria-labelledby. Give the heading an ID, and put that ID into the aria-labelledby attribute. If you can't give a section a heading, you can use the aria-label attribute with the label as text inside the quotes.

<section aria-labelledby="updates">
  <h2 id="updates">Page Updates</h2>
    [updates here]
</section>

<section aria-label="side notes">
  [notes here]
</section>

Note that using aria-labelledby with a heading is prefered to using aria-label. This is because the aria-labelledby method allows screen reader users to navigate sections by using both landmark elements and headings. Aria-label does not involve headings, thus screen reader users can't navigate these elements by headings.

Example Layouts with Landmark Elements and Headings

Now that we've covered both landmark elements and headings, we can put them together to create a semantic page layout that screen readers can navigate.

(Note: I used fieldset elements as visual grouping in the examples below, no form elements are actually used.)

Article

The article element is not a landmark element, but like landmark elements, its useful for semantically defining major sections of a page.

The article element describes a section that could be presented independently from the rest of the page.

Most pages usually contain only one article, but they can contain multiple (unlike main and h1 elements). For example, a blog or journal that shows all entries on the same page could have each entry contained in its own article element. Multiple articles on a blog or news page should have a h2 as their title (as the h1 header is reserved for the title of the entire page).

Div and Span

Although it's important to use semantic HTML, that doesn't mean you shouldn't use div and span elements. In fact, trying to use a semantic element like a section in place of a div, may make your page less accessible. A small section of text may not warrant the importance the section or article tag gives it.

It's more important to avoid misuing semantic elements than it is to avoid using divs and spans. Use semantic HTML where it is useful and makes obvious sense, like putting a picture in an img tag, or an article in an article tag. Divs are very appropriate for separating content into blocks with visual styles. Span is good for when you want to outline some text in a paragraph (but not as buttons).

Buttons

Any element that the user needs to select to preform an action (close, submit, open, etc) should be a button element. Some web designers make a div, span, link, or image and give it an onclick event instead of just using the button element. This is like making an empty div and giving it a background image instead of just using the img element (except its actually worse).

Links can be styled to look like buttons, but the a element should only used if it takes the user to a different location (site, page, or place within a page).

<span onclick="function()">change font</span>

<button onclick="function()">change font</button>

The great thing about buttons is that they already function as they should. They let screen reader users know that its a button, and they let keyboard users activate them by pressing enter or space. Buttons also have built in styling that gives them a border and outline when the keyboard is positioned on them (this outline is important for sighted keyboard users to tell where they are on the screen). A span or div element does not do this with only an onclick function, you would have to add these abilities with role="button" and extra JavaScript.

For related information, visit the article Use semantic HTML for easy keyboard wins.

<script>
  var x = document.querySelectorAll('.classexample'); 
  for(var i=0; i<x.length; i++) {
    x[i].setAttribute('tabindex', '0');}
</script>

<span onclick="function()" onkeypress="function()">
  change font
</span>

.classexample:focus {
  border: 2px solid blue;
  outline: 2px solid white;}

<script>
  var x = document.querySelectorAll('.classexample'); 
  for(var i=0; i<x.length; i++) {
    x[i].setAttribute('role', 'button');}
</script>

Image Descriptions

Image descriptions give pictures a text alternative, useful for screen reader users who would otherwise miss out on the information contained in the picture.

Images that contain relevant text should have the text transcribed exactly. This is particularly true for screenshots, though if you can, consider putting the plain text in a blockquote element with credit, that way everyone can access the same thing.

Text that is not important to the image however, does not need to be transcribed. A photo of a city scene does not need to have every traffic or building sign transcribed.

Alt Text

Brief descriptions go in the alt attribute.

Alt text is basically a quick look at an image. Sighted users don't closely study every image they come across, so do not put a paragraph's worth of text in the alt text, a phrase to two sentances is usually good. Note that not every img element needs a description.

Decorative images should have an empty alt like so: alt="" (no space between the quotations).

This prevents cluttering the listener experience with irrelevant or distracting details. You would do this for fun little gifs on your homepage (though if the page's entire purpose is to collect gifs, give them alt text.) Note that you shouldn't omit the alt attribute entirely, as the screen reader may read the file name (possibly a long string of numbers) and the user will wonder if the image was important or not.

For image links, the alt text should describe the link destination, not the image.

For example, the alt text of a book gif linking to your guestbook should read something like "guestbook," not "book with flipping pages"

<a href="guestbook.html">
  <img src="book.gif" alt="animated book with flipping pages">
</a>

<a href="guestbook.html">
  <img src="book.gif" alt="guestbook">
</a>

You may already have text next to an icon (like the word "home" next to a house icon). An alt attribute would be redundant, so you should leave the alt empty.

You don't need to put "image of", "picture of", or "graphic of" in the alt text, because the screen reader will announce that the element is an image. However, if the image being a painting, photo, diagram, screenshot, illustration, etc is relevant, include it in the description.

Alternative Text by WebAIM.

Figure and Figcaption

figure is a semantic HTML element that holds both a caption (figcaption) and the figure, which is usually an image (but it can be other things, like code).

< figure>
  <img src="rainbow.jpg" 
    alt="photo of a rainbow over a forest">
  <figcaption>
    (imagine a detailed description here)
  </figcaption>
</figure>

The figcaption should be either ther first or last element inside the figure element.

Figure captions are usually used to give relevant information, such as title, author, date, and location, but you can put other kinds of information in them.

Figures are particularly useful if you have multiple related images, and want give them a caption as a group.

Aria Described By and Aria Details

Most images only need a short description, but you may want longer descriptions for artwork and complex diagrams.

You can write a description in a paragraph and use the aria-describedby attribute to "link" the description to its image. This is particularly useful if you were already going to describe the image in the text. "Linking" it prevents redundancy that would be created if you repeated the description in the alt text.

<img src="rainbow.jpg" 
  aria-describedby="rainbowdesc"
  alt="photo of a rainbow over a forest">
<p id="rainbowdesc">
  (imagine a detailed description here)
</p>

You can name the description anything (as long as no other element has the same ID).

Unfortunately aria-describedby still only reads the text as a single string, making it limited to a paragraph. To preserve more complex formatting, use aria-details, which also uses IDs. Here's a guide on aria-details.

If necessary, you can hide descriptions from sighted users. Theres a few ways to do this with CSS, just don't use display: none; since screen readers can't access elements hidden this way. Hiding the description should not be your default choice though, anyone (not just screen reader users) can benefit from image descriptions.

.visually-hidden {
  clip: rect(0 0 0 0);
  clip-path: inset(50%);
  height: 1px;
  overflow: hidden;
  position: absolute;
  white-space: nowrap;
  width: 1px;
}

Skip Content Links and Keyboard Navigation

Skip links allow keyboard users to skip past a large group of interactive elements, so they don't have to press the tab key a bunch of times. This is particularly important for people who have limited mobility where pressing keys is difficult or painful (yet less so than using a mouse).

Links, buttons, form elements, and details, are all elements that a keyboard user will have to tab through on a page. Links and buttons will activate if the user presses enter or space.

If you have a bunch of interactive elements in a group (like a list of links,) put a link before them, linking to the ID of the element after the group.

Just make sure that you have described the links or other repetitive content somehow before or in the skip link, so the user can decide if they want to bypass the elements or not.

<h2>Cool Sites</h2>
  <a href="#next"skip past 3 links</a>
  <ul>
    <li><a href="url1">first site</a></li>
    <li><a href="url2">second site</a></li>
    <li><a href="url3">third site</a></li>
  </ul>
<h2 id="next">Next Section</h2>

The above example only has three links, which would not actually warrant a skip link. Putting too many skip links on a page defeats the purpose of skip links (it simply adds more things for users to tab through).

Skip links are commonly used at the very beginning of HTML documents to allow users to skip to the main content. This is not needed if the main content starts right away, but it is recommended if you have a header or navigation containing links. (Just like screen reader users get tired of hearing the same header over and over, keyboard users get tired of tabing past the same header links).

Skip links may also be used to bypass keyboard traps. Keyboard traps are places where the user can't escape using keys alone. This usually occurs with iframes or widgets, for example, calander widgets and cbox. If you can't fix the keyboard trap or find an alternative, you must put a link to bypass it so a keyboard user can navigate your page.

You can leave bypass links out in the open, but sometimes, in order to save space, you will want to hide them until a keyboard user tabs to them. Heres a guide explaining skip links and how to reveal links when they are focused on. Note that its important to make them visible when focused on for sighted keyboard users who need to know where they are tabbed at on a page.

Note that you should not make random elements keyboard focusable in attempt to make your page more keyboard navigatable, since the arrow buttons and space bar already do that.

Tooltips, Title, and Hover

Tooltips are labels, short descriptions, definitions, or other pieces of info that appear when a user hovers over an element.

You might use the title attribute on some of your elements as a tooltip or as a screen reader label/description, however, title="example text" is rarely recommended.

The problem is that title text is only accessible on mouse hover or read by a screen reader, sighted keyboard users cannot access title text with a keyboard alone.

Most useful information for screen reader users is better put in an alt or aria-label attribute. The only exception to this is an iframe element which should have a title attribute labeling it. Read more about the title element.

You may have made your own tooltips without using the title element, but they often have the same problems.

Infact, any hidden content that only appears on hover will need to be made keyboard accessable.

Now, if your hover effect is just making a button or link different colored you don't need to worry about making it keyboard accessible, since browsers automatically give these elements a border and outline to show when they are focused on.

In my research into tooltips, I've found a lot of contradictory, inconclusive, and incomplete advice, so unfortunately theres not a clear solution, other than avoiding using tooltips. If the content inside the tooltip is important, consider leaving it visible all the time.

If a tooltip is necessary you can make the element (that a mouse user hovers over) a button, this allows keyboard users to tab into it, and lets screen readers know that its an interactive element. Your button doesn't need JavaScript, just make sure it has the same styling on :focus as the :hover effects.

<div class="tipcontainer">
  <button class="tipactivator">
    example button text
  </button>
  <p class="tooltip">
    extra text in a tooltip
  </p>
</div>

Credit to OhScee on CodePen for the button recommendation and code demo.

.tooltip {
  display: none;}
.tipcontainer {
  position: relative;}

.tipcontainer:hover .tooltip,
.tipactivator:focus + .tooltip {
  display: inline-block;
  position: absolute;}

Note that the next sibling selector (+) is what allows the tooltip to be shown when the button (.activator) is focused on.

<script>
  var x = document.querySelectorAll('.classexample'); 
  for(var i=0; i<x.length; i++) {
    x[i].setAttribute('tabindex', '0');}
</script

Gifs and Animations

Certain animations can be distracting or nausia inducing. In extreme cases they can even induce fatal seizures in people with epilepsy. Fortunately there are ways to reduce these risks without omitting animations entirely.

Gifs, Videos, and Other Animated Files

Risky animations have all three traits:

• flash more than 3 times in 1 second
• are large
• and have high contrast flashes

High contrast flashes are usually flashes of white against dark, flashes of red, or flashes of yellow.

Blinkies seen on Neocities pages are unlikley to cause seizures due to being small, but some larger flashing gifs are more risky.

Note that there are browser extentions like this gif toggling extention that viewers can use. But if you'd like to be extra safe here are some options for your site:

• a JavaScript alert or entry page for pages with flashing gifs
• Using CSS to hide gifs from users who have prefers-reduced-motion set in thier browser
• Using JS to hide/show gifs with a button
• Using JS to pause/play gifs

I go into more detail for each method in my beginners' accessibility guide.

Pausing/playing gifs is very appealing, but the most difficult solution out of these. If it is only a few gifs, you can manually make a static version of each gif, and use JavaScript to change the source of the image. Of course this gets cumbersome the more gifs you want to pause. I have a guide for freezing gifs with JS.

The Freezeframe library allows users to freeze all of their gifs on a page by using the freezeframe class. This is done by overlaying a canvas element over the original gif, which is not without its flaws. I could not get this to work for my homepage, but you may have success. Bechnokid has a guide on implementing freezeframe with buttons.

Full video files should not autoplay, and neither should audio files. This can be disorienting/distracting, and also make it so that screen reader users can't hear their screen readers.

CSS and JS Animations

I would avoid CSS animations that continually wiggle or pulse, like obnxious ads that try to get your attention. These are very distracting, and frankly irritating to any user. Animations that occur on hover or focus are usually fine. Likewise slowly changing color should also be fine. Animations that move or change the size of elements are the troublesome ones.

Carousels, a rotating selection of photos or article thumbnails, are usually an accessability nightmare. Its best to avoid these, and just let users navigate a gallery of photos or list of articles on their own.

Similarly, marquees or other scrolling content should be used sparingly. Like animations, they can result in nausia, but it can also be frustrating to not be able to read text or buttons at your own pace.

@media (prefers-reduced-motion) {}

In this media query you might make the animation a lot more subtle, or remove it entirely. It can also be paired with the freezeframe JS library to make gifs paused from the start for reduced motion users. However, don't rely on this media query alone, as this browser setting is not as widely known compared to light and dark mode preferences.

Viewers should be able to disable CRT filters (a somewhat common stylistic choice on Neocities to evoke nostaligia). The thin lines featured in CRT filters can make it difficult to read text and can give users headaches, especially if they flicker or have moving lines.

JS Scrolling

I don't know anyone who likes their scrolling to be dictated or changed by JavaScript. Whether it be a "smooth" scrolling animation when you scroll or click an internal page link, or jerky scrolling that does not let you pause where you want to, forcing you at one position or another. The effort of changing the normal scrolling experience is not worth it when it causes most users frustration.

Showing scrolling when a user activates an internal page link, rather than jumping straight to the content, can also make viewers dizzy or nausiated.

Back to Top - Home