How we revamped our end-user portal for accessibility

In one fell swoop, we embarked on what was at once fascinating and essential.

To comply with accessibility standards, we decided to revamp the end user portal in its entirety. The word “revamp” is always fascinating. It allows us to add new and improved forms, structures, or appearances with a plethora of choices. We designed the new portal with accessibility in mind. The portal is an independent module, different from the other modules and pages of the app since the target audience are not support agents but end users themselves.

Tech stack

The legacy portal is not a Single Page Application (SPA). We decided to build the new one as API based SPA to align with other modules of experience and for better performance. The portal can be customized for every account, depending on their requirements.

But there were challenges that laid in front of us—hurdles that we had to overcome.

To begin with, modifying a simple component or part of a page ended up affecting the customized code. This meant that the code we wrote could not be modified for a long period of time since the customers might choose to override our code as per their needs. Looking back at the history of frontend frameworks, it was not wise to pick one from the available options, such as ember, react or angular considering the limitations due to customization.

So, vanilla JS was the obvious choice for us since we decided not to rely on any frameworks or major JavaScript development libraries. We selected Handlebars for templates, which the customers would be using for customizing the templates.

We also have an asset budget, which details how much network data is required to load the page completely. Powered with a performance target of the chrome lighthouse audit score, having an asset budget and performance target actually helped us a lot through the development.

How accessibility impacts product development

Spot a random web developer and ask them, “What is web accessibility?”

9 out of 10 answers will revolve around these: “It’s about having proper aria attributes” or “Web accessibility is about having the page read by screen readers for the visually challenged”. Although none of these answers are wrong, they do not completely define what accessibility actually is.

After a good deal of research, we learned one thing for sure: “Web accessibility is not just adding aria attributes to the HTML” as I told my team.

When we started building the portal, we ran into a lot of questions. At times, we ended up doubting ourselves. We asked each other, “Is this the right way?”, “Should we use a button or a link?”, “Should we use <img> tag or add via css background?”, “Will this be a <nav>, or <ul><li>, or menu item?”

Though there are browser plugins that you can use to get started, what we gleaned was that, at a basic level, axe and web developers plugins do prove helpful. However, it was not easy to find a tool that checked if the page was 100% compliant. We came to deduce that it has a lot more to it. We had to question some of our decisions that we made earlier. We initially decided not to include jQuery, and used vanilla JavaScript for performance reasons. But since the very few third-party plugins that were available are jQuery dependent, we were left with no choice but to include jQuery.

Making a simple web page compliant to WCAG criteria is not a hard thing. But things get increasingly difficult when we start using modern user experience components on the web like the infinite scroll, dynamic search, and display menu items on hover. The persona of a ‘power user’—one who is tech savvy and average in every way—dominated design decisions, where the understanding was that users who understand that the magnifying lens icon indicates search, the three horizontal lines means there is a menu waiting to be opened.

Considering these power users as a standard can cause a product to discriminate among its users.

The reason is simple.

What about the users who are new to the internet, who have been dependent on the old ways and have just started using the web? A significant part of the population do not know what these icons mean. Some may not even know that they have to click!

That is what, at Freshworks, we design and build for all kinds of users, not just the power user.

While single page applications in general are not a 100% complaint, it can pose some initial challenges that can be smoothened with precision and empathy.

The four pillars of accessibility

The accessibility standard for the module is determined as WCAG 2.1 AA. But we have around 25 – 30 criteria matching for each page, depending on functionalities and design.

At first, it was not easy to identify the criteria for the page itself. One thing for sure is that the page should be responsive. After multiple iterations, we realized that most of the accessibility criteria fell under the following four questions:

  1. How does the keyboard focus move?
  2. How do screen readers interpret this page?
  3. How does the page behave for users with very slow internet (without the images and media)?
  4. How do people with learning and cognitive disabilities understand the page?

