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.

Merge request widget layout grid
A grid layout of the merge request widget structure identifying the levels and content sections

Levels

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.
Merge request widget spacing
A layout with different sized overlays to indicate content spacing within a widget

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.
Merge request widget changes per breakpoint
Examples of different padding and action options as they change responsively

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.

Merge request widget overflow scrolling
Overflow example with scrim overlay to indicate scrolling for the combined levels 2 and 3
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
Merge request widget container shape
The container that groups merge request widgets with a slightly rounded border radius and light border
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
  • Status icon: required
Merge request widget level 1
The default layout of level 1 in a widget
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.
Merge request widget level 2
The default layout of level 2 in a widget
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
Merge request widget level 3
The default layout of level 3 in a widget
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 status icon Failed
  • Warning status icon Warning
  • Success status icon Success
  • Neutral status icon Neutral
  • Loading status icon Loading (spinner)

Level 2–3 general

  • Failed status icon Failed
  • Error status icon Error
  • Warning status icon Warning
  • Notice status icon Notice
  • Success status icon Success
  • Neutral status icon Neutral

Level 2–3 severity

  • Severity critical status icon Critical
  • Severity high status icon High
  • Severity medium status icon Medium
  • Severity low status icon Low
  • Severity info status icon Info
  • Severity unknown status icon 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 voice and tone guidelines for writing all text content.
Merge request widget subject styles
Example options and formatting within the subject area with numbered markers corresponding to the list that follows
  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.
Merge request widget actions
Example actions with numbered markers corresponding to the list that follows
  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 modal.
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 marker Region
  • Tab order marker Tab order
  • Screen reader marker Screen reader
  • Note marker 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.

Merge request landmark highlight
A basic merge request report region is contained within a border highlighting the parent div that has an assigned role of region
  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.

Merge request focus order highlights
Numbered markers represent the expected tab order of the focusable content within a widget
  • 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.

Merge request screen reader announcement highlights
Numbered markers highlight areas to identify how they're announced within a widget
  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.

Merge request notes highlights
The merge request report region with overlays that highlight the semantic container div and unordered list structure
  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>.

Last updated at: