Skip to content
Paste
UX Platform
GitHub

Design Guidelines for Paste

Notes on how to use Paste in design work


Installation#

You’ll need to download a few things before you can get started designing UIs with Paste.

Abstract#

All product designers across Twilio use Abstractlink takes you to an external page to host and version control their design files. We also use Abstract to link Paste Sketch libraries and manage library updates (more on that later). Connect with your design manager to get added to the Twilio team in Abstract.

Getting familiar with Abstract

If you are not yet familiar with Abstract, please take some time to learn about how it works, and read through these resources on best practices.

Sketch#

Product designers across Twilio use Sketch to design their UIs. You can file a ticket with ITlink takes you to an external page to get a Sketch license.

Font files#

Fira Mono#

If you are using any theme in Paste, you will need to download and install Fira Monolink takes you to an external page, our monospace typeface for code. It’s a free Google font.

SF Pro#

If you are using any theme in Paste, you will need to download and install SF Prolink takes you to an external page, the system font for Apple platforms. We represent native web element styles (like option lists in Select) in our design assets in the macOS styles.

Inter#

If you are using the Default theme in Paste, you will need to download and install Interlink takes you to an external page, which we use for UI text. It’s a free font. After you download the files, follow the instructions in the install-mac.txt file in your download. We recommend following the steps using Font Book.

Whitney#

If you are using the Console theme in Paste, you will need to download Whitney, which we use for UI text. Reach out to us in #help-design-system if you need access to the Whitney font files for your work.

How to use Sketch libraries#

For every Abstract project, you will need to link the necessary Paste Sketch libraries in order to use the Sketch symbols, text styles, and layer styles.

Tips on linking libraries in Abstract

If you haven’t linked libraries in Abstract before, follow this guide to learn how.

Paste components#

Success icon

Actively maintained

The Paste components project contains libraries that represent components that are available in Paste. For example, within the Paste components project, we have a Sketch library called button, which has all variants and states of our button component in both the Console and Default themes.

Linking the libraries#

To add Paste components to your designs, you will need to link the relevant component libraries from the Paste components project in Abstract. There are many libraries available in this project: one library per component available in Paste (except for a few special cases).

You can link all libraries within Paste components if you’d like, or you can link them as you need them. For example, if you are working on a flow that uses anchor, button, and card from Paste, at a minimum, you should link those libraries to your project.

Modal in Abstract where you can select libraries from the Paste compenents project to link to your project

Using the libraries#

Once you have them linked, you will be able to insert symbols from those libraries into your Sketch files in that Abstract project. Use the symbols that match the theme you are using in your project.

Menu in Sketch where you can navigate through symbols from the Anchor Sketch library

A note on SendGrid components

You will see that some symbols are provided in the SendGrid theme. If you plan to use them, please reach out to us in #help-design-system.

Special cases#

Most library names in the Paste components project mirror the list of components you will find on the docs site, with a few notable exceptions: typography, forms, and grid and spacing.

Paste design tokens#

Success icon

Actively maintained

The Paste design tokens project houses the text and layer styles for each theme in Paste. These libraries represent the tokens available for use in the system. For example, in the default theme file, you can find layer styles for every background color token that is available for the Default theme.

Linking the library#

There are two libraries available in this project:

  • The console theme is the current theme you see in Console. Flip the toggle on the Paste docs site to "Current" to see this theme.
  • The default theme is the new unified theme, formerly known as the "Unified Design Language" or "UDL". Flip the toggle on the Paste docs site to "Preview" to see this theme.

Link whichever library matches the theme you are using in your project. For example, if you are designing using the Default theme, link the default theme library to your project.

Modal in Abstract where you can select libraries from the Paste design tokens project to link to your project

A note on the SendGrid theme

You will also see the SendGrid theme in this project. If you plan to use this theme, please reach out to us in #help-design-system.

Using the library#

Once you have this library linked, you will see text styles (which include text colors, font families, and font sizes) and layer styles (which include background colors, border widths and colors, shadows, etc.) for that theme.

Menu in Sketch when you can navigate through text styles for the Default theme

Menu in Sketch where you can navigate through layer styles for the Default theme

