From 98ef454391671507bb557a5d1b0cb3d67f86e76d Mon Sep 17 00:00:00 2001 From: "hedwig.doets" Date: Thu, 17 Jul 2025 14:44:20 +0200 Subject: [PATCH 1/5] initial draft of accessibility how to --- .../front-end/accessibility-best-practices.md | 204 ++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 content/en/docs/howto/front-end/accessibility-best-practices.md diff --git a/content/en/docs/howto/front-end/accessibility-best-practices.md b/content/en/docs/howto/front-end/accessibility-best-practices.md new file mode 100644 index 00000000000..5cf1537a2ab --- /dev/null +++ b/content/en/docs/howto/front-end/accessibility-best-practices.md @@ -0,0 +1,204 @@ +--- +title: "Introduction to Accessibility in Mendix" +linktitle: "Accessibility introduction" +url: /howto/front-end/accessibility-introduction/ +weight: 10 +description: "Describes an introduction on accessibility in general and how to get started making your apps more accessible." +aliases: + - /howtogeneral/bestpractices/accessibility-introduction.html + - /howtogeneral/bestpractices/accessibility-introduction +--- + +## Introduction + +This how-to we’ll go over what accessibility is, what the WCAG is and how it’s relevant to you. We'll also go over the accessibility options in Studio Pro. + +## What is accessibility? + +Accessibility in our context refers to enabling the ability for everyone to use your application and designing your application specifically for that. To be able to do that you have to consider people with all levels of ability. The example that springs to mind the most is people who are blind to any degree. Being blind means being dependent on a screenreader to read the website out to you. However, the screenreaders need to be able to programatically understand the website to be able to properly read that out to the user and convey the information as was intended by the website maker. +An example of what can hinder this is if the component only looks like something, like a div styled and scripted like a button. This button would be inaccessible for blind users since it would not get picked up by screenreaders. +To fix this, you can either use ARIA (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) to add to that div in order to patch that functionality back in. Ideally though, you'd add a semantic html button instead. + + + +This would be picked up by screenreaders, and there's no extra configuration needed to help screenreaders understand it. + +However, accessibility goes further than that, it also includes people who are deaf or hard of hearing and rely on subtitles to understand a video. Or people with a cognitive disability that have trouble remembering the required information they need to enter. Or people who get too distracted by flashy animations on your webpage and therefor can't read what it says. + +Another often overlooked accessibility concern is situational accessibilty. Everyone has probably tried to use their laptop while outside in the sun and had trouble reading the page. The WCAG also covers those kinds of scenarios, requiring websites to have enough contrast so that they’re readable in all kinds of contexts. New parents probably recognize the situational disability from having a child on your arm and trying to use a touchscreen. + +## The WCAG + +Having to consider all these things is a lot, and if everyone would have to reinvent the wheel on that it would take a significant amount of time. That’s why the Web Content Accessibility Guidelines (WCAG) were created. These guidelines help you make your website/application accessible to a larger audience and help you improve the usability of it for everyone else. (Improving accessibility for a small group and finding out a large group benefits from it is called the [curb cut effect](https://en.wikipedia.org/wiki/Curb_cut_effect).) + +These guidelines are also the basis for various laws, including for the EU and the US. The European Accessibility Act (EAA) is based on version 2.1 level AA. + +Currently version 2.2 of these guidelines is available, the expectation is that this version will be adopted over 2.1 in the near future. Since the difference between 2.1 and 2.2 is minimal, that’s the version you probably want to target. You can find the WCAG 2.2 here: [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) + +The version currently used by the EAA can be found here: [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG21/) + +There’s 4 categories that these guidelines are organized in. Each category has a subset of Success Criteria (SC) which are the specific rules you have to comply with. + +### Perceivable +These SC’s are about contrast, correctly labeling your interactive components and providing text alternatives for things that are only visual (for example an informative image, that provides context to a page, needs to have a description in the alt text) + +### Operable +These SC’s are about being able to operate your website/application. This concerns focus, keyboard navigability and supporting different types of input devices. + +### Understandable +These SC’s are about making the page or action as easy to understand as possible. If you have a menu bar for example, it should be operating the same on each page. If you have errors on your page they should give you as much information as possible. +“Please fill out all the input fields“ is not enough for someone to be able to quickly understand what’s happening. They might be under the impression that they've already done so, and will therefore not understand this as an error message. Something like “Error: The required field 'address' was not provided“ gives more information on where and how that user made an error. + +### Robust + +The SC’s are specifically about compatibility with assistive technology, like the previously mentioned screenreader. + +## Using Mendix' accessibility options + +### Labels + +Starting simple, the text of a label will be read out when a screenreader reaches an input field. It should accurately describe the text that needs to be filled in. + +### Aria-required + + + +Various input widgets have the option to add aria-required to the input field. This will tell users of screenreaders that this is a required field. Usually you’d have this information in styling (for example using a star to indicate required fields). Adding this attribute makes sure the programming of your website matches the visuals (required by https://www.w3.org/TR/WCAG22/#info-and-relationships ). + +### Autocomplete + + + +Adding autocomplete to input fields helps people with reduced cognitive ability to reduce the amount of thinking needed to fill out a form. By tagging the firstname and lastname fields accordingly the browser of the user can prefill those inputs. (required by https://www.w3.org/TR/WCAG22/#identify-input-purpose ) + +### Aria-labels + + + +Aria labels are available in a number of widgets. Aria-labels take precedent over anything else that’s available for that element. It should describe the element the user is currently interacting with. This is useful for situations where a visible label would be redundant because of the context of the input field. The aria-label gives the opportunity to add that extra context. + +Note: While it’s very useful for adding context, you can go overboard with aria-labels and even hurt accessibility when using them. An example could be a situation where you have a button that says “Send“, if you’d add an aria-label with a description such as “Click this button to reserve your spot in line!“ that new text takes precedent over the “Send“ text of the button. This would impact voice control, if a user that uses voice control would say “press send“, it would no longer activate that button. +### Alternative text (image widget) + + + +Adding an alternative text that explains the image helps blind users understand the page. This should be left empty if the image is purely decorative. Informative images do need to have alt text, this should be a short text that explains what's happening in the image. If there's text in the image that's not available in another form it should also be added to the alt text. + +#### Decorative vs informative images +For images there's a difference between decorative images and informative images. Decorative images are ones that add no extra context to the page. An extreme example would be a festive page with images of confetti all over it, they don’t need to all be tagged as “Piece of confetti“. It doesn’t add to the users understanding of the page and would actually make it harder to navigate since they would hear “piece of confetti“ continually as they’re trying to read the page. + +### Tab index + +The tab index helps users who only use a keyboard navigate the page. The tab key is used to navigate all input elements, these include buttons, input fields, text boxes, check boxes etc. Any element that can be interacted with, should have a tab index. + +The way someone with a screenreader navigates the page isn’t just with tab. There’s a special key to go through the page an have it read out paragraphs (voiceoverkey + arrows). It’s not needed to put a tab-index on every element of the page, and it actually would make your page harder to navigate if you set it up that way. +### Role type + +Changing the role type will help screenreaders know what type of element you’ve added. Maybe you’ve added a link but the actual action that preforms is that of a button (instead of navigating to a new page it preforms an action on that page). You could make the link have the role button to make sure the screenreader knows what's going on. +### Accessibility helper + +If you require extra settings or attributes for your page, you can add them with the accessibility helper. This allows you to add attributes to widgets that don’t have that available in the settings. This ensures you can add those needed extra things without needing access to the codebase of that widget. +## What to look out for with styling + +The main things to keep in mind when styling are contrast and the focus indicator. +### Contrast + +There’s two specific requirements to do with contrast. +#### Text contrast + +Text contrast needs to be 4.5:1, the way this is calculated is described in the WCAG, but there are plenty of contrast checkers available (for example the WebAIM Contrast Checker). There are some exceptions for example for ‘big text’, but to err on the side of caution it’s best to just stick to 4.5:1. + +In custom-variables.scss you can find the following for font color: +// Default Font Size & Color +$font-size-default: 14px; +$font-color-default: #0a1325; + +Further on in the same document, the background color should be defined: +// Background Colors +// Backgrounds +$bg-color: #f8f8f8; +$bg-color-secondary: #fff; + +In this case with the text color being “#0a1325“ and background color being “#f8f8f8” the contrast ratio here is 17.45:1, well over 4.5:1. + +#### Non-text contrast + +Non text contrast needs to be 3:1, this means that any important inputs or buttons need to have this contrast with the background. An example could be an input field, there needs to be enough contrast there that it’s clear where the input field actually is. This could be the contrast of the field itself with the background, or a border line around the input field with the background. + +In custom-variables.scss the button background could be defined as such: +//== Step 1: Brand Colors +$brand-default: $gray-primary; +$brand-primary: #264ae5; +... +// Background Colors +// Backgrounds +$bg-color: #f8f8f8; +$bg-color-secondary: #fff; +... +// Button Background Color +$btn-default-bg: #fff; +$btn-primary-bg: $brand-primary; + +Our button color is the same as $brand-primary and has the value 264AE5, the background is F8F8F8. The contrast here is 6.19:1. Also well over 3:1. + +A situation where this would fail would be if we change our button color to $gray-light which is also defined in the custom-variables.scss file. The color contrast of A9ACB3 and F8F8F8 is only 2.14, which isn’t enough for everyone to be able to see the button in that case. + +### Focus + +The focus indicator helps users identify where the focus currently is on the page. There’s a few success criteria that describe what the focus indicator should look like. + + + +focus visible: the focus should be visible at all, this criteria does not specify how. In theory for this SC it could be a single pixel on the right of the element. However, there’s other criteria that give a bit more guidance on what it should look like. + +Use of color https://www.w3.org/TR/WCAG22/#use-of-color : this states that nothing can be indicated with one sensory characteristic alone. This counts for everything and thus also applies to the focus indicator. Using only color to indicate a focus change would fail this criteria. The focus indicator should use something else, the most common thing is to change the shape of the element while it’s focused. This could be something as simple as a box around the element, that counts as changing the shape of the component. + +The rules as described in (link back to non text contrast) also apply for the focus indicator. The color of the input focus indicator can be set here: +// Form Input styling +... +$form-input-border-focus-color: $brand-primary; +## Other quick wins +### Page titled + +Set the title of every page, to ensure it doesn’t end up with the url in the tab. SC 2.4.2. Page titled + + + +### Error messages + +Make sure you’ve got comprehensive error messages, do they describe the situation clearly? Do they offer enough guidance on how the fix the error? An example of a bad error message here would be having an error “please fill in all required fields“. Since the user might be under the impression that they have already done that. Instead saying “Please fill in address“ would give the user more information on how they can resolve the error. + +( +Web Content Accessibility Guidelines (WCAG) 2.2 , Web Content Accessibility Guidelines (WCAG) 2.2 , + +Web Content Accessibility Guidelines (WCAG) 2.2 ) +### Link purpose +Link purpose, instead of having a link say “click here“ it should be clear from the surrounding text where that link leads. Ideally, that description would be part of the link itself: + +Web Content Accessibility Guidelines (WCAG) 2.2(since this is a level AAA Success Criteria, it’s usually not required). +## How to test whether your app is accessible +### Automated accessibility testing + +There’s multiple options to run automatic tests on your pages, these are great for giving you an indication on the accessibility of your website and can suggest things to improve. +### Manual accessibility testing + +While also being the most time consuming, the best way to test your application for accessibility is to do a manual test. + +Doing just a few checks already goes a long way: + + Keyboard navigability, can you reach all the input elements with your keyboard? Does your tab key take you through all the elements of your page? + + Screenreader, is all the information that’s clear to a sighted person also available to a blind person? Are labels of input fields being read out correctly? + + Color contrast, does both text and nontext content have enough contrast? + +## Read more + +For a more in depth look at the accessibility learning path at the Academy Accessibility learning path. + +Mendix' full accessibility report can be found here: +Mendix Accessibility Conformance: Ensure Your Apps Are Accessible + + + + From dc183e31fa3e4afeb90747fc4723e5aecedea1cc Mon Sep 17 00:00:00 2001 From: "hedwig.doets" Date: Wed, 23 Jul 2025 13:51:13 +0200 Subject: [PATCH 2/5] Add urls --- .../front-end/accessibility-best-practices.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/content/en/docs/howto/front-end/accessibility-best-practices.md b/content/en/docs/howto/front-end/accessibility-best-practices.md index 5cf1537a2ab..b44c5a9dfbd 100644 --- a/content/en/docs/howto/front-end/accessibility-best-practices.md +++ b/content/en/docs/howto/front-end/accessibility-best-practices.md @@ -106,7 +106,7 @@ The main things to keep in mind when styling are contrast and the focus indicato There’s two specific requirements to do with contrast. #### Text contrast -Text contrast needs to be 4.5:1, the way this is calculated is described in the WCAG, but there are plenty of contrast checkers available (for example the WebAIM Contrast Checker). There are some exceptions for example for ‘big text’, but to err on the side of caution it’s best to just stick to 4.5:1. +Text contrast needs to be 4.5:1, the way this is calculated is described in the WCAG, but there are plenty of contrast checkers available (for example the [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)). There are some exceptions for example for ‘big text’, but to err on the side of caution it’s best to just stick to 4.5:1. In custom-variables.scss you can find the following for font color: // Default Font Size & Color @@ -126,7 +126,7 @@ In this case with the text color being “#0a1325“ and background color being Non text contrast needs to be 3:1, this means that any important inputs or buttons need to have this contrast with the background. An example could be an input field, there needs to be enough contrast there that it’s clear where the input field actually is. This could be the contrast of the field itself with the background, or a border line around the input field with the background. In custom-variables.scss the button background could be defined as such: -//== Step 1: Brand Colors +```//== Step 1: Brand Colors $brand-default: $gray-primary; $brand-primary: #264ae5; ... @@ -138,6 +138,7 @@ $bg-color-secondary: #fff; // Button Background Color $btn-default-bg: #fff; $btn-primary-bg: $brand-primary; +``` Our button color is the same as $brand-primary and has the value 264AE5, the background is F8F8F8. The contrast here is 6.19:1. Also well over 3:1. @@ -160,7 +161,7 @@ $form-input-border-focus-color: $brand-primary; ## Other quick wins ### Page titled -Set the title of every page, to ensure it doesn’t end up with the url in the tab. SC 2.4.2. Page titled +Set the title of every page, to ensure it doesn’t end up with the url in the tab. SC 2.4.2. [Page titled](https://www.w3.org/TR/WCAG22/#page-titled) @@ -169,17 +170,14 @@ Set the title of every page, to ensure it doesn’t end up with the url in the t Make sure you’ve got comprehensive error messages, do they describe the situation clearly? Do they offer enough guidance on how the fix the error? An example of a bad error message here would be having an error “please fill in all required fields“. Since the user might be under the impression that they have already done that. Instead saying “Please fill in address“ would give the user more information on how they can resolve the error. ( -Web Content Accessibility Guidelines (WCAG) 2.2 , Web Content Accessibility Guidelines (WCAG) 2.2 , +[WCAG Error Identification](https://www.w3.org/TR/WCAG22/#error-identification), [WCAG Error Suggestion](https://www.w3.org/TR/WCAG22/#error-suggestion), [Error Prevention](https://www.w3.org/TR/WCAG22/#error-prevention-legal-financial-data) -Web Content Accessibility Guidelines (WCAG) 2.2 ) ### Link purpose -Link purpose, instead of having a link say “click here“ it should be clear from the surrounding text where that link leads. Ideally, that description would be part of the link itself: - -Web Content Accessibility Guidelines (WCAG) 2.2(since this is a level AAA Success Criteria, it’s usually not required). +[Link purpose](https://www.w3.org/TR/WCAG22/#link-purpose-in-context), instead of having a link say “click here“ it should be clear from the surrounding text where that link leads. Ideally, that description would be part of the link itself: https://www.w3.org/TR/WCAG22/#link-purpose-link-only (since this is a level AAA Success Criteria, it’s usually not required). ## How to test whether your app is accessible ### Automated accessibility testing -There’s multiple options to run automatic tests on your pages, these are great for giving you an indication on the accessibility of your website and can suggest things to improve. +There’s multiple options to run automatic tests on your pages, these are great for giving you an indication on the accessibility of your website and can suggest things to improve. W3C offers a list of such tools: [List of tools for checking if your web content meets accessibility guidelines.](https://www.w3.org/WAI/test-evaluate/tools/list/) ### Manual accessibility testing While also being the most time consuming, the best way to test your application for accessibility is to do a manual test. @@ -192,9 +190,11 @@ Doing just a few checks already goes a long way: Color contrast, does both text and nontext content have enough contrast? +More info on this can be found on this page by the W3C: [Easy Checks – A First Review of Web Accessibility](https://www.w3.org/WAI/test-evaluate/preliminary/) + ## Read more -For a more in depth look at the accessibility learning path at the Academy Accessibility learning path. +For a more in depth look at the accessibility learning path at the [Academy Accessibility learning path](https://academy.mendix.com/link/paths/141/Improve-Your-App-Accessibility). Mendix' full accessibility report can be found here: Mendix Accessibility Conformance: Ensure Your Apps Are Accessible From 3c69452612779a83043284eef0a452834172d00a Mon Sep 17 00:00:00 2001 From: "hedwig.doets" Date: Tue, 2 Sep 2025 13:34:48 +0200 Subject: [PATCH 3/5] Update page titled description --- content/en/docs/howto/front-end/accessibility-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/howto/front-end/accessibility-best-practices.md b/content/en/docs/howto/front-end/accessibility-best-practices.md index b44c5a9dfbd..b0afe326ef7 100644 --- a/content/en/docs/howto/front-end/accessibility-best-practices.md +++ b/content/en/docs/howto/front-end/accessibility-best-practices.md @@ -161,7 +161,7 @@ $form-input-border-focus-color: $brand-primary; ## Other quick wins ### Page titled -Set the title of every page, to ensure it doesn’t end up with the url in the tab. SC 2.4.2. [Page titled](https://www.w3.org/TR/WCAG22/#page-titled) +Every page needs a meaningful name that describes the page. Having just "Page" for example isn't enough to make the page easy to find between other tabs. SC 2.4.2. [Page titled](https://www.w3.org/TR/WCAG22/#page-titled) From 024fd88d5af110300580ba8fa6d408425a92cab4 Mon Sep 17 00:00:00 2001 From: "hedwig.doets" Date: Tue, 2 Sep 2025 13:49:53 +0200 Subject: [PATCH 4/5] Move documentation from how-to to refguide --- .../general}/accessibility-best-practices.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) rename content/en/docs/{howto/front-end => refguide/general}/accessibility-best-practices.md (97%) diff --git a/content/en/docs/howto/front-end/accessibility-best-practices.md b/content/en/docs/refguide/general/accessibility-best-practices.md similarity index 97% rename from content/en/docs/howto/front-end/accessibility-best-practices.md rename to content/en/docs/refguide/general/accessibility-best-practices.md index b0afe326ef7..ed2cf21e5b4 100644 --- a/content/en/docs/howto/front-end/accessibility-best-practices.md +++ b/content/en/docs/refguide/general/accessibility-best-practices.md @@ -1,17 +1,14 @@ --- title: "Introduction to Accessibility in Mendix" linktitle: "Accessibility introduction" -url: /howto/front-end/accessibility-introduction/ +url: /refguide/accessibility-introduction/ weight: 10 description: "Describes an introduction on accessibility in general and how to get started making your apps more accessible." -aliases: - - /howtogeneral/bestpractices/accessibility-introduction.html - - /howtogeneral/bestpractices/accessibility-introduction --- ## Introduction -This how-to we’ll go over what accessibility is, what the WCAG is and how it’s relevant to you. We'll also go over the accessibility options in Studio Pro. +This guide we’ll go over what accessibility is, what the WCAG is and how it’s relevant to you. We'll also go over the accessibility options in Studio Pro. ## What is accessibility? From 93714ad60ac49939ef267bfb079223faafdef3a0 Mon Sep 17 00:00:00 2001 From: "hedwig.doets" Date: Fri, 10 Oct 2025 17:16:05 +0200 Subject: [PATCH 5/5] Update document after review --- .../general/accessibility-best-practices.md | 151 +++++++++++------- 1 file changed, 90 insertions(+), 61 deletions(-) diff --git a/content/en/docs/refguide/general/accessibility-best-practices.md b/content/en/docs/refguide/general/accessibility-best-practices.md index ed2cf21e5b4..0ae4a186814 100644 --- a/content/en/docs/refguide/general/accessibility-best-practices.md +++ b/content/en/docs/refguide/general/accessibility-best-practices.md @@ -8,122 +8,150 @@ description: "Describes an introduction on accessibility in general and how to g ## Introduction -This guide we’ll go over what accessibility is, what the WCAG is and how it’s relevant to you. We'll also go over the accessibility options in Studio Pro. +In this guide, we'll go over what accessibility is, what the Web Content Accessibility Guidelines (WCAG) are, and how they're relevant to you. We'll also go over the accessibility options in Studio Pro. ## What is accessibility? -Accessibility in our context refers to enabling the ability for everyone to use your application and designing your application specifically for that. To be able to do that you have to consider people with all levels of ability. The example that springs to mind the most is people who are blind to any degree. Being blind means being dependent on a screenreader to read the website out to you. However, the screenreaders need to be able to programatically understand the website to be able to properly read that out to the user and convey the information as was intended by the website maker. -An example of what can hinder this is if the component only looks like something, like a div styled and scripted like a button. This button would be inaccessible for blind users since it would not get picked up by screenreaders. -To fix this, you can either use ARIA (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) to add to that div in order to patch that functionality back in. Ideally though, you'd add a semantic html button instead. +Accessibility in our context refers to enabling everyone to use your application and designing it specifically for that. To achieve this, you must consider people with all levels of ability. The example that springs to mind the most is people who are blind to any degree. Being blind means being dependent on assistive technologies, such as screen readers, to read the website out to you. However, screen readers must be able to programmatically understand the website to accurately read it out to the user and convey the information as intended by the website maker. An example of what can hinder this is if the component only looks like something, like a div styled and scripted like a button. This button would be inaccessible to visually impaired users because screen readers would not detect it. To fix this, you can either use ARIA ([ARIA - Accessibility | MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA)) to add to that div to patch that functionality back in. Ideally, though, you'd add a semantic HTML button instead. +```html +``` -This would be picked up by screenreaders, and there's no extra configuration needed to help screenreaders understand it. +Screen readers would pick it up, and no extra configuration is needed to help them understand it. -However, accessibility goes further than that, it also includes people who are deaf or hard of hearing and rely on subtitles to understand a video. Or people with a cognitive disability that have trouble remembering the required information they need to enter. Or people who get too distracted by flashy animations on your webpage and therefor can't read what it says. +However, accessibility goes further than that; it also includes people who are deaf or hard of hearing and rely on subtitles to understand a video. Or people with a cognitive disability who struggle to recall the required information they need to enter. Or people who get too distracted by flashy animations on your webpage, and therefore can't read what it says. It also includes neurodivergent individuals who may encounter barriers that make it difficult, if not impossible, to use a website. -Another often overlooked accessibility concern is situational accessibilty. Everyone has probably tried to use their laptop while outside in the sun and had trouble reading the page. The WCAG also covers those kinds of scenarios, requiring websites to have enough contrast so that they’re readable in all kinds of contexts. New parents probably recognize the situational disability from having a child on your arm and trying to use a touchscreen. +Another often overlooked accessibility concern is situational accessibility. For instance, people trying to use their laptops outside in the sun usually have trouble reading the page. The WCAG also covers those kinds of scenarios, requiring websites to have enough contrast so that they're readable in all sorts of contexts. New parents probably recognize the situational disability from having a child on their arm and trying to use a touchscreen. -## The WCAG +## The Web Content Accessibility Guidelines (WCAG) -Having to consider all these things is a lot, and if everyone would have to reinvent the wheel on that it would take a significant amount of time. That’s why the Web Content Accessibility Guidelines (WCAG) were created. These guidelines help you make your website/application accessible to a larger audience and help you improve the usability of it for everyone else. (Improving accessibility for a small group and finding out a large group benefits from it is called the [curb cut effect](https://en.wikipedia.org/wiki/Curb_cut_effect).) +Considering all these things is a lot, and if everyone had to start from scratch, it would take a significant amount of time. That's why the World Wide Web Consortium (W3C) created the Web Content Accessibility Guidelines (WCAG). These guidelines help you make your application accessible to a larger audience and improve its usability for everyone else. (Improving accessibility for a small group and finding out that a considerable group benefits from it is called the [curb cut effect](https://en.wikipedia.org/wiki/Curb_cut_effect).) -These guidelines are also the basis for various laws, including for the EU and the US. The European Accessibility Act (EAA) is based on version 2.1 level AA. +These guidelines are also the basis for various laws, including those of the EU and the US. The European Accessibility Act (EAA) is based on version 2.1 level AA. -Currently version 2.2 of these guidelines is available, the expectation is that this version will be adopted over 2.1 in the near future. Since the difference between 2.1 and 2.2 is minimal, that’s the version you probably want to target. You can find the WCAG 2.2 here: [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) +Currently, version 2.2 of these guidelines is available; the expectation is that you will adopt this version over version 2.1 in the near future. Since the difference between 2.1 and 2.2 is minimal, that's the version you want to target. You can find the WCAG 2.2 here: [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/). -The version currently used by the EAA can be found here: [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG21/) +The version currently used by the EAA is Web Content Accessibility Guidelines (WCAG) 2.1 -There’s 4 categories that these guidelines are organized in. Each category has a subset of Success Criteria (SC) which are the specific rules you have to comply with. +The guidelines are organized into four distinct categories. Each category has a subset of Success Criteria (SC), which are the specific rules you have to comply with. ### Perceivable -These SC’s are about contrast, correctly labeling your interactive components and providing text alternatives for things that are only visual (for example an informative image, that provides context to a page, needs to have a description in the alt text) +SCs that fall under the [Perceivable Principle](https://www.w3.org/TR/WCAG22/#perceivable) are about contrast, correctly labeling your interactive components, and providing text alternatives for things that are only visual (for example, an informative image that gives context to a page needs to have a description in the alt text attribute). ### Operable -These SC’s are about being able to operate your website/application. This concerns focus, keyboard navigability and supporting different types of input devices. +SCs that fall under the [Operable Principle](https://www.w3.org/TR/WCAG22/#operable) are about being able to operate your application. This concerns focus, keyboard navigability, and supporting different types of input devices. ### Understandable -These SC’s are about making the page or action as easy to understand as possible. If you have a menu bar for example, it should be operating the same on each page. If you have errors on your page they should give you as much information as possible. -“Please fill out all the input fields“ is not enough for someone to be able to quickly understand what’s happening. They might be under the impression that they've already done so, and will therefore not understand this as an error message. Something like “Error: The required field 'address' was not provided“ gives more information on where and how that user made an error. +SCs that fall under the [Understandable Principle](https://www.w3.org/TR/WCAG22/#understandable) make the page or action as easy to understand as possible. If you have a menu bar, for example, it should function consistently across all pages. If you encounter errors on your page, the system should provide you with as much information as possible. The instruction "Please fill out all the input fields" is insufficient for someone to understand what's happening quickly. They might be under the impression that they've already done so, and will therefore not understand this as an error message. Something like "Error: The required field' address' was not provided" gives more information on where and how that user made an error. ### Robust -The SC’s are specifically about compatibility with assistive technology, like the previously mentioned screenreader. +The [Robust Principle](https://www.w3.org/TR/WCAG22/#robust) SCs are specifically about compatibility with assistive technology, like the previously mentioned screenreader. ## Using Mendix' accessibility options ### Labels -Starting simple, the text of a label will be read out when a screenreader reaches an input field. It should accurately describe the text that needs to be filled in. +When a screen reader reaches an input field, it will read the label text aloud. This label must clearly describe the information required. ### Aria-required -Various input widgets have the option to add aria-required to the input field. This will tell users of screenreaders that this is a required field. Usually you’d have this information in styling (for example using a star to indicate required fields). Adding this attribute makes sure the programming of your website matches the visuals (required by https://www.w3.org/TR/WCAG22/#info-and-relationships ). +Various input widgets have the option to add aria-required to the input field. It will inform users of screen readers that this is a required field. Usually, you'd have this information in styling (for example, using a star to indicate required fields). Adding this attribute makes sure the programming of your application matches the visuals required by [Success Criterion 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships). + +Tip: Do not set the Validation Type to "Required." If you do, a validation message will appear as soon as the user exits the input field. Instead, validation for required fields should occur only when the user submits the form or attempts to proceed to the next step. ### Autocomplete -Adding autocomplete to input fields helps people with reduced cognitive ability to reduce the amount of thinking needed to fill out a form. By tagging the firstname and lastname fields accordingly the browser of the user can prefill those inputs. (required by https://www.w3.org/TR/WCAG22/#identify-input-purpose ) +Adding autocomplete to input fields can help individuals with reduced cognitive abilities by reducing the effort needed to fill out forms ([Success Criterion 1.3.5 Identify Input Purpose](https://www.w3.org/TR/WCAG22/#identify-input-purpose)). When the first name and last name fields are correctly tagged, browsers can auto-fill these inputs. However, while beneficial for some, autocomplete can hinder users of assistive technologies, as it complicates the form-filling process. In such cases, it may be better to turn off this feature. + +You should avoid using autocomplete in the following situations: + +* **Sensitive Information**: Fields that collect sensitive data, such as credit card numbers, government IDs, or personal identification numbers. It helps protect user privacy and prevents unauthorized access to sensitive information. + +* **Public Computers**: If forms are likely to be filled out on public or shared computers, disabling autocomplete can prevent users from accessing previously entered information. + +* **One-Time Inputs**: For fields that require unique, one-time entries (like a temporary PIN), autocomplete can be unnecessary and may confuse users. + +* **Complex Forms**: In lengthy or complex forms, autocomplete might lead to incorrect autofill suggestions, which can frustrate users and lead to errors. + +* **Regulatory Compliance**: Certain regulations may require that sensitive information not be stored or autofilled. Disabling autocomplete can help ensure compliance with such regulations. ### Aria-labels -Aria labels are available in a number of widgets. Aria-labels take precedent over anything else that’s available for that element. It should describe the element the user is currently interacting with. This is useful for situations where a visible label would be redundant because of the context of the input field. The aria-label gives the opportunity to add that extra context. +Aria labels are available in several widgets. Aria-labels take precedent over anything else that's available for that element. It should describe the element the user is currently interacting with. It is helpful in situations where a visible label would be redundant due to the context of the input field. The aria-label provides an opportunity to add extra context for [Success Criterion 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value). + +**Important**: While aria-labels are very useful for adding context, using them excessively can even hurt accessibility. An example could be a situation where you have a button that says "Send ", if you add an aria-label with a description such as "Click this button to reserve your spot in line! "that new text takes precedent over the "Send "text of the button. It would impact voice control. If a user who uses voice control said "press send ", it would no longer activate that button. -Note: While it’s very useful for adding context, you can go overboard with aria-labels and even hurt accessibility when using them. An example could be a situation where you have a button that says “Send“, if you’d add an aria-label with a description such as “Click this button to reserve your spot in line!“ that new text takes precedent over the “Send“ text of the button. This would impact voice control, if a user that uses voice control would say “press send“, it would no longer activate that button. -### Alternative text (image widget) +### Alternative text (Image widget) -Adding an alternative text that explains the image helps blind users understand the page. This should be left empty if the image is purely decorative. Informative images do need to have alt text, this should be a short text that explains what's happening in the image. If there's text in the image that's not available in another form it should also be added to the alt text. +Adding an alternative text that explains the image helps visually impaired users understand the page as required by [Success Criterion 1.1.1 Non-text Content](https://www.w3.org/TR/WCAG22/#non-text-content). It should be left empty if the image is purely decorative. Informative images require alt text, which should be a brief description explaining what's happening in the image. If there's text in the image that's not available in another form, it should be included in the alt text. #### Decorative vs informative images -For images there's a difference between decorative images and informative images. Decorative images are ones that add no extra context to the page. An extreme example would be a festive page with images of confetti all over it, they don’t need to all be tagged as “Piece of confetti“. It doesn’t add to the users understanding of the page and would actually make it harder to navigate since they would hear “piece of confetti“ continually as they’re trying to read the page. + +For images, there's a difference between decorative images and informative images. Decorative images add no extra context to the page. An extreme example would be a festive page with images of confetti all over it; they don't need to all be tagged as "Piece of confetti ". It doesn't add to the user's understanding of the page. It would actually make it harder to navigate since they would hear "Piece of confetti" continually as they're trying to read the page. ### Tab index -The tab index helps users who only use a keyboard navigate the page. The tab key is used to navigate all input elements, these include buttons, input fields, text boxes, check boxes etc. Any element that can be interacted with, should have a tab index. +The tabindex helps users who only use a keyboard navigate the page (as required by [Guideline 2.1 Keyboard Accessible](https://www.w3.org/TR/WCAG22/#keyboard-accessible)). The Tab key allows users to navigate through interactive elements on a website, such as links, buttons, and form fields. Any element that can be interacted with should have a tab index. + +The way someone with a screen reader navigates the page involves more than just the tab. There's a special key to navigate the page and have it read out paragraphs (i.e, VoiceOver key + arrows in Mac OS). Assigning a tabindex to every element on the page is unnecessary, as it makes the page more challenging to navigate. + +To ensure that all interactive elements are accessible via the Tab key: +* Make sure all clickable elements are focusable. +* Use the tabindex attribute correctly. A value of 0 allows an element to be part of the default tab order. + +Tip: Avoid using positive tabindex values, as they can confuse users by altering the natural focus order. -The way someone with a screenreader navigates the page isn’t just with tab. There’s a special key to go through the page an have it read out paragraphs (voiceoverkey + arrows). It’s not needed to put a tab-index on every element of the page, and it actually would make your page harder to navigate if you set it up that way. ### Role type -Changing the role type will help screenreaders know what type of element you’ve added. Maybe you’ve added a link but the actual action that preforms is that of a button (instead of navigating to a new page it preforms an action on that page). You could make the link have the role button to make sure the screenreader knows what's going on. +Changing the role type helps screen readers understand the kind of element you've added ([Success Criterion 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)). You may have added a link, but the function performed is that of a button (instead of navigating to a new page, it performs an action on that page). In this case, it is better to change the element to a button. Changing role types can lead to confusion for users of assistive technologies, as incorrect roles may misrepresent the function of an element, making it harder for users to navigate and interact with content. Whenever possible, always choose semantic HTML over [ARIA (Accessible Rich Internet Applications)](https://www.w3.org/TR/wai-aria/) roles. + ### Accessibility helper -If you require extra settings or attributes for your page, you can add them with the accessibility helper. This allows you to add attributes to widgets that don’t have that available in the settings. This ensures you can add those needed extra things without needing access to the codebase of that widget. +If you need additional settings or attributes for your page, you can add them using the accessibility helper. It allows you to add attributes to widgets that are not available in the settings. It ensures you can add the necessary extra attributes without needing access to the codebase of that widget. ## What to look out for with styling -The main things to keep in mind when styling are contrast and the focus indicator. +The key elements to consider when styling are contrast and the focus indicator. ### Contrast -There’s two specific requirements to do with contrast. -#### Text contrast +There are two specific requirements related to contrast: [Success Criterion 1.4.3 Contrast (Minimum)](https://www.w3.org/TR/WCAG22/#contrast-minimum) for text contrast, and [Success Criterion 1.4.11 Non-text Contrast](https://www.w3.org/TR/WCAG22/#non-text-contrast) for user interface components and graphical objects. -Text contrast needs to be 4.5:1, the way this is calculated is described in the WCAG, but there are plenty of contrast checkers available (for example the [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)). There are some exceptions for example for ‘big text’, but to err on the side of caution it’s best to just stick to 4.5:1. +#### Text contrast +In the WCAG, you can find the calculation method, and there are many contrast checkers available, such as the [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/). There are some exceptions, such as for 'big text', but to err on the side of caution, it's best to stick to 4.5:1. -In custom-variables.scss you can find the following for font color: +In custom-variables.scss, you can find the following for font color: +```css // Default Font Size & Color $font-size-default: 14px; $font-color-default: #0a1325; +``` Further on in the same document, the background color should be defined: +```css // Background Colors // Backgrounds $bg-color: #f8f8f8; $bg-color-secondary: #fff; +``` -In this case with the text color being “#0a1325“ and background color being “#f8f8f8” the contrast ratio here is 17.45:1, well over 4.5:1. +In this case with the text color being “`#0a1325`“ and background color being “`#f8f8f8`” the contrast ratio here is 17.45:1, well over 4.5:1. #### Non-text contrast -Non text contrast needs to be 3:1, this means that any important inputs or buttons need to have this contrast with the background. An example could be an input field, there needs to be enough contrast there that it’s clear where the input field actually is. This could be the contrast of the field itself with the background, or a border line around the input field with the background. +Non-text contrast needs to be 3:1; this means that any critical inputs or buttons need to have this contrast with the background. An example could be an input field. There needs to be sufficient contrast so that the input field is clearly visible. It could be the contrast of the field itself with the background, or a border line around the input field with the background. -In custom-variables.scss the button background could be defined as such: -```//== Step 1: Brand Colors +In custom-variables.scss, you could define the button background as such: +```css +//== Step 1: Brand Colors $brand-default: $gray-primary; $brand-primary: #264ae5; ... @@ -137,64 +165,65 @@ $btn-default-bg: #fff; $btn-primary-bg: $brand-primary; ``` -Our button color is the same as $brand-primary and has the value 264AE5, the background is F8F8F8. The contrast here is 6.19:1. Also well over 3:1. +Our button color is the same as $brand-primary, with the value `#264AE5`, and its background is `#F8F8F8`. The contrast here is 6.19:1, also well over 3:1. -A situation where this would fail would be if we change our button color to $gray-light which is also defined in the custom-variables.scss file. The color contrast of A9ACB3 and F8F8F8 is only 2.14, which isn’t enough for everyone to be able to see the button in that case. +A situation where this would fail would be if you change your button color to `$gray-light`, also defined in the `custom-variables.scss` file. The color contrast of `#A9ACB3` and `#F8F8F8` is only 2.14, which is insufficient for everyone to see the button. ### Focus -The focus indicator helps users identify where the focus currently is on the page. There’s a few success criteria that describe what the focus indicator should look like. +The focus indicator helps users identify where the focus currently is on the page. There are a few success criteria that describe what the focus indicator should look like. -focus visible: the focus should be visible at all, this criteria does not specify how. In theory for this SC it could be a single pixel on the right of the element. However, there’s other criteria that give a bit more guidance on what it should look like. +[Focus visible](https://www.w3.org/TR/WCAG22/#focus-visible) The focus should be visible at all times; however, this criterion does not specify how. In theory, for this SC, it could be a single pixel on the right of the element. However, other criteria provide more specific guidance on what it should look like. -Use of color https://www.w3.org/TR/WCAG22/#use-of-color : this states that nothing can be indicated with one sensory characteristic alone. This counts for everything and thus also applies to the focus indicator. Using only color to indicate a focus change would fail this criteria. The focus indicator should use something else, the most common thing is to change the shape of the element while it’s focused. This could be something as simple as a box around the element, that counts as changing the shape of the component. +[Use of color](https://www.w3.org/TR/WCAG22/#use-of-color): This indicates that a single sensory characteristic alone is insufficient to convey meaning. It counts for everything and thus also applies to the focus indicator. Using only color to indicate a focus change would fail this criterion. The focus indicator should use an alternative method. The most common thing is to change the shape of the element while it's focused. It could be something as simple as a box around the element that counts as changing the shape of the component. -The rules as described in (link back to non text contrast) also apply for the focus indicator. The color of the input focus indicator can be set here: +The rules as described in "Non-text contrast" also apply to the focus indicator. You can set the color of the input focus indicator here: + +```css // Form Input styling ... $form-input-border-focus-color: $brand-primary; +``` ## Other quick wins ### Page titled -Every page needs a meaningful name that describes the page. Having just "Page" for example isn't enough to make the page easy to find between other tabs. SC 2.4.2. [Page titled](https://www.w3.org/TR/WCAG22/#page-titled) +[Page titled](https://www.w3.org/TR/WCAG22/#page-titled): Every page needs a meaningful name that describes the page. Having just "Page," for example, isn't enough to make the page easy to find among other tabs. ### Error messages -Make sure you’ve got comprehensive error messages, do they describe the situation clearly? Do they offer enough guidance on how the fix the error? An example of a bad error message here would be having an error “please fill in all required fields“. Since the user might be under the impression that they have already done that. Instead saying “Please fill in address“ would give the user more information on how they can resolve the error. +Make sure you've got comprehensive error messages. Do they describe the situation clearly? Do they provide sufficient guidance on how to resolve the error? An example of a poor error message would be "Please fill in all required fields." Since the user might be under the impression that they have already done that, saying "Please fill in address" would give the user more information on how they can resolve the error. -( -[WCAG Error Identification](https://www.w3.org/TR/WCAG22/#error-identification), [WCAG Error Suggestion](https://www.w3.org/TR/WCAG22/#error-suggestion), [Error Prevention](https://www.w3.org/TR/WCAG22/#error-prevention-legal-financial-data) +More information on this can be found in the following SCs: +[WCAG Error Identification](https://www.w3.org/TR/WCAG22/#error-identification), [WCAG Error Suggestion](https://www.w3.org/TR/WCAG22/#error-suggestion), [WCAG Error Prevention](https://www.w3.org/TR/WCAG22/#error-prevention-legal-financial-data) ### Link purpose -[Link purpose](https://www.w3.org/TR/WCAG22/#link-purpose-in-context), instead of having a link say “click here“ it should be clear from the surrounding text where that link leads. Ideally, that description would be part of the link itself: https://www.w3.org/TR/WCAG22/#link-purpose-link-only (since this is a level AAA Success Criteria, it’s usually not required). +[Link purpose](https://www.w3.org/TR/WCAG22/#link-purpose-in-context), instead of using "click here", the link's destination should be clear from the surrounding text. Ideally, that description would be part of the link itself. It would help users understand the purpose of each link, enabling them to decide whether to follow it. Also, assistive technology can provide users with a list of links on the website. + ## How to test whether your app is accessible ### Automated accessibility testing -There’s multiple options to run automatic tests on your pages, these are great for giving you an indication on the accessibility of your website and can suggest things to improve. W3C offers a list of such tools: [List of tools for checking if your web content meets accessibility guidelines.](https://www.w3.org/WAI/test-evaluate/tools/list/) +There are multiple options to run automatic tests on your pages. These tools are great for indicating the accessibility of your website and suggesting areas for improvement. W3C offers a [list of tools for checking if your web content meets accessibility guidelines.](https://www.w3.org/WAI/test-evaluate/tools/list/) ### Manual accessibility testing -While also being the most time consuming, the best way to test your application for accessibility is to do a manual test. +Although it is the most time-consuming, a manual test is a good way to assess your application's accessibility when you don't have access to users with different abilities. The best way to test your application is with real users. Doing just a few checks already goes a long way: +* Keyboard navigability: Can you reach all the input elements with your keyboard? Does your Tab key take you through all the elements of your page? +* Screen reader: Is all the information that's clear to a sighted person also available to a low vision or non-sighted person? Are labels of input fields being read out correctly? +* Color contrast: Does both text and non-text content have enough contrast? - Keyboard navigability, can you reach all the input elements with your keyboard? Does your tab key take you through all the elements of your page? - - Screenreader, is all the information that’s clear to a sighted person also available to a blind person? Are labels of input fields being read out correctly? - - Color contrast, does both text and nontext content have enough contrast? - -More info on this can be found on this page by the W3C: [Easy Checks – A First Review of Web Accessibility](https://www.w3.org/WAI/test-evaluate/preliminary/) +Find more info on this in [the W3C Easy Checks – A First Review of Web Accessibility](https://www.w3.org/WAI/test-evaluate/preliminary/) ## Read more -For a more in depth look at the accessibility learning path at the [Academy Accessibility learning path](https://academy.mendix.com/link/paths/141/Improve-Your-App-Accessibility). +For a more in depth look at the accessibility, there's a learning path at the [Academy Accessibility learning path](https://academy.mendix.com/link/paths/141/Improve-Your-App-Accessibility). Mendix' full accessibility report can be found here: -Mendix Accessibility Conformance: Ensure Your Apps Are Accessible +[Mendix Accessibility Conformance: Ensure Your Apps Are Accessible](https://www.mendix.com/evaluation-guide/app-lifecycle/develop/ux-multi-channel-apps/accessibility/)