docs(charts): Adds developer notes to about-charts page #4488
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,15 +8,15 @@ _Charts are only available in React_ | |
| A **chart** visualizes data in an application. The type of chart you use will depend on your use case and the type of data you need to display. | ||
|
|
||
| ## Elements | ||
| <img src="./img/axis-labels.png" alt="Chart with axis labels" width="713"/> | ||
|
|
||
| 1. **Title:** Titles should be left-aligned and appear above your chart. | ||
| 2. **Axis labels and scale values:** We recommend using tick marks to clearly mark scale values on the y-axis. The text for axis labels and scale values should be 12px font in standard text color. All scale values should be equally distributed across the axis and the axis label should fall outside the scale values, centered with the axis line. | ||
| 3. **Legends:** We recommend using legends when charts include more than one variable and therefore use more than one color. When datasets are overlapping, an [interactive legend](#interactive-chart-legends) can be used. If space is not available to display names of horizontal and vertical axes, a legend must be added instead. The legend should list the colors that each variable obtains and the name of the variable. The text on the legend should be 14px size and standard text color. They can either be placed left-aligned to the right of the chart or centered below the chart. | ||
| 4. **Chart tooltip:** A tooltip will appear on hover over certain elements of a chart, like bars in a bar chart or segments in a donut chart. [Chart tooltips](/charts/tooltips) should display the specific values related to the element the user is hovering over. | ||
|
|
||
| ## Chart types | ||
| <img src="./img/chart-legend.png" alt="Image displaying what chart types to use when" width="1024"/> | ||
|
|
||
| - [Area chart](/charts/area-chart/design-guidelines): Use to show (potentially multiple) trends over a continuous scale (usually time). | ||
| - [Bar chart](/charts/bar-chart/design-guidelines): Use to show and compare categories and their respective data point/value. Bar charts can be plotted vertically or horizontally. The axis that labels the bar is the category, the axis that marks the end point of the bar displays the data points/values. | ||
|
|
@@ -65,3 +65,15 @@ On click | |
|
|
||
| 1. **Legend:** When a user clicks on a legend label, it becomes disabled and the color swatch is replaced with an eye-slashed icon. | ||
| 2. **Chart:** Data corresponding to the clicked legend label is hidden from view. | ||
|
|
||
| ## Develop with charts | ||
|
|
||
| Default styles in the [@patternfly/react-charts package](https://www.npmjs.com/package/@patternfly/react-charts) are aligned with our light theme. To use chart styles, you must also have the [@patternfly/patternfly package](https://www.npmjs.com/package/@patternfly/patternfly) installed. | ||
|
|
||
| To utilize default chart styles, you don't need to import anything else. But, to support dark-themed charts, you must also import the stylesheet that contains dark theme styles. To do so, add this line before importing your main application component: | ||
|
Contributor
There was a problem hiding this comment. Also confused about "utilize default chart styles" - not sure what "utilize" means exactly. Same with "to support dark-themed charts" - not sure what "support" means. If I simplifed it, I'd say charts works with light theme out of the box, no additional styles or anything are needed. However, for charts to work in dark theme, you'll need to import 1) patternfly CSS (so they have our global tokens) and 2)
Collaborator
Author
There was a problem hiding this comment. Just to clarify, when you say "global tokens", do you mean design tokens? Or this file? Which, this file is ultimately our design tokens..right? I should find time to create a cheat sheet for some of these terms React tokens, design tokens, variables, styles, etc. I get so mixed up 😅
Collaborator
Author
There was a problem hiding this comment. Your simplified suggestion makes sense outside of me making sure I understand the verbiage, though! Gonna make updates based off this |
||
|
|
||
| `import '@patternfly/patternfly/patternfly-charts.css';` | ||
|
|
||
| Once you import this file, you'll have access to [all chart variables](https://www.npmjs.com/package/@patternfly/patternfly?activeTab=code). Beyond dark theme, you could use these variables to match the style of other UI elements to your chart styles. | ||
|
Contributor
There was a problem hiding this comment. IMO it isn't really intuitive that "all chart variables" links to
Collaborator
Author
There was a problem hiding this comment. Okay this is great feedback! I was thinking that the patternfly-charts.css file over on NPM was the chart variables, but I'm definitely treading water with variables, tokens, and friends lol
Collaborator
Author
There was a problem hiding this comment. I think my remaining question is, where is a list of our chart variables? |
||
|
|
||
| You can filter [the PatternFly design tokens table](/tokens/all-patternfly-tokens) to display the list of available chart tokens. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm a little confused about what it means to "use chart styles". Can you elaborate on that a bit? Just so it's clear (it probably is, just want to make sure) -
@patternfly/react-chartsin light theme works just fine without@patternfly/patternflyor any CSS from@patternfly/patternfly. The styles are all basically hard-coded into the chart SVG's.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah nope, I was misunderstanding/assuming that you had to install @patternfly/patternfly in either case! This is ringing a bell for me now, ty