Paste

Paste is a design system used to build accessible, consistent, and high quality customer experiences at Twilio. Paste is open source and contributions are welcome.

Usage

For usage guidelines, please see our documentation website.

Developing on Paste

Getting started

Clone the repo then run the following commands from within the repo's folder:

yarn clean # bootstraps the repo and downloads packages
yarn build # builds all of Paste

Then you can run a local storybook instance with:

yarn start:storybook

For more commands, please reference the package.json file.

Contributing

Before contributing, please make sure that you read our Contributing Guidelines and agree with our Code of Conduct.

Maintainers

This project is maintained by the design systems team.

Hosted Storybook

Storybook

We use GitHub pages to host the Storybook instance. We use the gh-pages branch and the gh-pages package to manage this.

The gh-pages branch ignores everything other than the built storybook instance in the root of the directory. The package handles everything.

Updating

🚨🚨🚨 This is now done in our CI/CD process 🚨🚨🚨

To update this we simply run the gh-pages package from yarn by using the release:storybook task.

yarn release:storybook

This task will build the storybook, switch to the gh-pages branch, commit the changes from the storybook build and push to GitHub.

Dependencies

Paste is a monorepo and has some specific requirements in how it handles dependencies.

Dev Deps

Each package can have dev dep requirements, such as typescript and rollup. As this is a monorepo using yarn workspaces there is no requirement to list these as package dev deps. All dev deps are hoisted to the monorepo root. Declare them at the root package.json file.

Peer Deps

A special note about peer deps: Peer dependencies should be hoisted up the dependency tree. If package-a lists package-b as a peer dep, and package-b lists package-c as a peer dep, package-c must also be listed as a peer dep for package-a. All the way down the tree.

A real example might be a Button. Button may only have a peer dependency on Box, but Box has a peer dependency on Theme, Design-Tokens, and Style-Props. These child peer deps need to be hoisted to the Button package. As such Button deps should look like:

{
  "name": "button",
  "peerDependencies": {
    "@twilio-paste/box": "^0.0.1",
    "@twilio-paste/theme": "^0.0.1",
    "@twilio-paste/design-tokens": "^0.0.1",
    "@twilio-paste/style-props": "^0.0.1"
  }
}

Internal Deps

When a package has a peer dependency on another internal package in the mono repo, it must also be listed as a dev dependency for compilation.

Example:

{
  "name": "button",
  "peerDependencies": {
    "react": "^16.8.6",
    "react-dom": "^16.8.6"
    "@twilio-paste/box": "^0.0.1",
    "@twilio-paste/theme": "^0.0.1",
    "@twilio-paste/design-tokens": "^0.0.1",
    "@twilio-paste/style-props": "^0.0.1"
  },
  "devDependencies": {
    "@twilio-paste/box": "^0.0.1",
    "@twilio-paste/theme": "^0.0.1",
    "@twilio-paste/design-tokens": "^0.0.1",
    "@twilio-paste/style-props": "^0.0.1"
  }
}

License

MIT

sebm / paste