Updated February 27, 2024

Coding with accessibility in mind can be intimidating if you’re not familiar with the needs of disabled, neurodiverse, Deaf/deaf, and hard of hearing users. Yet, it’s an essential skill to be both legally compliant, and to have easy to read and maintain code.

Here are five tips to get you started in making your sites accessible for users and learning how to implement the basics of Web Content Accessibility Guidelines (WCAG). Each tip has a template so you can easily cut, paste, and adjust to fit your projects, and a cats and coffee example so you can see how the tip works in an app.

Contents

  • Page title
  • Landmarks
  • Headings
  • Prefers reduced motion
  • Skip to main content

The Cats and Coffee Examples

All code examples are from a website for the fictional “Crazy Cats Coffee” coffee shop. View the Crazy Cats Coffee codepen here View the deployed site here: https://vanilla.crazycatscoffee.com GitHub repo: [GingerKiwi/CrazyCatsCoffee-Vanilla (github.com)]

Page Title

What is a page title?

The name of your page in the head of your html documents.

Why should developer use a page title?

  1. It’s the first thing a user hears when visiting any page on your site.
  2. It allows screen reader users to know the content of your page quickly, without having to read the majority of the page.
  3. (Bonus): It’s also helpful for search engine optimization (SEO).

How to use page title in your code.

  1. Each title should be unique to the page.
    1. If you have pages that are auto generated from content (e.g. an Astro, or 11ty blog), make sure to autogenerate the title for each page as well. e.g. Use: { {title} } - but omit the spaces between the double curly braces.
  2. Don’t code an empty page title tag.
  3. Make sure each page title is descriptive and accurate.
    1. Good: “Five ways to keep your cats from spilling your coffee on your keyboard - again!”
    2. Not so good: “blog post”

Page Title Code Template

<head>
	<title>My Page Title</title>
</head>

Page Title Code Template - Autogenerated Pages

<head>
	%% For autogenerated pages use this %%
	<title>{ { title } }</title> 
	% omit the spaces between the double curly braces %
</head>

Page Title Code Example

<head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="author" content="Elizabeth McCready" />
    
    <title>Crazy Cats Coffee</title>
    
    <link rel="shortcut icon" type="image/png" href="/assets/blog/favicon-2.png" />
    <link rel="stylesheet" href="/styles.css" />
	
  </head>

Semantic Landmarks

What are semantic landmarks?

Landmarks are section tags such as header, nav, main, and footer that identify different core sections of a page.

Why should developer use semantic landmarks?

  1. They allow users of screen readers and other assistive tech to navigate the page just like a user using their eyes.
  2. Makes it easier for others to read your code. Who wants to get lost in an endless sea of divs?

How to use semantic landmarks in your code

  1. All text on a page should be contained between a pair of landmark tags
  2. If you have multiple incidences of a particular landmark - such as nav in both your header and footer, use either “aria-label” or “aria-labelledby” to show the difference between the two.

Semantic Landmarks Template

<header>
    <nav aria-label="Primary navigation">
        <!--     Navigation links to the Website's pages -->
    </nav>
</header>

<main>
    <!--     The actual content of the page  -->
</main>

<footer>
    <nav aria-label="Secondary navigation">
        <!-- navigation links for topics   -->
    </nav>
</footer>

Semantic Landmarks Example

%% FIRST SEMANTIC LANDMARK - header tag %% 

<header>
	<nav aria-label="Primary navigation">
	%% USED TO TELL THE TWO DIFFERENT nav AREAS APART %%
		<ul>
			<li><a href="/">Home</a></li>
			<li><a href="/menu">Menu</a></li>
			<li><a href="/cats">The Cats</a></li>
		</ul>
	</nav>
</header>

 %% SECOND SEMANTIC LANDMARK  - main tag %% 

<main>
	<h1>Welcome to Crazy Cats Coffee!</h1>
	<!--     The actual content of the page  -->

	<p><em>Your Purr-fect Downtown Coffee Shop! </em></p>
	<p>Percentage of profits goes to support local rescue cat organizations </p>
	<img src="https://gingerkiwi.github.io/hosted-assets/reba-spike-OjB_lkGKhX8-unsplash.jpg" alt="Dark brown long haired cat at coffee shop on a dark wood table by two iced coffees in plastic cups">
	<h2>About Crazy Cats Coffee</h2>
	<p>Information about the coffee shop</p>
	
	<!-- This area can contain multiple headings, content items such as lists, and images, as well as sections and articles -->

</main>

%% THIRD SEMANTIC LANDMARK - footer tag %%

