Designing StoryMD’s ADA-compliant website

Dreamix’s accessibility checklist and coding convention Dreamix is the software development partner of the biggest online healthcare library in the US – StoryMD. Its platform allows patients, medical staff, and academia to access health journals, videos, and images, and interact through a CMS platform and a blog. For StoryMD, a healthcare knowledge medium, it’s of […]

by Andrey Anastassov

December 9, 2022

6 min read

healthcare provider and software partner shaking hands - Designing StoryMD’s ADA-compliant website

Dreamix’s accessibility checklist and coding convention

Dreamix is the software development partner of the biggest online healthcare library in the US – StoryMD. Its platform allows patients, medical staff, and academia to access health journals, videos, and images, and interact through a CMS platform and a blog.

For StoryMD, a healthcare knowledge medium, it’s of utmost importance to provide accessibility to all users, regardless of their condition. Therefore, the organisation regards the implementation of the ADA requirements for its platform not only as legal compliance, but also as an empowering tool for a valuable part of its audience – users with disabilities.

As its partner, Dreamix stepped in to implement the most commonly used ADA-compliant conformance level – AA. 

In this case study, we’ll reveal how we’re doing that, as well as share design checklists and coding convention insights from the field. You’ll also learn more about ADA requirements for US websites and the detailed timeline, team structure, and actors involved in achieving such a goal.


US websites need to comply with the Americans with Disabilities Act (ADA), released in 2010. It ensures that users with disabilities can access and use indiscriminately all information technology resources, such as websites. If you are a state or local government agency, a 15+ employee-employer, or a business operating for public benefit, you must provide the necessary design implementations to meet the act’s requirements. Failing to do so might result in lawsuits from users with disabilities who cannot access your website’s information fully. 

While there is no official guideline from the government to help you comply with ADA for your website, a Federal Court acknowledged the WCAG guidelines as an “industry standard” in a 2017 case. In it, the court ruled against a company website for failing to provide accessibility to the sight impaired. So federal agencies and their contractors are now required to conform with WCAG’s latest available version. And private businesses need to make sure they are accessible (with no obligation to a specific standardisation).

WCAG and Conformance Levels

The WCAG was first issued as early as 1995, after the second International Conference on the World-Wide Web. Since then, it has had regular updates: WCAG 1.0 added 14 guidelines and the A to Triple-A conformance levels. Today, most organisations strive to meet Level AA. Four principles: perceivable, operable, understandable, and robust, were added in WCAG 2.0. In December 2022, we expect the release of WCAG 2.2. 

The WCAG 2.2 draft adds 8 new features to the already existing ones for conformance level AA:

  • The focus area needs to stand out from the background
  • You need to have page numbers for anything you publish online and they need to correspond to the printed page numbers
  • Provide alternatives to the dragging movement, such as tapping or clicking
  • Interactive targets should take up at least 44×44 CSS pixels of space
  • Make your help option consistent and in the same relative place
  • Important controls should remain visible and available even when without mouseover or focus
  • Provide an alternative log-in tool, if your only option is a cognitive test
  • Auto-fill should assist with all fill-out forms, except passwords and abandoned forms

Getting started

Our biggest motivation was to provide an indiscriminate and pleasurable website experience to all of our partner’s users. Considering how huge and comprehensive StoryMD is, we knew that this would not be an easy task and that it required proficient product management. 

Like most US businesses, we knew that we needed AA conformance level as it provides the most common and optimally achievable standard. 

Our research phase started with identifying the history of WCAG and how it covered the ADA requirements. Naturally, we started off with W3’s 2.0 version to get some contextual information. Then we focused on the latest released version 2.1 and we pulled a comprehensive list of its AA conformance level requirements. 

Design checklist for WCAG, conformance list AA

Here are some of the main focus areas that you would need. Note that we’ve summarised them and put the most essential points together. If you wish to see the full guidelines, check the W3 website.

  • Providing alternatives to images and video, based on the following WCAG lines: 1.1.1: All images and non-text content that conveys necessary meaning or information needs a text alternative, and 1.2.1: All video-only and audio-only content has a text transcript. Transcripts are clearly labeled and available near the media. It also includes steps on closed captioning, audio descriptions, live captions in formal presentations, and the “radio-style” narration of videos.
  • Presentation guidelines. Use proper HTML markup techniques to structure your website’s content. (1.3.1). And of requirements including: HTML headings, ARIA, landmarks, and labels, usage of buttons and links with text alternatives to images, etc. You should avoid emulating links and buttons and using whitespace characters for layout purposes.
  • Orientation (1.3.4): your screen shouldn’t lock on portrait or landscape orientation, unless necessary
  • Autocomplete: forms should autocomplete user information
  • Use of colours
  • Colour contrast: Colour contrast ratio of at least 4.5:1 between regular text and background and 3:1 for large text; text must be able to be resized up to 200% without negatively affecting the ability to read content or use functions; Do not use images of text unless necessary; ll meaningful non-text content on your website should have 3:1 colour contrast with the background; content on hover or focus (1.4.13): Make it so any additional content (e.g., pop-ups, submenus) can be dismissed or remain visible if the user desires.

If you’d like to know more, we spoke with Shadi Abou-Zahra, Principal Accessibility Standards and Policy Manager at Amazon and one of the key contributors to the Web Accessibility Initiative. We asked him about the key elements he could outline in the WCAG. Take a look at the video he shared with us to get a glimpse of the accessibility guideline’s general overview:

Coding convention

Seeing how time-consuming refactoring code is, we initiated an effort to draft a coding convention. That way, all the code created in the future will meet the WCAG requirements. It’s also useful for the devs and the QAs, because no code can cover the acceptance criteria if it doesn’t follow the guidelines/rules in the convention. 

  • Describes in detail all the cases found during the refactoring, and explains how to deal with each of them. This way, the devs don’t need to invent the wheel and they know how to get things right from the get-go;
  • Helps the devs to better estimate the volume of the work planned and the deadlines for each task;
  • Helps the designers as well, because it contains clear requirements to follow – contrast, size, etc. 

What you need to plan in your timeline

It took some time for the team to:

  • Identify that something must be done;
  • Describe in detail what and why should be done;
  • Communicate said need with all team members and stakeholders;
  • Put the changes in the backlog;
  • Describe how things should be done and what tasks should be completed;
  • Start working on the tasks as a part of a long process;
  • Thinking of a solution how to involve the WCAG requirements in the whole process – design, coding, testing;

And this is a never-ending process. First, we need to refactor the whole platform, and then we need to make sure that every new piece of code meets the WCAG requirements. We are still refactoring the existing code.


Designing an ADA-compliant website is a must when it comes to comprehensive healthcare platforms such as StoryMD. Meeting WCAG’s AA conformance list is the industry standard. And yet it requires a dedicated team capable of following very specific coding and design standards. Be mindful and take the necessary steps to make your website truly accessible.