Accessibility (a11y) Rules

Part 1

Accessibility is about making sure everyone can use your website or app, no matter their abilities. Did you know that 1 in 6 people worldwide—that's over 1.3 billion—have some kind of disability? This could be anything from vision or hearing issues to motor or cognitive challenges. By building with accessibility in mind, you’re helping real people navigate the web more easily, whether they rely on a screen reader, voice commands, or just prefer keyboard shortcuts. It’s about creating a better, fairer experience for everyone—and it’s the right thing to do!
(The above part is brought to you by ChatGPT 🤷‍♂️)

If you want to dive deeper into a11y, check out these articles from MDN and WCAG. For a quick start, read this article on web.dev or watch this a11y podcast on YouTube.

These rules were created using the resources mentioned above. Feel free to comment if you find anything missing or incorrect.

ARIA (Accessible Rich Internet Applications) rules

• The three main features of ARIA—roles, properties, and states/values—should be present in the HTML element. ARIA and HTML article

• If the browser already supports an HTML tag with a built-in ARIA role, don't need to add ARIA manually e.g. <main>, <header>, <footer>, <aside>, <nav> etc.

Rule 1

• Try to use semantic HTML elements.
• ARIA is required only when an HTML element doesn't have a11y support.

Don't	Do
<a role="button">Submit</a>	<button>Submit</button>

Explanation: You don’t have to convert a hyperlink (<a>) to a button because we already have a semantically accurate element.

Rule 2

• Do not add unnecessary ARIA to HTML

Don't	Do
<h2 role="tab">Heading tab</h2>	<div role="tab"><h2>Heading tab</h2></div>

Explanation: The <h2> element has an implicit ARIA role of heading. Additionally, it has an ARIA attribute called aria-level, which corresponds to the heading level (e.g.,<h1> is level 1, <h2> is level 2, and so on). So no need to add an extra role to the <h2> element.

Rule 3

• All ARIA controls that users can interact with (not disabled) must work with the keyboard navigation.

• If an element can’t be focused with the keyboard by default, you can add tabindex="0" to make it focusable.

• Try to avoid using positive tabindex values (e.g., tabindex="1") because it can mess up the order in which users navigate with the keyboard.

Don't	Do
<span role="button" tabindex="1">Submit</span>	<span role="button" tabindex="0">Submit</span>

Rule 4

• Don’t use role="presentation" or aria-hidden="true" on elements that need to be focusable (like those with tabindex="0").

Don't	Do
<div aria-hidden="true"><button>Submit</button></div>	<div><button>Submit</button></div>

Rule 5

• Make sure users know what an interactive element does before they try to use it.

  • Accessible names can be:
  • The text inside the element (like for links)
  • Alternative text (e.g., for images)
  • A label (e.g., for form elements)

Example	Code
A plain link with text between the link tags	<a href="shoes.html">Red leather boots</a>
A linked image, where the image has alt text	<a href="shoes.html"><img src="shoes.png" alt="Red leather boots"></a>
A checkbox input with a label	<input type="checkbox" id="shoes"><label for="shoes">Red leather boots</label>

Landmarks

• At least one landmark per page should be present to ensure content is navigable

• Whenever possible, use semantic HTML elements like <header>, <nav>, <main>, and <footer>. If these aren't suitable, apply ARIA landmark roles (e.g., role="banner", role="navigation", role="main")

Headings

• <h1> should be used for the page's highest and most important information

• <h6> for the lowest and least important information

• sequence of the heading levels is important so do not skip heading levels e.g. starting a section with an <h1> and immediately following it with an <h5> is a bad practice. Instead, you should progress to the <h5> in order. (If the design does not align with the default style of the heading, change it using CSS)

Tip: Why headings and landmarks are so important

Lists

• <li> should only contain content or <dt> and <dd>

• If a <div> is used to wrap the content inside an <li>, and the content within the <div> serves a specific role or meaning, ensure you add appropriate ARIA attributes to improve accessibility. However, avoid using redundant aria-label attributes unless necessary.

Page title

• Page title should be small (55–60 characters) and the important information should be first.

Page language

• The language attribute (lang) in the <html> tag should be set to the default language, English (en)

• multi-language text, make sure to add a lang attribute to the corresponding element (such as a section or paragraph) with the correct two letter ISO 639 language code.

(continue...)