Theme Package

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

Version
3.3.2
Sources
Github
Import from
@twilio-paste/core/theme — or — @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.

Theme#

Paste components are built using our Styling Library, which currently wraps Emotionlink takes you to an external page and Styled Systemlink 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 {},
"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#

The Paste ThemeProvider leverages React's Contextlink 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="console">
<App />
</Theme.Provider>;

Props#

PropTypeDescriptionDefault
theme?enum'default', 'console', '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#

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#

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

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

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#

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?


Support

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.

Contributing

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.