Builder

Builder

Declaratively build and visualize applications and business processes.

Builder Guidelines

Introduction

A builder is a tool that lets everyone from developers and admins to business users create and customize applications and business processes. Developers and admins use builders that create interfaces for their business users, including Lightning App Builder, Community Builder, Bot Builder, and Flow Builder. Business users can also create experiences for teams or customers using tools such as Journey Builder and Engagement Studio.

Design Resources

  • SLDS Component Library
  • SLDS Pattern - Builder
Download Sketch Kit

Usage

When should you think about using a builder? Start, as, always, with the user. If users will be doing one or more of these things, there could be a builder in your future:

  • Working with WYSIWYG (“what you see is what you get”) declarative elements that can be added with clicks and customized with forms
  • Designing a business process on a blank canvas
  • Creating and defining a series of logical actions that result in different outputs
  • Defining the relationship of one element to another—for example, in a workflow or visual layout
  • Saving and tracking multiple drafts or versions

If a builder isn’t a good fit, consider using another framework, such as a modal wizard, Channel Studios on Marketing Cloud, an expression or formula builder, or a series of filters. If you’re working with templates, consider forms or studio editors.

Workflow

Where to Launch a Builder

Are you an admin or developer designing for your Salesforce users? If so, any builder you design should live in Setup. Make sure that your builder can be accessed from a Setup page and from the Setup navigation.

Outside of Setup, make builders accessible from a relevant record detail page or app landing page. For example, make a builder that creates a new workflow for email engagement accessible from both the email engagement record detail page and the email engagement app page.

Record Information: Names, Versions, and Statuses

When you’re ready to launch a builder, the journey often starts on a record list page, where you’ll find a clear summary of file names, versions, and statuses. Display this information in the builder as well. Record information must be displayed in three areas:

Record List

Display the file name, version, and status in a list among other similar builders.

Builder Home stenciled layout with global navigation bar, application navigation bar, lefthand tools panel and search box, and detailed results on the right.
Builder Home Layout

Record Detail

For each record, provide a dedicated view of its file name and version(s). This orients users without making them return to the builder.

File Overview stenciled layout with global navigation bar, application navigation bar, lefthand tools panel and search box, and detailed results on the right.
File Overview Layout

Builder Header

This header must display the builder name, file name, and save status. Read more here.

Builder Header with Builder Name, File Name, and Version Number in the header and a button bar below.
Builder Header Layout

Saving Builder Records

When working in a builder, users tend to save their changes often. Some builders also let users activate, run, or publish.

Saving is a server-side snapshot of an object and its state. Note that saving does not inherently equal approval to push an object for activation or publication. These are two separate actions that do two different things. If saving does activate/publish a file or execute a process, be sure to explicitly call this out to the user.

When and how can I save my builder objects?

  • Use a Save button to initiate a server-side save of the entire object.
  • When a builder uses manual saving, users should be allowed to save even when their work contains errors. See Error and Warning Popovers for more information on messaging.
  • When a save also triggers activation/publication, allow the file to be saved without push. Alert the user to errors blocking activation/publication.

What about object versions?

  • Builders may allow for object versioning. If your builder allows versioning, offer users the ability to clone or copy objects through a Save As command.
  • If a builder autosaves (and creates auto-versions for each save), batch changes in an autosave and a new version. And always give users an easy way to view and revert to previous versions.
Stencil of a Builder Header with a Save As and Save button in the toolbar.
Use Save button for server-side saving. Use Save As to create a new version.

How does saving work when multiple records are open?

  • Multiple records can be viewed simultaneously in new browser windows or tabs.
  • An explicit save affects only the record currently in focus—not other open records.
  • When closing a browser window with any unsaved records, users should see a warning that they will lose all unsaved changes.

Autosave

No Salesforce builders currently use autosave. However, here are four principles to consider if and when the feature becomes an option.

  • Confidence: Make clear what is and isn’t saved at all times. Can an autosave offer the trust of an explicit save button?
  • Simplicity: How are previous versions presented? Reinstated? What is a simple, easy, and on-pattern way for users to perform these actions?
  • Data: Where do autosave versions live? Do they affect a user’s data limits? Are both users and Salesforce prepared to deal with the data implications?
  • Performance: What effect will constant saving have on performance? Are the benefits of autosaving and versioning enough to outweigh any lag?

