Examples
The <SvgIcon>
component is a re-usable component that wraps its children in an <svg>
element.
This component is used by each individual icon component listed below.
Guidelines
Content
- Describe what the user still needs to do in a mandatory field that has been left incomplete or unanswered, or answered incorrectly.
- Repeat what the form label is asking the user to do, but with slightly more detail.
- Use the fewest words possible (i.e., don't use "please").
- Use sentence case.
- End with a period.
Accessibility
General accessibility
- The
<SvgIcon>
component has built-in accessibility features including:- a built-in
title
attribute. For any specific exported icon, thetitle
attribute is defaulted, but can be overwritten. focusable="false"
which prevents the icon from being focusable.role="img"
which tells assistive technologies that the icon's purpose is as an image- optional
description
attribute which can be used for a more detailed explanation of the icon's contents. Meant to be used to provide more detail than just thetitle
. - an available
ariaHidden
attribute which can be used if the icon's context is described elsewhere. For example, if the icon is part of a button with text, the text may provide the text description instead of the icon component.
- a built-in
- Make sure that the icon has a minimum contrast ratio of 3:1 against its background.
- If icons accompany a text link, place the icon inside the link to prevent screen readers from announcing the link twice.
Accessibility Testing
- Check that color is not the only method used to convey icon information. When an icon is paired with text, the meaning should be conveyed through the text, not color alone.
- Icons should meet color contrast requirements: when you view the icon on a page and use ANDI or a color contrast analyzer to look at the hex colors, contrast between the icon and background is at least 3:1.
- When you use a screen reader or view the page, the iconโs meaning and the way it is announced are the same across all pages.
Screen reader testing
Icons provide a text alternative for screen readers when needed.
- When you use a screen reader and navigate to a non-decorative icon, you should hear an appropriate description of the icon.
- If the icon is purely decorative, you should not hear a description.
Keyboard navigation tests
If focusable="true"
:
- When you use a keyboard to tab into an interactive icon, you should see an indicator around the icon.
Code
React
Review Storybook for React guidance of this component.
Changing icon color
Icon components support a few built-in color options that can be applied by using one of the following utility classes.
If you need a different color for an icon, you can pass a custom class to an icon component through the class
prop. Then, in your application CSS, set the color
prop.
Color | CSS utility Class | Example |
---|---|---|
Primary | ds-c-icon-color--primary | |
Inverse | ds-c-icon-color--inverse | |
Error | ds-c-icon-color--error | |
Warn | ds-c-icon-color--warn | |
Success | ds-c-icon-color--success |
Changing icon size
Icon components use ems
for their height and width and can thereby be sized by changing the font-size of the SVG element.
It is recommended that the font-size utilities be used.
Size | Example |
---|---|
Small | |
Default | |
Large | |
Extra Large | |
2x Large | |
3x Large | |
4x Large | |
5x Large |
Creating custom icons
The <SvgIcon>
component can be used for other custom icons. It allows you to pass in the SVG child elements. This component is recommended if you want built-in accessibility features and standard icon styles.
In the example below, the <SvgIcon>
component is used with a custom path.
Component maturity
For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.