Missing an accessibility-first community

It's hard to put into words how lonely it is when you’re the only person ensuring that there aren't click handlers on generic elements. I've come to accept that the bar for "accessibility advocate" is just "still cares about accessibility in spite of it all." I'm used to being the only one giving accessibility feedback when joining a new project. It's exhausting having to explain the same small issues over — the same issues that are easily caught by automated accessibility testing tools. Sometimes, it's tempting to just delete the repository and start over.

When you know anything about digital accessibility, you know that compliance doesn't always have to be a never-ending slog of fixes. It can be baked in from the start.

In many ways, I am lucky. At work, my recommendations are respected and my coworkers want to learn. When I come across hard questions, I can always reach out to former coworkers from my previous job at a digital accessibility company. When I need someone to check my assumptions, I just talk to the accessibility expert friends who always support me. I’ve never asked for permission to fix accessibility issues or build accessibly because accessibility has consistently improved the user experience, that’s worked in my favor.

Recently however, I got the chance to catch up with some of my former coworkers. There was a moment when I said "I don't know if the automated captions are better or worse." One of them responded "Yeah, they're really wrong - a live captioner would be a lot better." I closed my eyes, leaned back in my chair, and sighed "It's nice not to have to explain." Then, I remembered how nice it was to have a live captioner in our meetings. The next week, I started looking at expensive certifications. I wanted a reason to start learning deeply about accessibility again.

Finding an accessibility-first community

When I joined npmx the next month, I was curious and hoped I'd get to learn from brilliant developers. At VueConf 2025, I had learned that Daniel Roe wrote a script that automatically registers an npm package every time he buys a domain. I figured he’d probably know a thing or two about npm.

From an accessibility standpoint, I was expecting more of the same. I assumed I would still be the only person insisting "accessibility is a right, not a privilege." Explaining that screen reader users use several lists of things to navigate a webpage: links, headings, landmark regions. That’s why your <header> should be outside of <main> and your link text shouldn’t all be “click here!”

Inside the npmx Discord, I didn't expect to see a dedicated accessibility channel. I was delighted to see automated accessibility tests when I opened up my first pull request for review. There were other people already hard at work making sure there were no click handlers on generic elements. I started to feel things that I hadn't felt since working in digital accessibility full time.

Immediately, I started learning deeply about accessibility again. Some things were small, like HTML’s struggle with headings inside <details>/<summary> but I was also getting to have the big conversations about architecture and design that I missed having. I didn’t even have to explain what a VPAT was. Most importantly, our conversations are being treated as important. If there's a possible accessibility issue in another conversation, accessibility experts are tagged in. It’s all filling a bucket I hadn’t even realized was empty.

Of course, there are things we weren’t able to fix before the alpha release — that’s how software is: perpetually unfinished, never 100% accessible — but I don’t have to justify a fix with a business logic bug because we’re already auditing. Earlier this week, someone asked how the accessibility channel felt about accessible color contrast. I had already typed out a justification for sufficient color contrast before I realized it was an invitation to review a pull request.

Wrapping up with some tips for building an accessibility-first culture

For many reasons, the first step is writing documentation. In your onboarding documentation, encourage developers to install accessibility linters. Document the accessibility problems you’ve already solved, patterns for interactive controls and colors that have sufficient contrast together.

Bonus points if you have the documentation available in multiple forms (e.g. text, diagrams, and videos).

Tests are another form of documentation and useful for preventing regressions and always use accessibility testing tools. Write your components and types in ways that enforce accessibility. An <input> should always have a label, so the labelText prop for your component with an <input> should be required, right?

Think of accessibility concerns as early as possible, such as in the design and planning phases. Accessibility auditing is part of quality assurance (QA). If you have the budget, pay accessibility testing experts to do manual testing and also, testing with users with disabilities. When accessibility experts raise concerns, take them seriously. Also celebrate the little wins — sufficient color contrast and alt text mean a lot to a lot of people.

Finally, respond with humility when you get it wrong, because you will get it wrong. Use those moments as learning and improvement opportunities because your ultimate goal should be inclusion. It makes a lot of sense listen to the people who are excluded.

