accessibility

44 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Always announce results of user actions

Announcements about the success or failure of user actions must always be provided directly following a user action to assistive technology. This gives users feedback about whether their action succeeded or failed.

Sometimes announce other changes

Changes that are disconnected from the user's location or the success or failure of their actions should be evaluated case-by-case for announcement to assistive technology. Distracting change announcements include when other users add issue comments or when presence indicators appear. Essential change announcements include when log lines stream in on the GitHub Actions workflow run page.

Always announce location changes

Location changes on a page must always be announced to assistive technology. This helps users understand where they are on a page and maintains positional awareness.

GitHub's accessibility philosophy

GitHub's aim is to be the home for all developers. To be inclusive means accessibility must be considered at the core of how GitHub designs. When accessibility is considered from the beginning of the design process and incorporated throughout, it becomes part of an established design process that seeks to include everyone of all abilities.

World population with disabilities

Approximately 16% of the world's population has a disability according to the World Health Organization. This figure does not include those with temporary or situational disabilities.

Disability categories for accessible design

When designing for accessibility, consider four main disability categories: Visual (sight and color blindness), Cognitive (concentration, memory, judgement, problem solving, logic skills), Mobility (anything affecting body movement), and Hearing (sound and audio disabilities). Each category includes permanent disabilities (do not go away, e.g., someone who is deaf), temporary disabilities (will go away in time, e.g., someone with an ear infection), and situational disabilities (affected by environment, e.g., someone at a loud sporting event).

GitHub accessibility compliance standard

GitHub aims for Web Content Accessibility Guidelines (WCAG) 2.1 AA compliance. This includes all of WCAG 2.0 AA plus additional considerations. Section 508, which is required by law in the United States, follows WCAG 2.0 AA guidelines for compliance.

a11y abbreviation meaning

a11y is a shortening of the word 'accessibility'. It starts with the first letter 'a', uses the number 11 for the eleven characters between the first and last letter, and ends with the last letter 'y'.

WCAG terminology: label vs name

A label is text or other component presented to a user to identify a component. A name is text by which software can identify a component to the user. The name may be hidden and only exposed by assistive technology, whereas a label is presented to all users. In many cases, the label and the name are the same.

Related WCAG success criteria for button accessibility

Relevant WCAG criteria: SC 1.3.6 (Identify Purpose), SC 2.4.4 (Link Purpose In Context), SC 2.4.9 (Link Purpose Link Only), SC 2.5.3 (Label in Name), SC 3.2.4 (Consistent Identification), and SC 4.1.2 (Name, Role, Value).

Keyboard accessibility for all interactive elements

All interactive elements must be accessed and activated by keyboard alone per WCAG 2.1 Keyboard Accessible. Tabbing is used to access standalone controls (buttons, links, widgets), and arrow keys are used to navigate within composite controls (groups of standalone controls or lists of checkboxes). Focus must be visible for all interactive elements. Do not rely on keyboard shortcuts as the only alternative to mouse actions because some assistive technologies have keyboard combinations that override those of a web page.

Accessible design must start at design phase not after implementation

Tacking on accessibility after a design is implemented costs businesses time and money, and muddies the original design, leading to poor user experience for people with and without disabilities. Accessible experiences start with designers, and when accessibility is considered from the beginning, design works for everyone from the start.

Feature accessibility checklist

When designing a feature or experience in GitHub, use this checklist: Have you annotated the headings on your feature? Have you defined the focus/tabbing order on your feature? Have you added screen reader labels for elements that are not focusable (dynamic content changes, images and their alt text)? If this is a new page outside the GitHub monolith, are the landmarks annotated? Does the text meet color contrast? Do graphic objects meet color contrast? With color removed, can you still understand the design? Can all revealable information (hover card, tooltips, accordions) be accessed with a keyboard or a mouse? If the user increases the text size to 200%, is the page still usable? When the screen reduces in size (down to 320px wide), is everything usable without scrolling horizontally?

Link text must be meaningful and unique

Assistive technology users frequently browse a list of links for easy navigation. Link text must be meaningful and unique, with as few duplicated references as possible to prevent confusion. Links like 'click here' do not indicate purpose to users.

Form inputs must have visible labels

All form inputs must have a visible label. Do not use placeholder text for titles, hints, or other important information. Visible labels determine the purpose for inputs and allow screen readers to read this information without extra code. If placeholder text contains important information that disappears when typing, users with cognitive disabilities will have difficulty completing the form.

Tooltip accessibility requirements

Tooltips and hover cards must be dismissible without moving the pointer or keyboard focus unless the tooltip is an input error or does not cover other content. Pointer must be able to move over hover content without it disappearing. The tooltip must not dismiss itself without user action.

Text must remain usable when increased to 200% size

