## File: README.md # [Gestalt](https://gestalt.pinterest.systems/) · [](https://www.npmjs.com/package/gestalt) [](https://github.com/pinterest/gestalt/blob/master/LICENSE) Gestalt is Pinterest’s design system. Our system includes a React component library with comprehensive guidelines, best practices, tools, and resources to support designers and engineers delivering a high-quality product. [Visit the official Gestalt Documentation](https://gestalt.pinterest.systems/) ## Installation The package can be installed via npm: ```bash npm i gestalt --save npm i gestalt-charts --save npm i gestalt-datepicker --save ``` Or via yarn: ```bash yarn add gestalt yarn add gestalt-charts yarn add gestalt-datepicker ``` ## Usage Gestalt exports each component as ES6 modules and a single, precompiled CSS file: ```js import { Text } from 'gestalt'; import 'gestalt/dist/gestalt.css'; import 'gestalt/dist/gestalt-datepicker.css'; ``` That syntax is Webpack specific (and will work with Create React App), but you can use Gestalt anywhere that supports ES6 module bundling and global CSS. ## Development Gestalt is a [multi-project monorepo](https://yarnpkg.com/lang/en/docs/workspaces/). The docs and components are all organized as separate packages that share similar tooling. Install project dependencies and run tests: ```bash yarn yarn test ``` Build and watch Gestalt & run the docs server: ```bash yarn start ``` Visit [http://localhost:8888/](http://localhost:8888) and click on a component to view the docs. ## Codemods When a release will cause breaking changes — in usage or in typing — we provide a codemod to ease the upgrade process. Codemods are organized by release in `/packages/gestalt-codemods`. ### Codemod Usage Clone the Gestalt repo locally if you haven't already. Run the relevant codemod(s) in the relevant directory of your repo (not the Gestalt repo): anywhere the component to be updated is used. Example usage for a codebase using TypeScript: ```bash yarn codemod --parser=tsx -t={relative/path/to/codemod} relative/path/to/your/code.tsx ``` For a dry run to see what the changes will be, add the `-d` (dry run) and `-p` (print output) flags (pipe stdout to a file for easier inspection if you like). ## Releasing Every commit to master performs a release. As a reviewer, ensure the correct label is attached to every PR. Please follow [semantic versioning](https://semver.org/). - `patch release`: documentation updates / spelling mistakes in code / internal scripts - `minor release`: add component / add component props / API change with codemod - `major release`: backwards incompatible API change without codemod Example PR title: `Avatar: Add outline prop` ## Typescript Support Gestalt officiallty supports and maintains Typescript declarations files. ### Issues Gestalt is Pinterest's open-sourced design system. However, Gestalt's web component library is almost exclusively developed by a 5 engineer team within Pinterest, and our primary customers are Pinterest engineers who use Gestalt. The team’s priority is the needs of our internal Pinterest customers. We do not have resources to work on features or issues requested only by external developers. We also handle a very large amount of internal support requests, so we do not have the resources to respond to external Github issues. Pinterest is staying open source, as it's a great resource for the design and engineering community, but we don't provide support to external developers. If you need to get in touch, send us an [email](mailto:designsystems@pinterest.com?subject=Github%20Request%3A). ### Troubleshooting Take a look at our [FAQ](https://gestalt.pinterest.systems/get_started/faq) section if you run into any development problems. --- ## File: docs/examples/README.md # How to create or convert Sandpack examples 1. Create a new folder within this folder (/examples), matching the file name for the relevant page. 1. Create a new file for each code example, using a descriptive name. _Note: We usually use `main.tsx` for the top-level example on a component page._ 1. Build your example, or copy-paste the code from the existing example. You'll probably need to wrap the output in `` to center it within the Sandpack view. \_Note: Don't import `React`, but only what you need specifically. 1. Import your example into the relevant docs page file, then replace the existing example (or add your new example) using the SandpackExample component. _Note: Don't forget to set the `previewHeight` if necessary. Be sure to set `hideEditor` for the top-level example on a component page and for Best Practices Examples. "Don't" Best Practices examples should also include `hideControls`._ --- ## File: docs/markdown/team_support/design_file_hygiene/design_handoff.md --- title: Design handoff fullwidth: true --- When your design file is ready to hand off for development, we ask you to follow the best practices below to make it super clear what designs need to be implemented. We've created a library to facilitate your design handoff process by providing tips, annotation assets, design specs, and ready-to-use components. You can enable our [Handoff Kit library](https://www.figma.com/file/50RRYnFcgPTQzy1AIjQoWB/%5BLibrary%5D-Gestalt-Handoff-Kit?node-id=249%3A517&t=3H5nmocXTsIKd8sf-1) in your Figma files and get all its benefits. ## Adding covers to files The cover should have all the essential information to help design system users understand its context. It includes: the project type, title, related Jira ticket and platform, status, and owner. We recommend using our [Handoff Kit](https://www.figma.com/file/50RRYnFcgPTQzy1AIjQoWB/%5BLibrary%5D-Gestalt-Handoff-Kit?node-id=249%3A517&t=3H5nmocXTsIKd8sf-1) **Cover component** when adding covers to design system files. Standard covers will keep our files consistent and make scanning for Gestalt's resources easier. ## Annotations Use our annotation tools to clarify your design with engineers and product managers. See below our available annotation components: **Accessibility annotations**: Assets to make documenting accessibility easy **Contextual notes**: Problem statements and any contextual information cards **Flow notes**: Annotations to clarify features, design decisions or highlight something in your layout **Sticky notes**: Post-it notes for comments, thoughts and any feedback Our annotations work in both themes, light and dark mode. ## Flows and gestures Use the flows assets to show how one screen flows to another. Use the gestures assets to indicate swipes, pans and zooms. Similar to our annotations, the flows and gestures assets work in both light and dark themes. ## Handoff structure When creating handoff pages, it’s important to begin with control surfaces, or in other words, how things currently appear. Handoff can happen multiple times, and we use Emojis to distinguish status of the design iteration, like listed below: 🤝 Latest signed off version ✏ WIP (work in progress) handoff page ### Best practices - Name your final design page as Handoff, prefixing the page name with the appropriate Emoji - Nest pages to make them more readable (just add 4 spaces before the page name, extra spaces adds more indents) - If a handoff version goes out of date, add a version label like **v1**. Do as many versions as you need. - Use generic names for final design handoff pages - Use random Emojis. Using the suggested Emojis will help us to identity your work progress See below an example of how we name handoff pages on Figma: ### Final considerations Ensure you meet the criteria below before sending your design for development: - Handoff pages follows Gestalt's recommendation - Files have a control section, meaning displaying the current design for reference - Use of annotations - Usse of connectors to indicate user flows - The design doesn't present accessibility issues - Run the [Pinterest Design Figma plugin](https://www.figma.com/community/plugin/1215463263194174399) You can find all the assets and guidance in our [Handoff Kit library](https://www.figma.com/file/50RRYnFcgPTQzy1AIjQoWB/%5BLibrary%5D-Gestalt-Handoff-Kit?node-id=249%3A517&t=3H5nmocXTsIKd8sf-1). --- ## File: docs/markdown/team_support/design_file_hygiene/figma_branches.md --- title: Figma branches fullwidth: true --- We suggest using Figma branches when collaborating on Gestalt design projects. For example, adding a new component or variant or modifying a Gestalt style or pattern. Branches enable designers to safely try new ideas without changing the main or existing Gestalt file. Rather than auto-saving to the main file, changes from branches are merged into the main file when they are ready to go. Check out this [Figma guide to branching](https://help.figma.com/hc/en-us/articles/360063144053-Guide-to-branching) to learn all about creating branches. ## Naming a branch Branch names should follow the format: designer initials-Jira ticket number-brief description of change or task. We use dashes to separate the words (e.g., **CR-4536-IconButton-android-specs**, CR stands for Cintia Romero) . The initials and Jira ticket name will support with context of the task and how it relates to our roadmap.If there isn't a ticket number available, it should be: designer initials-brief description of change or task (e.g.,**CR-fixing-Badge-color**) ## Requesting a Gestalt review When your new branch is ready for review, we ask you to follow the process below: - Add 2 designers form the Gestalt team as reviewers. A primary, and a secondary reviewer - If relevant, add a designer from the design feature team - Add the description of your work, such as the objective of your design and any relevant highlights ### Aproval criteria Reviewers will approve the branch after it meets the criteria below: - Taxonomy for component is consistent for all platforms it effects - All naming convention criteria listed above have been met - All Gestalt styles are linked corrected (text, colors, shadows) - There are no remote styles conflicting with Gestalt styles - There are no accessibility concerns on the design - Included annotations and flow assets are connected to the Handoff Kit library ### Gestalt reviewers When requesting a branch review, prioritize as the "primary reviewer" the person with expertise in the area you need approval. See below the team members and their primary areas of expertise: - **Cintia Romero**: Components Figma structure, colors and themes - **Hector Jaime**: m10n components, data visualization, messaging/notifications and patterns - **Layla Leal**: Product Surfaces matters - **Kate Halvorsen**: Mobile components and illustrations - **P.J. Onori**: XFN branch collaboration and any situation not listed in the above 4 bullets - **Ravi Lingineni**: Plugins and any situation not listed in the above 5 bullets **Please note:** Any other Gestalt designer could be added as a secondary reviewer. --- ## File: docs/markdown/team_support/design_file_hygiene/naming_convention.md --- title: Naming convention fullwidth: true --- Keeping our design system files consistent is essential to facilitate design handoff and comprehension. Therefore, we ask designers to follow the standards below when contributing with Gestalt on design files, such as naming convention. Even if you aren't contributing our systems files, you can still use these standards as a reference to keep your feature files organized and easy to understand by cross-functional partners. A descriptive name matching a semantically named component aids the discoverability of our components and system assets. By ensuring file hygiene, we level up the quality of our design files, making it easier for our design systems users to manipulate our components and guidelines. ## Components All components should use the [PascalCase](https://www.theserverside.com/definition/Pascal-case) convention matching our docs and codebase style. (e.g., ComboBox, IconButton, RadioGroup) The platform name is added to the end of the component name starting with a "."; it helps to facilitate the search in our assets panel. The platform name uses a lower-case convention (e.g, Toast.web) ### Private components All private components should be prefixed with a period "." (e.g., .BannerUpsell/Visuals.web) You can hide components when you publish changes to your Team library, or from a library you have already published. You can only hide components from the file they originate from. Adding a period will prevent the component from being published to all designers, avoiding clutter in our assets panel. The private component will still be visible under our components page and through the Hidden panel in the Figma library file. Check out this [Figma article](https://help.figma.com/hc/en-us/articles/360039238193-Hide-published-styles-and-components) to learn more about hiding components. ## Emojis We only use Emojis to separate page sections, making it easier to scan the content. (e.g., 🧑‍🎨 Design explorations, 📔 Cover). We ask to be mindful of the use of Emojis. They are fun, but when overused they could lead to cognitive load issues and make the content difficult to digest. Avoid using Emojis when naming layers, unless it is highly necessary to support comprehension. ## Icons We aim to align our icon naming convention with how we display our icons names in our web docs. All names should follow a lower case style and we use a dash to facilitate the reading if the icon has two or more words. (e.g., heart, heart-outline). ## Layers We don't have a default case-type defined to name layers as long as the component follows the proposed naming convention [(PascalCase)](https://www.theserverside.com/definition/Pascal-case). However we suggest following the best practices below when naming your layers: - Give meaningful context to the text layers (e.g., Item name, Label) - Name shapes and vectors purposefully (e.g., Divider) - Give description to images layers for easy comprehension and reference (e.g., Brand collage) - Name frames, groups and sections relating them to the design in context (e.g., partner logos) - Be kind and limit the acronyms, or omit them all together when layer naming - Use generic or vague names (e.g., Text 01) - Use Figma generated shapes and vector names (e.g., Ellipse 2) - Use images raw names (e.g., Screenshot 2023-04-26) - Use non-related or vague names (e.g., Group 7, Frame 220) - Use acronyms or Emojis on layer names --- ## File: docs/markdown/team_support/design_file_hygiene/organizing_layout.md --- title: Organizing layout fullwidth: true --- Here are some tips on using groups, frames, and sections to organize design system Figma files. Creating a well-structured Figma file template makes it easy for collaborators and viewers of the systems file to navigate and quickly find what they need. ## Groups Groups allow you to combine multiple elements together as a single top level layer. A group's bounds are determined by its child elements, so resizing or moving those elements will cause the group's bounds to adjust automatically. - Use groups if the elements inside your group aren't reusable accross your file. - The elements inside the group don't need auto-layout and resizing properties. - Use groups if you need to set auto-layout and constraints, and make elements dynamic. Learn more about [Figma groups](https://www.figma.com/best-practices/groups-versus-frames/?fuid=982037494021279625) and how to set up them. ## Frames Frames allow you to create dynamic layouts on Figma. Differently from Groups, frame sizes are set independently from their child elements. When repositioning or scaling child elements inside a frame, its bounds will not auto-adjust. **We always use Frames to construct our Gestalt components.** - Use frames to construct components or any reusable assets. - To control padding, margins, and spaces. - Use frames if you don't need dynamic controls and your elements aren't reusable acrros your file. Learn more about [Figma frames](https://www.figma.com/best-practices/groups-versus-frames/frames/) and tricks to get up to speed. ## Sections Sections allow you to organize your canvas by adding labels, and to guide collaborators through your file. Use Sections for organizing information inside your pages and layouts. They work as layer types allowing to add and organize other artboards inside. **Please note**: Cannot be contained within frames or groups. - Use sections to organize your canvas by adding labels to specific part of your design. - Use sections to replace groups or frames. Learn more about [(Figma Sections)](https://help.figma.com/hc/en-us/articles/9771500257687-Organize-your-canvas-with-sections) and its best practices.