Because I have seen this pattern so often, I'm going to to use a couple of real-life examples to find out why this is the case. The examples have been edited and shortened to make them easier to understand.

I will use the code to assess what the intention for using role="presentation" might have been and what could have been done differently. In my experience, there’s only a few real use cases for this attribute value, which we will get to later in the article.

What you might read about this attribute

We will use the specifications to take a closer look at what role="presentation" does, how it is used in the wild, and what it should actually be used for.

The official specs

If you take a look at the specification, you will immediately notice the prominent note right at the beginning (emphasis ours):

In ARIA 1.1, the working group introduced none as a synonym to the presentation role, due to author confusion surrounding the intended meaning of the word "presentation" or "presentational." Many individuals erroneously consider role="presentation" to be synonymous with aria-hidden="true", and we believe role="none" conveys the actual meaning more unambiguously.

This gives us an initial indication of why this attribute might be used incorrectly.

Authors seem to understand “presentational” as “only to be seen”; not heard. This is the behaviour of aria-hidden, which hides an element in the accessibility tree so that it is no longer announced when assistive technology is used. role="presentation" only affects the role, but not an element and its content.

The intended use is when an element is used to change the look of the page but does not have all the functional, interactive, or structural relevance implied by the element type, or may be used to provide for an accessible fallback in older browsers that do not support WAI-ARIA.

Spoiler: they’re describing layout tables here, which we’ll get into later in the article.

An element whose content is completely presentational (like a spacer image, decorative graphic, or clearing element);

The first two examples sound like image elements. If it is a decorative svg element, aria-hidden="true" would make more sense. Whereas for an img element alt="" would be more appropriate for hiding it, as this makes the intention much more obvious and it comes for free with the img element.

“Clearing element” might refer to using an element to clear float behaviour, where you would use clear: both; after using float: left; or float: right;, so it wouldn’t get dragged up the flow and break the layout.

An image that is in a container with the img role and where the full text alternative is available and is marked up with aria-labelledby and (if needed) aria-describedby;

To be completely honest, I have never seen the following example in the wild, and it is much easier to implement — and for users to read — if you use the alt attribute for alternative text in an image.

In the following example, the hidden attribute is used to hide the <span> element visually. However, it’s still available in the DOM, so it can be referenced using aria-labelledby , up there in the sibling <div> element, for example.

<div role="img" aria-labelledby="image-title">
  <img src="example-image.jpg" role="presentation">
  <span id="image-title" hidden>A beautiful sunset over the ocean</span>
</div>

In the accessibility tree, in that context, the image is displayed correctly with the corresponding alternative text, but not the source URL. If you use axe-linter in development, removing role="presentation" will trigger an alarm that images need alternative text.

An element used as an additional markup "hook" for CSS [...]

This means that in CSS, you use this attribute to target an element with role="presentation", for example like this:

table[role=presentation] {
  /* Do something */
}

A layout table and/or any of its associated rows, cells, etc.

Again, we’ll get into this pattern later on.

The specification contains many more explanations and examples, which you are welcome to look at yourself. One of the most important sentences for me is this one: “[…] the presentation role causes a given element to be treated as having no role or to be removed from the accessibility tree, but does not cause the content contained within the element to be removed from the accessibility tree.”

The following example is not intended for use in production, but is only meant to illustrate that when using role="presentation", the element itself and the elements within it lose their semantic meaning, but the content is still available:

<!-- Output: One generic element containing 
two generic elements with content. -->
<ul role="presentation">
  <li> Sample Content </li>
  <li> More Sample Content </li>
</ul>

<!-- Output: Unordered list element containing two list items. -->
<ul>
  <li> Sample Content </li>
  <li> More Sample Content </li>
</ul>

The semantic HTML is still displayed in the source code, however, if you look at them in the accessibility tree, they are displayed as generic elements, so they could just as well be <div> or <span> elements.

Enough theory, let’s have a look at some real world examples!

Questionable examples

Some of these examples won’t create any real barriers for users and I consider them not nice, but more harmless. Others will cause problems, because role="presentation" has removed important semantic meaning, which can cause more issues because of nested elements.

You will quickly learn that I removed this attribute in all of my suggested fixes, as it’s just not necessary. It was also sometimes impossible for me to guess why developers used role="presentation" in the first place.

