Pattern library: Column Charts

Problem

While we have column charts currently in GitLab, we haven't officially established a design pattern for them. To ensure column charts are implemented consistently, we need to establish a set of standard guidelines for them.

Solution

Guidelines

• Recommend using popovers rather than tooltips. Popovers will allow for the display of richer amounts of information on more complex charts so, using them exclusively will cut down on confusion about when to use a tooltip and when to use a popover.
• Hovering: placement of the popover should follow the cursor. Hover area should include the area of the column plus 20 px above so that users can access the popover, even when the columns are very short.
• Chart titles: utilize primary/ui/02-h2 (20px and bold), and they are left-aligned (note, though, that the size of the chart title may depend on the already existing type hierarchy on the page). Chart titles are 24px above the y-axis labels (which is the highest point on the chart container).
• Axis labels: by default, they utilize ui/08-small/secondary (12px, regular weight). If the column is being hovered on, though, the label will highlight by changing to ui/08-small/primary (ie, from 707070 to 2E2E2E). Y-axis labels are right-aligned to the axis; x-axis labels are center-aligned to the column. Both sets of labels are 8px from the edge of the axis.
• Value + category titles: utilize ui/08-small/primary/bold (12px, bold weight). Both are centered within their axis space. They have 16px of space above and below them (or to the right and left of them, in the case of the y-axis title).
• Min widths: single columns should be a minimum of 8px wide and have 8px of space between them. There should also be a minimum of 8px of space between the left edge of the chart and the first bar. In general though, the size of the columns will be determined by the number of categories and the size of the chart container. The more space there is, the wider the bars are allowed to be, so the distance between the last bar and the right edge of the chart may vary slightly.
• For series charts, the minimum distance between the groups is 3x the space between each bar or, 24px.
• There is no default max width for the columns so, if you only have three categories and 1 series, each column would occupy around 33% of the available space.
• Colors: I've recommended the following as a default color order - blue, green, orange, purple. The colors are all of the basic color palette at the 500 weight. The fill is set at 20% opacity by default; 40% on hover. Note: if you have charts that feature positive and negative values, feel free to utilize a green/red version of the chart to make the data gains (greens) and losses (reds) more immediately apparent. This variation of a column chart is usually known as a waterfall chart.
• Chart heights: are defined as the distance between the top and bottom horizontal rules, since the labels can take up varying amounts of vertical space. On larger screens, the height is 256px; on smaller screens (<768), it goes down to 176px.
• Tick marks: when there are multiple series, the tick marks live between the series groups. When there is only one series, the tick marks are centered below each column.
• Legend: the text after the series name is optional. It allows for the possibility of complementing the series legend with additional useful calculations (total, etc).

Usage

Column charts are used to compare values across categories. The categories are usually presented on the x-axis, and the values on the y-axis.

Column charts can be considered the 'default' chart type. If you are thinking about using a pie chart, a column chart will probably tell the story more clearly.

Dos and dont's

(Use this table to add images and text describing what’s ok and not ok.)

✅ Do
Add a legend if there is more than one series being displayed
You may need to rotate the category labels for long labels + smaller screen sizes (ie, if there is less than 4px of space between each label)
Use category labels as necessary to clarify the content being shown (with units in parentheses, if required). Note, though, that units aren't always necessary, for example in the case of counts.
Move the x-axis upwards when negative values are present

Related patterns

#204 (closed)

Pattern checklist

Make sure these are completed before closing the issue, with a link to the relevant commit, if applicable.

1. Read our contribution guidelines, especially the For GitLabbers section.
2. Create a Sketch file in your progress folder just for this pattern and make sure that:
   1. You have not created a duplicate of an existing pattern, symbol, layer style, or text style.
   2. You have used the proper method for creating the pattern depending on the complexity. Atoms and molecules are symbols, organisms are groups.
   3. Typography uses text styles. When applicable, colors use shared styles.
3. Make recommendations for tick marks
4. Make recommendations for tooltips vs popovers
5. Explore hover recommendations
6. Review x axis distance to chart
7. Define guidelines for min. and max. space between columns but also width of columns.
8. Define guidelines for axis and chart titles
9. Define color scheme and color order
10. Define guidelines for legends
11. Ask a UXer to review your Sketch file, linking them to your latest commit so they know where to find it. If they have the capacity, they should assign themselves to this issue.
12. QA of your Sketch file by the reviewer.
13. Add your changes to the pattern library. When copying things over, watch out for duplicated symbols, layer styles, and text styles. Some of our recommended plugins can help you find and remove duplicates.
14. QA of pattern library by the reviewer.
15. Create an issue to add the pattern documentation to the Design System. Mark it as related to this issue.
16. Add an agenda item to the next UX weekly call to inform everyone (if it's a new pattern, not yet used in the application).