Design System

Theme Package

Paste Design System Theme Package which provides support for APIs to theme UIs and components.

yarn add @twilio-paste/theme

This package allows for straight-forward access to Paste design tokens via a Theme Provider to React components. By using this package, you can express your UIs with each of our supported themes, and get their associated token values.


Paste components are built using Emotion and Styled System, and provide a Theme object containing our design tokens. This enables our components to be themed, and also provide styling properties to some of our design primtive components like Box and Text. The theme object is grouped by categories and within each category, a key represents a camelCase formatted design token name. To see our supported themes and their values, check out the Token List page.

For example: If you were looking for token $color-background-success, you would see it listed on key backgroundColors as colorBackgroundSuccess i.e. theme.backgroundColors.colorBackgroundSuccess.

The shape of the Theme object currently looks like this:

Object {
"backgroundColors": Object {},
"borderColors": Object {},
"borderWidths": Object {},
"breakpoints": Object {},
"colors": Object {},
"fontSizes": Object {},
"fontWeights": Object {},
"fonts": Object {},
"heights": Object {},
"iconSizes": Object {},
"lineHeights": Object {},
"maxHeights": Object {},
"maxWidths": Object {},
"minHeights": Object {},
"minWidths": Object {},
"radii": Object {},
"shadows": Object {},
"sizes": Object {},
"space": Object {},
"textColors": Object {},
"widths": Object {},
"zIndices": Object {},

Theme Provider#

By design, all Paste Components require you to wrap your application in the Paste Theme provider. This gives all wrapped components the necessary design token values with theme support needed to render correctly.

The Paste Theme Provider is a wrapper around the Emotion Theme Provider and comes with a default theme.

You should place the Theme.Provider around the root of your React application.

import {Theme} from '@twilio-paste/theme';


theme?enum'default', 'sendgrid''default'
customBreakpoints?string[]An optional array of string values for custom screen sizes in the usual CSS width formatstheme.breakpoints

Using Tokens in Custom Components#

While Paste will aim to provide ample coverage of Components for teams to compose UIs, there will be occasions where you may need to build a custom component. This may be because it's in Paste's future roadmap (and it's worthwhile to create a parallel component in the short term for your own product), or something that Paste will explicitly not build. In these cases, it's still critical to ensure that your component looks like a Paste component in order to build a seamless experience. To do so, we recommend the use of Paste Tokens in your styles to access global design properties used across Paste.

By using Theme.Provider while creating a custom component using Emotion CSS, the theme object is available on props via context. You can access it via the Styled-System themeGet utility or accessing the props object directly.

For example:

import styled from '@emotion/styled';
import { themeGet } from '@styled-system/theme-get';
const custom = styled.div`
background-color: ${themeGet('backgrounds.primary')};
padding: ${props => props.theme.spacing.spacing20};

Alternatives when not using Emotion#


This is not a recommended approach for using Tokens. If you must do so, we strongly recommend reaching out at #help-design-system

If you are not using Emotion Styled Components or want to access the values of tokens in your React components outside of styling, there are three ways this can be achieved.

Paste ThemeConsumer#

Paste Theme provides Theme.Consumer - a React Context Consumer for the theme. It takes a function as a child, which provides the theme object as an argument.

import {Theme} from '@twilio-paste/theme';
{({theme}) => {
return <p>What is the default text color {theme.textColors.colorText}</p>;

Paste useTheme Hook#

Paste Theme provides a React Hook called useTheme which returns the theme object from the React Context via the Theme Provider.

import React from 'react';
import { useTheme } from '@twilio-paste/theme';
const HookExampleComponent = (): React.ReactElement => {
const theme = useTheme();
return <p>What is the default text color {theme.textColors.colorText}</p>;

Higher Order Component#

Paste also provides a HOC Component, which is a wrapper around the Emotion HOC Component to access the theme object.

import React from 'react';
import { withTheme } from '@twilio-paste/theme';
const ExampleComponent = ({theme}) => (
<p>What is the default text color {theme.textColors.colorText}</p>
const ExampleComponentwithTheme = withTheme(ExampleComponent);

Give us Feedback on this Page#

As you use Paste, you'll likely encounter things that don't seem right. Please reach out with your feedback! Here's some prompts to consider:

  • Is this page easy for me to consume?
  • Is the information supporting it sufficient / well-described?
  • What information is missing?
  • How approachable is the documentation? Can a new engineer / PM / designer at Twilio get started with it easily?

Change Log

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

1.0.1 (2019-10-31)

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

1.0.0 (2019-10-29)



  • box: many Box API changes

  • fix(theme-tokens): add sizes key for styled-system responsiveness

  • fix(absolute): update to newer Box

  • fix(types): allow for responsive values via array

  • fix(box): update story and light tweaks to OverflowProps

  • chore: update yarn.lock file

  • fix(types): many more types fixes

refactor: moved ValueOf into types package

  • fix(box): eslint error in story

  • fix(box): using the correct BorderProps definition

fix: we shouldn't allow users to pass the border shorthand, it circumvents tokens

  • fix: lint errors

  • fix(website): update box docs

  • fix(storybook): use theme breakpoints

0.4.1 (2019-09-16)

Bug Fixes#

  • design-tokens: fix SendGrid token values (#71) (396fccf)

0.4.0 (2019-08-15)

Bug Fixes#


  • ComponentHeader component, component overview fixes, more (#20) (875e124)
  • website: [DSYS-1046] website structure and navigation (306586e)