Paste

Design System

Engineering Guidelines for Paste

This document will highlight our approach for unified design libraries, tips for getting started, and similar resources for Engineers using Paste.


Installation#

The best way to use Paste is by using the core package. Paste Core provides all of the current Paste components which are ready for use.

Paste Core requires external dependencies, and other Paste system packages in order to function properly.

Install the following dependencies using yarn:

External dependencies#

PackageVersion
react^16.8.6
react-dom^16.8.6
react-uid^2.2.0
@emotion/core^10.0.10
@emotion/styled^10.0.10
styled-system^5.1.2
@styled-system/theme-get^5.1.2
yarn add react react-dom @emotion/core @emotion/styled styled-system @styled-system/theme-get react-uid

System packages#

PackageVersion
@twilio-paste/types3.0.0
@twilio-paste/style-props0.2.3
@twilio-paste/design-tokens4.3.0
@twilio-paste/theme3.1.0
yarn add @twilio-paste/types @twilio-paste/style-props @twilio-paste/design-tokens @twilio-paste/theme

Core package#

PackageVersion
@twilio-paste/core2.3.15
yarn add @twilio-paste/core

Usage#

Once Paste Core and the dependencies are installed, you can import the Paste Theme:

import {Theme} from '@twilio-paste/theme';
// Wrap your root component with the Theme.Provider like so:
<Theme.Provider theme="default">
// other stuff here
</Theme.Provider>

Now you can use the Paste themed and tokenized components anywhere in your app:

import {Box} from '@twilio-paste/core';
<Box margin="space20" backgroundColor="colorBackground">
Hello Paste!
</Box>

The Paste tokens are readily available on our components and typescript typings are provided.

Using Icons#

The Paste Icons package provides icon components. They can be used to enhance the appearance of a web interface and break up the monotony of text. Icons have to be imported individually.

Install Paste Icons using yarn:

PackageVersion
@twilio-paste/icons2.0.7
yarn @twilio-paste/icons

Then you can use an icon inside your app:

import {PlusIcon} from '@twilio-paste/icons/esm/PlusIcon';
<Button variant="secondary" size="small" onClick={() => {}}>
<PlusIcon decorative={true} />
Add to cart
</Button>

For more information about our icon system, checkout our usage guide here.

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.

Global Styles#

Many apps/websites utilize global stylesheets. Even though Paste styles are scoped at the component level, global styles can creep in and cause some havoc. Make sure to thoroughly test Paste components to verify everything looks as they should.

Fonts#

Paste leaves it up to you to load the fonts needed for the theme you've selected. Console uses Whitney ScreenSmart and SendGrid uses Colfax.

The Whitney font is loaded by the Typography.com service and is only allowed on *.twilio.com domains as well as localhost. Make sure to serve your app from the correct hostname if you're having issues with font loading.

Sandbox#

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.