How to Work with Us

Guidelines on how to engage the Gestalt team, when to work with us, and how to contribute.

What goes into Gestalt?

The goal of Gestalt is to create a shared library of design best practices, React components, and documentation. Therefore, the best contenders for addition to Gestalt are designs or components that benefit multiple teams and are used regularly throughout our products.

What is the process to request new additions or changes?

Please note: The process below applies to Pinterest employees.
What we build into Gestalt comes from the teams across Pinterest, so we’d love to pair with you early and often! The process starts in the design phase. Seeing early mocks, wireframes or even product roadmaps in our partnership meetings to learn where your project may be going helps inform our team OKRs. The earlier we see the work, the better we’re able to plan and the higher the likelihood we’ll be able to help.
We ask that any ideas that change the functionality of an existing Gestalt component or introduce a net-new component go through the following process:

  1. Present work early in our partnership meetings
    • Explain project goals and show multiple options explored with and without Gestalt components to help us understand your needs.
    • Coordinate with other designers if there are overlapping needs to help us better prioritize in our roadmap.
    • Be able to explain how this component should be used or not used. This helps us in testing the component against existing components and product surfaces.
    • Have a rough project timeline available. This allows us to determine if we’re able to accommodate the work.
  2. Iterate on solutions
    We love to see more iteration from the product designer asking for the component, if they have the time. If not, the component will follow our prioritization process. The designer (product designer or Gestalt designer) must ensure all edge cases have been considered.
  3. Prioritization by the Gestalt team
    If our team takes on the work, we will add it to our backlog and prioritize it appropriately. Typically the determining factor for taking on work is capacity: if your designers or engineers have the capacity, we’d love for them to contribute to Gestalt with our support. Otherwise, the Gestalt designers and engineers will prioritize the work against our current workload based on the following criteria.
    Some questions we ask ourselves when prioritizing:
    1. How many products/surfaces will benefit?
      • Ideally, we build things into Gestalt that 2 or more teams need with more teams meaning higher priority.
    2. How easy or difficult is it to build?
      • How many engineering hours will it take to build?
      • Are there accessibility concerns that should ideally be handled by Gestalt?
    3. Is it a dependency to other future work we need to do within Gestalt?
      • Will this unlock additional functionality that other teams need?
        We prioritize work following the same cycles as product teams within Pinterest. Knowing other teams needs before prioritization starts will help inform our roadmap. If we do no have capacity for the work, but believe we should add it to Gestalt, we may ask if a product team can continue the work. Otherwise, it will go into our backlog.
  4. Build or follow along
    Our engineering team will pair directly with your engineer if they are the ones who will be taking on the work and help them follow the process below. If the Gestalt team is building the component, we will take on the work and follow the same process. As we develop the documentation, Figma files, and code for the updated or new component, we’d love for you to help review and be part of a final sanity check.

How can you contribute to Gestalt?

Making a design contribution

We love the help and contributions of other designers across Pinterest, and we ask that any ideas that change the functionality of an existing Gestalt component or introduce a net-new component go through the following process:

  1. Present your idea or suggestion during our Office Hour meetings
    Sign up for an Office Hours slot! Explain project goals and show multiple options explored with and without Gestalt components to help us understand your needs. This does not need to be a polished presentation, but should have enough detail that we understand the request and why it is needed.
  2. Create a Branch in our design library
    Create a Branch file in our main file. Don't worry, our design team will support you with that. See Branching in Figma for more details and self-education.
  3. Present your work in a Design System Crit
    After your Branch file is ready, our design team will schedule a meeting to present your work.
  4. Send your Branch to review
    Update your Branch based on the feedback you received, and add a Gestalt reviewer (designer) to your Branch. Our design team will approve and merge the Branch when it is ready to implement in our web docs. We will follow up with you!

Making an engineering contribution