People using the web must be able to increase font size to 200% without losing content or functionality. For AAA guidelines, text width should not exceed 80 characters or glyphs and text should not be justified.

Browser zoom support requirement

It is best practice for pages to be readable with both full-page zoom and text-only zoom. Modern browsers support full-page zoom, while some browsers like Firefox also support text-only zoom.

Text resize requirement: 200% browser zoom

Test pages by using browser zoom with magnification of up to 200%. Confirm that text content does not overflow, overlap, or become truncated, and that interactive controls still work.

Text spacing WCAG testing

Modify text spacing according to WCAG text spacing testing guidelines. You can change CSS using the browser inspector or use a tool like the Steve Faulkner text spacing bookmarklet. Confirm that text is contained within the bounds of its container without overlapping or being cut off.

Design annotation for text resizing

When creating a design, ensure that font sizes and element sizes are annotated with proper resizing techniques before handing off to an engineer.

Avoid fixed height on text containers

Do not use fixed height on text content containers, as fixed height causes text to overflow out of bounds when text is resized.

Use relative units instead of px

Use relative units such as em and rem instead of px for font sizes and element sizes to ensure responsive text and space resizing.

Text must not be clipped, truncated, or obscured on resize

Users should be able to resize text and use custom text spacing without text being clipped, truncated, or obscured. Interactive controls should not break.

Label element best practice for inputs

The label must use the label element with a for attribute that references an id declared on the associated input.

Placeholder color should use design tokens

The placeholder color value should be controlled by a design token to ensure it visually renders appropriately across different themes.

Placeholders best practice for designers

Use techniques like explanatory paragraphs and input captions to explain content in a way that is always visually persistent. Ensure a visible label for the input is utilized, with a concise, descriptive name that communicates the input's purpose.

Placeholder contrast and visual ambiguity problem

Placeholders are typically styled with light text to visually indicate they are suggestions, not pre-filled input. However, light placeholder text often fails color contrast compliance requirements. If the placeholder color is darkened to meet contrast compliance, it risks being visually interpreted as pre-filled input instead of a hint.

Placeholders accessibility best practice

Avoid using placeholders if at all possible. Instead, use a caption to communicate hint information. If you must use a placeholder, ensure the input also has a concise, descriptive label.

Placeholder disappears on input activation

When a user activates an input that has a placeholder, the placeholder text disappears. If the placeholder contains important information such as formatting requirements, the user can no longer reference it. A caption, which is always visible to the user, avoids this problem.

Placeholder text truncation issue

Placeholder length is constrained by the width of the input. Important information may be truncated, especially if the user relies on an increased font size for readability.

Placeholder cannot contain interactive content

Placeholder information cannot contain interactive elements such as support links or buttons that trigger tooltips. A caption can contain these pieces of information, making captions more flexible for communicating complex requirements.

Placeholder role in accessible name computation

The placeholder attribute can factor into accessible name computation if a programmatically associated label element does not accompany the input. Although placeholder is not intended to be used this way, some assistive technology may use placeholder content as a last-resort technique to determine the input's purpose. This can be confusing if the placeholder does not communicate the input's actual purpose, such as when it only states formatting rules like 'No numbers or special characters'.

Annotate tooltips with semantic type

If you have an appropriate tooltip in your design, annotate the tooltip carefully with the preferred type, whether it is a label or description, to ensure proper semantics.

Tooltips should be avoided by default

Tooltips are rarely appropriate and their misuse can result in accessibility issues. Always consider not using a tooltip for an improved user experience.

Why tooltips are problematic

Tooltips are hidden by default making it easy to miss, so they should never be used to convey critical information. Tooltips are never accessible on mobile devices. Tooltips should never be set on non-interactive elements like div, span, or p, and should only be set on interactive elements like button or a. Tooltips on non-interactive elements are not accessible to keyboard users and screen reader users.

When tooltips are acceptable

Reserve tooltips for components like icon buttons. Tooltips should only be included on other components as a last resort.

Tooltip text should be minimal

Keep your tooltip text minimal to ensure clarity and accessibility.

Never use tooltips on non-interactive elements

Do not include tooltips on non-interactive components such as div, span, or p elements.

Developer action for tooltips on static elements

If you come across a design or a page with a tooltip on a static element such as div, span, or p, remove it and consult a designer for an alternative way of conveying the information.

Accessibility as core principle

Accessibility and inclusive design needs to be considered from the start of a project, because it deeply affects its design, how the product behaves, and how it's built. Adding accessibility support to a design after the fact generally turns into a difficult retrofit.

Responsive design as accessibility requirement

Making sure pages work well on most screen sizes or zoom levels is an accessibility requirement as well. Primer uses the term "Responsive design" to refer to design decisions that are adapted to device form factors and user preferences.

Give your agent this brain