Layout

Best practices

The layout component should:

• Use sections with white backgrounds for primary content and sections with grey backgrounds for secondary content that is less important
• Center cards on the background when there is no secondary card on the page to stop the content from becoming too wide
• Group similar concepts and actions together in cards
• Separate different cards using a full-width divider
• Structure two-column layouts so the primary ⅔ section is used for main information and the secondary ⅓ section is used for information that might not be used as often but remains helpful for context or secondary tasks

Content guidelines

The content from the layout component comes from cards and annotated sections.

Heading

Headings should be:

• Informative and descriptive
  • They should label the type of content grouped in the card
• Concise and scannable:
  • Use simple, clear language that can be read at a glance
  • Keep to a single sentence and avoid using punctuation such as periods, commas, or semicolons
  • Avoid articles (the, a, an) in microcopy headings to keep content short and actionable
  • Write in sentence case (first word capitalized, the rest is lowercase)

Body content

Body content should be:

• Actionable: start sentences with imperative verbs when telling a merchant what actions are available to them (especially something new). Don’t use permissive language like “you can”.

• Structured for merchant success: always put the most critical information first.
• Clear: use the verb “need” to help merchants understand when they’re required to do something.

Call-to-action button

Buttons should be:

• Clear and predictable: merchants should be able to anticipate what will happen when they click a button. Never deceive a merchant by mislabeling a button.

• Action-led: buttons should always lead with a strong verb that encourages action. To provide enough context to merchants use the {verb}+{noun} format on buttons except in the case of common actions like Save, Close, Cancel, or OK.

• Scannable: avoid unnecessary words and articles such as the, an, or a.

Section titles

Section titles should be:

• Informative: they should label the type of content grouped in the body content below
• Like headings: follow the same content guidelines as when you’re writing headings

Action links

Links should be:

• Used for secondary or persistent actions: links are for lower priority actions than buttons, or persistent actions that a merchant may take at any time (e.g. a persistent Edit link).
• Clearly labeled: merchants should not need to guess where they’ll end up if they click on an action link. Never use “click here” as a link because it doesn’t set expectations about what’s next.
• Similar to buttons: follow the same content guidelines as when you’re writing buttons.

Annotated content titles

Annotated content titles should be:

• Informative: they should label the type of content grouped in the body content below
• Like headings: follow the same content guidelines as when you’re writing headings

Annotated content descriptions

The descriptions in annotated sections should:

• Be used if the explanation or purpose of the associated cards isn’t clear
• Provide instructions for any choices the merchant needs to make, or explain the purpose of the section
• Be short, no more than 1–3 sentences
• Direct merchants to more content in the Help Center with “Learn more” links
• Not repeat the section title
• Use complete sentences and regular punctuation

Related components

• To visually group content in a layout section, use the card component
• To lay out a set of smaller components in a row, use the stack component
• To lay out form fields, use the layout component