Component guidelines

Accordion

SEO

• Critical content should be in the HTML rather than being rendered client side.

Accessibility

• All focusable elements in the accordion are included in the page tab sequence.
• Accordions can be expanded by pressing the Enter or Space keyboard keys
• Code header areas in the accordion as <button> so that they are usable with both screen readers and the keyboard.
• Buttons should state if they are expanded with aria-expanded="true". The aria-expanded="false" attributes will be added to other buttons when the accordion is initialized by the JavaScript.
• Each button has a unique name aria-controls="id" that associates the control to the appropriate region by referencing the controlled element’s id.
• Each content area will have its aria-hidden attribute set to either true or false by the component, depending on its corresponding button’s aria-expanded attribute. To ensure that your content is accessible in the event that the JavaScript does not load or is disabled, you should not set aria-hidden="true" on any of your content areas.
• The accordion content is accessible and/or visible in the event of either styles or scripts being turned off.

Ad Flag

SEO

• Use aria-describedby or a similar label to call this area by the flag’s name.

Accessibility

• All elements should use a high contrast ratio for readability.

Badge

SEO

• When making text with icon badges interactive, provide a meaningful alternative text to make the link destination clear.

Accessibility

• In the case of text with icon badges, the icon is purely decorative; it is only supporting the information conveyed by the badge label. Hide the icon SVG from screen readers with aria-hidden="true".

Button

SEO

• Search engines cannot crawl a <button> element type, and therefore cannot discover the content on the resulting page. When using a call-to-action button that navigates to a page needing to be indexed, use an <a> element so that the button can be crawled by bots.

Accessibility

• Use a <button> element type when displaying buttons.
• Buttons should display a visible focus state when users tab to them.
• It is expected that a button can be triggered by pressing spacebar, enter, or return.
• Always include a <title> tag on the SVG within an icon-only button to describe the button’s intent for icon-only buttons.
• Do not use <div> or <span> unless strictly required.
• An <a> element cannot be triggered from a spacebar press, only from an enter or returnpress.

Caption

SEO

• Don’t use <p> tags for captions as Google News penalizes short <p> paragraphs; use the <caption> tag instead.

Accessibility

• Images must have an alt attribute with a descriptive alt text. Images without one are likely inaccessible.
• If the image is decorative, provide a null (empty) text alternative (alt="") so that it can be ignored by assistive technologies, such as screen readers. Text values for decorative images add audible clutter to screen reader output or could distract users if the topic is different from that in adjacent text. Leaving out the alt attribute is not an option because when it is not provided, some screen readers will announce the file name of the image instead.

Card

SEO

• Each card should be a self contained HTML block, containing an appropriate level tag identifying the main content of the block, and closed paragraphs with the remaining content.

Accessibility

• Always wrap a card’s title in a heading element that maps to your content hierarchy.

Disclaimer

Accessibility

• If disclaimer includes text links, refer to the accessibility section on the Links] documentation.

Filter

Accessibility

• Always use an icon only Button for the dismiss action on a dismissible filter. This provides the required keyboard navigability.
• Always include a title tag on the dismiss icon with appropriate text for screen readers like “Remove Filter” or “Dismiss Filter.”
• Filters should display a visible focus state when users tab to them.
• It is expected that a filter can be triggered by pressing spacebar, enter, or return.

Form module

SEO

• Utilize an h-level heading tag for the heading to support search bot crawling of the content.

Forms - Checkboxes

SEO

• When checkboxes are used in tandem with a submission Button, Google will not find any resulting information or proceed down the path. If the resulting content is something you wish a user to land on, an alternate, linked path must be built.
• Critical content should be in the HTML rather than being rendered client side.

Accessibility

