@visactor/vchart-semi-theme

Description

The extension Semi Design themes for VChart.

What is Semi

Semi Design is a design system designed, developed and maintained by the Douyin front-end team and the MED product design team. As a comprehensive, easy-to-use, and high-quality modern enterprise-level application UI solution, it is refined from the complex scenes of Bytedance various business lines, supports nearly a thousand platform products, and serves 100,000+ internal and external users.

After nearly two years of iteration, Semi Design has become a cross-departmental infrastructure after various types of business landing verification, and has formed a rich tool chain and ecology around the component library. In order to allow the increasingly mature design system to serve more users and to further explore the usage scenarios, we decided to open source Semi and use the power of the community to continuously improve and expand the capability boundary.

Currently, VChart provides specialized adaptation for Semi Design. More information about Semi Design can be found on the website.

Installing and Using VChart

Semi Design 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 Semi Design

In order to provide a better experience for VChart in the Semi page environment, VisActor has launched an additional theme package called @visactor/vchart-semi-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 Semi design language and also automatically adapted to theme packages customized by users through Semi DSM.
• Responsive: @visactor/vchart-semi-theme supports listening for changes of light/dark mode and theme switching 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-semi-theme

# npm
npm install @visactor/vchart-semi-theme

# yarn
yarn add @visactor/vchart-semi-theme

Usage

To access the default functionality, simply execute the initVChartSemiTheme 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 { initVChartSemiTheme } from '@visactor/vchart-semi-theme';

// initialization
initVChartSemiTheme();

const dom = document.querySelector('#root');
const root = createRoot(dom);
root.render(<App />);

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

interface IInitVChartSemiThemeOption {
  /** 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;
  /** Whether to listen for theme switching and automatically change the chart theme. The default setting is false (applicable to the official theme switching interface of Semi: https://semi.design/dsm/install_switcher) */
  isWatchingThemeSwitch?: boolean;
  /** Specify a ThemeManager, usually not specified. If multiple versions of vchart coexist, it needs to be specified */
  themeManager?: typeof ThemeManager;
}

For example, if you want to enable listening for theme switching on the user side, the initialization statement can be changed as follows:

// initialization
initVChartSemiTheme({
  isWatchingThemeSwitch: true
});

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 Semi Design has been implemented by @visactor/vchart-semi-theme.

Data Palette

Semi Design 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-semi-theme.

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

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

Semantic Color Palette

In addition to the tokens mentioned earlier, @visactor/vchart-semi-theme will also automatically crawl other tokens of the current Semi 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 Semi theme), which can be used on demand.

• semiDesignLight Semi Design - light
• semiDesignDark Semi Design - dark

Debug

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

rush semi