We always appreciate the help and contributions of other engineers across Pinterest, whether it's new variants, simple bug fixes or building out entire components. Before any code changes happen though, be sure to follow our request process.

  1. Talk to your designer
    Check in with your designer and make sure the changes have been approved by the Gestalt team, via the request process. We don’t recommend starting a PR on new functionality — no matter how small — without confirming this, as you may spend time on changes that won’t be approved to merge into Gestalt.
  2. Technical Design Doc
    Create a technical design doc (TDD), using this template, for any net-new components or component additions/updates within Gestalt. This allows everyone to discuss the component API and functionality before starting to build.
  3. Implement and Test
    Once the TDD has been finalized, it's time to build! If creating a new component, check out our scaffolding script. Don't forget about tests! If updating an existing component, please remember to update/add unit tests. Use .test.js to test UI and .jsdom.test.js to test interactions. Note that accessibility integration tests cover both the component itself and the related docs page. Run the test suites using the package.json scripts.
  4. Pull request
    When your work is complete and all tests are passing, make a draft pull request for your changes by following the development guidelines. This will start the CI process, running a variety of tests. Once those tests are passing (aside from the semver one), mark your PR as "Ready for review" and ping us on #gestalt-web. Your changes will be reviewed by an engineer and a designer from the Gestalt team. We ensure each component is built to spec, accessible, performant and works well with other components.
  5. Release
    Now the fun part: releasing your component! After a Gestalt team member merges your change and Pinboard has been updated, feel free to announce your component/changes on the #gestalt-web Slack channel.

Other ways to contribute

Bugs
If you think you’ve found a bug with Gestalt components or documentation, first check our Gestalt Bugs Dashboard to see if it’s already been reported. If it hasn’t, please file a bug within the Bugs Jira project and set the Component to ”gestalt”. We do not actively monitor GitHub issues, so the best way to file is through Jira.
Surveys
The Gestalt team sends out twice-yearly surveys to the design and engineering orgs. Filling out this survey is one way to help inform our team on what is working and what is not working about out design system.

What kind of support can you expect from the team?

We are always happy to help answer questions regarding Gestalt component design and usage, design system best practices, accessibility, icons and colors. If it’s part of Gestalt, we’re here to help! If it’s outside of the realm of our design system, we’ll try our best to answer and/or point you to the person who can. Feel free to reach out to us on Slack anytime.
We also offer documentation on this site (go/GestaltWeb) and a Figma library of components that exist within Gestalt.

Resources, Slack, and Meetings — oh my!

Dashboards, Jira, and OKRs

If you’re curious what we’re working on, you can check out our Gestalt Sprint Dashboard, our full backlog, and our Bugs Dashboard.
To see the bigger picture, you can view our OKRs to understand our roadmap and priorities for each quarter. These priorities are determined through partnership meetings, which we use to learn about component needs and coordinate with designers to determine timelines.

Slack channels

Before reaching out, take a look at our documentation to see if it answers your question, because it will likely get you the fastest answer. Still need help? Try searching Slack for your question, and then feel free to ask if your question hasn’t been answered in the past. You can also reference our Communication Guidelines for more info.
#gestalt-design is for design-focused questions.
#gestalt-web is for engineering-focused questions.

Meetings and events

Our meetings, events, and timelines can be found on the Gestalt Event Calendar. We offer two different meetings for the community to bring questions, comments, ideas, and feedback:

  1. Gestalt Office Hours
    • Purpose
      For product designers seeking feedback on their usage of design systems and visual language. This is also a great time to propose new components or component changes.
    • Audience
      Primarily Pinner and M10n designers, though engineers are welcome if there are technical concerns as well.
    • Cadence
      Twice a week on Tuesdays and Thursdays. Please sign up for a half-hour slot with your discussion topic.
  2. Component Crit
    • Purpose
      For systems designers seeking feedback from the larger design org on systems-related designs.
    • Audience
      Pinterest designers and Gestalt engineers. The agenda for the Crit can be found in the recurring calendar invite. Please continue to bring component work to Office Hours.
    • Cadence
      Every other Friday. Please sign up through the link in the calendar invite.
Edit page on GitHub