The “invisible” iframe element

<iframe src="..." title role="presentation" loading="eager" style="width: 0px; height: 0px; border: 0px; display: none;">
  <!-- More code  -->
</iframe>

This iframe element contains a single <script> element for cookie logic. The intention here was most likely to hide it from assistive technology, as the CSS code suggests.

However, the content is still available because only the semantic meaning was removed from the iframe element. In addition, a title attribute without content was used here, which is incorrect.

Instead, the desired output could be implemented as follows:

<iframe aria-hidden="true" src="..." loading="eager">
  <!-- More code  -->
</iframe>

The list with no items

<nav>
	<ul>
	  <li role="presentation">
	  	<a href="/">To homepage</a>
	  </li>
	  <!-- More code  -->
	</ul>
</nav>

Why role="presentation" is applied to a list element here is beyond me. Especially since this is a navigation element and the semantics here have to be on point. Fortunately, it can be easily fixed by removing the attribute and using aria-current="page" for the current page.

The “hidden” image

<a href="/shop" aria-label="Shop">
  <svg role="presentation">
    <title>Shopping cart</title>
    <!-- More code  -->
  </svg>
</a>

As we learned from the specification, role="presentation" only removes the semantics of an element, but not its content, so the content of the <title> element should still be available, right? As aria-label is present, an accessible name is provided by this attribute, but not the <title> element itself.

If you would remove aria-label, it would have no accessible name at all, meaning role="presentation" has completely purged the <title> element from the accessibility tree! 🤯

The goal here was probably to hide the alternative text of the <svg> element, which worked. However, there are several ways to solve this use case more cleanly, and I would do it this way:

<a href="/shop">
  <svg>
    <title>Shop</title>
    <!-- More code  -->
  </svg>
</a>

In this case, we do not need aria-label, as the alternative text of the image is used as the accessible name.

Make it semantic, then undo it

<a href="/retail">
  <p role="presentation">Search store</p>
</a>

This is an awkward solution, but it does not present any real barriers for users, as the link text is still available. The developers probably wanted to hide the <p> element semantically, which is exactly what happens here. However, it could also have been done like this:

<a href="/retail">
  Search store
</a>

Technically meh, but still working

<div role="presentation">
  <section role="presentation" aria-label="Header">
    <!-- More code  -->
  </section>
</div>

This is a very interesting case! First of all, I don't understand why you would remove the semantic meaning but still use a semantic element.

In theory, <section> would be a generic element with an aria-label, which is prohibited according to the specification, which would result in a failure of test step 4.1.2 Name, Role, Value (Level A).

But because aria-label is present, this is ignored by the browser and the element is displayed correctly in the accessibility tree. Amazing! A technically clean solution would look like this:

<div>
  <section aria-label="Header">
    <!-- More code  -->
  </section>
</div>

Adding an accessible name and then removing it

<a href="/profile">
  <div>
    <div>
      <img alt="Go to profile" role="presentation" src="...">
    </div>
  </div>
</a>

The intention is not clear to me here either, because there are some problems due to role="presentation".

The <a> element needs an accessible name, which is not available because the <img> element has no semantic meaning and the alt attribute cannot be applied to a generic element.

Fortunately, these problems can be solved by removing role="presentation"! I also removed the <div> elements because personally, I don’t like the taste of div soup.

<a href="/profile">
  <img alt="Go to profile" src="...">
</a>

The alternative text is now linked to the image, and the accessible name of the link is provided by the alternative text. This one is similar to the “hidden” image example from earlier.

The few good use cases of this attribute

There are a couple of suggestions in the specs when you could use role="presentation", but I think only a few use cases could apply: Tabbed interfaces, menu pattern and a layout table. Let’s have a closer look at a layout table, which is using a <table> element for page layout.

Thanks to modern CSS, there’s no real need to use layout tables for websites anymore! We can produce flexible and robust designs by using flexbox and / or grid. The one use case where role="presentation" might come in handy could be email templates though.

If you are forced to use layout tables for your emails, Harvard University has a great article for you on creating accessible emails. The most relevant part for this article is the following sentence (emphasis ours):

