From 34a3fe8787f8f7a75a21635619ff41bc91274931 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan@youzan.com>
Date: Mon, 14 Jun 2021 10:07:00 +0800
Subject: [PATCH] docs: config provider usage (#8856)

---
 src/config-provider/README.md       | 49 ++++++++++++++++++++++++++---
 src/config-provider/README.zh-CN.md | 49 ++++++++++++++++++++++++++---
 src/config-provider/demo/index.vue  |  2 +-
 3 files changed, 89 insertions(+), 11 deletions(-)

diff --git a/src/config-provider/README.md b/src/config-provider/README.md
index a558cbcb8..ff3e0f42b 100644
--- a/src/config-provider/README.md
+++ b/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,
     };
   },
 };
diff --git a/src/config-provider/README.zh-CN.md b/src/config-provider/README.zh-CN.md
index 35df9be9c..a654d81ac 100644
--- a/src/config-provider/README.zh-CN.md
+++ b/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,
     };
   },
 };
diff --git a/src/config-provider/demo/index.vue b/src/config-provider/demo/index.vue
index 5d3d05440..cf4e76c81 100644
--- a/src/config-provider/demo/index.vue
+++ b/src/config-provider/demo/index.vue
@@ -56,7 +56,7 @@ const i18n = {
     slider: '滑块',
     switch: '开关',
     submit: '提交',
-    customTheme: '自定义主题',
+    customTheme: '定制主题',
     defaultTheme: '默认主题',
   },
   'en-US': {