feat: init guidelines (#198)

docs/plugins/development/sass-palette/guide.md

@@ -103,9 +103,9 @@ If the Scss file is not imported directly, but is imported through `@use` or `@i
 
 ::: tip
 
-- If you are developing a plugin, you may set `$dark-selector: html.dark !default;` in default config files, as `@vuepress/theme-default` is doing that.
+- If you are developing a plugin, you may set `$dark-selector: [data-theme="dark"] !default;` in default config files, as our guideline is asking this.
 
-  Your plugin will work with default theme, and users are allowed to change this selector in config file if they are using a third-party theme with different dark selector.
+  Your plugin will work with most of theme, and users are still allowed to change this selector in config file if they are using a third-party theme with different dark selector.
 
 - If you are developing a theme, you may set `$dark-selector` in default config files with your darkmode selector without `!default`, to insure users cannot override it.
 
@@ -180,15 +180,15 @@ $bg-color: (
 ) !default;
 ```
 
-Then if `$dark-selector` has a value `"html.dark"` in config file, you will get:
+Then if `$dark-selector` has a value `"[data-theme="dark"]"` in config file, you will get:
 
 ```scss
 :root {
   --text-color: #222;
   --bg-color: #fff;
 }
 
-html.dark {
+[data-theme='dark'] {
   --text-color: #999;
   --bg-color: #1e1e1e;
 }

docs/plugins/features/copy-code.md

@@ -29,7 +29,7 @@ export default {
 ### selector
 
 - Type: `string | string[]`
-- Default: `'.theme-default-content div[class*="language-"] pre'`
+- Default: `'[vp-content] div[class*="language-"] pre'`
 - Details:
 
   Code block selector
@@ -187,4 +187,4 @@ export default {
 
 You can customize the icon of the _copy button_ via CSS variables:
 
-@[code{1-6} css](@vuepress/plugin-copy-code/src/client/styles/copy-code.css)
+@[code{1-6} css](@vuepress/plugin-copy-code/src/client/styles/vars.css)

docs/plugins/features/medium-zoom.md

@@ -30,7 +30,7 @@ export default {
 
 - Type: `string`
 
-- Default: `':not(a) > img'`
+- Default: `'[vp-content] > img, [vp-content] :not(a) > img'`
 
 - Details:
 

docs/plugins/features/photo-swipe.md

@@ -43,7 +43,7 @@ In preview mode, you can:
 ### selector
 
 - Type: `string | string[]`
-- Default: `".theme-default-content :not(a) > img:not([no-view])"`
+- Default: `"[vp-content] :not(a) > img:not([no-view])"`
 - Details: Image selector
 
 ### download

docs/plugins/markdown/markdown-image.md

@@ -150,13 +150,13 @@ If the image is standalone in a line, wrapped or not wrapped by link, it will be
 ### lightmodeSelector
 
 - Type: `string`
-- Default: `'html:not(.dark)'`
+- Default: `'[data-theme="light"]'`
 - Details: The selector to detect light mode.
 
 ### darkmodeSelector
 
 - Type: `string`
-- Default: `'html.dark'`
+- Default: `'[data-theme="dark"]'`
 - Details: The selector to detect dark mode.
 
 <script setup>

docs/plugins/search/docsearch.md

@@ -77,13 +77,13 @@ new Crawler({
               selectors: '.vp-sidebar-heading.active',
               defaultValue: 'Documentation',
             },
-            lvl1: '.theme-default-content h1',
-            lvl2: '.theme-default-content h2',
-            lvl3: '.theme-default-content h3',
-            lvl4: '.theme-default-content h4',
-            lvl5: '.theme-default-content h5',
-            lvl6: '.theme-default-content h6',
-            content: '.theme-default-content p, .theme-default-content li',
+            lvl1: '[vp-content] h1',
+            lvl2: '[vp-content] h2',
+            lvl3: '[vp-content] h3',
+            lvl4: '[vp-content] h4',
+            lvl5: '[vp-content] h5',
+            lvl6: '[vp-content] h6',
+            content: '[vp-content] p, [vp-content] li',
           },
           indexHeadings: true,
         })

docs/themes/default/frontmatter.md

@@ -49,7 +49,7 @@ pageClass: custom-page-class
 Then you can customize styles of this page in `.vuepress/styles/index.scss` file:
 
 ```scss
-.theme-container.custom-page-class {
+[vp-container].custom-page-class {
   /* page styles */
 }
 ```

docs/themes/guidelines.md

@@ -0,0 +1,76 @@
+# Theme Guidelines
+
+To avoid theme developers and users setting unneeded options, we have a set of guidelines that should be followed when creating a theme.
+
+## DOM Structure
+
+A theme must implement the following DOM structure:
+
+- Container: An element which contains the entire theme. This element should have an attribute `vp-container`.
+- Content: An element which holds markdown render results. This element should have an attribute `vp-content`.
+
+A theme may have the following optional elements:
+
+- Navbar: Navbar of the site. This element should have an attribute `vp-navbar`.
+- Sidebar: Sidebar of the site. This element should have an attribute `vp-sidebar`.
+- Outline: Headings or outline of the main content. This element should have an attribute `vp-outline`.
+- Comment: Comment service (comment box and comment list). This element should have an attribute `vp-comment`.
+- Footer: Footer of the site. This element should have an attribute `vp-footer`.
+
+A theme must:
+
+- Set `data-theme` to `dark` on html in darkmode.
+- Set `data-theme` to `light` on html in lightmode.
+
+If it only have one color scheme, it still needs to set `data-theme` to `light` or `dark` to indicate the default color scheme.
+
+## Color Variables
+
+A theme must implement the following color variables:
+
+### Text
+
+- `--vp-c-text`: Default text color.
+- `--vp-c-text-mute`: Colors for muted texts, such as "inactive menu" or "info texts".
+- `--vp-c-text-subtle`: Color for subtle text, such as as "placeholders" or "caret icon".
+
+### Background
+
+- `--vp-c-bg`: The bg color used for main screen.
+- `--vp-c-bg-alt`: The alternative bg color used in places such as "sidebar", or "code block".
+- `--vp-c-bg-elv`: The elevated bg color. This is used at parts where it "floats", such as "dialog".
+
+### Shadow
+
+- `--vp-c-shadow`: The normal shadow color
+- `--vp-c-shadow-hard`: The shadow color used for hard shadow, such as "dialog".
+
+### Accent
+
+Accent color and brand colors which used for interactive components.
+
+- `--vp-c-accent`: The most solid color used mainly for colored text. It must satisfy the contrast ratio against when used on top of `--vp-c-accent-soft`.
+- `--vp-c-accent-hover`: Color used for hover state.
+- `--vp-c-accent-bg`: Color used for solid background. It must satisfy the contrast ratio with `--vp-c-accent-text` on top of it.
+- `--vp-c-accent-text`: Color used for text with `--vp-c-accent-bg` background. It must satisfy the contrast ratio with `--vp-c-accent-bg`.
+- `--vp-c-accent-soft`: The color used for subtle background such as custom container or badges. It must satisfy the contrast ratio when putting `--vp-c-accent` colors on top of it.
+
+  The soft color must be semi transparent alpha channel. This is crucial because it allows adding multiple "soft" colors on top of each other to create a accent, such as when having inline code block inside custom containers.
+
+### Borders
+
+- `--vp-c-border`: Border color for interactive components. For example this should be used for a button outline.
+- `--vp-c-border-hard`: Darker border colors, which is used for "hard" borders closed to text, such as table and kbd.
+- `--vp-c-divider`: Color for separators, used to divide sections within the same components, such as having separator on "h2" heading.
+
+### Controls
+
+- `--vp-c-control`: Background color for interactive controls, such as buttons or checkboxes.
+- `--vp-c-control-hover`: Background color for hover state of interactive controls.
+- `--vp-c-control-active`: Background color for active or focus state of interactive controls.
+- `--vp-c-control-disabled`: Color for disabled state of interactive controls.
+
+## Transition timing
+
+- `--vp-t-color`: Color transition timing.
+- `--vp-t-transform`: Transform transition timing.

docs/tools/helper/client.md

@@ -78,7 +78,7 @@ export interface GetHeadersOptions {
    * It will be passed as an argument to `document.querySelectorAll(selector)`,
    * so you should pass a `CSS Selector` string.
    *
-   * @default '#vp-content h1, #vp-content h2, #vp-content h3, #vp-content h4, #vp-content h5, #vp-content h6'
+   * @default '[vp-content] h1, [vp-content] h2, [vp-content] h3, [vp-content] h4, [vp-content] h5, [vp-content] h6'
    */
   selector?: string
   /**
@@ -148,7 +148,7 @@ export type MenuItem = Omit<Header, 'children' | 'slug'> & {
 ```ts
 onMounted(() => {
   const headers = getHeaders({
-    selector: '#vp-content :where(h1,h2,h3,h4,h5,h6)',
+    selector: '[vp-content] :where(h1,h2,h3,h4,h5,h6)',
     levels: [2, 3], // only h2 and h3
     ignore: ['.badge'], // ignore the <Badge /> within the header
   })

docs/zh/plugins/development/sass-palette/guide.md

@@ -101,9 +101,9 @@ $sidebar-width: 18rem !default;
 
 ::: tip
 
-- 如果你正在开发插件，你可以在默认配置文件中设置 `$dark-selector: html.dark !default;`，因为这是 `@vuepress/theme-default` 的默认行为。
+- 如果你正在开发插件，你可以在默认配置文件中设置 `$dark-selector: [data-theme="dark"] !default;`，因为这是社区对主题的推荐要求。
 
-  你的插件将在默认主题正常工作，如果用户使用具有不同深色模式选择器的第三方主题，则用户可以在配置文件中更改此选择器。
+  你的插件将在绝大多主题中正常工作，如果用户使用具有不同深色模式选择器的第三方主题，则用户可以在配置文件中更改此选择器。
 
 - 如果你在开发主题，你可以在默认配置文件中设置 `$dark-selector` 为你的深色模式选择器同时不包含 `!default`，确保用户不能覆盖它。
 
@@ -178,15 +178,15 @@ $bg-color: (
 ) !default;
 ```
 
-然后，如果在配置文件中 `$dark-selector` 的值为 `"html.dark"`，你会得到:
+然后，如果在配置文件中 `$dark-selector` 的值为 `"[data-theme="dark"]"`，你会得到:
 
 ```scss
 :root {
   --text-color: #222;
   --bg-color: #fff;
 }
 
-html.dark {
+[data-theme='dark'] {
   --text-color: #999;
   --bg-color: #1e1e1e;
 }

docs/zh/plugins/features/copy-code.md

@@ -29,7 +29,7 @@ export default {
 ### selector
 
 - 类型：`string | string[]`
-- 默认值：`'.theme-default-content div[class*="language-"] pre'`
+- 默认值：`'[vp-content] div[class*="language-"] pre'`
 - 详情:
 
   代码块选择器
@@ -185,4 +185,4 @@ export default {
 
 你可以通过 CSS 变量来自定义*复制按钮*的样式：
 
-@[code{1-6} css](@vuepress/plugin-copy-code/src/client/styles/copy-code.css)
+@[code{1-6} css](@vuepress/plugin-copy-code/src/client/styles/vars.css)

docs/zh/plugins/features/medium-zoom.md

@@ -30,7 +30,7 @@ export default {
 
 - 类型： `string`
 
-- 默认值： `':not(a) > img'`
+- 默认值： `'[vp-content] > img, [vp-content] :not(a) > img'`
 
 - 详情：
 

docs/zh/plugins/features/photo-swipe.md

@@ -43,7 +43,7 @@ export default {
 ### selector
 
 - 类型：`string | string[]`
-- 默认值：`".theme-default-content :not(a) > img:not([no-view])"`
+- 默认值：`"[vp-content] :not(a) > img:not([no-view])"`
 - 详情：图片选择器
 
 ### download

docs/zh/plugins/markdown/markdown-image.md

@@ -149,13 +149,13 @@ interface ImageMarkOptions {
 ### lightmodeSelector
 
 - 类型：`string`
-- 默认值：`'html:not(.dark)'`
+- 默认值：`'[data-theme="light"]'`
 - 详情：日间模式的选择器。
 
 ### darkmodeSelector
 
 - 类型：`string`
-- 默认值：`'html.dark'`
+- 默认值：`'[data-theme="dark"]'`
 - 详情：夜间模式的选择器。
 
 <script setup>

docs/zh/plugins/search/docsearch.md

@@ -76,13 +76,13 @@ new Crawler({
               selectors: '.vp-sidebar-heading.active',
               defaultValue: 'Documentation',
             },
-            lvl1: '.theme-default-content h1',
-            lvl2: '.theme-default-content h2',
-            lvl3: '.theme-default-content h3',
-            lvl4: '.theme-default-content h4',
-            lvl5: '.theme-default-content h5',
-            lvl6: '.theme-default-content h6',
-            content: '.theme-default-content p, .theme-default-content li',
+            lvl1: '[vp-content] h1',
+            lvl2: '[vp-content] h2',
+            lvl3: '[vp-content] h3',
+            lvl4: '[vp-content] h4',
+            lvl5: '[vp-content] h5',
+            lvl6: '[vp-content] h6',
+            content: '[vp-content] p, [vp-content] li',
           },
           indexHeadings: true,
         })

docs/zh/themes/default/frontmatter.md

@@ -49,7 +49,7 @@ pageClass: custom-page-class
 然后你可以在 `.vuepress/styles/index.scss` 文件中为这个页面添加自定义样式：
 
 ```scss
-.theme-container.custom-page-class {
+[vp-container].custom-page-class {
   /* 页面样式 */
 }
 ```

docs/zh/themes/guidelines.md

@@ -0,0 +1,76 @@
+# 主题指南
+
+为了避免主题开发者和用户设置不必要的选项，我们制定了一套主题创建时应遵循的指南。
+
+## DOM 结构
+
+一个主题必须实现以下 DOM 结构：
+
+- 容器：一个包含整个主题的元素。此元素应该有一个 `vp-container` 属性。
+- 内容：一个包含 markdown 渲染结果的元素。此元素应该有一个 `vp-content` 属性。
+
+一个主题可以有以下可选元素：
+
+- 导航栏：站点的导航栏。此元素应该有一个 `vp-navbar` 属性。
+- 侧边栏：站点的侧边栏。此元素应该有一个 `vp-sidebar` 属性。
+- 大纲：主要内容的标题或大纲。此元素应该有一个 `vp-outline` 属性。
+- 评论：评论服务（评论框和评论列表）。此元素应该有一个 `vp-comment` 属性。
+- 页脚：站点的页脚。此元素应该有一个 `vp-footer` 属性。
+
+一个主题必须：
+
+- 在暗色模式下，将 html 元素的 `data-theme` 设置为 `dark`。
+- 在亮色模式下，将 html 元素的 `data-theme` 设置为 `light`。
+
+如果主题只有一种颜色方案，主题仍然需要将 `data-theme` 设置为 `light` 或 `dark`，以指示默认颜色方案。
+
+## 颜色变量
+
+一个主题必须实现以下颜色变量：
+
+### 文字
+
+- `--vp-c-text`：默认文本颜色。
+- `--vp-c-text-mute`：用于静音文本的颜色，例如“非活动菜单”或“信息文本”。
+- `--vp-c-text-subtle`：用于细微文本的颜色，例如“占位符”或“插入符号”。
+
+### 背景
+
+- `--vp-c-bg`：用于主屏幕的背景颜色。
+- `--vp-c-bg-alt`：用于“侧边栏”或“代码块”等地方的备用背景颜色。
+- `--vp-c-bg-elv`：用于“浮动”部分的提升背景颜色，例如“对话框”。
+
+### 阴影
+
+- `--vp-c-shadow`：正常阴影颜色
+- `--vp-c-shadow-hard`：用于硬阴影的阴影颜色，例如“对话框”。
+
+### 强调
+
+用于交互组件的强调颜色和品牌颜色。
+
+- `--vp-c-accent`：主要用于彩色文本的最实色。它必须满足与放在 `--vp-c-accent-soft` 顶部时的对比度。
+- `--vp-c-accent-hover`：用于悬停状态的颜色。
+- `--vp-c-accent-bg`：用于实色背景的颜色。它必须满足与放在其顶部的 `--vp-c-accent-text` 的对比度。
+- `--vp-c-accent-text`：用于 `--vp-c-accent-bg` 背景的文本颜色。它必须满足与 `--vp-c-accent-bg` 的对比度。
+- `--vp-c-accent-soft`：用于自定义容器或徽章等细微背景的颜色。当将 `--vp-c-accent` 颜色放在其顶部时，它必须满足对比度。
+
+  软色必须是半透明的 alpha 通道。这是至关重要的，因为它允许将多个“软”颜色叠加在一起以创建强调，例如在自定义容器内部有内联代码块时。
+
+### 边框
+
+- `--vp-c-border`：交互组件的边框颜色。例如，这应该用于按钮轮廓。
+- `--vp-c-border-hard`：较暗的边框颜色，用于紧贴文本的“硬”边框，例如表格和 kbd。
+- `--vp-c-divider`：分隔符的颜色，用于在同一组件内分隔部分，例如在“h2”标题上放置分隔符。
+
+### 控件
+
+- `--vp-c-control`：用于交互控件（例如按钮或复选框）的背景颜色。
+- `--vp-c-control-hover`：用于交互控件悬停状态的背景颜色。
+- `--vp-c-control-active`：用于交互控件的活动或焦点状态的背景颜色。
+- `--vp-c-control-disabled`：用于交互控件禁用状态的颜色。
+
+## 过渡时间
+
+- `--vp-t-color`：颜色过渡时间。
+- `--vp-t-transform`：变换过渡时间。