Gestalt

Pinterest is a visual discovery engine for finding ideas like recipes, home and style inspiration and more. This is done via native mobile and web apps.

Design System Name

• Gestalt

Design System team size

• More than 10

Design System team make-up

• Designers
• Engineers
• Product Owner/Manager
• Design Technologists

Governance model

• Hybrid

Level of documentation

Level of detail 

• Anatomy
• Behaviors
• UX rules
• UI rules
• Tone and voice
• Usage guidelines
• Writing guidelines
• Accessibility guidelines
• Content guidelines
• Tech guidelines
• Options
• States
• Related patterns
• API
• Props
• Implementation
• Motion

Brand elements

• Colors
• Fonts
• Icons
• Illustrations
• Photographs
• Layouts + grids
• Radius
• Shadows
• Motion
• Borders
• Spacing
• Brand expression
• Accessibility
• Data visualization
• Charts and graphs

Components

• Actions (buttons, links, etc)
• Alerts (pop-up, snackbar, toaster, etc)
• Content and lists (cards, accordion, divider, etc)
• Data (charts, tables, etc)
• Forms (radio, checkbox, dropdown, inputs, etc)
• Media (video player, podcast, etc)
• Navigation (header, footer, tabs, etc)
• Status (progress bar, badges, loader, etc)
• Utilities (to accomplish specific tasks)
• Text, Headings and icons

Documentation architecture overview

• Our documentation architecture is articulated in 3 levels: top header tab navigation, left navigation for the content of each tab when needed and a page-level table of contents for skipping to sections of a page. There is also a toggle on the left navigation to view components for web, iOS and Android. Finally, our home page also contains links to primary elements and categories. We also provided a “visual search” way of navigating via graphic tiles on Overview pages.
• We have primary categories for Getting started, Components, Foundations, Support, Road Map and What’s new. Under each category, we then have subcategories. For example, “Get started” is divided into subcategories for Developers and Designers. Our Foundations are divided into the main foundational design elements and patterns, like Iconography, Typography, Color‌ and Content standards. Those are then subdivided as necessary. Content is divided into Voice, Formatting, Grammar, UI Elements‌ and Syntax and Structure. We strive to be as granular as possible so people can find what they are looking for via discoverable navigation and search queries. Finally, for components, people can view based on platform: web, iOS or Android.

Who document

• Designers
• Engineers
• Brand
• Product Owners

Documentation process

We document changes weekly. Components are documented based on when they are requested and when we decide to build them based on the larger product and engineering organization’s road map. Code updates are continuously deployed. Foundations, patterns and the road map are documented quarterly.

We maintain a backlog in JIRA to start with. Once we decide to document, we have Coda page templates for components and patterns. We start by drafting the written documentation in Coda. A handoff spec and file are prepared for engineers in Figma. For Android and iOS teams, those specs are embedded in the site documentation for easy reference. Once documentation is ready, internal and external stakeholders are involved in the feedback and commenting process. How long this goes depends on how fast something needs to get out. Sometimes, we go with the first version with minimal feedback, then iterate as we receive feedback once the documentation is out. For documenting recently added patterns or to solve issues that arise post-documentation—such as confusion around naming—we’ve conducted cross-functional workshops and research. But, this is done on an ad hoc basis. We also accept contributions from external teams. For this, we field an initial request via JIRA, have a kickoff meeting, introduce those Team members to our templates and then provide feedback as these teams provide drafts in Coda or Google Docs. Once the contribution is in a good state, we publish the documentation on our site. The documentation is implemented using VS Code and Github by designers and engineers. Throughout this process, we work in 2-week sprints.

Maintenance and contribution

We file JIRA tickets when updates need to be made. Then we plan them out in sprints. Quick updates like typos or missing information are done as they arise. When we update, we always run accessibility tests and once done, we create a pull request in GitHub that goes through a thorough design and engineering review.

We engage with external teams via our Slack channels and encourage them to suggest contributions to our documentation and to always point out places where we need to improve. We send out bi-yearly surveys on sentiment. We also have a Figma plug-in where people can view the documentation inside of their Figma files so that they are continuously engaged with our docs.

On the design part

To start, we bake as many design elements into our components so that designers and engineers don’t have to worry about low-level decisions like what a color or border radius should be or what colors pass accessibility contrast requirements. Regarding how components then fit together to create a good experience, our documentation provides usage guidelines and visual examples so that designers can make informed decisions on what, how and when to use certain elements. For example, our data visualization color palette includes a section on how to pair colors in charts, what colors to use for categorical data and what colors to avoid.

On the tech part

Our documentation is very detailed for engineers. It includes guidelines for installation, contributions and performing unit tests, including running accessibility tests. We always show the underlying code for components and all of the available properties. Finally, we do include design guidelines and brief details on why decisions were made in the component documentation. There are times when an engineer doesn’t have design support, so this helps them make decisions without a designer.

Overall

We not only provide examples of how to use components, we also explain why we are making these recommendations and provide suggested alternatives. For example, we don’t say things like “Don’t center align paragraph text”. Rather, we include a note as to why it’s not good to center-align text—it’s hard to read, especially for people with dyslexia. We also provide examples that can be tested within the site so that people can play with them and understand how the component functions, and if it fits their needs. Finally, our documentation includes a primary navigation item for support so that if people still have questions, they can easily contact us to get unblocked.