Foundations
Rationale

Rationale

Purpose

  • The content structure must be visually represented in the least intrusive way possible.
    When merchants understand the content structure, assigning meaning to each element is easier. A common way to represent this structure is using white containers over a gray background, but this approach adds unnecessary visual weight to the interface. This is why we use only borders to delineate containers and make the content structure visible.
  • Fixed and draggable elements need to have explicitly delineated boundaries.
    The web has default behaviors such as focus states that highlight the shape of an element and scroll bars that appear when content overflows. For example, in a Page Header that is fixed during scroll, it's important for merchants to see its boundaries to anticipate the behavior. This is why we use borders in these cases and don't rely only on white space.

Visual

  • Excessive borders act as clutter that takes up space and makes the interface look heavy.
    When content is grouped with borders instead of white space, it occupies more space since more padding needs to be added. When these borders are thick, they draw unnecessary attention and distract merchants. This is why we use thin borders only to delineate top-level containers when white space is insufficient.
  • Borders should be visible to users with mild vision impairments and low-quality monitors.
    An element that is not visible to some users is also less visible to all users, and elements that are not clearly visible act as noise. Even though the content of a container should draw more attention than its shape, when a container exists, it needs to be clearly visible. This is why we use containers with borders that pass WCAG AA or rely only on white space.
  • The entire style of a container should reinforce the semantics of its content.
    A container with a background color and a border that doesn't follow the same hue appears dissonant. Besides making the visual more harmonious, using colored borders in these cases also reinforces the semantics of an element, such as an Alert. This is why we include border variations that match each background color token.