If these things are captured before you start developing a page, that’s half the battle won. For instance, if we have an icon as a button, we need to consider screen reader users first and then add an “aria-label” for the button. But, even with this, the 3rd and 4th pillar questions might fail. Users with cognitive disabilities might not understand the purpose of the icon and if the icon failed to load due to some network issue, then the average user might not even know that there is a button. In that case, instead of adding aria-label to the button, adding alt text inside the image tag is the best way to solve these types of problems.

Single source

The only website that is most reliable and updated for learning about accessibility guidelines and best practices is the WAI-ARIA.  It has clear examples and best practices for building user interface components based on the accessibility guidelines. This is the first project where we referred to WAI-ARIA APG (Authoring Practices) a lot more than StackOverflow. You can browse through the authoring practice for the accessibility components and you just may not need any more information.

Modern components

Ever wondered why the websites of the government organizations are so plain and boring?

It’s because they have to be 100% compliant with accessibility. The simpler the UI, the better is its relationship with accessibility.

The guides will mostly help you with the commonly used components. Few components, such as dropdown selects, date picker, and attachment uploads are much more optimized today than the default browser functionalities. They have to comply with the accessibility criteria. Some complex and modern-day components are sadly not as accessible as we expect. Let’s discuss a few of those modern components that were not readily available as plug and play supporting accessibility.


 The modern dropdown components are an advanced version of the browser select. Their goal is to achieve the functionality of the <select> tag with much better options and better UI. There are tons of plugins and libraries available to implement those options. But none of them seemed well-suited when it came to accessibility compliance. Every dropdown plugin we tried ranged between having a few issues with accessibility to being not accessibility compliant at all. The one that came close to meeting our requirements is this example provided in the WAI-ARIA. We implemented this to all our functionalities.

Out of the four pillars, we were able to solve three questions except “How do screen readers interpret this?” for dropdowns. Screen readers can be challenging. We must mention if the dropdown is expanded or closed. The list of options DOM should be right next to the triggered element tag.

Then, we need to manage the focus toward the selected element. And the user should be able to search within the list (the functionality of <datalist>). Screen reader users should be able to use all these functionalities. For that, we needed a bunch of aria-attributes, such as aria-activedescendant, aria-expanded, aria-selected and the role of the element called “combobox”.

Infinite scroll

Infinite scroll design is crafted to encourage users to continue browsing. That is why this functionality is widely used in social media and the majority of e-commerce sites. This is one of the most complex components when it comes to accessibility. The reason is that it fails in every corner of the four pillars.

  1. Screen readers will find it difficult to understand the flow.
  2. Users with learning and cognitive disabilities cannot understand why the page has no end.
  3. The keyboard users will get trapped in the unending list and find it hard to navigate out of the scroll.

Not long ago, HTML5 introduced a tag <feed> to solve the screen reader issues in the infinite scroll. But there still exists older versions of screen readers that do not read this tag. Assuming that the screen readers can now understand an infinite scroll, we still faced the issue with keyboard users.

This video illustrates the issue of keyboard traps on the Twitter feed. Users, who are in the middle of the infinite scroll, are unable to get to the right side of the pane, creating a subpar user experience.

At one point, we thought that it was either that we should have to compromise or bring in a workaround for those kinds of solutions. We decided to go with the infinite scroll for a page with the list of catalog items in the new portal. That is because the list that we planned on showing was designed not to be endless.

As a tip, always makes a planned choice while deciding to go with infinite scroll. Use it if it is really necessary to the brand and product functionalities.

Date picker

 The date picker is another component that seems simple but, in reality, there are no plugins out there to have the modern date picker component with proper accessibility. The only thing we had is the example provided in the WCAG. The example answered all the four pillar questions. Yet they lacked some features, such as options to modify the year or the month of the picker by the user directly. We enhanced from the example provided from WCAG and added those functionalities. The day or date is provided in table format helping screen readers to read them exactly as in the table format. But we wanted to provide a better experience to the screen reader users too. So, we had custom aria-labels for each cell in the table with “<Day>, <Date> <Month> <Year>”.


