Engineering Best Practices

CircleCI

CSS

Design

Introduction

Explore

Accessibility

Oliver Harrison

Last edited 158 days ago by System Writer

At Kanopi we aim to meet the requirements for Level AA from the

WCAG 2.1 Guidelines⁠

while also looking ahead to what standards will be included in the next version.

While the official document is comprehensive and well documented, the

quick reference guide from W3C⁠

is a lot easier to parse, search, and filter, and will be referenced here in this document. It’s also

summarized later in this document⁠

⁠

Principle 1 -
`Perceivable`⁠
⁠

Provide text alternatives for all content that relies on visual context

Menu buttons, close buttons, shopping cart icons, charts, etc.

⁠

More About Links⁠

⁠

1.1.1 Non-text Content - Level A⁠

⁠

All image elements must have the alt attribute, no exceptions

<img src="#" alt /> and <img src="#" alt="" /> are acceptable.

⁠

More About Images⁠

⁠

1.1.1 Non-text Content - Level A⁠

⁠

Videos and audio files require captions or transcripts in order to present a text alternative for that media.

Auto captioning is acceptable.

⁠

More About Video & Audio⁠

⁠

1.2.1 Audio-only and Video-only (Prerecorded) - Level A⁠

⁠

1.2.2 Captions (Prerecorded) - Level A⁠

⁠

Use semantic HTML wherever possible.

Use HTML5 elements and landmarks

Add ARIA where relationships are unclear

⁠

More About Landmarks⁠

⁠

More About ARIA⁠

⁠

1.2.1 Info and Relationships - Level A⁠

⁠

Organize pages with headings

⁠

More About Headings⁠

⁠

1.2.1 Info and Relationships - Level A⁠

⁠

DOM order should match the visual order

Exceptions can be made, but only if the result is not confusing visually or audibly.

⁠

1.3.2 Meaningful sequence - Level A⁠

⁠

Do not indicate purpose solely with color.

Links must have another visual indicator (icons, underlines, backgrounds, design elements, placement)

If colors were removed, information should not be lost.

⁠

1.4.1 Use of Color - Level A⁠

⁠

Text requires a contrast ratio of 4.5:1

Text larger than 24px, or 19-23px that is bold, only need to meet 3:1

Graphic elements (such as icons, checkboxes, etc) need to meet 3:1

⁠

Contrast Checker⁠

⁠

1.4.3 Contrast (Minimum) - Level AA⁠

⁠

1.4.11 Non-text Contrast - Level AA⁠

⁠

Test your work at zoom 200%. You must still be able to read the content and use the site.

Do not disable zooming for any reason.

Use rem or % for font sizes to ensure they obey browser settings.

⁠

1.4.4 Resize text - Level AA⁠

⁠

Do not use images of text.

If images of text are required, that content must also be provided in an alternative text format.

Logos are exempt from this rule.

⁠

1.4.5 Images of Text - Level AA⁠

⁠

Do not justify text.

Though this is a Level AAA item, it is a practice Kanopi follows.

⁠

1.4.8 Visual Presentation - Level AAA⁠

⁠

Line spacing must be a minimum of 1.5 for body text.

Though this is a Level AAA item, it is a practice Kanopi follows.

⁠

1.4.8 Visual Presentation - Level AAA⁠

⁠

Build responsively. Check your work at all viewports from 320px and up.

⁠

1.4.10 Reflow - Level AA⁠

⁠

Line-height must use no measurements, or it must use rems (by default line-height uses rem).

User must be able to change site line-heights and still be able to view and use all content.

⁠

1.4.12 Text Spacing - Level AA⁠

⁠

Principle 2 -
`Operable`⁠
⁠

All site functionality must be operable through a keyboard interface.

Menu buttons, close buttons, links, sliders, tabs, accordions, etc.

⁠

More About Keyboard Testing⁠

⁠

2.1.1 Keyboard - Level A⁠

⁠

Do not trap a user via keyboard.

⁠

More About Keyboard Testing⁠

⁠

2.1.2 No Keyboard Trap - Level A⁠

⁠

Videos, audio, gifs, moving, or auto scrolling content must include Pause, Stop, Hide controls.

⁠

More About Video & Audio⁠

⁠

More About Motion & Animation⁠

⁠

2.2.2 Pause, Stop, Hide - Level A

Do not design content in a way that is known to cause seizures or physical reactions.

Includes videos and gifs.

⁠

More About Motion & Animation⁠

⁠

2.3.1 Three Flashes or Below Threshold - Level A⁠

⁠

Add a “skip to” link that bypasses the header and goes straight to the main content.

⁠

More About Landmarks⁠

⁠

2.4.1 Bypass Blocks - Level A⁠

⁠

Webpages must have titles that accurately describe the purpose of the page.

⁠

2.4.2 Page Titled - Level A⁠

⁠

Focus order should be sequential and logical.

Exceptions can be made, but only if the result is not confusing.

⁠

More About Keyboard Testing⁠

⁠

2.4.3 Focus Order - Level A⁠

⁠

