Engineering Guidelines for 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:

Install External dependencies#

The list of external third party dependencies are as follows:

Install them using:

yarn add react react-dom prop-types react-uid

Install Paste System packages#

Paste also requires these system dependencies:

Install them using:

yarn add @twilio-paste/types @twilio-paste/style-props @twilio-paste/design-tokens @twilio-paste/theme @twilio-paste/icons @twilio-paste/styling-library @twilio-paste/animation-library @twilio-paste/dropdown-library @twilio-paste/reakit-library

Install the Paste Core package#

Finally, install Paste Core.

yarn add @twilio-paste/core

Paste Core includes all Paste components in a single bundle. This is extremely useful if you are committed to using all Paste components and want an easy way to keep up to date with library updates.

Paste Core includes:#

Usage#

Once Paste Core and its dependencies are installed, you can import the Paste Theme at the root of your application:

import {Theme} from '@twilio-paste/theme';
// Wrap your root component with the Theme.Provider like so:
const App = () => (
  <Theme.Provider theme="default">
    <RestOfYourAppInHere />
  </Theme.Provider>
);

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

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

Jest / Testing#

Just like rendering Paste components in a web application, when rendering components for the purposes of testing you are required to wrap them in the theme provider. If you do not, your components may fail to render correctly.

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:

yarn add @twilio-paste/icons

Then you can use an icon inside your app:

import {PlusIcon} from '@twilio-paste/icons/esm/PlusIcon';
const Component = () => (
  <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.

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. More often than not you are working within existing SendGrid and Twilio Console applications and these fonts are automatically loaded for you.

Special note on Whitney#

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.

If you are not working in an existing Twilio Console experience, you can include the following link element in your sites head to load these fonts if you are serving your application from *.twilio.com domains.

<link rel="stylesheet" type="text/css" href="//cloud.typography.com/6230892/752864/css/fonts.css">

Special note on Inter#

The default theme (UDL theme) uses Inter as its primary font family. This is a free font that is hosted on Google Fonts. Feel free to copy how we load the font into your own app if you are using the default theme.