Accessibility best practices for Shopify apps

When you build an app, make design choices that help keep content accessible. An accessible app is designed so that it can be used by everyone, including people who rely on assistive technology. Accessibility for your app is essential to providing an inclusive experience for app users and customers.

The accessibility best practices for Shopify apps were created with the Web Content Accessibility Guidelines (WCAG) in mind.

Anchor to Accessibility testingAccessibility testing

You can test the accessibility of your app by using tools such as:

• Accessibility Insights for Web
• Lighthouse
• WAVE

Anchor to Accessibility principlesAccessibility principles

When building your app, focus on the main principles of the WCAG 2.0 Guidelines:

• Perceivable: Information and UI components must be presentable to users in ways that they can perceive.

• Operable: UI components and navigation must be operable.

• Understandable: Information and the operation of the UI must be understandable.

• Robust: Content must be clear enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies.

  The following sections provide a list of accessibility best practices for how app users and customers interact with your app.

Anchor to Keyboard and gesture controlsKeyboard and gesture controls

App users and customers who have visual or motor impairments might use a keyboard to navigate and complete tasks online. These users rely on a visual indicator to communicate where their keyboard's focus is on a web page. Your app should allow for all links, buttons, dropdown navigation, and form controls to be controlled using a keyboard.

Anchor to Keyboard supportKeyboard support

• The focus indicator is visible and consistent on active elements. When navigating with either the mouse or the keyboard, the focus indicator is apparent on active elements.
• The focus style is visible on the desktop when using a keyboard.
• Your app doesn't rely on a mouse hover action to be visible or accessible.
• The Tab key and Shift + Tab keys can be used to navigate your app.
• No sudden changes of context when a part of your app receives focus. For example, when navigating with a keyboard, focus shouldn't switch to something else when a control receives focus.

Anchor to Gesture supportGesture support

• Zooming gestures, for example pinch to zoom, are always available.
• Any functionality that requires several fingers or complex gestures, for example navigating 3D models, should be available with a single tap or click.

Anchor to Page structurePage structure

The following sections provide best practices for specific elements of your app's page structure.

Anchor to GlobalGlobal

• The page lang attribute is set on the html element to help screen readers pronounce content in the correct accent and dialect.
• The viewport zoom is enabled. Your app shouldn't use the maximum-scale and user-scalable=no attributes.
• Skip link is available and visible when focused to provide quick access to page content by skipping past common content such as headers. Your app should include tabindex="-1" on the container for the main content to receive focus.
• The content flow is linear. Your app uses no tabindex attributes values other than 0 or -1 and no autofocus attribute. Positive tabindex values in use and autofocus take the power away from the user by forcing a specific focus order. Let the user discover page content organically.

Anchor to HeadingsHeadings

• The HTML heading elements use heading markup. Your app uses heading tags (h1 to h6) to communicate the organization of the content on the page.
• The heading tags are used in sequence. Your app shouldn't use headings for design but rather to set the logical order of content on the page.
• The h1 element is used to identify the main topic of a page.

Anchor to NavigationNavigation

• The navigation areas are wrapped with the nav HTML element.
• aria-current is used to communicate the current page when traversing links.
• role=menu or role=menuitem aren't used for navigation.

Anchor to Drop-down menu navigationDrop-down menu navigation

• aria-expanded is used to communicate the state of collapsible navigation.
• aria-controls is used to convey to assistive technology that there's a visually-hidden container that the drop-down menu controls.
• aria-current is used to communicate the current location or page when traversing navigation items.
• Enter and Space keys are supported to open the drop-down menu. Your app should keep focus on the launcher control. The Tab key moves focus to the first item in the drop-down menu.
• The Esc key is supported to collapse the drop-down menu and return focus to the launcher control.

Anchor to Product informationProduct information

• Product images include descriptive alt text.
• Sale and regular prices are marked differently, both visually and by using markup for screen readers. Your app should use visually-hidden text to help discern the regular price from the sales price.
• If your app dynamically changes a product price and availability when different variants are selected, then the changes should also be communicated to screen readers.
• aria-live is used to communicate dynamic changes in the UI.

Anchor to ControlsControls

