Use the river component to introduce a feature using a type and media pairing.

A river component used to showcase a security feature. The title reads "Get security feedback with every git push" and it includes an image showing screenshots of of a CLI prompt with the git push command and a code scanning screenshot.


Use rivers to showcase features and introduce topics. Rivers are composed of images or videos paired alongside text content like headings, paragraphs, and links.

A river’s content should be short and concise, no longer than 3 or 4 sentences and in a single paragraph when possible.


Write short and concise text content.


Don't overload the river with too much content.


Two or more rivers can be stacked to guide the user through a set of features. When stacking rivers, alternate between left and right alignments to create a more dynamic reading flow. When alternating alignments, use a 40:60 image to text ratio, otherwise keep the ratio to 50:50.

It is possible to use 2 or more following left or right river to create a simple alignment promoting easy scroll scan.


Alternate rivers with left and right alignments.


Don't break the flow in a stack of rivers that would otherwise stay aligned.

Note that too many rivers can make the design feel repetitive. In that situation, consider introducing a breakout section or break the content with a different component, such as pillar or card to provide a better visual hierarchy and experience. For example, use the river for the top features you want to highlight and then use pillars to showcase the rest.


Use pillars or cards to breakout a multiple river section and provide a better visual hierarchy.


Don't stack numerous rivers without breaking the content to avoid repetitive a layout that can make the design feel repetitive.

Sections with rivers

A single river component acts as a section and it should not include any child sections within in. Multiple rivers can be used to conform a section. In that case, the section should include a section intro that introduces the main topic or features.


Use a section intro to introduce multiple rivers.


Don't add child sections or other components to the river body content.

River breakout

A river breakout component has an image that fills the width of the container while providing more space for content such as text and lists.

This is useful when you want to create a highlight which can be used to create more emphasis or simply break a monotonous vertical flow of left/right rivers. It can also be helpful on smaller viewports to avoid stacking two images or two chunks of text from adjacent river components.

As its name suggest, a river breakout should not be the first in the stack, it should be positioned in-between two standard rivers.

Some examples of when to use a river breakout:

  • Expand on more complex feature that require more room for content
  • Give designer a tool to emphasize the feature story
  • Use a branded wallpaper in a more cinematic way than the standard 50/50 or 60/40 text-to-image column ratios

Use a river breakout to emphasize a part of the river or break up a series of river components.


Don't stack river breakouts on top of other river breakout components or center-aligned river components. These both show a full-width image. This diminishes the visual impact the river breakout is intended to provide.

The headline in the river component must always be present, but the supplemental content is optional.


Exclude the supplemental content if it's not needed.


Don't exclude the headline.

Limit supplemental content to a maximum of 500 characters or two timeline items to avoid overwhelming the user and disrupting the layout's balance.


Limit supplemental timeline content to two items.


Avoid unbalanced river breakout content.


A river component used to showcase a security feature. The title reads "Get security feedback with every git push" and it includes an image showing screenshots of of a CLI prompt with the git push command and a code scanning screenshot.


River provides a heading as the main title and a body text as the main content that describes the adjacent visual. The heading should be short and concise and the body should describe the feature or topic in a short paragraph.


A river can include either an image or video to illustrate the feature or topic. The media should be relevant to the content and should not be used as a decorative element.

Always use high quality images and videos. Avoid using images with text or single logos. Ensure the image fills the provided container.

The image is automatically styled to fit the width of the parent container. If you have bespoke styling requirements, you can disable the provided default styles and style the image manually.

Additional guidance

  • We recommend using a river left as the first river of the flow to start with a visual and avoid stacking text with above section on mobile
  • River components stacks create a unit, the set should be considered to be the main parent section. The parent section should be spaced as a regular section with the largest spacing while internal elements should use smaller spacing
  • If the image is critical for the user to understand the message, default to right aligned. If the text is critical for the user to understand the image, choose left aligned.

River can include an optional call to action to link to more detailed content about the feature or topic.

  • Pillar: To display non-navigational related content in a compact way.
  • Card: To display navigational related content in a compact way.