Requirements for alt text content
Alt text should help visitors navigate the site, provide an inclusive experience, be as short and specific as possible, and be contextual to the intended message.
Shopify Polaris · all subjects
accessibility
114 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Alt text definition and purpose
Alt text is a text replacement for an image, represented by the alt HTML element attribute alt="alt text". It is used by people who are blind or have low vision through screen readers, which announce alt text to explain images. Alt text also displays when images fail to download due to unstable or low-bandwidth network connections.
All img tags must have alt attribute
All <img> tags need an alt text attribute, even if it is empty. If an image does not convey meaningful information, set the alt to an empty string to let the screen reader know to ignore the image, otherwise the screen reader may try to read the filename and create a negative experience. Use the format <img alt="" />.
Write alt text in plain text
Alt text should always be written in plain text. The average rate of listening to a screen reader is 3x slower than that of an average visual reader. Many screen reader users listen at fast speeds to make up time.
Alt text writing guidelines: conciseness
Be concise when writing alt text. Think about how to write for a small amount of space or a character limit.
Alt text writing guidelines: word choice
Use simple words in alt text. If you are unsure how to replace a complicated word, check the A-Z list of alternative words at plainenglish.co.uk, plain language tips, or the Hemingway editor.
Alt text writing guidelines: remove filler words
Avoid needless words in alt text. Remove articles like 'a, an, one of' whenever possible. Alt text has different grammatical rules from speech, and filler words that assist understanding in speech can get in the way in alt text.
Alt text writing guidelines: avoid descriptors
Avoid using 'image of' or 'photograph' in alt text unless the type of image is relevant to the context, since screen readers already announce images with use of the <img> attribute.
Alt text writing guidelines: punctuation and emoji
Avoid punctuation like !! and emoji like 🥰 in alt text. Screen readers will announce these as 'exclamation point, exclamation point' and 'smiling face with three hearts'. Use other punctuation marks as you regularly would, such as commas or periods at the ends of sentences, which the screen reader will react to with a brief pause.
Alt text writing guidelines: acronyms
Only use acronyms in alt text that you are confident your audience will understand. If using an acronym, write it with spaces in-between, like 'Y M C A'. Otherwise, most screen readers will try to read the acronym as a word.
Alt text writing guidelines: active voice
Write in the active voice when possible in alt text.
Determining whether an image needs alt text
To decide whether an image needs alt text or should be ignored by screen readers, ask yourself: Is it interactive? Does this image convey information that isn't given elsewhere? Does the context of the image communicate anything? The same image may have different alt text depending on what it conveys.
Alt text for icons
Icons that could be misinterpreted need an explanation using the Polaris accessibilityLabel prop or the aria-label HTML attribute. For interactive icons, describe the action rather than the image. For example, describe a magnifying glass icon as 'search' rather than 'magnifying glass'.
Alt text for interactive icons example
For interactive icon buttons, place an empty accessibilityLabel on the icon itself and put the meaningful label on the button. Example: <Button accessibilityLabel="search" onClick={() => search()}><Icon source={SearchIcon} accessibilityLabel="" /></Button>
Alt text for action links
Write clear and predictable link text. If space constraints require writing calls to action that are unclear where they take you (like 'Learn more' and 'Apply now'), give further indication of where merchants will be sent after they select using the accessibilityLabel prop.
Alt text for action links example
Example of providing context for unclear link text: <Link url="https://www.shopify.com/protect" accessibilityLabel="Learn more about Fraud Protect">Learn more</Link>
Alt text for complex images
Images with more complexity can be described by a single text rather than announcing each individual element. Groups of image elements should use role="img" with aria-labelledby to reference a single descriptive element.
Alt text for complex images example
For a star rating display with multiple icons, use: <div role="img" aria-labelledby="star_id"><LegacyStack><Icon source={StarFilledIcon} alt=""><Icon source={StarFilledIcon} alt=""><Icon source={StarFilledIcon} alt=""><Icon source={StarIcon} alt=""><Icon source={StarIcon} alt=""></LegacyStack></div><div id="star_id">3 of 5 stars</div>
Situations that don't need alt text: progress bars
Progress bars often present visual information that can also be found in the text, such as 'Loading 53%'. Continuously announcing that change is generally considered annoying, so set alt="" for progress bars.
Situations that don't need alt text: decorative elements
Decorative elements that are purely for aesthetic reasons, such as empty state illustrations, dividers, or hero images, should have empty alt text. If unsure whether valuable information is lost, consider testing with people who regularly use a screen reader.
Situations that don't need alt text: images with captions
Avoid adding repetitive alt text if an image has a caption that accurately reflects the information in the image. If the image presents information not in the caption, consider adding it to the caption text. Only if this is not possible or appropriate should you add that information as alt text. If the image has a longer description in the caption or following paragraph text, use the aria-describedby attribute to associate this description with the image.
Situations that don't need alt text: tracking images
Images that would not be visible to a sighted user should not be announced to screen readers, so set these to empty alt text.
Language attribute for pronunciation and translation
Always state the language of the page content with the HTML lang attribute. This ensures pronunciation and translation tools know what rules to use. If certain phrases are in a different language than the main content, you can also use the lang attribute in a <p> tag or similar.
Language attribute examples
Examples of proper language attribute usage: <html lang="en"></html>, <html lang="de"></html>, <html lang="pt-BR"></html>. Do not use <html></html> without a lang attribute.
Alt text for SEO purposes
Alt text helps increase image ranking results and site searchability outside of Shopify's admin. When accounting for SEO in alt text, use logical keywords that people search for and include relevant listing details like limited edition or unique colorway. Describe the image, not what you want your audience to think.
Alt text SEO guidelines: avoid keyword stuffing
Do not repeat your site name or brand name in alt text, as search engines will already associate your site with your images. Never include unassociated lists of keywords in the alt text; place those in your meta description instead. Avoid reducing the relevance or clarity of the alt text just to insert a keyword.
Alt text SEO example: good
Example of good alt text for SEO: <Thumbnail alt="1460 Boot Limited Edition Oxblood Women's" />
Alt text SEO example: poor
Examples of poor alt text for SEO: <Thumbnail alt="shoes sneakers womens footwear girls sizes soles heels boots" /> or <Thumbnail alt="Cool shoes for a night out or hot date" />. The first is keyword stuffing and the second describes what you want the audience to think rather than describing the image.
Components with alt text props
The following Polaris components include props to set alt text or aria labels: Avatar, Button, Icon, Link, Thumbnail, and Video Thumbnail.
Color relationships ensure consistent contrast and accessibility
Polaris uses consistent color palettes for each color role. Each color is assigned a specific relationship within the overall palette. These color relationships ensure that color contrasts remain consistent across every application of color and ensure proper legibility and understanding when combining text with color and interactive shapes with various backgrounds.
Color combinations must pass AA and AAA accessibility contrast standards
Colors are assigned relationships within palettes to ensure sufficient contrast, making things easier to find, identify, and interact with. Color combinations used for various elements in Polaris must pass AA and AAA accessibility standards for contrast.
Do: use color in conjunction with other discernible elements
Color should be used in conjunction with other discernible elements such as icons or text labels to amplify the message.
Don't: use color alone to convey meaning
Color should not be used alone to convey meaning. It must be accompanied by other visual or textual elements to ensure accessibility for all users.
Input devices to consider for interaction states
When designing interaction states, consider merchants using mouse, touch screen, keyboard, voice, game controller, or refreshable braille display.
Polaris accessibility mission and scope
Polaris aims to make commerce better for everyone by creating quality products with fantastic user experiences. Accessibility means caring deeply about this goal and includes beautiful functional design, consistent and useful copy, and principles of universal design and inclusivity. Polaris products should be usable and useful to merchants, their customers, developer partners, employees, and the greater tech community, including all members with disabilities.
Disability prevalence statistics
In the United States, as many as 1 in 4 adults has at least 1 disability. In Canada, the estimate is 22%. Elsewhere in the world, the estimate is closer to 1 in 7.
How components improve accessibility
Using Polaris components improves accessibility and consistency when building products. The component library includes accessible markup. Since the code exists in a single reusable component, it is easier to update and fix bugs. The build-it-once, use-it-everywhere model means the accessibility knowledge of designers and developers who build components is available to all of Shopify and partners, resulting in merchants getting a consistent experience that can be leveraged into accessible products. However, it is important to ensure components are integrated in a way that does not create unforeseen accessibility barriers, and user task flows should be tested post-integration.
Focus management rules for merchant workflows
Do not programmatically move focus to new content without merchant input. Move focus in these cases: when a merchant activates a link that goes elsewhere on the page, move focus to that content; when a merchant must access an overlay, move focus to it; when a merchant submits a form that results in an error, move focus to the error message. Do not move focus when content updates in the background or when the user is actively working elsewhere on the page. The only exception is when the merchant needs to be interrupted because they cannot continue their current workflow. Polaris components that use controls to display overlays, such as modals and popovers, manage focus automatically.
Non-standard interactions and keyboard expectations
Merchants expect to interact with controls and content in ways that follow defaults for their browser, platform, and assistive technologies. Merchants who rely on the keyboard expect buttons to be activated with the enter/return key or the space key. Before designing or building custom features that use non-standard controls or interactions, first consider whether the goal can be met using native features. If non-standard interactions are required, carefully follow guidelines and best practices for designing, building, and testing custom features on your platform, give merchants clear instructions for using the custom feature, and provide an additional standard way to accomplish the task.
Assistive technologies supported by Polaris
Polaris components are tested for accessibility with automated and manual techniques. Merchants should expect to be able to access features built with Polaris components using modern assistive technologies. These include native and third-party tools such as screen readers, speech recognition programs, supports for low vision and color blindness, alternative keyboards, switch devices, and tools for readability.
Web standards and ARIA in Polaris
Polaris components start with web standards for HTML, CSS, and JavaScript. Features from the Accessible Rich Internet Applications (WAI-ARIA or ARIA) specification are used to build functionality that is not available in native HTML.
Alternative text for assistive technologies
To help people who rely on assistive technologies such as screen readers or text to speech programs, Polaris components use alternative text for icons and images used to convey information and actions, like buttons and links.
WCAG compliance target
Polaris targets WCAG 2.1 Level A and Level AA success criteria, and seeks to provide a highly usable experience for everyone.
Avoid placeholder text in text fields
Placeholder text should generally be avoided in text fields due to accessibility problems including low color contrast making text hard to read, inconsistent behavior between browsers and screen readers, text disappearing when the user starts typing which can confuse people with cognitive impairments, and limited space available for additional context due to field size.
Accessible search field placeholder behavior
To make search, filter, and email entry fields more accessible, always move the placeholder text above the cursor while the field is in focus. This lets the user read the placeholder text as soon as they select the field.
Hover functionality must also work on focus
Whatever happens on hover should also happen on focus. This includes both styles and JavaScript functionality.
Clear error states with next steps required
Do not make users guess what to do next when it comes to forms. Have clear, informative error states that detail next steps.
Manual keyboard and screen reader testing recommended
Manually test pages with keyboard only and fire up a screen reader to test for yourself. Automated tools are useful for catching trends and low-hanging fruit but manual testing is the best approach.
WCAG 2.1 is the current accessibility standard
WCAG 2.1 is the current W3C recommendation for web accessibility standards (as of June 2018). WCAG is also an ISO standard. It includes recommendations for how users, especially those with disabilities, expect to interact with websites and complex web apps.
Color contrast ratio standard
Color contrast should be sufficient for readability. Check contrast with tools like Tanaguru Contrast-Finder and aim for a ratio as close as possible to 4.5. This applies to copy, headings, and form fields.
Heading hierarchy must follow structure
Heading levels must follow hierarchy in order: h1 > h2 > h3. This is a semantic HTML requirement for accessibility.
All form inputs must have valid labels
All form inputs must have a valid label using the format <label for="INPUT_ID"> or a fallback approach. This is a semantic HTML requirement for accessibility.
Interactive controls must use button element
If an interactive control does not point to a URL, use a <button type="button"> element instead of other interactive elements. Links should only be used for navigation to URLs.
Keyboard navigation and focus outlines required
Features must work with keyboard alone. Focus outlines on links and toggles must be kept visible, as they are impossible for keyboard users to navigate without them. The outline can be customized if the default style is not preferred, but the default comes for free.
Focus must be updated when content is revealed
When new content is revealed (for example auto-scrolling to a new page section, updating filtered results, or opening a modal window), focus must be updated accordingly.
Escape key binding for modals
Bind the Escape key to quickly cancel modals, popups, and similar interactions.
Icon-only buttons require screen reader friendly titles
Icon-only buttons should have screen reader friendly titles so they make sense to assistive technology users. The HTML pattern is: <button class="icon icon-close" type="button"><span class="visuallyhidden">Close Menu</span></button>
Meaningful content cannot be in img or CSS pseudo-elements
Meaningful content must not be hidden inside <img> elements or :before/:after CSS pseudo-elements, which are unavailable to screen readers.
ARIA roles must be tested on screen readers before shipping
Any ARIA roles must be tested on both VoiceOver and NVDA before shipping. If not tested, the effect on users is unknown. Untested ARIA can make things worse. If unsure, leave it out rather than add untested ARIA.
Automated accessibility validation required
Use automated tools like WAVE to automatically check for issues and validate WCAG compliance in order to catch trends and low-hanging fruit like missing alt attributes.