siemens · bettiifr · Sep 25, 2024 · Sep 26, 2024 · Oct 3, 2024
diff --git a/packages/documentation/docs/controls/charts/3d.md b/packages/documentation/docs/controls/charts/3d.md
@@ -3,32 +3,41 @@ import Playground from '@site/src/components/PlaygroundV3';
 
 # 3D-Charting
 
+3D Charts are a powerful way to visualize data in three dimensions. They provide a more immersive and interactive experience compared to traditional 2D charts. We typically use 3D charts to represent complex data sets or to visualize data in a more engaging way.
+
 The `echarts-gl` package extends ECharts to support 3D visualizations, enabling you to create immersive and interactive charts.
 With this package, you can design a variety of 3D charts, including:
 
 - 3D scatter plots
 - 3D bar charts
 - 3D surface plots
 
+<Playground
+height="40rem"
+name="echarts-special-3d"
+noMargin
+examplesByName>
+</Playground>
+
 ## Installation
 
+To install the `echarts-gl` package, run the following command:
+
 ```sh
 npm install --save @siemens/ix-echarts
 ```
 
 ## Import
 
+To use 3D charts, import the `echarts-gl` package in your project:
+
 ```typescript
 import 'echarts-gl';
 ```
 
-## Example
-
-### Basic
+## Dos and Don'ts
 
-<Playground
-height="40rem"
-name="echarts-special-3d"
-noMargin
-examplesByName>
-</Playground>
+- Do use appropriate data
+- Do ensure that 3D charts are suitable for the presented data, they are most effective when additional dimensions are needed
+- Don’t use 3D charts for simple data that can be effectively represented with 2D charts
+- Don’t overuse 3D charts, they can make the data harder to interpret
diff --git a/packages/documentation/docs/controls/charts/bar-chart.md b/packages/documentation/docs/controls/charts/bar-chart.md
@@ -3,9 +3,11 @@ import Playground from '@site/src/components/PlaygroundV3';
 
 # Bar chart
 
-## Examples
+Bar charts are a type of chart that displays data using rectangular bars. The length of each bar is proportional to the value it represents. Bar charts are commonly used to compare the values of different categories. We typically use bar charts to visualize data that is categorical or ordinal in nature.
 
-### Bar chart horizontal
+### Bar chart
+
+The common bar chart is typically used to compare the values of different categories. The length of each bar is proportional to the value it represents.
 
 <Playground
 height="40rem"
@@ -14,7 +16,9 @@ noMargin
 examplesByName>
 </Playground>
 
-### Bar chart horizontal stacked
+### Stacked bar chart
+
+The stacked bar chart is typically used to visualize the relationship between the parts and the whole. Each bar is divided into segments, with each segment representing a different category.
 
 <Playground
 height="40rem"
@@ -23,5 +27,15 @@ noMargin
 examplesByName>
 </Playground>
 
+## Dos and Don'ts
+
+- Do start the Y-axis at zero
+- Do label axes clearly
+- Do use short and clear category names
+- Do include context only when necessary
+- Do arrange categories and bars in logical order
+- Don’t use too many bars in one chart
+- Don’t overcrowd with colors and categories, especially within the stacked variant
+- Don’t use stacked bars if the total value is not important
 
 
diff --git a/packages/documentation/docs/controls/charts/gauge-chart.md b/packages/documentation/docs/controls/charts/gauge-chart.md
@@ -3,9 +3,12 @@ import Playground from '@site/src/components/PlaygroundV3';
 
 # Gauge chart
 
-## Examples
+Gauge charts are a type of chart that displays data using a dial or needle to indicate a value within a specific range. Gauge charts are commonly used to visualize performance metrics, such as speedometers, progress meters, and other KPIs. We typically use gauge charts to represent a single value within a range of values.
+
+### Metric gauge
+
+Metrics gauge chart, also known as dial or speedometer charts, are an effective way to visualize key performance indicators (KPIs) and other metrics. These charts indicate the current value of a metric within a predefined range, often segmented into different zones (e.g., red for poor performance, green for good performance). 
 
