Making your eko project ADA compliant

Here is our eko guide to making your projects WCAG 2.1 AA compliant!

Eko Studio Buttons:

Text Buttons

For text buttons in eko studio by default the text inside the button will be read/expressed to anyone using ADA settings but there are a few scenarios to look out for and 2 main ones are focus states and color contrast:

Button Roles:

Eko uses ARIA tagging, this means it assigns different eko studio elements a role, such as role=text, role=button, etc. If you are visually impaired how do you know what is a button and what is just text? That’s where the ARIA roles come into play. Eko studio currently handles button roles but there are a couple of scenarios to look out for:

Using Text buttons as information or additive text on the screen but NOT interactive.

All interactive text buttons should have a role=button, but what if you want to make a text button that ISN’T interactive and just descriptive like below:

We have a button in eko studio whose action is “Graphic (No Action)” Which means it’s not interactive, the button is providing context to the choice buttons which are “Hands” and “UFO”. So be sure to make any non-interactive text elements as “Graphic (No Action)” and check the box “Graphic Only” so as not to confuse the viewer to which elements are interactive buttons and which are not.

Color Contrast:

ADA also includes those who are color blind or might have difficulty distinguishing various colors on top of each other. There are some really helpful checks online to see if your text buttons have enough contrast in them:

https://www.w3.org/WAI/WCAG21/Techniques/general/G17 WCAG 2.1 introduced requirements for color contrast that apply not only to text, but icons that are a part of interactive elements as well. Normal-sized text must have a color contrast ratio of at least 4.5:1, while large text & icons must have a color contrast ratio of 3.0:1.

So that means you want to meet at least a 4.5:1. And looking at the list of resources there’s a lovely online color contrast testing: https://juicystudio.com/services/luminositycontrastratio.php#specify

So if you were to take black text on a gray background:

It shows that you would clear AAA which is the best ADA standard and this black on gray would work for any button color combination you have.

Invisible Buttons:

Say you wanted to choose between two objects that are inside the video but don’t have a text button or an image button. Instead you want to make an invisible hotspot area over that object so the viewer feels like they are selecting the video. To make this ADA compliant you can simply change the button name in eko studio to what you would put if you had a text description:

In the example above the invisible button selected is a fox painting, but the button text in eko studio says “Choose Fox Painting” and that’s what someone will hear/read when someone uses ADA and might not be able to just choose based on visuals.

Image Buttons

TLDR: image buttons must have clear text names and context in eko studio

For image buttons, especially ones that have text, it’s important that the button name in eko studio has the text of what’s been baked inside the image alongside with any context it should give the user.

So here the image buttons are “Hands” and “UFO” for how you want to open the box in Wonder Lab, since the text is baked inside the image you need to make sure the button name matches that text (not case sensitive) and gives context (example: Open with Hands)

This also goes with icons, if you have a button that’s an icon be sure to describe what the icon is inside the button name:

In this case we put “pick barbie 1” “pick barbie 2” “pick barbie 3” for the text to describe the 3 different barbies you can choose, that way an ADA viewer could understand you have one of 3 barbies to choose from.

Button Roles

Similar to button roles in text if you use an image button but do not have it interactive you need to make sure it’s set to a “Graphic (No Action)” and the box checked “Graphic only” so it will not receive focus. You must describe what that eko studio image is in the name of the button, even if it’s not interactive so long as it is visible. However, you do not have to if it is invisible + non interactive (example: timer).

The sun icon is set to “Graphic(No Action)” AND the button name is set to “Sun Icon” to describe what the viewer would be seeing.

Image Contrast

Similar to the ADA contrast for text there is a description for large images and icons that must have a contrast ratio of 3.0:1 in these guidelines:

https://www.w3.org/WAI/WCAG21/Techniques/general/G17

So here’s an example that would not pass:

The shopping cart icon on the paw is nearly impossible to distinguish from the background video. This might mean having a drop shadow or very clear borders around your icons or making sure you have enough contrast. Again some great resources are on the link above but theres a program you can download and test images for contrast: https://developer.paciellogroup.com/resources/contrastanalyser/

Color Contrast

As seen in Text and Image buttons in general there needs to be contrast between interactive elements, texts, images, and other screen elements from the video content.

Be sure to follow https://www.w3.org/WAI/WCAG21/Techniques/general/G17 WCAG 2.1 requirements for color contrast that apply not only to text, but icons that are a part of interactive elements as well. Normal sized text must have a color contrast ratio of at least 4.5:1, while large text & icons must have a color contrast ratio of 3.0:1.

Button Presentation Order

When someone is using assistive technology the order to which the buttons appear might be important for your content. For instance if you take this screenshot here:

There is an image “Open the box” and two buttons “hands” and “UFO” that the viewer can choose.

