Design Guidelines for Paste
Notes on how to use Paste in design work
You’ll need to download a few things before you can get started designing UIs with Paste.
All product designers across Twilio use Abstract 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.
Product designers across Twilio use Sketch to design their UIs. You can file a ticket with IT to get a Sketch license.
If you are using any theme in Paste, you will need to download and install Fira Mono, our monospace typeface for code. It’s a free Google font.
If you are using any theme in Paste, you will need to download and install SF Pro, 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.
If you are using the Default theme in Paste, you will need
to download and install Inter, 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.
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 project contains libraries that represent components that are available in Paste. For example,
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
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.
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.
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.
Most library names in the
Paste components project mirror the list of components you will find on the docs site, with a few notable
grid and spacing.
Grid and spacing
Paste design tokens#
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:
console themeis the current theme you see in Console. Flip the toggle on the Paste docs site to "Current" to see this theme.
default themeis 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.
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.
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-to for using these text and layer styles to create custom compositions in Sketch.
Flex design assets
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#
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.
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.
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:
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.
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.
The badge will open a dialog that outlines all of the library updates that are available.
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.
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 discussion.
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!
- Sketch Runner: Download the free version of Runner to install any plugin right from Sketch. Learn how to install a Sketch plugin from your desktop.
For the following plugins, once you've installed Runner, go to Plugins > Runner > Install, then search for the plugin:
- Camilo: Swaps Sketch libraries (e.g., from
- Symbol Swapper: Swaps all symbol instances in a file (e.g., swaps all destructive primary button symbols in the Console theme to destructive primary button symbols in the Default theme).
- SVGO Compressor: Compresses any SVG export automatically for more performant images and icons.