The Dialog is not a hard component to build. But transitioning the dialog is where it gets trickier. We have to track the keyboard navigation inside the dialog modal. The user’s focus should be trapped in the dialog by moving the focus to the first focusable element of the modal whenever the focus moves out of the modal.

The IE moment of A11y

When you develop a complete page with accessibility and focus management, you might then hit another issue, the usual one—browser compatibility. In case of accessibility, every browser and screen reader behave like IE. For instance, we found that NVDA and voiceover navigates and reads differently for components like buttons inside a group, data list and field sets.

UX, the surprising byproduct

User experience.

Everything comes down to this. The performance, the design, SPA, MPA, components, FCP, CLS, etc. As the core objective of accessibility is understanding each and every user’s ability to use the page or app, it actually enhances the UX of the whole portal. We had a lot of positive feedback around the UX of the new portal, all credits to accessibility compliant pages.

Gleaning from our experience, here are some of the things that provide a more delightful user experience:

Understand the user’s perspective

 Understanding the user’s perspective has become the job of engineers as well. The portal we were building would not be visited often by users like helpdesk agents. As a matter of fact, as yourself these questions: How often have you visited your IT team? Only if something is broken, right? Imagine that the access to a key tool that the user uses to present is lost just a few minutes before an important presentation. It makes sense that the user would be stressed out. They do not—in this scenario—have time to contact IT and get the problem fixed. So, they start browsing and come to the IT helpdesk portal. There is a big search bar there. Immediately they start typing out the issue. The search popup opens up showing the results. The user clicks on a result article, the article shows up only to find that it is not related to their issue and suddenly wants to see the next article. What will the user click now? Will they go to the search bar at the top to search again? Or will they hit the back button?

In this instance, they would hit the back button.

So we had to think through that even though we are showing the results in the popup window. That’s for normal users. Building pages with accessibility users in mind actually improved a lot for normal users too.

As part of the design process itself, we looked at how the results showed, trying to place ourselves in the shoes of users of all kinds.

Acknowledge user actions

It is essential to have focus state and hover state for every element that has actions to it to acknowledge the user’s action. Animate wherever needed, but keep them consistent and simple. Animations are not just “nice to have” or “beautiful things”. Animation, if used the right way, can offer a lot of information. It is helpful for beginner level users or users with cognitive disability to understand the component or the navigation on the page. Slide open a dropdown, specifying that the list is part of that field. Animate the sidebar from the side, mentioning that it can be hidden on that side of the page. Users will have a much better understanding of where the element came from. If the user closes the element by mistake, closing it to the right origin helps the user get back easily.

Small details matter

As we started through accessibility, we had to understand each and every small step and action of every type of user, from a power user to a beginner. So to make the experience better for the beginner, we had to look into small details. The focus indicators and the focus management might seem like very small cases, but these things play a key role in improving the experience of the portal.

It has become a basic thing for a frontend developer to remove the outline and the text-decorations for the <a> tags, which is a good thing for mouse pointer users’ experience, but not for keyboard users. Events like mouse down or touch can be replaced with device-independent events like click. This will help developers achieve pointer cancellation compliance.

Things like using tab index only when necessary, using native tags like <button>, <input> or <a> instead of <div> or <li> can have a huge impact on user experience. For screen reader users, we have to focus on a few non-actionable items, such as heading / title / section. But doing so we will start seeing outlines for those nonactionable elements that may not be an ideal case for other users. When the page is rendered, we focus the title using Javascript to notify the screen reader users which page they are in and hide the outline or border for that element using CSS when focused.

This might seem like a minor change, but small changes matter. Each of these small things create a great user-friendly portal that can delight end-users.

The biggest lesson for us was this: Building pages with accessibility in mind improved a lot of existing functionalities and delighted users of all abilities.

All thanks to accessibility.

Cover design: Vignesh Rajan