docs: config provider usage (#8856)

src/config-provider/README.md

@@ -16,11 +16,50 @@ const app = createApp();
 app.use(ConfigProvider);
 ```
 
-## Usage
+## Custom Theme
 
-### Custom Theme
+### CSS Variables
 
-Use `theme-vars` prop to custom theme variables。
+Vant organize component styles through [CSS Variables](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties), you can custom themes by overriding these CSS Variables.
+
+#### Demo
+
+Looking at the style of the Button component, you can see that the following variables exist on the `.van-button--primary` class:
+
+```css
+.van-button--primary {
+  color: var(--van-button-primary-color);
+  background-color: var(--van-button-primary-background-color);
+}
+```
+
+The default values of these variables are defined on the `root` node:
+
+```css
+:root {
+  --van-white: #fff;
+  --van-blue: #1989fa;
+  --van-button-primary-color: var(--van-white);
+  --van-button-primary-background-color: var(--van-blue);
+}
+```
+
+### Custom CSS Variables
+
+#### Override by CSS
+
+You can directly override these CSS variables in the code, and the style of the Button component will change accordingly:
+
+```css
+/* the Primary Button will turn red */
+:root {
+  --van-button-primary-background-color: red;
+}
+```
+
+#### Override by ConfigProvider
+
+The `ConfigProvider` component provides the ability to override CSS variables. You need to wrap a `ConfigProvider` component at the root node and configure some CSS variables through the `theme-vars` property.
 
 ```html
 <van-config-provider :theme-vars="themeVars">
@@ -51,8 +90,9 @@ export default {
   setup() {
     const rate = ref(4);
     const slider = ref(50);
-    const switchChecked = ref(true);
 
+    // ThemeVars will be converted to the corresponding CSS variable
+    // For example, sliderBarHeight will be converted to `--van-slider-bar-height`
     const themeVars = {
       rateIconFullColor: '#07c160',
       sliderBarHeight: '4px',
@@ -67,7 +107,6 @@ export default {
       rate,
       slider,
       themeVars,
-      switchChecked,
     };
   },
 };

src/config-provider/README.zh-CN.md

@@ -16,11 +16,50 @@ const app = createApp();
 app.use(ConfigProvider);
 ```
 
-## 代码演示
+## 定制主题
 
-### 自定义主题
+### 介绍
 
-通过 `theme-vars` 属性来自定义主题变量。
+Vant 组件通过丰富的 [CSS 变量](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) 来组织样式，通过覆盖这些 CSS 变量，可以实现**定制主题、动态切换主题**等效果。
+
+#### 示例
+
+以 Button 组件为例，查看组件的样式，可以看到 `.van-button--primary` 类名上存在以下变量：
+
+```css
+.van-button--primary {
+  color: var(--van-button-primary-color);
+  background-color: var(--van-button-primary-background-color);
+}
+```
+
+这些变量的默认值被定义在 `root` 节点上，HTML 文档的任何节点都可以访问到这些变量：
+
+```css
+:root {
+  --van-white: #fff;
+  --van-blue: #1989fa;
+  --van-button-primary-color: var(--van-white);
+  --van-button-primary-background-color: var(--van-blue);
+}
+```
+
+### 自定义 CSS 变量
+
+#### 通过 CSS 覆盖
+
+你可以直接在代码中覆盖这些 CSS 变量，Button 组件的样式会随之发生改变：
+
+```css
+/* 添加这段样式后，Primary Button 会变成红色 */
+:root {
+  --van-button-primary-background-color: red;
+}
+```
+
+#### 通过 ConfigProvider 覆盖
+
+`ConfigProvider` 组件提供了覆盖 CSS 变量的能力，你需要在根节点包裹一个 `ConfigProvider` 组件，并通过 `theme-vars` 属性来配置一些主题变量。
 
 ```html
 <van-config-provider :theme-vars="themeVars">
@@ -51,8 +90,9 @@ export default {
   setup() {
     const rate = ref(4);
     const slider = ref(50);
-    const switchChecked = ref(true);
 
+    // themeVars 内的值会被转换成对应 CSS 变量
+    // 比如 sliderBarHeight 会转换成 `--van-slider-bar-height`
     const themeVars = {
       rateIconFullColor: '#07c160',
       sliderBarHeight: '4px',
@@ -67,7 +107,6 @@ export default {
       rate,
       slider,
       themeVars,
-      switchChecked,
     };
   },
 };

src/config-provider/demo/index.vue

@@ -56,7 +56,7 @@ const i18n = {
     slider: '滑块',
     switch: '开关',
     submit: '提交',
-    customTheme: '自定义主题',
+    customTheme: '定制主题',
     defaultTheme: '默认主题',
   },
   'en-US': {