@visactor/vchart-arco-theme

Description

The extension ArcoDesign themes for 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.

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:

# 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.

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.

Installation

https://www.npmjs.com/package/@visactor/vchart-arco-theme

# 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:

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(<App />);

The initVChartArcoTheme method supports passing in an object as a parameter, whose type declaration is:

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	#4080FF
2	--color-data-2	#BEDAFF
3	--color-data-3	#55C5FD
4	--color-data-4	#9CDCFC
5	--color-data-5	#FF7D00
6	--color-data-6	#FFCF8B
7	--color-data-7	#4CD263
8	--color-data-8	#AFF0B5
9	--color-data-9	#A871E3
10	--color-data-10	#DDBEF6
11	--color-data-11	#F7BA1E
12	--color-data-12	#FADC6D
13	--color-data-13	#9FDB1D
14	--color-data-14	#C9E968
15	--color-data-15	#F979B7
16	--color-data-16	#FB9DC7
17	--color-data-17	#0FC6C2
18	--color-data-18	#86E8DD
19	--color-data-19	#E865DF
20	--color-data-20	#F7BAEF

The corresponding colors of these tokens form VChart's default 20 color palette in ArcoDesign.

As described in the document, 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	#4080FF
3	--color-data-3	#55C5FD
5	--color-data-5	#FF7D00
7	--color-data-7	#4CD263
9	--color-data-9	#A871E3
11	--color-data-11	#F7BA1E
13	--color-data-13	#9FDB1D
15	--color-data-15	#F979B7
17	--color-data-17	#0FC6C2
19	--color-data-19	#E865DF

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

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 Arco Design - light
• arcoDesignDark Arco Design - dark

Debug

Run the following command from any location in the project to start the dev server:

rush arco