To a viewer that might need assistive technology the logical order to receive this information would be to read the “open the box” first and then in general left to right for other information that is equal in importance. So in order of information it should go:

Open the box
Hands
U.F.O

To do this in eko studio you should have each button in order to the order you want the ADA viewer to experience them, in eko studio it goes from top to bottom for the order of tabbing:

So in this example the 1. Is the “Open the box!”, it should be on the top, then following in order from left to right on equal buttons that would mean “hands” should be the 2nd tab focus item, and “UFO” as 3. And when you test it, the order shows up as intended through tab focus!

Invisible Elements

If you are creating invisible elements in eko studio these will not receive focus by a screen reader and do not need to be renamed. In the example below you can see “4a choice” and “timer” which are not set to visible do not need to be renamed for ADA compliance.

Field Sets

Make sure that buttons are “grouped together” into a fieldset by naming the Node title.

If there are multiple fieldsets in one node then be sure to name buttons with additional context.

Looking at this mock example here, it would be best to name the button as “Approach with play” or “Explore guts” rather than simply “Play” or “Guts” that way the ADA viewer knows which choice moments are related to which.

Custom Buttons

Custom UI Buttons

While you can program your own buttons in our code, if decide to go custom with the look/animation/style of the buttons please be mindful to use the same ARIA custom tagging standards here: https://www.w3.org/WAI/standards-guidelines/aria/

This means making sure any buttons you make have the proper assigned roles, descriptions of what the button will do, and anything else to meet the ARIA ADA guidelines for AA.

Custom Eko shell buttons

Eko Shell has a fantastic dev resource: https://developer.eko.com/api/ekoshell.html

When you make a custom eko shell button it will also need an “alt text” or text description of what that new eko shell icon does for the viewer. To do this use the “label” and string you need to describe the button. Example below:

