[RFC] CSS variable theme of antd

[MadCcc]

Summary

Provide a theme of antd, which defines tokens with css variables.

Activation

Currently each theme of antd will have a hash value calculated by tokens, which bring us ablilty to dynamicly recogonize diffrent styles of themes at runtime.

However, a new problem with SSR/SSG project came to us: #44617

As is known to all, css variables has perfectly performance in this case, such as: https://react.dev/ . And it will have better performance when switch themes at runtime with less js logic.

So is there any way to use css variables in antd with cssinjs? Here it is.

Basic Example

Users may get this theme from antd or somewhere else,

import React from 'react';
import { ConfigProvider } from 'antd';
import { cssVariableTheme } from 'xxx';

const App: React.FC = () => (
  <ConfigProvider theme={cssVariableTheme}>
    // anything
  </ConfigProvider>
)

Detailed Design

In the example above, we introduced a new theme called cssVariableTheme and can be passed into ConfigProvider, which will enable css variables in antd 5.x.

What's in cssVariableTheme?

Currently we have three preset themes in antd, and all of them differs in values of token. For example, colorBgBase in default theme is #fff, but it is #000 in dark theme.

In cssVariableTheme, the value of colorBgBase will not be a valid color. A css variable will be given to it, which means colorBgBase would stand for var(--color-bg-base). There's nothing changed if we still use this token in styles of antd components, because it is a part of css gramma. And we may get something like this:

.ant-btn {
  background: var(--color-bg-container);
}

Which used to be:

.ant-btn {
  background: #fff;
}

How about algorithms?

We used to calculate palattes in algorithms. But with css variables theme, we only reflect tokens to css variables:

export default () => {
  return {
    colorBgContainer: 'var(--color-bg-container)',
    colorBgLayout: 'var(--color-bg-layout)',
    // Other tokens
  };
}

In this way, we could transform tokens to css variables.

Customize theme

Actually users can still override token with ConfigProvider, such as setting colorPrimary to #1890ff. But it will break css variables.

The right way to customize theme is to provide different css variables values. It can be done in runtime or build-time, depends on what you like.

We could also make some tricks on ConfigProvider, such as directly changes --color-primary to #1890ff instead of overriding tokens, and remain colorPriamry as var(--color-primary).

Drawbacks

Unchanged Hash

Since tokens are given values like var(--color-bg-container), they will not change during theme switching because only values of css variables changed. It is expected that we should have the same hash when switching light theme to dark theme, or we will get warnings from react and break SSR hydration.

So actually we lose the ability of nested theme because css variables are global. To enable nested theme, we have to provide a set of new css variables or get the nested element to update css variables locally. It wil be something like this:

html {
  --color-primary: #1677ff;
}

.local {
  --color-primary: #1890ff;
}

But users should be aware of one thing: hash is still remain unchanged. This may have some side effects.

Invalid values

Another problem is that when we get token value with useToken, we can only get var(--color-primary), which is not a valid color (nor valid value in other cases). Sometimes we want to calculate some other colors based on token, and it seems impossible now. So ways to get actual value should be taken into consideration.

How to teach this

Provide documentation with examples to show what we could do with it. FAQs will be necessary.

[zombieJ]

nest ability could be:

.css-hash {
  --color-xxx: xxx;
  --color-xxx: xxx;
  --color-xxx: xxx;
  --color-xxx: xxx;
  --color-xxx: xxx;
  --color-xxx: xxx;
  --color-xxx: xxx;
  --color-xxx: xxx;
  --color-xxx: xxx;
  --color-xxx: xxx;
}

[zombieJ]

What if it get from the theme.useToken?

[MadCcc]

Mentioned in Drawback Invalid values

[MadCcc]

We expected to get css variables in antd when developing, but to get actual value for users.

[Dunqing]

Great. this will be a huge improvement for SSR and SSG, and useful for no calculation is required scenario.

I think the token calculation is possible If useToken still returns the original theme or at least has one property containing an original theme.

Like this?

const tokens = useToken()
tokens.originalTheme

[MadCcc]

Yeah, both returning css variables and returning actual value make sense. Only implementations differs.

[zombieJ]

theme: {
  algorithm: createCssVarAlgorithm({ light: lightAlgorithm, dark: darkAlgorithm })
}

theme: {
  algorithm: [createCssVarAlgorithm({ light: lightAlgorithm, dark: darkAlgorithm }), compactAlgorithm]
}

[yuxuan]

太好了，终于等到准备支持css variables了。

之前antd4的时候，用less+对less内置function的hack的方式把css variables通过less变量搞进去。Antd5换成cssinjs之后，基础token不能用css variables，因为会参与到颜色或者距离的计算（less也有这个问题），例如primary-color会被用到button点击效果的颜色上之类。

css variables可能会需要更精细的token控制，因为没办法参与计算，只能通过覆盖。这是我之前尝试时遇到的问题，可能有更好的解决办法

[agileago]

兜兜转转还是naiveui遥遥领先

[yoyo837]

没搜到呢, 全名是啥? 或者发个 仓库链接

[Wxh16144]

https://github.com/tusen-ai/naive-ui

[benedictjohannes]

I think this is an excellent idea. For documentation, I think it would be best to provide link to a full example CSS-variable theme implementaiton, like in codesandbox, because with this, theme customization is now done using pure CSS.

I wouldn't worry about SSR hydration though, workarounds are there such as changing themes using className; ie, using a top Provider component that add className to body.
For algorithms, this opens up the possibility to use CSS preprocessors such as Sass, which is a plus IMO.

Due to the large change in developer experience, as an alternative theming approach, this can also be its own package. Preferably under the same org and endorsed in the official docs like @ant-design/css-variable-theme.

[bombillazo]

Hey, I think this is a great step in the right direction for SSR. Right now we have a dynamic theme changing via the ConfigProvider context, and we've had to basically disable SSR for the whole app since we get hydration issues.

[Profesor08]

This will be great. Currently there is no way to pass an css variable to tokens. This will make posible to switch theme from outside of react. For example creating figma plugins, where all colors are provided from figma itself.

[Rey-Wang]

any updates on this?