Data Viz Web documentation #3159
+275
−77
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| !!! Info | ||
|
|
||
| Refer to [Carbon’s Accessibility page](https://carbondesignsystem.com/guidelines/accessibility/overview/) for complete guidelines. | ||
|
|
||
| !!! | ||
|
|
||
| ## Conformance rating | ||
|
|
||
| Because this is an IBM Carbon component, please refer to their documentation for conformance information. | ||
|
|
||
| ## Accessibility considerations | ||
KristinLBradley marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### 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. | ||
|
|
||
|  | ||
| <Doc::ImageCaption @text="Clearly labeling elements can enhance the experience for all users." /> | ||
|
|
||
| ### 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. | ||
|
|
||
|  | ||
| <Doc::ImageCaption @text="Carbon Charts components include thin white separators to help distinguish colors" /> | ||
|
|
||
| ### 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%](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html)) and also [resize text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) 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. | ||
|
There was a problem hiding this comment. I edited this down to cover only what is within consumer control/concern when using Carbon Charts components as they already build in keyboard navigation, aria labels, etc. |
||
This comment was marked as outdated.
Sorry, something went wrong. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,158 @@ | ||
| !!! Info | ||
|
|
||
| For more support in using the Carbon Chart library, please message the Carbon Core team in the IBM Slack channel [#carbon-charts-design](https://ibm.enterprise.slack.com/archives/C01DTUSCQAJ) or [#carbon-charts](https://ibm.enterprise.slack.com/archives/CCA7L4MS9). | ||
|
|
||
| !!! | ||
|
|
||
| ## How to use Carbon Charts components | ||
|
|
||
| We recommend using the Vanilla JavaScript version of IBM’s [Carbon Chart components](https://charts.carbondesignsystem.com). | ||
|
|
||
| ### Helpful resources | ||
|
|
||
| - [Carbon Charts Introduction](https://charts.carbondesignsystem.com/introduction) | ||
| - [Carbon Charts installation](https://charts.carbondesignsystem.com/installation) | ||
| - [Carbon Charts API](https://charts.carbondesignsystem.com/api/) | ||
|
|
||
| ### Getting started | ||
|
|
||
| Refer to the [Carbon Charts installation & setup page](https://charts.carbondesignsystem.com/installation) 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: | ||
|
|
||
| ```html{data-execute=false} | ||
| <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: | ||
|
|
||
| ```javascript | ||
| import { DonutChart } from '@carbon/charts'; | ||
| import '@carbon/charts/styles.css'; | ||
| ``` | ||
|
|
||
| ### Ember component example | ||
|
|
||
| A simple example using the [Carbon Charts Donut](https://charts.carbondesignsystem.com/donut) component. | ||
|
|
||
| #### JavaScript | ||
|
|
||
| ```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](https://charts.carbondesignsystem.com/api/interfaces/donutchartoptions), can be set according to your needs. You can combine the preset options that you’ve included with dynamic options you’ve exposed. | ||
|
|
||
| ```javascript | ||
| // 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', | ||
| }; | ||
| ``` | ||
|
|
||
| !!! info | ||
|
|
||
| Refer to the [Carbon Charts API docs](https://charts.carbondesignsystem.com/api/) for the full list of available options for each component type. | ||
|
|
||
| !!! | ||
|
|
||
|
|
||
| #### Template | ||
|
|
||
| Attach the `setupChart` action to a generic container element. | ||
|
|
||
| ```handlebars{data-execute=false} | ||
KristinLBradley marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| <!-- 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. | ||
|
|
||
| ```handlebars{data-execute=false} | ||
| <!-- 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: | ||
|
|
||
|  | ||
KristinLBradley marked this conversation as resolved.
Show resolved
Hide resolved
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| ## 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](https://carbondesignsystem.com/data-visualization/chart-types/) that we recommend using to create data visualizations. These components are available in Figma and code and utilize Carbon Elements for [font styles](https://carbondesignsystem.com/elements/typography/overview/) and [color palettes](https://carbondesignsystem.com/elements/color/overview/). | ||
|
|
||
| ### Commonly used chart examples | ||
KristinLBradley marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| - [Vertical bar charts](https://charts.carbondesignsystem.com/bar#vertical) 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]( https://carbondesignsystem.com/data-visualization/simple-charts/#meter-(proportional)) 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](https://carbondesignsystem.com/data-visualization/simple-charts/#donut) 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](https://carbondesignsystem.com/data-visualization/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. | ||
|
|
||
|  | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| We recommend using Carbon Design System's [Carbon Charts](https://charts.carbondesignsystem.com/introduction) for data visualizations in HashiCorp products. | ||
|
|
||
| We've imported the latest [Carbon Charts Figma library](https://www.figma.com/design/k34tT4poC2p1RBQxVwZhW5/-Alpha--Carbon-Charts-Library-Kit-%E2%80%93-Carbon-Design-System--Copy-?node-id=3984-105570&t=YIZdjDNDhgDMtXBd-1) 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](https://ibm.enterprise.slack.com/archives/C01DTUSCQAJ) or [#carbon-charts](https://ibm.enterprise.slack.com/archives/CCA7L4MS9). |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.