From 541348d5b4f7cbc00e05dac1e65c9c009bdf80aa Mon Sep 17 00:00:00 2001
From: aratti96 <105744045+aratti96@users.noreply.github.com>
Date: Mon, 23 Oct 2023 09:10:33 -0600
Subject: [PATCH] Updates to the charts about page and charts colors page
(#3759)
* Updates to the charts about page and charts colors page
* Update to Color-and-pattern-usage image file
* Update colors-for-charts.md
* Update colors-for-charts.md
---------
Co-authored-by: Margot <51165119+mmenestr@users.noreply.github.com>
---
.../design-guidelines/charts/about/about.md | 14 ++++----
.../Color and pattern usage.png | Bin 0 -> 41218 bytes
.../colors-for-charts/colors-for-charts.md | 34 ++++++++++++++----
.../img/Color-and-pattern-usage.png | Bin 0 -> 116457 bytes
4 files changed, 35 insertions(+), 13 deletions(-)
create mode 100644 packages/documentation-site/patternfly-docs/content/design-guidelines/styles/colors-for-charts/Color and pattern usage.png
create mode 100644 packages/documentation-site/patternfly-docs/content/design-guidelines/styles/colors-for-charts/img/Color-and-pattern-usage.png
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/charts/about/about.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/charts/about/about.md
index f8ee5e1c8f..bf78ab98b5 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/charts/about/about.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/charts/about/about.md
@@ -18,16 +18,18 @@ A **chart** visualizes data in an application. The type of chart you use will de
## Chart types
-- [Area chart](/charts/area-chart/design-guidelines): Use to show trends over a continuous scale (usually time).
-- [Bar chart](/charts/bar-chart/design-guidelines): Use to show and compare categorical data. Can be plotted vertically or horizontally.
+- [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.
- [Stacked bar chart](/charts/stack-chart/design-guidelines): Use to show and compare categorical data of more than one variable. Can be plotted vertically or horizontally.
+ - Vertical bar charts (category on the horizontal x axis): Use to show a progression of the categories (or sequential variables). The most common bar chart.
+ - Horizontal bar charts (category on the vertical y axis): Use to show nominal variables. Allows for more space for category labeling.
- [Bullet chart](/charts/bullet-chart/design-guidelines): Use as an extension to the bar chart to measure data with thresholds and static ranges.
-- [Donut chart](/charts/donut-chart/design-guidelines): Use to show the relationship of a set of values to a whole, or progress completion as a percentage; best used to display data with a small number of categories (example: 2-5 categories).
+- [Donut chart](/charts/donut-chart/design-guidelines): Use to show the relationship of a set of values to a whole or to show progress completion as a percentage. Donut charts are best used to display data with a small number of categories (example: 2-5 categories). Use the middle of the chart to highlight a data point.
- [Donut utilization](/charts/donut-utilization-chart/design-guidelines): Use to show utilization for an object as a percentage.
- [Donut utilization with threshold](/charts/donut-utilization-chart/design-guidelines#donut-chart---utilization-with-threshold): Use to show utilization for an object as a percentage in relation to threshold values.
-- [Line chart](/charts/line-chart/design-guidelines): Use to compare several data sets, or to show data over a period of time.
-- [Pie chart](/charts/pie-chart/design-guidelines): Use to show percentages or proportional data.
-- [Sparkline](/charts/sparkline-chart/design-guidelines): Use to show how values change over time for multiple sets of data. Useful alternative to the line chart when multiple lines need to be plotted.
+- [Line chart](/charts/line-chart/design-guidelines): Use to compare several data sets or to show data changes over a period of time. Line charts work best when small changes exist within the data.
+- [Pie chart](/charts/pie-chart/design-guidelines): Use to show percentages or proportional data. Can be used to show up to five or more data points.
+- [Sparkline](/charts/sparkline-chart/design-guidelines): Use to show how values change over time for multiple sets of data. Sparkline charts offer an alternative to the line chart when multiple lines need to be plotted. Axis values are not labeled, but a tooltip can be used to display the value at a given point.
## Charts in cards
If a chart lives in a card, the title of that chart will be placed on the header of that card instead of the chart. The rest of the chart guidelines should be followed for the chart itself.
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/colors-for-charts/Color and pattern usage.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/colors-for-charts/Color and pattern usage.png
new file mode 100644
index 0000000000000000000000000000000000000000..ac9cda1036c75ef6aa18df404abeda3f3bdc24d4
GIT binary patch
literal 41218
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
JT>a^*{{e*duuA{{
literal 0
HcmV?d00001
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/colors-for-charts/colors-for-charts.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/colors-for-charts/colors-for-charts.md
index b03814e803..ce9d9b0fc8 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/colors-for-charts/colors-for-charts.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/colors-for-charts/colors-for-charts.md
@@ -15,7 +15,7 @@ import './colors-for-charts.css';
## Chart colors
-Colors for charts includes a recommended set of colors proposed for bar charts, donut charts and pie charts. There are six base colors (blue to orange) that the system is built on. Each base color has its own color family, which includes lighter and darker hues of the base. These families use a monochromatic color order. They are organized in a way that increases contrast while still looking extremely visually appealing. The variation of colors will depend on the type and amount of data at hand.
+PatternFly recommends colors to use with bar charts, donut charts and pie charts. There are six base colors (blue to orange) that the chart color system is built on. Each base color has its own monochromatic color family, which includes lighter and darker hues of the base color. Each family is ordered based on increasing color contrast. The variation of colors you use will depend on the type and amount of data you’re working with.
@@ -26,9 +26,9 @@ Colors for charts includes a recommended set of colors proposed for bar charts,
### How it works
- Although the system may seem complex, it is completely customizable. The idea is that you can put together your desired colors and amount of colors and the system will still sort them correctly. Here’s how the system works:
+ Although the system may seem complex, it is completely customizable. Once you choose the base colors you want to use and the total number of colors you will need, the system will still sort them correctly.
- In this instance, there are only four base colors, therefore four color families. The order begins by going through each base color. Next, it alternates between the lightest and darkest values of each family. Finally, if you still need more colors, it alternates between the second lightest and second darkest colors of each family. In variable-terms: #1a-d base colors, #2a-d [color]-100/[color]-500 alternating, #3a-d [color]-500/[color]-100 alternating, #4a-d [color]-200/[color]-400 alternating, and #5a-d [color]-400/[color]-200 alternating. No matter the colors inputted, the process will remain the same.
+ For example, if you select four base colors (and therefore their four respective color families) the system will first use each base color in your chart. Once all base colors have been used, the system will select additional colors from the families you selected. The system alternates between choosing the lightest and darkest values of each family (shown in the animation). The color picking system will continue to alternate between the remaining lightest and darkest colors of each family. In variable-terms: #1a-d base colors, #2a-d [color]-100/[color]-500 alternating, #3a-d [color]-500/[color]-100 alternating, #4a-d [color]-200/[color]-400 alternating, and #5a-d [color]-400/[color]-200 alternating. No matter which base colors you select, this process will remain the same.
@@ -37,12 +37,28 @@ Colors for charts includes a recommended set of colors proposed for bar charts,
+## Color and pattern usage
+
+When selecting colors for your chart, there are a few important usage considerations to keep in mind. Within a color family, use the base color before the other, lighter or darker hues. Additionally, consider other basic guidelines:
+
+* **Green family:** Use to show success
+* **Red family:** Use to show failure
+* **Other color families:** Use for neutral purposes or categories
+* **Patterns:** Use to deemphasize a section of a chart. Do not use patterns for every section of a chart. Instead, patterns should be used for a single chart portion or for one type of portion (such as for all successes) to deemphasize that section and highlight the other section, which utilizes a solid color.
+
+
+**Note:** When showing success and failure together in a chart, the base color red and green do not pass accessibility requirements. When using both red and green base colors in a single chart, add a pattern to the section that you want to deemphasize to improve the chart’s accessibility.
+
+
+
+
+
## Use cases
### Chart with few variables (1-7)
- If you are dealing with data that includes six or less variables, we recommend using the base colors to represent each. For example, if you collected data on how many sales were made per product at your organization during one period of time, it could look like this if plotted using a bar chart.
+ When working with data that includes fewer than 7 variables, we recommend corresponding each with one of the available base colors. For example, if you collected data on how many sales were made per product at your organization during a period of time, a bar chart of your data may look similar to the following image.
@@ -54,7 +70,9 @@ Colors for charts includes a recommended set of colors proposed for bar charts,
### Chart with nested (grouped) variables
- If you have a set of data that includes grouped variables, we recommend using the color families to represent each. Grouped variables would include a set of parents and children variables. Each group would use a color family that would be represented in the same order as the base colors are listed. So, depending on the amount of nested variables you have, the first color family would be blue, then green, cyan, etc. The colors would start over if there are more than 6 groups, returning back to the blue family. An example of this type of data would be quarterly sales broken down by geographical locations.
+ If your dataset includes grouped variables, we recommend aligning each group to a color family. When you select more than one color family, your chart will arrange the order of colors as follows: blue, green, cyan, purple, gold, orange, red, and then gray. The colors would start over if there are more than 6 groups, returning back to the blue family.
+
+ Shown in the following image is an example of this type of chart, which includes quarterly sales data broken down by geographical locations.
@@ -66,7 +84,9 @@ Colors for charts includes a recommended set of colors proposed for bar charts,
### Chart with many variables (>7)
- If the set of data includes more than six variables, we recommend applying the multichromatic order system, which uses all of the colors in the color system, to the data. This includes a mix of base colors and colors from their family. An example of this type of data would be the cost of living expenses during a period of time.
+ If the set of data includes more than 7 variables, we recommend applying a multichromatic order system, which includes all of the colors in the color system.
+
+ Shown in the following image is an example of this type of chart, which displays the cost of living expenses during a period of time.
@@ -79,7 +99,7 @@ Colors for charts includes a recommended set of colors proposed for bar charts,
- You can also use the color order system with one color family. This creates a monochromatic effect. It works using the same logic and order. We recommend using this system for charts with nested variables. The order begins by going through each base color, then lightest, darkest, second lightest, and ending with second darkest. In variable-terms: #1 [color]-300 (base color), #2 [color]-100, #3 [color]-500, #4 [color]-200, #5 [color]-400. The hues will always follow this order.
+ You can also use the color order system with one color family to create a monochromatic effect. We recommend using this approach for charts with nested variables. The order begins by going through each base color, then the lightest, darkest, second lightest, and second darkest colors in a family. In variable-terms, this order looks like: #1 [color]-300 (base color), #2 [color]-100, #3 [color]-500, #4 [color]-200, #5 [color]-400. Regardless of color family, hues will always follow this order.
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/colors-for-charts/img/Color-and-pattern-usage.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/colors-for-charts/img/Color-and-pattern-usage.png
new file mode 100644
index 0000000000000000000000000000000000000000..3630ea202680dd980db85a74d697924522f96e75
GIT binary patch
literal 116457
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