If you must use tables for layout, add the attribute role="presentation" on every table element to ensure screen readers won’t treat them as data tables.

In the W3C Tips and Tricks section for tables, they’re also very clear on the usage of layout tables (emphasis ours):

Tables should not be used for layout purposes. Use Cascading Style Sheets (CSS) for layout. If there are already layout tables present, don’t use structural elements (like <th> or <caption>) [...], and do add role="presentation" to the <table> element.

The University of Michigan keeps it more brief but same advice:

Only use tables to present tabular data, not to create a visual layout. Use CSS or styling options to handle layout.

In Screen reader heuristics for presentational tables, you’ll find some examples on how to use role="presentation" in the context of a layout table.

Wrapping up

Thanks to a detailed analysis of the specifications, we have learned what role="presentation" does and how few use cases there actually are for this attribute. We have also seen from real-life examples how misunderstood the functionality of this attribute is among developers.

The only real use cases would be tabbed interfaces, the menu pattern and email templates, but even here, one could (if possible) switch to plain text emails and avoid using role="presentation".

Many thanks to Heydon Pickering for their help checking over this article and lending us their endless accessibility wisdom.

If the answer to that is “no” or even “I don't know”, I recommend reading Inaccessible PDFs? How to know when to use HTML webpages instead of PDFs by Whitney Lewis.

If the answer was “yes”, I’m going to show you how to do the following things using a practical example:

• Creating an accessible PDF using LibreOffice
• Doing a quick structure check with a text editor
• Testing for PDF/UA and WCAG conformance on the axes4 website
• Checking our documents with different screenreaders (JAWS, NVDA and VoiceOver)

Why I’m writing this

As I write this, I am in the application phase of finding a new role. Every now and then, I am offered the option to have form fields filled in automatically by uploading my resume.

I created my resume in Pages and selected the “On” option under “Advanced Options” and “Accessibility” when exporting. I did this in the hope that it would be accessible and machine-readable from a technical point of view.

After uploading the resume, my first name was always displayed as “Mastodon” and many fields were filled in incorrectly, or not at all. Since “Mastodon” is not my first name, I suspected that there was some kind of technical problem. So, for the nth time, I researched how to create and test accessible PDFs, and for the nth time, I was told that this was only possible with Adobe Acrobat Reader Pro. I didn't feel like throwing my money at a big corporation, so I frantically continued searching for a way to make my wish come true.

I quickly found an answer after asking on Mastodon, thanks to Grant, who pointed me to the official accessibility documentation and Eric Eggert, who showed me how to test it for PDF/UA and WCAG conformance.

Using LibreOffice to create and export accessible PDFs

Often ridiculed by me and rarely needed, I wanted to give LibreOffice a real chance this time, so I transferred my resume manually and first got an overview of what the problems actually are.

Requirements for accessible PDFs in LibreOffice

PDFs are subject to very similar accessibility requirements as websites. Let's take a look at them (taken from the Universal Accessibility (PDF/UA) documentation):

• The document title is set.

This is not the visible main heading, but the title of the document, think metadata.

• The document language is set, or all styles in use have the language property set.

The language for the document is set automatically. However, if there are sections in other languages, these must be adjusted accordingly. Go to "Tools", "Languages" and select the appropriate option.

• All images, graphics, OLE objects have an alternate (alt) text or a title.

Graphics must either have a meaningful description or be marked as decorative. Got to "Format", "Alt Text..." and either enter the text or tick the "Decorative" box. Check out What’s the alternative? How to write good alt text if you need help writing alternative text.

• Tables do not contain split or merged cells.
• Only integrated numbering is used, no manual numbering. For example, do not type "1.", "2.", "3." at the beginning of paragraphs.

If numbers are generated, this should happen automatically and they should not be added manually. Example: Multiple lines of text are converted into a semantically correct element using “Ordered List” instead of adding the numbers yourself. Go to "Styles" and select "Numbering 123 List Style".

• Hyperlink texts without the underlying hyperlinks.

Texts marked as hyperlinks should contain the corresponding path. This warning appears when you create a hyperlink and then remove the path it contains using “Remove Hyperlink,” which you shouldn't; just leave it be!

