[Feature] Design Token for Apache ECharts

[Ovilia]

Background

Currently, there are several issues related to themes in ECharts:

1. Hardcoded literals in source code: These values are scattered across various components and lack unified
   management, leading to arbitrary use of default color values.
2. Theme registration via echarts.registerTheme: The parameters for theme registration lack systematic
   documentation, making it difficult for users to understand how to utilize them effectively.
3. Theme configuration via chart.setOption: Changing themes often requires modifications in multiple settings,
   leading to cumbersome processes.
4. Night mode as a hardcoded theme: Customizing the day theme does not allow for easy adaptation to night mode
   without additional development effort.

New Solution

We introduce a design token system to uniformly manage properties like colors, fonts, and spacing through token
names rather than using hardcoded literal values directly. This allows dynamic theme switching by resolving token
references during rendering. This approach makes styling more consistent and facilitates easy theme changes.

Usage

Using Tokens in setOption

ECharts provides a built-in set of default tokens that users can reference when setting options:

chart.setOption({
    series: [{
        type: 'bar',
        itemStyle: {
            borderColor: '@color-border',
            borderWidth: '@size-border'
        }
    }]
});

In this example, the bar chart uses the default style which does not include a border.

Customizing Themes

Custom themes can be registered using echarts.registerTheme:

echarts.registerTheme('custom-theme', {
    backgroundColor: '@color-background',
    title: {
        textStyle: {
            color: '@color-text-primary'
        },
        subtextStyle: {
            color: '@color-custom'
        }
    }
}, {
    color: {
        background: '#ffffff',
        text: {
            primary: '#333333'
        }
    }
});

This registers a custom theme where @color-background and @color-text-primary are tokens that can be overridden
when applying the theme.

Dynamic Changing Tokens

The tokens of a chart can be dynamically changed after a chart is created.

chart.setToken({
    'color-border': '#f00'
});

setToken is similar to setOption, and by default, it merges the new token with the existing one. It also supports
parameters like notMerge.

Generally, you should use setToken when you need to change a small part of the style of a chart instance (if you
need to change the overall style of the chart, consider using setTheme). In best practices, we recommend modifying
the token value via setToken to implement bulk changes for related elements' styles.

Technical Implementation

Approach Selection

We analyzed two potential approaches for implementing the token system:

1. In ZRender: This approach leverages the fact that tokens are closely tied to rendering decisions, making it
   more efficient and less error-prone.
2. In ECharts: This involves modifying all existing code to replace hardcoded values with token references and
   ensures that ZRender does not need to be modified.

Solution One: Implementing Token System in ZRender

ZRender Changes:

• （Complex）Design and manage the token system for storage.
• （Complex）Parse fill: '@color-border' and other attributes into literal values during rendering (can borrow the
  dirty approach to cache this with tokenDirty).

ECharts Changes:

• （Simple）Add a setToken method.
• （Simple）Update the setTheme method, binding tokens to themes when registering them.
• （Simple）Change all default styles to use tokens.

Implementation Effect:

• Use Token in Options: Parse token literals during rendering.
• Dynamic theme switching (or dark mode): Set tokenDirty for all elements, re-rendering them.

Solution Two: Implementing Token System in ECharts

ZRender Changes:

• None.

ECharts Changes:

• （Complex）Design and manage the token system, including storage.
• （Complex）Modify existing code where element styles are set, using parsed literals. Also store original token
  references.
• （Simple）Add a setToken method.
• （Complex）Update setTheme: Bind tokens to themes upon registration; iterate through all elements and update
  their styles based on token references.

Implementation Effect:

• Use Token in Options: Create elements and update styles by parsing token literals.
• Dynamic theme switching (or dark mode): Recompute token parsing for all elements.

Comparison of Solutions

Comparing the two solutions, Solution Two requires finding all elements and modifying related style codes, which is
not only labor-intensive but also prone to introducing bugs. Additionally, from a logical standpoint, the token
system is directly related to rendering, making it more suitable for handling in ZRender.

In summary, after careful consideration, we choose to implement the token system within ZRender. This approach aligns
logically with the rendering process and allows for incremental improvements without the risks associated with
extensive code modifications. By leveraging Solution One, we can effectively enhance the token system while
maintaining the stability of ECharts through minimal changes.

Thus, the optimal choice is to implement the token system in ZRender, ensuring both functional enhancements and
future scalability.

[100pah]

I am a rookie of design token. After reading the proposal, there are several issues I have not fully understood yet.

Create an new variable mechanism in echarts option or just use JS variable

If I understand correctly, the proposed approach can be analogous to CSS variables, which is introduced because it did not have one. But echarts option is set by JS, where JS variables seems to be usable naturally.
For example,

// JSON or JS defined dictionary, may generated by design tools.
const tokens = {
    color: {
        background: '#ffffff',
        text: {
            primary: '#333333'
        }
    }
};
const theme1 = {
    backgroundColor: tokens.color.background,
    title: {
        textStyle: {
            color: tokens.color.text.primary
        },
        subtextStyle: {
            color: tokens.color.custom
        }
    }
}
chart.setTheme(theme1);
// chart.setOption(option1); // Analogous structure

Should we introduce another template-like variable mechanism or just JS variable is enough?

Regarding dynamic changing tokens

The proposal mentioned that

chart.setToken({
    'color-border': '#f00'
});

But I haven't figured out in which scenario users need that.
In fact, this arises from another question I haven't clarified yet, see below.

Who defined the name of the tokens, only the users or both the users and echarts itself.

Typically the token name is supposed to be defined by users, if I understand it correctly.
The proposal mentioned that

Hardcoded literals in source code: These values are scattered across various components and lack unified
management, leading to arbitrary use of default color values.

If the new variable system intend to address the default echarts options values, echarts itself needs to define some built-in variable names. Will the values of those built-in variables be able to specified by users? If so, how do users establish the relationship between those built-in variable names and users' other tokens, which may be consistently generated by design tools or others?

Regarding Night mode

The proposal mentioned:

Night mode as a hardcoded theme: Customizing the day theme does not allow for easy adaptation to night mode
without additional development effort.

I have little experience about that and haven't grasp what the scenario is like yet.