Foundation

Layouts

We use specific layout structures, containers, and patterns to group information and create consistent experiences in our products.

Page Layouts

The following are foundational page layouts. We build on these layouts by adding containers and patterns.

Primary Layout with Navigation

This is the primary layout structure for each product. At minimum, it features the main navigation, the app bar, a page header with a title, and a content area with a title. Additional layout containers and patterns may be used as applicable.

An example of a primary layout with navigation from Planning & Self-Study.

When to use a primary layout

  • As landing pages of main navigation items
  • To provide users with easy access to the main navigation
  • For dashboards or pages providing an overview of multiple sets of information

When to avoid using a primary layout:

  • Navigating to another page would compete with the user’s current task or experience

Which layout containers and patterns may be used with a primary layout?

Containers:
Cards, tables, side panel, flyouts, dialogs, modals, full page panels, snackbars
Patterns:
Tabs, toolbar, forms

Immersive Layouts

Immersive layouts are used to dive deeper into a particular product area. By removing the app bar and main navigation, they allow users to be fully focused and absorbed in an experience. Immersive layouts may be used to provide extensive details about a specific product area, or to collect complex, multi-faceted information from users through multiple tasks and actions. Immersives may or may not have a unique URL.

An example of an immersive layout with tabs showing extensive details for a product area.
An example of an immersive layout with multiple tasks and actions for collecting data.
An example of an immersive layout created with the full page panel container element.

When to use an immersive layout:

  • To prevent users from navigating away to a different page through the main navigation
  • For a contained flow with details and/or multiple tasks and actions related to one objective

When to avoid using an immersive layout:

  • When users need to access other areas of the system through the main navigation

Which layout containers and patterns may be used with an immersive layout?

Containers:
Cards, tables, side panel, flyouts, dialogs, modals, full page panels, snackbars
Patterns:
Tabs, toolbar, forms

Layout Containers

The following are layout containers that present groups of information, tasks, or actions.

Card

Cards are containers that present a high level of information and guide users to further actions and details. They may display information using a combination or text and data visualization, and use buttons and links for additional information and actions. Cards are variable in width and height. Multiple cards may appear in a content area as a stacked list, or side-by-side in a grid layout.

When to use cards

  • To provide a high level overview
  • For scanning information
  • For groupings of information in a dashboard view
  • To present list items and related details in separate containers

Which layout containers and patterns may be used with cards

Containers:
No additional containers may be used inside cards. Actions (links, buttons, icons) inside cards may trigger side panels, flyouts, dialogs, modals, full page panels, and snackbars on a page level.
Patterns:
Tabs and forms may appear inside cards.

Table

Tables are containers that present large amounts of data with multiple rows and columns. A table may include filtering and sorting, expand/collapse functionality in rows to view and hide information, status labels, and actions related to each listed item.

When to use a table:

  • For displaying related or comparable information of multiple items
  • To help users find relevant information for a specific item

Which layout containers and patterns may be used with a table?

Containers:
No additional containers may be used inside tables. Actions (links, buttons, icons) inside tables may trigger side panels, flyouts, dialogs, modals, full page panels, and snackbars on a page level.
Patterns:
Toolbar.

Side Panel

A side panel is a container that pushes into the content area and lives side-by-side with the information in the content area (on larger screens). As the available screen width decreases, a side panel at a fixed width will cover an increasing larger area while leaving less space available the content area. So, on smaller screens we recommend either having the information in the panel below the content area or utilizing a flyout.

When to use a side panel:

  • To show supplementary or helpful information related to items in the content area
  • When the user is expected to reference or interact with information in the content area while completing or reviewing a task in the side panel

Which layout containers and patterns may be used with a sidepanel?

Containers:
Tables may be used inside a side panel. No additional containers may be used inside side panels. Actions (links, buttons, icons) inside side panels may trigger dialogs and snackbars.
Patterns:
Tabs and forms.

Flyout

A flyout is a container that slides in and lives on top of a page.

When to use a flyout

  • To provide a large amount of supplementary or detailed information without navigating away from the context of the underlying page or flow
  • To collect a large amount of information from users without navigating away from the context of the underlying page or flow
  • To drill into a detailed views of charts

Which layout containers and patterns may be used with flyouts

Containers:
Tables. Actions (links, buttons, icons) inside side panels may trigger dialogs.
Patterns:
Forms.

Modal

A modal is a container that appears on top of a page and requires the user to complete a specific task. Modals disable the main page content underneath until the user interacts with the modal (by either completing the task or exiting).

An example of a modal.
  • To collect information from the user in order to complete a task
  • The interaction required to complete the task is too complex for a card or table on the main page
  • To edit information on a page (related to a card or table)
  • To keep the user focused on a self-contained task

Which layout containers and patterns may be used with a modal?

Containers:
Tables.
Patterns:
Forms, Toolbars.

Dialog

A dialog is a container that communicates system feedback, informational messages, and confirmations of actions. Dialogs are conversational and straightforward and contain only text; they don’t require any complex interactions. Dialogs appear on top of pages and panels and disable the content underneath until the user interacts with the dialog.

An example of a dialog requesting user confirmation for a destructive action.

When to use a dialog:

  • To confirm an action initiated by the user:
    • A destructive action
    • Leaving a screen without saving changes
  • To provide system feedback or information users need to proceed

Which layout containers and patterns may be used with a dialog?

Containers:
Snackbars (as confirmation of action completion).
Patterns:
None.

Snackbar

A snackbar appears near the bottom left edge of a page and contains brief information about the completion of an system action. Snackbars may contain only text or include a link related to the action.

An example of a snackbar confirming the completion of an action.
An example of a snackbar confirming the completion of an action with a link to view the result of the action.

When to use a snackbar:

  • To confirm the completion of an action initiated by the user (such as adding information to a page or panel, or uploading a file)

Which layout containers and patterns may be used with a snackbar?

Containers:
None.
Patterns:
None.

Layout Patterns

Tabs

Tabs are used to divide and organize content into separate page sections.

Which pages and containers may use tabs?

Pages:
All. Primary and immersives.
Containers:
Cards and side panels.

Stepper

Steppers are used to show progress through a sequence of numbered steps.

Which pages and containers may use a stepper?

Pages:
Immersives.
Containers:
Cards, side panels, flyouts, modals, and full page panels.
An example of a stepper.

Toolbar

Toolbars offer controls and actions for filtering, searching, editing or reorganizing data inside a page or container.

Which pages and containers may use toolbars?

Pages:
All. Primary and immersives.
Containers:
Tables, side panels, flyouts, modals, and full page panels.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.