Skip to contentSkip to navigationSkip to topbar
Paste
Paste assistant Assistant
FigmaStar

Icon Usage Guidelines

(information)

Can't find the icon you need?

Check Streamline and contribute it to the library following our guidelines.

Icons are small graphical representation of a program or a function. They can be used to enhance the appearance of a web interface and break up the monotony of text.

Use an icon only when it provides additional clarity or is necessary to draw attention to a UI element.

Accessibility

Accessibility page anchor

Specify if an icon is decorative

Specify if an icon is decorative page anchor

Icons can either be decorative or informative. "Decorative icons don’t add information to the content of a page. The information provided by the image might already be given using adjacent text, or the image might be included to make the website more visually attractive." (w3.org)

Our icons require the developer define whether an icon is decorative by providing the required property.

Give informative icons a title

Give informative icons a title page anchor

A title is required so assistive technology can infer equal meaning as a sighted user would.

Add to cart (Title: "Add to cart")
(Hover over icon for tooltip)
Do

Use title text that gives context and meaning to the icon.

Plus (Title: "Plus")
(Hover over icon for tooltip)
Avoid

Avoid title text that only describes the icon image.

Pair icons with text

Pair icons with text page anchor

Remember that different cultures may interpret the same image in different ways so despite our best intentions it is helpful to provide adjoining text.

Add to cart
Do

Pair icons with text.

Plus
Avoid

Avoid having standalone icons.

Icons shouldn't be interactive

Icons shouldn't be interactive page anchor

Icons should not have interactions such as click or hover behavior. Instead they should be wrapped with an interactive element such as Button and Anchor.

Do

Wrap icons in an interactive component.

Add to cart
Avoid

Avoid making icons interactive without an interactive metaphor.

Examples

Examples page anchor

Adapting the icon's color

Adapting the icon's color page anchor

We can change the icon color directly using text color tokens.

Component preview theme
<LoadingIcon decorative={true} color="colorTextError" />

Alternatively, icons can inherit the current text color.

Component preview theme
<Text as="p" color="colorTextInverse">

  <Box as="span" display="flex" alignItems="center" backgroundColor="colorBackgroundBodyInverse" padding="space30" borderRadius="borderRadius20">

    <LoadingIcon decorative={true}  />

    <Box marginLeft="space20">Now loading</Box>

  </Box>

</Text>

Resizing icons

Resizing icons page anchor

Icons accept one of our sizeIcon tokens.

Component preview theme
<Text as="p">

  <Box><PlusIcon decorative={false} title="Add to cart" size="sizeIcon10" /></Box>

  <Box><PlusIcon decorative={false} title="Add to cart" size="sizeIcon20" /></Box>

  <Box><PlusIcon decorative={false} title="Add to cart" size="sizeIcon30" /></Box>

  <Box><PlusIcon decorative={false} title="Add to cart" size="sizeIcon40" /></Box>

</Text>

Making an icon decorative or informative

Making an icon decorative or informative page anchor

If an icon is decorative, no title is necessary. However, if an icon isn't decorative, you must provide a title property.

Component preview theme
<Text as="p">

  <PlusIcon decorative={false} title="Add to cart" />

  <PlusIcon decorative={true} />

</Text>

Usage Guide

Usage Guide page anchor

Installation

Installation page anchor
yarn add @twilio-paste/icons

Usage

Usage page anchor

Icons have to be imported individually. This import style was decided for important performance benefits. As our icon set grows to contain over 100 icons, we don't want projects that use only a few icons to pay the price of a large bundle.

import {PlusIcon} from '@twilio-paste/icons/esm/PlusIcon';

<Button variant="secondary" size="small" onClick={() => {}}>
  <PlusIcon decorative={true} />
  Add to cart
</Button>;

Props

Props page anchor
PropTypeDescriptionDefault
as?stringThe HTML tag to replace the default <span> tag.span
title?stringThe accessibility text that is read when screenreaders get to this component.
display?ResponsiveValue<CSS.DisplayProperty>block
decorativebooleanWhether or not the SVG is just visual flair or adds meaning to the page. Specifically for screenreaders to know whether to read out the title or not.
size?IconSizesizeIcon10 sizeIcon20 sizeIcon30 sizeIcon40sizeIcon20
color?TextColorSets the icon color to any of our text color tokens or currentColor, which inherits text color from the parent element.currentColor
element?stringOverrides the default element name to apply unique styles with the Customization Provider'ICON'

Icon Format

Icon Format page anchor

Paste icons are distributed as both SVG files and React components.

Why SVG?

Why SVG? page anchor

PNGs and JPGs are created using thousands of tiny pixels. SVGs are made out of geometric primitives such as points, lines, and basic shapes. Because of this attribute, SVGs can be resized without any loss of quality to the image. We can also write code to change SVG attributes in realtime. These characteristics are ideal for icons since we usually want to customize their size or color. To do this with PNGs or JPGs we would need to create a separate file for each variation.

Why React components?

Why React components? page anchor

If you're using any Paste component, you're familiar with how to install and use a React component. Our icon components have accessibility baked in. They also use our tokens for sizing and coloring. With icon components, you can import only the icons your project needs.

Curious why we chose to make React component icons? Check our write-up document(link takes you to an external page).