Data visualization

We recommend using Carbon Design System's Carbon Charts for data visualizations in HashiCorp products.

We've imported the latest Carbon Charts Figma library into the HashiCorp Figma instance. To use these components in Figma, enable the library as you would any other HDS library.

To get support when using the Carbon Chart library, please message the Carbon Core team in the IBM Slack channel #carbon-charts-design or #carbon-charts.

Deciding how best to represent data

Consider whether a data visualization is actually appropriate for the type of data you wish to present or whether a table may be clearer or more appropriate. Data visualizations offer a quick way to identify trends or patterns or as a way to visually summarize data. Tables, on the other hand, are better for examining precise or multi-dimensional data. Carbon Charts components, in a way, allow you to do both. The built-in toolbar enables users to view a table of the presented data in the data visualization.

Considerations for using data visualization

• Information density: If a table requires too many columns to fit within a screen consider whether using a data visualization would make the information easier to consume.
• Frequency of outliers: If most data points are clustered but there are a few outliers, this is less apparent using a table so a data visualization may be clearer.

Carbon charts components

IBM’s Carbon Design System includes various chart components that we recommend using to create data visualizations. These components are available in Figma and code and utilize Carbon Elements for font styles and color palettes.

Commonly used chart examples

• Vertical bar charts are the most common representation of categorical data. They allow a user to quickly compare the amounts of a value based on the heights of the bars in the chart. Examples in our products may include displaying cost per month or resource use per quarter.

• Proportional meters are used to show the breakdown of categories within a bar that equal 100% of the bar. This is may be used in our products to show the health of a group of resources or the amount of resources used toward a specific cap.

• Donut charts are circular graphs that display data as a portion of a whole divided into slices. This type of chart may be used in a similar way as proportional meter charts but offers a different presentation of the information.

Color palettes

When creating data visualizations, use the color palette created for the type of data being presented and consider that color choice can impact meaning. Carbon Charts offers preset color palettes for each type of data representation, making it simple to select appropriate and accessibility-compliant values.

There are three main types of color palettes used in data visualization:

1. Categorical palettes
2. Sequential palettes
3. Diverging palettes

Carbon’s data visualization palettes include categorical palettes with one to five colors, a full categorical palette for needs requiring more than five distinctions, a sequential palette, a diverging palette, and a gradient palette.

Categorical palettes

Use categorical palettes for presenting data that has no intrinsic order, such as in a pie or donut chart. They are also good for multi-line charts, area charts, stacked or grouped bar charts, etc.

Sequential palettes

Use sequential palettes for quantitative or ordered values in a continuum. This palette is useful for heat maps and grouped horizontal bar charts that compare sequential groups, such as age ranges, etc.

A gradient palette is a type of sequential palette that can be used to distinguish elements without inherent axes or directions, such as in maps or geographic representations.

Diverging palettes

Use diverging palettes when presenting two sequences of ordered values that share a central value. This type of palette can be used for diverging bar charts, horizon charts, heat maps, etc.

How to use Carbon Charts components

We recommend using the Vanilla JavaScript version of IBM’s Carbon Chart components.

Helpful resources

• Carbon Charts Introduction
• Carbon Charts installation
• Carbon Charts API

Getting started

Refer to the Carbon Charts installation & setup page for more complete instructions.

Basic steps

1. Install the Vanilla JavaScript Carbon Charts library as a dependency.
2. Import the component you wish to use, for example the DonutChart
3. Create an options.js file if you wish to customize the component’s available options.
4. Ensure components will have the correct visual appearance by
   • linking to font definitions within your HTML document
   • importing the component styles

Importing files

In HTML:

<link rel="stylesheet" href="https://1.www.s81c.com/common/carbon/plex/sans.css" />
<link rel="stylesheet" href="https://1.www.s81c.com/common/carbon/plex/sans-condensed.css" />

Within JavaScript:

import { DonutChart } from '@carbon/charts';
import '@carbon/charts/styles.css';

Ember component example

A simple example using the Carbon Charts Donut component.

JavaScript

// app/components/demo-carbon-donut/index.js

import Component from '@glimmer/component';
import { action } from '@ember/object';

import { DonutChart } from '@carbon/charts';
import data from './data';
import options from './options';
import '@carbon/charts/styles.css';

export default class DemoCarbonDonut extends Component {
  chart = null;

  @action
  setupChart(element) {
    // Merge the dynamic options into the default options
    const chartOptions = {
      ...options,
      title: this.args.title || options.title,
      color: {
        scale: this.args.colorMap,
      },
    };

    // Create the DonutChart instance
    this.chart = new DonutChart(element, {
      data,
      options: chartOptions,
    });
  }
}

Options.js file with example pre-set options

The component options, such as the Donut Chart options, can be set according to your needs. You can combine the preset options that you’ve included with dynamic options you’ve exposed.

// app/components/demo-carbon-donut/options.js

export default {
  title: '', // Set title using @title on the component
  resizable: true,
  legend: {
    position: 'left', // = position relative to chart, options: 'top', 'bottom', 'left', 'right'
    truncation: {
      type: 'none',
    },
  },
  donut: {
    alignment: 'center', // = alignment w/i container, options: 'center', 'left', 'right'
  },
  pie: {
    labels: {
      enabled: true,
      formatter: (data) => data.value,
    },
  },
  height: '175px',
};

Template

Attach the setupChart action to a generic container element.

<!-- app/components/demo-carbon-donut/index.hbs -->

<div {{did-insert this.setupChart}} ...attributes></div>

Application

Font definition links should only be included once within the HTML application page.

<!-- app/index.html -->

<html lang="en">
  <head>
    ...
    <!-- include the Plex fonts in the main application -->
    <link rel="stylesheet" href="https://1.www.s81c.com/common/carbon/plex/sans.css" />
    <link rel="stylesheet" href="https://1.www.s81c.com/common/carbon/plex/sans-condensed.css" />
    ...
  </head>
  <body>
    ...
  </body>
</html>

Rendered chart

This will render a chart similar to this one:

Conformance rating

Because this is an IBM Carbon component, please refer to their documentation for conformance information.

Accessibility considerations

Add labels to charts & chart elements

Text-based labels on charts and chart elements must be present. Text must not be truncated because keyboard-only users have no way to access truncated data. While the Carbon Charts components include truncation options for text, the value should be set to false in order to meet our conformance requirements.

Don’t rely on color only to convey information

Be sure to always add appropriate text, such as labels or descriptions of the visual information in the chart. Using patterns, in addition to (or instead of) color can enhance accessibility, although Carbon Charts components and palettes don’t include them at this time. A thin separating line between adjacent colors helps to visually distinguish chart areas.

Ensure charts are readable when resized

Always test that chart information is legible, even on smaller viewports, e.g., mobile devices. Per WCAG Success Criteria, users must also be able to zoom in on their browser (up to 400%) and also resize text associated with charts.

Use interactive elements appropriately

Interactive elements should have unique and clear labels to clearly differentiate them from one another and make their purpose clear.