Live accessibility checking: Using Editoria11y on your Mass.gov pages

Editoria11y is an accessibility tool that can help you improve your Mass.gov pages and make them more accessible.

Editora11y can help you make your Mass.gov content more accessible and user-friendly. It appears in the lower right corner of Mass.gov pages when you’re logged into the CMS, under the Feedback tag. If there are any potential issues on your page, you’ll see a number in a circle showing you the number of issues found on the page. If there are no issues, you’ll see a blue circle with a checkmark.

Editoria11y is showing that this page has 7 issues

The blue check means Editoria11y detects no issues on this page

Clicking the circle will expand the box so you can page through the issues on the page one at a time.

The box will tell you how many issues are detected. Clicking First will take you to the first issue on the page.

Each one will take you to the place on your page where the issue occurs and give you more information about it and how you might fix it. Below are examples of some of the issues it might find.

Examples of Common Issues

Manual checks and hiding alerts

Some issues found by Editoria11y will require manual checks to confirm if there is an actual issue. If you’ve checked and there is no issue or it’s been addressed, you can choose “Mark OK for all users” on the pop-up window. This will hide that specific issue on that page for all users.

If you don’t want to mark this issue as OK for all users, you can choose to hide from the list you personally see. For this, choose “Hide alert for me.” The issue will still show for other users.

Headings and heading levels

Editoria11y checks the order of heading levels, which should not skip levels — you should not have a heading 2 followed by a heading 4, and so forth. If your heading levels appear out of order, it will suggest revising them to go in order. This is so the division of sections is clear for those using a screen reader. Sections created by the CMS, such as when a new section is created on an Information Details page, use heading level 1; this is why heading level 2 is the highest available in a rich text field.

Skipped heading levels can create a confusing experience for visitors using screen readers

Another heading level issue it may find is when bolded text is used. Often bold text is used in place of a heading to show a ‘section’ in the text. If you’re using bold text in this way on your page, you should change the text to a heading instead. Read more tips for creating headings.

Bolded text should not be used in place of using a formatted heading

Image alt text

Make sure to include detailed and descriptive alt text for all images

Whenever you add an image, make sure you’re also creating alt text for it. Alt text is what will be read by a screen reader to describe an image for a person with limited vision. The CMS provides fields for including alt text. Editoria11y may suggest manual checks for these to encourage authors to be specific and descriptive to ensure the alt text being used is helpful. Learn more about adding alt text to images.

Video captions and transcripts

Including captions, video transcripts, and descriptions makes videos more accessible

Editoria11y also suggests manual checks for video captions and descriptions. These are for both visitors with limited vision and who are hard of hearing. Captions can be included in the video itself, but it’s also recommended to add a transcript with not just captions for any spoken or audio effects, but also descriptions of what is being shown in the video. When adding a video to a page, the CMS also has a field for including a transcript, which will be linked below the video player on the video, as seen in the screenshot above. Learn more about adding videos and transcripts.

Bulleted and numbered lists

Lists that are pasted in from Word or another program often are not formatted properly.

When pasting in text from another source, such as Microsoft Word, the formatting does not always carry over perfectly. For example, bulleted and numbered lists. Though the bullets and numbers will appear visually, it sometimes won’t be formatted as a list unless that formatting is selected in the rich text editor. Relying on the Word formatting to work will cause problems with screen readers, so make sure to check your list formatting. One way to know if you are using an HTML list is to try to highlight the bullet or the list number. In a true list, you will not be able to highlight it. If you can select it, then you really have a bullet character or a text number. You should remove them and style with the list button in the rich text editor. Read more about creating bulleted and numbered lists in the rich text editor.

Manual check items aren't always actually incorrect, but it's important to check them before marking them as OK.

Editoria11y will not always identify these issues perfectly, however. In this example, it’s asking if a number appearing in a list-like way – in table, in this case – should be a list. It’s important to check all of the issues highlighted carefully, as some, like this one, you can “Mark as OK for all users” because they are not legitimate issues.

Link text

Descriptive anchor text makes for a better user experience for all users, especially those using screen readers.

Another issue Editoria11y checks is link text. In the Mass.gov Knowledge Base, we encourage users to use descriptive anchor text for links. Anchor text is the text that a visitor will click or tap to open a link. We encourage using descriptive anchor text rather than just using the URL or words like “click here” and “at this link.” Descriptive anchor text is more accessible since a URL link will be read out exactly as it appears on a screen reader. Descriptive anchor text is easier and quicker to listen to, as well as providing context for the link for all visitors to your page.

Tables

Create header cells when using tables on your Mass.gov pages

Making tables accessible can be tricky. One easy fix to make them a better user experience is to include header cells. These are cells at the top of each column that identify the content in that column. For example, “Company names”, “Locations”, “Phone numbers”, etc. Read more about making accessible tables in the CMS.

Invisible issues

Some accessibility issues are very difficult to find without an accessibility checker

Some issues might be invisible if you’re not looking at the HTML source code or using a screen reader. For example, Editoria11y noticed a link with no text in this contact information. When the Contact info item was checked, there was an extra, empty section for an email link. Because there was no information there, there was no broken or incorrect link, and visually there was nothing to check on the page. But a screen reader could still get caught on this gap that was coded to be an email link but had no email. The issue was fixed by removing the empty section in the Contact info item.

If you have questions about Editoria11y, make a ServiceNow request with the URL of the page and a screenshot or exact text of the error.