CMS Reference

Table of contents

Making your content accessible

As websites continue to become more and more critical to businesses, ensuring that content on websites is accessible to all visitors has become more vital than ever. In the United States, this is often called section 508 compliance, which refers to the section of the Reauthorized Rehabilitation Act of 1998 that requires federal agencies to make electronic and information technology accessible to people with disabilities. While section 508 compliance is a good baseline, increasingly the Web Content Accessibility Guidelines (WCAG) are being used as the standard for creating accessible content on the web.

Accessibility is not a feature

The legal aspect shouldn't be your motivator for providing a good experience for your users. One in four Americans has a disability according to the CDC. Choosing not to provide a good experience for 25% of visitors is like a physical store denying every fourth visitor from entering. Not only will those customers be unhappy, they likely will not come back or recommend your services.

A common phrase among developers is that "accessibility is not a feature".  The idea is don't treat accessibility like a bonus thing to add, or something to deal with at the end of a project.

Accessibility requires thought, empathy and understanding. When approached early on in a project you can design and develop solutions instead of needing to re-architect something later.

Often times solving for accessibility solves for your other priorities as a developer, user experience, performance, and SEO being a few top concerns that are directly intertwined with accessibility. Improving one, often improves the other.

Empathy is a huge part of accessibility that is easy to overlook. As developers we want to automate everything, if something is hard or time consuming to do, we want tools to either do it for us or tell us the right way to do it. Unfortunately, these tools can only scratch the surface, because they are not human, they can't truly experience the page the way a human can. It is technically possible to create a web page that passes most automated accessibility tests with flying colors, but is completely unusable to all humans, sighted, blind, deaf, color blind, limited or unlimited motor function. You can technically meet requirements, but provide an unusable frustrating experience that completely alienates people. The takeaway is this: don't rely on the tools, test your work, empathise with your users, collect feedback.

While not a definitive guide, here are some steps that you can take to make your content accessible, as well as resources for further diving in.

Provide text alternatives for any non-text content

All images, icons, videos, and buttons should have a text alternative. Not only is this good for visitors that are consuming your content via a screen reader, it is also great for search engines. The alternative text should describe the content of the image. Most images on your site can likely be edited in the page editor, setting alt text in the page editor is easy. Inside of custom modules and templates however, you need to make sure that alt text specified in page editors is honored.

This means make sure if you have an img element that the alt text the user provides is actually used.

<img src="{{ module.image.src }}" alt="{{ module.image.alt }}">
<img src="{{ module.image.src }}">

If for some reason you are not making an image editable in the page editor, you should hard-code the alt text.

There is one exception to this alt text rule. If your image provides no additional context, and is purely just presentational it is better to have a "null" alt text value than to go without an alt attribute altogether.

Good if only presentational:
<img src="{{ module.image.src }}" alt="">

For videos, use a service that supports captions and consider including a transcript. Some services that support uploading transcripts include Vidyard, Youtube, Vimeo, and Wistia.

Make sure that all links and form inputs have descriptive text

If using an icon, provide screen reader text. For example, some standard HubSpot templates use a icon shortcode:

<a href=""><i class="fab fa-facebook-f"></i><span class="screen-reader-text">Facebook</span></a>

Don’t use 'display: none' to hide form labels and other descriptive text. This prevents text from being read aloud for those with difficulty seeing, as well as hurts users who can see but have trouble seeing the text due to lack of contrast on the placeholder text. Not to mention, who hasn't started filling out a form or had a form get autofilled for them, but had no idea if it was entered correct because the form field labels were invisible.

If you absolutely have to have hidden text, or hidden text could provide additional context that a sighted user wouldn't need. Use CSS that makes the text invisible without hiding it from screen readers or add the '.screen-reader-text' class.

