Engineering Guidelines for Paste

Installation#

Dependencies#

To start using Paste, you must first install the following third party dependencies:

Install them in your project folder using either of these terminal commands:

# yarn
yarn add react react-dom prop-types
# npm
npm install react react-dom prop-types

Paste Packages#

Paste is split into two main packages: @twilio-paste/core and @twilio-paste/icons. Everything provided by Paste is included into those two packages. A key distinction with Paste Core is that we include - not bundle - all of Paste; this means we expose sub-packages you can individually import. For example, you would install @twilio-paste/core and import the Button component from @twilio-paste/core/button rather than directly from @twilio-paste/core. This keeps your app lean by only including the code you use. You can read about how Paste keeps your bundles small down below.

Everything exposed inside Paste Core can also be installed individually; you could install @twilio-paste/button and import only that one package. However, we recommend using the Core package for ease of maintenance and only falling back to the individual packages if you need to pin to a specific version.

# yarn
yarn add @twilio-paste/core @twilio-paste/icons
# npm
npm install @twilio-paste/core @twilio-paste/icons

Setting up the Theme Provider#

For Paste components to be styled correctly, you must provide them with a theme. To do so you must wrap the root of your app with the theme provider and select a theme. We recommend the default theme.

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

Usage#

Paste Components#

You can use the Paste components anywhere that is wrapped by the Theme Provider.

import {Box} from '@twilio-paste/core/box';
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.

It can sometimes be helpful to test Paste components without animation. To disable animations on Paste components, pass the disableAnimations boolean prop to the <Theme.Provider>.

<Theme.Provider theme="default" disableAnimations>
  {/* your content */}
</Theme.Provider>

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.

// or from '@twilio-paste/icons/cjs/PlusIcon'
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.

Additional information#

Core package list#

You can install Paste packages individually to pin to a specific version in your project. Here's an list of all the packages included inside Paste Core:

How the Core package stays lean#

Unlike other bundled libraries, using Core and Icons won't load all of Paste into your product's bundle, it will only include the parts you are importing. This happens automatically, without any requirement for a tree-shaking config in your builds.

You may have imported from other libraries like this:

import {Box, Anchor, Button, Theme} from '@twilio-paste/core';
import {DisclosureIcon, DeleteIcon} from '@twilio-paste/icons';

The problem with importing this way is that the referenced "main" file in these packages has to bundle all the different pieces together. This causes everything to be loaded even if we only need one small feature. With over 50 icons in our Icon package and 40 components in Core - with more being added continuously - this can become very heavy very quickly.

In Paste, we use an "unbarreled" import mechanism, so the above would look like this:

import {Box} from '@twilio-paste/core/box';
import {Anchor} from '@twilio-paste/core/anchor';
import {Button} from '@twilio-paste/core/button';
import {Theme} from '@twilio-paste/core/theme';
import {DisclosureIcon} from '@twilio-paste/icons/esm/DisclosureIcon';
import {DeleteIcon} from '@twilio-paste/icons/esm/DeleteIcon';

While this has more import lines than the previous example, we are specifying the import to a limited package. This keeps your bundles lean by only loading exactly what you need.

Paste Core is able to do this because Paste publishes each library and component as its own package. For example the above can be written as:

import {Box} from '@twilio-paste/box';
import {Anchor} from '@twilio-paste/anchor';
import {Button} from '@twilio-paste/button';
import {Theme} from '@twilio-paste/theme';
// Paste Icons are not individually published
import {DisclosureIcon} from '@twilio-paste/icons/esm/DisclosureIcon';
import {DeleteIcon} from '@twilio-paste/icons/esm/DeleteIcon';

The reason we recommend Core over using individual package imports is because it makes maintaining Paste in your project easier. If using the above approach, your package.json file will be full of individual package dependencies and keeping their versions in sync can be quite time consuming.

However, the individual package import is invaluable for when updating Core also makes changes to a package you aren't ready for. You can then install that pinned package and import from it directly. For example let's assume we update our Core package and as a side effect, the Button component gets updated. We aren't ready to update Button, but that shouldn't stop us from updating the rest of Core! We can install @twilio-paste/button to the version that works and import it like this:

import {Box} from '@twilio-paste/core/box';
import {Anchor} from '@twilio-paste/core/anchor';
import {Button} from '@twilio-paste/button'; // This loads the version we installed
import {Theme} from '@twilio-paste/core/theme';