All links must have textual content that indicates where the link goes.

“Read More” / “Learn More” are not appropriate link names on their own.

Screen reader text can be added to most links to provide article titles, or other context about the destination.

Images used as links must use their alt text to identify the destination of the link.

⁠

More About Links⁠

⁠

2.4.4 Link Purpose (In Context) - Level A⁠

⁠

Do not misuse headings to achieve a design.

Headings are meant to describe a topic or a purpose, not as an application of style.

⁠

More About Headings⁠

⁠

2.4.6 Headings and Labels - Level AA⁠

⁠

The keyboard focus must be visible.

Focus status should not be subtle changes. The outline property is well known and easily identified.

Do not disable the default focus styles if you do not intend to replace them.

⁠

More About Keyboard Testing⁠

⁠

2.4.7 Focus Visible - Level AA⁠

⁠

Use section headings appropriately.

Headings should be used

sequentially⁠

Though this is a Level AAA item, it is a practice Kanopi follows.

⁠

More About Headings⁠

⁠

2.4.10 Section Headings - Level AAA⁠

⁠

Ensure target sizes on mobile are easy to tap.

Target size is at least 44px by 44px.

Does not apply to inline links and typically does not apply to navigation lists.

Though this is a Level AAA item, it is a practice Kanopi follows.

⁠

2.5.5 Target Size - Level AAA⁠

⁠

Principle 3 -
`Understandable`⁠
⁠

All pages must have a language code.

Sections of content that is presented in another language must also identify the language used.

⁠

3.1.1 Language of Page - Level A⁠

⁠

3.1.2 Language of Parts - Level AA⁠

⁠

Form inputs must include textual error messages.

⁠

More About Forms⁠

⁠

3.3.1 Error Identification - Level A⁠

⁠

Form inputs must include labels or instructions.

⁠

More About Forms⁠

⁠

3.3.2 Labels or Instructions - Level A⁠

⁠

Principle 4 -
`Robust`⁠
⁠

Do not leave broken tags or stray tags.

⁠

4.1.1 Parsing - Level A⁠

⁠

Elements must be nested according to their specifications.

Do not put a <div> inside a <p> or an <a> inside an <a>

If you are unfamiliar with valid HTML, please reach out to your manager for training.

⁠

4.1.1 Parsing - Level A⁠

⁠

Do not duplicate IDs within a page.

IDs must be unique. Use a class instead if the element will be duplicated on a page.

⁠

4.1.1 Parsing - Level A⁠

⁠

Use a keyboard to operate all components of the site

Also check focus order and focus states

⁠

More About Keyboard Testing⁠

⁠

Zoom to 200%

Repeat keyboard testing

Ensure all content is still readable and usable

Automated Scans

⁠

aXe⁠

- Required

⁠

Site Improve’s browser extension⁠

- Recommended

⁠

WAVE⁠

- Recommended

⁠

More About the Auditing Tools⁠

⁠

Check uncertain color combinations with a

contrast checker⁠

⁠

If text appears overtop of an image, sample the color closest in hue to the color of the text and run it through the checker. If it fails, then you need to change the color of the text, or add an overlay to the image, or both.

Manual review

Images do not contain text

Images have appropriate alt text

Headings are used sequentially

Hover states exist

Site is responsive and reflows properly from 320px and up

Screen Reader Testing

Alternatively, your developer tools will give you access to the accessibility tree which will give you an indication of what content is being passed through to assistive technology.

⁠

More About Screen Readers⁠

⁠

Ally Teaching & Learning is a monthly session Kanopians can attend to talk through accessibility concepts and guidelines. You can find all of

our sesson documents here⁠

, or search for the term “

Accessibility⁠

”. Some intranet documents include session videos.

There are 4 specific aspects of the WCAG guidelines and they are defined by the acronym “POUR”. This is a general summary of what you can find in each area.

⁠

⁠
`1 Perceivable:`⁠
⁠

Everything in the 1 point rule set has to do with an individual’s ability to perceive the content. It’s broken out into four areas.

1.1 - Text Alternatives.

Could someone perceive this content if they were unable to see it?

Can a machine without eyes understand this content? That’s how assistive technologies work.

1.2 - Time-based Media.

Can anyone, regardless of ability or disability, consume your media?

What if they can only see?

What if they can only hear?

What if they can do neither and depend on assistive technology to interpret content in another manner such as Braille?

What if they have motor difficulties that prevent them from using the interface quickly?

1.3 Adaptable

Do users need to meet specific requirements in order to perceive your page and its content?

Can content be perceived and understood with changes to screen size?

Does content make sense in the order it’s presented? Is its purpose clear programatically?

1.4 Distinguishable

Is the presentation clear and understandable?

Is content easily identified without needing context clues like color?

Does the design interfere with the ability to consume content?

Does anything interfere with the user’s ability to use the whole page? (For example, an autoplay video or audio file would be considered an interference).

⁠

⁠
`2 Operable:`⁠
⁠

Everything in the 2 point rule set has to do with an individual’s ability to operate the page. It’s broken out into five areas.

