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
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
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"
}
}