-### Performance metrics gauge
 
 <Playground
 height="25rem"
@@ -14,20 +17,32 @@ noMargin
 examplesByName>
 </Playground>
 
-### Progress circle gauge
+### Circle gauge
 
+Circle gauge chart, also known as radial progress charts or circular progress bars, are a visually appealing way to represent data and track progress towards a goal. These charts use a circular shape to display the percentage of completion, making it easy to quickly grasp the status of a project or task. The circle is typically filled in proportion to the progress made, with the center often displaying the percentage value.
 <Playground
 height="30rem"
 name="echarts-progress-circle"
 noMargin
 examplesByName>
 </Playground>
 
-### Progress arc gauge
+### Arc gauge
+
+Arc gauge chart, also known as semi-circular progress bars, are a dynamic way to visualize data and track progress. Unlike circle charts, progress arc charts use a semi-circle or arc to represent the percentage of completion. This design can be particularly effective in dashboards and user interfaces where space is limited, yet a clear and engaging visual representation is needed.
 
 <Playground
 height="30rem"
 name="echarts-progress-arc"
 noMargin
 examplesByName>
 </Playground>
+
+## Dos and Don'ts
+
+- Do keep it simple and easy to read, with a clear needle and well-defined ranges
+- Do use color coding (e.g., green for good, yellow for caution, red for danger) to indicate different ranges
+- Do label the ranges and the needle value clearly to avoid any confusion
+- Don’t overcrowd the gauge with too many ranges or labels
+- Don’t use gauge charts for complex data visualization or large datasets
+- Don’t use similar colors for adjacent ranges to avoid confusion
diff --git a/packages/documentation/docs/controls/charts/line-chart.md b/packages/documentation/docs/controls/charts/line-chart.md
@@ -3,11 +3,12 @@ import Playground from '@site/src/components/PlaygroundV3';
 
 # Line chart
 
-
-## Examples
+Line charts are a type of chart that displays data as a series of data points connected by straight line segments. Line charts are commonly used to visualize trends over time, or to show the comparison between two variables. We typically use line charts to visualize data that is continuous in nature.
 
 ### Basic line chart
 
+Basic line charts use a series of data points connected by straight lines to show changes in values, making it easy to identify patterns, trends, and fluctuations. Line charts are particularly effective for displaying continuous data, such as stock prices, temperature changes, or sales figures. Their simplicity and clarity make them a popular choice for dashboards, where understanding data trends is essential.
+
 <Playground
 height="40rem"
 name="echarts-line-simple"
@@ -17,6 +18,8 @@ examplesByName>
 
 ### Multi-y-axis line chart
 
+Multi-y-axis line charts are used to compare multiple data series that have different scales or units of measurement. By using multiple y-axes, you can display data with different ranges on the same chart, making it easier to compare trends and relationships between variables. Multi-y-axis line charts are particularly useful when visualizing data that has distinct patterns or trends.
+
 <Playground
 height="40rem"
 name="echarts-line-multiple-y-axis"
@@ -26,9 +29,22 @@ examplesByName>
 
 ### Advanced line chart
 
+Advanced line charts are an enhanced version of basic line charts, designed to provide deeper insights and more detailed analysis of data trends. These charts often incorporate features such as multiple data series, interactive elements, and additional annotations to highlight key points or events. Advanced line charts can also include trend lines, moving averages, and other statistical tools to help identify patterns and correlations.
+
 <Playground
 height="40rem"
 name="echarts-line-advanced"
 noMargin
 examplesByName>
 </Playground>
