Merge request reports

The merge request (MR) reports region includes a wide variety of widgets that report information about the MR changes, helping authors and reviewers understand their impact and what needs to be improved. The following guidelines systematize attributes like layout, hierarchy, and content sections, making the widgets consistent, scannable, and utilitarian. Widgets are designed to adapt to page layout (responsive), and future widgets will have patterns to follow. We provide constraints where possible, but ultimately a widget's unique purpose should define the extent of how the guidelines are applied.

View in Pajamas UI Kit →

Layout

Each widget is laid out as a grid with three possible horizontal levels and three vertical sections. Levels define hierarchy and sections define content sections for each level.

Levels

• Level 1 - parent level of the widget.
• Level 2 - child of level 1.
• Level 3 - child of level 2.

Sections

• Status - contains the status icon for the widget and each child item.
• Subject - describes the widget and each child item.
• Actions - a group of optional actions for the widget and each level 2 child item.

Grid

The widgets use our 8px spacing system to align elements within. External spacing is always greater than or equal to internal spacing, meaning that as nesting increases, space decreases. This helps identify content relationships and makes the higher levels more scannable. Widget content nests up to two levels deep.

• Level 1 adjusts vertical spacing responsively to keep more widgets in view at smaller breakpoints.
• All levels adjust horizontal spacing responsively to provide more room for the subject at smaller breakpoints.

Responsive

Content sections follow a left-to-right reading order at all breakpoints.

• Actions other than info and the expand/collapse toggle are within an overflow (ellipsis) dropdown for the medium breakpoint and down (<768px).
• When download options are available, they merge into the overflow menu at small viewports.

Overflow

An optional maximum height can be applied to the nested content when level 1 is expanded. This is best used when the number of nested reports typically exceeds five, or when the expanded view introduces a large amount of scrolling that makes it difficult to view the rest of the page content.

TODO:

Replace static visual with live example Create an issue

1. A maximum height is set for the expanded level 2 and level 3 area with overflow scrolling set to auto.
2. A scrim visual indicator overlays the bottom of the scroll area when the content height exceeds the maximum height. The scrim is hidden once the end of the scrolling content is reached.

Hierarchy

In addition to external spacing being greater than internal spacing, widgets use progressive indentation to help establish hierarchy.

Container

The container wraps one or more widgets.

• 1px $gray-100 inset border
• $white background
• 4px border radius

TODO:

Replace static visual with live example Create an issue

Level 1

Level 1 is the parent level of the widget and has the primary status in text and icon form, as well as optional controls and actions that apply to the entire widget. The status icon is surrounded by a highlight to make it a stronger visual anchor while emphasizing the status. The primary status is determined by the widget's rules and influenced by level 2 statuses if present. The expand/collapse control is only visible when this level contains children.

• Top border 1px $gray-100 for n+1
• $white background
• Collapsed by default with the exception of a merge widget that details reasons a merge request is blocked. Try to limit the number of expanded ones to avoid an overwhelming page.
• Status icon: required

TODO:

Replace static visual with live example Create an issue

Level 2

Level 2 has a status that may be the same or different from the parent, as well as optional controls and actions that apply to itself. Its influence on the parent status will depend on the type of widget and the applicable rules. Likewise, its status will be determined by applicable rules and influenced by level 3 status if present.

• Content indented and left-aligned to the level 1 subject.
• Full width 1px $gray-100 top border for n+1
• Top border inset (16px left and right padding) 1px $gray-100 for n+1
• $gray-10 background
• Level 3 children are always visible
• Status icon: optional
• Actions: optional
• Section title and description: optional
• Items that share the same title and/or description do not have a top border.

TODO:

Replace static visual with live example Create an issue

Level 3

Level 3 has a status that may be the same or different from the level 2 parent. Its influence on the level 2 parent status will depend on the type of widget and the applicable rules.

• Content indented and left-aligned to the level 2 subject.
• $gray-10 background
• Status icon: optional
• Actions: inline text links only
• Section title and description: optional

TODO:

Replace static visual with live example Create an issue

Content sections

As shown in the layout, there are three content sections: status, subject, and actions.

Status

Each widget has rules that determine its status. The icon at the top level of each widget reflects the highest severity, unless the highest nested severity doesn’t trigger a failure of the parent.

Level 1

• Failed
• Warning
• Success
• Neutral
• Loading (spinner)

Level 2–3 general