You should be using components from Paste to compose your UIs whenever possible, but the text and layer styles will be helpful when you need to compose something more custom. This can be anything from setting a piece of text next to an icon to creating a custom stepper component. Check out this how-tolink takes you to an external page for using these text and layer styles to create custom compositions in Sketch.

Other libraries#

How to incorporate library updates#

Library release roadmap and notices#

The DSYS Design Team releases library updates on a 6-week cadence. Take a look at our roadmap to see release dates, as well as what will be included in each release (note that the roadmap is approximate, so each release may look a little bit different than what’s on the roadmap due to shifting priorities).

With each release, we will make an announcement in the #team-ux channel, as well as send out an email to the UX team. This announcement will outline all changes included in that release, and there will be special callouts for any major changes and how to safely accept those changes into your design files.

Types of library changes#

Major#

Breaking changes that require work to incorporate into designs. For example, symbols changed size, requiring designers to realign design elements; or symbol overrides reset, requiring designers to reapply them.

Minor#

Non-breaking functionality was added that requires no work to incorporate. For example, a new button variant was added, or a token value was adjusted.

Patch#

Non-breaking bug fixes that require no work to incorporate. For example, the alignment of text in an input was fixed, or an incorrect border radius on small buttons was updated.

Safely accepting library updates#

When we merge library updates into the master branch in Abstract, those updates will be available in any projects where you have those libraries linked.

We do our best to thoroughly test all library updates before merging them in, but we will still miss bugs from time to time, and some updates may come with unavoidable breaking changes. To safely test library updates, we strongly recommend following these steps when you want to move to the newest versions of the Paste libraries:

  1. Create a new branch within the project where you want to pull in the most recent library updates. Use this branch specifically for testing the library updates. You can create this branch directly off of master or off of another active branch in your project.

    Do NOT accept library updates on a branch where you are actively doing other design work.

    Doing so may break your current work. Either create a new branch to test the library updates, or just wait to use the updated libraries until you start your next project. If you wait, you can still work with your engineering team to use the most recent component style, even if you don’t have that style represented in your designs.

  2. Open your Sketch file(s) within that project. You will have the “Library Updates Available” badge in the header if there are library updates relevant to the symbols or styles used in your project.

    Badge in Sketch that appears when you have library updates available

  3. The badge will open a dialog that outlines all of the library updates that are available.

    Modal in Sketch that allows you to select which library updates you want to accept into your file

    You do NOT have to accept all library updates at once. In fact, we strongly encourage that you accept one update or group of related updates at a time, so that if something breaks in your design, it is easy to isolate which library update caused the issue.
  4. After applying the library updates, take a look through all of the artboards in your file. If everything looks good, you are safe to merge this branch back into the parent branch.

    If the library updates broke anything in your design, identify which of the following issues you are seeing:

    • A style change has been incorporated that impacted the alignment and/or spacing of your design. For example, the line height of paragraph text was reduced, so you now have extra spacing between your paragraph text and the elements around it. In this case, the resolution is to either adjust your designs to accommodate the changes or decline the library updates for now. We will communicate in our release notes if library updates will impact your designs in this way.
    • Symbol overrides that you had previously applied were reset. For example, the labels overrides on your text inputs were reset back to “Label”. This is likely due to a re-architecting of the symbol that we implemented to either improve the usability of the symbol or to work with a recent Sketch update. In either case, the resolution is to either reapply the symbol overrides or decline the library updates for now. We will do our best to communicate in our release notes if library updates will impact your designs in this way.
    • A symbol does not appear to be functioning as expected. For example, the background color of a primary button is gray instead of blue. In this case, check to see if you are using the same version of Sketch (or higher) that is being used in the library from which you are applying updates. You can check the Sketch version of any file in Abstract by navigating to the Master branch and selecting a file.

      Screen in Abstract that shows you the Sketch version of a given file

      If you are using an old version of Sketch, please try updating to the same version that is being used in the Paste libraries, and try again.

      If you are still seeing the issue, decline the library updates and submit a Github discussionlink takes you to an external page.

Additional questions or concerns#

If you have any questions for us that weren’t covered by this guide, or you are running into problems using our design resources, please reach out!

Useful resources#

For the following plugins, once you've installed Runner, go to Plugins > Runner > Install, then search for the plugin:

Black lives matter.