<footer>
	<nav aria-label="Secondary navigation">
		<ul>
			<li><a href="/" class="footer--nav">Home</a></li>
			<li><a href="/blog/coffee-history" class="footer--nav ">Blog: Coffee History</a></li>
			<li class="footer--nav "><a href="/blog/special-events" class="footer--nav ">Blog: Special Events</a></li>
			<li><a href="/cats/adoptions" class="footer--nav ">Adoptions</a></li>
		</ul>
		<!-- navigation links for topics   -->
	</nav>
</footer>

Semantic Headings

What are semantic headings?

Semantic headings are heading tags from h1 though h6 that provide navigation aids, and content organization and structure to your page.

Why should developers use semantic headings?

  1. They help sighted users easily scan to a particular topic on your page.
  2. Screen reader users frequently use a list of headings and jump to the particular section they’re looking for.
  3. Semantic headings help your SEO.
  4. They make your code easier to read by others, and by yourself months or years later - making it easier to maintain.

How to use semantic headings in your code:

  1. Use only one h1 on a page*.
    1. The exception to this is when there’s a modal that covers the page content. That modal can have a different h1 to the page’s h1.
      1. Note that there are specific accessibility concerns with modals, especially with WCAG2.2. These are beyond the scope of this article.
  2. Use heading tags to identify heading levels, and css to style them.
  3. If you want to change the style of a particular heading to be larger/bolder/ the same colour as another heading tag use a css utility class.
  4. Use headings in order. You shouldn’t skip from a h1 to a h4 heading.

Semantic Headings Template

<h1>My Page Topic</h1>
	<!-- some content like paragraphs, images, lists, ...-->

	<h2>Section 1 heading</h2>
		<!-- some content like paragraphs, images, lists, ...-->

		<h3>A subtopic of section 1</h3>
		%page content%
		<h3>Another subtopic of section 1</h3>
		%page content%
		
	<h2>Section 2 heading</h2>
		<!-- some content like paragraphs, images, lists, ...-->

		<h3>A subtopic of section 2</h3>
		<!-- content -->
		<h3>Another subtopic of section 2</h3>
		<!-- content -->

Semantic Headings Code Example

%% h1 - ONLY H1 HEADING ON THE PAGE %%
<h1>Welcome to Crazy Cats Coffee!</h1>
	<!--     some content  -->

	<p><em>Your Purr-fect Downtown Coffee Shop! </em></p>
	<p>Percentage of profits goes to support local rescue cat organizations </p>
	<img src="https://gingerkiwi.github.io/hosted-assets/reba-spike-OjB_lkGKhX8-unsplash.jpg" alt="Dark brown long haired cat at coffee shop on a dark wood table by two iced coffees in plastic cups">

%% H2 MARKS THE BEGINNING OF A SUBTOPIC - IN THIS CASE ABOUT THE BUSINESS %%
	<h2>About Crazy Cats Coffee</h2>
	<ol>
		<li>1st list item about Crazy Cats Coffee</li>
		<li>2nd list item about Crazy Cats Coffee</li>
		<li>3rd list item about Crazy Cats Coffee</li>
	</ol>
	</p>
	
	%% H3 MARKS THE BEGINNING OF A SUBTOPIC THAT'S PART OF THE "ABOUT THE BUSINESS" - IN THIS CASE IT'S ABOUT THE BUSINESS' ACCESSIBILITY %%
	
	<h3 class="font--like-h2">Accessibility</h3>
	
	%% Note the css utility class that changes the styling of the heading, without changing the heading level %%
	<ol>
		<li>
			wheelchair and mobility aid accessible, </li>
		<li>three, single person accessible non-gendered washrooms, </li>
		<li>level access at entrace and to our back garden patio </li>
		<li>American Sign Lanaguage is part of staff training</li>
		<li>silent library room in back with dimmed lighting</li>
	</ol>
	
	<article> % THE SEMANTIC TAG 'article' WILL BE COVERED IN A LATER ARTICLE%
	
	%% WE GO BACK UP ONE HEADING LEVEL TO LEARN ABOUT THE SEASONAL SPECIALS %%
		<h2>Seasonal Specials</h2>
		<p> A selection of our seasonal special snacks, meals, and drinks</p>
		%% H3 - FOR EACH TYPE OF SEASONAL SPECIAL %%
		<h3>Snacks</h3>
		<p> Cheese and crackers</p>
		<p> Ginger cat crazy squares</p>
		<h3>Meals</h3>
		<p> Tuna bagel melt</p>
		<p>Grrrriled cheese</p>
		<p>Zoomie party platter - for sharing with friends!</p>
		<h3>Drinks</h3>
		<p> Ginger cat flat white</p>
		<p> Purrrrfect peppermint hot chocolate</p>
	</article>