• Include the checkbox in the page tab sequence.
• Ensure checkboxes are keyboard accessible; it is expected that a checkbox can be checked by pressing spacebar.
• Checkboxes should display a visible focus state when users tab to them.
• The checkbox has a role="checkbox".
• Use the <label> element, and, in specific cases, other mechanisms (e.g., WAI-ARIA, title attribute etc.), to identify each form control.
• The checkbox has an accessible label provided by one of the following: visible text content contained within the element with role="checkbox"; a visible label referenced by the value of aria-labelledby set on the element with role="checkbox"; aria-label set on the element with role="checkbox".
• When checked, the checkbox element has state aria-checked set to true.
• When not checked, it has state aria-checked set to false.
• When partially checked, it has state aria-checked set to mixed.
• Group related checkboxes together with <fieldset> and describe the group with <legend>. Do not use these for a single checkbox.
• If a set of checkboxes is presented as a logical group with a visible label, the checkboxes are included in an element with role="group" that has the property aria-labelledby set to the id of the element containing the label.
• In the case of errors, use the aria-invalid="true" attribute to an input that triggers an error alert. It is used to indicate that the value entered does not conform to the expected format or that a required field has not been filled in.
• Use the ARIA role="alert" attribute on the element, allowing the browser to send out an accessible alert event to assistive technologies which can then notify the user about it. For example: notifying users about an invalid value in a form field, a login session about to expire, or a lost connection to the server. If the message is interactive, use the alertdialog role instead.

Forms - Form controls

SEO

• Text is clearly defined in the <label> element in this component, and should describe what action the switch is performing for the user.
• The Switch is actually a native HTML checkbox that is either checked or unchecked, visually masked with a different design.

Accessibility

• Include each switch in the page keyboard tab navigation sequence.
• Ensure each switch is keyboard accessible; it is expected that a switch can be selected with the SPACE key, with the ability to move to the next switch with the the TAB key.
• The switch includes the role="switch" attribute to inform screen readers of this control’s function.
• A <span> element with aria-hidden="true" is included which is the hook for the switch styles.

Forms - Radios

SEO

• When radios are used in tandem with a submission Button, Google will not find any resulting information or proceed down the path. If the resulting content is something you wish a user to land on, an alternate, linked path must be built.
• Critical content should be in the HTML rather than being rendered client side.

Accessibility

• Include each radio in the page tab sequence.
• Ensure radios are keyboard accessible; it is expected that a radio can be selected with the up/left or down/right arrows and moving to the next radio with the the tab key.
• Each radio button should have a <label>, and, in specific cases, other mechanisms (e.g., WAI-ARIA, title attribute etc.), to identify each form control.
• Group related radio buttons together with <fieldset> and describe the group with <legend>. Do not use these for a single radio.
• Each input should have a semantic id attribute, and its corresponding label should have the same value in its for attribute.
• In the case of errors, use the aria-invalid=“true” attribute to an input that triggers an error alert. It is used to indicate that the value entered does not conform to the expected format or that a required field has not been filled in.
• Use the ARIA role="alert" attribute on the element, allowing the browser to send out an accessible alert event to assistive technologies which can then notify the user about it. For example: notifying users about an invalid value in a form field, a login session about to expire, or a lost connection to the server. If the message is interactive, use the alertdialog role instead.

Forms - Text fields & dropdowns

Accessibility

Text-fields

• Avoid breaking numbers with distinct sections into separate input fields. For example, use one input for U.S. phone numbers, not three (one for area code, one for local code, and one for number). Each field needs to be labeled for a screen reader and the labels for fields broken into segments are often not meaningful.
• Include the text field in the page tab sequence.
• Text fields are keyboard accessible.
• Each text field should have a <label>, and, in specific cases, other mechanisms (e.g., WAI-ARIA, title attribute etc.), to identify each form control.
• Never use a placeholder text in place of a label.
• Group related radio buttons together with <fieldset> and describe the group with <legend>.
• In the case of errors, use the aria-invalid=“true” attribute to an input that triggers an error alert. It is used to indicate that the value entered does not conform to the expected format or that a required field has not been filled in.
• Use the ARIA role="alert" attribute on the element, allowing the browser to send out an accessible alert event to assistive technologies which can then notify the user about it. For example: notifying users about an invalid value in a form field, a login session about to expire, or a lost connection to the server. If the message is interactive, use the alertdialog role instead.

Dropdowns

• A dropdown can be expanded by pressing spacebar.
• Always include a label with each dropdown. Don’t replace it with the default dropdown option.

