From 15cf92969c1f47ccd0b73c975666293acf876733 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Sat, 14 Jun 2025 17:34:27 +0800
Subject: [PATCH] docs: clarify CSS Modules class name generation

---
 website/docs/en/guide/styling/css-modules.mdx | 22 +++++++++++++++++--
 website/docs/zh/guide/styling/css-modules.mdx | 22 +++++++++++++++++--
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/website/docs/en/guide/styling/css-modules.mdx b/website/docs/en/guide/styling/css-modules.mdx
index 5e550cbbd6..a57451520d 100644
--- a/website/docs/en/guide/styling/css-modules.mdx
+++ b/website/docs/en/guide/styling/css-modules.mdx
@@ -15,7 +15,7 @@ The following style files are considered CSS Modules:
 
 ## Usage example
 
-- Write style:
+Write style in `*.module.css` file:
 
 ```css title="button.module.css"
 .red {
@@ -23,7 +23,7 @@ The following style files are considered CSS Modules:
 }
 ```
 
-- Using styles:
+Import styles in JavaScript file:
 
 ```tsx title="Button.tsx"
 import styles from './button.module.css';
@@ -33,6 +33,24 @@ export default () => {
 };
 ```
 
+After compilation, CSS Modules class names are automatically appended with a hash value to prevent class name conflicts:
+
+```css
+/* classnames generated in development mode */
+.src-App-module__red-hiQIE4 {
+  background: red;
+}
+
+/* classnames generated in production mode */
+.red-hiQIE4 {
+  background: red;
+}
+```
+
+:::tip
+See [Custom Class Names](#custom-class-names) to modify the class name generation rules.
+:::
+
 ## Named import
 
 If you prefer to use named imports in CSS Modules, you can enable it through the [output.cssModules.namedExport](/config/output/css-modules#cssmodulesnamedexport) config.
diff --git a/website/docs/zh/guide/styling/css-modules.mdx b/website/docs/zh/guide/styling/css-modules.mdx
index 63f8e7e48f..9690c064f6 100644
--- a/website/docs/zh/guide/styling/css-modules.mdx
+++ b/website/docs/zh/guide/styling/css-modules.mdx
@@ -15,7 +15,7 @@ Rsbuild 默认支持使用 CSS Modules，无需添加额外的配置。我们约
 
 ## 用法示例
 
-- 编写样式：
+在 `*.module.css` 文件中编写样式：
 
 ```css title="button.module.css"
 .red {
@@ -23,7 +23,7 @@ Rsbuild 默认支持使用 CSS Modules，无需添加额外的配置。我们约
 }
 ```
 
-- 使用样式：
+在 JavaScript 文件中导入样式：
 
 ```tsx title="Button.tsx"
 import styles from './button.module.css';
@@ -33,6 +33,24 @@ export default () => {
 };
 ```
 
+经过编译后，CSS Modules 中的类名会自动添加一个哈希值，以避免类名冲突：
+
+```css
+/* 开发模式下生成的类名 */
+.src-App-module__red-hiQIE4 {
+  background: red;
+}
+
+/* 生产模式下生成的类名 */
+.red-hiQIE4 {
+  background: red;
+}
+```
+
+:::tip
+参考 [自定义类名](#自定义类名) 来修改生成类名的规则。
+:::
+
 ## 具名导入
 
 如果你倾向于在 CSS Modules 中使用具名导入，可以通过 [output.cssModules.namedExport](/config/output/css-modules#cssmodulesnamedexport) 配置项来开启。