docs: add css var documatation (#46189)

* docs: add css var documatation

* chore: remove hash

.dumi/pages/index/components/Theme/index.tsx

@@ -403,7 +403,6 @@ export default function Theme() {
           ...themeToken,
           colorPrimary: colorPrimaryValue,
         },
-        hashed: true,
         algorithm: algorithmFn,
         components: {
           Layout: isLight

.dumi/theme/builtins/DemoWrapper/index.tsx

@@ -50,27 +50,30 @@ const DemoWrapper: typeof DumiDemoGrid = ({ items }) => {
 
   const demos = React.useMemo(
     () =>
-      items.reduce((acc, item) => {
-        const { previewerProps } = item;
-        const { debug } = previewerProps;
+      items.reduce(
+        (acc, item) => {
+          const { previewerProps } = item;
+          const { debug } = previewerProps;
 
-        if (debug && !showDebug) return acc;
+          if (debug && !showDebug) return acc;
 
-        return acc.concat({
-          ...item,
-          previewerProps: {
-            ...previewerProps,
-            expand: expandAll,
-            // always override debug property, because dumi will hide debug demo in production
-            debug: false,
-            /**
-             * antd extra marker for the original debug
-             * @see https://github.com/ant-design/ant-design/pull/40130#issuecomment-1380208762
-             */
-            originDebug: debug,
-          },
-        });
-      }, [] as typeof items),
+          return acc.concat({
+            ...item,
+            previewerProps: {
+              ...previewerProps,
+              expand: expandAll,
+              // always override debug property, because dumi will hide debug demo in production
+              debug: false,
+              /**
+               * antd extra marker for the original debug
+               * @see https://github.com/ant-design/ant-design/pull/40130#issuecomment-1380208762
+               */
+              originDebug: debug,
+            },
+          });
+        },
+        [] as typeof items,
+      ),
     [expandAll, showDebug],
   );
 
@@ -107,7 +110,7 @@ const DemoWrapper: typeof DumiDemoGrid = ({ items }) => {
           )}
         </Tooltip>
       </span>
-      <ConfigProvider theme={{ cssVar: enableCssVar }}>
+      <ConfigProvider theme={{ cssVar: enableCssVar, hashed: !enableCssVar }}>
         <DumiDemoGrid items={demos} />
       </ConfigProvider>
     </div>

.dumi/theme/layouts/GlobalLayout.tsx

@@ -45,7 +45,7 @@ const getAlgorithm = (themes: ThemeName[] = []) =>
       }
       return null;
     })
-    .filter((item) => item) as typeof antdTheme.darkAlgorithm[];
+    .filter((item) => item) as (typeof antdTheme.darkAlgorithm)[];
 
 const GlobalLayout: React.FC = () => {
   const outlet = useOutlet();
@@ -178,6 +178,7 @@ const GlobalLayout: React.FC = () => {
                 motion: !theme.includes('motion-off'),
               },
               cssVar: true,
+              hashed: false,
             }}
           >
             <HappyProvider disabled={!theme.includes('happy-work')}>{content}</HappyProvider>

docs/react/common-props.en-US.md

@@ -1,8 +1,7 @@
 ---
 group:
-  title: Other
-  order: 0
-order: 0
+  title: Advanced
+order: 6
 title: Common Props
 ---
 

docs/react/common-props.zh-CN.md

@@ -1,8 +1,7 @@
 ---
 group:
-  title: 其他
-  order: 0
-order: 0
+  title: 进阶使用
+order: 6
 title: 通用属性
 ---
 

docs/react/css-variables.en-US.md