Headshot

SEO

• Provide a descriptive alt text to give better image context and description to search engine crawlers.

Accessibility

• The image must have an alt attribute with a descriptive alt text. Images without one are likely inaccessible.
• If the image is decorative, provide a null (empty) text alternative (alt="") so that it can be ignored by assistive technologies, such as screen readers. Text values for decorative images add audible clutter to screen reader output or could distract users if the topic is different from that in adjacent text. Leaving out the alt attribute is not an option because when it is not provided, some screen readers will announce the file name of the image instead.

Hero

SEO

• Work with SEO to determine whether the hero text should utilize a <h1> or other HTML heading tag. Otherwise, if the text is unimportant to search crawlers, it can be marked up accordingly.

Links

SEO

• Use an <a> element if you want the resulting URL to be discovered by bots.

Accessibility

• Include all links in the page tab sequence.
• Links should display a visible focus state when users tab to them.
• Ensure links are keyboard accessible; it is expected that a link can be triggered by pressing enter.
• Always include an href attribute for a link.
• Text links should include the title="description of action" attribute so that the browser tooltip can display this helpful information.
• An aria-label should be clear and concise, using fewer than 100 characters will increase user comprehension.
• An aria-label should make sense out of context and clearly inform a user of what action will be taken if the link is selected. Don’t rely on surrounding context to inform link content.
• For links that activate a download, explicitly state this action within the aria-label, including the file-type and file-size.
• For links that force the user to leave the current window or tab, explicitly state this action within the aria-label.
• Combine adjacent image and text links into the same <a> element.
• Don’t use redundant wording within ARIA labels. An aria-label on an anchor tag automatically informs the user an element is a link. Words such as, “link”, “links”, or “go to” are repetitive and unnecessary.
• Don’t write aria-label text in all caps. Most screen readers read all cap text one letter at a time.
• Don’t embed critical information within CSS. Screen readers do not recognize CSS.
• Never use URLs in link text, screen readers dictate URLs letter by letter.
• Never use dashes, mathematical characters or emoticons in place of the actual word within an aria-label. These symbols are not recognized by most assistive technology.

Link pack

SEO

• Use <a href> in the html for the links
• Links must be accessible/discoverable to the consumer (whether directly on-page or in a collapsed accordion, etc.)
• Header tag and link text must be contextually appropriate and keyword-focused
• Header tag and link text must be legible/ADA-compliant (Google recommends going no smaller than 12px in font size)
• Line of unique content must be accessible/discoverable to the consumer, and crawlable in the html for Googlebot.
• Dynamic variables in the line of unique content must be updated daily to ensure freshness and accuracy of data points.

Accessibility

• Adhere to the same accessibility rules as applied to Links and Lists

Lists

Accessibility

• When using an unordered list, apply aria-labeledby to the preceding heading to help give context for screen-readers

Modal

SEO

• In the case of modals that are not user-initiated, make sure to wait at least 15 seconds before firing them.

Accessibility

• When a modal opens, focus moves to the first focusable element inside the modal.
• Use ARIA role role="dialog" to separate content from the rest of the page.
• Add the aria-labelledby attribute in the same element as the modal role. This attribute references associated title markup to describe the modal and is the first item read by screen readers. Limit title length and avoid being too descriptive (e.g., “Do you want to save this?”). For a more thorough description of the modal, use the aria-describedby attribute instead.
• If you want to hide/not render the modal and its content to any user, add the aria-hidden="true" attribute.
• It is expected that a modal can be closed by pressing the Esc key on the keyboard.
• The tab sequence of modals include a visible element with role button that closes the modal, such as a close icon or cancel button. Action is not required on this button however, as the Esc key will trigger a close action.
• When a modal closes, focus should usually return to the element that opened the modal (typically a button or link).

Notification

Accessibility

• Add the aria-invalid="true" attribute to an input that triggers an error notification. This indicates that the value entered does not conform to the expected format or that a required field has not been filled in.
• For notifications with no interactive controls, use the ARIA role="alert" attribute on the element, to allow the browser to send out an accessible alert event to assistive technologies which can then notify the user about it. For example: notifying users about an invalid value in a form field, a login session about to expire, or a lost connection to the server.
• For notifications that provide interactive controls, include the role="alertdialog" attribute on the element.

