Gestalt Design System

In Figma design files, use Groups to combine multiple elements into a single top-level layer when those elements are not intended to be reused across the file.

Key Characteristics:

• The group's bounds automatically adjust based on the size and position of its child elements.
• Child elements inside a group do not require auto-layout or resizing properties.

When NOT to use Groups:

• Do not use groups if you need to implement auto-layout, constraints, or make elements dynamic.

On Pinterest, inspiration refers to anything that sparks a desire to try something new, from everyday recipes to life-changing ideas.

Usage Strategy:

• Use sparingly: Do not pepper the term across every experience. Use it thoughtfully, similar to how the brand limits the use of 'Pinterest red'.
• High-level only: Use it for high-level company descriptions (e.g., "The inspiration company").
• Prefer external validation: It is more effective to let Pinners describe the experience (e.g., "Inspired on Pinterest") than to claim it ourselves.
• Advertiser context: Use it when discussing how businesses provide inspiration to users.

Understanding the stages of an RFC from proposal to implementation:

1. Proposal & Discussion: The RFC is submitted and discussed via Pull Request.
2. Acceptance: The RFC is merged into the repository.
3. Implementation: Authors implement the feature and submit a separate Pull Request for the code. Note that code implementation requires its own review process.
4. Maintenance:
   • If design changes occur during implementation, the RFC must be updated to reflect them.
   • Once the feature is shipped, the RFC should be updated with a link to the Pull Request that implemented it.
   • If authors decide not to proceed, the RFC is removed from the repository.

Use Sections to organize information within pages and layouts by adding labels to guide collaborators through your design file.

Key Characteristics:

• Sections act as layer types that can contain other artboards.
• Constraint: Sections cannot be contained within frames or groups.

Best Practices:

• Do: Use sections to label and organize specific parts of your design canvas.

When NOT to use Sections:

• Do not use sections as a replacement for groups or frames.

Masonry is a generic layout component that manages a grid of items by measuring their heights and calculating their positions.

Key behaviors to note:

• Measurement-driven: It renders items offscreen to measure their heights, uses those measurements to determine layout positions, and then renders them onscreen. This process repeats as users scroll and new items are fetched.
• Generic & Decoupled: Masonry knows nothing about its items and does not communicate with them.
• Constraint on Item Heights: Because Masonry does not communicate with items, item heights cannot change after their initial render. If an item's height changes, Masonry will not be aware of it, which will result in overlaps or gaps in the grid. This is intended behavior to maintain its generic nature.

In Figma design files, Frames are the primary tool for creating dynamic layouts and reusable assets. Gestalt components are always constructed using Frames.

Key Characteristics:

• Frame sizes are set independently of their child elements (unlike Groups).
• Moving or scaling child elements does not automatically adjust the frame's bounds.

Best Practices:

• Do: Use frames to construct components or any reusable assets.
• Do: Use frames to control padding, margins, and spacing.

When NOT to use Frames:

• Do not use frames if your elements are not reusable across the file and you do not require dynamic controls.

The GlobalEventsHandlerProvider is a utility used to share external logic (such as logging or analytics) with interactive Gestalt components. It works by passing handlers down unidirectionally from parent to child. You can define specific handlers for different component types (e.g., buttonHandlers, linkHandlers) to intercept events like onClick, onBlur, or onFocus.

To avoid code duplication when using multiple providers in different parts of your application, it is recommended to encapsulate your handler logic within a custom React hook.

// Example of providing button-specific logging logic
<GlobalEventsHandlerProvider
  buttonHandlers={{ onClick: ({ name, surface }) => log("button", "campaign_form", name, surface)}}
>
  {children}
</GlobalEventsHandlerProvider>

The GlobalEventsHandlerProvider works by exposing a context that components can consume via a hook (e.g., useGlobalEventsHandlerContext).

When a Gestalt component (like SheetMobile) is rendered, it checks the context for its specific handler prop. If handlers are present, the component executes them during its lifecycle (for example, inside a useEffect for mounting/unmounting or during an onClick event).

Mental Model:

• Provider: Defines what should happen when an event occurs.
• Component: Defines when that event occurs (e.g., onOpen, onClose, onClick).
• Decoupling: This allows the core Gestalt component to remain agnostic of specific business logic (like Pinterest's impression tracking) while still allowing that logic to be executed seamlessly.