2.1 - Keyboard Accessible

Can a user operate this page with just a keyboard?

Can all of the links and interactive elements be reached and activated via keyboard?

This is critical because many assistive technologies operate with keyboard interactions.

2.2 - Enough Time

Does the user have the time to operate the page?

Are there timed interactions?

Are there elements that cause interruptions?

Can users control media so that they can consume it at their leisure?

2.3 - Seizures and Physical Reactions

Does this site follow good practices to prevent experiences that are known to cause seizures?

2.4 - Navigable

Can the user move around the page in a logical manner?

Is link purpose clear?

Does the content have appropriate headings and labels?

2.5 - Input Modalities

Are target/tap sizes appropriate?

Are target/tap areas too close together?

Does the site rely on swipes or gestures to complete actions and tasks?

Are there alternatives present?

⁠

⁠
`3 Understandable:`⁠
⁠

Everything in the 3 point rule set has to do with an individual’s ability to understand the page. It’s broken out into three areas.

3.1 - Readable

Is the language programmatically determined?

Is the content understandable without additional context?

Are there mechanisms for identifying the definitions of abbreviations, industry jargon, idioms, etc?

Is the reading level appropriate?

Is meaning ambiguous without knowing pronunciation?

3.2 - Predictable

Does the page conform to a standard web experience?

Does focusing an element or using an input field produce typical expected behaviour?

Is navigation consistent from page to page?

Are components with the same functionality identified consistently throughout the site?

Are changes of context appropriately managed?

3.3 - Input Assistance

Are input errors easily identified and described to the user?

Are inputs accompanied by labels and, when appropriate, instructions?

Do errors include suggestions for correction?

When collecting legal information, does the user have the ability to correct and review their submissions?

⁠

⁠
`4 Robust:`⁠
⁠

Everything in the 4 point rule set has to do with a device’s ability to understand the page. It’s broken out into one area.

4.1 - Compatible

Is the site compatible with current user agents (browsers, operating systems, assistive technologies)?

Will the site be compatible with future user agents (browsers, operating systems, assistive technologies)?

Do all interface-able components provide enough information that their name and role can be programmatically determined?

When states, properties, or values are changed, is that change made available to user agents?

Are status messages presented to the user without requiring focus?

Images make up a good portion of a website’s design and content, but aren’t accessible to users with low or no vision. How do we make sure they get conveyed to users of assistive technology?

When do they need the “alt” attribute?

Always. This can’t be understated. If you are using <img> or <svg>, then you need the alt attribute. This is to create valid HTML and also passes important info about the image to assistive technologies.

These are all valid html:

Images that are applied via CSS cannot be given the alt attribute. If your image is important for conveying meaning to a user, you need to find an alternative method for providing that context, perhaps through a caption or hidden screen reader text.

What happens if the image has no alt attribute?

If your image has no alt attribute, then the image name will be presented instead.

img_NCBI-macbook-1x-1-743x475

Kanopi-Icon-Confused-Editor-Trimmed

logo-phr@2x-grey

iStock_Civic-425x275

When does the alt tag need to be filled in?

Only if the image is not classified as decorative.

Decorative images could be:

Background designs like dots, arrows, swoops

Icons that accompany visual labels

Lines, shapes, other items that frame headings or other content

Images that are important enough to present to a sighted user are important enough to present to a user with reduced vision.

What about Icons?

If an icon is use decoratively - that is to enhance a label - then they do not need alt text, just the alt attribute. Or if they’re applied via css, then they do not need any sort of attribute.

Icons that sit alone and have no associated label, or add additional context to a label, need to have alt text. A good rule of thumb is if this icon was missing, is context lost? If so, then it needs additional information.

For example:

A phone icon next to a phone number would be fine with an empty attribute.

An icon of a shopping cart with no label would need alt text.

What about when the image is also a link?

This is very common with social media links, or logos. In this case, the alt text of the image should reflect the purpose of the link, not the image.

What makes a good alt tag?

That is a good question and up for debate. There are a couple ways to approach them:

A literal description of the image.

“Smiling Asian woman sitting on a blue couch using a tablet.”

The intended meaning of the image.

Woman happily working from home on her iPad."

Those could both be used to describe the same image, one gives you a better idea of what the image is of, the other a description of the emotion the image is meant to convey. Which is better? That’s the debate. At the end of the day, make sure that users with or without vision understand the same thing.

Landmarks are HTML elements that assistive technology can detect and navigate by. They are extremely useful when used correctly, and can cause confusion when they aren’t.

Your document should follow this structure:

<html>

<body>

<a href="#main">Skip To Main Content</a>

</body>

</html>

All of your content should be inside the <header>, <main>, or <footer>. The primary exception to this rule is the Skip To Link can be outside of these landmarks (this is recommended by Deque, the providers of aXe). The other exception is that <aside> can exist at this same level, however it can also be used within <main> and that is preferable.

Cookie notices are typically added via third party javascript and are placed after the footer. This is outside our control and not a large concern.

⁠