Pagination

SEO

• Use rel=next, rel=prev in the <head> to communicate that the URLs are of a series. When pointing to page 1, make sure you use the clean URL (without parameters).
• Make sure that there is a last page to avoid Google going down an infinite rabbit hole.

Accessibility

• In order to let assistive technologies users recognize that there is a pagination, wrap the pagination links in a <nav> element with role="navigation" and aria-label="Pagination Navigation".
• Add the appropriate ARIA labels to each navigation link to help any user understand they can navigate different pages. Use aria-label to add a descriptive label to each link such as “Goto Page 1”; for example, 2. This way, instead of announcing “Link 1”, the screen reader will say “Internal link Goto Page 1”.
• To indicate the currently selected page in the range, set the appropriate ARIA attributes on the anchor element, for example, <a href="/page-1" aria-label="Current Page, Page 1" aria-current="page">1</a>.
• Disable the previous and next links when at the beginning or end of a page set.

Rating

SEO

• Always provide rating value(s) - on page or as a descriptive alt text - so that the rating is available in a non-visual form for search engine crawlers.
• When using any rating variants, please reach out to the SEO team about any potential use of schema.org on the page.

Accessibility

• Always provide rating value(s) - on page or as a descriptive alt text - so that screen readers announce the value(s) to users.
• When using the default variant, Links accessibility guidelines apply.

Reveal

Accessibility

• Display a visible focus state when users tab to it.
• It is expected that reveal can be triggered by pressing spacebar or enter.
• Use the aria-role="button" on the element so that it is usable with both screen readers and the keyboard.
• Use the aria-expanded states aria-expanded="false" or aria-expanded="true" to mark expandable and collapsible regions of content and to expose whether a region is currently expanded or collapsed.
• The content area will have its aria-hidden attribute set to either true or false by the component, depending on its corresponding button’s aria-expanded attribute.

Separator

Accessibility

• Do not use image separators; use CSS instead.
• Use the <hr> element with style sheets to convey content structure and separation, such as a shift of topic within a section.
• If the separators are strictly ornamental, use CSS instead of the <hr> element.

Tabs

SEO

• Tabs that do not change a URL hide content from Google.
• Links visually represented as tabs function the same as Links.

Accessibility

• Tabs are fully accessible with a keyboard.
• Ensure the focus state is always visible and that the focus can be moved away using only the keyboard.
• Provide a linear tabbing order (tabindex) for the navigation of focusable elements.
• Add tablist role to the <ul> to indicate it contains tabs.
• Add presentation role to each <li> to bypass its list item state.
• Add tab role to each <a> to incidate it is an actual tab.
• Add href and aria-controls to each <a> to reference its tab panel.
• Add id to each <a> as a reference for its tab panel.
• Add aria-selected="true" to the active <a> tab.
• Add tabpanel role to each <section> to indicate it is a tab panel.
• Add id to each <section> as a reference for its tab.
• Add aria-labelledby to each <section> to reference its label.
• Add hidden to each inactive <section> to indicate it is hidden.

Tags

SEO

• Use an <a> element if you want the resulting URL to be discovered by bots.

Tooltip

• Tooltips can be closed by clicking the original trigger link, clicking the “x” inside of the tooltip window, or by pressing the esc key.

SEO

• Critical content should be in the HTML rather than being rendered client side.

Accessibility

• When a tooltip opens, focus moves to the first focusable element inside the tooltip.
• Always use role="tooltip" on the tooltip element.
• Use aria-hidden="true" to prevent screenreaders from reading hidden tooltips. Change value to false when tooltip is visible.
• Tooltip trigger element should have a aria-describedby attribute which references to the id of the associated tooltip.
• Add aria-labelledby to tooltip to associate full content of a tooltip.
• It is expected that a tooltip can be closed by pressing esc.
• When a tooltip closes, focus should return to the element that opened the tooltip.