Accessibility for Giants

This is a little project I'm trying out, using nextra (opens in a new tab) to build the site based on next.js, which in turn uses mdx (opens in a new tab) to write the content.

The primary goal of this project will be to provide various examples of how to make your website more accessible, with some failing examples followed by how to fix them.

Hopefully, as these become more usable, we can start to produce more accessible websites for everyone.

Accessibility?

The main goal of accessibility is to make sure that everyone can use your website, regardless of any disabilities they may have.

The added benefit of this is that it also makes your website easy to use for everyone else. Whether that's seeing well contrasted text in bright sunlight, or having room for error when trying to click buttons in a moving vehicle, every change made to support accessibility will also make your website easier to use.

This site won't aim to reach WCAG 2.2 AA (opens in a new tab), and won't help you reach it either. But it will help to get a simple, readable, starting point that helps to add some basic accessibility to your site.

What are these page titles?

The layout of the folders and page titles are based on the headings / sections in the Accessibility Insights for Web (opens in a new tab) extension, which our QA Team aims to use for the testing of Accessibility requirements for a consistent approach across the team.

An example can be seen in the "Run the automated checks" (opens in a new tab) section of the documentation that helps visualise those headings, and these are nice sensible groupings of the WCAG requirements.

Why nextra?

Copilot wanted me to say "I've been looking for a way to write content in markdown, but also have the ability to add some custom components to the content." but this sounds very sales-pitch-y.

Realistically, I had a plan to make a static site with some fun examples, and then I spotted the nextra template on the next.js website and wondered if markdown with inline components would be easier to write about and visualise the content than a full HTML app.

I may swap back at some point. The beauty of this is that it's all markdown, so I can just copy and paste it into a new project if I want to.

And the MDX thing looked cool so I could put some components in the markdown. Such as this example from the nextra site (opens in a new tab):

Then when I want to show the code, it also used "Shiki (opens in a new tab)" to highlight the code, which is nice.

import { useState } from 'react';
import DemoIframe from '../components/DemoIframe';
 
export const Counter = ({ children }) => {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(count + 1)}>
      {children}
      {count}
    </button>
  );
};
 
<DemoIframe height={40} width={200} title="Demo button">
  <Counter>**Click me!** Clicks: </Counter>;
</DemoIframe>;

Learnings!

Going forward, I'd recommend not using Nextra unless you plan to use a fully custom theme, as trying to fix each small thing with the Nextra styles or components has been one undocumented issue after another.

It's nice for a quick bootstrap and getting things into place, but there's probably something out there that does it better, and there is not an easy way to just configure the things you want to configure.

I think it's nice once configured. Just throwing together an MDX file and having it look nice is great, but the initial setup is a bit of a pain and the documentation is lacking.

Intellisense

Final note on this page, VS Code has a nice vscode-mdx extension that can help with the intellisense for the components. For example, in this page, the <DemoIframe> component has a height and width property, and the intellisense will show those when you start typing the component name.