• Failed
• Error
• Warning
• Notice
• Success
• Neutral

Level 2–3 severity

• Critical
• High
• Medium
• Low
• Info
• Unknown

Subject

Since everything in a widget is technically content, identifying a specific subject section allows us to focus on the text and meta information that identifies the item, what it means for a user, and how to remedy problems.

• Section title, description, and meta information are optional, but the main text is required.
• Follow the UI text guidelines for writing all text content.

1. Section title and description - groups level 2 and level 3 status items. A description must be preceded by a title, but a title does not require a description.
2. Text - identifies the item, what it means for a user, and how to remedy problems. It can contain inline links and formatting to emphasize text.
3. Meta - supplemental text, links, and badges that add meaningful context to an item. Text can include formatting for emphasis.

TODO:

Replace static visual with live example Create an issue

Actions

Actions available for level 1 and level 2 and always use the tertiary confirm or default button variants.

• Only level 1 can be expanded and collapsed.
• Level 3 can only have inline text links.
• All actions are optional except the expand/collapse toggle for a level 1 item with children.

1. Info button - provides supplemental information in a popover.
2. Options button - at smaller breakpoints opens a dropdown with available actions. On hover/focus a tooltip reads “{widget} options”.
3. Download dropdown - ability to download assets related to the widget. On hover/focus a tooltip reads “{widget} downloads”.
4. Tertiary button - actions that can be taken on or from the widget, like “Manage licenses” or “View report”.
5. Expand/collapse button - toggles the visibility of level 2 and level 3 items when present. On hover/focus a tooltip reads “Show {widget} details” when collapsed and “Hide {widget} details” when expanded.
6. Inline links - can be used to provide more information about level 3 items. For example, by linking to another page or by triggering a drawer.

TODO:

Replace static visual with live example Create an issue

Accessibility

The following provides guidance on roles, keyboarding, and content for screen readers.

Legend

• Region
• Tab order
• Screen reader
• Note

Landmark

The widget area is an important enough section of a merge request page that it should be identified as its own landmark region. It contains the unordered list where each widget is a list item. See the notes section below for markup recommendations.

1. <div role="region" aria-label="Merge request reports">

Focus order

The focus order traverses focusable elements in the DOM in a left-to-right, top-down order.

• TAB key moves through the list of interactive items in the order of the DOM.
• ENTER or SPACE key expands/collapses the mobile overflow dropdown.
• ENTER or SPACE key expands/collapses a level 1 item to reveal level 2–3 content.

Screen reader

The following highlights element attributes and the general expectation of how they should be announced by a screen reader.

1. aria-label="{status} {widget}"
   SR: “{status} {widget}, image”
2. aria-label="{widget} information"
aria-describedby="{popoverID}" SR: “{widget} information, button, {popoverID content}”
3. aria-label="[widget} options"
   Collapsed: aria-expanded="false" → Expanded: aria-expanded="true"
aria-haspopup="true"
aria-controls="{menuID}"
   SR collapsed: “{widget} options, collapsed, pop up button” → SR expanded: “{widget} options, expanded, pop up button”
4. Collapsed: aria-label="Show {widget} details" → Expanded: aria-label="Hide {widget} details"
   Collapsed: aria-expanded="false" → Expanded: aria-expanded="true"
aria-controls="{nestedStatusID}"
   SR collapsed: “Show {widget} details, collapsed, button” → SR expanded: “Hide {widget} details, expanded, button”
5. aria-label="Downloads" Collapsed: aria-expanded="false" → Expanded: aria-expanded="true"
aria-haspopup="true"
aria-controls="{menuID}"
   SR collapsed: “Downloads, collapsed, pop up button” → SR expanded: “Downloads, expanded, pop up button”
6. aria-label="{status} {report}"
   SR: “{status} {report}, image”

Notes

The widgets are organized in an unordered list, which has the benefit of providing hierarchy and a report count (number of list items) to screen reader users.

1. The widget group is wrapped in a <div> that functions as a landmark.
2. Each level is a <ul> with <li>s for individual reports. A title and description for a report are contained within that report’s <li>.

Content

Empty state

Merge request report widgets use an adapted version of the configuration required empty state.

• Use level 1 layout with an info status icon.
• Use a title and succinct description as the subject.

TODO:

Add a visual example View issue

Note that different from other "configuration required" empty states, the action to configure a feature is presented in a tertiary confirm button. This is done to avoid distracting users from the merge workflow.