Indicating Save Status

Clearly communicate save status, but without overwhelming users or drawing focus from the task at hand.

  • Show status with an inline indicator next the builder header action buttons: Saving... (save in progress), Saved, or Saved [time] (indicating when the file was last saved).
  • Don’t use toasts or banners for save messages. When users save often, toasts can be disruptive. Banners are reserved for systemwide messages.
Builder page stenciled with a in-progress spinner animating in the center of the page.
Builder Saving in Progress
Builder Header stenciled with a small notification message: (Checkmark) Saved.
Save Successful
Builder Header stenciled with a small notification message (Saved 5 mins ago) and a popup with the message: Last modified on June 1, 2018 by SysAdmin.
After a Successful Save
Builder Header stenciled with a small notification message (Saved 45 mins ago), a warning icon, a stop icon, and a popup with the message: Last modified on June 1, 2018 by SysAdmin.
After a Failed Save
OrderMessageTime on ScreenTransition/AnimationNotes
1Saving...Time needed to complete taskOpacity 0.25s ease-in animate the "..."Block canvas from further editing with an overlay and spinner.
2, if successfulSaved4.8s (same as toast)Opacity 0.25s ease-inUse a green checkmark icon next to the Saved text, as shown.
2, if failedSaved [time] (Seconds, minutes, days, months, years)4.8s (same as toast)Opacity 0.25s ease-inUse lightning:relativeDateTime to show previous successful save. Include relevant warnings and errors in popovers. See the popover section for more detail.
3Saved [time] (Seconds, minutes, days, months, years)PersistentOpacity 0.25s ease-inUse lightning:relativeDateTime

Activating or Publishing a Builder

Most builders separate save functionality from publication/activation, allowing users the freedom to edit without affecting runtime or live business processes.

Place the Activate or Publish action at the right side of the builder toolbar, with other action buttons. If the needs or technical limitations of your builder make that difficult, you may also place this action on the Builder Home or Record Overview pages.

Stencil of a Builder Header with Active, Save As, and Save buttons.
Activate Action Button

Activation and deactivation are significant milestones—use a toast to notify users of success, failure, and related warnings or errors.

Stencil of a Builder Header with Active, Save As, and Save buttons and a green toast notification with the text: Activation Successful.
Stencil of a Builder Header with Active, Save As, and Save buttons and a red toast notification with the text: Activation Failed.

Exiting a Builder

To exit a builder, users can close the browser window or hit the back button in the Builder Header. They should be brought back to the page initially used to launch the builder.

Stencil of a Builder Header with a Back button in the top right.

Builder Parts

A builder is made up of a set of parts, some commonly used and others unique to specific builders. Lightning Design System has markup ready to use as component blueprints for some builder parts. Parts without component blueprints are covered in the next section, Builder Elements.

All builders must have a builder header and a toolbar. These make up the basic frame that indicates to users that they are in a builder.

Logic builders have a specific set of required parts: a canvas, workflow connectors, and nodes. Some examples of logic builders are Flow Builder, Engagement Studio, Journey Builder, Process Builder.

In addition to required parts, builders can have one or more optional panels, modals, and popovers to configure items on the canvas. There’s also an optional zoom tool.

Required (all)Required (Logic Builder)Optional (all)
Builder headerCanvasPanels
Builder header toolbarWorkflow connectorsModals
NodesPopovers
Zoom tool
Stencil of a Builder

Builder Elements

Canvas

The canvas is the open workspace and main working area of your builder layout. It should occupy the bulk of UX real estate. Here users can add and manipulate nodes, connectors, and other components.

Canvas stencil with a lefthand tools panel and righthand work area.
Builder Canvas

Connectors

Connectors are lines that connect nodes to illustrate a path. They represent relationships and movements between nodes. Use the badge component to label connectors.

  • Use connectors to connect to nodes horizontally or vertically at 0°, 90°, 180°, or 270° angles.
  • Don’t use connectors without horizontal or vertical alignment (i.e., avoid 45° and freeform connectors).

In testing mode, a user can choose a path through a workflow, then see it reflected in color and line-weight changes to the connector path.

