Common accessibility mistakes by developers

There are quite many common accessibility mistakes a lot of people make. I thought I'd try to list a few so you can test for these and make sure your content does better.

Media alternative texts

One common mistake I've seen is to have alt texts for decorative images. On a CMS level this is sometimes even forced, don't do this. Always allow users to improve the accessibility of their content. The actual HTML alt tag needs to be present also for decorative images, but it needs to be empty.

Whenever you add an image via code, make sure that the alternative text is like it should be. If you are unsure about how to write a good alternative text, there are a lot of guides online. At least for English and Finnish content.

Not using semantic HTML elements

Misusing elements and not using semantic elements is surprisingly common.

One example is the use of link elements (<a> tag) when you should be using button elements (<button> tag). If an element takes you to another page, use link elements. If the element does something on the current page, use button elements.

People often use <div> elements for closing icons. Don't do this, use button elements instead. Button elements have keyboard navigation built into them. Div elements don't. You would need to build custom functionality for the div elements. Otherwise, people using keyboards cannot use the div elements.

Overusing ARIA, or misusing ARIA

Developers who are new to accessibility have the unfortunate habit of overusing ARIA. You should only use ARIA if you need to. When there is a possibility to use a semantic HTML element, do that instead of ARIA. It even says in the ARIA spec that bad ARIA is worse than no ARIA. I definitely recommend always testing everything you use ARIA for with extra care. Especially because the ARIA spec can be somewhat hard to grasp.

Not paying attention to heading level logic

Mistakes in heading levels are quite common for both content writers and developers. The heading levels should be logical. One h1 heading for each page. Under the h1 only h2 headings. Under h2 headings use only h3 headings and so on. And do remember that there is no limit for the number of headings you can use, use as many as you need. A quite common mistake is to use h3 or h4 headings for some extra content on a page, like a news listing. But usually, these should be h2. Because a related news element relates to the news page, not some random subheading. It is easy to make mistakes in heading logic. If you expect a content editor to include an h2 heading and they don't, you might skip a heading level. So always try to keep in mind the logical heading structure of each page. Especially with elements that are located on multiple different kinds of pages. On some pages, an h3 element might be correct, but on others not.

Issues with content language

I see a lot of content in the wrong language. Some content management systems add visually hidden headings to content regions. These are often left untranslated. It is easy to miss something you cannot see, so really pay attention to these. Some small parts of the content in another language are often ignored. A good example of such content is a language menu. These all need to be taken care of to ensure accessible content for all your users. I've even seen cases where the whole page language is wrong. These can make the whole site unusable to some of your users. Having the screen reader read the content in the wrong language can be unpleasant.

Misconfiguring forms

I've often seen form labels that are not attached to the form input fields. I've seen form input fields that use placeholder as a label. These kinds of practices make the forms unusable for some people. Always prefer visible, correctly created labels. But if you, for some reason, simply cannot have a visible label, provide one with ARIA.

There are often issues with custom form validations. They tend to neglect users using assistive technologies. So if you have custom logic, always ensure the forms remain usable for all your users. You can use aria-required to tell assistive technology users that a field is required. This can be used even if the field wasn't required with an HTML's required attribute. So you can use that in a custom validation logic.

Attach any instructions you add to form fields with aria-describedby. That way the instructions will be announced to the user when they focus the input.

Make sure you display error messages to all users. Depending on the form, you can use ARIA to do this. Some content management systems do offer error functionality out-of-the-box. But whatever you use, again I remind you to test.

When creating and testing forms, look into the WCAG section 3.3. There are 6 criteria under the section, 2 level A, 2 level AA, and 2 level AAA. Make sure to follow all the good practices listed in those criteria. Also, criterion 4.1.3 covers status messages. They also cover the form error statuses.

Styling issues

There are always the common issues of color contrast and the use of color in general. Since these usually have a lot to do with a designer, I won't go into details in this post.

Setting widths and heights for all elements

You are looking for trouble if you set hardcoded sizes for all things. A common issue happens when a button (or similar) gets styled with a short word. What will happen to the button if there is a long sentence in it? Often content either will get cut, or the content will overflow on top of other content. In either case, this is bad. Another good example is a header bar. You might think it's harmless to define a height for it. But what happens when there will be more content? Or if a user zooms the content? Often the content doesn't fit in the space. Depending on how you created the heading structure, the layout will break in some way. Some content might get lost outside of the screen or again, the content might overflow. Content needs to be able to flow.

I'm not saying that you shouldn't use widths or heights for elements. But make sure the layout does not break if things change. If you have a button with a specific width, can the content grow the height of the button? If a "read more" fits into the button, will "read more about this interesting topic"? And if this button grows in height, will something weird happen for the layout of the other content?