• The contrast between text and the background meets the WCAG specification.

See Testing Color Contrast in Non-Web Documents and Images.

• No blinking text.
• No footnotes or endnotes.
• Headings must increase sequentially with no skips, for example, you cannot have Heading 1, Heading 3, and no Heading 2.
• Text does not convey additional meaning with (direct) formatting.

If the font or style for text is changed, this must not be applied to the text itself, but only to the semantic element itself representing this element. Example: All Heading 2 elements should be italic and in Comic Sans. Select the appropriate element either directly in the document or in the right-hand sidebar, go to "Styles" and select "Edit Style…" and change it accordingly.

Some of these points apply to our use case, as we will need headings, paragraphs, lists, hyperlinks, and a decorative image for the resume. If you work in web development and know a little about accessibility, these pain points should be very familiar to you.

Now that we know all the requirements, we can get started!

Displaying accessibility problems and warnings

On the right-hand side, you can click on “Accessibility Check” to display the corresponding warnings and notes. I have also selected “Entire page” under “Zoom” and “Formatting Marks” under “View.” This gives me an overview of the entire page and allows me to see where elements such as paragraphs, line breaks, or lists are located.

Not very pretty, but the good thing is that we only have one problem and a handful of warnings! The problem with the missing page title is quickly solved by clicking on the “Fix...” button and entering the title for the document, “Resume Steve Frenzel”:

Creating a heading structure

Before we look at the warnings for links, I want to start by creating a hierarchy using headings. On the right-hand side, you can either select “Properties” or use the select element at the top left of the toolbar.

To do this, we highlight the relevant text and select, for example, “Heading 1,” “Heading 2,” and so on.

That looks much clearer already. However, there are now two warnings for “Avoid new empty lines between numbered paragraphs.”

Before we look at how to solve this, let's add the lists.

Adding lists

Lists can be added either via “Format,” “Lists,” and “Unordered List,” or via the toolbar and the button element with the list icon:

Our structure is coming along nicely, but what’s that: more warnings?! Let’s see how we can get rid of those.

Avoiding empty lines between paragraphs

By removing the empty paragraphs between headings, lists, and so on, we can significantly tidy up the “Accessibility Check” section:

The warnings have disappeared, but now the spacing between the “Heading 3” elements is virtually non-existent. “Heading 1” and “Heading 2” are fine for me.

To create a better visual hierarchy, we can go to “Styles” and “Edit styles...” and adjust the spacing under “Spacing” in “Indents & Spacing.”

I chose a value of 0.20 and checked the box next to “Do not add space between paragraphs of the same style” so that these values are applied above and below the element.

Now our document looks less squashed and we can take care of the warning about the links.

Implementing links correctly

There are two warnings, namely “Missing ‘name’ property of hyperlink.” and “Hyperlink text is the same as the link address [...]”. Here is our list of links:

• Email: stvfrnzl@duck.com
• Website: https://stevefrenzel.dev/
  • Blog: https://stevefrenzel.dev/blog/
• LinkedIn: https://linkedin.com/in/stevefrenzel/
• GitHub: https://github.com/stevefrenzel/
• Mastodon: https://mastodon.online/@stvfrnzl/

What we need to do is give the link itself an accessible name and replace the URL with a different word. For example:

• Email
• Website
  • Blog
• LinkedIn
• GitHub
• Mastodon

To do this, select the relevant word and open the context menu via “Insert” and “Hyperlink” in the toolbar (or CMD + K on macOS). For the email address, select “Mail” and enter the email address under “Recipient:”.

For hyperlinks, we select “Internet” and paste the URL under “Hyperlink settings” and “URL” (it is automatically pasted from the clipboard).

Although the warning about the hyperlink text has disappeared, two of the six links are now too short. It's “only” a warning, but my goal is to have zero errors or warnings, so we're going to fix that. “Email” becomes “Send email” and ‘Blog’ becomes “Read blog.”

Nice! All that's missing now is the accessible name for the links. To do this, we click the corresponding “Fix…” button and enter the appropriate name:

Adding a different font

This resume looks very plain, doesn't it? I'm not interested in winning a design award, but I would like to make it a little more appealing by using a different font. I've chosen “Graphik” for the headings and “Atkinson Hyperlegible Next” for the paragraphs.

