TDesignOteam · LeonardoSya · Dec 12, 2025
diff --git a/site/docs/getting-started.md b/site/docs/getting-started.md
@@ -139,91 +139,6 @@ module.exports = {
 }
 ```
 
-### 更改样式
-
-有些业务场景需要更改组件的样式，但是`shadowDOM`具有天然样式隔离的特点，组件外部的样式影响不到组件内部，为此 TDesign Web Components 提供了几种方式来对样式进行更改：
-
-#### 通过设置`css`属性，来修改样式（推荐）
-
-目前每一个组件，都默认有一个`css`的属性，设置该值时会在`shadowDOM`内部创建`style`标签：
-
-```html
-<t-button css="button.t-button {color: red}">填充按钮</t-button>
-```
-
-会在组件内部，创建`style`标签，改变内部样式：
-
-```html
-<!-- DOM结构 -->
-<t-button
-  #shadow-root
-    <button>...</button>
-    <style>
-      button.t-button {
-        color: red;
-      }
-    </style>
-</t-button>
-```
-
-#### 通过设置`style`、`innerStyle`来改变样式
-
-**任意组件**，均可设置`style`和`innerStyle`，约定`style`只在最外层标签上起作用：
-
-```html
-<!-- 设置style -->
-<t-button style={{ color: 'red' }}>填充按钮</t-button>
-
-<!-- DOM结构 -->
-<t-button style="color: red">
-  #shadow-root
-    <button>...</button>
-</t-button>
-```
-
-约定`innerStyle`只在`shadowDOM`内部第一层标签上起作用：
-
-```html
-<!-- 设置innerStyle -->
-<t-button innerStyle={{ color: 'red' }}>填充按钮</t-button>
-
-<!-- 对应DOM结构 -->
-<t-button>
-  #shadow-root
-    <button style="color: red">...</button>
-</t-button>
-```
-
-#### 通过设置`class`、`innerClass`来改变样式（可以和`css`属性搭配使用）
-
-**任意组件**，均可设置`class`和`innerClass`，约定`class`只在最外层标签上起作用：
-
-```html
-<!-- 设置class -->
-<t-button class="customClass">填充按钮</t-button>
-
-<!-- 对应DOM结构 -->
-<t-button class="customClass">
-  #shadow-root
-    <button>...</button>
-</t-button>
-```
-
-约定`innerClass`只在`shadowDOM`内部第一层标签上起作用：
-
-```html
-<!-- 设置innerStyle -->
-<t-button innerClass="customClass">填充按钮</t-button>
-
-<!-- 对应DOM结构 -->
-<t-button>
-  #shadow-root
-    <button class="customClass">...</button>
-</t-button>
-```
-
-> 后续会推出基于打包工具的样式注入插件，敬请期待...
-
 ### 浏览器兼容性
 
 | [<img src="https://tdesign.gtimg.com/docs/edge_48x48.png" alt="IE / Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/> IE / Edge | [<img src="https://tdesign.gtimg.com/docs/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Firefox | [<img src="https://tdesign.gtimg.com/docs/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Chrome | [<img src="https://tdesign.gtimg.com/docs/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Safari |

diff --git a/site/docs/style.md b/site/docs/style.md
@@ -1,6 +1,107 @@
 ---
 title: 自定义样式
-description: xxxx
+description: 样式自定义指南
 spline: explain
 isGettingStarted: true
 ---
+
+## 概述
+
+TDesign Web Components 组件底层基于 Web Components 技术构建，提供了灵活的样式自定义方案。由于 Web Components 的 Shadow DOM 特性，传统的 CSS 选择器无法直接穿透组件内部样式，因此我们提供了以下两种样式自定义方式：
+
+1. **CSS Parts**：通过 `::part()` 伪元素选择器直接修改组件内部元素样式（[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/CSS/::part)）。
+2. **宿主属性选择器**：结合组件属性实现特定条件下的样式定制。
+
+## 方式一：CSS Parts
+
+CSS Parts 允许你直接选择和修改 Web Components 内部的特定元素。组件通过 `exportparts` 属性暴露内部元素（[了解更多](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/exportparts)），**因此，你可以使用 `::part()` 伪元素选择器来修改这些元素的样式。**
+
+### 基础用法
+
+以 Button 组件为例，先在 Chrome DevTools 中查看内部元素，**查看元素顶层的 `exportparts` 属性：**
+
+```html
+<t-button exportparts="t-button,t-button__text,t-button__suffix">
+  #shadow-root
+    <button class="t-button" part="t-button">
+      <slot name="icon">...</slot>
+      <span class="t-button__text" part="t-button__text"><slot>...</slot></span>
+    </button>
+</t-button>
+```
+
+可见，Button 组件暴露了以下 parts：
+1. `t-button`：按钮根元素
+2. `t-button__text`：按钮文字区域
+3. `t-button__suffix`：按钮后缀区域
+
+**我们可以使用 `::part()` 包裹元素提供的 parts 来修改样式：**
+
+```css
+/* 修改按钮的圆角 */
+t-button::part(t-button) {
+  border-radius: 100%;
+}
+
+/* 修改按钮文字样式 */
+t-button::part(t-button__text) {
+  font-weight: bold;
+  letter-spacing: 2px;
+}
+```
+
+### 配合伪类使用
+
+`::part()` 如何与 CSS 伪类结合使用：
+
+```css
+/* hover 状态 */
+t-button::part(t-button):hover {
+  transform: translateY(-5px);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+}
+
+/* focus 状态 */
+t-button::part(t-button):focus-visible {
+  outline: 2px solid #0052d9;
+  outline-offset: 2px;
+}
+```
+
+## 方式二：宿主属性选择器 + CSS Parts
+
+当需要根据组件的不同属性（如 `variant`、`theme`、`size` 等）应用不同样式时，可以使用 **宿主属性选择器** 配合 `::part()` 实现精确控制。
+
+> **注意：** 由于 CSS 规范限制，`::part()` 不能直接与 class 选择器组合（如 `::part(t-button).some-class` 的写法是无效的）。因此需要通过宿主元素的属性来区分。
+
+### 基础用法
+
+```css
+/* 只选中 variant="outline" 的按钮 */
+t-button[variant="outline"]::part(t-button) {
+  border-radius: 100%;
+}
+```
+
+### 配合状态属性和伪类
+
+```css
+/* outline + danger 主题 + focus-visible */
+t-button[variant="outline"][theme="danger"]:focus-visible::part(t-button) {
+  outline-color: #e34d59;
+}
+```
+
+## 常见问题
+
+### Q: 为什么我的 CSS 选择器不生效？
+A: 组件内部使用了 Shadow DOM，外部 CSS 无法直接穿透。请使用 CSS Parts 的方式修改。
+
+### Q: 为什么 `::part(t-button).some-class` 不生效？
+A: 这是 CSS 规范的限制，`::part()` 伪元素不能与 class 选择器组合使用。请改用宿主属性选择器，如 `t-button[variant="outline"]::part(t-button)` 这样的写法。
+
+### Q: 如何查看组件暴露了哪些 parts？
+A: 在浏览器开发者工具中检查组件的顶层 DOM，查找带有 `exportpart` 属性的元素。也可以查阅各组件的 API 文档。
+
+### Q: 宿主属性选择器支持哪些属性？
+A: 以 Button 组件为例，宿主属性如 `variant` 、 `theme` 、 `disabled` 、 `loading` 等需要作为 HTML 属性存在于 `<t-button>` 上。
diff --git a/site/pages/layout/td-wc-content/style.less b/site/pages/layout/td-wc-content/style.less
@@ -58,3 +58,11 @@
     }
   }
 }
+
+div[name='DOC'] ol,
+div[name='DEMO'] ol,
+div[name='API'] ol,
+// 文档页面有序列表 需要显示序号
+div[name='DESIGN'] ol {
+  list-style-type: decimal;
+}
diff --git a/site/sidebar.config.ts b/site/sidebar.config.ts
@@ -18,6 +18,13 @@ export default [
         path: '/webcomponents/custom-theme',
         component: () => import('@docs/theme.md'),
       },
+      {
+        title: '自定义样式',
+        titleEn: 'Style Customization',
+        name: 'style',
+        path: '/webcomponents/style',
+        component: () => import('@docs/style.md'),
+      },
       // {
       //   title: '最佳实践',
       //   titleEn: 'Starter Kit',