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.