Buttons must have discernible text

You may of come across the rule “Buttons must have discernible text” when running accessibility audits or using automated tools such as axe-core.

The rule is a relative simple rule, and in most cases (depending on your site) a small fix. The simplicity of the rule is something you need to account for if you are using automation tools, or running automated audits.

By nature of the rule the pass criteria for is very simple – does a button have a discernible text value. Let’s take the axe-core information on what would allow for this rule to pass for a button –

  • Inner text that is discernible to screen reader users.
  • Non-empty aria-label attribute.
  • aria-labelledby pointing to element with text which is discernible to screen reader users (i.e. not display: none; or aria-hidden="true".
  • role="presentation" or role="none" (ARIA 1.1) and is not in tab order (tabindex="-1").

Those points are straight forward, using either one of the different techniques ensure the button has discernible text – Pass!

Now lets look at some example code (The SVG isn’t complete as the path value was removed to keep it short – the SVG in the example below is of the twitter bird icon/logo)

  <button title="twitter" type="button" class="shareButton">
    <svg width="24" height="24" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">

We have a button that has the twitter icon within it – so it’s a icon button that as you may of noticed with the class name it is a share button. A typical scenario for a lot of websites these days, providing a button near the article or page showing the icon of a social network that allows you to quickly share the content.

So the example passes all automated tests. Which is good and bad, yes there is the added title attribute to provide the button with a text value. But the primary issue here, and that goes for relying on automated tools alone is context – the tools are unable to determine the context of the element and if the text is going to provide any meaning the user.

Some possible better values of the title attributes that could be used –

  • Share on Twitter
  • Share current [page/article] to Twitter
  • Share [article title] on Twitter

The first two would be pretty simple updates to make, the third could be a little more tricky depending on the way the site is built and the share buttons are built – but it’s not an unreasonable ask.

The updated version of what would still pass all the test but also provide a more meaningful text value to all.

  <button title="Share Buttons must have discernible text article on Twitter" type="button" class="shareButton">
    <svg width="24" height="24" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">

If you have run a lighthouse audit with the accessibility option enable you may of come across the following –

Only a subset of accessibility issues can be automatically detected so manual testing is also encouraged

This highlights the need for manual testing – but just because something passed an automated test it doesn’t mean it’s correct. It’s always worth manually testing your entire site and also using real users. Ensuring the passed tests are valid and make sense within the context of your site.

Valid ALT text?

This tweet the other day from Addy Osmani showing some CSS on how to highlight images on a page with no alt attribute got me thinking. Addy’s tip is great and shows how developers can provide guidance within the apps/sites they are building to editors/admins on missing attributes that are required for accessibility. The part I was stuck on was this only shows what I would call error states, there is also the state where the alt attribute can be present meaning the red border isn’t shown, this can provide false positives as even though a blank alt attribute is valid. It is only valid for decorative image. For frameworks like React or others it’s possible to put yourself outside of the error state easily without knowing it, and it appears like you are valid. A much better tip would be to highlight the “decorative” state image with a warning – using an orange or so forth. This then allows the user to quickly check the images that are present and have an alt attribute but not value and gives them the opportunity to confirm if that’s the correct state for the given image.

For example in a web application where a developer is using a utility function to display and image/graphic and assumes the alt text is being set based on them passing a value, or even if they are just passing an object of data from a API or other datasource. Example of a CMS, where the UI is built in React and you just pass the image data from the API into your component – the issue here is you are hoping the admin/editor added the alt text in the photo/media library tool.

Having images that are non decorative with a blank/null alt text fails accessibility for WCAG 1.1.1 Non-text Content – H67: Using null alt text and no title attribute on img elements for images that AT should ignore.

// Error - missing alt
img:not([alt]) {
    border: 5px solid rgb(255, 0, 0);

// Warning - Has alt attribute but no text value
img[alt=''] {
    border: 5px solid rgb(255, 165, 0);

The following CSS is used to produce the output you see in the image below. I also put together a quick demo over to provide a working example: https://xenodochial-ride-8a0e7a.netlify.com/


Demo of highlight alt missing and alt blank