# @visactor/vchart-arco-theme
## Description
The extension [ArcoDesign](https://github.com/arco-design) themes for [VChart](https://github.com/VisActor/VChart).
## Introduction for ArcoDesign
Upgraded from Byte Design, a comprehensive enterprise-level product design system.
### How does ArcoDesign come into being
ArcoDesign is short for a set of design system.
- The objective of ArcoDesign is to solve the experience problems occurred when using a product with a general design system and to provide guiding principles for product design to address problems occurred during the business. At the same time, it can also promote the cooperation between design department and R&D department and serve as the communication language among developers.
- ArcoDesign mainly serves the experience design and technical realization in the middle and back-end products of ByteDance and is mainly constructed and maintained by UED designers and developers.
### Design Language - Pragmatic Romanticism
#### ArcoDesign tries to establish a working mode
Pragmatism=Empathy; Romantism=Imagination
- First, pragmatism allows design system to solve most of the needs to greatly improve efficiency. Based on this, designers & developers can do more "romantic" things, that is, to develop more innovative and imaginative outcomes.
- On the product side, we can not only build basic functions pragmatically through the design system, but also use it to configure some romantic product pursuits.
- Romanticism and pragmatism is not contradictory. The philosophy of design language is derived through the definition of romanticism and pragmatism, which runs through the entire design system. They are complementary to each other to influence the design direction.
Currently, VChart provides specialized adaptation for ArcoDesign. More information about ArcoDesign can be found on the [website](https://arco.design/).
## Installing and Using VChart
ArcoDesign is currently mainly adapted to React projects. In React projects, you can use the following command to install react-vchart:
```bash
# npm
npm install @visactor/react-vchart
# yarn
yarn add @visactor/react-vchart
```
The method of drawing charts and more detailed guidance can be found in [this tutorial](https://visactor.io/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react).
## Chart Theme Package for ArcoDesign
In order to provide a better experience for VChart in the Arco page environment, VisActor has launched an additional theme package called `@visactor/vchart-arco-theme`. This package has the following features:
- Ready to use out of the box: With simple configuration, VChart styles can be automatically integrated into the ArcoDesign language and also automatically adapted to theme packages customized by users based on Arco.
- Responsive: `@visactor/vchart-arco-theme` supports listening for changes of light/dark mode and CSS variable update on the page, and automatically updates the theme of the charts on the page.
### DEMO
For a complete demo, please visit the [codeSandBox page](https://gr93cn-3000.csb.app/).
### Installation
[https://www.npmjs.com/package/@visactor/vchart-arco-theme](https://www.npmjs.com/package/@visactor/vchart-arco-theme)
```bash
# npm
npm install @visactor/vchart-arco-theme
# yarn
yarn add @visactor/vchart-arco-theme
```
### Usage
To access the default functionality, simply execute the `initVChartArcoTheme` method once globally for initialization. This statement can usually be placed in the entry file of a React project. As an example:
```javascript
import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './app.jsx';
import { initVChartArcoTheme } from '@visactor/vchart-arco-theme';
// initialization
initVChartArcoTheme();
const dom = document.querySelector('#root');
const root = createRoot(dom);
root.render();
```
The `initVChartArcoTheme` method supports passing in an object as a parameter, whose type declaration is:
```typescript
interface IInitVChartArcoThemeOption {
/** Initial light/dark mode */
defaultMode?: 'light' | 'dark';
/** Whether to listen for the light/dark mode switching and automatically change the chart theme. The default setting is true */
isWatchingMode?: boolean;
/** Specify a ThemeManager, usually not specified. If multiple versions of vchart coexist, it needs to be specified */
themeManager?: typeof ThemeManager;
}
```
### Token Mapping
In terms of functional design of chart themes, VChart supports custom configuration of data palettes and semantic color palettes. Based on this feature, the combination of VChart and ArcoDesign has been implemented by `@visactor/vchart-arco-theme`.
#### Data Palette
ArcoDesign declared the corresponding token for the data palette for VChart. Users can configure the following tokens when customizing themes in DSM to customize the data palette for VChart. The data palette of charts will automatically apply these variables, and users do not need to intervene. This feature is implemented by `@visactor/vchart-arco-theme`.
Index |
Arco Token |
Default Color |
1 |
--color-data-1
|
|
2 |
--color-data-2
|
|
3 |
--color-data-3
|
|
4 |
--color-data-4
|
|
5 |
--color-data-5
|
|
6 |
--color-data-6
|
|
7 |
--color-data-7
|
|
8 |
--color-data-8
|
|
9 |
--color-data-9
|
|
10 |
--color-data-10
|
|
11 |
--color-data-11
|
|
12 |
--color-data-12
|
|
13 |
--color-data-13
|
|
14 |
--color-data-14
|
|
15 |
--color-data-15
|
|
16 |
--color-data-16
|
|
17 |
--color-data-17
|
|
18 |
--color-data-18
|
|
19 |
--color-data-19
|
|
20 |
--color-data-20
|
|
The corresponding colors of these tokens form VChart's default 20 color palette in ArcoDesign.
As described in the [document](https://visactor.io/vchart/guide/tutorial_docs/Theme/Theme_Concept_and_Design_Rules), the VChart data palette can also be dynamic and progressive. In general, the color palette will be dynamically adjusted based on the range of data item quantities. When there are no more than 10 data groups, a 10 color palette should be used; When there are more than 10 data groups, a 20 color palette is used. If there are more than 20 data groups, the palette colors will be applied repeatedly, starting from the first one.
`@visactor/vchart-arco-theme` will automatically draw 10 colors from the 20 color palette mentioned earlier to form a 10 color palette that is compatible with small amounts of data. The current method is to take even indexed colors, which means that the default 10 color palette consists of the color values corresponding to the following tokens:
Index |
Arco Token |
Default Color |
1 |
--color-data-1
|
|
3 |
--color-data-3
|
|
5 |
--color-data-5
|
|
7 |
--color-data-7
|
|
9 |
--color-data-9
|
|
11 |
--color-data-11
|
|
13 |
--color-data-13
|
|
15 |
--color-data-15
|
|
17 |
--color-data-17
|
|
19 |
--color-data-19
|
|
#### Semantic Color Palette
In addition to the tokens mentioned earlier, `@visactor/vchart-arco-theme` will also automatically crawl other tokens of the current Arco theme in the page environment to generate a VChart chart theme. These tokens are mainly used for the styles of various chart components. You can refer to the following document for details:
- [VChart Theme Concept and Design Rules](https://visactor.io/vchart/guide/tutorial_docs/Theme/Theme_Concept_and_Design_Rules)
### Static resources
This package contains both static theme JSON resources (static resources only apply to the default Arco theme), which can be used on demand.
- [arcoDesignLight](https://raw.githubusercontent.com/VisActor/vchart-theme/main/packages/vchart-arco-theme/public/arcoDesignLight.json) Arco Design - light
- [arcoDesignDark](https://raw.githubusercontent.com/VisActor/vchart-theme/main/packages/vchart-arco-theme/public/arcoDesignDark.json) Arco Design - dark
## Debug
Run the following command from any location in the project to start the dev server:
```bash
rush arco
```