Connector example in base state with two nodes joined by a path that is a diminished color.
Connector Base
Connector example in a hovered state with two nodes joined by a path that is light blue in color.
Connector Hover
Connector example in a focused state with two nodes joined by a path that is dark blue in color.
Connector Focus
Connector example in variant style with two nodes joined by a path that is a gray dotted line.
Connector Variant
Connector example animating an orange line connecting two nodes.
Connector Tracing
Connector example animating an orange line connecting two nodes.
Connector Tracing Animation

Nodes

Nodes are the building blocks of a workflow. Each one represents an action.

  • Use paired shapes and colors to represent each possible action and process step.
  • Don't use different colors and shapes to represent the same state.

Consistency is important here: Keep node shapes and colors consistent across actions, and standardize type color, size, and spacing.

Each node must have a name label. Nodes may also include an icon inside the node, a description below the name, and a link below the description. Labels can be up to 132 pixels across. You can also add icons to differentiate related functions, such as Start and End.

Node stencils
Workflow Nodes

Node Deletion Behavior

Across Salesforce, the trashcan icon denotes removal of an element, while the “x” icon denotes closing or dismissing an element. Use the trash can icon to allow removal of a workflow node when the user hovers over it.

Use a 44x44 pixel touch target for mobile web.

Three Node examples
Left: Node in hover; Middle: Node in focus; Right: Node delete in focus

Node Error Behavior

Across Salesforce, the ban icon denotes errors. Use the ban icon in the upper left corner of the node, and highlight the affected node with an outline.

When errors are identified and appear in the Error Popover, highlight affected node(s). Allow the user to navigate between elements, to address the node that is causing the error.

Use a 44x44 pixel touch target for mobile web.

Three Node error examples
Left: Node in error state, Middle: Node in hover; Right: Node in focus

Builder Component Blueprints

Builder Header

See the Builder Header component blueprint for implementation information

Overview

Every builder needs a builder header, which contains basic navigation elements. It also shows the builder type and content name.

Builder header bar
Builder Header

Usage

A builder header should span the width of the viewport (the viewable area in a browser), and should be used in full-screen mode. Navigation to other areas of the builder may be placed between the app name and document name.

Designing for business users? Use the record header component as your builder header. Put it below the global header and global navigation.

Action Toolbar Variant

The action toolbar lives below the builder header. It’s locked in place, and has a width of 1024 pixels.

This toolbar houses buttons that affect the builder as whole—classics like Save, Undo, Copy, and Zoom. Keep your action toolbar lean and mean, with a maximum of five buttons. For more than that, use an overflow menu.

Builder header toolbar
Builder Header Toolbar

About Messaging in the Toolbar

Like in the Save and Error and Warning Popover sections, the toolbar is also used to convey important messages to users about builder status (save success/failure and related warnings and errors).

Button Group

See the Button Group component blueprint for implementation information

Overview

Use a Button Group to create a zoom tool to allow users to magnify or minimize the screen view, zooming in or out on items viewed.

The preferred mode is incremental zoom, a button group using the minus, plus, and expand and contract icons. Users can click to incrementally zoom out (-) or zoom in (+), and can toggle between zoom-to-fit (contract) and zoom-to-100% (expand) views of the canvas.

Usage

When first opening a record, users view the canvas at 100%, with the first node in a workflow placed at the upper left of the canvas. Zooms in and out are based on the current center point of the canvas in view; users can pan to shift the center point.

If a user clicks on a node or other canvas element, the view centers on that element and that element becomes the center point of any zooming action.

  • Place the zoom button group inside the canvas; we recommend the bottom right of the canvas, as shown below.
  • Set canvas zoom speed at 250ms per increment.
  • When maximum and minimum zoom threshold is reached, disable the corresponding - or + button.
Grouped button zoom control with three buttons: zoom out, zoom to 100%, zoom in.
Zoom button group shown with zoom-to-100% option
Grouped button zoom control with three buttons: zoom out, zoom to fit, zoom in.
Zoom button group shown with zoom-to-fit option
Canvas stencil with zoom controls highlighted in blue in the bottom right corner
Ideal placement of the incremental zoom button group at the bottom right of the canvas

Toggle Zoom Variant