Let's start by applying the style to the main heading:

It looks better (in my opinion), but we got the warning “The text formatting conveys additional meaning.” This warning appears when we apply the new font directly to the text instead of using it globally for all main headings.

A better approach is to change the font under “Styles,” “Edit Style...,” “Font,” and “Family.” Alternatively, you can select the corresponding element, right-click, and access it in the context menu via ‘Paragraph’ and “Edit Style...”.

Adding a decorative image

Perfect, no more accessibility problems or warnings anymore! Now let's add a visual accent to the document with a visual separator. The toolbar has a button called “Insert line” (visualized by a diagonal line), which we can use to add the decorative image:

Interestingly, we do not receive a warning in the “Accessibility Check” section that this image has no alternative text or that it has not been marked as decorative. However, as we are aware of this issue, we will fix it immediately.

By right-clicking on the image (or selecting “Format” and “Alt Text...”), we can check the “Decorative” box. Done!

Exporting it as accessible PDF

Before exporting, we check whether we have implemented our elements correctly. To do this, we open the side panel under “Tools” and “Navigator,” which shows us semantic elements in the document. Although no paragraphs are displayed, all headings, hyperlinks, and images are shown as expected. Nice, moving on!

Go to “File”, “Export As” and “Export as PDF...” and tick the box labelled “Universal Accessibility (PDF/UA)” to make sure it’s meeting the technical requirements for an accessible PDF:

Testing the PDF

Let's start with a very simple test to make sure our document structure is correct. As I'm on MacOS, I'm using the native Preview and TextEdit apps here but you can choose whatever is available to you.

After opening the PDF with Preview, we select all the text via CMD + A and copy it using CMD + C.

Now, we're going to paste it into an empty TextEdit document with CMD + V.

So, what are we looking for? We’re checking for:

• A logical reading order without mixed up content
• Random text or characters

As both are not the case, we can assume our document is fine. Let’s move on to check if it fulfils the PDF/UA and WCAG requirements on axes4.

Checking PDF/UA and WCAG requirements on axes4

Head over to the axes4 website and either drag and drop your document where it says “Drag and drop your PDF here” or upload it by selecting the “select file” button.

Great, our document meets all requirements! In the “Document” and “Test Report” sections, you will find detailed information about the document and which criteria were checked.

To be really sure that everything is as we intended, we can check our document with a screen reader to see how it interacts with this type of assistive technology.

Testing it with different screen readers

There are many screen reader apps out there and I chose to test with JAWS, NVDA and VoiceOver, as these are the three most popular ones according to the WebAIM Screen Reader User Survey. A great resource on screen reader usage is Your Accessibility Claims Are Wrong, Unless... by Adrian Roselli.

I'm using MacOS Sequoia 15.6 and running Windows 11 on Mac with Parallels. Thanks to this wonderful explainer by Sara Soueidan, I was able to set it up quickly.

Screen reader and browser combinations

Regarding JAWS and NVDA: as I want to keep it as simple as possible, I open the PDF with Microsoft Edge, as it comes pre-installed with Windows 11.

However, some screen readers work better with certain browsers. These are some of the most popular combinations according to the WebAIM Screen Reader User Survey #10, which are also recommended by the IAAP (WAS Body of Knowledge, page 45):

• JAWS with Chrome
• NVDA with Firefox (or Chrome)
• VoiceOver with Safari

JAWS (Version 2025.2508.120) on Windows 11

By pressing H, I’m moving through all the headings in the document, which worked as expected. We can also check the speech output by opening the Speech History via Insert + Spacebar + H.

Next, let’s check the lists by pressing L. It should announce seven lists:

• Five lists with three items
• One list with two
• One list with five items

Sweet, this looks good as well! Lastly, let’s check if the links are working as expected by pressing TAB to traverse through the document:

Looks like we’re good here! As we formatted our “Send email” hyperlink as a link to send an email straight away, JAWS announces “Send Mail Link” after the accessible name.

NVDA (Version 2025.2) on Windows 11

As before, I’m opening the PDF in Microsoft Edge and press H to traverse through the headings. All of them are announced correctly, let’s have a look at them in the Speech Viewer:

