Theme
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.
Paste components are built using our Styling Library, which currently wraps Emotion and
Styled System. 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 {}, "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 {},}The Paste ThemeProvider leverages React's Context 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>;| Prop | Type | Description | Default |
|---|---|---|---|
| theme? | enum | 'default', 'sendgrid' | 'default' |
| customBreakpoints? | string[] | An optional array of string values for custom screen sizes in the usual CSS width formats | theme.breakpoints |
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.
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 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', }));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 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 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>;};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 propconst ExampleComponentwithTheme = withTheme(ExampleComponent);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?