“customButtons”: [

{

“id”: “mute_on”,

“order”: 10,

“location”: “bottomRight”,

“icon”: “https://eko.com/volume-off.svg”,

“label”: “Mute video”

{

“id”: “mute_off”,

“order”: 10,

“location”: “false”,

“icon”: “https://eko.com//volume-on.svg”,

“label”: “Play sounds”

}

]

Hiding content in the code

Here are a couple of scenarios how to hide CSS/Code content from screen readers or hide the content but allow screen reader access:

Hidden from all users (sighted, assistive technologies, everything)

For this you want either “display: none;” or “visibility: hidden;”
- This will block content visually as well as to assistive technologies, but leave content in the DOM
aria-hidden=”true” (technically not CSS, but I’ll mention it anyway)
- This hides content from assistive technologies, but will not block items from receiving keyboard focus, which can create issues

e.g. a screen reader places focus on a button, but there is no content set to announce

Generally, best to avoid this if you intend to hide content for everyone (and rarely will you want to *just* hide content to assistive technologies) You want to avoid this so please use the techniques above to make sure a viewer doesn’t get confused by a focus state on something they cannot consume.

Hiding content visually (but providing it to screen reader users)

This would be for if you want to provide a textual alternative for something on-screen to ensure screen reader users have the context that is provided by the design

A classic example of this is a price reduction on a coupon

Usually we use two numbers close together, one with a cross-through on the older higher price: e.g. $100 $75

Screen readers may not render this text style difference, so we need to supply the information we’re presenting visually in some textual way, but don’t want to change the visual design (because that may be redundant)

For this, you would want to use what is generally called ‘offscreen text’
- There are a variety of ways to do this, but usually they involve ‘position: absolute;’
- From there you can do a lot of things, but ‘left: -99999px;’ is usually sufficient & keeps the changes to just 2 declarations.

Using Background CSS images

When making a custom background or using images in general please be sure to avoid using CSS image backgrounds because they will not be displayed in the DOM or tagged for someone using assistive technologies to experience. CSS background images will not be presented to screen reader users at all, and may be removed from the page by some users’ high contrast modes. All CSS background images of text should be converted to inline HTML text, and background image icons must be placed into the DOM As html img elements.

*Walmart has given us an exception to allow CSS background images in image buttons because it is so core to our product

ADA Compliant Example

<!– Inline Image Example ->

<!– Pseudo class example with CSS positioned text and CSS content images with the

before pseudo class–>

.error:before {

content: url(path/to/error.gif);

}

.error {

position: absolute;

clip:rect(1px,1px,1px,1px);

overflow:hidden;

width:1px;

height:1px;

}

</style>

<span class=”error”>Error</span>

Another Option

Place the image behind the background image. This works well when the image is not transparent. Note: the image must be set to the exact size.

</div>

div .BGimage {

width: 150px; height: 150px;

position: relative;

overflow: hidden

}

div . BGimage span {

background: url(“images/logo.jpg”);

position: absolute;

width: 150px;

height:150px;

}

Non-Compliant Example

.error {

background-image: url(path/to/error.gif);

}

</style>

…

Tab index

If you create an interactive button or element you want to make sure that it receives a “focus state” using the tab index guidelines. So that would mean setting up a button to be “tabindex=0” if the button is selectable, therefore a viewer can select it using the keyboard focusing.

Alternatively, if you make, say for instance, a UI element that is not selectable but informative to the information that needs to be displayed to the viewer. Let’s say a timer, or a score keeping or money tracking meter, you want to display this information but make sure it’s not tab-able so it has a focus state because it’s not selectable. To do this you want to make sure you set the ARIA role properly to something like “text” or “image” and make sure you set it’s “tabindex=-1” so it’s not selectable. Or you can post something like this in the code panel:

player.ui.override(‘buttonId’, null, { tabbable: false})

ARIA Roles

Noted upon earlier in Tab Index, when you make custom icons/UI for an eko project be sure to tag them with the proper ARIA roles, such as button/text/image etc. By default eko studio will put a “button” as the ARIA role but that also means it will get a tab index focus state which might not be appropriate for the element you are creating. For instance if you are putting a money meter and it’s being updated after every choice moment, the money meter is not interactive nor a button therefore it will need a proper role such as “image” or “text” and the tab index nullified so it cannot be focused via keyboard.

Please refer to these guidelines: https://www.w3.org/TR/wai-aria-practices-1.1/ for which role is best for the type of interactivity you are developing.

Unused elements not in DOM

Again any custom unused elements that are not in the DOM and do not need to be in the DOM be sure to hide them in the proper ways as outlined earlier in “Hiding Content in Code”

Video and Audio:

Closed Captions

It’s eko’s standard to include closed captions in the project, common closed captions are in the file format of .SRT, and eko is no different here. We recommend you use the same name as the video in the node to the SRT name, therefore know which SRT goes to which video.

SRTs should also be named to some standards, such as filename.en-US.srt so that “.en-US.srt” indicates the english language US delineation. If it were australian english that would be “en-AU.srt”

https://developer.eko.com/api/subtitles.html has more details about how to attach the SRTs to the video nodes and further guidelines will be in place soon when this becomes automated.

Audio Descriptions

Nearly identical to closed captions, Audio Descriptions are presented to the viewer in the same format of an SRT file that will be attached to a node in eko studio. This means for every 1 video node there needs to be 2 SRT files minimum: closed captions, and audio descriptions. Audio descriptions are a caption that describes what’s going on in the video as it’s happening. You could say it’s a more elaborate closed caption.

For all intents and purposes the procedure for closed captions is identical to audio descriptions, you should label them according to the language they are in and attach them to every node or follow up with eko on an automated process. But currently to implement Audio Descriptions look here for the dev subtitle/audio description practices.

Must be muted on first video node if autoplays

To meet ADA requirements you cannot have audio start without a viewer interaction. This means if you have the video autoplay wherever it might live, you will need to make sure the video is muted. This can be done in the project or in code, or inside the video itself. You could have your first video without any audio till the viewer hits a start button or customize your own play button and then the audio plays in the next video node.

So whichever solution you go with be sure to have the audio muted by default if you decide to have it autoplay in your experience.

*ADA vendors have noted that clicking on a “play button” on a video thumbnail could be sufficient compliance for viewer interaction and provides the user enough evidence to expect autoplaying video with audio only if users cannot get to the video any way where it would not give this experience.

The example above is ADA compliant where clicking the play button would autoplay the video full-screen and unmuted because it is expected by the user. Even so, always double check with Walmart to see if they will allow this as it really comes down to what is considered first interaction, what the user will expect, and how the user can get to the video.

How to Test YOUR project for ADA

Keyboard tabbing / Focus states

So when you are using ADA assistance technologies you might not have a mouse to navigate the project. So a great way to test if your show meets ADA compliance you can use the “TAB” button on a keyboard while watching a project and you can see what elements have a focus state:

So if you hold down the “TAB” button while viewing the project you can see what focus states are on the project. In this case the focus state is an invisible button over the video for the screw driver or hammer, then if you continue to tab you see the viewer goes to the pause button then the mute button, then fullscreen.

General rule of thumb:

If it’s interactive it needs a focus state. If it’s not interactive no need for a focus state unless it is text or image you want picked up by a screen reader.

So be sure to test your project to make sure you have the proper focus states for interactive elements. Please refer to the image buttons and text buttons to properly make sure you do this.

Audio descriptions

Audio descriptions should be easy to test when you get them in and implement them via our guidelines.

To test you need to enable subtitles on your eko project:

Checking that box and publishing the project will enable subtitles and audio descriptions, then if the SRT files are attached correctly you should see:

English Audio Descriptions as an option. And when you view them they should be the SRTs with audio descriptions in them: