Pinterest web engineers can visit the internal Gestalt documentation.
Set up your laptop
- Install a code editor - we recommended VS Code
Set up your Gestalt repository
- Clone the repo: Fork the Gestalt repo and work off your forked repo, not the
- Once forked, clone to your local machine using the SSH option
git clone email@example.com:<YOUR_USERNAME>/gestalt.git
- Use the correct Node.js version to setup the environment locally
cd gestalt && nvm use
- Install project dependencies. Do not run npm install because it will create a package-lock.json file (and also takes considerably longer).
- Add pinterest/gestalt as a remote upstream (you'll only need to do this once).
git remote add upstream firstname.lastname@example.org:pinterest/gestalt.git
- Check your remote configuration
git remote -v // origin email@example.com:<YOUR_USERNAME>/gestalt.git (fetch) // origin firstname.lastname@example.org:<YOUR_USERNAME>/gestalt.git (push) // upstream email@example.com:pinterest/gestalt.git (fetch) // upstream firstname.lastname@example.org:pinterest/gestalt.git (push)
Set up Visual Studio Code
- Open the new
/gestaltfolder with VS Code.
- Install the suggested VS Code extensions including vs code-stylelint to lint CSS files.
- If you want to automatically launch the docs when you open VS Code:
- In VS Code type
- Search and select Tasks: "Manage Automatic Tasks in Folder"
- Select Allow "Automatic Tasks in Folder"
- Relaunch VS Code
Run the Gestalt documentation server
Whenever you make changes to Gestalt, please test them out locally before making a PR.
To start the documentation server, run
yarn start. In your favorite browser, navigate to .
Create a pull request
- Rebase your local master branch
git fetch upstream git rebase upstream/master
- Create an checkout a branch. Replace the text
<feature-branch>with your branch name
git checkout -b <feature-branch> upstream/master
- Time to make changes to Gestalt! If you are introducing a new component, run the scaffolding command to generate the necessary files. Replace ‘ComponentName‘ with the name of your component.
yarn generate ComponentName
Any subsequent component changes might require the following actions.
- Run unit tests
yarn jest -u
- Run Playwright accessibility integration tests. If any documentation examples are expected to fail accessibility testing, wrap the example in a container with
yarn playwright:test accessibility/
- Run Playwright visual diff snapshot tests. If any component changes are expected to visually modify your component, you must update the snapshot tests. Make sure your macOS version matches the one set in Playwright's config file
# Stop Docs build # Update all Gestalt packages builds running rollup. Make sure to run after every change in component/snapshot test yarn build # Update a specific visual test snapshots with the latest builds yarn playwright:update-visual-test playwright/visual-test/<filename> --update-snapshots
- Update CSS flow types
yarn run flow-generate:css
- If you are introducing breaking changes, create a codemod to help users migrate between versions.
yarn run flow-generate:css
Commit the changes to your branch. Follow naming conventions for the PR
<Component>: <Commit Change Description>
When you are done, push your branch up.
git add . git commit -am "Component: Commit Change Description" git push -f origin HEAD
Go to https://github.com/pinterest/gestalt. A new banner will be displayed, click on 'Compare & Create Pull Request'.
Add useful summary and screenshots. We provide a template for the summary to make sure you include all necessary information.
Create Draft Pull Requestto create your PR. Once you are done committing changes to it, and all the CI tests have passed, click the "Ready for Review" button.
Ensure checks pass on your Pull Request - having the "Require Semver / Test (pull_request)" check fail is expected, because a Gestalt maintainer needs to add a correct semver label. Read our release and versioning guidelines.
After a Gestalt maintainer adds a correct semver label and approves a Pull Request, the PR will be ready to merge. Coordinate with the reviewer to determine when the PR should be merged.
My pull request fails on "Semver / Require Label (pull_request)", how do I fix it?
Nothing you can do to fix it.
A Gestalt Core maintainer will add a semver label (patch release / minor release / major release) when reviewing a PR.
Scope of work
When pushing new changes to GitHub, your PR title should be aligned with the scope of your work. If your goal was to change the default color of a component, keep the scope of changes to that specific task and word the title to exactly reflect those changes.
Changes not allowed
Do not use the following CSS style properties:
line-height: Property in CSS that controls the space between lines of text. Not defining a
line-heightallows the browser to determine line-height based on language which prevents localization issues.
height/width: Height & width are CSS properties that can be used for determining the size of static assets such as an icon size. However, components that contain text data should not fix the height & width of the component to prevent incorrect styling under different cases such as localization, longer texts, etc. Consider other alternatives such as padding to define different component sizes.
- Boolean props: For example, instead of
isEnd: boolean, use more declarative props such as
layoutDirection: rtl | ltror
role: startInput | endInput.
Technical Design Documents
Before starting coding a new component, you must first detail the component specifications in Technical Design Documents (TDD). You can find the TDD template here.
Find the RFCs (request for comments) process and repository here.