@@ -0,0 +1,76 @@
+---
+group:
+  title: Advanced
+order: 3
+title: CSS Variables
+tag: New
+---
+
+Since `5.12.0`, Ant Design 5.x enabled CSS variables again. Unlike 4.x, this time we have integrated the capabilities of CSS-in-JS, and all Design Tokens have been included in the management scope of CSS variables.
+
+> Currently, the CSS variable mode has been globally enabled on the official website.
+
+## When to Use
+
+CSS variable mode brings two important improvements to Ant Design's styling capabilities:
+
+1. The styles of the same component under different themes can be shared, reducing the total size of the styles
+2. When switching themes, there is no need to re-serialize the styles, which improves the performance of theme switching
+
+Therefore, if your application depends on Ant Design's theme capabilities, we strongly recommend that you enable the CSS variable mode.
+
+## Quick Start
+
+To enable CSS variable mode, use the `cssVar` configuration in the `theme` property of ConfigProvider. This configuration will be inherited, so if you want to enable CSS variable mode globally, you only need to configure it in the root of your application.
+
+<!-- prettier-ignore -->
+:::warning
+CSS variable mode requires a unique key for each theme to ensure style isolation. 
+In React 18, we use `useId` to generate unique keys by default, so you don't have to worry about this issue in React 18.
+But in React 17 or 16, you need to manually set a unique key for each theme, otherwise the themes will be mixed up.
+:::
+
+```tsx
+// React 18
+<ConfigProvider theme={{ cssVar: true }}>
+  <App />
+</ConfigProvider>
+
+// React 17 or 16
+<ConfigProvider theme={{ cssVar: { key: 'app' } }}>
+  <App />
+</ConfigProvider>
+```
+
+After enabling it, you can see that some specific values in the antd component styles have been replaced with CSS variables:
+
+![image](https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*p5NrRJmUNHgAAAAAAAAAAAAADrJ8AQ/original)
+
+## Advanced
+
+### Disable Hash
+
+Hash is one of the features since Ant Design 5.0. Its function is to calculate a unique hash value for each theme, and use it in the class of the component to isolate the theme style.
+
+However, after enabling CSS variables, the component styles of the same antd version will not change with the token —— because we use CSS variables to fill in the dynamic parts of the styles. So if there is only one version of antd in your application, you can choose to disable hash to further reduce the total size of the styles:
+
+```tsx
+<ConfigProvider theme={{ cssVar: true, hashed: false }}>
+  <App />
+</ConfigProvider>
+```
+
+By the way, we strongly recommend using `extractStyle` to extract static styles, which will bring a certain amount of performance improvement to the application.
+
+### Customize Theme
+
+With CSS variable mode, the method of modifying the theme is the same as before, refer to [Customize Theme](/docs/react/customize-theme).
+
+## API
+
+`cssVar` configuration:
+
+| Properties | Description | Type | Default | Version |
+| --- | --- | --- | --- | --- |
+| prefix | Prefix of CSS Variables | string | `ant` | 5.12.0 |
+| key | The unique key of theme. Automaticly set by `useId` in React 18, but need to be set manually in React 17 or 16 | string | `useId` in React 18 | 5.12.0 |

docs/react/css-variables.zh-CN.md

