Skip to contentSkip to navigationSkip to topbar
Paste
FigmaStar

Theme

Version 11.0.1Github

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

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.

For more information about how Paste is built and where themes fit into that hierarchy, read About Paste.

Theme

Theme page anchor

Paste components are built using our Styling Library, which currently wraps Emotion(link takes you to an external page) and Styled System(link takes you to an external page). Our Styling Library 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 camelCase key represents a 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 {},
  "colorSchemes": Object {},
  "dataVisualization": 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

Theme Provider page anchor

The Paste ThemeProvider leverages React's Context(link takes you to an external page) to provide the theme object to any descendant components in the tree. For that reason, we recommend wrapping your application at the root level with the Paste ThemeProvider. This allows all sub-components to retrieve the correct token value for the supplied theme.

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

<Theme.Provider theme="default">
  <App />
</Theme.Provider>;

Props

Props page anchor
PropTypeDescriptionDefault
theme?enum'default', 'dark', 'twilio', 'twilio-dark' and 'evergreen''default'
customBreakpoints?string[]An optional array of string values for custom screen sizes in the usual CSS width formatstheme.breakpoints

Choosing a theme

Choosing a theme page anchor

Paste includes a number of themes out of the box. Choosing the right one for your project will depend on who you are and what you are building.

ThemeWhen to use
DefaultIf you are not building an application for Twilio, use this theme
DarkIf you are not building an application for Twilio and want a dark mode, use this theme
TwilioIf you are building an application for Twilio, use this theme
Twilio DarkIf you are building an application for Twilio and want a dark mode, use this theme
EvergreenIf you are building an application for Segment, use this theme

Using tokens in custom components

Using tokens in custom components page anchor

Sometimes you will need to create something custom that is not available in Paste but you need that component to still look like it's from Paste. The use of Paste Tokens in your styles is the way that you can access global design properties used in all Paste Components.

Styled Component

Styled Component page anchor

By using the Theme.Provider, when you create a custom component using Styling-Library, the theme object is available on props via context. You can access those via the css utility(link takes you to an external page) or props object directly.

This is the preferred method.

import {styled, css} from '@twilio-paste/styling-library';

const custom = styled.div(
  css({
    backgroundColor: 'colorBackgroundPrimary',
    padding: 'spacing20',
  })
);

Alternatives when not using Emotion

Alternatives when not using Emotion page anchor
(warning)

Careful!

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 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 ThemeConsumer page anchor

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.Consumer>
  {({theme}) => {
    return <p>What is the default text color {theme.textColors.colorText}</p>;
  }}
</Theme.Consumer>;

Paste useTheme Hook

Paste useTheme Hook page anchor

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 (HoC)

Higher Order Component (HoC) page anchor

Paste also provides a HoC to be able 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>;

// Provides this component with the theme object as a prop
const ExampleComponentwithTheme = withTheme(ExampleComponent);

Give us Feedback on this Page

Give us Feedback on this Page page anchor

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?