Our goal at Grasple is to help everyone learn statistics, mathematics or any numeric related knowledge. This also means our platform must be easy to use for any learner who wants or needs to learn these topics.
Therefore we started a thorough investigation into how accessible our platform since the summer of 2024. Based on that we concluded we needed to changes in our platform to ensure that learners with different abilities can use Grasple for learning. In this article you can read about how we did this and how we will keep doing this for any updates on the platform.
Current Status
Our approach is the following: we use the WCAG 2.2 Level AA requirements as baseline for how we are making our platform accessible. This means that the platform is fully WCAG 2.2 Level AA compliant based on our self-assessment at the time of writing. If you find any accessibility issues, please do report them to use (via chat or email).
We use resources and tools available to assess accessibility of our platform and any future updates to determine solutions to fulfil each criteria from the requirements. We have concluded the project that started in the summer of 2024 to make sure the platform is compliant. This project has been concluded mid of January 2025 after the final student pages were checked and updated accordingly to ensure each student page is compliant.
We are now gathering feedback to keep improving our platform continuously (as we are doing with all features). If you (or your university) are interested in testing and providing feedback, please reach out to us since we are happy to receive feedback on how easy to use the platform is for different users.
This document contains updates we made to make the sure the platform is WCAG 2.2 Level AA compliant. The approaches/updates listed are also translated into best practices to be applied for any new features/updates on the platform together with (automated) tests to prevent regression of accessibility.
Updates & Approaches
Page per Page checks
We went through each individual page which students might encounter in the application. For each of those pages we applied the established best practices and requirements listed below.
Our approach for those pages and all future new pages are as follows:
Make sure the page has a clear title
Make sure the focus is managed when navigating between "pages" via a standard approach.
If a page load has failed, show and announce a clear message to the user ensuring they know what they can do next.
Make sure the page has a clear header structure.
Make sure that buttons, links, input fields and icons have clear names (which can be read by a screen reader).
Apply form validation best practices ensuring that forms all work the same across the application for students.
For any dynamic content within the page either focus on that content when it appears in the page, or announce content has been added to the page.
Add status messages to the page (which are also announced) to ensure a user knows what is happening (e.g. saving answer in a test or checking answer in a practice session).
Make sure all features in the page are keyboard operable by testing this.
Make sure the page is the screenreader friendly by testing out each feature of the page at the same time as operating the page with a keyboard.
Below this section you can find more detailed sections on how we achieved the above steps together with other global updates in the platform.
Page title
Each page the student can encounter now has a unique title, making it easier for a student to understand where they are in the application based on the window/tab title in the browser.
Page Load & Focus Management
Since our application is a Single Page Application (i.e. we have a single page where content is dynamically changed between 'navigations' instead of full browser page loads) we established how to best handle focus management based upon other experts in the fields.
Focus management
On a normal successful page load we do one of the following two approaches:
Start with a focus on the H1 (main header) and announce screen reader users when the rest of the page is loaded.
If the H1 is not present (since it is based upon the data which needs to be loaded from a server), focus on the page loader element (which has a clear default label) first. Once the data is loaded and the H1 is present, focus on the H1.
In both cases a UI element is shown to indicate the page is still loading and that loading spinner has a clear label (e.g. "loading main content") to ensure also screen reader users understand what is happening.
The above approach is based upon how experts on SPA and accessibility advice to do this in combination with how our application is currently setup. By doing this consistently across each student page, it becomes a predictable pattern which helps the student understands what page they are on and when it is ready for use.
Error handling
When the loading of data fails a clear message is shown to the user this happened, together with instructions what to do. In addition, this message is announced with urgency to any screen-reader user.
Inspiration
We used the following articles/blogs for inspiration on how to implement a good system:
Dynamic Content
Our application focusses on helping students learn from their mistake by providing immediate feedback when practicing. This means that we have dynamic content (e.g. content being added and removed from pages based upon interactions of the user) across our application. To ensure this is clear to all users (e.g. screen reader users) we apply the following approach to any dynamic content in a page (after page load).
We make sure we do one of the two things:
Focus on the new content. We do this when the content is important (e.g. the feedback based on upon the submitted answer of the student).
Announce that content has been added to the page. We do this when the content is not directly important (e.g. when changing values in a form enables/disabled/shows/hides other elements in the form).
The goal of the above is to make sure that it is clear to users that new content is added to the page.
Exercise Interaction
One of the most important parts of our platform is the way a student interacts with an exercise. When interacting with an exercise in a practice environment there is contend added and removed. After testing we estbalished the following pattern to be the most logical for different kind of users (e.g. screen reader users, keyboard users, mouse users).
When answering a question, feedback is shown after a delay (since we need to check the answer in the math engine in the background). We do the following:
It is announced the answer is being checked.
When checking is done, we show the feedback and the focus is moved to the header of the feedback. Since the feedback is the most important thing at that moment (this is where the student can learn from their mistakes) we choose to focus on the feedback instead of just announcing it is now available.
We show a "retry" button (if applicable) in the feedback as well, to allow the student to also see what action is available next.
If a user cannot retry the question, this is clearly stated in the feedback.
When a user retries the question, the feedback is removed the and the focus is moved back to the answer input field. This allows the student to directly try a new answer based upon the feedback.
Status Messages
When the status of page changes (e.g. checking answer, saving answer) we show status messages which are announced by screen readers. This also holds for form submission which have a successful submission.
These updates are based upon the following criteria from the WCAG 2.2. AA Requirements:
Names & Icons
We do use icons in our application. To make sure these are clear and accessible we have the following approach:
Do not use an icon by itself to convey a message, but combine this where possible with text as well (e.g. buttons with a icon and a save). This is our preference, but not always possible, especially for mobile devices.
When an icon is shown without text, make sure it has an accessible label for screen readers (with the role="img").
When an icon is shown with text, hide the icon for screen readers if it does not convey a meaning by itself.
Use icons consistently (e.g. "floppy disk" for save buttons).
Use legends to explain what icons means. We do this for our mastery/progress icons which are used across the application.
These updates are based upon the following criteria from the WCAG 2.2. AA Requirements:
Navigation Groups
A student is generally within one of the following three contexts: learning via a lesson, practicing in a practice session or taking a (formative) test. Within each of these context we have means of navigation allowing the user to go back and forth between previous items/pages and the current item/page.
To make it clear what these links mean all of them have both a clear accessible aria-label and a navigation group with a role and label explaining what the group is for (i.e. navigating within the specific context).
Remaining Time Countdown in Tests
A teacher can specify maximum duration settings in tests. They also have the means to make the available time dependent on the student (e.g. allowing for additional time for users with dyslexia).
To help screen reader students also understand this we do the following:
We clearly state at the beginning of the test how much time they have to take the test.
We show the remaining time on each page of the test and label this as a timer to ensure a screen reader can announce this as such.
We announce when the student has 10 minutes, 2 minutes and 30 seconds remaining.
We show a dialog when the time is up, clearly stating that the time is up and the test attempt is closed with navigation action for the student.
We choose to not announce to frequent since this is disturbing the student while trying to solve an (hard?) math problem in a test.
Mastery Icon Colors
We use mastery icons across our application to help the student understand whether they master, somewhat master or not master certain subjects/topics/learning goals. We introduced an accessibility mode for these icons earlier to help students with color blindness differentiate between those icons based on their form instead of their color.
To make sure the color contrast of those accessible icons is sufficient we changed the color of the somewhat mastered icon to have enough contrast with its surroundings at all time.
Dialogs
We use dialogs (i.e. popups) frequently in Grasple. To make sure these are accessible we apply the following logic to each of them:
Make sure the dialog title is associated with the header shown in the dialog.
Make sure the dialog header is a H1 header.
Make sure the focus is set within the dialog.
Make sure a focus trap is created ensuring that the focus is not moved to the page in the background, also not if a navigation action is taking place via the dialog.
When closing the dialog focus back on the same element in the page which opened the dialog.
Color contrast
We updated our color palette we use in our application to make sure that the contrast of how these colors are used are sufficient according to the WCAG 2.2 AA requirements.
We identified the following usages of color:
background color with longer dark/light text;
background color in buttons with dark/light text;
icon colors on top of dark/light background;
icon colors on top of colored background.
We updated all the colors to ensure we have sufficient contrast. This means that all colors except for the light/dark text colors are updated to ensure the contrast ratio is higher.
There is one color not yet contrasting enough, this will be updated in a later update and will be reflected in this article.
These updates are based upon the following criteria from the WCAG 2.2. AA Requirements:
Skip to main content
To help users out to get to the main content quickly when navigating with a keyboard, we added a Skip to Main content button which skips over the fixed navigation bar at the top.
This updates is based on the criteria 2.4.1 Bypass Blocks from the WCAG 2.2 AA Requirements.
Unique names/labels for repeatable elements
On our exercise pages we can have multiple questions which have the same name programmatically (e.g. "check-answer-button"). To ensure it is easy to differentiate between these when using a screenreader we updated these names to be unique per question (e.g. "check-answer-button-for-question-1").
Improved Keyboard Control
To make sure the whole learning platform can be operated with keyboard only, we updated two parts which we identified as unaccessible for keyboards:
we made sure the dropdown in the navigation bar is easy to operate with a keyboard only;
we ensures that the arrows on the left and right side of the screen can be operated using the keyboard;
These updates are based on the criteria 2.1.1 Keyboard from the WCAG 2.2 AA Requirements.
Indicate website language programmatically when changed by user
A website can indicate the language of the website in their "lang" attribute in the html tag. We did this by indicating the language "English" (our default language), but did not change this when the user changed the language in the application.
We now update this value based on the language the user is using, such that screen readers can use this to inform the user about the language currently used.
This update is based on the criteria 3.1.1 Language of Page from the WCAG 2.2. AA Requirements.
Updated ARIA Labels for links on course overview page
On the main page of a course (the course overview page) there are some links which only use an icon and not an accessible name. These two links have been updated to have an accessible name explaining where the links point to and how they should be used. This now allows screen readers to let the user now where the link is for.
This update is based on the criteria 2.4.4 Link Purpose (In Context) from the WCAG 2.2 AA Requirements.
Clear Focus Rings for Keyboard use
This update is based on the following criteria's from the WCAG 2.2 AA Requirements:
The design and understanding has been largely based upon this article.
Improved Form Validation (Messages)
To make sure form validation (messages) are easier to understand by a screen reader we made the following improvements across the application:
make sure to add aria-required if a field is required;
make sure to add aria-invalid if a field is invalid;
make sure the validation messages are programmatically linked to the input fields (not only in order);
make sure the validation messages are programmatically marked as important for screen readers to read.
These updates ensure that form validation and messages related to invalid input from the user are easier to read and understand for screen reader users.
These updates are based upon the following criteria from the WCAG 2.2. AA Requirements:
In addition, we used the following articles/blogs for inspiration on how to implement a good system:
Make Language Switcher Screen Reader Accessible
The language switcher in the navigation bar was not accessible for screen readers (i.e. it did not have a descriptive name). We updated this and make sure it is clear where the button is for.
Sortable Tables
In our application we regularly use sortable tables (mainly for teachers, but also for students). Upon testing these out we noticed that the state of sorting was not always easy to understand, both from a screen reader perspective as from a visual viewer perspective.
Therefore we updated the way we present (sortable) tables and ensured they are easier to operate with a keyboard and screen reader. We did this by applying the following updates:
make sure sortable column headers are buttons to which can be focussed on with clear (aria) labels such that a user understands they sort the table on that column value;
use icons to indicate which columns can be used to sort the data on and indicate also with a clearly distinctive icon which current column is sorted on (these icons are hidden for screen readers since we use aria attributes to indicate this for screen readers);
add captions to each table which are also programmatically linked to ensure that both screen reader users and non-screen reader users understand what the table is showing;
remove the underline for column headers since they are confusing since they look like links.
This update is mainly based upon our own insights based upon a collection of criteria and reading the following two articles which were a great inspiration to improve this:
Underline links by default and do not underline other things
We did not have a consistent styling for links and used the underline styling for both links and emphasis. To ensure that links are easy to recognise we did:
remove the underline style as base style for non-link elements (e.g. table header columns);
added a global link style in the application making sure links by default have an underline.
H1, H2 and H3 headers
To make it easier for screen readers to understand the structure of the page, we have updated our default headers to use H1 for our main page header and H2 for our page sub-headers. In addition, we are going through each page and check whether we want to add a H3 headers to more clearly indicate the different sections/parts in the page.
These updates are based upon the following criteria from the WCAG 2.2. AA Requirements:
Make Student Table Helper Accessible
In our testing we discovered the the way the table helper option for students during practice and tests was not very accessible for screen reader users. This was mainly due to the unclear focus management, unusable tabs in a tablist and the missing table captions.
We updated this feature such that is uses the accessible options we have to open a popup (with proper compliant and predictable focus management) and updated the tablist to be keyboard controllable (with the arrow keys as it should be to be compliant).
Finally, we also updated the tables itself to be more readable, for example by adding a caption to each table and ensuring the column (and row) names are easy to understand.
This update is based on the criteria 2.4.3 Focus Order from the WCAG 2.2 AA Requirements.
Math and Screen Readers
We use Katex for our math rendering in the content. That software ensures that in addition to the displayed math there is an MathML element present as well which is recognised and can be read by screen readers.
This works well with Windows based screen readers (e.g. NVDA, JAWS) or ChromeVox (available in ChromeOS). However, since a recent update of Mac OSx the VoiceOver screen reader does not read MathML anymore. Therefore we advise users who are dependent on a screen reader to use a Windows or ChromeOs based screen reader and report the issue to Apple.