Design System

Design Guidelines for Paste

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

Early Access! Early Access! Early Access!

These guidelines are a living document, and not final. Reach out with comments & concerns at #help-design-system


Welcome! Paste is currently in early access. The intention of this release is to:

  • Give clarity to the UX Org for what our vision for a Unified Design System is, through a working example.
  • Validate our ability to execute together as a larger systems team.
  • Get folks excited!

However, this release is not:

  • Complete. This is a steel thread that requires active participation from the Systems team to make things work.
  • Fully documented. Expect to see pages or sections that just say “Coming Soon” or “TBD”.
  • Locked in on opinions. We always reserve the right to wake up smarter and rely on your feedback to do so.

Getting Started with Paste#

Access for Font Files, Sketch Licenses, Abstract#

Instructions for Download (Confluence)

Basic Terminology#

If you’re unfamiliar with Abstract, version control, or git workflows, read through how it works. Since Abstract uses version control terms, brushing up on these would be a good first step.

Some terms you'll encounter:

  • Abstract: A version control app for Sketch, which means we can share a single source of truth for our Sketch files and not run into unmanageable edit conflicts.

  • Master: The single source of truth of files in a project

  • Branch: A copy of the Master files that lets you make any changes without affecting the rest of the team’s work. Only the creator of the branch can make changes in it. If you want to work off someone's branch, you can create a child branch off their branch.

  • Commit: The way you save your work so it’s publicly viewable to the rest of the team. Committing is like saving a snapshot of your work, so you can revert your work back to previous commits when you need to. It does not affect the Master. Always Be Committing!

  • Merge: The way you combine your branch with the Master files

  • Merge conflict: This happens when there’s a conflicting version of an artboard with the Master and a branch. Abstract will walk you through which artboards are conflicting so you can choose what you want to appear in Master. To avoid these conflicts, we recommend:

    • Planning out and splitting up the work between your collaborators before making the changes. Merge conflicts can prevent you from overriding work unintentionally, but can’t tell you which change is the “right” one.
    • Splitting up your Sketch files into more granular pieces (e.g., split a Sketch library and product feature work into separate files).
  • Paste: This design system

  • Console / Flex / SendGrid components: The Sketch libraries for the Twilio Console / Flex / SendGrid (some of this may not be available yet).

Joining or Creating a New Project in Abstract#

Early Access! Early Access! Early Access!

This section will be updated in the future for specific guidance for SendGrid and Flex Product Designers.

  1. After installing Abstract, sync the Console Components project. You may also want to sync all the other projects to be able to easily review and study your peer designers’ work. You can star projects to pin them to the top of your projects list.

  2. To find the right project for the product you’ll be working on, search through existing ones. To create a project, click New Project in Abstract and give your project a name. If it already exists, feel free to skip to "Do a quick font check!"

Guidance on how to name your projects will be provided in a future release.

  1. After creating your project, click into it and create a Sketch file.

  2. Now it's time to import a Sketch Library! To use console symbols in your project, you’ll have to link the Console components Sketch libraries. To do that in your project, click on Add File, then Link Sketch Library...

  3. Select all the Console components files, then click Link Library

Do a quick font check!

Now is a good time to test your fonts to ensure that the components look right! In Abstract, go to the DesignOps project and open Font tester.sketch in untracked mode. Use the Font Tester artboard to make sure your font files have been installed correctly.

You’re all set to work with Abstract and the Paste Sketch Libraries!

Your First Commit in Abstract#

A commit is the way you save your work so it’s publicly viewable to the rest of the team. Any changes you make before you commit are saved locally to your computer and only viewable by you.

Committing is like saving a snapshot of your work. You can always revert your work back to previous commits when you need to, so get comfortable deleting explorations of work! If you commit before and after you delete a bunch of explorations, you’ll be able to find those explorations in the future. More importantly, your files will be easier to grok for anyone who’s looking for the latest version of the work.

How often you might commit depends on the scope of your project. If the scope is to do an icon color change or a typo fix, you might commit for that change only and close out the branch and project. If the scope is much larger (like creating a new component or laying out a sign-up flow), then commits might bundle more changes together. In general, Always Be Committing!

  1. To start work in any project, you’ll create a branch. A branch is a copy of the Master file that lets you make any changes without affecting the rest of the team’s work.

    To create a branch, click Master in the left sidebar and then click New Branch… in the upper right.

Early Access! Early Access! Early Access!

This section will be updated in the future with specific guidance for Flex & SendGrid.

When you’re working in the Console components library, the branch naming convention is:

[JIRA ticket] [description]
For example:
[PROJ-1234] Added a new button
  1. Once you’ve created your branch, go to the Overview tab and add a link to your documentation in the Summary section and a description for context.

  2. To start working in Sketch, return to Files and double-click on a Sketch file.

  3. Once you’ve made changes, you’ll commit your work. It does not affect the Master branch.

    Changes in Abstract are tracked per artboard. If you don’t want to lose track of an Abstract comment thread on an artboard, make sure you don’t delete it (even if you rename another artboard with the same name), or don’t copy-and-paste it and start working off the duplicate.

    To commit, click Commit Changes on the Abstract plugin in Sketch. When working on design system projects, please follow our commit message conventions below.

Commit Message Conventions#

Commit messages are important. You may be tempted to write "updates" as your commit’s description while you're working hard, but will that be useful in six months when you’re trying to find a specific exploration? We recommend using the conventional commit format for messages, which attaches a strict style to commits, and makes them readable: not just for you, but also for your peers!

Commit Message Conventions are Mandatory for Design System Contributions

While we can only strongly recommend what you do in your own Abstract projects, following this convention is mandatory for Design System projects. We'll have to ask you to redo your branch, so please follow this format!

Commit typeCommit message syntaxExample
Add / Edit / Delete Featurefeat: [description]feat: Added a new button
Minor change / typo fix, library cleanupchore: [description]chore: wierd was spelled weirdly
Fixed a broken style or buggy component (no customer change)fix: [description]fix: Applied correct layer style for grey

Creating your own libraries#

Early Access! Early Access! Early Access!

This section will be updated in a future release.

As your projects become more and more complex (or you start working on multiple projects), it may be useful for you to create your own local symbol library for compositions that are specific to your product. We recommend reaching out to the Design System team for guidance.

Coming Soon#

  • Plugin recommendations
  • How to use collections and request reviews
  • Working with Abstract and other tools (Invision, Zeplin, etc.)
  • How to request Guest access to Abstract for your Engineer or PM

Give us Feedback on this Page#

As you use Paste, you’ll likely encounter things that don’t seem right. Please reach out with your feedback! Here are some prompts to consider:

  • Is this page easy for me to consume?
  • Is the information supporting it sufficient / well-described?
  • What information is missing?
  • How approachable is the documentation? Can a new engineer / PM / designer at Twilio get started with it easily?