@@ -0,0 +1,75 @@
+---
+group:
+  title: 进阶使用
+order: 3
+title: 使用 CSS 变量
+tag: New
+---
+
+从 `5.12.0` 起，Ant Design 5.x 重新支持了 CSS 变量。与 4.x 版本不同的是，这次我们融合了 CSS-in-JS 的能力，并且将所有 Design Token 纳入了 CSS 变量的管理范畴。
+
+> 目前 CSS 变量模式已在 Ant Design 官网上全局开启。
+
+## 何时使用
+
+CSS 变量模式为 Ant Design 的样式能力带来了两个重要的提升：
+
+1. 同一组件在不同主题下的样式可以共享，减少了样式体积
+2. 切换主题时不再需要重新序列化样式，提升了主题切换的性能
+
+因此如果你的应用依赖了 Ant Design 的主题能力，那么我们强烈建议你开启 CSS 变量模式。
+
+## 快速上手
+
+在 ConfigProvider 的 `theme` 属性中，通过 `cssVar` 配置来开启 CSS 变量模式。这个配置会被继承，所以希望全局开启 CSS 变量模式的话，只需要在根节点的 ConfigProvider 中配置即可。
+
+<!-- prettier-ignore -->
+:::warning
+CSS 变量模式需要为每一个主题设置独特的 key 来保证样式隔离，在 React 18 中我们使用了 `useId` 来生成唯一的 key，所以在 React 18 中，你可以不用关心这个问题。
+但是在 React 17 或者 16 中，你需要手动为每一个主题设置一个唯一的 key，否则会导致主题混乱。
+:::
+
+```tsx
+// React 18
+<ConfigProvider theme={{ cssVar: true }}>
+  <App />
+</ConfigProvider>
+
+// React 17 or 16
+<ConfigProvider theme={{ cssVar: { key: 'app' } }}>
+  <App />
+</ConfigProvider>
+```
+
+开启后审查元素，就可以看到 antd 组件样式中一些原本具体的数值被替换为了 CSS 变量：
+
+![image](https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*p5NrRJmUNHgAAAAAAAAAAAAADrJ8AQ/original)
+
+## 进阶使用
+
+### 关闭 hash
+
+hash 是 Ant Design 5.0 以来的特性之一，其功能是为每一份主题计算一个独特的 hash 值，并将其用在组件的 class 上，用于隔离主题样式。
+
+但是启用了 CSS 变量之后，相同 antd 版本下的组件样式将不会随着 token 变化而改变 —— 因为我们用 CSS 变量填充了样式中的动态部分。所以如果你的应用中只存在一个版本的 antd，你可以选择关闭 hash 来进一步减小样式体积：
+
+```tsx
+<ConfigProvider theme={{ cssVar: true, hashed: false }}>
+  <App />
+</ConfigProvider>
+```
+
+同时我们非常推荐使用 `extractStyle` 来抽取静态样式，这样会为应用性能带来一定量的提升。
+
+### 修改主题
+
+在 CSS 变量模式下，修改主题的方法与之前无异，参考 [定制主题](/docs/react/customize-theme-cn)。
+
+## API
+
+`cssVar` 目前支持的参数：
+
+| 属性 | 说明 | 类型 | 默认值 | 版本 |
+| --- | --- | --- | --- | --- |
+| prefix | CSS 变量的前缀 | string | `ant` | 5.12.0 |
+| key | 当前主题的唯一识别 key. 在 React 18 中会默认用 `useId` 填充，小于 React 18 的版本需要手动填充。 | string | `useId` in React 18 | 5.12.0 |

docs/react/customize-theme.en-US.md

@@ -4,7 +4,6 @@ group:
   order: 1
 order: 0
 title: Customize Theme
-tag: Updated
 ---
 
 Ant Design allows you to customize our design tokens to satisfy UI diversity from business or brand requirements, including primary color, border radius, border color, etc.
@@ -329,9 +328,9 @@ const globalToken = getDesignToken();
 Same as ConfigProvider, `getDesignToken` could also accept a config object as `theme`:
 
 ```tsx
-import { createRoot } from 'react-dom/client';
 import type { ThemeConfig } from 'antd';
 import { theme } from 'antd';
+import { createRoot } from 'react-dom/client';
 
 const { getDesignToken, useToken } = theme;
 

docs/react/customize-theme.zh-CN.md

@@ -4,7 +4,6 @@ group:
   order: 1
 order: 0
 title: 定制主题
-tag: Updated
 ---
 
 Ant Design 设计规范和技术上支持灵活的样式定制，以满足业务和品牌上多样化的视觉需求，包括但不限于全局样式（主色、圆角、边框）和指定组件的视觉定制。

docs/react/i18n.en-US.md

@@ -1,7 +1,7 @@
 ---
 group:
   title: Advanced
-order: 4
+order: 5
 title: Internationalization
 ---
 

docs/react/i18n.zh-CN.md

@@ -1,7 +1,7 @@
 ---
 group:
   title: 进阶使用
-order: 4
+order: 5
 title: 国际化
 ---
 

docs/react/server-side-rendering.en-US.md

@@ -3,7 +3,6 @@ group:
   title: Advanced
 order: 2
 title: Server Side Rendering
-tag: New
 ---
 
 There are two options for server-side rendering styles, each with advantages and disadvantages:

docs/react/server-side-rendering.zh-CN.md

@@ -3,7 +3,6 @@ group:
   title: 进阶使用
 order: 2
 title: 服务端渲染
-tag: New
 ---
 
 服务端渲染样式有两种方案，它们各有优缺点：

docs/react/use-custom-date-library.en-US.md

@@ -1,7 +1,7 @@
 ---
 group:
   title: Advanced
-order: 3
+order: 4
 title: Use custom date library
 ---
 

docs/react/use-custom-date-library.zh-CN.md

@@ -1,7 +1,7 @@
 ---
 group:
   title: 进阶使用
-order: 3
+order: 4
 title: 使用自定义日期库
 ---