+
+## Dos and Don'ts
+
+- Do start the Y-axis at zero
+- Do label axes clearly
+- Do use contrasting colors for multiple lines to distinguish different data series better
+- Do use consistent intervals on axes
+- Do highlight important data points
+- Do use visual cues to show gaps in data
+- Don’t overcrowd with colors
+- Don’t clutter the chart with too many lines (max. 7 lines)
diff --git a/packages/documentation/docs/controls/charts/overview.md b/packages/documentation/docs/controls/charts/overview.md
@@ -6,33 +6,66 @@ import Playground from '@site/src/components/PlaygroundV3';
 # Basics
 
 Siemens Industrial Experience provides a theme for the popular chart library [ECharts](https://echarts.apache.org/handbook/en/get-started).
-This lets you harness the power of ECharts with seamless integration into the Siemens Industrial Experience styleguide.
+This lets you harness the power of ECharts with seamless integration into the Siemens Industrial Experience design system.
 
 <div className="siemens-brand-section">
-
 ECharts is a third party library distributed under [Apache License 2.0](https://www.apache.org/licenses).
-
 </div>
 
+![Chart usage guide](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3532-4181&t=MD9MvUCkoIcmSi8H-4)
+
+## Attributes
+
+| Name           | Description                                                                                                                                                                                   |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Axes**       | Most charts have a horizontal (x-axis) and a vertical (y-axis) axis. These axes are labeled to indicate what data they represent.                                                             |
+| **Scale**      | Each axis has a scale, often marked with periodic graduations and numerical or categorical indications.                                                                                       |
+| **Labels**     | Axes labels describe the dimensions represented, often including units of measurement, e.g. “Distance traveled (m)”.                                                                          |
+| **Grid lines** | Grid lines help in visually aligning data points within the chart.                                                                                                                            |
+| **Legend**     | Legends explain the symbols, colors, or patterns used in the chart to represent different data sets. By clicking on the date in the legend, you can toggle the visibility of the data series. |
+| **Tooltip**    | Provides detailed information about data while hover over the area of interest.                                                                                                               |
+
 ## Installation
 
+To install the Siemens Industrial Experience ECharts theme, run the follow the steps below:
+
 ```sh
 npm install --save @siemens/ix-echarts
 ```
 
-First, import the `registerTheme` function from our module. Then, invoke this function, passing in your `echarts` instance as an argument. You don't need to provide the `echarts` instance if it is provided globally in your `window` object when using vanilla Javascript. Once this is done, you’ll be able to utilize the `brand-dark`, `brand-light`, `classic-dark`, and `classic-light` themes for your chart.
+1. Import the `registerTheme` function from our module. 
+2. Invoke this function, passing in your `echarts` instance as an argument. You don't need to provide the `echarts` instance if it is provided globally in your `window` object when using vanilla Javascript. 
+3. Once this is done, you’ll be able to utilize the `brand-dark`, `brand-light`, `classic-dark`, and `classic-light` themes for your chart.
 
 ```typescript
 import { registerTheme } from '@siemens/ix-echarts';
 
 registerTheme(echarts);
 ```
 
-### Angular
+<div className="Angular">
+For Angular make sure to correctly add `NgxEcharts` in your module file.
+</div>
+
+### Colors
+
+The Siemens Industrial Experience ECharts theme provides a set of colors that are used to style the charts. These colors are optimized for accessibility and readability. 
+
+**Categorical data**
+For easily distinguishable data series where each category is distinct but not ordered, we recommend the following color sequence. 
+Example: Different product types or regions.
+
+![Colors for categorical data](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3223-1647&t=MD9MvUCkoIcmSi8H-4)
 
-Please make sure to correctly add `NgxEcharts` in your module file.
+**Sequential data**
+For ordered data, we recommend to use every second color (e.g. chart-1, chart-3, chart-5, ...). Example: monthly data.
 
-## Examples
+![Colors for sequential data](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3225-2412&t=MD9MvUCkoIcmSi8H-4)
+
+**Comparative data**
+For comparing data within a category, we recommend to use the matching -40 color with 40% opacity. Example: last year and current year.
+
+![Colors for comparative data](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3225-2885&t=MD9MvUCkoIcmSi8H-4)
 
 <Playground
 height="40rem"
@@ -43,9 +76,28 @@ noMargin
 
 ## Empty state
 
+An empty state occurs when a user first opens an application, and no chart was added manually. Make sure to provide a clear message and a call to action to guide users on what to do next.
+
 <Playground
 height="40rem"
 name="echarts-empty-state"
 noMargin
 examplesByName>
 </Playground>
+
+### Loading indicator
+
+A loading indicator provides users with visual feedback that the chart is being processed and will be displayed shortly. This helps manage user expectations and enhances the overall user experience by preventing confusion or frustration during data loading times. 
+
+### Failure and error message
+
+A failure occurs when no data can be displayed within the chart. This can happen for various reasons, such as connection failure, missing data or other. Error messages have following three elements to move users forward:
+
+- State problem: What happened? Add a clear reason for the error, i.e. “No data available”
+- Explain cause: Why did the error appear? A clear and concise message explaining why the error happened. "Connection failure"
+- Give solution: What can the user do to proceed?  
+    Add clear instructions for the user regarding what to do next to resolve the error, e.g. “Try again”
+
+### Missing data points
+
+Indicate missing data with a special visual marker (like a different color or shape) to highlight the gaps without connecting them.
diff --git a/packages/documentation/docs/controls/charts/pie-chart.md b/packages/documentation/docs/controls/charts/pie-chart.md
@@ -3,22 +3,30 @@ import Playground from '@site/src/components/PlaygroundV3';
 
 # Pie chart
 
-## Examples
+Pie charts are a type of chart that displays data using a circular graph. The length of each slice is proportional to the value it represents. Pie charts are commonly used to visualize the parts of a whole and are particularly useful for comparing the relative sizes of different categories.
+
+### Pie chart
+
+Pie charts are typically used to visualize the parts of a whole. Each slice represents a different category, with the size of the slice proportional to the value it represents.
 
-### Donut chart
 
 <Playground
 height="40rem"
-name="echarts-circle"
+name="echarts-pie"
 noMargin
 examplesByName>
 </Playground>
 
-### Pie chart
+### Donut chart
+
+Donut charts are a variation of pie charts that have a hole in the center. Donut charts are often used to display the same information as a pie chart but an additional information can be displayed in the center of the chart.
+
+
 
 <Playground
 height="40rem"
-name="echarts-pie"
+name="echarts-circle"
 noMargin
 examplesByName>
 </Playground>
+
diff --git a/packages/documentation/docs/controls/charts/special-chart.md b/packages/documentation/docs/controls/charts/special-chart.md
@@ -6,18 +6,11 @@ import Playground from '@site/src/components/PlaygroundV3';
 
 # Functionalities
 
-ECharts offers a wide variety of different chart types and features. Following page deals with some more special chart types and chart features, which might become handy in some use cases.
-
-
-## Examples
-
+ECharts offers a wide variety of different chart types and features. Following page deals with some more special chart types and chart features, which might become handy in some use cases. 
 ### Interactive toolbox
 
-Apache ECharts offers a versatile toolbox that enables users to interact with and manipulate charts effectively.
-By default, the toolbox appears in the top right corner of the chart.
-You can customize this toolbox using the `toolbox` option within the option object.
+Apache ECharts offers a versatile toolbox that enables users to interact with and manipulate charts effectively. By default, the toolbox appears in the top right corner of the chart. The toolbox includes various interactive tools (like download, zoom, change type), each designed to enhance the user experience. You can customize this toolbox using the `toolbox` option within the option object.
 
-The toolbox includes various interactive tools (like download, zoom, change type), each designed to enhance the user experience.
 Below is an example demonstrating some of the most commonly used tools and how to configure them to suit your needs.
 
 <Playground

diff --git a/packages/form-field/form-field.md b/packages/form-field/form-field.md
diff --git a/packages/validation/validation.md b/packages/validation/validation.md