Toggle zoom lets users switch between two views, 100%, and zoom-to-fit. If zoom functionality is controlled in the toolbar, use toggle zoom.

Zoom to 100% button
Zoom to Fit button

Panel

See the Panel component blueprint for implementation information

Overview

Panels are builder tool chests, presenting momentary tasks and supplemental information associated with the current builder.

Usage

Use a panel to host functions pertinent to the current builder. Panels have a hierarchy from left to right. The left panel must host the primary functions and tasks to be used in the builder. Once tasks are added to the Canvas, they can be interacted with. The right panel must host the secondary functions, plus supplemental information to be used when a canvas item is active.

Panel stencil with a blank canvas
Overview panel image

Panel Navigation

Use a button icon in the builder header toolbar to toggle panel visibility.

Use a drill in to show a second level of builder content in a panel.

Panel stencil with a X closing button
Panel Toggle

Dialog and Reflow Variants

By default, panels are nonmodal dialogs that float above the canvas content on a raised z-index. Use the default dialog panel in a builder if the content in the panel takes temporary focus.

Alternatively, panels can open as drawers, reflowing the screen content to share screen real estate. Use a reflow panel if the panel content needs to share focus with the canvas—for example, where the canvas needs to be referenced when interacting with the panel’s content.

Panel content stencil example with scrollable center content
Panel Overlay Behavior/Image
Panel content stencil example with reflowed center content
Drawer Reflow Behavior

Popover

See the Popover component blueprint for implementation information

Overview

Popovers are nonmodal dialogs that give the user contextual information and actions on canvas elements, and message users about errors and warnings.

Usage

A popover gives the user information relevant to whatever it points to on the builder canvas. Each popover has a linked trigger element, like a node; when clicked, it opens the popover and either highlights relevant information or provides actions against the trigger element.

All popover messages must be:

  • Dynamically generated, based on builder file contents (no static messages here)
  • Actionable (the user can take action against the element)

Error Popover Variant

All errors that prevent a builder from being saved should appear in an error popovers based in the toolbar. Error messages include header text on a red background; footers are optional.

Error popover variant with red Ban icon and a popover with a red banner.
Error Popover

Warning Popover Variant

All issues that prevent a builder from being activated or published, or prevent runtime, should appear in warning popovers based in the toolbar. Warning popovers include header text on a gold background; footers are optional.

Warning popover variant with a yellow Waning icon and a popover with a yellow banner.
Warning Popover

Click to Create Variant

This popover variant lets users build workflows by selecting nodes, connectors, and other workflow elements from its menu. Note that the “add” icon rotates 45° to look like a “close” icon when the popover is open, in addition to other animation changes.

Click to Create Popover

List Menu

The list menu layout presents next-step options visually.

Click to create popover stencil
Click to Create List Menu

Visual Menu

The tile menu layout lets users quickly select from a limited number of options.

Click to create popover tiles stencil
Click to Create Visual Picker

Drill In

For longer, nested option menus, add a drill in and a search input. A back button will let users navigate branches of the original menu.

Click to create popover with search input.
Click to Create Drill In

Test Mode Variant

In manual workflow testing, users evaluate paths for logic and flow. At each decision point, a popover offers the user options to choose from (for example, an audience group or an event). To present two options, use two buttons side by side. For three to four options, stack the option buttons. For five or more options, add a scroll bar.

Popover stencils with buttons
Test Mode Popovers

See the Modal component blueprint for implementation information

Overview

Modals display content in a layer above the app. They’re used for messaging, setup, and other wizards, and for creating or editing records.

Usage

You can use both modals and panels in a builder. In general, panels are preferred over modals, though each has its uses. Use this decision matrix to guide your choices.

When to Use Panels or Modals

Pro or ConPanelsModals
ProsSmall and medium panels maintain the context of the builder beneath them.

Full panels allow greater focus when viewing a single element—ideal for emails and other large visual elements.
Easily maintain trust with explicit Save, Cancel, and similar CRUD actions.

Have greater versatility; can appear in any context.

Provide focus in any context by obscuring anything below the modal.
ConsCan partially or completely obscure the canvas.

Don't require CRUD actions, which can result in confusion.
Obscures canvas completely.

Difficult to cross-reference other elements on canvas and tool palette.