docs: add dark mode usage & compile dark/css-vars.css (#7513)

* docs: add dark mode usage & compile dark/css-vars.css

* docs: add example link

docs/.vitepress/crowdin/en-US/pages/guide.json

@@ -2,8 +2,14 @@
   "intro": {
     "text": "Basics",
     "children": [
-      { "text": "Design", "link": "/guide/design" },
-      { "text": "Navigation", "link": "/guide/nav" },
+      {
+        "text": "Design",
+        "link": "/guide/design"
+      },
+      {
+        "text": "Navigation",
+        "link": "/guide/nav"
+      },
       {
         "text": "Installation",
         "link": "/guide/installation"
@@ -17,13 +23,27 @@
   "advanced": {
     "text": "Advanced",
     "children": [
-      { "text": "i18n", "link": "/guide/i18n" },
+      {
+        "text": "i18n",
+        "link": "/guide/i18n"
+      },
       {
         "text": "Migration from ElementUI",
         "link": "/guide/migration"
       },
-      { "text": "Theming", "link": "/guide/theming" },
-      { "text": "Built-in Transitions", "link": "/guide/transitions" },
+      {
+        "text": "Theming",
+        "link": "/guide/theming"
+      },
+      {
+        "text": "Dark Mode",
+        "link": "/guide/dark-mode",
+        "promotion": "2.2.0"
+      },
+      {
+        "text": "Built-in Transitions",
+        "link": "/guide/transitions"
+      },
       {
         "text": "Changelog",
         "link": "/guide/changelog"

docs/.vitepress/vitepress/components/dev/VersionTag.vue

@@ -0,0 +1,11 @@
+<script lang="ts" setup>
+defineProps<{
+  version: string
+}>()
+</script>
+
+<template>
+  <el-tag size="small" effect="plain" hit round>
+    {{ version }}
+  </el-tag>
+</template>

docs/.vitepress/vitepress/components/sidebar/vp-sidebar-link.vue

@@ -24,15 +24,7 @@ const route = useRoute()
     @click="$emit('close')"
   >
     <p class="link-text">{{ item.text }}</p>
-    <ElTag
-      v-if="item.promotion"
-      class="ml-2"
-      size="small"
-      effect="plain"
-      hit
-      style="border-radius: 9999px"
-      >{{ item.promotion }}</ElTag
-    >
+    <VersionTag v-if="item.promotion" class="ml-2" :version="item.promotion" />
   </a>
 </template>
 

docs/components.d.ts

@@ -55,6 +55,7 @@ declare module '@vue/runtime-core' {
     ToggleButton: typeof import('./.vitepress/vitepress/components/icons/toggle-button.vue')['default']
     ToggleSidebarBtn: typeof import('./.vitepress/vitepress/components/subnav/toggle-sidebar-btn.vue')['default']
     TopNavigationExample: typeof import('./.vitepress/vitepress/components/nav/top-navigation-example.vue')['default']
+    VersionTag: typeof import('./.vitepress/vitepress/components/dev/VersionTag.vue')['default']
     VpApp: typeof import('./.vitepress/vitepress/components/vp-app.vue')['default']
     VpChangelog: typeof import('./.vitepress/vitepress/components/globals/vp-changelog.vue')['default']
     VpContent: typeof import('./.vitepress/vitepress/components/vp-content.vue')['default']

docs/en-US/component/button.md

@@ -85,7 +85,7 @@ button/size
 
 :::
 
-## Custom Color <el-tag>beta</el-tag>
+## Custom Color <VersionTag version="beta" />
 
 You can custom button color.
 

docs/en-US/component/table-v2.md

@@ -3,7 +3,7 @@ title: Virtualized Table
 lang: en-US
 ---
 
-# Virtualized Table <el-tag round effect="plain">Beta</el-tag>
+# Virtualized Table <VersionTag version="beta" />
 
 Along with the evolutionary web development, table component has always been the most popular component in our web apps especially for dashboards, data analysis. For [Table V1](./table.md), with even just 1000 records of data, it can be very annoying when using it, because the poor performance.
 

docs/en-US/guide/dark-mode.md

@@ -0,0 +1,84 @@
+---
+title: Dark Mode
+lang: en-US
+---
+
+# Dark Mode <VersionTag version="2.2.0" />
+
+After a long time, Element Plus supports dark mode!
+
+We extracted and unified all necessary variables to make it possible to implement based on CSS Vars.
+
+## How to enable it?
+
+First you can create a switch to toggle `dark` class of html.
+
+> If you only need dark mode, just add `dark` class for html.
+
+```html
+<html class="dark">
+  <head></head>
+  <body></body>
+</html>
+```
+
+> If you want to toggle it, i recommend [useDark | VueUse](https://vueuse.org/core/useDark/).
+
+Then, you can quickly enable it with just one line of code to import CSS in your entry.
+
+```ts
+// main.ts
+// if you just want to import css
+import 'element-plus/theme-chalk/dark/css-vars.css'
+```
+
+> If you want an example, you can refer to [element-plus-vite-starter](https://github.com/element-plus/element-plus-vite-starter).
+
+## Custom variables
+
+### By CSS
+
+Just override it by CSS Vars.
+
+For example, new file `styles/dark/css-vars.css`:
+
+```css
+html.dark {
+  /* custom dark bg color */
+  --el-bg-color: #626aef;
+}
+```
+
+Import it after styles of Element Plus:
+
+```ts
+// main.ts
+import 'element-plus/theme-chalk/dark/css-vars.css'
+import './styles/dark/css-vars.css'
+```
+
+### By SCSS
+
+If you use scss, you can also import scss file to compile.
+
+> You can refer [Theming](./theming.md) to get more info.
+
+```scss
+// styles/element/index.scss
+/*just override what you need*/
+@forward 'element-plus/theme-chalk/src/dark/var.scss' with (
+  $bg-color: (
+    'page': #0a0a0a,
+    '': #626aef,
+    'overlay': #1d1e1f,
+  )
+);
+```
+
+```ts
+// main.ts
+import './styles/element/index.scss'
+
+// or just want to import scss?
+// import 'element-plus/theme-chalk/src/dark/css-vars.scss'
+```

packages/theme-chalk/gulpfile.ts

@@ -42,6 +42,27 @@ function buildThemeChalk() {
     .pipe(dest(distFolder))
 }
 
+/**
+ * Build dark Css Vars
+ * @returns
+ */
+function buildDarkCssVars() {
+  const sass = gulpSass(dartSass)
+  return src(path.resolve(__dirname, 'src/dark/css-vars.scss'))
+    .pipe(sass.sync())
+    .pipe(autoprefixer({ cascade: false }))
+    .pipe(
+      cleanCSS({}, (details) => {
+        consola.success(
+          `${chalk.cyan(details.name)}: ${chalk.yellow(
+            details.stats.originalSize / 1000
+          )} KB -> ${chalk.green(details.stats.minifiedSize / 1000)} KB`
+        )
+      })
+    )
+    .pipe(dest(`${distFolder}/dark`))
+}
+
 /**
  * copy from packages/theme-chalk/dist to dist/element-plus/theme-chalk
  */
@@ -61,7 +82,7 @@ export function copyThemeChalkSource() {
 
 export const build = parallel(
   copyThemeChalkSource,
-  series(buildThemeChalk, copyThemeChalkBundle)
+  series(buildThemeChalk, buildDarkCssVars, copyThemeChalkBundle)
 )
 
 export default build