Design System

Icon Usage Guidelines

You can view and play with icons on our storybook icon list. Our icon set is still limited, and more will be added over time. Please file an icon request or follow the guide on how to add an icon.

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. If an icon is used to indicate hierarchy of a UI element, all elements at the same hierarchy should also be paired with an icon.


Specify if an icon is decorative#

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." (

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

Give informative icons a title#

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

Add to cart
(Hover over icon for tooltip)

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

(Hover over icon for tooltip)

Avoid title text that only describes the icon image.

Pair icons with text#

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

We're working on a better example for this section. #TODO

Add to cart

Pair icons with text.


Avoid having standalone icons.

Icons shouldn't be interactive#

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.


Wrap icons in an interactive component.

Add to cart

Avoid making icons interactive without an interactive metaphor.


Adapting the icon's color#

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

Alternatively, icons can inherit the current text color.

Now loading

Resizing icons#

Icons accept one of our sizeIcon tokens.

Add to cart
Add to cart
Add to cart
Add to cart

Making an icon decorative or informative#

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

Add to cart

Usage Guide#


yarn add @twilio-paste/icons


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


as?stringThe HTML tag to replace the default <button> tag.span
title?stringThe accessibility text that is read when screenreaders get to this component.
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
iconColor?TextColorSets the icon color to any of our text color tokens or currentColor, which inherits text color from the parent element.currentColor

Icon Format#

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

Why SVG?#

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?#

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.

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

2.0.7 (2020-04-02)

Note: Version bump only for package @twilio-paste/icons

2.0.6 (2020-03-24)

Bug Fixes#

  • icons: switch from theme-tokens to theme package dep (cfbb07f)

2.0.5 (2020-03-17)

Note: Version bump only for package @twilio-paste/icons

2.0.4 (2020-03-17)

Note: Version bump only for package @twilio-paste/icons

2.0.3 (2020-03-11)

Note: Version bump only for package @twilio-paste/icons

2.0.2 (2020-03-06)

Note: Version bump only for package @twilio-paste/icons

2.0.1 (2020-03-02)

Note: Version bump only for package @twilio-paste/icons

2.0.0 (2020-03-02)

Bug Fixes#

  • icons: change IconWrapper to inline-flex (e02f3d5)
  • icons: rename SVG file to remove 'Icon' suffix (f0437d9)
  • icons: update default icon size (7e3d2e0)
  • icons: update several icons (94f5c70)
  • storybook: incorrect import package (types -> style-props) (b199a10)


  • icons: Renamed some SVG files to remove icon suffix

1.7.2 (2020-02-28)

Note: Version bump only for package @twilio-paste/icons

1.7.1 (2020-02-26)

Bug Fixes#

  • package dependencies and deprecation warnings (#334) (0e88338)

1.7.0 (2020-02-21)


1.6.0 (2020-02-20)


  • icons: add ChevronDown icon (ebb8360)
  • icons: add ChevronUp icon (5070b68)
  • icons: add LinkExternal icon (fa14ca3)

1.5.0 (2020-02-19)


1.4.6 (2020-02-18)

Note: Version bump only for package @twilio-paste/icons

1.4.5 (2020-02-13)

Note: Version bump only for package @twilio-paste/icons

1.4.4 (2020-02-11)

Note: Version bump only for package @twilio-paste/icons

1.4.3 (2020-02-11)

Note: Version bump only for package @twilio-paste/icons

1.4.2 (2020-02-03)

Note: Version bump only for package @twilio-paste/icons

1.4.1 (2020-01-27)

Bug Fixes#

  • icons: adjust the twilio org product icon so it builds (#281) (8a4d04c)

1.4.0 (2020-01-25)


  • icons: add the twilio org product icon (#270) (f07f641)

1.3.1 (2020-01-24)

Note: Version bump only for package @twilio-paste/icons

1.3.0 (2020-01-17)


1.2.1 (2019-12-20)

Note: Version bump only for package @twilio-paste/icons

1.2.0 (2019-12-19)


1.1.1 (2019-12-05)

Note: Version bump only for package @twilio-paste/icons

1.1.0 (2019-11-20)


  • icons: make decorative required + icon docs (#165) (15ccbc2)

1.0.2 (2019-11-18)

Bug Fixes#

1.0.1 (2019-11-12)

Bug Fixes#

  • prettier updated, updating formatting (8644831)

1.0.0 (2019-11-11)


  • icons: delete old icons, add new streamline icons (#129) (571791d)


  • icons: removed all the inherited icons since we're moving to a new system

  • chore(icons): update icon list for storybook

  • fix(spinner): use new icon

  • fix(storybook): use new icon for story

  • fix(story): button icons should be 24px

  • fix: adjust icon size tokens

  • feat: add iconSizes as separate key in theme-tokens

  • feat(icons): icons package to use tokens and update icons

  • fix(spinner): update to use tokens and new icons

  • fix(button): use correct spinner size

  • fix(icons): major icons package fixes

  • huge overhaul to build process
  • now uses rollup
  • builds into cjs and esm directories
  • made the package publishable to npm
  • moved svg folder out of src, now src only holds react stuff
  • updated scripts to use new paths and cleaned up the code
  • programmatically generates rollup config from the icon-list command
  • chore: add new icons dist folders to gitignore

  • fix: spinner and button icon usage

  • feat(icons): add rollup icon list cache file

  • fix(core-bundle): sort packages for consistent builds

  • chore: use esm instead of es in rollup for correctness

  • chore: yarn.lock

  • fix(spinner): lint error

  • chore(icons): move rollup icon list

  • chore(spinner): use types package in story

  • fix(spinner): swap out destructured props for explicit props

0.4.0 (2019-10-29)


0.3.1 (2019-09-16)

Bug Fixes#

0.3.0 (2019-08-15)

Bug Fixes#


  • ComponentHeader component, component overview fixes, more (#20) (875e124)


If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.


The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.