.screen-reader-text {
   clip: rect(1px, 1px, 1px, 1px);
   height: 1px;
   overflow: hidden;
   position: absolute !important;
   width: 1px;

Adding a skip to content link

When a visitor is navigating using a screen reader, it is super helpful if there is a way to skip over the portions of the page that are repeated such as a header. We can do this by adding a link that points to the main content of the page.  

In your header, add HTML with the following content:

<a href="#content" class="screen-reader-text">Five ways to make your site more accessible</a>

Then, in every template ensure that there is an element with an ID attribute of content. In our example we used the article title as the text to jump to. This enables search engines to understand what is being linked to. It's a more semantic way of jumping to the content.

<main id="content">
<!-- your page or post's actual content -->

Use semantic markup

Semantic markup is HTML that conveys meaning. Some examples of elements that are semantic are <header> <main> <footer> <nav> <time> <code> <aside> <article>

Some examples of elements that are not semantic are <div> <span>
Non semantic elements still have their place, but should be used primarily for presentation and not for conveying meaning.

Semantic elements are able to be understood by search engines and assistive technologies, both positively affecting SEO and improving your user experience.

Do not use <div> elements as interactive elements like buttons, tabs, or links unless absolutely sure you've provided a good experience via aria attributes.

Use links (<a />) and  <button />  appropriately.

Use links for linking to sections of a page and navigating to other pages. 

Use Buttons for interactions that do not result in leaving the page or navigating to an id. 

When working with tables - if a table has a descriptive title include it in a <caption> element just after the <table> element.

Use <th> elements with the proper scope attribute in tables for column and row headings and <thead>, <tbody>, and <tfoot> to denote sections. 

Use the scope attribute on <th> attributes to denote whether the heading is for the row or column.

Need an accordion? don't forget about the <details> and <summary> elements they give you most of this functionality for free, and it's accessible.

Keyboard navigation

Some users uses their keyboard to navigate webpages and forms out of preference. Some visitors must use the keyboard or some sort of assistive device that emulates a keyboard to navigate websites.

  1. Make sure that ':focus' is styled so that when a user is navigating via the keyboard they can see what is focused. Only disable the css outline property if you are providing an acceptable alternate visual indicator. Use :focus-within if it can help direct users attention usefully.
  2. When hiding/showing portions of the page with ':hover' or via Javascript, make sure that users are also able to navigate those controls via Javascript or that there is alternative path to the information.

Use semantic elements, fallback to roles if needed

When creating templates or coded files, you should use correct semantic elements (<header>, <main>, <footer>, <nav>, etc.) to communicate to web browsers and screen readers what type of content is inside your elements.

In the off-chance semantic elements are not appropriate for your scenario you should add role attributes for the main content block. This can be done using wrapping html(for drag and drop templates) in the design manager. 

Adding landmarks makes it easier for users that are using screen readers to jump between the major sections of a web page. HubSpot includes 'role' attributes to the Menu, Simple Menu, and Google Search modules.

Additional design tips

  1. Make sure that when a user zooms their browser to 200% content remains visible and readable.
  2. It is not advised to make fonts much smaller than 16px as it may become hard for visitors to read.
  3. Avoid using color as the only way of communicating information. A surprising percentage of the world population is color blind.
  4. Make sure that there is sufficient contrast between the color of text and the background so that users with limited vision are able to read the content.
  5. Avoid animations that flash rapidly (more than three times per second) as it could trigger seizures in some visitors.
  6. Consider supporting prefers-reduced-motion if you have animations on your site.
  7. Building a responsive website is considered a must now days. Make sure all interactive elements function as expected on mobile, and that there's plenty of room between tap regions.

Content writing

An easy thing to forget is that accessibility should also be considered in your text content.

  1. Avoid directional language "see sidebar on the left". If the user is on mobile, odds are this makes no sense to them as content usually stacks on mobile.
  2. Use headings like <h1> <h2>  etc. and nest them consecutively. Do not skip a heading for visual effect.
  3. When adding a link, never have the link text be "Click here", it conveys no meaning to screen readers, doesn't make any sense on touch screens or other types of devices. Instead, your text should state what is at that link. This is also better for SEO, because search engines then understand what is being linked to.
  4. Make sure if you use any special styles on the text to convey meaning, you are using the appropriate <mark><strong> <em> <sup> etc. semantic tag, otherwise your meaning may be lost to some visitors.
  5. If you are targeting visitors worldwide, avoid jokes that are region specific. If you are having your site translated, avoid puns. As much as we love a good dad joke, they often don't translate well.
  6. Use tools to help improve your grammar and spelling. This helps comprehension as well as usually results in better translations.
  7. Write your content in a way that fits your site's audience. You wouldn't explain astrophysics to 5th grader, the same as you would an accomplished physicist. That said, avoid fancy words just for the sake of using them, plain is better.

More accessibility information

There are some really great resources out there for building accessible-minded websites. We highly, highly encourage you to check them out.