I’m remaking this website in the open. Follow along, if you wish: Writing, RSS, Source


Everything I Did to Make This Site Accessible

I believe the web is meant to be open and available to everyone, no matter who they are, what device/software they’re using, or the speed/quality of the network they’re on.


Accessibility (also known as a11y) is so much bigger than just making things work for people with no or low vision. But, even if you define it so narrowly, that’s still 285 million people or ~5% of the world’s population. What follows is a collection of everything I’ve done to make this site as accessible as I could.

Note: I‘m using The A11y Project‘s helpful checklist as a rough starting point for this post.

Not relying on JavaScript (Progressive Enhancement)

This site is built using React, a JS library. But, it renders everything from the server before all that JS does anything. The JS then progressively enhances the site to enable things like super-fast additional page loads and the SVG animations. This means that the site will be accessible even if the JS were to fail for any reason. You may think the numbers for that are small… like, 1%. Keep in mind that it’s not 1% of people who always encounter a broken site, and 99% of people who don’t. It’s 1% of visits. I stole that line from this wonderful illustration of the phenomenon.

Also, progressive enhancement makes supporting older browsers so much easier. Because the site will always work without JS, you can cut the mustard so that your JS only runs on your supported browsers. Meaning you don’t ever have to write JS to work in non-modern browsers.

Making it responsive

The only reasonable way I know of to ensure a website is usable on any device/software is Responsive Web Design.

Writing semantic HTML

The easiest way to make something accessible is when you get it for free. By using <header>, <footer>, <nav>, <button>, and other elements appropriately, you build accessibility into the very structure of your app. This includes using <h1>, <h2>, etc… in a sensible order. I reviewed this site’s code and found some areas I could improve.

A11y commit #1

Supplanting semantic HTML with aria landmark roles

While most browsers automatically associate, say, <main> with aria-role="main", not all do. So it’s best to go ahead and define those yourself.

A11y commit #2

Focus states

A lot of sites have some CSS like this to remove the default dotted outline when elements are focused in some browsers:

a:focus {
  outline: none;
}

Don‘t do that! If you absolutely must remove it, you also must define your own focus styles.

Use alt text (and the equivalent for SVG)

Any image in the content of a site must have an appropriate alt attribute defined. The only exception is images that are purely decorative.

For SVGs, you can use the <title> and <desc> elements to describe the graphic in combination with aria attributes. See the commit for examples.

A11y commit #3

Test for sufficient color contrast and color blindness

Researchers have determined a minimum threshold for foreground/background color contrast that is readable by most people, which is specified as part of WCAG. You can use a tool like aXe, which integrates into Chrome‘s Dev Tools, or tota11y, which can be integrated into your site or used as a bookmarklet, to check if the text of your site meets this threshold. There are some gotchas, though:

  1. It will only test actual text and backgrounds, not text that is part of or on top of an image.
  2. It cannot determine the contrast of pseudo-elements (::before & ::after)

After running checks, if I find any colors that need changed, I like to use Colorable to find values with sufficient contrast.

A11y commit #4 & A11y commit #5

Consider a “Skip to content” link

Sometimes a site can have a lot of stuff that a person using a screenreader or restricted to a keyboard would have to wade through before they get to the content. Including a link to skip down to the content in the very beginning of your page that is visually hidden until focused is a nice way to help them out.

This site has a very minimal header and the primary navigation is at the bottom of the page, so the link I‘m adding will be “Skip to navigation”.

A11y commit #6 & A11y commit #7

Make sure to use descriptive links

Consider the post teasers on my Writing page. They have a title, a brief excerpt of the post, and a Keep Reading… link. Sighted users can see that the “Keep Reading…” belongs to the post above it, but screen readers have no way of relaying that information to their users. That is, not without a little help.

We can use aria attributes again to add a more descriptive label to those links:

<article role="article">
  <h3 id="everything-i-did-to-make-this-site-accessible"><a href="/writing/everything-i-did-to-make-this-site-accessible/">Everything I Did to Make This Site Accessible</a></h3>
  <em><span title="April 12, 2016">3 days ago</span></em>
  <div>I believe the web is meant to be open and available to everyone, no matter who they are, what device/software...</div>
  <a href="/writing/everything-i-did-to-make-this-site-accessible/" aria-labelledby="everything-i-did-to-make-this-site-accessible">Keep reading…</a>
</article>

Thanks to this CodePen by Gray Ghost Visuals for the technique.

You should also generally avoid using generic phrases like “Click here” for your links, because they provide very little context.

A11y commit #8

Test, test, test

After you’ve done everything you can, you should test your site using assistive technology tools. Ideally, you‘d do so with someone who uses such tools on a regular basis, but you can simply use the tools yourself in a pinch. If you‘re on a Mac, you have VoiceOver built in.