• The a element is used for links. Your app should use links for navigation, loading a new page, or shifting keyboard focus from one element to another.
• The button element is used for on-screen actions such as launching a modal window and sorting a data table.
• The destination of your link should be clear from the text alone.
• Links that open a new window include a warning. Your app should include a visual icon with alternative text to help screen readers and sighted, keyboard-only users understand that clicking the link opens a new window.

Anchor to TablesTables

• The table element is used for tabular data.
• The caption element is used to help assistive technology identify that a table is being read.
• The th element is used for headers with scope attributes.
• The scope="col" element is used for column headers, and scope="row" for row headers.

Anchor to FormsForms

• All form fields include a label. Fields can use aria-label, the .visuallyhidden element, floating labels, or a visible label to label forms. Form inputs and controls have names that clearly state their purpose.
• Form inputs have labels with for attributes, including form labels in the app settings.
• Required inputs have the required attribute.
• Fields use the autocomplete attribute. Auto-complete helps people fill in form fields by using the data stored in their browser.

Anchor to Form errorsForm errors

• Focus is placed on the feedback message. Any errors returned as a result of completing or submitting a form are communicated to screen readers where possible and as soon as possible.
• Error messages are clear and descriptive.
• The aria-describedby attribute is applied to input elements which reference the error text container.
• Notifications, error messages, success messages are announced aloud. Critical information is announced by screen readers using aria-live.

Anchor to MediaMedia

Media can be distracting, disruptive, or unexpected. All the media in your app should adhere to the following best practices:

• Media controls should respect the user's prefers-reduced-motion browser setting.
• Media controls are marked up using native HTML elements. Make sure your app has a toggle state for buttons and range input for sliders.
• Media can be paused using the Space key.

Anchor to Images and iconsImages and icons

• All img elements should have an alt attribute. Without an alt attribute, screen readers announce the name and path of the image file.
• Product or content images feature alt text which describes the image for screen reader users.
• Decorative images use empty values for alt attributes. Use <img src="/content/assets/images/" alt="" /> to hide images and icons from screen readers.

Anchor to VideoVideo

• Closed captions are available.
• Descriptive audio is available.
• If an auto-playing video is required, including videos in slideshows, the sound is muted.
• Videos with audio aren't visually obstructed.
• The Space key can be used to pause and play the video.

Anchor to AudioAudio

• Transcripts are available.
• Auto-playing audio can be paused.

Anchor to Color and contrastColor and contrast

When you add colors to your app's UI, make sure that all of your text is accessible to app users and customers who are colorblind or have other visual impairments. These app users and customers rely on adequate color contrast to visually differentiate one thing from another.

You can use an online contrast ratio tool to check the contrast of the different parts of your app.

The content in your app should adhere to the best practices described in the WCAG 1.4.3: Contrast (Minimum) (Level AA) standards.

Anchor to Dynamic componentsDynamic components

Dynamic components such as slideshows, predictive search, modal windows, and tabs can be complex and difficult to navigate. Use elements that can be interpreted by screen readers, provide context, and include keyboard functionality.

Anchor to Drawers and modalsDrawers and modals

• When a drawer or modal is opened, focus is moved to the element that labels the drawer or modal.
• Navigating with the keyboard stays within the open drawer or modal.
• The Esc key is supported to close drawers and modals, and returns keyboard focus to the launcher element.
• The role used to identify modals is dialog.

Anchor to SlideshowsSlideshows

• Content that plays automatically in a slideshow can be paused or stopped.
• Content in a slideshow can be accessed through next and previous buttons.

Anchor to Touch screens and mobile devicesTouch screens and mobile devices

The main consideration for touch screens and mobile devices is to make sure that the app user or customer can easily change the orientation and tap the target to navigate the content.

Touch targets on primary controls and links need to be at least 44 by 44 pixels. Primary touch targets include controls and links such as:

• Main menu links (regardless if first or third level)
• Submit buttons for any forms, such as contact forms, comment forms, search, and add to cart
• Menu buttons for carts and for hamburger menus
• Close buttons for modals
• Product page variants and options, such as color, size, and quantity

Anchor to Next stepsNext steps

• Review the Polaris guidelines for accessibility.
• Learn how to design apps with keyboard accessibility in mind.