Absolute positioning and zooming

When you use absolute positioning, ensure that the content doesn't break with zoom. I've seen cases where some buttons or similar are on the right side next to a heading. And when content is either zoomed, or the window gets narrow, the buttons move on top of the heading. Absolute positioning can be risky in this way. This particular case would have worked better if the row used, for example, flexbox.

Using only scalable units to theme the site

There is a place for all the available units. Using only scalable units like ems and rems is a quite common practice these days. And for some elements, this is an excellent practice. But not for all.

If all the margins and paddings use scaling units and you have a more complex layout, you will be in trouble. You will have very little space left for the actual text content. Sometimes margins or paddings use over half of a mobile screen width while zoomed. And since the text is also quite large when zoomed, the result was that about 5 characters fit on the screen. The rest was outside the screen and the user had to scroll horizontally. Not a very nice user experience.

What I'm trying to say here is that do test all the elements also while zooming in content. In some cases, a scaling margin/padding will work best but in some cases, pixels will work better. Always use what you think works best for each case. Your users won't care what units you use as long as the site functions properly.

Problems with link styles

If you have defined a link style, don't use it for anything else but links or it will be confusing for your users. If you have chosen to underline your links, other parts of the text shouldn't be underlined. And if you've chosen bold as your link cue, don't use bold for any other text. Otherwise, the link will only be defined by a color, and that is not enough. It is possible to use lightness as a link cue, but that does require some understanding of how colors work.

One of the most common ways to identify links is underlining. You can, of course, make your links even more visible by making them also bold. That is if you don't need to bold any parts of your texts. If you add color for the link that has enough contrast, then you would already have three clear cues for your links.

Removing visible focus styles

Some people like to remove element focus styles. One common reasoning for this I've heard is that the default styles are ugly and don't fit the design. Don't reduce the usability of your site, design nicer focus styles instead. This will become even more important when WCAG 2.2 comes out. If someone tells you to remove the focus styles, tell them no. And if you are nice, you can also tell them why.

Not testing in general

I wanted to have a separate section for testing. I can see that testing is often ignored. And I kind of get it. If there is a strict and horrible deadline, you will need to make compromises somewhere. But try not to reduce testing too much.

Validation

A lot of sites I've audited have had quite a few validation errors. From simple typing mistakes to misused elements or properties. You can easily avoid these with proper testing. Make using a code validator a part of your development process. Either manual or automated, whatever works best for you.

Try to include both keyboard and screen reader testing in your workflow. Especially if you aim to create accessible websites. It is easier to fix possible mistakes while creating the elements. Accessibility tools might detect some issues, but not all. So don't only rely on tools, but do manual testing as well.

Don't ignore code validation, non-valid code can cause some weird bugs. And valid code makes you look more professional. Fix any error you get in a validator. If you can, try to get rid of all the warnings as well. If the validator shows no results, then it will be easier to spot any issues in the future. If there is a lot of clutter in the form or warnings, you can lose an error in the mix.

Zooming and responsiveness

Test your content with and without zooming. For text-only zoom, you will need to make sure your site works with 200% zoom. For the "regular" zooming, 400% without requiring scrolling in two dimensions. For vertical scrolling, the content should work at a width equivalent to 320 CSS pixels. I rarely see something that uses horizontal scrolling. But if you do create something like that, the content should work at a height equivalent to 256 CSS pixels. And notice the word "equivalent" here, it makes a difference.

320 CSS pixels is equivalent to a starting viewport width of 1280 CSS pixels wide at 400% zoom. For web content which is designed to scroll horizontally (e.g., with vertical text), 256 CSS pixels is equivalent to a starting viewport height of 1024 CSS pixels at 400% zoom.

Understanding Success Criterion 1.4.10: Reflow

Remember to test the responsiveness of the site as well, and test with several browsers. There can sometimes be some weird bug in one browser, while others work fine. Browsers support various CSS features sometimes in a different way.

Screen reader testing

If you are creating an accessible site, you should also test the site with a screen reader. That way you won't get any surprises from buggy features or content. If you use Windows and have Windows 10, you have access to Narrator. NVDA is free software for Windows. And if you are a Mac or an iPhone user, there is VoiceOver. For Android there is TalkBack. The usability idea behind them all is very similar. There are some differences in user experience, though. And the software has a bit of a learning curve, so try to be patient while learning. To be able to test the basic functionality of the site, it usually is enough to know the basics. But of course, the more fluent you are with the software, the easier it will be to test content with it. Screen reader testing is also important to ensure proper ARIA. This I already mentioned earlier in this post but this is so important that I can repeat myself.