</main>

CSS for Semantic Headings Code Example

h1,
h2 {
	font-family: var(--ff-heading);
	color: var(--clr-spice);
	text-align: center;
	padding: 2rem 0;
}

h3 {
	color: var(--clr-spice);
	text-decoration: underline;
}

%% UTILITY CLASS 
- THIS CHANGES THE STYLING OF THE h3 ABOVE TO BE CLOSER TO THE H2 
- WITHOUT CHANGING THE OUTLINE/HEADING LEVEL%%

font--like-h2 {
	font-family: var(--ff-heading);
	color: var(--clr-spice);
	text-align: center;
	padding: 2rem 0;
}

Prefers Reduced Motion

What is prefers reduced motion?

  • CSS that respects users preferences for reduced or no motion and animations

Why should developers include prefers reduced motion in our code?

  1. Motion can trigger seizures, migraines, vertigo, and be painful for users with sight loss, and/or other disabilities and medical conditions.
  2. Yes, animations are cool! But risking a user being in pain or even having an ambulance ride from your animations isn’t cool.
  3. Respecting users’ preferences helps keep users on your site, and reduces the chance they leave your site and never visit again.

How can I include prefers reduced motion in my code?

  1. There are many ways to implement prefers reduced motion. The simplest is below.
  2. For every animated element include it’s class name inside of an @media query in your css.
  3. There’s some really awesome, but more complex ways to implement prefers reduced motion, css that only implements animations and transitions if a user hasn’t set their preferences.
    1. But again, the goal of this article is “quick accessibility tips”.
    2. See Respecting Users’ Motion Preferences by Michelle Barker on Smashing Magazine for an in-depth 12-minute read on different ways to implement prefers reduced motion.
@media (prefers-reduced-motion: reduce) {
  .your-element-name {
    animation: none;
  }
  .your-other-element-name {
    animation: none;
  }
}
<button class="btn--cta">
		Book your holiday party
		<span> - 10% off until Nov 15th!</span>
</button>

.btn--cta {
  border: 5px solid transparent;
  background: var(--clr-spice);
  color: var(--clr-white);
	text-transform: uppercase;
	width: 20rem;
  border-radius: 42px;
  padding: 15px 30px;
	margin-bottom: 2rem;
  overflow: hidden;
  transition: 
    all        1.2s,
    border     0.5s 1.2s,
    box-shadow 0.3s 1.5s;
  white-space: nowrap;
  text-indent: 23px;
  font-weight: bold;
  span {
    display: inline-block;
    transform: translateX(300px);
    font-weight: normal;
    opacity: 0;
    transition: 
      opacity 0.1s 0.5s,
      transform 0.4s 0.5s;
  }
  &:hover {
    text-indent: 0;
		width: 30rem;
    background: var(--clr-holiday-green);
    color: #FFE8A3;
    border: 10px solid var(--clr-holiday-purple);
		padding-right: 20px;
    box-shadow: 3px 3px 2px rgba(black, 0.15);
    span {
      transform: translateX(0);
      opacity: 1;
    }
  }
}

Skip to Main Content

What is skip to main content?

A simple link at the top of the page that allows users to skip hearing the navigation, banner, icons, logos, and get right to the main content.

Why should developers use skip to main content?

  1. This allows users to get to the main content and enjoy it - rather than be annoyed at hearing the entire navigation, banner, logos, icons and other header information read out loud.
    1. You wouldn’t want to spend all the time and effort to develop and maintain a site, only to annoy your users.

How can you include a skip to main content in your code?

  1. The simplest way is to include a visible link before any of your page content - right below the header tag. This is the method we’re using here.
  2. You can also use css, or css and some javascript to make the link visible only on keyboard focus to screen reader users.
    1. As the theme of this article is “quick a11y tips”, I’m not getting into the different options for hiding and showing the link here.

Skip to Main Content template

<header>
	<a href="#main" id="skipToMain" class="a11y--skip-to-main">Skip to main content</a>

%% other header content such as your nav, site logo, branding %%
<header>

Skip to Main Content code example

<header>
	<a href="#main" id="skipToMain" class="a11y--skip-to-main">Skip to main content</a>
	<nav aria-label="Primary navigation">
		<ul>
			<li><a href="/">Home</a></li>
			<li><a href="/menu">Menu</a></li>
			<li><a href="/cats">The Cats</a></li>
		</ul>
	</nav>
</header>

Putting it All Together

See the Pen CrazyCatsCoffee_A11y by GingerKiwi (@gingerkiwi) on CodePen.