Moving on to the lists by pressing L, they are all recognised and announced correctly. However, NVDA also announces the bullet points here. Which is fine, as the most important thing are lists being announced as lists.

When tabbing through the document using TAB, all links are announced as expected. Great, let’s check how this document behaves with VoiceOver.

VoiceOver (Version 10) on MacOS Sequoia 15.6

I am opening the document in Preview and use the so called Rotor feature in VoiceOver to get an overview of elements like headings, links, images and many more. Let’s have a look at our heading structure:

Everything looks as expected, layers and names are correct! Let's continue with the links:

No surprises here either, wonderful. Let's take a look at the “Images” section:

Nothing is displayed here because we have marked the image as decorative.

Since the lists are not displayed here in Rotor, I navigated directly through the document using VoiceOver, and the lists were announced to me correctly.

Wrapping up

Anyone familiar with Microsoft Word or similar word processing programs should have no problem quickly finding their way around LibreOffice. It is also a small step toward digital sovereignty, moving away from the products of US tech giants.

The example with my resume may not be very complex, but it should contain enough examples for everyday use to quickly and easily create an accessible PDF.

Thanks to axes4, we can test our PDFs without ever having to think about the words “Adobe Acrobat Reader Pro”. If you wan't to make extra sure, you now know how to check the document with different screen readers too.

See the Pen Button with shadow-based focus that’s not accessible in high contrast mode by Andy Bell (@piccalilli) on CodePen.

Because outline doesn’t clip to the shape of your button if you use border-radius, it can be tempting to use a sharp box-shadow for focus styles.

button:focus {
  outline: none;
  box-shadow: 0px 0px 0px 3px #192a56;
}

With standard operating system and browser settings this looks fine. There’s plenty of contrast and the focus style is very clear. Job done, right? Unfortunately not because in Windows High Contrast Mode, both the background and focus styles probably won’t show up.

There is a solution to this: transparent borders and outlines! First, we add a transparent border to our button:

button {
  border: 1px solid transparent;
  /* all the other CSS */
}

This border is completely invisible and you probably won’t even notice it, but the difference in Windows High Contrast Mode is huge.

This doesn’t fix the focus style though. It’s best to provide genuine contrast with focus styles so when a keyboard user tabs to your element, they can see that it is focused. To improve the initial focus style, we need to tweak it a bit:

button:focus {
  outline: 2px solid transparent;
  outline-offset: 4px;
  box-shadow: 0px 0px 0px 3px #192a56;
}

See the Pen Button with shadow-based focus that’s still accessible in high contrast mode by Andy Bell (@piccalilli) on CodePen.

We first set a 2 pixel outline and then using the ever-handy outline-offset, push it out by another 4 pixels. Now, when a user focuses our button, it looks great both in a standard operating system and browser configuration and it looks great in Windows High Contrast Mode.

Here’s all the CSS for the button:

button {
  display: inline-block;
  padding: 0.5rem 2rem;
  font: inherit;
  font-weight: bold;
  border-radius: 2rem;
  border: 1px solid transparent;
  background: #3f25c4;
  color: #ffffff;
  min-width: 10rem;
  cursor: pointer;
}

button:hover,
button:focus {
  background: #8c7ae6;
  color: #000000;
}

button:focus {
  outline: 2px solid transparent;
  outline-offset: 4px;
  box-shadow: 0px 0px 0px 3px #192a56;
}

This is a quick win, for everyone: the visual design is left almost untouched and it’s accessible.

This little helper function will find all focusable child elements—specifically, user-focusable elements—of a passed parent element:

/**
 * Returns back a NodeList of focusable elements
 * that exist within the passed parent HTMLElement, or
 * an empty array if no parent passed.
 *
 * @param {HTMLElement} parent HTML element
 * @returns {(NodeList|Array)} The focusable elements that we can find
 */
const getAllFocusableElements = parent => {
  if (!parent) {
    console.warn('You need to pass a parent HTMLElement');
    return []; // Return array so length queries will work
  }

  return parent.querySelectorAll(
    'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]):not([disabled]), details:not([disabled]), summary:not(:disabled)'
  );
};