fix(styles): handle search icon in RTL

fix(styles): handle RTL
fix(tabs): handle RTL
2026-07-18 21:38:03 +08:00 · 2026-07-16 17:27:40 +08:00 · 2026-07-16 17:27:25 +08:00 · 2026-07-16 17:27:08 +08:00 · 2026-07-14 10:54:53 +08:00 · 2026-07-14 10:51:43 +08:00
668 changed files with 16901 additions and 14651 deletions
@@ -1,6 +1,6 @@
 ---
 title: ButtonGroup 按钮组
-description: 将相关按钮组合在一起，并提供一致的样式与间距。
+description: 将相关按钮组合在一起，保持一致的样式与间距
 links:
  rac: Button
  source: button-group/button-group.tsx
@@ -9,21 +9,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { ButtonGroup, Button } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="button-group-basic"
 />

-### 组件结构
-
-导入 ButtonGroup 组件后，可通过点语法访问所有子部分。
+## 组件结构

 ```tsx
 import { ButtonGroup, Button } from '@heroui/react';
@@ -43,7 +39,9 @@ export default () => (
 );
 ```

-> **ButtonGroup** 将多个 Button 组件包裹在一起，应用一致的样式、间距以及自动圆角处理。它使用 React Context 将 `size`、`variant` 与 `isDisabled` props 传递给所有子按钮。
+> **ButtonGroup** 将多个 Button 组合在一起，应用一致的样式、间距与自动圆角处理。它通过 React Context 向所有子按钮传递 `size`、`variant` 与 `isDisabled` 属性。
+
+## 示例

 ### 变体

@@ -59,7 +57,7 @@ export default () => (

 ### 方向

-使用 `orientation` prop 将按钮按水平或垂直方向排列。
+使用 `orientation` 属性可水平或垂直排列按钮。

 <ComponentPreview
  name="button-group-orientation"
@@ -71,7 +69,7 @@ export default () => (
  name="button-group-with-icons"
 />

-### 全宽
+### 宽度充满

 <ComponentPreview
  name="button-group-full-width"
@@ -85,42 +83,22 @@ export default () => (

 ### 无分隔线

-直接在按钮中省略 `<ButtonGroup.Separator />` 组件即可。
+省略按钮中的 `<ButtonGroup.Separator />` 组件即可。

 <ComponentPreview
  name="button-group-without-separator"
 />

-<RelatedComponents component="button-group" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="button-group-custom-styles" />

-```tsx
-import { ButtonGroup, Button } from '@heroui/react';
+### 全局 CSS

-function CustomButtonGroup() {
-  return (
-    <ButtonGroup className="gap-2">
-      <Button>First</Button>
-      <Button>
-        <ButtonGroup.Separator />
-        Second
-      </Button>
-      <Button>
-        <ButtonGroup.Separator />
-        Third
-      </Button>
-    </ButtonGroup>
-  );
-}
-```
-
-### 自定义组件类
-
-要自定义 ButtonGroup 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+可使用 `@layer components` 指令自定义 ButtonGroup 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -134,52 +112,56 @@ function CustomButtonGroup() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-ButtonGroup 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)）：
+ButtonGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)）：

-#### 基础类
-
- `.button-group` - 按钮组容器的基础样式
+#### 基础类 [!toc]
+- `.button-group` - 按钮组根容器
 - `.button-group--full-width` - 全宽修饰符
- `.button-group__separator` - 按钮之间的分隔线元素
+- `.button-group__separator` - 按钮之间的分隔元素

-ButtonGroup 会自动为按钮处理圆角：
+ButtonGroup 组件自动为按钮应用圆角：
+- 第一个按钮圆角左/起始边
+- 最后一个按钮圆角右/结束边
+- 中间按钮无圆角
+- 单个按钮四边全圆角

- 第一个按钮获得左侧/起始侧圆角
- 最后一个按钮获得右侧/结束侧圆角
- 中间按钮不带圆角
- 仅有一个按钮时，四边都会应用完整圆角
-
-在每个 Button（第一个除外）内部添加 `<ButtonGroup.Separator />`，即可在按钮之间显示分隔线。
+在每个 Button 内（第一个除外）添加 `<ButtonGroup.Separator />` 以显示分隔线。

 ## API 参考

-### ButtonGroup Props
+### ButtonGroup

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'` | - | 应用于组内所有按钮的视觉变体 |
 | `size` | `'sm' \| 'md' \| 'lg'` | - | 应用于组内所有按钮的尺寸 |
-| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 按钮组的排列方向 |
-| `fullWidth` | `boolean` | `false` | 按钮组是否占满容器宽度 |
-| `isDisabled` | `boolean` | `false` | 是否禁用组内全部按钮（可在单个按钮上覆盖） |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `children` | `React.ReactNode` | - | 需要组合在一起的按钮组件 |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 按钮组方向 |
+| `fullWidth` | `boolean` | `false` | 是否占满容器宽度 |
+| `isDisabled` | `boolean` | `false` | 是否禁用组内所有按钮（单个按钮可覆盖） |
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `React.ReactNode` | - | 要组合的 Button 组件 |

-### ButtonGroup.Separator Props
+### ButtonGroup.Separator

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |

-### 说明
+## 说明

- ButtonGroup 使用 React Context 将 `size`、`variant` 与 `isDisabled` props 传递给所有子 Button 组件
- **只有直接子级按钮会接收 ButtonGroup 的 props**：即使某个按钮是 ButtonGroup 的后代，只要它嵌套在其他组件（如 Modal、Dropdown）中，就不会继承组级 props
- 单个 Button 可通过设置 `isDisabled={false}` 覆盖组级别的 `isDisabled`
- 组件会自动处理按钮之间的圆角
- 在每个 Button（第一个除外）中添加 `<ButtonGroup.Separator />` 可显示分隔线
- 按钮组中的按钮会移除激活/按压时的缩放变换，以获得更统一的视觉效果
+- ButtonGroup 通过 React Context 向所有子 Button 传递 `size`、`variant` 与 `isDisabled` 属性
+- **仅直接子按钮接收 ButtonGroup 属性** - 嵌套在其他组件（如 Modal、Dropdown 等）内的 Button 即使位于 ButtonGroup 后代也不会继承组属性
+- 单个 Button 可通过 `isDisabled={false}` 覆盖组的 `isDisabled` 属性
+- 组件自动处理按钮之间的圆角
+- 在每个 Button 内（第一个除外）添加 `<ButtonGroup.Separator />` 以显示分隔线
+- 组内按钮移除 active/pressed 缩放变换，外观更统一
+
+## 相关组件
+
+<RelatedComponents component="button-group" />
@@ -1,6 +1,6 @@
 ---
 title: Button 按钮
-description: 可点击的按钮组件，支持多种变体与状态。
+description: 可点击的按钮组件，支持多种变体与状态
 links:
  rac: Button
  source: button/button.tsx
@@ -9,25 +9,30 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Button } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="button-basic"
 />

-### 变体
+## 示例

+### 变体

 <ComponentPreview
  name="button-variants"
 />

+### 尺寸
+
+<ComponentPreview
+  name="button-sizes"
+/>
+
 ### 带图标

 <ComponentPreview
@@ -46,19 +51,13 @@ import { Button } from '@heroui/react';
  name="button-loading"
 />

-### 加载状态
+### 加载中（点击触发）

 <ComponentPreview
  name="button-loading-state"
 />

-### 尺寸
-
-<ComponentPreview
-  name="button-sizes"
-/>
-
-### 全宽
+### 宽度充满

 <ComponentPreview
  name="button-full-width"
@@ -66,47 +65,48 @@ import { Button } from '@heroui/react';

 ### 禁用状态

-
 <ComponentPreview
  name="button-disabled"
 />

-### 社交按钮
+### 社交媒体按钮

 <ComponentPreview
  name="button-social"
 />

-### 自定义渲染函数
+### 渲染函数

 <ComponentPreview
-  name="button-custom-render-function"
+  name="button-render-function"
 />

-<RelatedComponents component="button" />
+### 添加自定义变体

-<RelatedShowcases component="Button" />
+可通过包装组件并添加自定义变体来扩展 HeroUI 组件。

-## 样式
+<ComponentPreview
+  name="button-custom-variants"
+/>

-### 传入 Tailwind CSS 类
+### 添加涟漪效果

-```tsx
-import { Button } from '@heroui/react';
+Button 组件通过组合支持 ripple 效果，可将 ripple 组件作为子节点嵌套。本示例使用 [m3-ripple](https://github.com/saltyaom/m3-ripple)。

-function CustomButton() {
-  return (
-    <Button className="bg-purple-500 text-white hover:bg-purple-600">
-      Purple Button
-    </Button>
-  );
-}
-```
+<ComponentPreview
+  name="button-ripple-effect"
+/>

-### 自定义组件类
+## 自定义样式

-若要自定义 Button 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+### Tailwind CSS
+
+<ComponentPreview name="button-custom-styles" />
+
+### 全局 CSS
+
+可使用 `@layer components` 指令自定义 Button 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -120,35 +120,21 @@ function CustomButton() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

-### 添加自定义变体
-
-你可以通过封装 HeroUI 组件并添加自定义变体来扩展其能力。
-
-<ComponentPreview
-  name="button-custom-variants"
-/>
-
-### 添加涟漪效果
-
-Button 组件支持通过组合方式实现涟漪效果，你可以将涟漪组件作为子节点嵌套。此示例使用 [m3-ripple](https://github.com/saltyaom/m3-ripple)。
-
-<ComponentPreview
-  name="button-ripple-effect"
-/>
-
 ### CSS 类

 Button 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css)）：

-#### 基础与尺寸类
- `.button` - 按钮基础样式
+#### 基础与尺寸类 [!toc]
+- `.button` - 基础按钮样式
 - `.button--sm` - 小尺寸变体
 - `.button--md` - 中尺寸变体
 - `.button--lg` - 大尺寸变体

-#### 变体类
+#### 变体类 [!toc]
 - `.button--primary`
 - `.button--secondary`
 - `.button--tertiary`
@@ -156,46 +142,54 @@ Button 组件使用以下 CSS 类（[查看源码样式](https://github.com/hero
 - `.button--ghost`
 - `.button--danger`

-#### 修饰符类
+#### 修饰符类 [!toc]
 - `.button--icon-only`
 - `.button--icon-only.button--sm`
 - `.button--icon-only.button--lg`

 ### 交互状态

-该按钮同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：
+按钮同时支持 CSS 伪类与 data 属性：

- **悬停**：`:hover` 或 `[data-hovered="true"]`
- **激活/按压**：`:active` 或 `[data-pressed="true"]`（包含缩放变换）
- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环）
- **禁用**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度，禁用指针事件）
- **等待中**：`[data-pending]`（加载期间禁用指针事件）
+- **Hover**：`:hover` 或 `[data-hovered="true"]`
+- **Active/Pressed**：`:active` 或 `[data-pressed="true"]`（含缩放变换）
+- **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环）
+- **Disabled**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度，禁用指针事件）
+- **Pending**：`[data-pending]`（加载期间禁用指针事件）

 ## API 参考

-### Button Props
+### Button

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | 视觉样式变体 |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 按钮尺寸 |
-| `fullWidth` | `boolean` | `false` | 按钮是否占满容器宽度 |
-| `isDisabled` | `boolean` | `false` | 按钮是否禁用 |
-| `isPending` | `boolean` | `false` | 按钮是否处于加载状态 |
-| `isIconOnly` | `boolean` | `false` | 按钮是否仅包含图标 |
-| `onPress` | `(e: PressEvent) => void` | - | 按钮被按下时的事件处理函数 |
-| `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | 按钮内容或渲染 prop |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+| `fullWidth` | `boolean` | `false` | 是否占满容器宽度 |
+| `isDisabled` | `boolean` | `false` | 是否禁用 |
+| `isPending` | `boolean` | `false` | 是否处于加载状态 |
+| `isIconOnly` | `boolean` | `false` | 是否仅包含图标 |
+| `onPress` | `(e: PressEvent) => void` | - | 按下时的回调 |
+| `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | 按钮内容或 render prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### ButtonRenderProps
+### Render Props

-使用渲染 prop 模式时，会提供以下值：
+使用 render prop 模式时，提供以下值：

 | Prop | 类型 | 描述 |
 |------|------|------|
-| `isPending` | `boolean` | 按钮是否处于加载状态 |
-| `isPressed` | `boolean` | 按钮当前是否被按压 |
-| `isHovered` | `boolean` | 按钮是否处于悬停状态 |
-| `isFocused` | `boolean` | 按钮是否处于聚焦状态 |
-| `isFocusVisible` | `boolean` | 按钮是否应显示焦点指示 |
-| `isDisabled` | `boolean` | 按钮是否禁用 |
+| `isPending` | `boolean` | 是否处于加载状态 |
+| `isPressed` | `boolean` | 是否正在按下 |
+| `isHovered` | `boolean` | 是否悬停 |
+| `isFocused` | `boolean` | 是否聚焦 |
+| `isFocusVisible` | `boolean` | 是否显示焦点指示器 |
+| `isDisabled` | `boolean` | 是否禁用 |
+
+## 相关案例
+
+<RelatedShowcases component="Button" />
+
+## 相关组件
+
+<RelatedComponents component="button" />
@@ -1,6 +1,6 @@
 ---
 title: CloseButton 关闭按钮
-description: 用于关闭对话框、模态框或收起内容的按钮组件。
+description: 用于关闭对话框、模态框或 dismiss 内容的按钮组件
 links:
  rac: Button
  source: close-button/close-button.tsx
@@ -8,48 +8,40 @@ links:
  storybook: Components/Buttons/CloseButton
 ---

-## 引入
+## 用法

 ```tsx
 import { CloseButton } from "@heroui/react";
 ```

-### 用法
-
 <ComponentPreview
  name="close-button-default"
 />

+## 示例
+
+### 交互
+
+<ComponentPreview
+  name="close-button-interactive"
+/>
+
 ### 自定义图标

 <ComponentPreview
  name="close-button-with-custom-icon"
 />

-### 交互
+## 自定义样式

-<ComponentPreview
-  name="close-button-interactive"
-/>
+### Tailwind CSS

-<RelatedComponents component="closebutton" />
+<ComponentPreview name="close-button-custom-styles" />

-## 样式
+### 全局 CSS

-### 传入 Tailwind CSS 类
-
-```tsx
-import {CloseButton} from "@heroui/react";
-
-function CustomCloseButton() {
-  return <CloseButton className="text-red-600 hover:bg-red-100">Close</CloseButton>;
-}
-```
-
-### 自定义组件类
-
-要自定义 CloseButton 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+可使用 `@layer components` 指令自定义 CloseButton 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -63,57 +55,63 @@ function CustomCloseButton() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-CloseButton 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/close-button.css)）：
+CloseButton 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/close-button.css)）：

-#### 基础类
+#### 基础类 [!toc]

- `.close-button` - 组件基础样式
+- `.close-button` - 基础组件样式

-#### 变体类
+#### 变体类 [!toc]

 - `.close-button--default` - 默认变体

 ### 交互状态

-该组件同时支持 CSS 伪类与 data 属性，便于灵活编写样式：
+组件同时支持 CSS 伪类与 data 属性：

- **悬停**：`:hover` 或 `[data-hovered="true"]`
- **激活/按压**：`:active` 或 `[data-pressed="true"]`
- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`
- **禁用**：`:disabled` 或 `[aria-disabled="true"]`
+- **Hover**：`:hover` 或 `[data-hovered="true"]`
+- **Active/Pressed**：`:active` 或 `[data-pressed="true"]`
+- **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **Disabled**：`:disabled` 或 `[aria-disabled="true"]`

 ## API 参考

-### CloseButton Props
+### CloseButton

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
-| `variant` | `"default"` | `"default"` | 按钮的视觉变体 |
+|------|------|--------|------|
+| `variant` | `"default"` | `"default"` | 按钮视觉变体 |
 | `children` | `ReactNode \| function` | `<CloseIcon />` | 显示内容（默认为关闭图标） |
-| `onPress` | `() => void` | - | 按钮按下时触发的事件处理函数 |
-| `isDisabled` | `boolean` | `false` | 是否禁用按钮 |
+| `onPress` | `() => void` | - | 按下时的回调 |
+| `isDisabled` | `boolean` | `false` | 是否禁用 |

 ### React Aria Button Props

-CloseButton 继承所有 React Aria Button props。常见 props 包括：
+CloseButton 继承所有 React Aria Button 属性。常用属性包括：

 | Prop | 类型 | 描述 |
-| ---- | ---- | ---- |
-| `aria-label` | `string` | 提供给屏幕阅读器的无障碍标签 |
-| `aria-labelledby` | `string` | 用于标注按钮的元素 id |
-| `aria-describedby` | `string` | 用于描述按钮的元素 id |
+|------|------|------|
+| `aria-label` | `string` | 屏幕阅读器的无障碍标签 |
+| `aria-labelledby` | `string` | 标注按钮的元素 ID |
+| `aria-describedby` | `string` | 描述按钮的元素 ID |

-### RenderProps
+### Render Props

-使用渲染 prop 模式时，会提供以下值：
+使用 render prop 模式时，提供以下值：

 | Prop | 类型 | 描述 |
-| ---- | ---- | ---- |
-| `isHovered` | `boolean` | 按钮是否处于悬停状态 |
-| `isPressed` | `boolean` | 按钮是否处于按压状态 |
-| `isFocused` | `boolean` | 按钮是否处于聚焦状态 |
-| `isDisabled` | `boolean` | 按钮是否禁用 |
+|------|------|------|
+| `isHovered` | `boolean` | 是否悬停 |
+| `isPressed` | `boolean` | 是否按下 |
+| `isFocused` | `boolean` | 是否聚焦 |
+| `isDisabled` | `boolean` | 是否禁用 |
+
+## 相关组件
+
+<RelatedComponents component="closebutton" />
@@ -9,19 +9,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="toggle-button-group-basic"
 />

-### 组件结构
+## 组件结构

 导入 ToggleButtonGroup 组件，并通过点语法访问所有子部分。

@@ -43,6 +41,8 @@ export default () => (
 );
 ```

+## 示例
+
 ### 尺寸

 <ComponentPreview
@@ -55,34 +55,12 @@ export default () => (
  name="toggle-button-group-orientation"
 />

-### 分离模式
-
-使用 `isDetached` 让按钮之间留出间隔，而不是彼此连接。
-
-<ComponentPreview
-  name="toggle-button-group-attached"
-/>
-
-### 全宽
+### 宽度充满

 <ComponentPreview
  name="toggle-button-group-full-width"
 />

-### 选择模式
-
-使用 `selectionMode="single"` 实现互斥选择，或使用 `selectionMode="multiple"` 实现独立切换。
-
-<ComponentPreview
-  name="toggle-button-group-selection-mode"
-/>
-
-### 受控
-
-<ComponentPreview
-  name="toggle-button-group-controlled"
-/>
-
 ### 禁用

 <ComponentPreview
@@ -91,38 +69,43 @@ export default () => (

 ### 无分隔线

-在按钮中直接省略 `<ToggleButtonGroup.Separator />` 组件即可。
+省略按钮中的 `<ToggleButtonGroup.Separator />` 组件即可。

 <ComponentPreview
  name="toggle-button-group-without-separator"
 />

-<RelatedComponents component="toggle-button-group" />
+### 分离模式

-## 样式
+使用 `isDetached` 让按钮之间留出间隔，而不是彼此连接。

-### 传入 Tailwind CSS 类
+<ComponentPreview
+  name="toggle-button-group-attached"
+/>

-```tsx
-import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
+### 选择模式

-function CustomToggleButtonGroup() {
-  return (
-    <ToggleButtonGroup className="bg-purple-100" selectionMode="single">
-      <ToggleButton id="a">Option A</ToggleButton>
-      <ToggleButton id="b">
-        <ToggleButtonGroup.Separator />
-        Option B
-      </ToggleButton>
-    </ToggleButtonGroup>
-  );
-}
-```
+使用 `selectionMode="single"` 实现互斥选择，或使用 `selectionMode="multiple"` 实现独立切换。

-### 自定义组件类
+<ComponentPreview
+  name="toggle-button-group-selection-mode"
+/>

-若要自定义 ToggleButtonGroup 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+### 受控组件
+
+<ComponentPreview
+  name="toggle-button-group-controlled"
+/>
+
+## 自定义样式
+
+### Tailwind CSS
+
+<ComponentPreview name="toggle-button-group-custom-styles" />
+
+### 全局 CSS
+
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -140,13 +123,15 @@ function CustomToggleButtonGroup() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 ToggleButtonGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button-group.css)）：

-#### 基础与布局类
+#### 基础与布局类 [!toc]

 - `.toggle-button-group` - 容器基础样式
 - `.toggle-button-group--horizontal` - 水平方向
@@ -154,13 +139,13 @@ ToggleButtonGroup 组件使用以下 CSS 类（[查看源码样式](https://gith
 - `.toggle-button-group--full-width` - 全宽修饰符
 - `.toggle-button-group__separator` - 按钮之间的分隔线元素

-#### 修饰符类
+#### 修饰符类 [!toc]

 - `.toggle-button-group--detached` - 分离模式（按钮间有间隔）

 ## API 参考

-### ToggleButtonGroup Props
+### ToggleButtonGroup

 继承自 [React Aria ToggleButtonGroup](https://react-aria.adobe.com/ToggleButtonGroup)。

@@ -178,13 +163,13 @@ ToggleButtonGroup 组件使用以下 CSS 类（[查看源码样式](https://gith
 | `isDisabled` | `boolean` | `false` | 是否禁用组内全部按钮 |
 | `className` | `string` | - | 额外的 CSS 类 |

-### ToggleButtonGroup.Separator Props
+### ToggleButtonGroup.Separator

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类 |

-### 说明
+## 说明

 - ToggleButtonGroup 使用 React Context 将 `size` 传递给所有子 ToggleButton 组件
 - 每个 ToggleButton 都必须有唯一 `id` prop，并与 `selectedKeys` / `defaultSelectedKeys` 中使用的 key 对应
@@ -192,3 +177,7 @@ ToggleButtonGroup 组件使用以下 CSS 类（[查看源码样式](https://gith
 - 组件会自动处理按钮之间的圆角
 - 在每个 ToggleButton（第一个除外）内添加 `<ToggleButtonGroup.Separator />`，可在按钮之间显示分隔线
 - 将 `disallowEmptySelection` 与 `selectionMode="single"` 一起使用，可确保始终有一个选项被选中
+
+## 相关组件
+
+<RelatedComponents component="toggle-button-group" />
@@ -9,18 +9,18 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { ToggleButton } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="toggle-button-basic"
 />

+## 示例
+
 ### 变体

 <ComponentPreview
@@ -39,41 +39,27 @@ import { ToggleButton } from '@heroui/react';
  name="toggle-button-sizes"
 />

-
-### 受控
-
-<ComponentPreview
-  name="toggle-button-controlled"
-/>
-
 ### 禁用

 <ComponentPreview
  name="toggle-button-disabled"
 />

-<RelatedComponents component="togglebutton" />
+### 受控组件

-## 样式
+<ComponentPreview
+  name="toggle-button-controlled"
+/>

-### 传入 Tailwind CSS 类
+## 自定义样式

-```tsx
-import { ToggleButton } from '@heroui/react';
+### Tailwind CSS

-function CustomToggleButton() {
-  return (
-    <ToggleButton className="bg-purple-500 text-white">
-      Toggle
-    </ToggleButton>
-  );
-}
-```
+<ComponentPreview name="toggle-button-custom-styles" />

-### 自定义组件类
+### 全局 CSS

-若要自定义 ToggleButton 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -87,25 +73,27 @@ function CustomToggleButton() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 ToggleButton 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button.css)）：

-#### 基础与尺寸类
+#### 基础与尺寸类 [!toc]

 - `.toggle-button` - 切换按钮基础样式
 - `.toggle-button--sm` - 小尺寸变体
 - `.toggle-button--md` - 中尺寸变体（默认）
 - `.toggle-button--lg` - 大尺寸变体

-#### 变体类
+#### 变体类 [!toc]

 - `.toggle-button--default` - 默认变体（填充背景）
 - `.toggle-button--ghost` - 幽灵变体（透明背景）

-#### 修饰符类
+#### 修饰符类 [!toc]

 - `.toggle-button--icon-only` - 仅图标切换按钮
 - `.toggle-button--icon-only.toggle-button--sm` - 小尺寸仅图标
@@ -123,8 +111,7 @@ ToggleButton 组件使用以下 CSS 类（[查看源码样式](https://github.co

 ## API 参考

-### ToggleButton Props
-
+### ToggleButton
 继承自 [React Aria ToggleButton](https://react-spectrum.adobe.com/react-aria/ToggleButton.html)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -151,3 +138,7 @@ ToggleButton 组件使用以下 CSS 类（[查看源码样式](https://github.co
 | `isFocused` | `boolean` | 按钮是否处于聚焦状态 |
 | `isFocusVisible` | `boolean` | 按钮是否应显示焦点指示 |
 | `isDisabled` | `boolean` | 按钮是否被禁用 |
+
+## 相关组件
+
+<RelatedComponents component="togglebutton" />
@@ -1,6 +1,6 @@
 ---
 title: Dropdown 下拉菜单
-description: 下拉菜单展示一组可供用户选择的操作或选项。
+description: 展示用户可选择的操作或选项列表
 links:
  rac: Menu
  source: dropdown/dropdown.tsx
@@ -8,21 +8,17 @@ links:
  storybook: Components/Collections/Dropdown
 ---

-## 引入
+## 用法

 ```tsx
 import { Dropdown } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="dropdown-default"
 />

-### 组件结构
-
-引入 Dropdown 组件并通过点语法访问所有子部分。
+## 组件结构

 ```tsx
 import { Dropdown, Button, Label, Description, Header, Kbd, Separator } from '@heroui/react';
@@ -62,35 +58,7 @@ export default () => (
 )
 ```

-### 带单选
-
-<ComponentPreview
-  name="dropdown-with-single-selection"
-/>
-
-### 单选且自定义指示器
-
-<ComponentPreview
-  name="dropdown-single-with-custom-indicator"
-/>
-
-### 带多选
-
-<ComponentPreview
-  name="dropdown-with-multiple-selection"
-/>
-
-### 带分组级选择
-
-<ComponentPreview
-  name="dropdown-with-section-level-selection"
-/>
-
-### 带键盘快捷键
-
-<ComponentPreview
-  name="dropdown-with-keyboard-shortcuts"
-/>
+## 示例

 ### 带图标

@@ -98,43 +66,31 @@ export default () => (
  name="dropdown-with-icons"
 />

-### 长按触发
-
-<ComponentPreview
-  name="dropdown-long-press-trigger"
-/>
-
 ### 带描述

 <ComponentPreview
  name="dropdown-with-descriptions"
 />

-### 带分组
-
-<ComponentPreview
-  name="dropdown-with-sections"
-/>
-
-### 带禁用项
+### 含禁用项

 <ComponentPreview
  name="dropdown-with-disabled-items"
 />

-### 带子菜单
+### 分组选项

 <ComponentPreview
-  name="dropdown-with-submenus"
+  name="dropdown-with-sections"
 />

-### 带自定义子菜单指示器
+### 多选

 <ComponentPreview
-  name="dropdown-with-custom-submenu-indicator"
+  name="dropdown-with-multiple-selection"
 />

-### 受控
+### 受控组件

 <ComponentPreview
  name="dropdown-controlled"
@@ -146,43 +102,64 @@ export default () => (
  name="dropdown-controlled-open-state"
 />

+### 单选
+
+<ComponentPreview
+  name="dropdown-with-single-selection"
+/>
+
+### 单选自定义指示器
+
+<ComponentPreview
+  name="dropdown-single-with-custom-indicator"
+/>
+
+### 分组级选择
+
+<ComponentPreview
+  name="dropdown-with-section-level-selection"
+/>
+
+### 带快捷键
+
+<ComponentPreview
+  name="dropdown-with-keyboard-shortcuts"
+/>
+
+### 含子菜单
+
+<ComponentPreview
+  name="dropdown-with-submenus"
+/>
+
+### 自定义子菜单指示器
+
+<ComponentPreview
+  name="dropdown-with-custom-submenu-indicator"
+/>
+
 ### 自定义触发器

 <ComponentPreview
  name="dropdown-custom-trigger"
 />

-<RelatedComponents component="dropdown" />
- 
-## 样式
+### 长按触发

-### 传入 Tailwind CSS 类
+<ComponentPreview
+  name="dropdown-long-press-trigger"
+/>

-```tsx
-import { Dropdown, Button } from '@heroui/react';
+## 自定义样式

-function CustomDropdown() {
-  return (
-    <Dropdown>
-      <Dropdown.Trigger className="rounded-lg border p-2 bg-surface">
-        <Button>Actions</Button>
-      </Dropdown.Trigger>
-      <Dropdown.Popover className="min-w-[200px]">
-        <Dropdown.Menu>
-          <Dropdown.Item id="item-1" textValue="Item 1" className="hover:bg-surface-secondary">
-            Item 1
-          </Dropdown.Item>
-        </Dropdown.Menu>
-      </Dropdown.Popover>
-    </Dropdown>
-  );
-}
-```
+### Tailwind CSS

-### 自定义组件类
+<ComponentPreview name="dropdown-custom-styles" />

-若要自定义 Dropdown 组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+### 全局 CSS
+
+可使用 `@layer components` 指令自定义 Dropdown 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -204,19 +181,21 @@ function CustomDropdown() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体和状态可复用且易于自定义。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Dropdown 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/dropdown.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.dropdown` - Dropdown 根容器
- `.dropdown__trigger` - 用于触发 Dropdown 的按钮或元素
+- `.dropdown__trigger` - 触发 Dropdown 的按钮或元素
 - `.dropdown__popover` - Popover 容器
 - `.dropdown__menu` - Popover 内的菜单容器

-#### 状态类
+#### 状态类 [!toc]
 - `.dropdown__trigger[data-focus-visible="true"]` - 触发器聚焦状态
 - `.dropdown__trigger[data-disabled="true"]` - 触发器禁用状态
 - `.dropdown__trigger[data-pressed="true"]` - 触发器按下状态
@@ -229,11 +208,11 @@ Dropdown 组件使用以下 CSS 类（[查看源码样式](https://github.com/he

 Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类名也可用于自定义：

-#### Menu 类
+#### 菜单类 [!toc]
 - `.menu` - 菜单容器（[menu.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu.css)）
  - `[data-slot="separator"]` - 菜单内的分隔线元素

-#### MenuItem 类
+#### 菜单项类 [!toc]
 - `.menu-item` - 菜单项容器（[menu-item.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-item.css)）
 - `.menu-item__indicator` - 选中指示器（对勾或圆点）
  - `[data-slot="menu-item-indicator--checkmark"]` - 对勾指示器 SVG
@@ -242,7 +221,7 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类
 - `.menu-item--default` - 默认样式变体
 - `.menu-item--danger` - 危险样式变体

-#### MenuItem 状态类
+#### 菜单项状态类 [!toc]
 - `.menu-item[data-focus-visible="true"]` - 聚焦状态（键盘焦点）
 - `.menu-item[data-focus="true"]` - 聚焦状态
 - `.menu-item[data-pressed]` - 按下状态
@@ -255,22 +234,22 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类
 - `.menu-item[aria-checked="true"]` - 已勾选（ARIA）
 - `.menu-item[aria-selected="true"]` - 已选中（ARIA）

-#### MenuSection 类
+#### 菜单分区类 [!toc]
 - `.menu-section` - 菜单分区容器（[menu-section.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-section.css)）

 ### 交互状态

-该组件同时支持 CSS 伪类和 data 属性，便于灵活组合：
+组件同时支持 CSS 伪类与 data 属性：

- **悬停**：触发器与菜单项上 `:hover` 或 `[data-hovered="true"]`
- **聚焦**：触发器与菜单项上 `:focus-visible` 或 `[data-focus-visible="true"]`
- **禁用**：触发器与菜单项上 `:disabled` 或 `[data-disabled="true"]`
- **按下**：触发器与菜单项上 `:active` 或 `[data-pressed="true"]`
- **选中**：菜单项上 `[data-selected="true"]` 或 `[aria-selected="true"]`
+- **Hover**：触发器与菜单项上 `:hover` 或 `[data-hovered="true"]`
+- **Focus**：触发器与菜单项上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **Disabled**：触发器与菜单项上 `:disabled` 或 `[data-disabled="true"]`
+- **Pressed**：触发器与菜单项上 `:active` 或 `[data-pressed="true"]`
+- **Selected**：菜单项上 `[data-selected="true"]` 或 `[aria-selected="true"]`

 ## API 参考

-### Dropdown Props
+### Dropdown

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
@@ -281,7 +260,7 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类
 | `className` | `string` | - | 额外的 Tailwind CSS 类。 |
 | `children` | `ReactNode` | - | Dropdown 内容。 |

-### Dropdown.Trigger Props
+### Dropdown.Trigger

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
@@ -290,7 +269,7 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类

 使用 Button 作为触发器时，同样支持所有 [Button](https://react-spectrum.adobe.com/react-aria/Button.html) props。

-### Dropdown.Popover Props
+### Dropdown.Popover

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
@@ -300,7 +279,7 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类

 同样支持所有 [Popover](https://react-spectrum.adobe.com/react-aria/Popover.html) props。

-### Dropdown.Menu Props
+### Dropdown.Menu

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
@@ -315,7 +294,7 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类

 同样支持所有 [Menu](https://react-spectrum.adobe.com/react-aria/Menu.html#menu) props。

-### Dropdown.Section Props
+### Dropdown.Section

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
@@ -329,7 +308,7 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类

 同样支持所有 [MenuSection](https://react-spectrum.adobe.com/react-aria/Menu.html#menusection) props。

-### Dropdown.Item Props
+### Dropdown.Item

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
@@ -341,7 +320,7 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类

 同样支持所有 [MenuItem](https://react-spectrum.adobe.com/react-aria/Menu.html#menuitem) props。

-### Dropdown.ItemIndicator Props
+### Dropdown.ItemIndicator

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
@@ -356,14 +335,14 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类
 | `isSelected` | `boolean` | 该项是否选中。 |
 | `isIndeterminate` | `boolean` | 该项是否处于不确定状态。 |

-### Dropdown.SubmenuIndicator Props
+### Dropdown.SubmenuIndicator

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 Tailwind CSS 类。 |
 | `children` | `ReactNode` | - | 自定义指示器内容。 |

-### Dropdown.SubmenuTrigger Props
+### Dropdown.SubmenuTrigger

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
@@ -372,7 +351,7 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类

 同样支持所有 [SubmenuTrigger](https://react-spectrum.adobe.com/react-aria/Menu.html#submenutrigger) props。

-### RenderProps
+### Render Props

 在 Dropdown.Item 中使用渲染函数时，会传入以下值：

@@ -385,7 +364,7 @@ Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类

 ## 示例

-### 基础用法
+### 基本用法

 ```tsx
 import { Dropdown, Button, Label } from '@heroui/react';
@@ -410,7 +389,7 @@ import { Dropdown, Button, Label } from '@heroui/react';
 </Dropdown>
 ```

-### 带分组
+### 代码示例：分组选项

 ```tsx
 import { Dropdown, Button, Label, Header, Separator } from '@heroui/react';
@@ -479,7 +458,7 @@ function ControlledDropdown() {
 }
 ```

-### 带子菜单
+### 代码示例：含子菜单

 ```tsx
 import { Dropdown, Button, Label } from '@heroui/react';
@@ -527,3 +506,6 @@ Dropdown 组件实现 ARIA 菜单模式，并提供：

 更多信息见 [React Aria Menu 文档](https://react-spectrum.adobe.com/react-aria/Menu.html#menu)。

+## 相关组件
+
+<RelatedComponents component="dropdown" />
@@ -8,21 +8,17 @@ links:
  storybook: Components/Collections/ListBox
 ---

-## 引入
+## 用法

 ```tsx
 import { ListBox } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="list-box-default"
 />

-### 组件结构
-
-引入 ListBox 组件并通过点语法访问所有子部分。
+## 组件结构

 ```tsx
 import { ListBox, Label, Description, Header } from '@heroui/react';
@@ -44,7 +40,15 @@ export default () => (
 )
 ```

-### 带分组
+## 示例
+
+### 含禁用项
+
+<ComponentPreview
+  name="list-box-with-disabled-items"
+/>
+
+### 分组选项

 <ComponentPreview
  name="list-box-with-sections"
@@ -56,10 +60,18 @@ export default () => (
  name="list-box-multi-select"
 />

-### 带禁用项
+### 受控组件

 <ComponentPreview
-  name="list-box-with-disabled-items"
+  name="list-box-controlled"
+/>
+
+### 虚拟滚动
+
+ListBox 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见行，从而高效展示大数据集。
+
+<ComponentPreview 
+  name="list-box-virtualization"
 />

 ### 自定义勾选图标
@@ -68,50 +80,21 @@ export default () => (
  name="list-box-custom-check-icon"
 />

-### 受控
+### 渲染函数

 <ComponentPreview
-  name="list-box-controlled"
+  name="list-box-render-function"
 />

-### 自定义渲染函数
+## 自定义样式

-<ComponentPreview
-  name="list-box-custom-render-function"
-/>
+### Tailwind CSS

-### 虚拟化
+<ComponentPreview name="list-box-custom-styles" />

-ListBox 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见的行，从而高效展示大数据集。
+### 全局 CSS

-<ComponentPreview 
-  name="list-box-virtualization"
-/>
-
-<RelatedComponents component="list-box" />
-
-## 样式
-
-### 传入 Tailwind CSS 类
-
-```tsx
-import { ListBox } from '@heroui/react';
-
-function CustomListBox() {
-  return (
-    <ListBox className="border rounded-lg p-2 bg-surface">
-      <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
-        Item 1
-      </ListBox.Item>
-    </ListBox>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 ListBox 组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -133,25 +116,27 @@ function CustomListBox() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 ListBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/list-box.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.list-box` - ListBox 根容器
 - `.list-box-item` - 单个列表项
 - `.list-box-item__indicator` - 选中指示图标
 - `.list-box-section` - 用于分组的区块容器

-#### 变体类
+#### 变体类 [!toc]
 - `.list-box--default` - 默认变体样式
 - `.list-box--danger` - 危险变体样式
 - `.list-box-item--default` - 列表项默认变体
 - `.list-box-item--danger` - 列表项危险变体

-#### 状态类
+#### 状态类 [!toc]
 - `.list-box-item[data-selected="true"]` - 选中状态
 - `.list-box-item[data-focus-visible="true"]` - 聚焦状态
 - `.list-box-item[data-disabled="true"]` - 禁用状态
@@ -168,8 +153,7 @@ ListBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/her

 ## API 参考

-### ListBox Props
-
+### ListBox
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `aria-label` | `string` | - | ListBox 的无障碍标签。 |
@@ -185,8 +169,7 @@ ListBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/her
 | `children` | `ReactNode` | - | ListBox 项与分组。 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ListBoxRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### ListBox.Item Props
-
+### ListBox.Item
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `id` | `Key` | - | 列表项唯一标识。 |
@@ -197,15 +180,13 @@ ListBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/her
 | `children` | `ReactNode \| RenderFunction` | - | 列表项内容或渲染函数。 |
 | `render` | `(props: DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> \| React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], renderProps: ListBoxItemRenderProps) => ReactElement` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### ListBox.ItemIndicator Props
-
+### ListBox.ItemIndicator
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 Tailwind CSS 类。 |
 | `children` | `ReactNode \| RenderFunction` | - | 自定义指示器内容或渲染函数。 |

-### ListBox.Section Props
-
+### ListBox.Section
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 Tailwind CSS 类。 |
@@ -237,7 +218,7 @@ ListBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/her

 ## 示例

-### 基础用法
+### 基本用法

 ```tsx
 import { ListBox, Label, Description } from '@heroui/react';
@@ -254,7 +235,7 @@ import { ListBox, Label, Description } from '@heroui/react';
 </ListBox>
 ```

-### 带分组
+### 分组选项

 ```tsx
 import { ListBox, Header, Separator } from '@heroui/react';
@@ -326,3 +307,7 @@ ListBox 组件实现 ARIA listbox 模式，并提供：
 - 首字母导航（typeahead）搜索能力

 更多信息见 [React Aria ListBox 文档](https://react-spectrum.adobe.com/react-aria/ListBox.html)。
+
+## 相关组件
+
+<RelatedComponents component="list-box" />
@@ -8,19 +8,17 @@ links:
  storybook: Components/Collections/TagGroup
 ---

-## 引入
+## 用法

 ```tsx
 import { TagGroup } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="tag-group-basic"
 />

-### 组件结构
+## 组件结构

 ```tsx
 import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';
@@ -39,6 +37,8 @@ export default () => (
 )
 ```

+## 示例
+
 ### 尺寸

 <ComponentPreview
@@ -63,7 +63,7 @@ export default () => (
  name="tag-group-selection-modes"
 />

-### 受控
+### 受控组件

 <ComponentPreview
  name="tag-group-controlled"
@@ -75,6 +75,12 @@ export default () => (
  name="tag-group-with-error-message"
 />

+### 带列表数据
+
+<ComponentPreview
+  name="tag-group-with-list-data"
+/>
+
 ### 带前缀

 <ComponentPreview
@@ -87,45 +93,21 @@ export default () => (
  name="tag-group-with-remove-button"
 />

-### 带列表数据
+### 渲染函数

 <ComponentPreview
-  name="tag-group-with-list-data"
+  name="tag-group-render-function"
 />

-### 自定义渲染函数
+## 自定义样式

-<ComponentPreview
-  name="tag-group-custom-render-function"
-/>
+### Tailwind CSS

-<RelatedComponents component="taggroup" />
+<ComponentPreview name="tag-group-custom-styles" />

-## 样式
+### 全局 CSS

-### 传入 Tailwind CSS 类
-
-```tsx
-import { TagGroup, Tag, Label } from '@heroui/react';
-
-function CustomTagGroup() {
-  return (
-    <TagGroup className="w-full">
-      <Label>Categories</Label>
-      <TagGroup.List className="gap-2">
-        <Tag className="rounded-lg px-4 py-2 font-bold">
-          Custom Styled
-        </Tag>
-      </TagGroup.List>
-    </TagGroup>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 TagGroup 组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -147,32 +129,34 @@ function CustomTagGroup() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 TagGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag-group.css) 与 [tag.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.tag-group` - TagGroup 根容器
 - `.tag-group__list` - 标签列表容器
 - `.tag` - 标签基础样式
 - `.tag__remove-button` - 移除按钮触发器

-#### 插槽类
+#### 插槽类 [!toc]
 - `.tag-group [slot="description"]` - Description 插槽样式
 - `.tag-group [slot="errorMessage"]` - ErrorMessage 插槽样式

-#### 尺寸类
+#### 尺寸类 [!toc]
 - `.tag--sm` - 小尺寸标签
 - `.tag--md` - 中尺寸标签（默认）
 - `.tag--lg` - 大尺寸标签

-#### 变体类
+#### 变体类 [!toc]
 - `.tag--default` - 默认变体
 - `.tag--surface` - 带 Surface 背景的变体

-#### 状态类
+#### 状态类 [!toc]
 - `.tag[data-selected="true"]` - 选中状态
 - `.tag[data-disabled="true"]` - 禁用状态
 - `.tag[data-hovered="true"]` - 悬停状态
@@ -191,8 +175,7 @@ TagGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/he

 ## API 参考

-### TagGroup Props
-
+### TagGroup
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | 允许的选择类型。 |
@@ -208,8 +191,7 @@ TagGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/he
 | `children` | `ReactNode \| RenderFunction` | - | TagGroup 内容或渲染函数。 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### TagGroup.List Props
-
+### TagGroup.List
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `items` | `Iterable<T>` | - | 标签列表要展示的数据项。 |
@@ -218,8 +200,7 @@ TagGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/he
 | `children` | `ReactNode \| RenderFunction` | - | 标签列表内容或渲染函数。 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagListRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Tag Props
-
+### Tag
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `id` | `Key` | - | 标签唯一标识。 |
@@ -231,8 +212,7 @@ TagGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/he

 **提示：** `size`、`variant` 由父级 `TagGroup` 继承，无法在单个 `Tag` 上直接设置。

-### Tag.RemoveButton Props
-
+### Tag.RemoveButton
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 Tailwind CSS 类。 |
@@ -296,3 +276,7 @@ TagGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/he
 | `isPressed` | `boolean` | 标签是否按下。 |
 | `isFocused` | `boolean` | 标签是否聚焦。 |
 | `isFocusVisible` | `boolean` | 标签是否为可见键盘焦点。 |
+
+## 相关组件
+
+<RelatedComponents component="taggroup" />
@@ -1,6 +1,6 @@
 ---
 title: ColorArea 颜色区域
-description: 二维颜色选择器，用户可在渐变区域内选取颜色。
+description: 二维颜色选择器，允许用户从渐变区域中选择颜色
 links:
  rac: ColorArea
  source: color-area/color-area.tsx
@@ -9,19 +9,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { ColorArea } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="color-area-basic"
 />

-### 组件结构
+## 组件结构

 ```tsx
 import { ColorArea } from '@heroui/react';
@@ -33,22 +31,17 @@ export default () => (
 );
 ```

-### 显示点阵
+## 示例
+
+### 带定位点

 <ComponentPreview
  name="color-area-with-dots"
 />

-### 受控
+### 色彩空间与通道

-<ComponentPreview
-  name="color-area-controlled"
-/>
-
-
-### 颜色空间与通道
-
-使用 `colorSpace` 设置颜色空间（RGB、HSL、HSB），并通过 `xChannel` / `yChannel` prop 自定义横纵轴展示的颜色通道。
+使用 `colorSpace` 设置颜色空间（RGB、HSL、HSB），使用 `xChannel`/`yChannel` 自定义各轴显示的颜色通道。

 <ComponentPreview
  name="color-area-space-and-channels"
@@ -60,34 +53,28 @@ export default () => (
  name="color-area-disabled"
 />

-### 自定义渲染函数
+### 受控组件

 <ComponentPreview
-  name="color-area-custom-render-function"
+  name="color-area-controlled"
 />

-<RelatedComponents component="color-area" />
+### 渲染函数

-## 样式
+<ComponentPreview
+  name="color-area-render-function"
+/>

-### 传入 Tailwind CSS 类
+## 自定义样式

-```tsx
-import { ColorArea } from '@heroui/react';
+### Tailwind CSS

-function CustomColorArea() {
-  return (
-    <ColorArea className="max-w-72 rounded-3xl">
-      <ColorArea.Thumb />
-    </ColorArea>
-  );
-}
-```
+<ComponentPreview name="color-area-custom-styles" />

-### 自定义组件类
+### 全局 CSS

-若要自定义 ColorArea 组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 ColorArea 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -101,51 +88,57 @@ function CustomColorArea() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 ColorArea 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-area.css)）：

-#### 基础类
- `.color-area` - 基础样式，含渐变背景与内阴影
- `.color-area--show-dots` - 叠加点阵网格，便于精确取色
+#### 基础类 [!toc]
+- `.color-area` - 渐变背景与内阴影的基础样式
+- `.color-area--show-dots` - 添加点阵网格覆盖层以精确选色

-#### 元素类
- `.color-area__thumb` - 可拖动的 thumb 指示器
+#### 元素类 [!toc]
+- `.color-area__thumb` - 可拖拽的滑块指示器

 ### 交互状态

-该组件同时支持 CSS 伪类与 data 属性：
+组件同时支持 CSS 伪类与 data 属性：

- **禁用**：`[data-disabled="true"]`
- **聚焦**：`[data-focus-visible="true"]`
- **拖拽**：`[data-dragging="true"]`（仅 thumb）
+- **Disabled**：`[data-disabled="true"]`
+- **Focus**：`[data-focus-visible="true"]`
+- **Dragging**：`[data-dragging="true"]`（仅 thumb）

 ## API 参考

-### ColorArea Props
+### ColorArea

 继承自 [React Aria ColorArea](https://react-spectrum.adobe.com/react-aria/ColorArea.html)。

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `value` | `string \| Color` | - | 当前颜色值（受控）。 |
-| `defaultValue` | `string \| Color` | - | 默认颜色值（非受控）。 |
-| `onChange` | `(color: Color) => void` | - | 拖拽过程中颜色变化时调用的事件处理函数。 |
-| `onChangeEnd` | `(color: Color) => void` | - | 用户结束拖拽时调用的事件处理函数。 |
-| `xChannel` | `ColorChannel` | `"saturation"` | 水平轴对应的颜色通道。 |
-| `yChannel` | `ColorChannel` | `"brightness"` | 垂直轴对应的颜色通道。 |
-| `colorSpace` | `ColorSpace` | - | 通道所在的颜色空间。 |
-| `isDisabled` | `boolean` | `false` | 是否禁用 ColorArea。 |
-| `showDots` | `boolean` | `false` | 是否显示点阵网格叠加层。 |
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorAreaRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+| `value` | `string \| Color` | - | 当前颜色值（受控） |
+| `defaultValue` | `string \| Color` | - | 默认颜色值（非受控） |
+| `onChange` | `(color: Color) => void` | - | 拖拽过程中颜色变化时的回调 |
+| `onChangeEnd` | `(color: Color) => void` | - | 用户停止拖拽时的回调 |
+| `xChannel` | `ColorChannel` | `"saturation"` | 水平轴的颜色通道 |
+| `yChannel` | `ColorChannel` | `"brightness"` | 垂直轴的颜色通道 |
+| `colorSpace` | `ColorSpace` | - | 通道使用的颜色空间 |
+| `isDisabled` | `boolean` | `false` | 是否禁用 |
+| `showDots` | `boolean` | `false` | 是否显示点阵网格覆盖层 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorAreaRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### ColorArea.Thumb Props
+### ColorArea.Thumb

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | 行内样式或渲染函数。 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorThumbRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+| `className` | `string` | - | 附加 CSS 类 |
+| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | 内联样式或 render props 函数 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorThumbRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |
+
+## 相关组件
+
+<RelatedComponents component="color-area" />
@@ -1,6 +1,6 @@
 ---
 title: ColorField 颜色输入框
-description: 基于 React Aria ColorField 的颜色输入字段，包含标签、说明与校验能力。
+description: 基于 React Aria ColorField 的颜色输入字段，支持标签、描述与验证
 links:
  rac: ColorField
  source: color-field/color-field.tsx
@@ -8,17 +8,15 @@ links:
  storybook: Components/Colors/ColorField
 ---

-## 引入
+## 用法

 ```tsx
 import { ColorField, parseColor } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="color-field-basic" />

-### 组件结构
+## 组件结构

 ```tsx
 import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
@@ -38,9 +36,26 @@ export default () => (
 )
 ```

-> **ColorField** 将标签、颜色输入、说明与错误信息组合为单个可访问组件。
+> **ColorField** 将标签、颜色输入、描述与错误合并为单个无障碍组件。

-### 带说明
+## 示例
+
+### 变体
+
+ColorField.Group 组件支持两种视觉变体：
+
+- **`primary`**（默认）- 标准样式带阴影，适用于大多数场景
+- **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内
+
+<ComponentPreview name="color-field-variants" />
+
+### 表面样式
+
+在 [Surface](/docs/components/surface) 组件内使用时，在 ColorField.Group 上使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。
+
+<ComponentPreview name="color-field-on-surface" />
+
+### 带描述

 <ComponentPreview name="color-field-with-description" />

@@ -48,91 +63,53 @@ export default () => (

 <ComponentPreview name="color-field-required" />

-### 校验
-
-将 `isInvalid` 与 `FieldError` 配合使用，以展示校验信息。
-
-<ComponentPreview name="color-field-invalid" />
-
-### 通道编辑
-
-通过设置 `colorSpace` 与 `channel`，ColorField 支持编辑单个颜色通道（hue、saturation、lightness、红、绿、蓝、alpha）。
-
-<ComponentPreview name="color-field-channel-editing" />
-
-### 受控
-
-控制数值以与其他组件或状态管理同步。
-
-<ComponentPreview name="color-field-controlled" />
-
-### 禁用状态
+### 禁用

 <ComponentPreview name="color-field-disabled" />

-### 全宽
+### 宽度充满

 <ComponentPreview name="color-field-full-width" />

-### 变体
+### 表单校验

-ColorField.Group 支持两种视觉变体：
+将 `isInvalid` 与 `FieldError` 一起使用以显示验证消息。

- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
- **`secondary`** — 低强调、无阴影的变体，适合用在 Surface 组件内
+<ComponentPreview name="color-field-invalid" />

-<ComponentPreview name="color-field-variants" />
+### 分量编辑

-### On Surface
+ColorField 支持通过设置 `colorSpace` 与 `channel` 属性编辑单个颜色通道（hue、saturation、lightness、red、green、blue、alpha）。

-在 [Surface](/docs/components/surface) 内使用时，请在 ColorField.Group 上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+<ComponentPreview name="color-field-channel-editing" />

-<ComponentPreview name="color-field-on-surface" />
+### 受控组件
+
+控制值以与其他组件或状态管理同步。
+
+<ComponentPreview name="color-field-controlled" />

 ### 表单示例

-包含校验与提交处理的完整表单示例。
+包含验证与提交处理的完整表单示例。

 <ComponentPreview name="color-field-form-example" />

-### 自定义渲染函数
+### 渲染函数

 <ComponentPreview
-  name="color-field-custom-render-function"
+  name="color-field-render-function"
 />

-<RelatedComponents component="colorfield" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="color-field-custom-styles" />

-```tsx
-import {ColorField, Label, ColorSwatch, Description} from '@heroui/react';
+### 全局 CSS

-function CustomColorField() {
-  return (
-    <ColorField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
-      <Label className="text-sm font-semibold text-default-700">
-        Brand Color
-      </Label>
-      <ColorField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
-        <ColorField.Prefix>
-          <ColorSwatch color="#3B82F6" />
-        </ColorField.Prefix>
-        <ColorField.Input />
-      </ColorField.Group>
-      <Description className="text-xs text-default-500">
-        Select your brand's primary color.
-      </Description>
-    </ColorField>
-  );
-}
-```
-
-### 自定义组件类
-
-ColorField 的默认样式非常克制。你可以覆盖 `.color-field` 类来自定义容器样式。
+ColorField 默认样式较少。覆盖 `.color-field` 类以自定义容器样式。

 ```css
@layer components {
@@ -157,99 +134,103 @@ ColorField 的默认样式非常克制。你可以覆盖 `.color-field` 类来
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

- `.color-field` – 根容器，样式非常克制（`flex flex-col gap-1`）
+- `.color-field` – 最小样式的根容器（`flex flex-col gap-1`）

-> **说明：** 子组件（[Label](/docs/components/label)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参见对应文档。ColorField.Group 的样式见下文 API 参考中的 **ColorField.Group Styling** 小节。
+> **Note:** 子组件（[Label](/docs/components/label)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）有各自的 CSS 类与样式。请参阅各自文档了解自定义选项。ColorField.Group 样式见下方 API 参考。

 ### 交互状态

-ColorField 会根据状态自动管理以下 data 属性：
+ColorField 根据状态自动管理以下 data 属性：

- **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` – 无效时会自动隐藏 description 插槽
- **Required**：`[data-required="true"]` – 当 `isRequired` 为 true 时应用
- **Disabled**：`[data-disabled="true"]` – 当 `isDisabled` 为 true 时应用
- **Focus Within**：`[data-focus-within="true"]` – 当任意子输入聚焦时应用
+- **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` - 无效时自动隐藏 description slot
+- **Required**：`[data-required="true"]` - `isRequired` 为 true 时应用
+- **Disabled**：`[data-disabled="true"]` - `isDisabled` 为 true 时应用
+- **Focus Within**：`[data-focus-within="true"]` - 任一子 input 聚焦时应用

 ## API 参考

-### ColorField Props
+### ColorField

-ColorField 继承 React Aria [ColorField](https://react-aria.adobe.com/ColorField.md) 组件的全部 props。
+ColorField 继承 React Aria [ColorField](https://react-aria.adobe.com/ColorField.md) 组件的所有属性。

 #### Base Props

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `children` | `React.ReactNode \| (values: ColorFieldRenderProps) => React.ReactNode` | - | 子组件（Label、ColorField.Group 等）或渲染函数。 |
-| `className` | `string \| (values: ColorFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 |
-| `style` | `React.CSSProperties \| (values: ColorFieldRenderProps) => React.CSSProperties` | - | 行内样式，支持渲染 prop。 |
-| `fullWidth` | `boolean` | `false` | 颜色字段是否占满容器宽度 |
-| `id` | `string` | - | 元素的唯一标识符。 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+| `children` | `React.ReactNode \| (values: ColorFieldRenderProps) => React.ReactNode` | - | 子组件（Label、ColorField.Group 等）或 render 函数 |
+| `className` | `string \| (values: ColorFieldRenderProps) => string` | - | CSS 类，支持 render props |
+| `style` | `React.CSSProperties \| (values: ColorFieldRenderProps) => React.CSSProperties` | - | 内联样式，支持 render props |
+| `fullWidth` | `boolean` | `false` | 是否占满容器宽度 |
+| `id` | `string` | - | 元素唯一标识符 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorFieldRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

 #### Value Props

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `value` | `Color \| null` | - | 当前值（受控）。 |
-| `defaultValue` | `Color \| null` | - | 默认值（非受控）。 |
-| `onChange` | `(color: Color \| null) => void` | - | 值变化时触发的事件处理函数。 |
+| `value` | `Color \| null` | - | 当前值（受控） |
+| `defaultValue` | `Color \| null` | - | 默认值（非受控） |
+| `onChange` | `(color: Color \| null) => void` | - | 值变化时的回调 |

 #### Channel Props

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `colorSpace` | `ColorSpace` | - | 当提供 `channel` 时，颜色字段所处的色彩空间。 |
-| `channel` | `ColorChannel` | - | 要编辑的颜色通道。未提供时编辑十六进制值。 |
+| `colorSpace` | `ColorSpace` | - | 提供 `channel` 时颜色字段操作的颜色空间 |
+| `channel` | `ColorChannel` | - | 要编辑的颜色通道。未提供时编辑 hex 值 |

 #### Validation Props

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `isRequired` | `boolean` | `false` | 提交表单前是否要求用户输入。 |
-| `isInvalid` | `boolean` | - | 当前值是否无效。 |
-| `validate` | `(value: Color) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 |
-| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验或 ARIA 属性。 |
+| `isRequired` | `boolean` | `false` | 表单提交前是否必须输入 |
+| `isInvalid` | `boolean` | - | 值是否无效 |
+| `validate` | `(value: Color) => ValidationError \| true \| null \| undefined` | - | 自定义验证函数 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单验证还是 ARIA 属性 |

 #### State Props

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `isDisabled` | `boolean` | - | 是否禁用输入。 |
-| `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 |
-| `isWheelDisabled` | `boolean` | - | 是否禁用滚轮改变数值。 |
+| `isDisabled` | `boolean` | - | 是否禁用 |
+| `isReadOnly` | `boolean` | - | 是否可选中但不可更改 |
+| `isWheelDisabled` | `boolean` | - | 是否禁用滚轮更改值 |

 #### Form Props

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `name` | `string` | - | input 元素的名称，用于 HTML 表单提交。 |
-| `autoFocus` | `boolean` | - | 元素渲染后是否应获得焦点。 |
+| `name` | `string` | - | HTML 表单提交时 input 元素的名称 |
+| `autoFocus` | `boolean` | - | 渲染时是否自动聚焦 |

 #### Accessibility Props

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `aria-label` | `string` | - | 没有可见标签时的无障碍标签。 |
-| `aria-labelledby` | `string` | - | 用于标注该字段的元素 ID。 |
-| `aria-describedby` | `string` | - | 用于描述该字段的元素 ID。 |
-| `aria-details` | `string` | - | 包含更多详情的元素 ID。 |
+| `aria-label` | `string` | - | 无可见标签时的无障碍标签 |
+| `aria-labelledby` | `string` | - | 标注此字段的元素 ID |
+| `aria-describedby` | `string` | - | 描述此字段的元素 ID |
+| `aria-details` | `string` | - | 包含附加详情的元素 ID |

 ### Composition Components

-ColorField 需要与以下独立组件组合使用，请分别导入并直接使用：
+ColorField 与以下需单独导入并直接使用的组件配合：

- **Label** – 字段标签组件（`@heroui/react`）
- **ColorField.Group** – 颜色输入分组组件（见下文）
- **ColorField.Input** – ColorField.Group 内的输入元素
- **ColorField.Prefix** / **ColorField.Suffix** – 输入组的前缀与后缀插槽
- **ColorSwatch** – 颜色预览组件（`@heroui/react`）
- **Description** – 辅助说明文本组件（`@heroui/react`）
- **FieldError** – 校验错误信息组件（`@heroui/react`）
+- **Label** - 来自 `@heroui/react` 的字段标签组件
+- **ColorField.Group** - 颜色输入组组件（见下方文档）
+- **ColorField.Input** - ColorField.Group 内的 input 元素
+- **ColorField.Prefix** / **ColorField.Suffix** - 输入组的前缀与后缀 slot
+- **ColorSwatch** - 来自 `@heroui/react` 的颜色预览组件
+- **Description** - 来自 `@heroui/react` 的帮助文本组件
+- **FieldError** - 来自 `@heroui/react` 的验证错误消息

-这些组件各自拥有 props API。请直接在 ColorField 内组合使用：
+每个组件有各自的 props API。在 ColorField 内直接使用它们进行组合：

 ```tsx
 import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
@@ -274,7 +255,7 @@ import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} fro

 ### Color Types

-ColorField 使用来自 React Aria Components 的 `Color` 对象：
+ColorField 使用 React Aria Components 的 `Color` 对象：

 ```tsx
 import {parseColor} from '@heroui/react';
@@ -294,63 +275,63 @@ const rgb = color.toString('rgb'); // "rgb(59, 130, 246)"
 </ColorField>
 ```

-### ColorFieldRenderProps
+### Render Props

-在 `className`、`style` 或 `children` 上使用渲染 prop 时，可使用以下值：
+对 `className`、`style` 或 `children` 使用 render props 时，可使用以下值：

 | Prop | 类型 | 描述 |
 |------|------|------|
-| `isDisabled` | `boolean` | 字段是否禁用。 |
-| `isInvalid` | `boolean` | 字段当前是否无效。 |
-| `isReadOnly` | `boolean` | 字段是否只读。 |
-| `isRequired` | `boolean` | 字段是否必填。 |
-| `isFocused` | `boolean` | 字段是否聚焦。 |
-| `isFocusWithin` | `boolean` | 是否有任意子元素聚焦。 |
-| `isFocusVisible` | `boolean` | 是否为可见焦点（键盘导航）。 |
+| `isDisabled` | `boolean` | 字段是否禁用 |
+| `isInvalid` | `boolean` | 字段是否当前无效 |
+| `isReadOnly` | `boolean` | 字段是否只读 |
+| `isRequired` | `boolean` | 字段是否必填 |
+| `isFocused` | `boolean` | 字段是否当前聚焦 |
+| `isFocusWithin` | `boolean` | 是否有子元素聚焦 |
+| `isFocusVisible` | `boolean` | 焦点是否可见（键盘导航） |

-### ColorField.Group Props
+### ColorField.Group

-ColorField.Group 接受 React Aria `Group` 组件的全部 props，以及：
+ColorField.Group 接受 React Aria `Group` 组件的所有属性，以及以下属性：

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `className` | `string` | - | 与组件样式合并的 Tailwind 类 |
 | `fullWidth` | `boolean` | `false` | 颜色输入组是否占满容器宽度 |
-| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, GroupRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, GroupRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### ColorField.Input Props
+### ColorField.Input

-ColorField.Input 接受 React Aria `Input` 组件的全部 props，以及：
+ColorField.Input 接受 React Aria `Input` 组件的所有属性，以及以下属性：

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
-| `placeholder` | `string` | - | 为空时显示的占位符文本。 |
+| `className` | `string` | - | 与组件样式合并的 Tailwind 类 |
+| `placeholder` | `string` | - | 为空时显示的占位文本 |

-### ColorField.Prefix Props
+### ColorField.Prefix

 ColorField.Prefix 接受标准 HTML `div` 属性：

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | 前缀插槽中要展示的内容。 |
+| `className` | `string` | - | 与组件样式合并的 Tailwind 类 |
+| `children` | `ReactNode` | - | 前缀 slot 中显示的内容 |

-### ColorField.Suffix Props
+### ColorField.Suffix

 ColorField.Suffix 接受标准 HTML `div` 属性：

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | 后缀插槽中要展示的内容。 |
+| `className` | `string` | - | 与组件样式合并的 Tailwind 类 |
+| `children` | `ReactNode` | - | 后缀 slot 中显示的内容 |

 ## ColorField.Group Styling

-### 自定义组件类
+### Customizing the component classes

-基础类会作用于每个实例。你可以在 `@layer components` 中一次性覆盖它们。
+基础类驱动每个实例。使用 `@layer components` 一次性覆盖。

 ```css
@layer components {
@@ -391,7 +372,7 @@ ColorField.Suffix 接受标准 HTML `div` 属性：
 ### ColorField.Group CSS Classes

 - `.color-input-group` – 根容器样式
- `.color-input-group__input` – 输入区域包裹样式
+- `.color-input-group__input` – Input 包装器样式
 - `.color-input-group__prefix` – 前缀元素样式
 - `.color-input-group__suffix` – 后缀元素样式

@@ -399,5 +380,9 @@ ColorField.Suffix 接受标准 HTML `div` 属性：

 - **Hover**：`:hover` 或 `[data-hovered="true"]`
 - **Focus Within**：`[data-focus-within="true"]` 或 `:focus-within`
- **Invalid**：`[data-invalid="true"]`（也会与 `aria-invalid` 同步）
+- **Invalid**：`[data-invalid="true"]`（与 `aria-invalid` 同步）
 - **Disabled**：`[data-disabled="true"]` 或 `[aria-disabled="true"]`
+
+## 相关组件
+
+<RelatedComponents component="colorfield" />
@@ -1,6 +1,6 @@
 ---
 title: ColorPicker 颜色选择器
-description: 可组合的 ColorPicker，在多个颜色组件之间同步颜色值。
+description: 可组合的颜色选择器，在多个颜色组件间同步颜色值
 links:
  rac: ColorPicker
  source: color-picker/color-picker.tsx
@@ -9,7 +9,7 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import {
@@ -22,15 +22,13 @@ import {
 } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="color-picker-basic"
 />

-### 组件结构
+## 组件结构

-ColorPicker 是一个可组合组件，会组合多个颜色相关子组件：
+ColorPicker 是组合多个颜色组件的可组合组件：

 ```tsx
 import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
@@ -55,13 +53,15 @@ export default () => (
 );
 ```

-### 受控
+## 示例
+
+### 受控组件

 <ComponentPreview
  name="color-picker-controlled"
 />

-### 带 swatch
+### 带色板

 <ComponentPreview
  name="color-picker-with-swatches"
@@ -69,7 +69,7 @@ export default () => (

 ### 带输入字段

-使用 `ColorField` 让用户编辑各个颜色通道的数值，并可配合 `Select` 切换色彩空间。
+使用 `ColorField` 允许用户编辑单个颜色通道值，配合 `Select` 切换颜色空间。

 <ComponentPreview
  name="color-picker-with-fields"
@@ -77,42 +77,22 @@ export default () => (

 ### 带滑块

-使用多个 `ColorSlider` 来调整颜色值的各个通道。
+使用多个 `ColorSlider` 组件调整颜色值的各通道。

 <ComponentPreview
  name="color-picker-with-sliders"
 />

-<RelatedComponents component="color-picker" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="color-picker-custom-styles" />

-```tsx
-import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
+### 全局 CSS

-function CustomColorPicker() {
-  return (
-    <ColorPicker defaultValue="#0485F7">
-      <ColorPicker.Trigger className="gap-4">
-        <ColorSwatch className="rounded-lg" />
-        <Label>Pick a color</Label>
-      </ColorPicker.Trigger>
-      <ColorPicker.Popover className="p-4 rounded-xl">
-        <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness">
-          <ColorArea.Thumb />
-        </ColorArea>
-      </ColorPicker.Popover>
-    </ColorPicker>
-  );
-}
-```
-
-### 自定义组件类
-
-要自定义 ColorPicker 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 ColorPicker 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -130,27 +110,29 @@ function CustomColorPicker() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-ColorPicker 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-picker.css)）：
+ColorPicker 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-picker.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.color-picker` - 基础容器
 - `.color-picker__trigger` - 触发按钮
- `.color-picker__popover` - Popover 容器
+- `.color-picker__popover` - 弹出层容器

 ### 交互状态

-组件同时支持 CSS 伪类与 data 属性，便于灵活定制：
+组件同时支持 CSS 伪类与 data 属性：

 - **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]`
 - **Disabled**：`:disabled` 或 `[data-disabled="true"]`

 ## API 参考

-### ColorPicker Props
+### ColorPicker

 继承自 [React Aria ColorPicker](https://react-spectrum.adobe.com/react-aria/ColorPicker.html)。

@@ -158,33 +140,33 @@ ColorPicker 使用以下 CSS 类（[查看源码样式](https://github.com/herou
 |------|------|--------|------|
 | `value` | `string \| Color` | - | 当前颜色值（受控） |
 | `defaultValue` | `string \| Color` | - | 默认颜色值（非受控） |
-| `onChange` | `(color: Color) => void` | - | 颜色变化时触发的事件处理函数 |
+| `onChange` | `(color: Color) => void` | - | 颜色变化时的回调 |
 | `children` | `React.ReactNode` | - | 颜色选择器内容（Trigger、Popover 等） |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |

-### ColorPicker.Trigger Props
+### ColorPicker.Trigger

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `children` | `React.ReactNode \| ((renderProps) => React.ReactNode)` | - | 触发器内容或渲染 prop |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `React.ReactNode \| ((renderProps) => React.ReactNode)` | - | 触发器内容或 render prop |
+| `className` | `string` | - | 附加 CSS 类 |

-### ColorPicker.Popover Props
+### ColorPicker.Popover

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `placement` | `Placement` | `"bottom left"` | Popover 的放置位置 |
-| `children` | `React.ReactNode` | - | Popover 内容 |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `placement` | `Placement` | `"bottom left"` | 弹出层位置 |
+| `children` | `React.ReactNode` | - | 弹出层内容 |
+| `className` | `string` | - | 附加 CSS 类 |

 ### Related Types

 #### Color

-表示颜色值。完整 API 见 [React Aria Color](https://react-spectrum.adobe.com/react-aria/ColorPicker.html#color)。
+表示颜色值。完整 API 请参阅 [React Aria Color](https://react-spectrum.adobe.com/react-aria/ColorPicker.html#color)。

-| Method | 描述 |
-|--------|------|
+| Method | Description |
+|--------|-------------|
 | `toString(format)` | 将颜色转换为指定格式的字符串（hex、rgb、hsl、hsb、css） |
 | `toFormat(format)` | 将颜色转换为指定格式并返回新的 Color 对象 |
 | `getChannelValue(channel)` | 返回指定通道的数值 |
@@ -199,3 +181,7 @@ import { parseColor } from 'react-aria-components';
 const color = parseColor('#ff0000');
 const hslColor = parseColor('hsl(0, 100%, 50%)');
 ```
+
+## 相关组件
+
+<RelatedComponents component="color-picker" />
@@ -1,6 +1,7 @@
 ---
 title: ColorSlider 颜色滑块
-description: ColorSlider 允许用户调整颜色值的单个通道。
+description: 颜色滑块允许用户调整颜色值的单个通道
+
 links:
  rac: ColorSlider
  source: color-slider/color-slider.tsx
@@ -9,21 +10,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { ColorSlider, Label } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="color-slider-basic"
 />

-### 组件结构
-
-导入 ColorSlider 组件后，可通过点号访问各个子部分。
+## 组件结构

 ```tsx
 import { ColorSlider, Label } from '@heroui/react';
@@ -38,80 +35,66 @@ export default () => (
  </ColorSlider>
 )
 ```
-### Vertical
+## 示例

-<ComponentPreview
-  name="color-slider-vertical"
-/>
-
-### Disabled
+### 禁用

 <ComponentPreview
  name="color-slider-disabled"
 />

-### Controlled
+### 垂直方向
+
+<ComponentPreview
+  name="color-slider-vertical"
+/>
+
+### 受控组件

 <ComponentPreview
  name="color-slider-controlled"
 />

-### HSL Channels
+### HSL 通道

-使用多个 ColorSlider 控制同一颜色值的不同通道。这些滑块可以共享同一个颜色值，从而组成完整的颜色选择器。
+使用多个 ColorSlider 控制颜色值的不同通道。滑块可共享同一颜色值以构建完整颜色选择器。

 <ComponentPreview
  name="color-slider-channels"
 />

-### Alpha Channel
+### 透明度通道

-alpha 通道滑块会显示透明度棋盘格背景，以帮助可视化透明度。
+Alpha 通道滑块显示透明棋盘格图案，帮助可视化透明度级别。

 <ComponentPreview
  name="color-slider-alpha-channel"
 />

-### RGB Channels
+### RGB 通道

-你也可以使用 RGB 色彩空间，并分别控制红、绿、蓝通道。
+也可使用 RGB 颜色空间的红、绿、蓝通道。

 <ComponentPreview
  name="color-slider-rgb-channels"
 />

-### 自定义渲染函数
+### 渲染函数

 <ComponentPreview
-  name="color-slider-custom-render-function"
+  name="color-slider-render-function"
 />

-<RelatedComponents component="color-slider" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="color-slider-custom-styles" />

-```tsx
-import { ColorSlider, Label } from '@heroui/react';
+### 全局 CSS

-function CustomColorSlider() {
-  return (
-    <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)" className="w-full">
-      <Label>Hue</Label>
-      <ColorSlider.Output className="text-muted text-sm" />
-      <ColorSlider.Track className="h-6 rounded-full">
-        <ColorSlider.Thumb className="size-5 rounded-full border-2 border-white" />
-      </ColorSlider.Track>
-    </ColorSlider>
-  );
-}
-```
-
-### 自定义组件类
-
-要自定义 ColorSlider 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 ColorSlider 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -133,99 +116,105 @@ function CustomColorSlider() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-ColorSlider 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-slider.css)）：
+ColorSlider 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-slider.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.color-slider` - 基础滑块容器
- `.color-slider__output` - 显示当前数值的输出元素
+- `.color-slider__output` - 显示当前值的输出元素
 - `.color-slider__track` - 带颜色渐变的轨道元素
- `.color-slider__thumb` - 显示当前颜色的滑块（thumb）
+- `.color-slider__thumb` - 显示当前颜色的滑块元素

-#### 状态类
- `.color-slider[data-disabled="true"]` - 禁用状态
- `.color-slider[data-orientation="vertical"]` - 纵向方向
- `.color-slider__thumb[data-dragging="true"]` - 正在拖动 thumb
- `.color-slider__thumb[data-focus-visible="true"]` - thumb 的键盘焦点
- `.color-slider__thumb[data-disabled="true"]` - thumb 禁用状态
+#### 状态类 [!toc]
+- `.color-slider[data-disabled="true"]` - 禁用滑块状态
+- `.color-slider[data-orientation="vertical"]` - 垂直方向
+- `.color-slider__thumb[data-dragging="true"]` - 滑块正在拖拽
+- `.color-slider__thumb[data-focus-visible="true"]` - 滑块键盘聚焦
+- `.color-slider__thumb[data-disabled="true"]` - 禁用滑块状态

 ### 交互状态

-组件同时支持 CSS 伪类与 data 属性，便于灵活定制：
+组件同时支持 CSS 伪类与 data 属性：

- **Hover**：thumb 上 `:hover` 或 `[data-hovered="true"]`
- **Focus**：thumb 上 `:focus-visible` 或 `[data-focus-visible="true"]`
- **Dragging**：thumb 上 `[data-dragging="true"]`
- **Disabled**：滑块或 thumb 上 `:disabled` 或 `[data-disabled="true"]`
+- **Hover**：滑块上的 `:hover` 或 `[data-hovered="true"]`
+- **Focus**：滑块上的 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **Dragging**：滑块上的 `[data-dragging="true"]`
+- **Disabled**：滑块或 thumb 上的 `:disabled` 或 `[data-disabled="true"]`

 ## API 参考

-### ColorSlider Props
+### ColorSlider

 继承自 [React Aria ColorSlider](https://react-spectrum.adobe.com/react-aria/ColorSlider.html)。

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `channel` | `ColorChannel` | - | 滑块操作的通道（hue、saturation、lightness、brightness、alpha、red、green、blue） |
-| `colorSpace` | `ColorSpace` | - | 色彩空间（hsl、hsb、rgb）。默认取当前值的色彩空间 |
+| `channel` | `ColorChannel` | - | 滑块操作的颜色通道（hue、saturation、lightness、brightness、alpha、red、green、blue） |
+| `colorSpace` | `ColorSpace` | - | 颜色空间（hsl、hsb、rgb）。默认为值的颜色空间 |
 | `value` | `string \| Color` | - | 当前颜色值（受控） |
 | `defaultValue` | `string \| Color` | - | 默认颜色值（非受控） |
-| `onChange` | `(value: Color) => void` | - | 拖动过程中数值变化时触发的事件处理函数 |
-| `onChangeEnd` | `(value: Color) => void` | - | 拖动结束时触发的事件处理函数 |
+| `onChange` | `(value: Color) => void` | - | 拖拽过程中值变化时的回调 |
+| `onChangeEnd` | `(value: Color) => void` | - | 拖拽结束时的回调 |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 滑块方向 |
-| `isDisabled` | `boolean` | - | 是否禁用滑块 |
-| `name` | `string` | - | 用于表单提交的 input 名称 |
+| `isDisabled` | `boolean` | - | 是否禁用 |
+| `name` | `string` | - | 表单提交时 input 元素的名称 |
 | `aria-label` | `string` | - | 滑块的无障碍标签 |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `children` | `ReactNode \| RenderFunction` | - | 滑块内容或渲染函数 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSliderRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 滑块内容或 render 函数 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSliderRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### ColorSlider.Output Props
+### ColorSlider.Output

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 CSS 类 |
-| `children` | `ReactNode \| RenderFunction` | - | 输出内容或渲染函数 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 输出内容或 render 函数 |

-### ColorSlider.Track Props
+### ColorSlider.Track

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 CSS 类 |
-| `style` | `CSSProperties \| RenderFunction` | - | 行内样式或渲染函数 |
-| `children` | `ReactNode \| RenderFunction` | - | 轨道内容或渲染函数 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `style` | `CSSProperties \| RenderFunction` | - | 内联样式或 render 函数 |
+| `children` | `ReactNode \| RenderFunction` | - | 轨道内容或 render 函数 |

-### ColorSlider.Thumb Props
+### ColorSlider.Thumb

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 CSS 类 |
-| `style` | `CSSProperties \| RenderFunction` | - | 行内样式或渲染函数 |
-| `children` | `ReactNode \| RenderFunction` | - | thumb 内容或渲染函数 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `style` | `CSSProperties \| RenderFunction` | - | 内联样式或 render 函数 |
+| `children` | `ReactNode \| RenderFunction` | - | 滑块内容或 render 函数 |

-### RenderProps
+### Render Props

-使用渲染函数时，会提供以下值：
+使用 render 函数时，提供以下值：

 | Prop | 类型 | 描述 |
 |------|------|------|
-| `state` | `ColorSliderState` | ColorSlider 的状态 |
+| `state` | `ColorSliderState` | 颜色滑块的状态 |
 | `color` | `Color` | 当前颜色值 |
 | `orientation` | `"horizontal" \| "vertical"` | 滑块方向 |
-| `isDisabled` | `boolean` | 是否禁用滑块 |
+| `isDisabled` | `boolean` | 是否禁用 |

 ## 无障碍

-ColorSlider 实现了 ARIA slider 模式，并提供：
+ColorSlider 组件实现 ARIA slider 模式，提供：

- 完整的键盘导航支持（方向键、Home、End、Page Up/Down）
- 屏幕阅读器对数值变化的播报
- 合理的焦点管理
+- 完整键盘导航支持（方向键、Home、End、Page Up/Down）
+- 值变化的屏幕阅读器播报
+- 正确的焦点管理
 - 禁用状态支持
- 通过隐藏 input 元素与 HTML 表单集成
- 结合区域设置进行数值格式化的国际化支持
+- 通过隐藏 input 元素集成 HTML 表单
+- 支持 locale 感知值格式化的国际化

-更多信息见 [React Aria ColorSlider 文档](https://react-spectrum.adobe.com/react-aria/ColorSlider.html)。
+更多信息请参阅 [React Aria ColorSlider 文档](https://react-spectrum.adobe.com/react-aria/ColorSlider.html)。
+
+## 相关组件
+
+<RelatedComponents component="color-slider" />
@@ -1,6 +1,6 @@
 ---
 title: ColorSwatchPicker 颜色色块选择器
-description: 允许用户从预置调色板中选择颜色的 swatch 列表。
+description: 允许用户从预置调色板中选择颜色的 swatch 列表
 links:
  rac: ColorSwatchPicker
  source: color-swatch-picker/color-swatch-picker.tsx
@@ -9,21 +9,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { ColorSwatchPicker, parseColor } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="color-swatch-picker-basic"
 />

-### 组件结构
-
-导入 ColorSwatchPicker 组件，并通过点语法访问所有子部分。
+## 组件结构

 ```tsx
 import { ColorSwatchPicker } from '@heroui/react';
@@ -46,6 +42,8 @@ export default () => (
 );
 ```

+## 示例
+
 ### 变体

 <ComponentPreview
@@ -58,6 +56,12 @@ export default () => (
  name="color-swatch-picker-sizes"
 />

+### 禁用
+
+<ComponentPreview
+  name="color-swatch-picker-disabled"
+/>
+
 ### 堆叠布局

 <ComponentPreview
@@ -70,60 +74,34 @@ export default () => (
  name="color-swatch-picker-default-value"
 />

-### 受控
+### 受控组件

 <ComponentPreview
  name="color-swatch-picker-controlled"
 />

-### 禁用
-
-<ComponentPreview
-  name="color-swatch-picker-disabled"
-/>
-
 ### 自定义指示器

 <ComponentPreview
  name="color-swatch-picker-custom-indicator"
 />

-### 自定义渲染函数
+### 渲染函数

 <ComponentPreview
-  name="color-swatch-picker-custom-render-function"
+  name="color-swatch-picker-render-function"
 />

-<RelatedComponents component="color-swatch-picker" />
+## 自定义样式

+### Tailwind CSS

-## 样式
+<ComponentPreview name="color-swatch-picker-custom-styles" />

-### 传入 Tailwind CSS 类
+### 全局 CSS

-你可以使用 `className` props 自定义 ColorSwatchPicker：
-
-```tsx
-import { ColorSwatchPicker } from '@heroui/react';
-
-function CustomColorSwatchPicker() {
-  return (
-    <ColorSwatchPicker className="gap-4">
-      <ColorSwatchPicker.Item color="#F43F5E" className="shadow-lg">
-        <ColorSwatchPicker.Swatch />
-      </ColorSwatchPicker.Item>
-      <ColorSwatchPicker.Item color="#D946EF">
-        <ColorSwatchPicker.Swatch />
-      </ColorSwatchPicker.Item>
-    </ColorSwatchPicker>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 ColorSwatchPicker 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+可使用 `@layer components` 指令自定义 ColorSwatchPicker 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -141,48 +119,46 @@ function CustomColorSwatchPicker() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 ColorSwatchPicker 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch-picker.css)）：

-#### 基础与结构
-
+#### 基础与结构 [!toc]
 - `.color-swatch-picker` - 基础容器（flex 布局）
 - `.color-swatch-picker__item` - 单个 swatch 包裹层
 - `.color-swatch-picker__swatch` - swatch 视觉元素

-#### 尺寸类
-
+#### 尺寸类 [!toc]
 - `.color-swatch-picker--xs` - 特小（16px）
 - `.color-swatch-picker--sm` - 小（24px）
 - `.color-swatch-picker--md` - 中（32px，默认）
 - `.color-swatch-picker--lg` - 大（36px）
 - `.color-swatch-picker--xl` - 特大（40px）

-#### 形状变体
-
+#### 形状变体 [!toc]
 - `.color-swatch-picker--circle` - 圆形（默认）
 - `.color-swatch-picker--square` - 圆角方形

-#### 布局类
-
+#### 布局类 [!toc]
 - `.color-swatch-picker--grid` - 横向换行网格（默认）
 - `.color-swatch-picker--stack` - 纵向堆叠

 ### 交互状态

-组件同时支持 CSS 伪类与 data 属性，以便灵活控制状态：
+组件同时支持 CSS 伪类与 data 属性：

- **悬停**：`:hover` 或 `[data-hovered="true"]` — 缩放至 1.1（仅在未选中时）
- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]` — 焦点环
- **已选中**：`[data-selected="true"]` — 与 swatch 同色的内边框
- **禁用**：`[data-disabled="true"]` — 降低透明度
+- **Hover**：`:hover` 或 `[data-hovered="true"]` - 缩放至 1.1（仅在未选中时）
+- **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]` - 焦点环
+- **Selected**：`[data-selected="true"]` - 与 swatch 同色的内边框
+- **Disabled**：`[data-disabled="true"]` - 降低透明度

 ## API 参考

-### ColorSwatchPicker Props
+### ColorSwatchPicker

 继承自 [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/react-aria/ColorSwatchPicker.html)。

@@ -190,29 +166,29 @@ ColorSwatchPicker 组件使用以下 CSS 类（[查看源码样式](https://gith
 |------|------|--------|------|
 | `value` | `string \| Color` | - | 当前选中颜色（受控） |
 | `defaultValue` | `string \| Color` | - | 默认选中颜色（非受控） |
-| `onChange` | `(value: Color) => void` | - | 选中变化时调用的处理函数 |
+| `onChange` | `(value: Color) => void` | - | 选中变化时的回调 |
 | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | swatch 尺寸 |
 | `variant` | `"circle" \| "square"` | `"circle"` | swatch 形状 |
 | `layout` | `"grid" \| "stack"` | `"grid"` | 布局方向 |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |
 | `children` | `React.ReactNode` | - | ColorSwatchPicker.Item 元素 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### ColorSwatchPicker.Item Props
+### ColorSwatchPicker.Item

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `color` | `string \| Color` | **必填** | swatch 颜色 |
 | `isDisabled` | `boolean` | `false` | 是否禁用该项 |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |
 | `children` | `React.ReactNode` | - | ColorSwatchPicker.Swatch 元素 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerItemRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerItemRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### ColorSwatchPicker.Swatch Props
+### ColorSwatchPicker.Swatch

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |

 ### parseColor

@@ -230,3 +206,7 @@ const green = parseColor('rgb(0, 255, 0)');
 // 解析 HSL
 const blue = parseColor('hsl(240, 100%, 50%)');
 ```
+
+## 相关组件
+
+<RelatedComponents component="color-swatch-picker" />
@@ -1,6 +1,6 @@
 ---
 title: ColorSwatch 颜色色块
-description: 颜色值的视觉预览，并提供无障碍支持。
+description: 颜色值的视觉预览，并提供无障碍支持
 links:
  rac: ColorSwatch
  source: color-swatch/color-swatch.tsx
@@ -8,45 +8,45 @@ links:
  storybook: Components/Colors/ColorSwatch
 ---

-## 引入
+## 用法

 ```tsx
 import { ColorSwatch } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="color-swatch-basic"
 />

-### Sizes
+## 示例
+
+### 尺寸

 <ComponentPreview
  name="color-swatch-sizes"
 />

-### Shapes
+### 形状

 <ComponentPreview
  name="color-swatch-shapes"
 />

-### Transparency
+### 透明度

 <ComponentPreview
  name="color-swatch-transparency"
 />

-### Custom Styles with Render Props
+### 渲染函数

-你可以使用 `style` 渲染 prop 来读取颜色值并创建自定义视觉效果。
+可使用 `style` render prop 读取颜色值并创建自定义视觉效果。

 <ComponentPreview
-  name="color-swatch-custom-styles"
+  name="color-swatch-render-function"
 />

-### Accessibility
+### 无障碍

 使用 `colorName` 为颜色提供自定义可访问名称，并使用 `aria-label` 补充颜色用途的上下文。

@@ -54,35 +54,16 @@ import { ColorSwatch } from '@heroui/react';
  name="color-swatch-accessibility"
 />

-### 自定义渲染函数
+## 自定义样式

-<ComponentPreview
-  name="color-swatch-custom-render-function"
-/>
+### Tailwind CSS

-<RelatedComponents component="color-swatch" />
+<ComponentPreview name="color-swatch-custom-styles" />

-## 样式
+### 全局 CSS

-### 传入 Tailwind CSS 类
-
-```tsx
-import {ColorSwatch} from '@heroui/react';
-
-function CustomColorSwatch() {
-  return (
-    <ColorSwatch
-      className="size-12 rounded-lg"
-      color="#0485F7"
-    />
-  );
-}
-```
-
-### 自定义组件类
-
-要自定义 ColorSwatch 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 ColorSwatch 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -92,20 +73,22 @@ function CustomColorSwatch() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-ColorSwatch 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch.css)）：
+ColorSwatch 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch.css)）：

-#### 基础类
- `.color-swatch` - 基础 swatch（色板）样式，透明区域使用棋盘格背景
+#### 基础类 [!toc]
+- `.color-swatch` - 基础 swatch 样式，透明区域使用棋盘格背景

-#### 形状类
+#### 形状类 [!toc]
 - `.color-swatch--circle` - 圆形（默认）
 - `.color-swatch--square` - 圆角方形

-#### 尺寸类
+#### 尺寸类 [!toc]
 - `.color-swatch--xs` - 特小（16px）
 - `.color-swatch--sm` - 小（24px）
 - `.color-swatch--md` - 中（32px，默认）
@@ -114,22 +97,21 @@ ColorSwatch 使用以下 CSS 类（[查看源码样式](https://github.com/herou

 ## API 参考

-### ColorSwatch Props
+### ColorSwatch

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `color` | `string \| Color` | - | 要展示的颜色值（hex、rgb、hsl 等） |
 | `colorName` | `string` | - | 颜色的可访问名称（会覆盖自动生成的描述） |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `shape` | `"circle" \| "square"` | `"circle"` | swatch（色板）形状 |
-| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | swatch（色板）尺寸 |
-| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | 行内样式，或带颜色访问能力的渲染 prop 函数 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `shape` | `"circle" \| "square"` | `"circle"` | swatch 形状 |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | swatch 尺寸 |
+| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | 行内样式，或带颜色访问能力的 render prop 函数 |
 | `aria-label` | `string` | - | swatch 的无障碍标签 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### Style Render Props
-
-当把 `style` 作为函数传入时，你会获得包含颜色对象在内的渲染参数：
+### Style Render
+当把 `style` 作为函数传入时，会获得包含颜色对象在内的 render props：

 ```tsx
 <ColorSwatch
@@ -141,7 +123,10 @@ ColorSwatch 使用以下 CSS 类（[查看源码样式](https://github.com/herou
 ```

 `color` 对象提供例如：
-
 - `color.toString("css")` - 返回 CSS 颜色字符串
 - `color.toString("hex")` - 返回十六进制颜色字符串
 - `color.getChannelValue("alpha")` - 返回 alpha 通道数值
+
+## 相关组件
+
+<RelatedComponents component="color-swatch" />
@@ -8,21 +8,17 @@ links:
  storybook: Components/Controls/Slider
 ---

-## 引入
+## 用法

 ```tsx
 import { Slider } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="slider-default"
 />

-### 组件结构
-
-引入 Slider 组件，并通过点语法访问各部分。
+## 组件结构

 ```tsx
 import { Slider, Label } from '@heroui/react';
@@ -39,7 +35,15 @@ export default () => (
 )
 ```

-### 范围滑块组件结构
+## 示例
+
+### 禁用
+
+<ComponentPreview
+  name="slider-disabled"
+/>
+
+### 范围滑块结构

 ```tsx
 import { Slider, Label } from '@heroui/react';
@@ -62,57 +66,33 @@ export default () => (
 )
 ```

-### 纵向
+### 垂直方向

 <ComponentPreview
  name="slider-vertical"
 />

-### 范围
+### 范围选择

 <ComponentPreview
  name="slider-range"
 />

-### 禁用
+### 渲染函数

 <ComponentPreview
-  name="slider-disabled"
+  name="slider-render-function"
 />

-### 自定义渲染函数
+## 自定义样式

-<ComponentPreview
-  name="slider-custom-render-function"
-/>
+### Tailwind CSS

-<RelatedComponents component="slider" />
+<ComponentPreview name="slider-custom-styles" />

-## 样式
+### 全局 CSS

-### 传入 Tailwind CSS 类
-
-```tsx
-import { Slider, Label } from '@heroui/react';
-
-function CustomSlider() {
-  return (
-    <Slider className="w-full">
-      <Label>Volume</Label>
-      <Slider.Output className="text-muted-fg text-sm" />
-      <Slider.Track className="h-2 rounded-full bg-surface-secondary">
-        <Slider.Fill className="bg-accent" />
-        <Slider.Thumb className="size-4 rounded-full bg-accent" />
-      </Slider.Track>
-    </Slider>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Slider 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -138,20 +118,22 @@ function CustomSlider() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Slider 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/slider.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.slider` - Slider 根容器
 - `.slider__output` - 显示当前值的输出元素
 - `.slider-track` - 包含填充与滑块的轨道元素
 - `.slider-fill` - 显示已选范围的填充元素
 - `.slider-thumb` - 单个滑块控制点

-#### 状态类
+#### 状态类 [!toc]
 - `.slider[data-disabled="true"]` - 禁用状态
 - `.slider[data-orientation="vertical"]` - 纵向方向
 - `.slider-thumb[data-dragging="true"]` - 滑块正在拖动
@@ -171,8 +153,7 @@ Slider 组件使用以下 CSS 类（[查看源码样式](https://github.com/hero

 ## API 参考

-### Slider Props
-
+### Slider
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `value` | `number \| number[]` | - | 当前值（受控）。 |
@@ -191,31 +172,27 @@ Slider 组件使用以下 CSS 类（[查看源码样式](https://github.com/hero
 | `children` | `ReactNode \| RenderFunction` | - | Slider 内容或渲染函数。 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Slider.Output Props
-
+### Slider.Output
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类。 |
 | `children` | `ReactNode \| RenderFunction` | - | 输出内容或渲染函数。 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderOutputRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Slider.Track Props
-
+### Slider.Track
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类。 |
 | `children` | `ReactNode \| RenderFunction` | - | 轨道内容或渲染函数。 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderTrackRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Slider.Fill Props
-
+### Slider.Fill
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类。 |
 | `style` | `CSSProperties` | - | 行内样式。 |

-### Slider.Thumb Props
-
+### Slider.Thumb
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `index` | `number` | `0` | 滑块在 Slider 内的索引。 |
@@ -239,7 +216,7 @@ Slider 组件使用以下 CSS 类（[查看源码样式](https://github.com/hero

 ## 示例

-### 基础用法
+### 基本用法

 ```tsx
 import { Slider, Label } from '@heroui/react';
@@ -281,7 +258,7 @@ import { Slider, Label } from '@heroui/react';
 </Slider>
 ```

-### 受控值
+### 受控数值

 ```tsx
 import { Slider, Label } from '@heroui/react';
@@ -324,7 +301,7 @@ import { Slider, Label } from '@heroui/react';
 </Slider>
 ```

-### 纵向方向
+### 垂直方向

 ```tsx
 import { Slider, Label } from '@heroui/react';
@@ -377,3 +354,7 @@ Slider 组件实现 ARIA slider 模式，并提供：
 - 从右到左（RTL）语言支持

 更多信息见 [React Aria Slider 文档](https://react-spectrum.adobe.com/react-aria/Slider.html)。
+
+## 相关组件
+
+<RelatedComponents component="slider" />
@@ -10,37 +10,32 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Switch, SwitchGroup, Label } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="switch-basic"
 />

-### 组件结构
-
-引入 Switch 组件，并通过点语法访问各部分。
+## 组件结构

 ```tsx
-import { Switch, Description, FieldError } from '@heroui/react';
+import { Switch, Label, Description } from '@heroui/react';

 export default () => (
  <Switch>
+    <Switch.Control>
+      <Switch.Thumb>
+        <Switch.Icon/> {/* 可选 */}
+      </Switch.Thumb>
+    </Switch.Control>
    <Switch.Content>
-      <Switch.Control>
-        <Switch.Thumb>
-          <Switch.Icon /> {/* 可选 */}
-        </Switch.Thumb>
-      </Switch.Control>
-      Label {/* 纯文本 —— 可点击的标签，同时作为无障碍名称 */}
+      <Label />
+      <Description /> {/* 可选 */}
    </Switch.Content>
-    <Description /> {/* 可选 — 字段级帮助文本 */}
-    <FieldError /> {/* 可选 — 校验错误信息 */}
  </Switch>
 );
 ```
@@ -53,48 +48,23 @@ import { Switch, SwitchGroup, Label } from '@heroui/react';
 export default () => (
  <SwitchGroup>
    <Switch>
-      <Switch.Content>
-        <Switch.Control>
-          <Switch.Thumb />
-        </Switch.Control>
-        Option 1
-      </Switch.Content>
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Label>Option 1</Label>
    </Switch>
    <Switch>
-      <Switch.Content>
-        <Switch.Control>
-          <Switch.Thumb />
-        </Switch.Control>
-        Option 2
-      </Switch.Content>
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Label>Option 2</Label>
    </Switch>
  </SwitchGroup>
 );
 ```

-### 禁用

-<ComponentPreview
-  name="switch-disabled"
-/>
-
-### 默认选中
-
-<ComponentPreview
-  name="switch-default-selected"
-/>
-
-### 受控
-
-<ComponentPreview
-  name="switch-controlled"
-/>
-
-### 无标签
-
-<ComponentPreview
-  name="switch-without-label"
-/>
+## 示例

 ### 尺寸

@@ -102,24 +72,48 @@ export default () => (
  name="switch-sizes"
 />

-### 标签位置
-
-<ComponentPreview
-  name="switch-label-position"
-/>
-
 ### 带图标

 <ComponentPreview
  name="switch-with-icons"
 />

+### 禁用
+
+<ComponentPreview
+  name="switch-disabled"
+/>
+
+### 无标签
+
+<ComponentPreview
+  name="switch-without-label"
+/>
+
 ### 带描述

 <ComponentPreview
  name="switch-with-description"
 />

+### 默认选中
+
+<ComponentPreview
+  name="switch-default-selected"
+/>
+
+### 受控组件
+
+<ComponentPreview
+  name="switch-controlled"
+/>
+
+### 标签位置
+
+<ComponentPreview
+  name="switch-label-position"
+/>
+
 ### 分组

 <ComponentPreview
@@ -132,94 +126,33 @@ export default () => (
  name="switch-group-horizontal"
 />

-### Render Props
-
-<ComponentPreview
-  name="switch-render-props"
-/>
-
 ### 表单集成

 <ComponentPreview
  name="switch-form"
 />

-### 自定义样式
+### 渲染属性

 <ComponentPreview
-  name="switch-custom-styles"
+  name="switch-render-props"
 />

-### 自定义渲染函数
+### 渲染函数

 <ComponentPreview
-  name="switch-custom-render-function"
+  name="switch-render-function"
 />

-<RelatedComponents component="switch" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="switch-custom-styles" />

-你可以自定义各个 Switch：
+### 全局 CSS

-```tsx
-import { Switch, Label } from '@heroui/react';
-
-function CustomSwitch() {
-  return (
-    <Switch>
-      {({isSelected}) => (
-        <>
-          <Switch.Control
-            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
-          >
-            <Switch.Thumb
-              className={`size-[27px] bg-white shadow-sm ${isSelected ? "translate-x-5 shadow-lg" : ""}`}
-            />
-          </Switch.Control>
-          Custom Switch
-        </>
-      )}
-    </Switch>
-  );
-}
-```
-
-或自定义 SwitchGroup 布局：
-
-```tsx
-import { Switch, SwitchGroup, Label } from '@heroui/react';
-
-function CustomSwitchGroup() {
-  return (
-    <SwitchGroup className="gap-8" orientation="horizontal">
-      <Switch>
-        <Switch.Content>
-          <Switch.Control>
-            <Switch.Thumb />
-          </Switch.Control>
-          Option 1
-        </Switch.Content>
-      </Switch>
-      <Switch>
-        <Switch.Content>
-          <Switch.Control>
-            <Switch.Thumb />
-          </Switch.Control>
-          Option 2
-        </Switch.Content>
-      </Switch>
-    </SwitchGroup>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Switch 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -236,7 +169,7 @@ function CustomSwitchGroup() {
  }

  .switch__content {
-    @apply items-center gap-3;
+    @apply flex flex-col gap-1;
  }

  .switch__icon {
@@ -245,11 +178,13 @@ function CustomSwitchGroup() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-#### Switch 类
+#### Switch 类 [!toc]

 Switch 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch.css)）：

@@ -262,7 +197,7 @@ Switch 组件使用以下 CSS 类（[查看源码样式](https://github.com/hero
 - `.switch--md` - 中尺寸变体（默认）
 - `.switch--lg` - 大尺寸变体

-#### SwitchGroup 类
+#### SwitchGroup 类 [!toc]

 SwitchGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch-group.css)）：

@@ -283,8 +218,7 @@ SwitchGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com

 ## API 参考

-### Switch Props
-
+### Switch
 继承自 [React Aria SwitchField](https://react-spectrum.adobe.com/react-aria/Switch.html)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -305,8 +239,7 @@ SwitchGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com
 | `children` | `React.ReactNode \| (values: SwitchFieldRenderProps) => React.ReactNode` | - | Switch 内容或字段级渲染 prop。 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SwitchFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Switch.Content Props
-
+### Switch.Content
 包裹控件与标签文本的可点击 `<label>`。请把 `Switch.Control` 与 `Label` 放在它内部；`Description`/`FieldError` 作为 `Switch.Content` 的兄弟节点。对于没有标签的 switch，省略 `Label` 并在 `Switch` 上传入 `aria-label`。

 | Prop | 类型 | 默认值 | 描述 |
@@ -331,10 +264,13 @@ SwitchGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com

 `Switch.Control` 使用按钮级渲染 prop（`isHovered`、`isPressed`、`isFocusVisible` 等）。将函数作为 `Switch.Control` 的子元素即可访问。

-### SwitchGroup Props
-
+### SwitchGroup
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | Switch 组方向。 |
 | `children` | `React.ReactNode` | - | 要渲染的 Switch 项。 |
 | `className` | `string` | - | 额外的 CSS 类。 |
+
+## 相关组件
+
+<RelatedComponents component="switch" />
@@ -1,6 +1,7 @@
 ---
-title: Badge 徽标
-description: 展示相对其他元素定位的小型指示器，常用于未读数、状态点与标签等场景。
+title: Badge 徽章
+description: 相对其他元素定位的小型指示器，常用于通知数量、状态点与标签
+
 links:
  source: badge/badge.tsx
  styles: badge.css
@@ -8,17 +9,21 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Badge } from '@heroui/react';
 ```

+<ComponentPreview
+  name="badge-basic"
+/>
+
 ## 组件结构

-Badge 通过 `Badge.Anchor` 相对另一个元素定位。纯文本子节点会自动包在 `<Badge.Label>` 中。
+Badge 通过 `Badge.Anchor` 相对其他元素定位。纯文本子节点会自动包裹在 `<Badge.Label>` 中。

-> 若需要独立展示标签，请改用 [Chip](/docs/react/components/chip) 组件。
+> 独立标签用法请使用 [Chip](/docs/react/components/chip) 组件。

 ```tsx
 <Badge.Anchor>
@@ -27,16 +32,12 @@ Badge 通过 `Badge.Anchor` 相对另一个元素定位。纯文本子节点会
 </Badge.Anchor>
 ```

-### 用法
+## 示例
+
+### 变体

 <ComponentPreview
-  name="badge-basic"
-/>
-
-### 颜色
-
-<ComponentPreview
-  name="badge-colors"
+  name="badge-variants"
 />

 ### 尺寸
@@ -45,61 +46,44 @@ Badge 通过 `Badge.Anchor` 相对另一个元素定位。纯文本子节点会
  name="badge-sizes"
 />

-### 变体
+### 颜色

 <ComponentPreview
-  name="badge-variants"
+  name="badge-colors"
 />

-### 位置
+### 徽章位置

 <ComponentPreview
  name="badge-placements"
 />

-### 带内容
+### 点状徽标

-Badge 支持以文本、数字与图标作为内容。未提供子节点时，会渲染为点状指示器。
-
-<ComponentPreview
-  name="badge-with-content"
-/>
-
-### 点状 Badge
-
-空的 Badge 可作为状态指示器，适用于在线/离线状态或活动信号等场景。
+空徽章作为状态指示器，适用于在线/离线或活动信号。

 <ComponentPreview
  name="badge-dot"
 />

-<RelatedComponents component="badge" />
+### 带内容

-## 样式
+Badge 支持文本、数字与图标。无子节点时渲染为点状指示器。

-### 传入 Tailwind CSS 类
+<ComponentPreview
+  name="badge-with-content"
+/>

-你可以为根容器与各插槽分别添加类名：
+## 自定义样式

-```tsx
-import {Badge, Avatar} from '@heroui/react';
+### Tailwind CSS

-function CustomBadge() {
-  return (
-    <Badge.Anchor>
-      <Avatar />
-      <Badge className="border-2 border-white" color="danger">
-        <Badge.Label className="font-bold">99+</Badge.Label>
-      </Badge>
-    </Badge.Anchor>
-  );
-}
-```
+<ComponentPreview name="badge-custom-styles" />

-### 自定义组件类
+### 全局 CSS

-若要自定义 Badge 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 Badge 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -117,81 +101,87 @@ function CustomBadge() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Badge 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/badge.css)）：

-#### 基础类
- `.badge` - Badge 容器基础样式
- `.badge__label` - 标签文本插槽样式
- `.badge-anchor` - 锚定元素的定位包裹层
+#### 基础类 [!toc]
+- `.badge` - 基础徽章容器样式
+- `.badge__label` - 标签文本 slot 样式
+- `.badge-anchor` - 锚定元素的定位包装器

-#### 颜色类
- `.badge--accent` - 强调颜色变体
- `.badge--danger` - 危险颜色变体
- `.badge--default` - 默认颜色变体
- `.badge--success` - 成功颜色变体
- `.badge--warning` - 警告颜色变体
+#### 颜色类 [!toc]
+- `.badge--accent` - 强调色变体
+- `.badge--danger` - 危险色变体
+- `.badge--default` - 默认色变体
+- `.badge--success` - 成功色变体
+- `.badge--warning` - 警告色变体

-#### 变体类
- `.badge--primary` - Primary 变体，实心背景
- `.badge--secondary` - Secondary 变体，默认背景
- `.badge--soft` - Soft 变体，浅色背景
+#### 变体类 [!toc]
+- `.badge--primary` - 填充背景的主变体
+- `.badge--secondary` - 默认背景的次变体
+- `.badge--soft` - 浅色背景的 soft 变体

-#### 尺寸类
+#### 尺寸类 [!toc]
 - `.badge--sm` - 小尺寸
 - `.badge--md` - 中尺寸（默认）
 - `.badge--lg` - 大尺寸

-#### 位置类
+#### 位置类 [!toc]
 - `.badge--top-right` - 右上角（默认）
 - `.badge--top-left` - 左上角
 - `.badge--bottom-right` - 右下角
 - `.badge--bottom-left` - 左下角

-#### 复合变体类
+#### 复合变体类 [!toc]

-Badge 支持组合变体与颜色类（例如 `.badge--primary.badge--accent`）。以下组合定义了默认样式：
+Badge 支持组合变体与颜色类（如 `.badge--primary.badge--accent`）。以下组合有默认样式：

-**Primary 变体：**
- `.badge--primary.badge--accent` - Primary + 强调色，实心背景
- `.badge--primary.badge--default` - Primary + 默认色，实心背景
- `.badge--primary.badge--success` - Primary + 成功色，实心背景
- `.badge--primary.badge--warning` - Primary + 警告色，实心背景
- `.badge--primary.badge--danger` - Primary + 危险色，实心背景
+**Primary Variants:**
+- `.badge--primary.badge--accent` - 填充背景的 primary accent
+- `.badge--primary.badge--default` - 填充背景的 primary default
+- `.badge--primary.badge--success` - 填充背景的 primary success
+- `.badge--primary.badge--warning` - 填充背景的 primary warning
+- `.badge--primary.badge--danger` - 填充背景的 primary danger

-**Soft 变体：**
- `.badge--soft.badge--accent` - Soft + 强调色，浅色背景
- `.badge--soft.badge--default` - Soft + 默认色，浅色背景
- `.badge--soft.badge--success` - Soft + 成功色，浅色背景
- `.badge--soft.badge--warning` - Soft + 警告色，浅色背景
- `.badge--soft.badge--danger` - Soft + 危险色，浅色背景
+**Soft Variants:**
+- `.badge--soft.badge--accent` - 浅色背景的 soft accent
+- `.badge--soft.badge--default` - 浅色背景的 soft default
+- `.badge--soft.badge--success` - 浅色背景的 soft success
+- `.badge--soft.badge--warning` - 浅色背景的 soft warning
+- `.badge--soft.badge--danger` - 浅色背景的 soft danger

 ## API 参考

-### Badge Props
+### Badge

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `children` | `React.ReactNode` | - | Badge 内展示的内容（文本、数字或图标）。省略时渲染为点状指示器。 |
-| `className` | `string` | - | 根元素的额外 CSS 类。 |
-| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 颜色变体。 |
-| `variant` | `"primary" \| "secondary" \| "soft"` | `"primary"` | 视觉样式变体。 |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 尺寸。 |
-| `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | 相对锚点的位置。 |
+| `children` | `React.ReactNode` | - | 徽章内容（文本、数字或图标）。省略时渲染为点 |
+| `className` | `string` | - | 根元素附加 CSS 类 |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 徽章颜色变体 |
+| `variant` | `"primary" \| "secondary" \| "soft"` | `"primary"` | 视觉样式变体 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 徽章尺寸 |
+| `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | 相对锚点的位置 |

-### Badge.Anchor Props
+### Badge.Anchor

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `children` | `React.ReactNode` | - | 被锚定的元素以及 Badge 本身。 |
-| `className` | `string` | - | 锚点包裹层的额外 CSS 类。 |
+| `children` | `React.ReactNode` | - | 锚定元素及 Badge 本身 |
+| `className` | `string` | - | 锚点包装器附加 CSS 类 |

-### Badge.Label Props
+### Badge.Label

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `children` | `React.ReactNode` | - | 标签文本内容。 |
-| `className` | `string` | - | 标签插槽的额外 CSS 类。 |
+| `children` | `React.ReactNode` | - | 标签文本内容 |
+| `className` | `string` | - | 标签 slot 附加 CSS 类 |
+
+## 相关组件
+
+<RelatedComponents component="badge" />
@@ -1,6 +1,6 @@
 ---
 title: Chip 标签
-description: 用于展示标签、状态与分类等信息的小型徽标。
+description: 用于显示标签、状态与分类的小型信息徽章
 links:
  source: chip/chip.tsx
  styles: chip.css
@@ -8,17 +8,19 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Chip } from '@heroui/react';
 ```

+<ComponentPreview
+  name="chip-basic"
+/>
+
 ## 组件结构

-引入 Chip 组件，并通过点语法访问各部分。
-
-> 纯文本子节点会自动包在 `<Chip.Label>` 中。
+> 纯文本子节点会自动包裹在 `<Chip.Label>` 中。

 ```tsx
 <Chip>
@@ -26,11 +28,7 @@ import { Chip } from '@heroui/react';
 </Chip>
 ```

-### 用法
-
-<ComponentPreview
-  name="chip-basic"
-/>
+## 示例

 ### 变体

@@ -38,44 +36,28 @@ import { Chip } from '@heroui/react';
  name="chip-variants"
 />

+### 状态类型
+
+<ComponentPreview
+  name="chip-statuses"
+/>
+
 ### 带图标

 <ComponentPreview
  name="chip-with-icon"
 />

-### 状态
+## 自定义样式

-<ComponentPreview
-  name="chip-statuses"
-/>
+### Tailwind CSS

-<RelatedComponents component="chip" />
+<ComponentPreview name="chip-custom-styles" />

-## 样式
+### 全局 CSS

-### 传入 Tailwind CSS 类
-
-你可以为根容器与各插槽分别添加类名：
-
-```tsx
-import {Chip} from '@heroui/react';
-
-function CustomChip() {
-  return (
-    <Chip className="rounded-full px-4 py-2 font-bold">
-      <Chip.Label className="text-lg uppercase">
-        Custom Styled
-      </Chip.Label>
-    </Chip>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Chip 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 Chip 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -97,67 +79,73 @@ function CustomChip() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Chip 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/chip.css)）：

-#### 基础类
- `.chip` - Chip 容器基础样式
- `.chip__label` - 标签文本插槽样式
+#### 基础类 [!toc]
+- `.chip` - 基础标签容器样式
+- `.chip__label` - 标签文本 slot 样式

-#### 颜色类
- `.chip--accent` - 强调颜色变体
- `.chip--danger` - 危险颜色变体
- `.chip--default` - 默认颜色变体
- `.chip--success` - 成功颜色变体
- `.chip--warning` - 警告颜色变体
+#### 颜色类 [!toc]
+- `.chip--accent` - 强调色变体
+- `.chip--danger` - 危险色变体
+- `.chip--default` - 默认色变体
+- `.chip--success` - 成功色变体
+- `.chip--warning` - 警告色变体

-#### 变体类
- `.chip--primary` - Primary 变体，实心背景
- `.chip--secondary` - Secondary 变体，带边框
- `.chip--tertiary` - Tertiary 变体，透明背景
- `.chip--soft` - Soft 变体，浅色背景
+#### 变体类 [!toc]
+- `.chip--primary` - 填充背景的主变体
+- `.chip--secondary` - 带边框的次变体
+- `.chip--tertiary` - 透明背景的三级变体
+- `.chip--soft` - 浅色背景的 soft 变体

-#### 尺寸类
+#### 尺寸类 [!toc]
 - `.chip--sm` - 小尺寸
 - `.chip--md` - 中尺寸（默认）
 - `.chip--lg` - 大尺寸

-#### 复合变体类
+#### 复合变体类 [!toc]

-Chip 支持组合变体与颜色类（例如 `.chip--secondary.chip--accent`）。以下组合定义了默认样式：
+Chip 支持组合变体与颜色类（如 `.chip--secondary.chip--accent`）。以下组合有默认样式：

-**Primary 变体：**
- `.chip--primary.chip--accent` - Primary + 强调色，实心背景
- `.chip--primary.chip--success` - Primary + 成功色，实心背景
- `.chip--primary.chip--warning` - Primary + 警告色，实心背景
- `.chip--primary.chip--danger` - Primary + 危险色，实心背景
+**Primary Variants:**
+- `.chip--primary.chip--accent` - 填充背景的 primary accent 组合
+- `.chip--primary.chip--success` - 填充背景的 primary success 组合
+- `.chip--primary.chip--warning` - 填充背景的 primary warning 组合
+- `.chip--primary.chip--danger` - 填充背景的 primary danger 组合

-**Soft 变体：**
- `.chip--accent.chip--soft` - Soft + 强调色，浅色背景
- `.chip--success.chip--soft` - Soft + 成功色，浅色背景
- `.chip--warning.chip--soft` - Soft + 警告色，浅色背景
- `.chip--danger.chip--soft` - Soft + 危险色，浅色背景
+**Soft Variants:**
+- `.chip--accent.chip--soft` - 浅色背景的 soft accent 组合
+- `.chip--success.chip--soft` - 浅色背景的 soft success 组合
+- `.chip--warning.chip--soft` - 浅色背景的 soft warning 组合
+- `.chip--danger.chip--soft` - 浅色背景的 soft danger 组合

-**说明：** 你也可以在 CSS 中通过 `@layer components` 为任意变体与颜色组合（例如 `.chip--secondary.chip--accent`、`.chip--tertiary.chip--success`）编写自定义样式。
+**Note:** 可使用 CSS 中的 `@layer components` 指令为任意变体-颜色组合（如 `.chip--secondary.chip--accent`、`.chip--tertiary.chip--success`）应用自定义样式。

 ## API 参考

-### Chip Props
+### Chip

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `children` | `React.ReactNode` | - | Chip 内展示的内容 |
-| `className` | `string` | - | 根元素的额外 CSS 类 |
-| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 颜色变体 |
+| `children` | `React.ReactNode` | - | 标签内显示的内容 |
+| `className` | `string` | - | 根元素附加 CSS 类 |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 标签颜色变体 |
 | `variant` | `"primary" \| "secondary" \| "tertiary" \| "soft"` | `"secondary"` | 视觉样式变体 |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 尺寸 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 标签尺寸 |

-### Chip.Label Props
+### Chip.Label

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 标签文本内容 |
-| `className` | `string` | - | 标签插槽的额外 CSS 类 |
+| `className` | `string` | - | 标签 slot 附加 CSS 类 |
+
+## 相关组件
+
+<RelatedComponents component="chip" />
@@ -9,22 +9,18 @@ links:
  storybook: Components/Data Display/Table
 ---

-## 引入
+## 用法

 ```tsx
 import { Table } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="table-basic"
  minHeight="320px"
 />

-### 组件结构
-
-引入 Table 组件，并通过点语法访问各部分。
+## 组件结构

 ```tsx
 import { Table } from '@heroui/react';
@@ -56,6 +52,8 @@ export default () => (
 );
 ```

+## 示例
+
 ### 次要变体

 <ComponentPreview
@@ -63,9 +61,18 @@ export default () => (
  minHeight="320px"
 />

+### 异步加载
+
+使用 `Table.LoadMore` 实现无限滚动。它会渲染一个哨兵行，滚动到视口时触发 `onLoadMore`。
+
+<ComponentPreview
+  name="table-async-loading"
+  minHeight="380px"
+/>
+
 ### 排序

-在 `Table.Column` 上设置 `allowsSorting` 可将列设为可排序。在 `Table.Content` 上使用 `sortDescriptor` 与 `onSortChange` 管理排序状态。使用 `Table.SortableColumnHeader` 包裹列标签，并将列渲染函数中的 `sortDirection` 传入，即可显示默认的升序 / 降序指示器。
+在 `Table.Column` 上使用 `allowsSorting` 属性可启用列排序。在 `Table.Content` 上使用 `sortDescriptor` 与 `onSortChange` 管理排序状态。将标签包裹在 `Table.SortableColumnHeader` 中，并将列 render prop 的 `sortDirection` 转发以渲染默认升序/降序指示器。

 <ComponentPreview
  name="table-sorting"
@@ -74,23 +81,16 @@ export default () => (

 ### 选择

-在 `Table.Content` 上设置 `selectionMode` 以启用行选择。全选与每行复选框可使用带 `slot="selection"` 的 `Checkbox`。
+在 `Table.Content` 上使用 `selectionMode` 启用行选择。使用 `slot="selection"` 的 `Checkbox` 实现全选与逐行勾选。

 <ComponentPreview
  name="table-selection"
  minHeight="380px"
 />

-### 自定义单元格
-
-<ComponentPreview
-  name="table-custom-cells"
-  minHeight="420px"
-/>
-
 ### 可展开行

-行可以嵌套以展示层级数据。使用 `treeColumn` 指定列，并在该列单元格内渲染带 `slot="chevron"` 的 `Button`，以便用户展开/收起行。使用 `expandedKeys` 控制哪些行处于展开状态。
+行可嵌套以展示层级数据。使用 `treeColumn` 指定列，并在该列单元格中渲染 `slot="chevron"` 的 `Button`，供用户展开/收起行。使用 `expandedKeys` 控制哪些行处于展开状态。

 <ComponentPreview
  name="table-expandable-rows"
@@ -108,7 +108,7 @@ export default () => (

 ### 列宽调整

-使用 `Table.ResizableContainer` 包裹表格，并在每个可调整宽度的列中加入 `Table.ColumnResizer`。
+将表格包裹在 `Table.ResizableContainer` 中，并在每个可调整宽度的列内添加 `Table.ColumnResizer`。

 <ComponentPreview
  name="table-column-resizing"
@@ -117,25 +117,16 @@ export default () => (

 ### 空状态

-在 `Table.Body` 上使用 `renderEmptyState`，在表格无数据时展示自定义内容。
+在 `Table.Body` 上使用 `renderEmptyState`，在表格无数据时展示自定义消息。

 <ComponentPreview
  name="table-empty-state"
  minHeight="300px"
 />

-### 异步加载
+### 虚拟滚动

-使用 `Table.LoadMore` 实现无限滚动：会渲染一行哨兵节点，在进入视口时触发 `onLoadMore`。
-
-<ComponentPreview
-  name="table-async-loading"
-  minHeight="380px"
-/>
-
-### 虚拟化
-
-Table 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见行，从而高效处理大数据集。
+Table 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见行，从而高效展示大数据集。

 <ComponentPreview
  name="table-virtualization"
@@ -144,49 +135,30 @@ Table 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚

 ### TanStack Table

-HeroUI 的 Table 可作为无头表格库之上的渲染层。
-本示例使用 [TanStack Table](https://tanstack.com/table) 处理列定义、排序与分页，而样式与无障碍由 HeroUI 负责。
+HeroUI 的 Table 作为无头表格库之上的渲染层。
+本示例使用 [TanStack Table](https://tanstack.com/table) 处理列定义、排序与分页，而 HeroUI 负责样式与无障碍。

 <ComponentPreview
  name="table-tanstack-table"
  minHeight="420px"
 />

-<RelatedComponents component="table" />
+### 自定义单元格

-## 样式
+<ComponentPreview
+  name="table-custom-cells"
+  minHeight="420px"
+/>

-### 传入 Tailwind CSS 类
+## 自定义样式

-你可以为 Table 的各个部分分别传入类名：
+### Tailwind CSS

-```tsx
-import { Table } from '@heroui/react';
+<ComponentPreview name="table-custom-styles" />

-function CustomTable() {
-  return (
-    <Table className="border border-purple-200">
-      <Table.ScrollContainer>
-        <Table.Content aria-label="Custom styled table">
-          <Table.Header className="bg-purple-50">
-            <Table.Column>Name</Table.Column>
-          </Table.Header>
-          <Table.Body>
-            <Table.Row className="hover:bg-purple-50">
-              <Table.Cell>Kate Moore</Table.Cell>
-            </Table.Row>
-          </Table.Body>
-        </Table.Content>
-      </Table.ScrollContainer>
-    </Table>
-  );
-}
-```
+### 全局 CSS

-### 自定义组件类
-
-若要自定义 Table 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -216,13 +188,15 @@ function CustomTable() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Table 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/table.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.table-root` - 根容器（命名为 `table-root` 而非 `table`，因为 `table` 是 Tailwind CSS 内置的 `display: table` 工具类）
 - `.table__scroll-container` - 横向滚动包裹层与自定义滚动条
 - `.table__content` - `<table>` 元素
@@ -233,7 +207,7 @@ Table 组件使用以下 CSS 类（[查看源码样式](https://github.com/herou
 - `.table__cell` - 数据单元格（`<td>`）
 - `.table__footer` - 表底容器（位于 table 外部）

-#### 进阶类
+#### 进阶类 [!toc]
 - `.table__column-resizer` - 列宽拖拽手柄
 - `.table__resizable-container` - 启用列宽调整的包裹层
 - `.table__load-more` - 无限滚动的哨兵行
@@ -241,7 +215,7 @@ Table 组件使用以下 CSS 类（[查看源码样式](https://github.com/herou
 - `.table__sortable-column-header` - 可排序列标签与指示器的包裹层
 - `.table__sortable-column-indicator` - 排序方向 chevron（通过 `[data-direction="descending"]` 翻转）

-#### 变体类
+#### 变体类 [!toc]
 - `.table-root--primary` - 灰色背景容器与卡片式表体（默认）
 - `.table-root--secondary` - 无背景，独立圆角表头

@@ -259,23 +233,20 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制

 ## API 参考

-### Table Props
-
+### Table
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。Primary 为灰色背景容器；Secondary 为扁平透明行。 |
 | `className` | `string` | - | 根容器的额外 CSS 类。 |
 | `children` | `React.ReactNode` | - | 表格内容（ScrollContainer、Footer 等）。 |

-### Table.ScrollContainer Props
-
+### Table.ScrollContainer
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类。 |
 | `children` | `React.ReactNode` | - | `Table.Content` 元素。 |

-### Table.Content Props
-
+### Table.Content
 继承自 [React Aria Table](https://react-spectrum.adobe.com/react-aria/Table.html)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -288,8 +259,7 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制
 | `onSortChange` | `(descriptor: SortDescriptor) => void` | - | 排序变化时的事件处理函数。 |
 | `className` | `string` | - | 额外的 CSS 类。 |

-### Table.Header Props
-
+### Table.Header
 继承自 [React Aria TableHeader](https://react-spectrum.adobe.com/react-aria/Table.html#tableheader)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -297,8 +267,7 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制
 | `columns` | `T[]` | - | 渲染函数模式下的动态列数据。 |
 | `children` | `React.ReactNode \| (column: T) => React.ReactNode` | - | 静态列或渲染函数。 |

-### Table.Column Props
-
+### Table.Column
 继承自 [React Aria Column](https://react-spectrum.adobe.com/react-aria/Table.html#column)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -310,8 +279,7 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制
 | `minWidth` | `number` | - | 可调整列的最小宽度。 |
 | `children` | `React.ReactNode \| (values: ColumnRenderProps) => React.ReactNode` | - | 列内容或带排序方向的渲染函数。 |

-### Table.Body Props
-
+### Table.Body
 继承自 [React Aria TableBody](https://react-spectrum.adobe.com/react-aria/Table.html#tablebody)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -320,8 +288,7 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制
 | `renderEmptyState` | `() => React.ReactNode` | - | 表格为空时展示的内容。 |
 | `children` | `React.ReactNode \| (item: T) => React.ReactNode` | - | 静态行或渲染函数。 |

-### Table.Row Props
-
+### Table.Row
 继承自 [React Aria Row](https://react-spectrum.adobe.com/react-aria/Table.html#row)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -330,8 +297,7 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制
 | `className` | `string` | - | 额外的 CSS 类。 |
 | `children` | `React.ReactNode` | - | 行单元格。 |

-### Table.Cell Props
-
+### Table.Cell
 继承自 [React Aria Cell](https://react-spectrum.adobe.com/react-aria/Table.html#cell)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -339,8 +305,7 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制
 | `className` | `string` | - | 额外的 CSS 类。 |
 | `children` | `React.ReactNode` | - | 单元格内容。 |

-### Table.SortableColumnHeader Props
-
+### Table.SortableColumnHeader
 渲染可排序列的标签与升序 / 降序指示器。请在 `Table.Column` 的渲染函数回调中使用，并将 `sortDirection` 透传进来。

 | Prop | 类型 | 默认值 | 描述 |
@@ -351,23 +316,20 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制
 | `className` | `string` | - | 包裹元素的额外 CSS 类。 |
 | `children` | `React.ReactNode` | - | 列标签内容。 |

-### Table.Footer Props
-
+### Table.Footer
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类。 |
 | `children` | `React.ReactNode` | - | 表底内容（例如分页）。 |

-### Table.ColumnResizer Props
-
+### Table.ColumnResizer
 继承自 [React Aria ColumnResizer](https://react-spectrum.adobe.com/react-aria/Table.html#columnresizer)。

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类。 |

-### Table.ResizableContainer Props
-
+### Table.ResizableContainer
 继承自 [React Aria ResizableTableContainer](https://react-spectrum.adobe.com/react-aria/Table.html#resizabletablecontainer)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -375,8 +337,7 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制
 | `className` | `string` | - | 额外的 CSS 类。 |
 | `children` | `React.ReactNode` | - | `Table.Content` 元素。 |

-### Table.LoadMore Props
-
+### Table.LoadMore
 继承自 [React Aria TableLoadMoreItem](https://react-spectrum.adobe.com/react-aria/Table.html)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -385,15 +346,13 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制
 | `onLoadMore` | `() => void` | - | 哨兵行可见时的事件处理函数。 |
 | `children` | `React.ReactNode` | - | 加载指示器内容。 |

-### Table.LoadMoreContent Props
-
+### Table.LoadMoreContent
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类。 |
 | `children` | `React.ReactNode` | - | 加载指示器内容（例如 Spinner）。 |

-### Table.Collection Props
-
+### Table.Collection
 由 React Aria `Collection` 重新导出。用于在行内与静态单元格并存时渲染动态单元格（例如复选框）。

 | Prop | 类型 | 默认值 | 描述 |
@@ -414,3 +373,7 @@ Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制
 | `dropIndicatorThickness` | `number \| undefined` | 2 | 放置指示器的线条粗细。 |
 | `gap` | `number \| undefined` | 0 | 条目之间的间距。 |
 | `padding` | `number \| undefined` | 0 | 列表的内边距。 |
+
+## 相关组件
+
+<RelatedComponents component="table" />
@@ -1,6 +1,6 @@
 ---
 title: Calendar 日历
-description: 基于 React Aria Calendar 的可组合日期选择器，包含月份网格、导航与年份选择器支持。
+description: 基于 React Aria Calendar 的可组合日期选择器，支持月网格、导航与年份选择
 icon: updated
 links:
  rac: Calendar
@@ -9,17 +9,15 @@ links:
  storybook: Components/Date and Time/Calendar
 ---

-## 引入
+## 用法

 ```tsx
 import { Calendar } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="calendar-basic" />

-### 组件结构
+## 组件结构

 ```tsx
 import {Calendar} from '@heroui/react';
@@ -43,55 +41,7 @@ export default () => (
 )
 ```

-### 年份选择器
-
-`Calendar.YearPickerTrigger`、`Calendar.YearPickerGrid` 以及对应的 body/cell 子组件提供一体化的年份导航模式。
-
-<ComponentPreview name="calendar-year-picker" />
-
-### 默认值
-
-<ComponentPreview name="calendar-default-value" />
-
-### 受控
-
-使用受控的 `value` 与 `focusedValue` 与外部状态协同，并支持自定义快捷键。
-
-<ComponentPreview name="calendar-controlled" />
-
-### 最小与最大日期
-
-<ComponentPreview name="calendar-min-max-dates" />
-
-### 不可用日期
-
-使用 `isDateUnavailable` 禁用周末、节假日或已被预订等日期。
-
-<ComponentPreview name="calendar-unavailable-dates" />
-
-### 固定周数
-
-将 `weeksInMonth` 设为固定值（例如 `6`），可在月份切换时保持网格高度稳定。在非公历场景中请谨慎使用，与 `firstDayOfWeek` 类似。
-
-<ComponentPreview name="calendar-weeks-in-month" />
-
-### 周视图
-
-设置 `visibleDuration={{ weeks: n }}` 可一次显示一个或多个周。翻页会按可见周范围前进。显示多周时可配合 `pageBehavior="single"` 每次仅移动一周。
-
-<ComponentPreview name="calendar-week-view" />
-
-### 日视图
-
-设置 `visibleDuration={{ days: n }}` 可显示连续多天的滚动窗口。翻页会按可见天数范围前进。显示多天时配合 `pageBehavior="single"` 可每次仅移动一天。
-
-<ComponentPreview name="calendar-day-view" />
-
-### 多选
-
-设置 `selectionMode="multiple"` 以选择多个日期。此时 `value`、`defaultValue` 与 `onChange` 使用日期数组。
-
-<ComponentPreview name="calendar-multiple-selection" />
+## 示例

 ### 禁用

@@ -101,79 +51,101 @@ export default () => (

 <ComponentPreview name="calendar-read-only" />

-### 焦点值
+### 默认值

-使用 `focusedValue` 与 `onFocusChange` 以编程方式控制焦点落在哪一天。
+<ComponentPreview name="calendar-default-value" />
+
+### 年份选择
+
+`Calendar.YearPickerTrigger`、`Calendar.YearPickerGrid` 及其 body/cell 子组件提供集成的年份导航模式。
+
+<ComponentPreview name="calendar-year-picker" />
+
+### 受控组件
+
+使用受控的 `value` 与 `focusedValue` 进行外部状态协调与自定义快捷操作。
+
+<ComponentPreview name="calendar-controlled" />
+
+### 日期范围限制
+
+<ComponentPreview name="calendar-min-max-dates" />
+
+### 不可用日期
+
+使用 `isDateUnavailable` 阻止周末、节假日或已预订时段等日期。
+
+<ComponentPreview name="calendar-unavailable-dates" />
+
+### 月份周数
+
+将 `weeksInMonth` 设为固定值（如 `6`）可在月份切换时保持网格高度稳定。在非公历 locale 中请谨慎使用，类似 `firstDayOfWeek`。
+
+<ComponentPreview name="calendar-weeks-in-month" />
+
+### 周视图
+
+设置 `visibleDuration={{ weeks: n }}` 可一次显示一周或多周。导航按可见周范围前进。显示多周时使用 `pageBehavior="single"` 可每次移动一周。
+
+<ComponentPreview name="calendar-week-view" />
+
+### 日视图
+
+设置 `visibleDuration={{ days: n }}` 可显示连续日期的滚动窗口。导航按可见日范围前进。显示多天时使用 `pageBehavior="single"` 可每次移动一天。
+
+<ComponentPreview name="calendar-day-view" />
+
+### 多选
+
+设置 `selectionMode="multiple"` 允许选择多个日期。`value`、`defaultValue` 与 `onChange` 使用日期数组。
+
+<ComponentPreview name="calendar-multiple-selection" />
+
+### 聚焦值
+
+使用 `focusedValue` 与 `onFocusChange` 以编程方式控制聚焦日期。

 <ComponentPreview name="calendar-focused-value" />

-### 单元格指示器
+### 单元格标记

-你可以自定义 `Calendar.Cell` 的子节点，并使用 `Calendar.CellIndicator` 展示活动等元数据。
+可自定义 `Calendar.Cell` 子节点，并使用 `Calendar.CellIndicator` 显示事件等元数据。

 <ComponentPreview name="calendar-with-indicators" />

-### 多个月份
-
-使用 `visibleDuration` 与 `offset` 渲染多个月份网格，适用于预订与规划场景。在各列头部为 `Calendar.Heading` 设置 `offset`（例如 `offset={{ months: 1 }}`）以显示对应月份标题。
-
-<ComponentPreview name="calendar-multiple-months" />
-
-### 国际化日历
-
-默认情况下，Calendar 使用用户语言环境对应的历法系统显示日期。你可以使用 `I18nProvider` 包裹 Calendar，并通过 [Unicode 历法语言扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。
-
-下方示例展示印度历法系统：
-
-<ComponentPreview name="calendar-international-calendar" />
-
-**提示：** `onChange` 事件始终返回与 `value` 或 `defaultValue` 相同历法系统中的日期（若未提供值则为公历），与界面展示的语言环境无关。这样应用逻辑可以始终使用单一历法系统，同时仍可按用户偏好的格式展示日期。
-
 ### 自定义导航图标

-向 `Calendar.NavButton` 传入子节点即可替换默认的箭头图标。
+向 `Calendar.NavButton` 传入子节点以替换默认 chevron 图标。

 <ComponentPreview name="calendar-custom-icons" />

-### 真实场景示例
+### 多月份展示
+
+使用 `visibleDuration` 与 `offset` 渲染多个月份网格，适用于预订与规划场景。
+
+<ComponentPreview name="calendar-multiple-months" />
+
+### 典型场景

 <ComponentPreview name="calendar-booking-calendar" />

-### 自定义样式
+### 国际化日历
+
+默认情况下，Calendar 使用用户 locale 的历法系统显示日期。可用 `I18nProvider` 包裹 Calendar 并设置 [Unicode 历法 locale 扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 来覆盖。
+
+以下示例展示印度历法系统：
+
+<ComponentPreview name="calendar-international-calendar" />
+
+**Note:** `onChange` 事件始终返回与 `value` 或 `defaultValue` 相同历法系统的日期（未提供 value 时为公历），无论显示 locale 如何。这确保应用逻辑在单一历法系统下一致运行，同时仍以用户偏好的格式显示日期。
+
+## 自定义样式
+
+### Tailwind CSS

 <ComponentPreview name="calendar-custom-styles" />

-<RelatedComponents component="calendar" />
-
-## 样式
-
-### 传入 Tailwind CSS 类
-
-```tsx
-import {Calendar} from '@heroui/react';
-
-function CustomCalendar() {
-  return (
-    <Calendar aria-label="Custom calendar" className="w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm">
-      <Calendar.Header className="pb-3">
-        <Calendar.Heading className="text-default" />
-        <Calendar.NavButton slot="previous" className="text-default" />
-        <Calendar.NavButton slot="next" className="text-default" />
-      </Calendar.Header>
-      <Calendar.Grid>
-        <Calendar.GridHeader>
-          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
-        </Calendar.GridHeader>
-        <Calendar.GridBody>
-          {(date) => <Calendar.Cell date={date} />}
-        </Calendar.GridBody>
-      </Calendar.Grid>
-    </Calendar>
-  );
-}
-```
-
-### 自定义组件类
+### 全局 CSS

 ```css
@layer components {
@@ -191,116 +163,123 @@ function CustomCalendar() {
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

 Calendar 在 `packages/styles/components/calendar.css` 与 `packages/styles/components/calendar-year-picker.css` 中使用以下类：

- `.calendar` - 根容器。
- `.calendar__header` - 包含导航按钮与标题的头部行。
- `.calendar__heading` - 当前月份标签。
- `.calendar__nav-button` - 上一月/下一月导航控件。
- `.calendar__grid` - 主体日期网格。
- `.calendar__grid-header` - 星期标题行容器。
- `.calendar__grid-body` - 日期行容器。
- `.calendar__header-cell` - 星期标题单元格。
- `.calendar__cell` - 可交互的日期单元格。
- `.calendar__cell-indicator` - 日期单元格内的点状指示器。
- `.calendar-year-picker__trigger` - 年份选择器切换按钮。
- `.calendar-year-picker__trigger-heading` - 年份选择触发器内的标题文本。
- `.calendar-year-picker__trigger-indicator` - 年份选择触发器内的指示图标。
- `.calendar-year-picker__year-grid` - 可选年份的覆盖网格。
- `.calendar-year-picker__year-cell` - 单个年份选项。
+- `.calendar` - 根容器
+- `.calendar__header` - 包含导航按钮与标题的头部行
+- `.calendar__heading` - 当前月份标签
+- `.calendar__nav-button` - 上/下月导航控件
+- `.calendar__grid` - 主日期网格
+- `.calendar__grid-header` - 星期标题行包装器
+- `.calendar__grid-body` - 日期行包装器
+- `.calendar__header-cell` - 星期标题单元格
+- `.calendar__cell` - 可交互的日期单元格
+- `.calendar__cell-indicator` - 日期单元格内的点指示器
+- `.calendar-year-picker__trigger` - 年份选择器切换按钮
+- `.calendar-year-picker__trigger-heading` - 年份选择器触发器内的标题文本
+- `.calendar-year-picker__trigger-indicator` - 年份选择器触发器内的指示图标
+- `.calendar-year-picker__year-grid` - 可选年份的覆盖网格
+- `.calendar-year-picker__year-cell` - 单个年份选项

 ### 交互状态

-Calendar 同时支持伪类与 React Aria 的 data 属性：
+Calendar 同时支持伪类与 React Aria data 属性：

- **已选中**：`[data-selected="true"]`
- **今天**：`[data-today="true"]`
- **不可用**：`[data-unavailable="true"]`
- **跨月**：`[data-outside-month="true"]`
- **悬停**：`:hover` 或 `[data-hovered="true"]`
- **按下**：`:active` 或 `[data-pressed="true"]`
- **可见焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`
- **禁用**：`:disabled` 或 `[data-disabled="true"]`
+- **Selected**：`[data-selected="true"]`
+- **Today**：`[data-today="true"]`
+- **Unavailable**：`[data-unavailable="true"]`
+- **Outside month**：`[data-outside-month="true"]`
+- **Hovered**：`:hover` 或 `[data-hovered="true"]`
+- **Pressed**：`:active` 或 `[data-pressed="true"]`
+- **Focus visible**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **Disabled**：`:disabled` 或 `[data-disabled="true"]`

 ## API 参考

-### Calendar Props
+### Calendar

-Calendar 继承 React Aria [Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html) 的全部 props。
+Calendar 继承 React Aria [Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html) 的所有属性。

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `selectionMode` | `'single' \| 'multiple'` | `'single'` | 单选或多选日期。 |
-| `value` | `DateValue \| null` 或 `DateValue[] \| null` | - | 受控的选中日期。`selectionMode="multiple"` 时使用数组。 |
-| `defaultValue` | `DateValue \| null` 或 `DateValue[] \| null` | - | 初始选中日期（非受控）。 |
-| `onChange` | `(value: DateValue \| null)` 或 `(value: DateValue[] \| null) => void` | - | 选中变化时调用。 |
-| `focusedValue` | `DateValue` | - | 受控的焦点日期。 |
-| `onFocusChange` | `(value: DateValue) => void` | - | 焦点移动到其它日期时调用。 |
-| `minValue` | `DateValue` | 历法感知的 `1900-01-01` | 最早可选日期。 |
-| `maxValue` | `DateValue` | 历法感知的 `2099-12-31` | 最晚可选日期。 |
-| `weeksInMonth` | `number` | - | 一个月的周数。该值会覆盖区域设置的默认值。 |
-| `isDateUnavailable` | `(date: DateValue) => boolean` | - | 将日期标记为不可用。 |
-| `firstDayOfWeek` | `'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` | - | 覆盖区域设置的一周起始日。 |
-| `pageBehavior` | `'visible' \| 'single'` | `'visible'` | 翻页按可见范围或单步前进。 |
-| `selectionAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | 初始渲染时按选中项对齐可见范围。 |
-| `isDisabled` | `boolean` | `false` | 禁用交互与选择。 |
-| `isReadOnly` | `boolean` | `false` | 内容只读，无法更改选中。 |
-| `isInvalid` | `boolean` | `false` | 将日历标记为无效以配合校验 UI。 |
-| `visibleDuration` | `{months?: number; weeks?: number; days?: number}` | `{months: 1}` | 可见时间范围。使用 `{ months: n }` 为月视图，`{ weeks: n }` 为周视图，`{ days: n }` 为日视图。 |
-| `defaultYearPickerOpen` | `boolean` | `false` | 内置年份选择器的初始展开状态。 |
-| `isYearPickerOpen` | `boolean` | - | 受控的年份选择器展开状态。 |
-| `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | 年份选择器展开状态变化时调用。 |
+| `selectionMode` | `'single' \| 'multiple'` | `'single'` | 是否可选择单个或多个日期 |
+| `value` | `DateValue \| null` 或 `DateValue[] \| null` | - | 受控选中日期。`selectionMode` 为 `multiple` 时使用数组 |
+| `defaultValue` | `DateValue \| null` 或 `DateValue[] \| null` | - | 初始选中日期（非受控） |
+| `onChange` | `(value: DateValue \| null)` 或 `(value: DateValue[] \| null) => void` | - | 选择变化时调用 |
+| `focusedValue` | `DateValue` | - | 受控聚焦日期 |
+| `onFocusChange` | `(value: DateValue) => void` | - | 焦点移至其他日期时调用 |
+| `minValue` | `DateValue` | 历法感知的 `1900-01-01` | 最早可选日期 |
+| `maxValue` | `DateValue` | 历法感知的 `2099-12-31` | 最晚可选日期 |
+| `weeksInMonth` | `number` | - | 月份中的周数，覆盖 locale 默认值 |
+| `isDateUnavailable` | `(date: DateValue) => boolean` | - | 标记日期为不可用 |
+| `firstDayOfWeek` | `'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` | - | 覆盖 locale 默认的一周起始日 |
+| `pageBehavior` | `'visible' \| 'single'` | `'visible'` | 翻页按可见时长还是单个单位前进 |
+| `selectionAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | 初始渲染时可见范围与选择的对齐方式 |
+| `isDisabled` | `boolean` | `false` | 禁用交互与选择 |
+| `isReadOnly` | `boolean` | `false` | 内容可读但不可更改选择 |
+| `isInvalid` | `boolean` | `false` | 标记日历为无效以显示验证 UI |
+| `visibleDuration` | `{months?: number; weeks?: number; days?: number}` | `{months: 1}` | 可见时间范围。月视图用 `{ months: n }`，周视图用 `{ weeks: n }`，日视图用 `{ days: n }` |
+| `defaultYearPickerOpen` | `boolean` | `false` | 内部年份选择器初始打开状态 |
+| `isYearPickerOpen` | `boolean` | - | 受控年份选择器打开状态 |
+| `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | 年份选择器打开状态变化时调用 |

-### 组合部件
+### Composition Parts

-| Component | 描述 |
-|-----------|------|
-| `Calendar.Header` | 导航与标题的头部容器。 |
-| `Calendar.Heading` | 可见范围的格式化标题。支持 `offset`（多月份布局）与 `format`（月/年/日格式选项）。 |
-| `Calendar.NavButton` | 上一月/下一月导航控件（`slot="previous"` 或 `slot="next"`）。 |
-| `Calendar.Grid` | 单个月的日期网格（多月份布局支持 `offset`）。 |
-| `Calendar.GridHeader` | 星期标题容器。 |
-| `Calendar.GridBody` | 日期单元格主体容器。 |
-| `Calendar.HeaderCell` | 星期标签单元格。 |
-| `Calendar.Cell` | 单个日期单元格。 |
-| `Calendar.CellIndicator` | 用于自定义元数据的可选指示元素。 |
-| `Calendar.YearPickerTrigger` | 切换年份选择模式的触发器。 |
-| `Calendar.YearPickerTriggerHeading` | 年份选择触发器内的本地化标题内容。 |
-| `Calendar.YearPickerTriggerIndicator` | 年份选择触发器内的切换图标。 |
-| `Calendar.YearPickerGrid` | 年份选择覆盖网格容器。 |
-| `Calendar.YearPickerGridBody` | 年份网格单元格的 body 渲染器。 |
-| `Calendar.YearPickerCell` | 单个年份选项单元格。 |
+| Component | Description |
+|-----------|-------------|
+| `Calendar.Header` | 导航与标题的头部容器 |
+| `Calendar.Heading` | 可见范围的格式化标题。支持 `offset`（多月布局）与 `format`（月/年/日选项） |
+| `Calendar.NavButton` | 上/下月导航控件（`slot="previous"` 或 `slot="next"`） |
+| `Calendar.Grid` | 单个月份的日期网格（多月布局支持 `offset`） |
+| `Calendar.GridHeader` | 星期标题容器 |
+| `Calendar.GridBody` | 日期单元格 body 容器 |
+| `Calendar.HeaderCell` | 星期标签单元格 |
+| `Calendar.Cell` | 单个日期单元格 |
+| `Calendar.CellIndicator` | 自定义元数据的可选指示元素 |
+| `Calendar.YearPickerTrigger` | 切换年份选择器模式的触发器 |
+| `Calendar.YearPickerTriggerHeading` | 年份选择器触发器内的本地化标题内容 |
+| `Calendar.YearPickerTriggerIndicator` | 年份选择器触发器内的切换图标 |
+| `Calendar.YearPickerGrid` | 覆盖式年份选择网格容器 |
+| `Calendar.YearPickerGridBody` | 年份网格单元格的 body 渲染器 |
+| `Calendar.YearPickerCell` | 单个年份选项单元格 |

-### 年份选择器子组件
+### Year Picker Parts

 年份选择器子组件继承 React Aria [`useCalendarHeading`](https://react-aria.adobe.com/useCalendar#usecalendarheading) 与 [`useCalendarYearPicker`](https://react-aria.adobe.com/useCalendar#usecalendaryearpicker) 的格式化属性。

-| 组件 | 属性 | 类型 | 默认值 | 描述 |
-|------|------|------|--------|------|
-| `Calendar.YearPickerTriggerHeading` | `format` | `DateFormatterOptions` | - | 自定义月/年标题（如 `{month: 'short'}`）。 |
-| `Calendar.YearPickerTriggerHeading` | `offset` | `{months?: number}` | - | 相对聚焦日期偏移标题（多月布局）。 |
-| `Calendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | 自定义年份单元格标签（纪元、历法系统等）。 |
-| `Calendar.YearPickerGrid` | `visibleYears` | `number` | min–max 跨度或 `20` | 滑动窗口中显示的年份数量。当同时设置 `minValue` 与 `maxValue` 时，默认为二者之间的完整范围。 |
+| Component | Prop | 类型 | 默认值 | 描述 |
+|-----------|------|------|--------|------|
+| `Calendar.YearPickerTriggerHeading` | `format` | `DateFormatterOptions` | - | 自定义月/年标签（如 `{month: 'short'}`） |
+| `Calendar.YearPickerTriggerHeading` | `offset` | `{months?: number}` | - | 相对聚焦日期偏移标题（多月布局） |
+| `Calendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | 自定义年份单元格标签（纪元、历法等） |
+| `Calendar.YearPickerGrid` | `visibleYears` | `number` | min–max 跨度或 `20` | 滑动窗口中显示的年份数。同时设置 `minValue` 与 `maxValue` 时默认为完整范围 |

-### Calendar.Cell Render Props
-
-当 `Calendar.Cell` 的 `children` 为函数时，可使用 React Aria 的渲染参数：
+### Calendar.Cell Render
+`Calendar.Cell` 子节点为函数时，可使用 React Aria render props：

 | Prop | 类型 | 描述 |
 |------|------|------|
-| `formattedDate` | `string` | 单元格日期的本地化标签。 |
-| `isSelected` | `boolean` | 该日期是否被选中。 |
-| `isUnavailable` | `boolean` | 该日期是否不可用。 |
-| `isDisabled` | `boolean` | 单元格是否禁用。 |
-| `isOutsideMonth` | `boolean` | 是否属于相邻月份。 |
+| `formattedDate` | `string` | 单元格的本地化日期标签 |
+| `isSelected` | `boolean` | 日期是否选中 |
+| `isUnavailable` | `boolean` | 日期是否不可用 |
+| `isDisabled` | `boolean` | 单元格是否禁用 |
+| `isOutsideMonth` | `boolean` | 日期是否属于相邻月份 |

-支持的历法系统及其标识符完整列表见：
+有关支持的历法系统及其标识符的完整列表，请参阅：
 - [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
 - [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)

 ### Related packages
- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 各日期组件共用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具函数
- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖语言环境
- [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前语言环境与书写方向
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 所有日期组件使用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 覆盖子树的 locale
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前 locale 与布局方向
+
+## 相关组件
+
+<RelatedComponents component="calendar" />
@@ -1,6 +1,6 @@
 ---
 title: DateField 日期字段
-description: 基于 React Aria DateField 的日期输入字段，包含标签、说明与校验。
+description: 基于 React Aria DateField 的日期输入字段，包含标签、说明与校验
 links:
  rac: DateField
  source: date-field/date-field.tsx
@@ -8,17 +8,15 @@ links:
  storybook: Components/Date and Time/DateField
 ---

-## 引入
+## 用法

 ```tsx
 import { DateField } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="date-field-basic" />

-### 组件结构
+## 组件结构

 ```tsx
 import {DateField, Label, Description, FieldError} from '@heroui/react';
@@ -39,39 +37,7 @@ export default () => (

 > **DateField** 将标签、日期输入、说明与错误信息组合为单个无障碍组件。

-### 带描述
-
-<ComponentPreview name="date-field-with-description" />
-
-### 必填字段
-
-<ComponentPreview name="date-field-required" />
-
-### 校验
-
-配合 `FieldError`，使用 `isInvalid` 展示校验信息。
-
-<ComponentPreview name="date-field-invalid" />
-
-### 带校验
-
-DateField 支持使用 `minValue`、`maxValue` 及自定义校验逻辑。
-
-<ComponentPreview name="date-field-with-validation" />
-
-### 粒度
-
-<ComponentPreview name="date-field-granularity" />
-
-### 受控
-
-通过受控 `value` 与其它组件或状态管理同步。
-
-<ComponentPreview name="date-field-controlled" />
-
-### 禁用状态
-
-<ComponentPreview name="date-field-disabled" />
+## 示例

 ### 带图标

@@ -83,68 +49,80 @@ DateField 支持使用 `minValue`、`maxValue` 及自定义校验逻辑。

 <ComponentPreview name="date-field-with-prefix-and-suffix" />

-### 全宽
-
-<ComponentPreview name="date-field-full-width" />
-
 ### 变体

-`DateField.Group` 提供两种视觉变体：
+DateField.Group 组件支持两种视觉变体：

- **`primary`**（默认）：带阴影的标准样式，适用于大多数场景
- **`secondary`**：低强调、无阴影，适合放在 Surface 等表面背景上
+- **`primary`**（默认）- 标准样式带阴影，适用于大多数场景
+- **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内

 <ComponentPreview name="date-field-variants" />

-### 在 Surface 中
+### 表面样式

-在 [Surface](/docs/components/surface) 内使用时，请在 `DateField.Group` 上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+在 [Surface](/docs/components/surface) 内使用时，请在 DateField.Group 上使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。

 <ComponentPreview name="date-field-on-surface" />

+### 带描述
+
+<ComponentPreview name="date-field-with-description" />
+
+### 必填字段
+
+<ComponentPreview name="date-field-required" />
+
+### 禁用
+
+<ComponentPreview name="date-field-disabled" />
+
+### 宽度充满
+
+<ComponentPreview name="date-field-full-width" />
+
+### 表单校验
+
+配合 `FieldError` 使用 `isInvalid` 展示校验消息。
+
+<ComponentPreview name="date-field-invalid" />
+
+### 时间粒度
+
+<ComponentPreview name="date-field-granularity" />
+
+### 受控组件
+
+控制 value 以与其他组件或状态管理同步。
+
+<ComponentPreview name="date-field-controlled" />
+
 ### 表单示例

 包含校验与提交的完整表单示例。

 <ComponentPreview name="date-field-form-example" />

-<RelatedComponents component="datefield" />
+### 带校验

-### 自定义渲染函数
+DateField 支持 `minValue`、`maxValue` 与自定义校验逻辑。
+
+<ComponentPreview name="date-field-with-validation" />
+
+### 渲染函数

 <ComponentPreview
-  name="date-field-custom-render-function"
+  name="date-field-render-function"
 />

-## 样式
+## 自定义样式

-### 传入 Tailwind CSS 类
+### Tailwind CSS

-```tsx
-import {DateField, Label, Description} from '@heroui/react';
+<ComponentPreview name="date-field-custom-styles" />

-function CustomDateField() {
-  return (
-    <DateField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
-      <Label className="text-sm font-semibold text-default-700">
-        Appointment date
-      </Label>
-      <DateField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
-        <DateField.Input>
-          {(segment) => <DateField.Segment segment={segment} />}
-        </DateField.Input>
-      </DateField.Group>
-      <Description className="text-xs text-default-500">
-        Select a date for your appointment.
-      </Description>
-    </DateField>
-  );
-}
-```
+### 全局 CSS

-### 自定义组件类
-
-DateField 的默认样式很轻量。覆盖 `.date-field` 类即可自定义容器样式。
+DateField 默认样式较轻量。覆盖 `.date-field` 类可自定义容器样式。

 ```css
@layer components {
@@ -169,24 +147,28 @@ DateField 的默认样式很轻量。覆盖 `.date-field` 类即可自定义容
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

 - `.date-field` – 轻量样式的根容器（`flex flex-col gap-1`）

-> **说明：** 子组件（[Label](/docs/components/label)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参阅对应文档。`DateField.Group` 的样式见下文 API 参考。
+> **Note：** 子组件（[Label](/docs/components/label)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参阅对应文档。DateField.Group 样式见下文 API 参考。

 ### 交互状态

 DateField 会根据状态自动设置以下 data 属性：

- **无效**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` – 无效时自动隐藏 description 插槽
- **必填**：`[data-required="true"]` – 当 `isRequired` 为 true 时添加
- **禁用**：`[data-disabled="true"]` – 当 `isDisabled` 为 true 时添加
- **焦点在内**：`[data-focus-within="true"]` – 任一子输入聚焦时添加
+- **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` - 无效时自动隐藏 description slot
+- **Required**：`[data-required="true"]` - 当 `isRequired` 为 true 时应用
+- **Disabled**：`[data-disabled="true"]` - 当 `isDisabled` 为 true 时应用
+- **Focus Within**：`[data-focus-within="true"]` - 任一子输入聚焦时应用

 ## API 参考

-### DateField Props
+### DateField

 DateField 继承 React Aria [DateField](https://react-aria.adobe.com/DateField.md) 的全部 props。

@@ -255,7 +237,7 @@ DateField 继承 React Aria [DateField](https://react-aria.adobe.com/DateField.m
 | `aria-describedby` | `string` | - | 描述该字段的元素 id。 |
 | `aria-details` | `string` | - | 包含额外详情的元素 id。 |

-### 组合组件
+### Composition Components

 DateField 与以下独立组件配合使用，请分别导入并直接使用：

@@ -292,7 +274,7 @@ import {DateField, Label, Description, FieldError} from '@heroui/react';
 </DateField>
 ```

-### DateValue 类型
+### DateValue Types

 DateField 使用 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 中的类型：

@@ -320,7 +302,7 @@ const todayDate = today(getLocalTimeZone());

 > **说明：** DateField 依赖 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 进行解析、运算与类型定义。更多类型与函数见 [Internationalized Date 文档](https://react-aria.adobe.com/internationalized/date/)。

-### DateFieldRenderProps
+### Render Props

 对 `className`、`style` 或 `children` 使用渲染 prop 时，可使用以下值：

@@ -334,7 +316,7 @@ const todayDate = today(getLocalTimeZone());
 | `isFocusWithin` | `boolean` | 是否有子元素聚焦。 |
 | `isFocusVisible` | `boolean` | 焦点是否可见（键盘导航）。 |

-### DateField.Group Props
+### DateField.Group

 DateField.Group 继承 React Aria `Group` 的全部 props，并额外支持：

@@ -344,7 +326,7 @@ DateField.Group 继承 React Aria `Group` 的全部 props，并额外支持：
 | `fullWidth` | `boolean` | `false` | 日期输入组是否占满容器宽度。 |
 | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 |

-### DateField.Input Props
+### DateField.Input

 DateField.Input 继承 React Aria `DateInput` 的全部 props，并额外支持：

@@ -355,7 +337,7 @@ DateField.Input 继承 React Aria `DateInput` 的全部 props，并额外支持

 `DateField.Input` 接受渲染函数作为子节点，函数参数为日期段位；每个段位对应日期的一部分（年、月、日等）。

-### DateField.Segment Props
+### DateField.Segment

 DateField.Segment 继承 React Aria `DateSegment` 的全部 props：

@@ -364,7 +346,7 @@ DateField.Segment 继承 React Aria `DateSegment` 的全部 props：
 | `segment` | `DateSegment` | - | 来自 DateField.Input 渲染函数的 `DateSegment` 对象。 |
 | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |

-### DateField.InputContainer Props
+### DateField.InputContainer

 DateField.InputContainer 接受标准 HTML `div` 属性：

@@ -373,7 +355,7 @@ DateField.InputContainer 接受标准 HTML `div` 属性：
 | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
 | `children` | `ReactNode` | - | 滚动容器中的内容（通常为多个 `DateField.Input`）。 |

-### DateField.Prefix Props
+### DateField.Prefix

 DateField.Prefix 接受标准 HTML `div` 属性：

@@ -382,7 +364,7 @@ DateField.Prefix 接受标准 HTML `div` 属性：
 | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
 | `children` | `ReactNode` | - | 前缀插槽中要显示的内容。 |

-### DateField.Suffix Props
+### DateField.Suffix

 DateField.Suffix 接受标准 HTML `div` 属性：

@@ -391,9 +373,9 @@ DateField.Suffix 接受标准 HTML `div` 属性：
 | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
 | `children` | `ReactNode` | - | 后缀插槽中要显示的内容。 |

-## DateField.Group 样式
+## DateField.Group Styling

-### 自定义组件类
+### Customizing the component classes

 基础类作用于所有实例，可通过 `@layer components` 一次性覆盖。

@@ -449,7 +431,7 @@ DateField.Suffix 接受标准 HTML `div` 属性：
 }
 ```

-### DateField.Group CSS 类
+### DateField.Group CSS Classes

 - `.date-input-group` – 根容器样式
 - `.date-input-group__input` – 输入包裹层样式
@@ -458,11 +440,15 @@ DateField.Suffix 接受标准 HTML `div` 属性：
 - `.date-input-group__prefix` – 前缀元素样式
 - `.date-input-group__suffix` – 后缀元素样式

-### DateField.Group 交互状态
+### DateField.Group Interactive States

- **悬停**：`:hover` 或 `[data-hovered="true"]`
- **焦点在内**：`[data-focus-within="true"]` 或 `:focus-within`
- **无效**：`[data-invalid="true"]`（同时与 `aria-invalid` 同步）
- **禁用**：`[data-disabled="true"]` 或 `[aria-disabled="true"]`
- **段位聚焦**：段位上的 `:focus` 或 `[data-focused="true"]`
- **段位占位符**：段位上的 `[data-placeholder="true"]`
+- **Hover**：`:hover` 或 `[data-hovered="true"]`
+- **Focus Within**：`[data-focus-within="true"]` 或 `:focus-within`
+- **Invalid**：`[data-invalid="true"]`（与 `aria-invalid` 同步）
+- **Disabled**：`[data-disabled="true"]` 或 `[aria-disabled="true"]`
+- **Segment Focus**：段位上 `:focus` 或 `[data-focused="true"]`
+- **Segment Placeholder**：段位上 `[data-placeholder="true"]`
+
+## 相关组件
+
+<RelatedComponents component="datefield" />
@@ -1,6 +1,6 @@
 ---
 title: DatePicker 日期选择器
-description: 可组合的日期选择器，基于 React Aria DatePicker，通过 DateField 与 Calendar 组合实现。
+description: 基于 React Aria DatePicker，通过 DateField 与 Calendar 组合的可组合日期选择器
 links:
  rac: DatePicker
  source: date-picker/date-picker.tsx
@@ -9,19 +9,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { DatePicker, DateField, Calendar, Label } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="date-picker-basic" />

-### 组件结构
+## 组件结构

-`DatePicker` 采用组合优先的 API。请显式组合 `DateField` 与 `Calendar`，以便完全控制结构与样式。
+`DatePicker` 采用组合优先 API。显式组合 `DateField` 与 `Calendar` 以控制结构与样式。

 ```tsx
 import {Calendar, DateField, DatePicker, Label} from '@heroui/react';
@@ -61,93 +59,65 @@ export default () => (
 )
 ```

-### 受控
-
-<ComponentPreview name="date-picker-controlled" />
-
-### 校验
-
-<ComponentPreview name="date-picker-with-validation" />
-
-### 格式选项
-
-使用 `granularity`、`hourCycle`、`hideTimeZone`、`shouldForceLeadingZeros` 等 props 控制 DatePicker 值的展示方式。
-
-<ComponentPreview name="date-picker-format-options" />
+## 示例

 ### 禁用

 <ComponentPreview name="date-picker-disabled" />

-### 自定义指示器
+### 受控组件

-未提供子节点时，`DatePicker.TriggerIndicator` 会渲染默认的 `IconCalendar`。传入子节点即可替换。
+<ComponentPreview name="date-picker-controlled" />

-<ComponentPreview name="date-picker-with-custom-indicator" />
+### 表单校验
+
+<ComponentPreview name="date-picker-with-validation" />
+
+### 格式选项
+
+使用 `granularity`、`hourCycle`、`hideTimeZone`、`shouldForceLeadingZeros` 等 props 控制 DatePicker 值的显示方式。
+
+<ComponentPreview name="date-picker-format-options" />

 ### 表单示例

 <ComponentPreview name="date-picker-form-example" />

-### 国际化历法
+### 自定义指示器

-默认情况下，DatePicker 会使用用户语言环境对应的历法显示日期。你可以使用 `I18nProvider` 包裹 DatePicker，并通过 [Unicode 历法语言扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。
+未提供 children 时，`DatePicker.TriggerIndicator` 渲染默认 `IconCalendar`。传入 children 可替换。

-下方示例展示印度历法系统：
+<ComponentPreview name="date-picker-with-custom-indicator" />
+
+### 渲染函数
+
+<ComponentPreview
+  name="date-picker-render-function"
+/>
+
+### 国际化日历
+
+默认情况下，DatePicker 使用用户 locale 的日历系统显示日期。可用 `I18nProvider` 包裹并设置 [Unicode 日历 locale 扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。
+
+以下示例展示印度日历系统：

 <ComponentPreview name="date-picker-international-calendar" />

-**说明：** `onChange` 事件返回的日期始终与 `value` 或 `defaultValue` 使用同一历法系统（未提供值时为公历），与界面展示的本地化格式无关。这能确保应用逻辑在单一历法系统下保持一致，同时仍可按用户偏好展示日期。
-
-支持的历法系统及其标识符完整列表见：
+**Note：** 无论显示的 locale 如何，`onChange` 事件始终返回与 `value` 或 `defaultValue` 相同日历系统的日期（未提供 value 时为 Gregorian）。这确保应用逻辑在单一日历系统下一致运行，同时仍可按用户偏好格式显示日期。

+完整支持的日历系统及其标识符列表请参阅：
 - [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
 - [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)

-### 自定义渲染函数
+## 自定义样式

-<ComponentPreview
-  name="date-picker-custom-render-function"
-/>
+### Tailwind CSS

-<RelatedComponents component="datepicker" />
+<ComponentPreview name="date-picker-custom-styles" />

-## 样式
+### 全局 CSS

-### 传入 Tailwind CSS 类
-
-你可以分别为各个组合部分添加样式：
-
-```tsx
-import {Calendar, DateField, DatePicker, Label} from '@heroui/react';
-
-function CustomDatePicker() {
-  return (
-    <DatePicker className="w-[320px] gap-2">
-      <Label className="text-sm font-semibold">Date</Label>
-      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
-        <DateField.Input>
-          {(segment) => <DateField.Segment segment={segment} />}
-        </DateField.Input>
-        <DateField.Suffix>
-          <DatePicker.Trigger className="w-full">
-            <DatePicker.TriggerIndicator className="text-default-600" />
-          </DatePicker.Trigger>
-        </DateField.Suffix>
-      </DateField.Group>
-      <DatePicker.Popover className="rounded-xl p-2">
-        <Calendar aria-label="Custom date picker calendar">
-          {/* Calendar parts */}
-        </Calendar>
-      </DatePicker.Popover>
-    </DatePicker>
-  );
-}
-```
-
-### 自定义组件类
-
-要自定义 DatePicker 的基础类，请使用 `@layer components`。
+使用 `@layer components` 自定义 DatePicker 基础类。

 ```css
@layer components {
@@ -169,59 +139,64 @@ function CustomDatePicker() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 命名，便于复写与定制。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 命名以便复用自定义。

 ### CSS 类

 DatePicker 在 `packages/styles/components/date-picker.css` 中使用以下类：

- `.date-picker` - 根包裹层。
- `.date-picker__trigger` - 打开弹出层的触发区域。
- `.date-picker__trigger-indicator` - 默认或自定义指示器插槽。
- `.date-picker__popover` - 弹出层内容包裹。
+- `.date-picker` - 根包裹层
+- `.date-picker__trigger` - 打开 popover 的触发器部分
+- `.date-picker__trigger-indicator` - 默认/自定义指示器 slot
+- `.date-picker__popover` - Popover 内容包裹层

 ### 交互状态

-DatePicker 支持 React Aria 的 data 属性与伪类状态：
+DatePicker 支持 React Aria data 属性与伪状态：

- **展开**：触发器上的 `[data-open="true"]`。
- **禁用**：触发器上的 `[data-disabled="true"]` 或 `[aria-disabled="true"]`。
- **焦点可见**：触发器上的 `:focus-visible` 或 `[data-focus-visible="true"]`。
- **悬停**：触发器上的 `:hover` 或 `[data-hovered="true"]`。
+- **Open**：触发器上 `[data-open="true"]`
+- **Disabled**：触发器上 `[data-disabled="true"]` 或 `[aria-disabled="true"]`
+- **Focus visible**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **Hover**：触发器上 `:hover` 或 `[data-hovered="true"]`

 ## API 参考

-### DatePicker Props
+### DatePicker

-DatePicker 继承 React Aria [DatePicker](https://react-aria.adobe.com/DatePicker.md) 的全部 props。
+DatePicker 继承 React Aria [DatePicker](https://react-aria.adobe.com/DatePicker.md) 的所有 props。

 | Prop | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| `value` | `DateValue \| null` | - | 受控的选中日期值。 |
-| `defaultValue` | `DateValue \| null` | - | 非受控模式下的默认选中值。 |
-| `onChange` | `(value: DateValue \| null) => void` | - | 选中日期变化时调用。 |
-| `isOpen` | `boolean` | - | 受控的弹出层打开状态。 |
-| `defaultOpen` | `boolean` | `false` | 弹出层初始打开状态。 |
-| `onOpenChange` | `(isOpen: boolean) => void` | - | 弹出层打开状态变化时调用。 |
-| `isDisabled` | `boolean` | `false` | 禁用日期选择与触发器交互。 |
-| `isInvalid` | `boolean` | - | 将字段标记为无效以呈现校验状态。 |
-| `minValue` | `DateValue` | - | 可选择的最小日期。 |
-| `maxValue` | `DateValue` | - | 可选择的最大日期。 |
-| `name` | `string` | - | HTML 表单提交使用的 name。 |
-| `children` | `ReactNode \| (values: DatePickerRenderProps) => ReactNode` | - | 组合内容或渲染函数。 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DatePickerRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+|------|------|---------|-------------|
+| `value` | `DateValue \| null` | - | 受控选中日期值 |
+| `defaultValue` | `DateValue \| null` | - | 非受控模式下的默认选中值 |
+| `onChange` | `(value: DateValue \| null) => void` | - | 选中日期变化时调用 |
+| `isOpen` | `boolean` | - | 受控 popover 打开状态 |
+| `defaultOpen` | `boolean` | `false` | 初始 popover 打开状态 |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | popover 打开状态变化时调用 |
+| `isDisabled` | `boolean` | `false` | 禁用日期选择与触发器交互 |
+| `isInvalid` | `boolean` | - | 标记字段为无效以显示校验状态 |
+| `minValue` | `DateValue` | - | 最小可选日期 |
+| `maxValue` | `DateValue` | - | 最大可选日期 |
+| `name` | `string` | - | HTML 表单提交时使用的 name |
+| `children` | `ReactNode \| (values: DatePickerRenderProps) => ReactNode` | - | 组合内容或 render 函数 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DatePickerRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### 组合部件
+### Composition Parts

-| 组件 | 描述 |
-| --- | --- |
-| `DatePicker.Root` | 根日期选择器容器与状态持有者。 |
-| `DatePicker.Trigger` | 触发按钮，通常渲染在 `DateField.Suffix` 内。 |
-| `DatePicker.TriggerIndicator` | 带默认日历图标的指示器插槽。 |
-| `DatePicker.Popover` | 包裹 `Calendar` 内容的弹出层。 |
+| Component | Description |
+|-----------|-------------|
+| `DatePicker.Root` | 根 date picker 容器与状态所有者 |
+| `DatePicker.Trigger` | 触发按钮，通常渲染在 `DateField.Suffix` 内 |
+| `DatePicker.TriggerIndicator` | 带默认日历图标的指示器 slot |
+| `DatePicker.Popover` | `Calendar` 内容的 Popover 包裹层 |

-### 相关包
+### Related packages
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 所有日期组件使用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖 locale
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前 locale 与布局方向

- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 所有日期组件共用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具函数
- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖语言环境
- [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前语言环境与布局方向
+## 相关组件
+
+<RelatedComponents component="datepicker" />
@@ -1,6 +1,6 @@
 ---
 title: DateRangePicker 日期范围选择器
-description: 基于 React Aria DateRangePicker 的可组合日期范围选择器，由 DateField 与 RangeCalendar 组合而成。
+description: 基于 React Aria DateRangePicker，通过 DateField 与 RangeCalendar 组合的可组合日期范围选择器
 links:
  rac: DateRangePicker
  source: date-range-picker/date-range-picker.tsx
@@ -9,19 +9,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { DateField, DateRangePicker, Label, RangeCalendar } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="date-range-picker-basic" />

-### 组件结构
+## 组件结构

-`DateRangePicker` 采用组合优先的 API。请显式组合 `DateField` 与 `RangeCalendar`，以便完全控制结构与样式。
+`DateRangePicker` 采用组合优先 API。显式组合 `DateField` 与 `RangeCalendar` 以控制结构与样式。

 ```tsx
 import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react';
@@ -67,98 +65,65 @@ export default () => (
 )
 ```

-### 受控
-
-<ComponentPreview name="date-range-picker-controlled" />
-
-### 校验
-
-<ComponentPreview name="date-range-picker-with-validation" />
-
-### 格式选项
-
-使用 `granularity`、`hourCycle`、`hideTimeZone`、`shouldForceLeadingZeros` 等 props 控制 DateRangePicker 值的展示格式。
-
-<ComponentPreview name="date-range-picker-format-options" />
+## 示例

 ### 禁用

 <ComponentPreview name="date-range-picker-disabled" />

-### 自定义指示器
+### 受控组件

-未传入子节点时，`DateRangePicker.TriggerIndicator` 会渲染默认的 `IconCalendar`。传入子节点即可替换。
+<ComponentPreview name="date-range-picker-controlled" />

-<ComponentPreview name="date-range-picker-with-custom-indicator" />
+### 表单校验
+
+<ComponentPreview name="date-range-picker-with-validation" />
+
+### 格式选项
+
+使用 `granularity`、`hourCycle`、`hideTimeZone`、`shouldForceLeadingZeros` 等 props 控制 DateRangePicker 值的显示方式。
+
+<ComponentPreview name="date-range-picker-format-options" />

 ### 表单示例

 <ComponentPreview name="date-range-picker-form-example" />

-### 国际化历法
+### 自定义指示器

-默认情况下，DateRangePicker 按用户语言环境的历法显示日期。你可以使用 `I18nProvider` 包裹 DateRangePicker，并通过 [Unicode 历法语言扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。
+未提供 children 时，`DateRangePicker.TriggerIndicator` 渲染默认 `IconCalendar`。传入 children 可替换。

-下方示例展示印度历法系统：
+<ComponentPreview name="date-range-picker-with-custom-indicator" />
+
+### 渲染函数
+
+<ComponentPreview
+  name="date-range-picker-render-function"
+/>
+
+### 国际化日历
+
+默认情况下，DateRangePicker 使用用户 locale 的日历系统显示日期。可用 `I18nProvider` 包裹并设置 [Unicode 日历 locale 扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。
+
+以下示例展示印度日历系统：

 <ComponentPreview name="date-range-picker-international-calendar" />

-**说明：** `onChange` 事件始终返回与 `value` 或 `defaultValue` 相同历法系统中的日期（若未提供值则为公历），与界面展示的本地化格式无关。
+**Note：** 无论显示的 locale 如何，`onChange` 事件始终返回与 `value` 或 `defaultValue` 相同日历系统的日期（未提供 value 时为 Gregorian）。

-支持的历法系统及其标识符完整列表见：
+完整支持的日历系统及其标识符列表请参阅：
 - [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
 - [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)

-### 自定义渲染函数
+## 自定义样式

-<ComponentPreview
-  name="date-range-picker-custom-render-function"
-/>
+### Tailwind CSS

-<RelatedComponents component="daterangepicker" />
+<ComponentPreview name="date-range-picker-custom-styles" />

-## 样式
+### 全局 CSS

-### 传入 Tailwind CSS 类
-
-你可以独立为每个组合部件添加样式：
-
-```tsx
-import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react';
-
-function CustomDateRangePicker() {
-  return (
-    <DateRangePicker className="w-[360px] gap-2">
-      <Label className="text-sm font-semibold">Trip dates</Label>
-      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
-        <DateField.InputContainer>
-          <DateField.Input slot="start">
-            {(segment) => <DateField.Segment segment={segment} />}
-          </DateField.Input>
-          <DateRangePicker.RangeSeparator className="px-2 text-default" />
-          <DateField.Input slot="end">
-            {(segment) => <DateField.Segment segment={segment} />}
-          </DateField.Input>
-        </DateField.InputContainer>
-        <DateField.Suffix>
-          <DateRangePicker.Trigger className="w-full">
-            <DateRangePicker.TriggerIndicator className="text-default" />
-          </DateRangePicker.Trigger>
-        </DateField.Suffix>
-      </DateField.Group>
-      <DateRangePicker.Popover className="rounded-xl p-2">
-        <RangeCalendar aria-label="Custom range picker calendar">
-          {/* RangeCalendar parts */}
-        </RangeCalendar>
-      </DateRangePicker.Popover>
-    </DateRangePicker>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 DateRangePicker 基础类，请使用 `@layer components`。
+使用 `@layer components` 自定义 DateRangePicker 基础类。

 ```css
@layer components {
@@ -184,62 +149,67 @@ function CustomDateRangePicker() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 命名，以便复写与自定义。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 DateRangePicker 在 `packages/styles/components/date-range-picker.css` 中使用以下类：

- `.date-range-picker` - 根包裹层。
- `.date-range-picker__trigger` - 打开弹出层的触发区域。
- `.date-range-picker__trigger-indicator` - 默认或自定义指示器插槽。
- `.date-range-picker__range-separator` - 开始与结束日期输入之间的分隔。
- `.date-range-picker__popover` - 弹出层内容包裹。
+- `.date-range-picker` - 根包裹层
+- `.date-range-picker__trigger` - 打开 popover 的触发器部分
+- `.date-range-picker__trigger-indicator` - 默认/自定义指示器 slot
+- `.date-range-picker__range-separator` - 开始与结束日期输入之间的分隔符
+- `.date-range-picker__popover` - Popover 内容包裹层

 ### 交互状态

-DateRangePicker 支持 React Aria 的 data 属性与伪类状态：
+DateRangePicker 支持 React Aria data 属性与伪状态：

- **展开**：触发器上的 `[data-open="true"]`。
- **禁用**：触发器上的 `[data-disabled="true"]` 或 `[aria-disabled="true"]`。
- **焦点可见**：触发器上的 `:focus-visible` 或 `[data-focus-visible="true"]`。
- **悬停**：触发器上的 `:hover` 或 `[data-hovered="true"]`。
+- **Open**：触发器上 `[data-open="true"]`
+- **Disabled**：触发器上 `[data-disabled="true"]` 或 `[aria-disabled="true"]`
+- **Focus visible**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **Hover**：触发器上 `:hover` 或 `[data-hovered="true"]`

 ## API 参考

-### DateRangePicker Props
+### DateRangePicker

-DateRangePicker 继承 React Aria [DateRangePicker](https://react-aria.adobe.com/DateRangePicker) 的全部 props。
+DateRangePicker 继承 React Aria [DateRangePicker](https://react-aria.adobe.com/DateRangePicker) 的所有 props。

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `value` | `{ start: DateValue; end: DateValue } \| null` | - | 受控的选中日期范围值。 |
-| `defaultValue` | `{ start: DateValue; end: DateValue } \| null` | - | 非受控模式下的默认范围。 |
-| `onChange` | `(value: { start: DateValue; end: DateValue } \| null) => void` | - | 选中范围变化时调用。 |
-| `isOpen` | `boolean` | - | 受控的弹出层展开状态。 |
-| `defaultOpen` | `boolean` | `false` | 弹出层初始是否展开。 |
-| `onOpenChange` | `(isOpen: boolean) => void` | - | 弹出层展开状态变化时调用。 |
-| `isDisabled` | `boolean` | `false` | 禁用范围选择与触发器交互。 |
-| `isInvalid` | `boolean` | - | 标记字段无效以呈现校验状态。 |
-| `minValue` | `DateValue` | - | 可选的最小日期。 |
-| `maxValue` | `DateValue` | - | 可选的最大日期。 |
-| `startName` | `string` | - | HTML 表单提交时开始日期字段名。 |
-| `endName` | `string` | - | HTML 表单提交时结束日期字段名。 |
-| `children` | `ReactNode \| (values: DateRangePickerRenderProps) => ReactNode` | - | 组合内容或渲染函数。 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DateRangePickerRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+|------|------|---------|-------------|
+| `value` | `{ start: DateValue; end: DateValue } \| null` | - | 受控选中日期范围值 |
+| `defaultValue` | `{ start: DateValue; end: DateValue } \| null` | - | 非受控模式下的默认选中范围 |
+| `onChange` | `(value: { start: DateValue; end: DateValue } \| null) => void` | - | 选中范围变化时调用 |
+| `isOpen` | `boolean` | - | 受控 popover 打开状态 |
+| `defaultOpen` | `boolean` | `false` | 初始 popover 打开状态 |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | popover 打开状态变化时调用 |
+| `isDisabled` | `boolean` | `false` | 禁用范围选择与触发器交互 |
+| `isInvalid` | `boolean` | - | 标记字段为无效以显示校验状态 |
+| `minValue` | `DateValue` | - | 最小可选日期 |
+| `maxValue` | `DateValue` | - | 最大可选日期 |
+| `startName` | `string` | - | HTML 表单提交时开始日期的 name |
+| `endName` | `string` | - | HTML 表单提交时结束日期的 name |
+| `children` | `ReactNode \| (values: DateRangePickerRenderProps) => ReactNode` | - | 组合内容或 render 函数 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DateRangePickerRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### 组合部件
+### Composition Parts

-| 组件 | 描述 |
+| Component | Description |
 |-----------|-------------|
-| `DateRangePicker.Root` | 根日期范围选择器容器与状态持有者。 |
-| `DateRangePicker.Trigger` | 触发按钮，通常放在 `DateField.Suffix` 内。 |
-| `DateRangePicker.TriggerIndicator` | 带默认日历图标的指示器插槽。 |
-| `DateRangePicker.RangeSeparator` | 开始与结束日期输入之间的分隔部件。 |
-| `DateRangePicker.Popover` | 包裹 `RangeCalendar` 内容的弹出层。 |
+| `DateRangePicker.Root` | 根 date range picker 容器与状态所有者 |
+| `DateRangePicker.Trigger` | 触发按钮，通常渲染在 `DateField.Suffix` 内 |
+| `DateRangePicker.TriggerIndicator` | 带默认日历图标的指示器 slot |
+| `DateRangePicker.RangeSeparator` | 开始与结束日期输入之间的分隔符部分 |
+| `DateRangePicker.Popover` | `RangeCalendar` 内容的 Popover 包裹层 |

 ### Related packages
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 所有日期组件使用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖 locale
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前 locale 与布局方向

- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 各日期组件共用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具函数
- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖语言环境
- [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前语言环境与书写方向
+## 相关组件
+
+<RelatedComponents component="daterangepicker" />
@@ -8,17 +8,15 @@ links:
  storybook: Components/Date and Time/RangeCalendar
 ---

-## 引入
+## 用法

 ```tsx
 import { RangeCalendar } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="range-calendar-basic" />

-### 组件结构
+## 组件结构

 ```tsx
 import {RangeCalendar} from '@heroui/react';
@@ -42,9 +40,15 @@ export default () => (
 )
 ```

+## 示例
+
+### 禁用
+
+<ComponentPreview name="range-calendar-disabled" />
+
 ### 年份选择

-`RangeCalendar.YearPickerTrigger`、`RangeCalendar.YearPickerGrid` 及其 body/cell 子组件提供一体化的年份导航模式。
+`RangeCalendar.YearPickerTrigger`, `RangeCalendar.YearPickerGrid`, and their body/cell subcomponents provide an integrated year navigation pattern.

 <ComponentPreview name="range-calendar-year-picker" />

@@ -52,123 +56,97 @@ export default () => (

 <ComponentPreview name="range-calendar-default-value" />

-### 受控
+### 受控组件

 <ComponentPreview name="range-calendar-controlled" />

-### 最小与最大日期
+### 日期范围限制

 <ComponentPreview name="range-calendar-min-max-dates" />

 ### 不可用日期

-使用 `isDateUnavailable` 禁用周末、节假日或已被预订的日期等。
+使用 `isDateUnavailable` 屏蔽周末、节假日或已预订等不可用日期。

 <ComponentPreview name="range-calendar-unavailable-dates" />

 ### 基于锚点的不可用日期

-选择范围时，`isDateUnavailable` 的第二个参数 `anchorDate` 为用户选中的开始日期。可据此限制结束日期（例如仅允许开始日期前后 7 天）。
+选择范围时，`isDateUnavailable` 会收到第二个参数 `anchorDate`（首个选中日期）。可用它限制哪些结束日期有效（例如起始日期后 7 天内）。

 <ComponentPreview name="range-calendar-anchor-unavailable-dates" />

-### 固定周数
+### 月份周数

-将 `weeksInMonth` 设为固定值（例如 `6`），可在月份切换时保持网格高度稳定。
+将 `weeksInMonth` 设为固定值（例如 `6`），在月份切换时保持网格高度稳定。

 <ComponentPreview name="range-calendar-weeks-in-month" />

 ### 周视图

-设置 `visibleDuration={{ weeks: n }}` 可一次显示一个或多个周。翻页会按可见周范围前进。显示多周时可配合 `pageBehavior="single"` 每次仅移动一周。
+设置 `visibleDuration={{ weeks: n }}` 一次显示一个或多个周。导航按可见周范围前进。显示多周时，使用 `pageBehavior="single"` 每次移动一周。

 <ComponentPreview name="range-calendar-week-view" />

 ### 日视图

-设置 `visibleDuration={{ days: n }}` 可显示连续多天的滚动窗口。翻页会按可见天数范围前进。显示多天时配合 `pageBehavior="single"` 可每次仅移动一天。
+设置 `visibleDuration={{ days: n }}` 显示连续日期的滚动窗口。导航按可见日范围前进。显示多天时，使用 `pageBehavior="single"` 每次移动一天。

 <ComponentPreview name="range-calendar-day-view" />

-### 允许非连续范围
+### 非连续范围

-启用 `allowsNonContiguousRanges`，允许选择跨越不可用日期的范围。
+启用 `allowsNonContiguousRanges` 以允许跨越不可用日期进行选择。

 <ComponentPreview name="range-calendar-allows-non-contiguous-ranges" />

-### 禁用
-
-<ComponentPreview name="range-calendar-disabled" />
-
 ### 只读

 <ComponentPreview name="range-calendar-read-only" />

-### 无效
+### 无效状态

 <ComponentPreview name="range-calendar-invalid" />

-### 焦点日期
+### 聚焦值

 <ComponentPreview name="range-calendar-focused-value" />

-### 单元格指示器
+### 单元格标记

-你可以自定义 `RangeCalendar.Cell` 的子节点，并使用 `RangeCalendar.CellIndicator` 展示活动等元数据。
+可自定义 `RangeCalendar.Cell` 的子内容，并使用 `RangeCalendar.CellIndicator` 展示事件等元数据。

 <ComponentPreview name="range-calendar-with-indicators" />

-### 多个月份
-
-使用 `visibleDuration` 与 `offset` 渲染多个月份网格，适用于预订与规划场景。在各列头部为 `RangeCalendar.Heading` 设置 `offset`（例如 `offset={{ months: 1 }}`）以显示对应月份标题。
-
-<ComponentPreview name="range-calendar-multiple-months" />
-
-### 国际化历法
-
-默认情况下，RangeCalendar 按用户语言环境的历法显示日期。你可以使用 `I18nProvider` 包裹 RangeCalendar，并通过 [Unicode 历法语言扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。
-
-下方示例展示印度历法系统：
-
-<ComponentPreview name="range-calendar-international-calendar" />
-
-**说明：** `onChange` 事件始终返回与 `value` 或 `defaultValue` 相同历法系统中的日期（若未提供值则为公历），与界面展示的本地化格式无关。
-
-### 实际场景示例
+### 典型场景

 <ComponentPreview name="range-calendar-booking-calendar" />

-<RelatedComponents component="range-calendar" />
+### 多月份展示

-## 样式
+结合 `visibleDuration` 与 `offset` 渲染多个网格，适用于预订与规划场景。

-### 传入 Tailwind CSS 类
+<ComponentPreview name="range-calendar-multiple-months" />

-```tsx
-import {RangeCalendar} from '@heroui/react';
+### 国际化日历

-function CustomRangeCalendar() {
-  return (
-    <RangeCalendar aria-label="Trip dates" className="w-80 rounded-2xl border border-border bg-surface p-3 shadow-sm">
-      <RangeCalendar.Header className="pb-3">
-        <RangeCalendar.Heading className="text-default" />
-        <RangeCalendar.NavButton slot="previous" className="text-default" />
-        <RangeCalendar.NavButton slot="next" className="text-default" />
-      </RangeCalendar.Header>
-      <RangeCalendar.Grid>
-        <RangeCalendar.GridHeader>
-          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
-        </RangeCalendar.GridHeader>
-        <RangeCalendar.GridBody>
-          {(date) => <RangeCalendar.Cell date={date} />}
-        </RangeCalendar.GridBody>
-      </RangeCalendar.Grid>
-    </RangeCalendar>
-  );
-}
-```
+默认情况下，RangeCalendar 使用用户 locale 的历法系统显示日期。可用 `I18nProvider` 包裹组件，并设置 [Unicode 历法 locale 扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。

-### 自定义组件类
+以下示例展示印度历法系统：
+
+<ComponentPreview name="range-calendar-international-calendar" />
+
+**注意：** 无论显示 locale 如何，`onChange` 事件始终返回与 `value` 或 `defaultValue` 相同历法系统的日期（未提供 value 时为公历）。
+
+## 自定义样式
+
+### Tailwind CSS
+
+<ComponentPreview name="range-calendar-custom-styles" />
+
+### 全局 CSS
+
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -186,6 +164,10 @@ function CustomRangeCalendar() {
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

 RangeCalendar 在 `packages/styles/components/range-calendar.css` 与 `packages/styles/components/calendar-year-picker.css` 中使用以下类：
@@ -225,8 +207,7 @@ RangeCalendar 同时支持伪类与 React Aria 的 data 属性：

 ## API 参考

-### RangeCalendar Props
-
+### RangeCalendar
 RangeCalendar 继承 React Aria [RangeCalendar](https://react-spectrum.adobe.com/react-aria/RangeCalendar.html) 的全部 props。

 | Prop | 类型 | 默认值 | 描述 |
@@ -283,8 +264,7 @@ RangeCalendar 继承 React Aria [RangeCalendar](https://react-spectrum.adobe.com
 | `RangeCalendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | 自定义年份单元格标签（纪元、历法系统等）。 |
 | `RangeCalendar.YearPickerGrid` | `visibleYears` | `number` | min–max 跨度或 `20` | 滑动窗口中显示的年份数量。当同时设置 `minValue` 与 `maxValue` 时，默认为二者之间的完整范围。 |

-### RangeCalendar.Cell Render Props
-
+### RangeCalendar.Cell Render
 当 `RangeCalendar.Cell` 的 `children` 为函数时，可使用 React Aria 的渲染参数：

 | Prop | 类型 | 描述 |
@@ -306,3 +286,7 @@ RangeCalendar 继承 React Aria [RangeCalendar](https://react-spectrum.adobe.com
 - [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 各日期组件共用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具函数
 - [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖语言环境
 - [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前语言环境与书写方向
+
+## 相关组件
+
+<RelatedComponents component="range-calendar" />
@@ -8,17 +8,15 @@ links:
  storybook: Components/Date and Time/TimeField
 ---

-## 引入
+## 用法

 ```tsx
 import { TimeField } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="time-field-basic" />

-### 组件结构
+## 组件结构

 ```tsx
 import {TimeField, Label, Description, FieldError} from '@heroui/react';
@@ -39,6 +37,24 @@ export default () => (

 > **TimeField** 将标签、时间输入、说明与错误信息组合为单个无障碍组件。

+## 示例
+
+### 带图标
+
+添加前缀或后缀图标以增强时间字段。
+
+<ComponentPreview name="time-field-with-prefix-icon" />
+
+<ComponentPreview name="time-field-with-suffix-icon" />
+
+<ComponentPreview name="time-field-with-prefix-and-suffix" />
+
+### 表面样式
+
+在 [Surface](/docs/components/surface) 内使用时，请在 `TimeField.Group` 上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="time-field-on-surface" />
+
 ### 带描述

 <ComponentPreview name="time-field-with-description" />
@@ -47,91 +63,53 @@ export default () => (

 <ComponentPreview name="time-field-required" />

-### 校验
-
-配合 `FieldError`，使用 `isInvalid` 展示校验信息。
-
-<ComponentPreview name="time-field-invalid" />
-
-### 带校验
-
-TimeField 支持使用 `minValue`、`maxValue` 及自定义校验逻辑。
-
-<ComponentPreview name="time-field-with-validation" />
-
-### 受控
-
-通过控制 `value` 与其它组件或状态管理同步。
-
-<ComponentPreview name="time-field-controlled" />
-
-### 禁用状态
+### 禁用

 <ComponentPreview name="time-field-disabled" />

-### 带图标
-
-通过前缀或后缀图标增强时间输入。
-
-<ComponentPreview name="time-field-with-prefix-icon" />
-
-<ComponentPreview name="time-field-with-suffix-icon" />
-
-<ComponentPreview name="time-field-with-prefix-and-suffix" />
-
-### 全宽
+### 宽度充满

 <ComponentPreview name="time-field-full-width" />

-### 在 Surface 中
+### 表单校验

-在 [Surface](/docs/components/surface) 内使用时，请在 `TimeField.Group` 上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+将 `isInvalid` 与 `FieldError` 配合使用，以展示校验消息。

-<ComponentPreview name="time-field-on-surface" />
+<ComponentPreview name="time-field-invalid" />
+
+### 受控组件
+
+控制 value 以与其他组件或状态管理同步。
+
+<ComponentPreview name="time-field-controlled" />

 ### 表单示例

-包含校验与提交的完整表单示例。
+包含校验与提交处理的完整表单示例。

 <ComponentPreview name="time-field-form-example" />

-<RelatedComponents component="timefield" />
+### 带校验

-### 自定义渲染函数
+TimeField 支持通过 `minValue`、`maxValue` 及自定义校验逻辑进行验证。
+
+<ComponentPreview name="time-field-with-validation" />
+
+### 渲染函数

 <ComponentPreview
-  name="time-field-custom-render-function"
+  name="time-field-render-function"
 />

-## 样式
+## 自定义样式

-### 传入 Tailwind CSS 类
+### Tailwind CSS

-```tsx
-import {TimeField, Label, Description} from '@heroui/react';
+<ComponentPreview name="time-field-custom-styles" />

-function CustomTimeField() {
-  return (
-    <TimeField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
-      <Label className="text-sm font-semibold text-default-700">
-        Appointment time
-      </Label>
-      <TimeField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
-        <TimeField.Input>
-          {(segment) => <TimeField.Segment segment={segment} />}
-        </TimeField.Input>
-      </TimeField.Group>
-      <Description className="text-xs text-default-500">
-        Select a time for your appointment.
-      </Description>
-    </TimeField>
-  );
-}
-```
+### 全局 CSS

-### 自定义组件类
-
-TimeField 的默认样式很轻量。覆盖 `.time-field` 类即可自定义容器样式。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -156,6 +134,10 @@ TimeField 的默认样式很轻量。覆盖 `.time-field` 类即可自定义容
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

 - `.time-field` – 轻量样式的根容器（`flex flex-col gap-1`）
@@ -173,8 +155,7 @@ TimeField 会根据状态自动设置以下 data 属性：

 ## API 参考

-### TimeField Props
-
+### TimeField
 TimeField 继承 React Aria [TimeField](https://react-aria.adobe.com/TimeField) 的全部 props。

 #### Base Props
@@ -319,8 +300,7 @@ const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.sec
 | `isFocusWithin` | `boolean` | 是否有子元素聚焦。 |
 | `isFocusVisible` | `boolean` | 焦点是否可见（键盘导航）。 |

-### TimeField.Group Props
-
+### TimeField.Group
 TimeField.Group 继承 React Aria `Group` 的全部 props，并额外支持：

 | Prop | 类型 | 默认值 | 描述 |
@@ -328,8 +308,7 @@ TimeField.Group 继承 React Aria `Group` 的全部 props，并额外支持：
 | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
 | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 |

-### TimeField.Input Props
-
+### TimeField.Input
 TimeField.Input 继承 React Aria `DateInput` 的全部 props，并额外支持：

 | Prop | 类型 | 默认值 | 描述 |
@@ -339,8 +318,7 @@ TimeField.Input 继承 React Aria `DateInput` 的全部 props，并额外支持

 `TimeField.Input` 接受渲染函数作为子节点，函数接收日期段位；每个段位表示时间的一部分（时、分、秒等）。

-### TimeField.Segment Props
-
+### TimeField.Segment
 TimeField.Segment 继承 React Aria `DateSegment` 的全部 props：

 | Prop | 类型 | 默认值 | 描述 |
@@ -348,8 +326,7 @@ TimeField.Segment 继承 React Aria `DateSegment` 的全部 props：
 | `segment` | `DateSegment` | - | 来自 TimeField.Input 渲染函数的 `DateSegment` 对象。 |
 | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |

-### TimeField.Prefix Props
-
+### TimeField.Prefix
 TimeField.Prefix 接受标准 HTML `div` 属性：

 | Prop | 类型 | 默认值 | 描述 |
@@ -357,8 +334,7 @@ TimeField.Prefix 接受标准 HTML `div` 属性：
 | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
 | `children` | `ReactNode` | - | 前缀插槽中要显示的内容。 |

-### TimeField.Suffix Props
-
+### TimeField.Suffix
 TimeField.Suffix 接受标准 HTML `div` 属性：

 | Prop | 类型 | 默认值 | 描述 |
@@ -368,7 +344,7 @@ TimeField.Suffix 接受标准 HTML `div` 属性：

 ## TimeField.Group 样式

-### 自定义组件类
+### 全局 CSS

 基础类作用于所有实例，可通过 `@layer components` 一次性覆盖。

@@ -433,3 +409,7 @@ TimeField.Suffix 接受标准 HTML `div` 属性：
 - **禁用**：`[data-disabled="true"]` 或 `[aria-disabled="true"]`
 - **段位聚焦**：段位上的 `:focus` 或 `[data-focused="true"]`
 - **段位占位符**：段位上的 `[data-placeholder="true"]`
+
+## 相关组件
+
+<RelatedComponents component="timefield" />
@@ -1,6 +1,6 @@
 ---
 title: Alert 警告
-description: 向用户展示重要消息与通知，并提供状态指示。
+description: 向用户展示重要消息与通知，并提供状态指示
 links:
  source: alert/alert.tsx
  styles: alert.css
@@ -8,22 +8,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Alert } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="alert-basic"
 />

-
-### 组件结构
-
-导入 Alert 组件后，可通过点语法访问所有子部分。
+## 组件结构

 ```tsx
 import { Alert } from '@heroui/react';
@@ -39,34 +34,16 @@ export default () => (
 )
 ```

-<RelatedComponents component="alert" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="alert-custom-styles" />

-```tsx
-import { Alert } from "@heroui/react";
-
-function CustomAlert() {
-  return (
-    <Alert className="border-2 border-blue-500 rounded-xl" status="accent">
-      <Alert.Indicator className="text-blue-600" />
-      <Alert.Content className="gap-1">
-        <Alert.Title className="font-bold text-lg">Custom Alert</Alert.Title>
-        <Alert.Description className="text-sm opacity-80">
-          This alert has custom styling applied
-        </Alert.Description>
-      </Alert.Content>
-    </Alert>
-  );
-}
-```
-
-### 自定义组件类
+### 全局 CSS

 要自定义 Alert 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -84,25 +61,27 @@ function CustomAlert() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Alert 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert.css)）：

-#### 基础类
- `.alert` — Alert 根容器
- `.alert__indicator` — 图标/指示器容器
- `.alert__content` — 包裹标题与说明的内容容器
- `.alert__title` — Alert 标题文本
- `.alert__description` — Alert 说明文本
+#### 基础类 [!toc]
+- `.alert` - Alert 根容器
+- `.alert__indicator` - 图标/指示器容器
+- `.alert__content` - 包裹标题与说明的内容容器
+- `.alert__title` - Alert 标题文本
+- `.alert__description` - Alert 说明文本

-#### 状态变体类
- `.alert--default` — 默认灰色状态
- `.alert--accent` — 强调蓝色状态
- `.alert--success` — 成功绿色状态
- `.alert--warning` — 警告黄/橙色状态
- `.alert--danger` — 危险红色状态
+#### 状态变体类 [!toc]
+- `.alert--default` - 默认灰色状态
+- `.alert--accent` - 强调蓝色状态
+- `.alert--success` - 成功绿色状态
+- `.alert--warning` - 警告黄/橙色状态
+- `.alert--danger` - 危险红色状态

 ### 交互状态

@@ -110,38 +89,42 @@ Alert 主要用于信息展示，基础组件本身通常没有交互状态；

 ## API 参考

-### Alert Props
+### Alert

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
+|------|------|---------|-------------|
 | `status` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Alert 的视觉状态 |
 | `className` | `string` | - | 附加的 CSS 类 |
 | `children` | `ReactNode` | - | Alert 内容 |

-### Alert.Indicator Props
+### Alert.Indicator

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
+|------|------|---------|-------------|
 | `className` | `string` | - | 附加的 CSS 类 |
 | `children` | `ReactNode` | - | 自定义指示图标（默认显示状态图标） |

-### Alert.Content Props
+### Alert.Content

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
+|------|------|---------|-------------|
 | `className` | `string` | - | 附加的 CSS 类 |
 | `children` | `ReactNode` | - | 内容（通常为 Title 与 Description） |

-### Alert.Title Props
+### Alert.Title

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
+|------|------|---------|-------------|
 | `className` | `string` | - | 附加的 CSS 类 |
 | `children` | `ReactNode` | - | Alert 标题文本 |

-### Alert.Description Props
+### Alert.Description

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
+|------|------|---------|-------------|
 | `className` | `string` | - | 附加的 CSS 类 |
 | `children` | `ReactNode` | - | Alert 说明文本 |
+
+## 相关组件
+
+<RelatedComponents component="alert" />
@@ -8,19 +8,17 @@ links:
  storybook: Components/Feedback/Meter
 ---

-## 引入
+## 用法

 ```tsx
 import { Meter, Label } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="meter-basic"
 />

-### 组件结构
+## 组件结构

 ```tsx
 import { Meter, Label } from '@heroui/react';
@@ -36,6 +34,8 @@ export default () => (
 );
 ```

+## 示例
+
 ### 尺寸

 <ComponentPreview
@@ -48,50 +48,31 @@ export default () => (
  name="meter-colors"
 />

-### 自定义取值范围与格式
-
-使用 `minValue`、`maxValue` 与 `formatOptions` 自定义取值范围与展示格式。
-
-<ComponentPreview
-  name="meter-custom-value"
-/>
-
 ### 无可见标签

-当不需要可见标签时，请使用 `aria-label` 以保证无障碍。
+无需可见标签时，使用 `aria-label` 提供无障碍标签。

 <ComponentPreview
  name="meter-without-label"
 />

-<RelatedComponents component="meter" />
+### 自定义取值范围与格式

-## 样式
+使用 `minValue`、`maxValue` 与 `formatOptions` 自定义取值范围与显示格式。

-### 传入 Tailwind CSS 类
+<ComponentPreview
+  name="meter-custom-value"
+/>

-你可以为 Meter 的各个部分分别自定义样式：
+## 自定义样式

-```tsx
-import { Meter, Label } from '@heroui/react';
+### Tailwind CSS

-function CustomMeter() {
-  return (
-    <Meter value={60}>
-      <Label>Storage</Label>
-      <Meter.Output />
-      <Meter.Track className="bg-purple-100 dark:bg-purple-900">
-        <Meter.Fill className="bg-purple-500" />
-      </Meter.Track>
-    </Meter>
-  );
-}
-```
+<ComponentPreview name="meter-custom-styles" />

-### 自定义组件类
+### 全局 CSS

-要自定义 Meter 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -109,24 +90,26 @@ function CustomMeter() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Meter 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/meter.css)）：

-#### 基础与元素类
+#### 基础与元素类 [!toc]
 - `.meter` — 基础容器（grid 布局）
 - `.meter__output` — 数值文本展示
 - `.meter__track` — 轨道背景
 - `.meter__fill` — 轨道已填充部分

-#### 尺寸类
+#### 尺寸类 [!toc]
 - `.meter--sm` — 小尺寸变体（更细的轨道）
 - `.meter--md` — 中等尺寸变体（默认）
 - `.meter--lg` — 大尺寸变体（更粗的轨道）

-#### 颜色类
+#### 颜色类 [!toc]
 - `.meter--default` — 默认颜色变体
 - `.meter--accent` — 强调色变体
 - `.meter--success` — 成功色变体
@@ -135,8 +118,7 @@ Meter 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/

 ## API 参考

-### Meter Props
-
+### Meter
 继承自 [React Aria Meter](https://react-spectrum.adobe.com/react-aria/Meter.html)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -158,3 +140,7 @@ Meter 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/
 |------|------|------|
 | `percentage` | `number` | Meter 百分比（0–100） |
 | `valueText` | `string` | 格式化后的数值文本 |
+
+## 相关组件
+
+<RelatedComponents component="meter" />
@@ -8,19 +8,17 @@ links:
  storybook: Components/Feedback/ProgressBar
 ---

-## 引入
+## 用法

 ```tsx
 import { ProgressBar, Label } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="progress-bar-basic"
 />

-### 组件结构
+## 组件结构

 ```tsx
 import { ProgressBar, Label } from '@heroui/react';
@@ -36,6 +34,8 @@ export default () => (
 );
 ```

+## 示例
+
 ### 尺寸

 <ComponentPreview
@@ -48,9 +48,17 @@ export default () => (
  name="progress-bar-colors"
 />

+### 无可见标签
+
+无需可见标签时，使用 `aria-label` 提供无障碍标签。
+
+<ComponentPreview
+  name="progress-bar-without-label"
+/>
+
 ### 不确定进度

-在无法确定具体进度时，使用 `isIndeterminate`。
+无法确定进度时使用 `isIndeterminate`。

 <ComponentPreview
  name="progress-bar-indeterminate"
@@ -58,48 +66,21 @@ export default () => (

 ### 自定义数值范围

-使用 `minValue`、`maxValue` 与 `formatOptions` 自定义取值范围与展示格式。
+使用 `minValue`、`maxValue` 与 `formatOptions` 自定义取值范围与显示格式。

 <ComponentPreview
  name="progress-bar-custom-value"
 />

-### 无可见标签
+## 自定义样式

-不需要可见标签时，请使用 `aria-label` 保证无障碍。
+### Tailwind CSS

-<ComponentPreview
-  name="progress-bar-without-label"
-/>
+<ComponentPreview name="progress-bar-custom-styles" />

-<RelatedComponents component="progress-bar" />
+### 全局 CSS

-## 样式
-
-### 传入 Tailwind CSS 类
-
-你可以为 ProgressBar 的各个部分单独添加类名：
-
-```tsx
-import { ProgressBar, Label } from '@heroui/react';
-
-function CustomProgressBar() {
-  return (
-    <ProgressBar value={60}>
-      <Label>Loading</Label>
-      <ProgressBar.Output />
-      <ProgressBar.Track className="bg-purple-100 dark:bg-purple-900">
-        <ProgressBar.Fill className="bg-purple-500" />
-      </ProgressBar.Track>
-    </ProgressBar>
-  );
-}
-```
-
-### 自定义组件类
-
-要自定义 ProgressBar 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -117,26 +98,28 @@ function CustomProgressBar() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 ProgressBar 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/progress-bar.css)）：

-#### 基础与元素类
+#### 基础与元素类 [!toc]

 - `.progress-bar` - 基础容器（网格布局）
 - `.progress-bar__output` - 数值文本展示
 - `.progress-bar__track` - 轨道背景
 - `.progress-bar__fill` - 轨道上已填充部分

-#### 尺寸类
+#### 尺寸类 [!toc]

 - `.progress-bar--sm` - 小尺寸变体（更细的轨道）
 - `.progress-bar--md` - 中等尺寸变体（默认）
 - `.progress-bar--lg` - 大尺寸变体（更粗的轨道）

-#### 颜色类
+#### 颜色类 [!toc]

 - `.progress-bar--default` - 默认颜色变体
 - `.progress-bar--accent` - 强调色变体
@@ -146,8 +129,7 @@ ProgressBar 使用以下 CSS 类（[查看源码样式](https://github.com/herou

 ## API 参考

-### ProgressBar Props
-
+### ProgressBar
 继承自 [React Aria ProgressBar](https://react-spectrum.adobe.com/react-aria/ProgressBar.html)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -171,3 +153,7 @@ ProgressBar 使用以下 CSS 类（[查看源码样式](https://github.com/herou
 | `percentage` | `number` | 进度百分比（0–100） |
 | `valueText` | `string` | 格式化后的数值文本 |
 | `isIndeterminate` | `boolean` | 是否为不确定进度 |
+
+## 相关组件
+
+<RelatedComponents component="progress-bar" />
@@ -8,19 +8,17 @@ links:
  storybook: Components/Feedback/ProgressCircle
 ---

-## 引入
+## 用法

 ```tsx
 import { ProgressCircle } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="progress-circle-basic"
 />

-### 组件结构
+## 组件结构

 ```tsx
 import { ProgressCircle } from '@heroui/react';
@@ -35,6 +33,8 @@ export default () => (
 );
 ```

+## 示例
+
 ### 尺寸

 <ComponentPreview
@@ -49,7 +49,7 @@ export default () => (

 ### 不确定进度

-在无法确定具体进度时，使用 `isIndeterminate`。
+无法确定进度时使用 `isIndeterminate`。

 <ComponentPreview
  name="progress-circle-indeterminate"
@@ -63,39 +63,21 @@ export default () => (

 ### 自定义 SVG 属性

-由于每个部分都是可组合组件，你可以直接覆盖 `strokeWidth`、`r`、`cx`、`cy`、`viewBox` 等 SVG 属性。
+各子部分均为可组合组件，可直接覆盖 `strokeWidth`、`r`、`cx`、`cy`、`viewBox` 等 SVG 属性。

 <ComponentPreview
  name="progress-circle-custom-svg"
 />

-<RelatedComponents component="progress-circle" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="progress-circle-custom-styles" />

-你可以分别自定义 ProgressCircle 的各个部分：
+### 全局 CSS

-```tsx
-import { ProgressCircle } from '@heroui/react';
-
-function CustomProgressCircle() {
-  return (
-    <ProgressCircle aria-label="Loading" value={60}>
-      <ProgressCircle.Track>
-        <ProgressCircle.TrackCircle />
-        <ProgressCircle.FillCircle className="stroke-purple-500" />
-      </ProgressCircle.Track>
-    </ProgressCircle>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 ProgressCircle 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -113,26 +95,28 @@ function CustomProgressCircle() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 ProgressCircle 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/progress-circle.css)）：

-#### 基础与元素类
+#### 基础与元素类 [!toc]

 - `.progress-circle` - 基础容器
 - `.progress-circle__track` - SVG 元素
 - `.progress-circle__track-circle` - 背景圆环
 - `.progress-circle__fill-circle` - 进度弧

-#### 尺寸类
+#### 尺寸类 [!toc]

 - `.progress-circle--sm` - 小尺寸
 - `.progress-circle--md` - 中等尺寸（默认）
 - `.progress-circle--lg` - 大尺寸

-#### 颜色类
+#### 颜色类 [!toc]

 - `.progress-circle--default` - 默认颜色
 - `.progress-circle--accent` - 强调色
@@ -142,8 +126,7 @@ ProgressCircle 组件使用以下 CSS 类（[查看源码样式](https://github.

 ## API 参考

-### ProgressCircle Props
-
+### ProgressCircle
 继承自 [React Aria ProgressBar](https://react-spectrum.adobe.com/react-aria/ProgressBar.html)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -166,3 +149,7 @@ ProgressCircle 组件使用以下 CSS 类（[查看源码样式](https://github.
 | `percentage` | `number` | 进度百分比（0–100） |
 | `valueText` | `string` | 格式化后的数值文案 |
 | `isIndeterminate` | `boolean` | 是否为不确定进度 |
+
+## 相关组件
+
+<RelatedComponents component="progress-circle" />
@@ -8,18 +8,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Skeleton } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview 
  name="skeleton-basic"
 />
- 
+
+## 示例

 ### 文本内容

@@ -39,12 +38,6 @@ import { Skeleton } from '@heroui/react';
  name="skeleton-list"
 />

-### 动画类型
-
-<ComponentPreview
-  name="skeleton-animation-types"
-/>
-
 ### 网格

 <ComponentPreview
@@ -53,56 +46,28 @@ import { Skeleton } from '@heroui/react';

 ### 单次闪烁

-一种同步的闪烁效果，会一次性扫过所有骨架元素。请在父容器上应用 `skeleton--shimmer` 类，并将子级 Skeleton 的 `animationType` 设为 `"none"`。
+同步的 shimmer 效果会一次性扫过所有骨架元素。在父容器上应用 `skeleton--shimmer` 类，并将子骨架的 `animationType` 设为 `"none"`。

 <ComponentPreview
  name="skeleton-single-shimmer"
  style={{'contain': 'none'}}
 />

-<RelatedComponents component="skeleton" />
+### 动画类型

-## 样式
+<ComponentPreview
+  name="skeleton-animation-types"
+/>

-### 全局动画配置
+## 自定义样式

-你可以通过在应用中定义 `--skeleton-animation` CSS 变量，为所有 Skeleton 设置默认动画类型：
+### Tailwind CSS

-```css
-/* In your global CSS file */
-:root {
-  /* Possible values: shimmer, pulse, none */
-  --skeleton-animation: pulse;
-}
+<ComponentPreview name="skeleton-custom-styles" />

-/* You can also set different values for light/dark themes */
-.light, [data-theme="light"] {
-  --skeleton-animation: shimmer;
-}
+### 全局 CSS

-.dark, [data-theme="dark"] {
-  --skeleton-animation: pulse;
-}
-```
-
-在单个组件上指定 `animationType` 时，会覆盖上述全局设置。
-
-### 传入 Tailwind CSS 类
-
-```tsx
-import { Skeleton } from '@heroui/react';
-
-function CustomSkeleton() {
-  return (
-    <Skeleton className="h-20 w-32 rounded-full" />
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Skeleton 的组件类名，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -128,16 +93,66 @@ function CustomSkeleton() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+### 全局动画配置
+
+可在全局 CSS 中通过 `--skeleton-animation` 变量为所有 Skeleton 组件设置默认动画类型：
+
+```css
+/* 全局 CSS 文件 */
+:root {
+  /* 可选值：shimmer、pulse、none */
+  --skeleton-animation: pulse;
+}
+
+/* 也可为浅色/深色主题设置不同值 */
+.light, [data-theme="light"] {
+  --skeleton-animation: shimmer;
+}
+
+.dark, [data-theme="dark"] {
+  --skeleton-animation: pulse;
+}
+```
+
+在单个组件上指定 `animationType` 属性会覆盖此全局设置。
+
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### 全局动画配置
+
+你可以通过在应用中定义 `--skeleton-animation` CSS 变量，为所有 Skeleton 设置默认动画类型：
+
+```css
+/* In your global CSS file */
+:root {
+  /* Possible values: shimmer, pulse, none */
+  --skeleton-animation: pulse;
+}
+
+/* You can also set different values for light/dark themes */
+.light, [data-theme="light"] {
+  --skeleton-animation: shimmer;
+}
+
+.dark, [data-theme="dark"] {
+  --skeleton-animation: pulse;
+}
+```
+
+在单个组件上指定 `animationType` 时，会覆盖上述全局设置。
+
+

 ### CSS 类

 Skeleton 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/skeleton.css)）：

-#### 基础类
+#### 基础类 [!toc]
 `.skeleton` - 包含背景与圆角等基础骨架样式

-#### 动画变体类
+#### 动画变体类 [!toc]
 - `.skeleton--shimmer` - 添加带渐变效果的闪烁动画（默认）
 - `.skeleton--pulse` - 使用 Tailwind 的 `animate-pulse` 添加脉冲动画
 - `.skeleton--none` - 无动画的静态骨架
@@ -146,7 +161,7 @@ Skeleton 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-i

 Skeleton 支持三种动画类型，视觉效果各不相同：

-#### 闪烁动画
+#### 闪烁动画 [!toc]

 闪烁效果会在骨架元素上移动渐变：

@@ -171,7 +186,7 @@ Skeleton 支持三种动画类型，视觉效果各不相同：
 }
 ```

-#### 脉冲动画
+#### 脉冲动画 [!toc]

 脉冲动画使用 Tailwind 内置的 `animate-pulse` 工具类：

@@ -181,7 +196,7 @@ Skeleton 支持三种动画类型，视觉效果各不相同：
 }
 ```

-#### 无动画
+#### 无动画 [!toc]

 用于不需要任何动画的静态骨架：

@@ -193,9 +208,12 @@ Skeleton 支持三种动画类型，视觉效果各不相同：

 ## API 参考

-### Skeleton Props
-
+### Skeleton
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `animationType` | `"shimmer" \| "pulse" \| "none"` | `"shimmer"` 或 CSS 变量 | Skeleton 的动画类型；也可通过 `--skeleton-animation` CSS 变量进行全局配置 |
 | `className` | `string` | - | 额外的 CSS 类名 |
+
+## 相关组件
+
+<RelatedComponents component="skeleton" />
@@ -8,18 +8,18 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Spinner } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="spinner-basic"
 />

+## 示例
+
 ### 颜色

 <ComponentPreview
@@ -32,26 +32,15 @@ import { Spinner } from '@heroui/react';
  name="spinner-sizes"
 />

-<RelatedComponents component="spinner" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="spinner-custom-styles" />

-```tsx
-import {Spinner} from '@heroui/react';
+### 全局 CSS

-function CustomSpinner() {
-  return (
-    <Spinner className="text-blue-500" />
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Spinner 的组件类名，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -65,20 +54,22 @@ function CustomSpinner() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Spinner 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/spinner.css)）：

-#### 基础类与尺寸类
+#### 基础类与尺寸类 [!toc]
 - `.spinner` - 基础样式与默认尺寸
 - `.spinner--sm` - 小尺寸变体
 - `.spinner--md` - 中等尺寸变体（默认）
 - `.spinner--lg` - 大尺寸变体
 - `.spinner--xl` - 特大尺寸变体

-#### 颜色类
+#### 颜色类 [!toc]
 - `.spinner--current` - 继承当前文本颜色
 - `.spinner--accent` - 强调色变体
 - `.spinner--danger` - 危险色变体
@@ -87,10 +78,13 @@ Spinner 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-in

 ## API 参考

-### Spinner Props
-
+### Spinner
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Spinner 的尺寸 |
 | `color` | `"current" \| "accent" \| "success" \| "warning" \| "danger"` | `"current"` | Spinner 的颜色变体 |
 | `className` | `string` | - | 额外的 CSS 类名 |
+
+## 相关组件
+
+<RelatedComponents component="spinner" />
@@ -1,6 +1,6 @@
 ---
 title: CheckboxGroup 复选框组
-description: 用于管理多项复选框选择的 CheckboxGroup 组件。
+description: 用于管理多个复选框选择的复选框组组件
 icon: updated
 links:
  rac: CheckboxGroup
@@ -9,21 +9,17 @@ links:
  storybook: Components/Forms/CheckboxGroup
 ---

-## 引入
+## 用法

 ```tsx
 import { CheckboxGroup, Checkbox, Label, Description } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="checkbox-group-basic"
 />

-### 组件结构
-
-导入 CheckboxGroup 组件，并通过点语法访问所有子部分。
+## 组件结构

 ```tsx
 import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@heroui/react';
@@ -31,102 +27,83 @@ import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@heroui/r
 export default () => (
  <CheckboxGroup name="interests">
    <Label />
-    <Description /> {/* Optional */}
+    <Description /> {/* 可选 */}
    <Checkbox value="option1">
      <Checkbox.Content>
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
-        Label {/* 纯文本 —— 可点击的标签 */}
+        Label {/* 纯文本 — 可点击标签 */}
      </Checkbox.Content>
-      <Description /> {/* 可选：单个复选框的帮助文本 */}
+      <Description /> {/* 可选 — 单个 Checkbox 的帮助文本 */}
    </Checkbox>
-    <FieldError /> {/* Optional */}
+    <FieldError /> {/* 可选 */}
  </CheckboxGroup>
 );
 ```

-### 在 Surface 内
+## 示例

-置于 [Surface](/docs/components/surface) 中时，使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+### 表面样式
+
+在 [Surface](/docs/components/surface) 组件内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。

 <ComponentPreview
  name="checkbox-group-on-surface"
 />

-### 自定义指示器
-
-<ComponentPreview
-  name="checkbox-group-with-custom-indicator"
-/>
-
-### 不定状态
-
-<ComponentPreview
-  name="checkbox-group-indeterminate"
-/>
-
-### 受控
-
-<ComponentPreview
-  name="checkbox-group-controlled"
-/>
-
-### 校验
-
-<ComponentPreview
-  name="checkbox-group-validation"
-/>
-
 ### 禁用

 <ComponentPreview
  name="checkbox-group-disabled"
 />

-### 特性与附加示例
+### 半选状态
+
+<ComponentPreview
+  name="checkbox-group-indeterminate"
+/>
+
+### 受控组件
+
+<ComponentPreview
+  name="checkbox-group-controlled"
+/>
+
+### 表单校验
+
+<ComponentPreview
+  name="checkbox-group-validation"
+/>
+
+### 功能扩展示例

 <ComponentPreview
  name="checkbox-group-features-and-addons"
 />

-### 自定义渲染函数
+### 自定义指示器

 <ComponentPreview
-  name="checkbox-group-custom-render-function"
+  name="checkbox-group-with-custom-indicator"
 />

-<RelatedComponents component="checkboxgroup" />
+### 渲染函数

-## 样式
+<ComponentPreview
+  name="checkbox-group-render-function"
+/>

-### 传入 Tailwind CSS 类
+## 自定义样式

-你可以自定义 CheckboxGroup 组件：
+### Tailwind CSS

-```tsx
-import { CheckboxGroup, Checkbox, Label } from '@heroui/react';
+<ComponentPreview name="checkbox-group-custom-styles" />

-function CustomCheckboxGroup() {
-  return (
-    <CheckboxGroup className="gap-4" name="custom">
-      <Checkbox value="option1">
-        <Checkbox.Content>
-          <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
-            <Checkbox.Indicator className="text-white" />
-          </Checkbox.Control>
-          Option 1
-        </Checkbox.Content>
-      </Checkbox>
-    </CheckboxGroup>
-  );
-}
-```
+### 全局 CSS

-### 自定义组件类
-
-若要自定义 CheckboxGroup 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+可使用 `@layer components` 指令自定义 CheckboxGroup 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -136,17 +113,21 @@ function CustomCheckboxGroup() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 CheckboxGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox-group.css)）：

- `.checkbox-group` - 复选框组合容器基础样式
+#### 基础类 [!toc]
+
+- `.checkbox-group` - 复选框组根容器

 ## API 参考

-### CheckboxGroup Props
+### CheckboxGroup

 继承自 [React Aria CheckboxGroup](https://react-spectrum.adobe.com/react-aria/CheckboxGroup.html)。

@@ -154,18 +135,18 @@ CheckboxGroup 组件使用以下 CSS 类（[查看源码样式](https://github.c
 |------|------|--------|------|
 | `value` | `string[]` | - | 当前选中值（受控） |
 | `defaultValue` | `string[]` | - | 默认选中值（非受控） |
-| `onChange` | `(value: string[]) => void` | - | 选中值变化时调用的处理函数 |
-| `isDisabled` | `boolean` | `false` | 是否禁用整个复选框组合 |
+| `onChange` | `(value: string[]) => void` | - | 选中值变化时的回调 |
+| `isDisabled` | `boolean` | `false` | 是否禁用 |
 | `isRequired` | `boolean` | `false` | 是否必填 |
 | `isReadOnly` | `boolean` | `false` | 是否只读 |
 | `isInvalid` | `boolean` | `false` | 是否处于无效状态 |
-| `name` | `string` | - | 提交 HTML 表单时复选框组合的名称 |
-| `children` | `React.ReactNode \| (values: CheckboxGroupRenderProps) => React.ReactNode` | - | 复选框组合内容或渲染 prop |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+| `name` | `string` | - | 提交 HTML 表单时复选框组的名称 |
+| `children` | `React.ReactNode \| (values: CheckboxGroupRenderProps) => React.ReactNode` | - | 内容或 render prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### CheckboxGroupRenderProps
+### Render Props

-使用渲染 prop 模式时，会提供以下值：
+使用 render prop 模式时，提供以下值：

 | Prop | 类型 | 描述 |
 |------|------|------|
@@ -174,3 +155,7 @@ CheckboxGroup 组件使用以下 CSS 类（[查看源码样式](https://github.c
 | `isReadOnly` | `boolean` | 是否只读 |
 | `isInvalid` | `boolean` | 是否处于无效状态 |
 | `isRequired` | `boolean` | 是否必填 |
+
+## 相关组件
+
+<RelatedComponents component="checkboxgroup" />
@@ -1,6 +1,6 @@
 ---
 title: Checkbox 复选框
-description: 复选框允许用户从多个独立选项中选择多项，或将单个独立选项标记为已选。
+description: 复选框允许用户从列表中选择多项，或标记单个项目为选中状态
 icon: updated
 links:
  rac: CheckboxField
@@ -10,21 +10,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Checkbox } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="checkbox-basic"
 />

-### 组件结构
-
-引入 Checkbox 后，可通过点语法访问各个部分。
+## 组件结构

 ```tsx
 import { Checkbox, Description, FieldError } from '@heroui/react';
@@ -35,54 +31,71 @@ export default () => (
      <Checkbox.Control>
        <Checkbox.Indicator />
      </Checkbox.Control>
-      Label {/* 纯文本 —— 可点击的标签，同时作为无障碍名称 */}
+      Label {/* 纯文本 — 可点击标签与无障碍名称 */}
    </Checkbox.Content>
    <Description /> {/* 可选 — 字段级帮助文本 */}
-    <FieldError /> {/* 可选 — 校验错误信息 */}
+    <FieldError /> {/* 可选 — 校验消息 */}
  </Checkbox>
 );
 ```

+## 示例
+
+### 变体
+
+Checkbox 组件支持两种视觉变体：
+
+- **`primary`**（默认）- 标准样式与默认背景，适用于大多数场景
+- **`secondary`** - 低强调变体，适用于 Surface 组件内
+
+<ComponentPreview name="checkbox-variants" />
+
+### 全圆角
+
+<ComponentPreview
+  name="checkbox-full-rounded"
+/>
+
 ### 禁用

 <ComponentPreview
  name="checkbox-disabled"
 />

-### 默认选中
-
-<ComponentPreview
-  name="checkbox-default-selected"
-/>
-
-### 受控
-
-<ComponentPreview
-  name="checkbox-controlled"
-/>
-
-### 不定状态
-
-<ComponentPreview
-  name="checkbox-indeterminate"
-/>
-
 ### 外部标签

 <ComponentPreview
  name="checkbox-external-label"
 />

-### 带说明
+### 带描述

 <ComponentPreview
  name="checkbox-with-description"
 />

-### 渲染 props
+### 默认选中

 <ComponentPreview
-  name="checkbox-render-props"
+  name="checkbox-default-selected"
+/>
+
+### 无效状态
+
+<ComponentPreview
+  name="checkbox-invalid"
+/>
+
+### 受控组件
+
+<ComponentPreview
+  name="checkbox-controlled"
+/>
+
+### 半选状态
+
+<ComponentPreview
+  name="checkbox-indeterminate"
 />

 ### 表单集成
@@ -91,10 +104,16 @@ export default () => (
  name="checkbox-form"
 />

-### 无效
+### 渲染属性

 <ComponentPreview
-  name="checkbox-invalid"
+  name="checkbox-render-props"
+/>
+
+### 渲染函数
+
+<ComponentPreview
+  name="checkbox-render-function"
 />

 ### 自定义指示器
@@ -103,56 +122,16 @@ export default () => (
  name="checkbox-custom-indicator"
 />

-### 全圆角
+## 自定义样式

-<ComponentPreview
-  name="checkbox-full-rounded"
-/>
+### Tailwind CSS

-### 变体
+<ComponentPreview name="checkbox-custom-styles" />

-Checkbox 支持两种视觉变体：
+### 全局 CSS

- **`primary`**（默认）— 常规样式与默认背景，适用于大多数场景
- **`secondary`** — 弱强调变体，适合用于 Surface 等组件内部
-
-<ComponentPreview name="checkbox-variants" />
-
-### 自定义渲染函数
-
-<ComponentPreview
-  name="checkbox-custom-render-function"
-/>
-
-<RelatedComponents component="checkbox" />
-
-## 样式
-
-### 传入 Tailwind CSS 类
-
-你可以单独定制各个 Checkbox：
-
-```tsx
-import { Checkbox, Label } from '@heroui/react';
-
-function CustomCheckbox() {
-  return (
-    <Checkbox name="custom">
-      <Checkbox.Content>
-        <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
-          <Checkbox.Indicator className="text-white" />
-        </Checkbox.Control>
-        Custom Checkbox
-      </Checkbox.Content>
-    </Checkbox>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Checkbox 的组件类名，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 Checkbox 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -166,7 +145,7 @@ function CustomCheckbox() {
    /* Animated background indicator */
    &::before {
      @apply bg-accent pointer-events-none absolute inset-0 z-0 origin-center scale-50 rounded-md opacity-0 content-[''];
-      
+
      transition:
        scale 200ms linear,
        opacity 200ms linear,
@@ -189,75 +168,83 @@ function CustomCheckbox() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-Checkbox 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox.css)）：
+Checkbox 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox.css)）：

- `.checkbox` - Checkbox 根容器
+#### 基础类 [!toc]
+
+- `.checkbox` - 基础复选框容器（字段）
 - `.checkbox__content` - 包裹控件与标签文本的可点击 label
- `.checkbox__control` - Checkbox 控件方框
- `.checkbox__indicator` - Checkbox 勾选指示器
+- `.checkbox__control` - 复选框控件框
+- `.checkbox__indicator` - 复选框勾选指示器

 ### 交互状态

-Checkbox 同时支持 CSS 伪类与 data 属性，以获得更好的灵活性：
+复选框同时支持 CSS 伪类与 data 属性：

- **选中**：`[data-selected="true"]` 或 `[aria-checked="true"]`（显示勾选与背景色变化）
- **不定**：`[data-indeterminate="true"]`（以横线表示不定状态）
- **无效**：`[data-invalid="true"]` 或 `[aria-invalid="true"]`（以危险色显示错误状态）
- **悬停**：`:hover` 或 `[data-hovered="true"]`（交互状态在 `Checkbox.Control` / 按钮上）
- **焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环，作用于按钮）
- **禁用**：`[data-disabled="true"]`（降低透明度并禁用指针事件）
- **按下**：`:active` 或 `[data-pressed="true"]`
+- **Selected**：`[data-selected="true"]` 或 `[aria-checked="true"]`（显示勾选与背景色变化）
+- **Indeterminate**：`[data-indeterminate="true"]`（显示不确定状态的短横线）
+- **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]`（显示 danger 色错误状态）
+- **Hover**：`Checkbox.Control`（按钮）上的 `:hover` 或 `[data-hovered="true"]`
+- **Focus**：按钮上的 `:focus-visible` 或 `[data-focus-visible="true"]`（控件上显示焦点环）
+- **Disabled**：字段上的 `[data-disabled="true"]`（降低透明度，包括帮助文本）
+- **Pressed**：`:active` 或 `[data-pressed="true"]`

 ## API 参考

-### Checkbox Props
+### Checkbox

 继承自 [React Aria CheckboxField](https://react-spectrum.adobe.com/react-aria/Checkbox.html)。

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `isSelected` | `boolean` | `false` | Checkbox 是否选中 |
-| `defaultSelected` | `boolean` | `false` | Checkbox 默认是否选中（非受控） |
-| `isIndeterminate` | `boolean` | `false` | Checkbox 是否处于不定状态 |
-| `isDisabled` | `boolean` | `false` | Checkbox 是否禁用 |
-| `isInvalid` | `boolean` | `false` | Checkbox 是否无效 |
-| `isReadOnly` | `boolean` | `false` | Checkbox 是否只读 |
-| `isRequired` | `boolean` | `false` | Checkbox 是否必须选中 |
-| `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数 |
-| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 校验或 ARIA 校验 |
-| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为弱强调、无阴影变体，适合用于 surface 上。 |
-| `name` | `string` | - | input 元素的 name，用于提交 HTML 表单 |
-| `value` | `string` | - | input 元素的 value，用于提交 HTML 表单 |
-| `onChange` | `(isSelected: boolean) => void` | - | Checkbox 值变化时调用 |
-| `children` | `React.ReactNode \| (values: CheckboxFieldRenderProps) => React.ReactNode` | - | Checkbox 内容或字段级渲染 prop |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxFieldRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+| `isSelected` | `boolean` | `false` | 是否选中 |
+| `defaultSelected` | `boolean` | `false` | 默认是否选中（非受控） |
+| `isIndeterminate` | `boolean` | `false` | 是否处于不确定状态 |
+| `isDisabled` | `boolean` | `false` | 是否禁用 |
+| `isInvalid` | `boolean` | `false` | 是否无效 |
+| `isReadOnly` | `boolean` | `false` | 是否只读 |
+| `isRequired` | `boolean` | `false` | 是否必须选中 |
+| `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | 自定义验证函数 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单验证还是 ARIA |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 |
+| `name` | `string` | - | 提交 HTML 表单时 input 元素的名称 |
+| `value` | `string` | - | 提交 HTML 表单时 input 元素的值 |
+| `onChange` | `(isSelected: boolean) => void` | - | 值变化时的回调 |
+| `children` | `React.ReactNode \| (values: CheckboxFieldRenderProps) => React.ReactNode` | - | 内容或字段 render prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxFieldRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### Checkbox.Content Props
+### Checkbox.Content

-包裹控件与标签文本的可点击 `<label>`。请把 `Checkbox.Control` 与 `Label` 放在它内部；`Description`/`FieldError` 作为 `Checkbox.Content` 的兄弟节点。对于没有标签的 checkbox，省略 `Label` 并在 `Checkbox` 上传入 `aria-label`。
+可点击的 `<label>`，包裹控件与标签文本。将 `Checkbox.Control` 与 `Label` 放在其中；`Description`/`FieldError` 作为 `Checkbox.Content` 的兄弟节点。无标签的复选框可省略 `Label`，并在 `Checkbox` 上传递 `aria-label`。

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `children` | `React.ReactNode \| (values: CheckboxButtonRenderProps) => React.ReactNode` | - | 按钮内容（控件 + 标签），或按钮级渲染 prop |
-| `className` | `string \| (values: CheckboxButtonRenderProps) => string` | - | 应用到可点击 label 的类名 |
+| `children` | `React.ReactNode \| (values: CheckboxButtonRenderProps) => React.ReactNode` | - | 按钮内容（控件 + 标签）或按钮 render prop |
+| `className` | `string \| (values: CheckboxButtonRenderProps) => string` | - | 应用于可点击 label 的类 |

 ### CheckboxFieldRenderProps

-在根 `Checkbox` 上使用渲染 prop 时，提供以下字段级值：
+在根 `Checkbox` 上使用 render prop 时，提供以下字段级值：

 | Prop | 类型 | 描述 |
 |------|------|------|
-| `isSelected` | `boolean` | Checkbox 当前是否选中 |
-| `isIndeterminate` | `boolean` | Checkbox 是否处于不定状态 |
-| `isDisabled` | `boolean` | Checkbox 是否禁用 |
-| `isReadOnly` | `boolean` | Checkbox 是否只读 |
-| `isInvalid` | `boolean` | Checkbox 是否无效 |
-| `isRequired` | `boolean` | Checkbox 是否必填 |
+| `isSelected` | `boolean` | 是否当前选中 |
+| `isIndeterminate` | `boolean` | 是否处于不确定状态 |
+| `isDisabled` | `boolean` | 是否禁用 |
+| `isReadOnly` | `boolean` | 是否只读 |
+| `isInvalid` | `boolean` | 是否无效 |
+| `isRequired` | `boolean` | 是否必填 |

 ### CheckboxButtonRenderProps

-`Checkbox.Control` 与 `Checkbox.Indicator` 使用按钮级渲染 prop（`isHovered`、`isPressed`、`isFocusVisible` 等）。将函数作为 `Checkbox.Control` 或 `Checkbox.Indicator` 的子元素即可访问。
+`Checkbox.Control` 与 `Checkbox.Indicator` 使用按钮级 render props（`isHovered`、`isPressed`、`isFocusVisible` 等）。将函数作为 `Checkbox.Control` 子节点或传给 `Checkbox.Indicator` 以访问它们。
+
+## 相关组件
+
+<RelatedComponents component="checkbox" />
@@ -1,64 +1,37 @@
 ---
 title: Description 描述
-description: 为表单字段及其他组件提供补充说明文字。
+description: 为表单字段及其他组件提供补充说明文本
 links:
  rac: TextField
  source: description/description.tsx
  styles: description.css
 ---

-## 引入
+## 用法

 ```tsx
 import { Description } from '@heroui/react';
 ```

-## 用法
-
 <ComponentPreview
  name="description-basic"
 />

-<RelatedComponents component="description" />
-
-## API 参考
-
-### Description Props
-
-| Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | Description 的内容。 |
-
-## 无障碍
-
-Description 组件通过以下方式增强无障碍：
-
- 使用语义化 HTML，屏幕阅读器可识别
- 提供 `slot="description"` 属性以便与 React Aria 集成
- 支持适宜的文本对比度
-
-## 样式
-
-Description 组件使用以下 CSS 类：
-
- `.description` - 基础 Description 样式，使用弱化（muted）文本颜色
-
 ## 示例

-### 与表单字段一起使用
+### 搭配表单字段

 ```tsx
 <div className="flex flex-col gap-1">
  <Label htmlFor="password">Password</Label>
  <Input id="password" type="password" aria-describedby="password-description" />
  <Description id="password-description">
-    Must be at least 8 characters with one uppercase letter
+    至少 8 个字符，且包含一个大写字母
  </Description>
 </div>
 ```
- 
-### 与 TextField 集成
+
+### 与 TextField 配合

 ```tsx
 import {TextField, Label, Input, Description} from '@heroui/react';
@@ -70,4 +43,55 @@ import {TextField, Label, Input, Description} from '@heroui/react';
 </TextField>
 ```

-使用 [TextField](./text-field) 组件时，无障碍属性会自动应用到 Label 与 Description 上。
+使用 [TextField](./text-field) 组件时，无障碍属性会自动应用到标签与描述。
+
+## 自定义样式
+
+### Tailwind CSS
+
+<ComponentPreview name="description-custom-styles" />
+
+### 全局 CSS
+
+可使用 `@layer components` 指令自定义 Description 组件类。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .description {
+    @apply text-muted;
+  }
+}
+```
+
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Description 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/description.css)）：
+
+#### 基础类 [!toc]
+
+- `.description` - 基础描述样式，使用 `muted` 文本颜色
+
+## API 参考
+
+### Description
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode` | - | 描述内容 |
+
+## 无障碍
+
+Description 组件通过以下方式增强无障碍性：
+
+- 使用屏幕阅读器可识别的语义化 HTML
+- 提供 `slot="description"` 属性以集成 React Aria
+- 支持适当的文本对比度
+
+## 相关组件
+
+<RelatedComponents component="description" />
@@ -1,27 +1,25 @@
 ---
-title: ErrorMessage 错误信息
-description: 用于展示错误信息的底层组件。
+title: ErrorMessage 错误消息
+description: 用于展示错误的底层错误消息组件
 links:
  rac: TagGroup
  source: error-message/error-message.tsx
  styles: error-message.css
 ---

-## 引入
+## 用法

 ```tsx
 import { ErrorMessage } from '@heroui/react';
 ```

-## 用法
-
-`ErrorMessage` 是基于 React Aria `Text`、并使用 `errorMessage` 插槽的底层组件，适用于 **非表单** 场景（例如 `TagGroup`、`Calendar` 等集合类组件）。
-
 <ComponentPreview
  name="error-message-basic"
 />

-### 组件结构
+`ErrorMessage` 是基于 React Aria `Text` 组件、`errorMessage` slot 的底层组件，用于在 **非表单组件**（如 `TagGroup`、`Calendar` 及其他集合类组件）中展示错误消息。
+
+## 组件结构

 ```tsx
 import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';
@@ -36,83 +34,78 @@ import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';
 </TagGroup>
 ```

-<RelatedComponents component="errormessage" />
-
 ## 何时使用

 `ErrorMessage` **不绑定表单**，是用于非表单上下文的通用错误展示组件。

- **推荐用于** 非表单组件（例如 `TagGroup`、`Calendar`、集合类组件）
- **对于表单字段**，我们更推荐使用 [`FieldError`](/docs/components/field-error)，它提供表单相关的校验能力与自动错误处理，并遵循标准化的表单校验模式。
+- **推荐用于** 非表单组件（如 `TagGroup`、`Calendar`、集合类组件）
+- **表单字段** 建议使用 [`FieldError`](/docs/components/field-error)，它提供表单专用校验特性与自动错误处理，遵循标准化表单校验模式。

 ## ErrorMessage 与 FieldError

 | 组件 | 使用场景 | 表单集成 | 示例组件 |
-| --- | --- | --- | --- |
+|-----------|----------|------------------|---------------------|
 | `ErrorMessage` | 非表单组件 | 否 | `TagGroup`、`Calendar` |
 | `FieldError` | 表单字段（推荐） | 是 | `TextField`、`NumberField`、`Select` |

-对于表单校验，我们推荐使用 `FieldError`，因为它遵循标准化的表单校验模式并提供表单相关能力。示例与最佳实践见 [FieldError 文档](/docs/components/field-error) 与 [Form 指南](/docs/components/form)。
+表单校验建议使用 `FieldError`，它遵循标准化表单校验模式并提供表单专用特性。参见 [FieldError 文档](/docs/components/field-error) 与 [Form 指南](/docs/components/form)。

-## API 参考
+## 自定义样式

-### ErrorMessage Props
+### Tailwind CSS

-| Prop | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `children` | `ReactNode` | - | 错误信息内容 |
+<ComponentPreview name="error-message-custom-styles" />

-**说明：** `ErrorMessage` 基于 React Aria 的 `Text` 组件，并使用 `slot="errorMessage"`。你可以使用 `[slot=errorMessage]` CSS 选择器进行样式覆盖。
+### 全局 CSS

-## 无障碍
-
-ErrorMessage 通过以下方式增强无障碍：
-
- 使用屏幕阅读器可识别的语义化 HTML
- 提供 `slot="errorMessage"` 属性以集成 React Aria
- 为错误状态提供合适的文本对比度
- 遵循 WAI-ARIA 的错误信息最佳实践
-
-## 样式
-
-### 传入 Tailwind CSS 类
-
-```tsx
-import { ErrorMessage } from '@heroui/react';
-
-function CustomErrorMessage() {
-  return (
-    <ErrorMessage className="font-bold text-sm">
-      Custom styled error message
-    </ErrorMessage>
-  );
-}
-```
-
-### 自定义组件类
-
-要自定义 ErrorMessage 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+可使用 `@layer components` 指令自定义 ErrorMessage 组件类。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
  .error-message {
-    @apply text-red-600 text-sm font-medium;
+    @apply text-sm font-medium text-danger;
  }
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-ErrorMessage 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/error-message.css)）：
+ErrorMessage 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/error-message.css)）：

-#### 基础类
+#### 基础类 [!toc]

- `.error-message` - 危险色与文本截断等基础样式
+- `.error-message` - 基础错误消息样式，danger 色与文本截断

-#### 插槽类
+#### 插槽类 [!toc]

- `[slot="errorMessage"]` - 与 React Aria 集成的 ErrorMessage 插槽样式
+- `[slot="errorMessage"]` - 用于 React Aria 集成的 ErrorMessage slot 样式
+
+## API 参考
+
+### ErrorMessage
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode` | - | 错误消息内容 |
+
+## 说明
+
+`ErrorMessage` 基于 React Aria 的 `Text` 组件，`slot="errorMessage"`。可通过 `[slot=errorMessage]` CSS 选择器定位。
+
+## 无障碍
+
+ErrorMessage 组件通过以下方式增强无障碍性：
+
+- 使用屏幕阅读器可识别的语义化 HTML
+- 提供 `slot="errorMessage"` 属性以集成 React Aria
+- 错误状态支持适当的文本对比度
+- 遵循 WAI-ARIA 错误消息最佳实践
+
+## 相关组件
+
+<RelatedComponents component="errormessage" />
@@ -1,53 +1,23 @@
 ---
 title: FieldError 字段错误
-description: 用于展示表单字段的校验错误信息。
+description: 展示表单字段校验错误消息
 links:
  rac: FieldError
  source: field-error/field-error.tsx
  styles: field-error.css
 ---

-## 引入
+## 用法

 ```tsx
 import { FieldError } from '@heroui/react';
 ```

-## 用法
-
-FieldError 组件用于展示表单字段的校验错误信息。当父级字段被标记为无效时会自动显示，并提供平滑的透明度过渡。
-
 <ComponentPreview
  name="field-error-basic"
 />

-<RelatedComponents component="fielderror" />
-
-## API 参考
-
-### FieldError Props
-
-| Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode \| ((validation: ValidationResult) => ReactNode)` | - | 错误信息内容或渲染函数。 |
-
-## 无障碍
-
-FieldError 组件通过以下方式保证无障碍：
-
- 使用恰当的 ARIA 属性以播报错误
- 通过语义化 HTML 支持屏幕阅读器
- 同时提供视觉与程序化的错误提示
- 根据校验状态自动控制可见性
-
-## 样式
-
-FieldError 组件使用以下 CSS 类：
-
- `.field-error` - 基础错误样式，使用危险色（danger）
- 仅在存在 `data-visible` 属性时显示
- 长文案会以省略号截断
+FieldError 组件展示表单字段的校验错误消息。当父字段标记为无效时自动显示，并提供平滑的透明度过渡。

 ## 示例

@@ -119,3 +89,57 @@ function EmailField() {
  </FieldError>
 </TextField>
 ```
+
+## 自定义样式
+
+### Tailwind CSS
+
+<ComponentPreview name="field-error-custom-styles" />
+
+### 全局 CSS
+
+可使用 `@layer components` 指令自定义 FieldError 组件类。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .field-error {
+    @apply font-medium text-danger;
+  }
+}
+```
+
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+FieldError 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/field-error.css)）：
+
+#### 基础类 [!toc]
+
+- `.field-error` - 基础错误样式，danger 色
+- 仅在存在 `data-visible` 属性时显示
+- 长消息以省略号截断
+
+## API 参考
+
+### FieldError
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode \| ((validation: ValidationResult) => ReactNode)` | - | 错误消息内容或 render 函数 |
+
+## 无障碍
+
+FieldError 组件通过以下方式确保无障碍性：
+
+- 使用适当的 ARIA 属性播报错误
+- 语义化 HTML 支持屏幕阅读器
+- 提供视觉与程序化错误指示
+- 根据校验状态自动管理可见性
+
+## 相关组件
+
+<RelatedComponents component="fielderror" />
@@ -1,31 +1,21 @@
 ---
-title: Fieldset 字段集
-description: 使用 legend、description 与操作区对相关表单控件进行分组。
+title: Fieldset 字段组
+description: 将相关表单控件与图例、描述和操作组合在一起
 links:
  source: fieldset/fieldset.tsx
  styles: fieldset.css
  storybook: Components/Forms/Fieldset
 ---

-## 引入
+## 用法

 ```tsx
 import { Fieldset } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="fieldset-basic" />

-### 在 Surface 内
-
-在 [Surface](/docs/components/surface) 组件内部使用时，请在表单控件（Input、TextArea 等）上使用 `variant="secondary"`，以应用适合 surface 背景的弱强调变体。
-
-<ComponentPreview name="fieldset-on-surface" />
-
-### 组件结构
-
-引入 Fieldset 后，可通过点语法访问各个部分。
+## 组件结构

 ```tsx
 import { Fieldset } from '@heroui/react';
@@ -43,42 +33,23 @@ export default () => (
 )
 ```

-<RelatedComponents component="fieldset" />
+## 示例

-<RelatedShowcases component="Fieldset" />
+### 表面样式

-## 样式
+在 [Surface](/docs/components/surface) 内使用时，请在表单控件（Input、TextArea 等）上使用 `variant="secondary"`，以应用适合 Surface 背景的低强调变体。

-### 传入 Tailwind CSS 类
+<ComponentPreview name="fieldset-on-surface" />

-```tsx
-import { Fieldset, TextField, Label, Input } from '@heroui/react';
+## 自定义样式

-function CustomFieldset() {
-  return (
-    <Fieldset className="rounded-xl border border-border bg-surface p-6 shadow-sm">
-      <Fieldset.Legend className="text-lg font-semibold">Team members</Fieldset.Legend>
-      <Fieldset.Group className="grid gap-4 md:grid-cols-2">
-        <TextField>
-          <Label>First name</Label>
-          <Input className="rounded-full border-border/60" placeholder="Jane" />
-        </TextField>
-        <TextField>
-          <Label>Last name</Label>
-          <Input className="rounded-full border-border/60" placeholder="Doe" />
-        </TextField>
-      </Fieldset.Group>
-      <Fieldset.Actions className="justify-end gap-3">
-        {/* Action buttons */}
-      </Fieldset.Actions>
-    </Fieldset>
-  );
-}
-```
+### Tailwind CSS

-### 自定义组件类
+<ComponentPreview name="fieldset-custom-styles" />

-使用 `@layer components` 指令，针对 Fieldset 的 [BEM](https://getbem.com/) 风格类名进行定制。
+### 全局 CSS
+
+使用 `@layer components` 指令定位 Fieldset 的 [BEM](https://getbem.com/) 风格类。

 ```css
@layer components {
@@ -100,45 +71,59 @@ function CustomFieldset() {
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

 Fieldset 复合组件暴露以下 CSS 选择器：

+#### 基础类 [!toc]
+
 - `.fieldset` – 根容器
- `.fieldset__legend` – Legend 元素
- `.fieldset__field_group` – 分组字段的包裹层
+- `.fieldset__legend` – 图例元素
+- `.fieldset__field_group` – 分组字段包裹层
 - `.fieldset__actions` – 字段下方的操作栏

 ## API 参考

-### Fieldset Props
+### Fieldset

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 应用到根元素上的 Tailwind CSS 类。 |
-| `children` | `React.ReactNode` | - | Fieldset 内容（legend、分组、description、操作区等）。 |
-| `nativeProps` | `React.HTMLAttributes<HTMLFieldSetElement>` | 支持原生 fieldset 的属性与事件。 |
+| `className` | `string` | - | 应用于根元素的 Tailwind CSS 类 |
+| `children` | `React.ReactNode` | - | Fieldset 内容（图例、分组、描述、操作） |
+| `nativeProps` | `React.HTMLAttributes<HTMLFieldSetElement>` | 支持原生 fieldset 属性与事件 |

-### Fieldset.Legend Props
+### Fieldset.Legend

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | legend 元素的 Tailwind 类。 |
-| `children` | `React.ReactNode` | - | Legend 内容，通常为纯文本。 |
-| `nativeProps` | `React.HTMLAttributes<HTMLLegendElement>` |  - | 原生 legend 属性。 |
+| `className` | `string` | - | 图例元素的 Tailwind 类 |
+| `children` | `React.ReactNode` | - | 图例内容，通常为纯文本 |
+| `nativeProps` | `React.HTMLAttributes<HTMLLegendElement>` |  - | 原生 legend 属性 |

-### Fieldset.Group Props
+### Fieldset.Group

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 分组字段的布局与间距类。 |
-| `children` | `React.ReactNode` | - | 在 fieldset 内分组的表单控件。 |
-| `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | 原生 div 属性。 |
+| `className` | `string` | - | 分组字段的布局与间距类 |
+| `children` | `React.ReactNode` | - | fieldset 内要分组的表单控件 |
+| `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | 原生 div 属性 |

-### Fieldset.Actions Props
+### Fieldset.Actions

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 用于对齐操作按钮或辅助文本的 Tailwind 类。 |
-| `children` | `React.ReactNode` | - | 操作按钮或辅助文本。 |
-| `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | 原生 div 属性。 |
+| `className` | `string` | - | 对齐操作按钮或文本的 Tailwind 类 |
+| `children` | `React.ReactNode` | - | 操作按钮或辅助文本 |
+| `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | 原生 div 属性 |
+
+## 相关案例
+
+<RelatedShowcases component="Fieldset" />
+
+## 相关组件
+
+<RelatedComponents component="fieldset" />
@@ -1,24 +1,20 @@
 ---
 title: Form 表单
-description: 用于表单校验与提交处理的包装组件。
+description: 用于表单校验与提交处理的包裹组件
 links:
  source: form/form.tsx
  rac: https://react-spectrum.adobe.com/react-aria/Form.html
 ---

-## 引入
+## 用法

 ```tsx
 import { Form } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="form-basic" />

-### 组件结构
-
-引入所有组件部分，并自由组合：
+## 组件结构

 ```tsx
 import {Form, Button} from '@heroui/react';
@@ -32,90 +28,100 @@ export default () => (
 )
 ```

-### 自定义渲染函数
+## 示例
+
+### 渲染函数

 <ComponentPreview
-  name="form-custom-render-function"
+  name="form-render-function"
 />

-<RelatedComponents component="form" />
+## 自定义样式

-<RelatedShowcases component="Form" />
+### Tailwind CSS

-## 样式
+<ComponentPreview name="form-custom-styles" />

-### 传入 Tailwind CSS 类
+### 全局 CSS

-```tsx
-import {Form, TextField, Label, Input, FieldError, Button} from '@heroui/react';
+要自定义表单布局与间距，可在 `<Form>` 上使用 `className` prop，或通过 `@layer components` 添加项目级类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

-function CustomForm() {
-  return (
-    <Form className="w-full max-w-md space-y-4 rounded-lg border border-border bg-surface p-6">
-      <TextField>
-        <Label className="text-sm font-medium">Email</Label>
-        <Input className="rounded-full border-border/60" placeholder="Enter your email" />
-        <FieldError className="text-xs" />
-      </TextField>
-      <Button type="submit" className="w-full">
-        Submit
-      </Button>
-    </Form>
-  );
+`Form` 渲染原生 `<form>` 元素，聚焦校验与提交。`@heroui/styles` 中无专用 BEM 类——从全局 CSS 应用容器样式，控件级自定义请使用字段组件。
+
+```css
+@layer components {
+  .form-layout {
+    @apply flex flex-col gap-4 rounded-xl border border-border bg-surface p-4 shadow-sm;
+  }
 }
 ```

+```tsx
+<Form className="form-layout" onSubmit={handleSubmit}>
+  {/* TextField, Input, Button, etc. */}
+</Form>
+```
+
+分组字段与共享布局请使用 [Fieldset](./fieldset)，并定位 `.fieldset`、`.fieldset__legend` 等相关类。单个控件请参阅 [TextField](./text-field)、[Input](./input)、[Label](./label)、[FieldError](./field-error) 的 **Global CSS** 部分。
+
+## 样式参考
+
+HeroUI 对在 `@heroui/styles` 中提供样式的组件遵循 [BEM](https://getbem.com/) 方法论。
+
+`Form` 渲染原生 `<form>` 元素，无专用 BEM 类。通过 `className` 应用布局、间距与表面样式。字段外观与校验状态来自 `TextField`、`Input`、`Label`、`Description`、`FieldError` 等子组件。结构化多字段布局请与 [Fieldset](./fieldset) 组合使用。
+
 ## API 参考

-### Form Props
+### Form

-Form 组件是对 React Aria `Form` 原语的封装，提供表单校验与提交处理能力。
+Form 组件是 React Aria Form 原语的包裹层，提供表单校验与提交处理能力。

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `action` | `string \| FormHTMLAttributes['action']` | - | 表单数据提交的目标 URL。 |
-| `className` | `string` | - | 应用到 form 元素上的 Tailwind CSS 类。 |
-| `children` | `React.ReactNode` | - | 表单内容（字段、按钮等）。 |
-| `encType` | `'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'` | - | 表单数据提交时的编码类型。 |
-| `method` | `'get' \| 'post'` | - | 提交表单时使用的 HTTP 方法。 |
-| `onInvalid` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单校验失败时调用的处理函数。默认会聚焦第一个无效字段，使用 `preventDefault()` 可自定义聚焦行为。 |
-| `onReset` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单被重置时调用的处理函数。 |
-| `onSubmit` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单被提交时调用的处理函数。 |
-| `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | - | 提交表单后响应的展示位置。 |
-| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用浏览器原生 HTML 校验还是 ARIA 校验。`'native'` 会阻止表单提交，`'aria'` 会实时显示错误。 |
-| `validationErrors` | `ValidationErrors` | - | 按字段名映射的服务端校验错误。错误会立即展示，并在用户修改字段后自动清除。 |
-| `aria-label` | `string` | - | 表单的无障碍标签。 |
-| `aria-labelledby` | `string` | - | 用于为表单提供标签的元素 ID。提供后会创建 form landmark。 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+|------|------|---------|-------------|
+| `action` | `string \| FormHTMLAttributes['action']` | - | 提交表单数据的 URL |
+| `className` | `string` | - | 应用于 form 元素的 Tailwind CSS 类 |
+| `children` | `React.ReactNode` | - | 表单内容（字段、按钮等） |
+| `encType` | `'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'` | - | 表单数据提交的编码类型 |
+| `method` | `'get' \| 'post'` | - | 提交表单时使用的 HTTP 方法 |
+| `onInvalid` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单校验失败时调用。默认聚焦第一个无效字段。使用 `preventDefault()` 可自定义聚焦行为 |
+| `onReset` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单重置时调用 |
+| `onSubmit` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单提交时调用 |
+| `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | - | 提交后显示响应的位置 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 校验还是 ARIA 校验。`native` 阻止提交，`aria` 实时显示错误 |
+| `validationErrors` | `ValidationErrors` | - | 按字段名映射的服务端校验错误。立即显示，用户修改字段时清除 |
+| `aria-label` | `string` | - | 表单的无障碍标签 |
+| `aria-labelledby` | `string` | - | 标注表单的元素 ID。提供时创建 form landmark |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### 表单校验
+### Form Validation

-Form 组件集成了 React Aria 的校验体系，你可以：
+Form 组件集成 React Aria 校验系统，支持：

- 使用内置的 HTML5 校验属性（`required`、`minLength`、`pattern` 等）
- 在 TextField 等组件上提供自定义校验函数
- 通过 FieldError 组件展示校验错误
- 在提交时进行完整的校验处理
+- 使用内置 HTML5 校验属性（`required`、`minLength`、`pattern` 等）
+- 在 TextField 组件上提供自定义校验函数
+- 使用 FieldError 组件展示校验错误
+- 在正确校验后处理表单提交
 - 通过 `validationErrors` prop 提供服务端校验错误

-#### 校验行为
+#### Validation Behavior

-`validationBehavior` prop 控制校验信息的展示方式：
+`validationBehavior` prop 控制校验展示方式：

- **`native`**（默认）：使用浏览器原生 HTML 校验，发生错误时阻止表单提交。
- **`aria`**：使用 ARIA 属性进行校验，在用户输入时实时显示错误，且不会阻止提交。
+- **`native`**（默认）：使用原生 HTML 校验，有错误时阻止提交
+- **`aria`**：使用 ARIA 属性校验，用户输入时实时显示错误，不阻止提交

-该行为可以在 form 层级设置，也可以在单个字段层级覆盖。
+可在表单级或单个字段级设置此行为。

-### 表单提交
+### Form Submission

-表单可以通过多种方式提交：
+表单可通过多种方式提交：

- **传统提交**：设置 `action` prop 提交到一个 URL
- **JavaScript 处理**：使用 `onSubmit` 处理函数处理表单数据
- **FormData API**：在提交处理函数中使用 FormData API 读取表单数据
+- **传统提交**：设置 `action` prop 提交到 URL
+- **JavaScript 处理**：使用 `onSubmit` 处理表单数据
+- **FormData API**：在 submit 处理函数中使用 FormData API 访问表单数据

-使用 FormData 的示例：
+FormData 示例：

 ```tsx
 function handleSubmit(e: FormEvent<HTMLFormElement>) {
@@ -126,33 +132,41 @@ function handleSubmit(e: FormEvent<HTMLFormElement>) {
 }
 ```

-### 与表单字段集成
+### Integration with Form Fields

-Form 组件可与 HeroUI 的所有表单字段组件无缝配合：
+Form 组件与 HeroUI 表单字段组件无缝协作：

 - **TextField**：带标签与校验的文本输入
 - **Checkbox**：布尔选择
- **RadioGroup**：从多个选项中单选
- **Switch**：切换控件
- **Button**：用于表单提交与重置
+- **RadioGroup**：多选一
+- **Switch**：开关控件
+- **Button**：提交与重置操作

-所有字段组件在置于 Form 内部时，都会自动接入 Form 的校验与提交行为。
+所有字段组件放在 Form 内时会自动集成 Form 的校验与提交行为。

-### 无障碍
+### Advanced Usage

-使用 React Aria 组件时，表单默认即具备良好的无障碍能力，主要特性包括：
+更高级用法包括：
+- 自定义校验上下文
+- 表单 context provider
+- 与第三方库集成
+- 校验错误时的自定义焦点管理
+
+请参阅 [React Aria Form 文档](https://react-spectrum.adobe.com/react-aria/Form.html)。
+
+## 无障碍
+
+使用 React Aria 组件时，表单默认可访问。主要特性包括：

 - 原生 `<form>` 元素语义
- 通过 `aria-label` 或 `aria-labelledby` 创建 form landmark
- 校验失败时自动聚焦管理
- 设置 `validationBehavior="aria"` 时使用 ARIA 校验属性
+- 使用 `aria-label` 或 `aria-labelledby` 创建 form landmark
+- 校验错误时自动焦点管理
+- 使用 `validationBehavior="aria"` 时的 ARIA 校验属性

-### 进阶用法
+## 相关案例

-更高级的使用场景，包括：
- 自定义校验上下文
- Form context provider
- 与第三方库的集成
- 校验错误时的自定义聚焦管理
+<RelatedShowcases component="Form" />

-请参考 [React Aria Form 文档](https://react-spectrum.adobe.com/react-aria/Form.html)。
+## 相关组件
+
+<RelatedComponents component="form" />
@@ -1,6 +1,6 @@
 ---
 title: InputGroup 输入框组
-description: 将相关输入控件与前后缀元素组合，以增强表单字段。
+description: 将相关输入控件与前后缀元素组合，以增强表单字段
 links:
  rac: Group
  source: input-group/input-group.tsx
@@ -9,17 +9,15 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { InputGroup } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="input-group-default" />

-### 组件结构
+## 组件结构

 ```tsx
 import {InputGroup, TextField, Label} from '@heroui/react';
@@ -38,23 +36,44 @@ export default () => (

 > **InputGroup** 使用可选的前缀与后缀包裹输入框，形成视觉上统一的组合。通常放在 **[TextField](/docs/components/text-field)** 内，用于在输入前后添加图标、文字、按钮等元素。单行输入请使用 **InputGroup.Input**，多行输入请使用 **InputGroup.TextArea**。

-### 前缀图标
+## 示例

-在输入框前添加图标。
+### 变体

-<ComponentPreview name="input-group-with-prefix-icon" />
+InputGroup 组件支持两种视觉变体：

-### 后缀图标
+- **`primary`**（默认）- 标准样式带阴影，适用于大多数场景
+- **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内

-在输入框后添加图标。
+<ComponentPreview name="input-group-variants" />

-<ComponentPreview name="input-group-with-suffix-icon" />
+### 表面样式

-### 前缀与后缀
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。

-同时组合前缀与后缀。
+<ComponentPreview name="input-group-on-surface" />

-<ComponentPreview name="input-group-with-prefix-and-suffix" />
+### 后缀加载状态
+
+在后缀显示加载 spinner 以表示正在处理。
+
+<ComponentPreview name="input-group-with-loading-suffix" />
+
+### 必填字段
+
+InputGroup 会遵循父级 TextField 的必填状态。
+
+<ComponentPreview name="input-group-required" />
+
+### 禁用状态
+
+InputGroup 会遵循父级 TextField 的禁用状态。
+
+<ComponentPreview name="input-group-disabled" />
+
+### 宽度充满
+
+<ComponentPreview name="input-group-full-width" />

 ### 文字前缀

@@ -86,239 +105,55 @@ export default () => (

 <ComponentPreview name="input-group-with-icon-prefix-and-copy-suffix" />

-### 密码显隐切换
+### 密码可见性切换

 在后缀中使用按钮切换密码可见性。

 <ComponentPreview name="input-group-password-with-toggle" />

-### 加载状态
-
-在后缀显示加载指示器，表示正在处理。
-
-<ComponentPreview name="input-group-with-loading-suffix" />
-
 ### 键盘快捷键

 使用 [Kbd](/docs/components/kbd) 组件展示键盘快捷键。

 <ComponentPreview name="input-group-with-keyboard-shortcut" />

-### Badge 后缀
+### 徽章后缀

 在后缀中加入徽章或 chip，用于展示状态或标签。

 <ComponentPreview name="input-group-with-badge-suffix" />

-### 必填字段
-
-InputGroup 会遵循父级 TextField 的必填状态。
-
-<ComponentPreview name="input-group-required" />
-
-### 校验
+### 表单校验

 InputGroup 会自动反映父级 TextField 的无效状态。

 <ComponentPreview name="input-group-invalid" />

-### 禁用状态
+### 前缀图标

-InputGroup 会遵循父级 TextField 的禁用状态。
+在输入框前添加图标。

-<ComponentPreview name="input-group-disabled" />
+<ComponentPreview name="input-group-with-prefix-icon" />

-### 全宽
+### 后缀图标

-<ComponentPreview name="input-group-full-width" />
+在输入框后添加图标。

-### 变体
+<ComponentPreview name="input-group-with-suffix-icon" />

-InputGroup 支持两种视觉变体：
+### 前缀与后缀

- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
- **`secondary`** — 低强调、无阴影的变体，适合用在 Surface 组件内
+同时组合前缀与后缀。

-<ComponentPreview name="input-group-variants" />
+<ComponentPreview name="input-group-with-prefix-and-suffix" />

-### 在 Surface 内
-
-在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
-
-<ComponentPreview name="input-group-on-surface" />
-
-### 搭配 TextArea
+### 文本域

 多行输入请使用 **InputGroup.TextArea**，并搭配前缀与后缀。当存在 textarea 时，容器高度会自动适应内容，并将前缀/后缀与顶部对齐。

 <ComponentPreview name="input-group-with-textarea" />

-<RelatedComponents component="inputgroup" />
-
-<RelatedShowcases component="InputGroup" />
-
-## 样式
-
-### 传入 Tailwind CSS 类
-
-```tsx
-import {InputGroup, TextField, Label} from '@heroui/react';
-
-function CustomInputGroup() {
-  return (
-    <TextField>
-      <Label>Website</Label>
-      <InputGroup className="rounded-xl border-2 border-primary">
-        <InputGroup.Prefix className="bg-primary/10 text-primary">
-          https://
-        </InputGroup.Prefix>
-        <InputGroup.Input className="font-medium" />
-        <InputGroup.Suffix className="bg-primary/10 text-primary">
-          .com
-        </InputGroup.Suffix>
-      </InputGroup>
-    </TextField>
-  );
-}
-```
-
-### 自定义组件类
-
-InputGroup 使用可自定义的 CSS 类。你可以覆盖这些类名以匹配自己的设计系统。
-
-```css
-@layer components {
-  .input-group {
-    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex min-h-9 items-center overflow-hidden border text-sm outline-none;
-  }
-
-  .input-group__input {
-    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
-  }
-
-  .input-group__prefix {
-    @apply text-field-placeholder rounded-l-field flex h-full items-center justify-center rounded-r-none bg-transparent px-3;
-  }
-
-  .input-group__suffix {
-    @apply text-field-placeholder rounded-r-field flex h-full items-center justify-center rounded-l-none bg-transparent px-3;
-  }
-
-  /* Secondary variant */
-  .input-group--secondary {
-    @apply shadow-none;
-    background-color: var(--color-default);
-  }
-}
-```
-
-### CSS 类
-
- `.input-group` – 根容器：带边框、背景与 flex 布局。默认使用 `min-h-9` 与 `items-center`；当存在 textarea 时会切换为 `items-start`。
- `.input-group__input` – 透明背景、无边框的输入元素。textarea 也使用该基础类。
- `.input-group__prefix` – 左侧圆角的前缀容器。与 textarea 搭配时与顶部对齐。
- `.input-group__suffix` – 右侧圆角的后缀容器。与 textarea 搭配时与顶部对齐。
- `.input-group--primary` – 带阴影的主变体（默认）
- `.input-group--secondary` – 无阴影的次变体，适合用在 surface 上
-
-**说明：** 使用 `InputGroup.TextArea` 时，容器会从 `items-center` 切换为 `items-start`，并使用 `height: auto` 替代固定高度。前缀与后缀与顶部对齐，并增加内边距以匹配 textarea 的垂直内边距。textarea 使用相同的 `.input-group__input` 基础类，并通过 `[data-slot="input-group-textarea"]` 选择器应用 textarea 专用样式（最小高度与纵向 resize）。
-
-### 交互状态
-
-InputGroup 会根据状态自动管理以下 data 属性：
-
- **Hover**：`[data-hovered]` – 悬停在整个组合上时应用
- **Focus Within**：`[data-focus-within]` – 输入框聚焦时应用
- **Invalid**：`[data-invalid]` – 父级 TextField 为无效时应用
- **Disabled**：`[data-disabled]` 或 `[aria-disabled]` – 父级 TextField 为禁用时应用
-
-## API 参考
-
-### InputGroup Props
-
-InputGroup 继承 React Aria [Group](https://react-spectrum.adobe.com/react-aria/Group.html) 组件的全部 props。
-
-#### Base Props
-
-| Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | 子组件（Input、TextArea、Prefix、Suffix）或渲染函数。 |
-| `className` | `string \| (values: GroupRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 |
-| `style` | `React.CSSProperties \| (values: GroupRenderProps) => React.CSSProperties` | - | 行内样式，支持渲染 prop。 |
-| `fullWidth` | `boolean` | `false` | 输入组是否占满容器宽度 |
-| `id` | `string` | - | 元素的唯一标识符。 |
-
-#### Variant Props
-
-| Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
-
-#### Accessibility Props
-
-| Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `aria-label` | `string` | - | 没有可见标签时的无障碍标签。 |
-| `aria-labelledby` | `string` | - | 用于标注该组的元素 ID。 |
-| `aria-describedby` | `string` | - | 用于描述该组的元素 ID。 |
-| `aria-details` | `string` | - | 包含更多详情的元素 ID。 |
-| `role` | `'group' \| 'region' \| 'presentation'` | `'group'` | 分组的无障碍角色。重要内容可使用 `region`，纯视觉分组可使用 `presentation`。 |
-
-### Composition Components
-
-InputGroup 与以下子组件配合使用：
-
- **InputGroup.Root** – 根容器（也可直接写作 `InputGroup`）
- **InputGroup.Input** – 单行输入元素组件
- **InputGroup.TextArea** – 多行 textarea 元素组件
- **InputGroup.Prefix** – 前缀容器组件
- **InputGroup.Suffix** – 后缀容器组件
-
-#### InputGroup.Input Props
-
-InputGroup.Input 继承 React Aria [Input](https://react-spectrum.adobe.com/react-aria/Input.html) 组件的全部 props。
-
-| Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `className` | `string` | - | 用于样式的 CSS 类。 |
-| `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
-| `type` | `string` | `'text'` | 输入类型（text、password、email 等）。 |
-| `value` | `string` | - | 当前值（受控）。 |
-| `defaultValue` | `string` | - | 默认值（非受控）。 |
-| `placeholder` | `string` | - | 占位符文本。 |
-| `disabled` | `boolean` | - | 是否禁用输入。 |
-| `readOnly` | `boolean` | - | 是否只读。 |
-
-#### InputGroup.TextArea Props
-
-InputGroup.TextArea 继承 React Aria [TextArea](https://react-spectrum.adobe.com/react-aria/TextArea.html) 组件的全部 props。
-
-| Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `className` | `string` | - | 用于样式的 CSS 类。 |
-| `variant` | `"primary" \| "secondary"` | `"primary"` | textarea 的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
-| `value` | `string` | - | 当前值（受控）。 |
-| `defaultValue` | `string` | - | 默认值（非受控）。 |
-| `placeholder` | `string` | - | 占位符文本。 |
-| `rows` | `number` | - | 可见文本行数。 |
-| `disabled` | `boolean` | - | 是否禁用 textarea。 |
-| `readOnly` | `boolean` | - | 是否只读。 |
-
-#### InputGroup.Prefix Props
-
-| Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `children` | `React.ReactNode` | - | 前缀中要展示的内容（图标、文字等）。 |
-| `className` | `string` | - | 用于样式的 CSS 类。 |
-
-#### InputGroup.Suffix Props
-
-| Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `children` | `React.ReactNode` | - | 后缀中要展示的内容（图标、按钮、徽章等）。 |
-| `className` | `string` | - | 用于样式的 CSS 类。 |
-
-### Usage Example
+### 用法示例

 ```tsx
 import {InputGroup, TextField, Label, Button} from '@heroui/react';
@@ -344,7 +179,7 @@ function Example() {
 }
 ```

-### TextArea Usage Example
+### 文本域用法示例

 ```tsx
 import {Envelope} from "@gravity-ui/icons";
@@ -377,3 +212,162 @@ function TextAreaExample() {
  );
 }
 ```
+
+## 自定义样式
+
+### Tailwind CSS
+
+<ComponentPreview name="input-group-custom-styles" />
+
+### 全局 CSS
+
+InputGroup 使用可自定义的 CSS 类。覆盖组件类以匹配设计系统。
+
+```css
+@layer components {
+  .input-group {
+    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex min-h-9 items-center overflow-hidden border text-sm outline-none;
+  }
+
+  .input-group__input {
+    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .input-group__prefix {
+    @apply text-field-placeholder rounded-l-field flex h-full items-center justify-center rounded-r-none bg-transparent px-3;
+  }
+
+  .input-group__suffix {
+    @apply text-field-placeholder rounded-r-field flex h-full items-center justify-center rounded-l-none bg-transparent px-3;
+  }
+
+  /* Secondary variant */
+  .input-group--secondary {
+    @apply shadow-none;
+    background-color: var(--color-default);
+  }
+}
+```
+
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+#### 基础类 [!toc]
+
+- `.input-group` – 根容器：带边框、背景与 flex 布局。默认 `min-h-9` 与 `items-center`；存在 textarea 时切换为 `items-start`
+- `.input-group__input` – 透明背景、无边框的输入元素。textarea 也使用该基础类
+- `.input-group__prefix` – 左侧圆角的前缀容器。与 textarea 搭配时与顶部对齐
+- `.input-group__suffix` – 右侧圆角的后缀容器。与 textarea 搭配时与顶部对齐
+
+#### 变体类 [!toc]
+
+- `.input-group--primary` – 带阴影的主变体（默认）
+- `.input-group--secondary` – 无阴影的次变体，适用于 Surface 内
+
+**Note：** 使用 `InputGroup.TextArea` 时，容器从 `items-center` 切换为 `items-start`，并使用 `height: auto` 替代固定高度。前缀与后缀与顶部对齐，并增加内边距以匹配 textarea 的垂直内边距。textarea 使用相同的 `.input-group__input` 基础类，并通过 `[data-slot="input-group-textarea"]` 选择器应用 textarea 专用样式（最小高度与纵向 resize）。
+
+### 交互状态
+
+InputGroup 会根据状态自动管理以下 data 属性：
+
+- **Hover**：`[data-hovered]` - 悬停在组合上时应用
+- **Focus Within**：`[data-focus-within]` - 输入聚焦时应用
+- **Invalid**：`[data-invalid]` - 父级 TextField 无效时应用
+- **Disabled**：`[data-disabled]` 或 `[aria-disabled]` - 父级 TextField 禁用时应用
+
+## API 参考
+
+### InputGroup
+
+InputGroup 继承 React Aria [Group](https://react-spectrum.adobe.com/react-aria/Group.html) 组件的全部 props。
+
+#### Base Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | 子组件（Input、TextArea、Prefix、Suffix）或 render 函数 |
+| `className` | `string \| (values: GroupRenderProps) => string` | - | CSS 类，支持 render props |
+| `style` | `React.CSSProperties \| (values: GroupRenderProps) => React.CSSProperties` | - | 行内样式，支持 render props |
+| `fullWidth` | `boolean` | `false` | 输入组是否占满容器宽度 |
+| `id` | `string` | - | 元素唯一标识符 |
+
+#### Variant Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 |
+
+#### Accessibility Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | 无可见标签时的无障碍标签 |
+| `aria-labelledby` | `string` | - | 标注该组的元素 ID |
+| `aria-describedby` | `string` | - | 描述该组的元素 ID |
+| `aria-details` | `string` | - | 包含更多详情的元素 ID |
+| `role` | `'group' \| 'region' \| 'presentation'` | `'group'` | 分组的无障碍角色。重要内容用 `region`，纯视觉分组用 `presentation` |
+
+### Composition Components
+
+InputGroup 与以下子组件配合使用：
+
+- **InputGroup.Root** - 根容器（也可写作 `InputGroup`）
+- **InputGroup.Input** - 单行输入元素组件
+- **InputGroup.TextArea** - 多行 textarea 元素组件
+- **InputGroup.Prefix** - 前缀容器组件
+- **InputGroup.Suffix** - 后缀容器组件
+
+#### InputGroup.Input
+
+InputGroup.Input 继承 React Aria [Input](https://react-spectrum.adobe.com/react-aria/Input.html) 组件的全部 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | CSS 类 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 输入视觉变体 |
+| `type` | `string` | `'text'` | 输入类型（text、password、email 等） |
+| `value` | `string` | - | 当前值（受控） |
+| `defaultValue` | `string` | - | 默认值（非受控） |
+| `placeholder` | `string` | - | 占位文本 |
+| `disabled` | `boolean` | - | 是否禁用 |
+| `readOnly` | `boolean` | - | 是否只读 |
+
+#### InputGroup.TextArea
+
+InputGroup.TextArea 继承 React Aria [TextArea](https://react-spectrum.adobe.com/react-aria/TextArea.html) 组件的全部 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | CSS 类 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | textarea 视觉变体 |
+| `value` | `string` | - | 当前值（受控） |
+| `defaultValue` | `string` | - | 默认值（非受控） |
+| `placeholder` | `string` | - | 占位文本 |
+| `rows` | `number` | - | 可见文本行数 |
+| `disabled` | `boolean` | - | 是否禁用 |
+| `readOnly` | `boolean` | - | 是否只读 |
+
+#### InputGroup.Prefix
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 前缀内容（图标、文字等） |
+| `className` | `string` | - | CSS 类 |
+
+#### InputGroup.Suffix
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 后缀内容（图标、按钮、徽章等） |
+| `className` | `string` | - | CSS 类 |
+
+## 相关案例
+
+<RelatedShowcases component="InputGroup" />
+
+## 相关组件
+
+<RelatedComponents component="inputgroup" />
@@ -1,6 +1,6 @@
 ---
-title: InputOTP 一次性密码输入框
-description: 用于验证码与安全认证等场景的一次性密码输入组件。
+title: InputOTP 一次性密码输入
+description: 用于验证码与安全认证的一次性密码输入组件
 links:
  source: input-otp/input-otp.tsx
  styles: input-otp.css
@@ -8,19 +8,15 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { InputOTP } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="input-otp-basic" />

-### 组件结构
-
-引入 InputOTP 后，可通过点语法访问各个部分。
+## 组件结构

 ```tsx
 import { InputOTP } from '@heroui/react';
@@ -41,118 +37,73 @@ export default () => (
 )
 ```

-> **InputOTP** 基于 [@guilherme_rodz](https://twitter.com/guilherme_rodz) 的 [input-otp](https://github.com/guilhermerodz/input-otp) 构建，为 OTP 输入组件提供灵活且无障碍的基础能力。
+> **InputOTP** 基于 [@guilherme_rodz](https://twitter.com/guilherme_rodz) 的 [input-otp](https://github.com/guilhermerodz/input-otp) 构建，为 OTP 输入组件提供灵活且无障碍的基础。

-### 四位数字
+## 示例

-<ComponentPreview name="input-otp-four-digits" />
+### 变体
+
+InputOTP 组件支持两种视觉变体：
+
+- **`primary`**（默认）- 标准样式带阴影，适用于大多数场景
+- **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内
+
+<ComponentPreview name="input-otp-variants" />
+
+### 表面样式
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。
+
+<ComponentPreview name="input-otp-on-surface" />

 ### 禁用状态

 <ComponentPreview name="input-otp-disabled" />

-### 使用 pattern
+### 四位验证码

-使用 `pattern` prop 限制可输入字符。HeroUI 会导出常用模式，例如 `REGEXP_ONLY_CHARS` 与 `REGEXP_ONLY_DIGITS`。
+<ComponentPreview name="input-otp-four-digits" />

-<ComponentPreview name="input-otp-with-pattern" />
+### 受控组件

-### 受控
-
-控制值以同步状态、清空输入或实现自定义校验。
+控制 value 以与状态同步、清空输入或实现自定义校验。

 <ComponentPreview name="input-otp-controlled" />

-### 带校验
+### 输入完成回调

-将 `isInvalid` 与校验消息一起使用以展示错误。
-
-<ComponentPreview name="input-otp-with-validation" />
-
-### 完成回调
-
-在所有槽位填满时使用 `onComplete` 回调触发逻辑。
+使用 `onComplete` 回调在所有 slot 填满时触发操作。

 <ComponentPreview name="input-otp-on-complete" />

 ### 表单示例

-包含校验与提交的完整双因素认证表单。
+完整的双因素认证表单，含校验与提交。

 <ComponentPreview name="input-otp-form-example" />

-### 变体
+### 限定格式

-InputOTP 支持两种视觉变体：
+使用 `pattern` prop 限制输入字符。HeroUI 导出 `REGEXP_ONLY_CHARS`、`REGEXP_ONLY_DIGITS` 等常用模式。

- **`primary`**（默认）— 常规带阴影样式，适用于大多数场景
- **`secondary`** — 弱强调、无阴影变体，适合用于 Surface 组件内部
+<ComponentPreview name="input-otp-with-pattern" />

-<ComponentPreview name="input-otp-variants" />
+### 带校验

-### 在 Surface 内
+配合 `isInvalid` 与校验消息展示错误。

-在 [Surface](/docs/components/surface) 组件内部使用时，请使用 `variant="secondary"`，以应用适合 surface 背景的弱强调变体。
+<ComponentPreview name="input-otp-with-validation" />

-<ComponentPreview name="input-otp-on-surface" />
+## 自定义样式

-<RelatedComponents component="inputotp" />
+### Tailwind CSS

-## 样式
+<ComponentPreview name="input-otp-custom-styles" />

-### 传入 Tailwind CSS 类
+### 全局 CSS

-```tsx
-import {InputOTP, Label} from '@heroui/react';
-
-function CustomInputOTP() {
-  return (
-    <div className="flex flex-col gap-2">
-      <Label className="text-sm font-semibold">Enter verification code</Label>
-      <InputOTP
-        className="gap-3"
-        containerClassName="gap-4"
-        maxLength={6}
-      >
-        <InputOTP.Group className="gap-3">
-          <InputOTP.Slot
-            className="size-12 rounded-lg border-2 text-lg font-bold"
-            index={0}
-          />
-          <InputOTP.Slot
-            className="size-12 rounded-lg border-2 text-lg font-bold"
-            index={1}
-          />
-          <InputOTP.Slot
-            className="size-12 rounded-lg border-2 text-lg font-bold"
-            index={2}
-          />
-        </InputOTP.Group>
-        <InputOTP.Separator className="bg-border h-1 w-2 rounded-full" />
-        <InputOTP.Group className="gap-3">
-          <InputOTP.Slot
-            className="size-12 rounded-lg border-2 text-lg font-bold"
-            index={3}
-          />
-          <InputOTP.Slot
-            className="size-12 rounded-lg border-2 text-lg font-bold"
-            index={4}
-          />
-          <InputOTP.Slot
-            className="size-12 rounded-lg border-2 text-lg font-bold"
-            index={5}
-          />
-        </InputOTP.Group>
-      </InputOTP>
-    </div>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 InputOTP 的组件类名，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 InputOTP 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -174,106 +125,108 @@ function CustomInputOTP() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-InputOTP 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/input-otp.css)）：
+InputOTP 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/input-otp.css)）：

-#### 基础类
- `.input-otp` - 根容器
- `.input-otp__container` - input-otp 库提供的内层容器
- `.input-otp__group` - 槽位分组
- `.input-otp__slot` - 单个输入槽位
- `.input-otp__slot-value` - 槽位内的字符
- `.input-otp__caret` - 闪烁的光标指示器
- `.input-otp__separator` - 分组之间的视觉分隔符
+#### 基础类 [!toc]
+- `.input-otp` - 基础容器
+- `.input-otp__container` - input-otp 库的内部容器
+- `.input-otp__group` - slot 组
+- `.input-otp__slot` - 单个输入 slot
+- `.input-otp__slot-value` - slot 内的字符
+- `.input-otp__caret` - 闪烁光标指示器
+- `.input-otp__separator` - 组之间的视觉分隔符

-#### 状态类
- `.input-otp__slot[data-active="true"]` - 当前激活的槽位
- `.input-otp__slot[data-filled="true"]` - 已填入字符的槽位
- `.input-otp__slot[data-disabled="true"]` - 禁用的槽位
- `.input-otp__slot[data-invalid="true"]` - 无效的槽位
+#### 状态类 [!toc]
+- `.input-otp__slot[data-active="true"]` - 当前激活的 slot
+- `.input-otp__slot[data-filled="true"]` - 含字符的 slot
+- `.input-otp__slot[data-disabled="true"]` - 禁用的 slot
+- `.input-otp__slot[data-invalid="true"]` - 无效的 slot
 - `.input-otp__container[data-disabled="true"]` - 禁用的容器

 ### 交互状态

-组件同时支持 CSS 伪类与 data 属性，以获得更好的灵活性：
+组件同时支持 CSS 伪类与 data 属性：

- **悬停**：槽位上的 `:hover` 或 `[data-hovered="true"]`
- **激活**：槽位上的 `[data-active="true"]`（当前聚焦）
- **已填**：槽位上的 `[data-filled="true"]`（包含字符）
- **禁用**：容器与槽位上的 `[data-disabled="true"]`
- **无效**：槽位上的 `[data-invalid="true"]`
+- **Hover**：slot 上 `:hover` 或 `[data-hovered="true"]`
+- **Active**：slot 上 `[data-active="true"]`（当前聚焦）
+- **Filled**：slot 上 `[data-filled="true"]`（含字符）
+- **Disabled**：容器与 slot 上 `[data-disabled="true"]`
+- **Invalid**：slot 上 `[data-invalid="true"]`

 ## API 参考

-### InputOTP Props
+### InputOTP

-InputOTP 在 [input-otp](https://github.com/guilhermerodz/input-otp) 库之上构建，并增加了额外能力。
+InputOTP 基于 [input-otp](https://github.com/guilhermerodz/input-otp) 库构建，并附加额外特性。

 #### Base Props

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `maxLength` | `number` | - | **必填。** 输入槽位数量。 |
-| `value` | `string` | - | 受控值（未提供则为非受控）。 |
-| `onChange` | `(value: string) => void` | - | 值变化时调用。 |
-| `onComplete` | `(value: string) => void` | - | 所有槽位填满时调用。 |
-| `className` | `string` | - | 容器的额外 CSS 类名。 |
-| `containerClassName` | `string` | - | 内层容器的 CSS 类名。 |
-| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为弱强调、无阴影变体，适合用于 surface 上。 |
-| `children` | `React.ReactNode` | - | InputOTP.Group、InputOTP.Slot 与 InputOTP.Separator 组件。 |
+|------|------|---------|-------------|
+| `maxLength` | `number` | - | **必填。** 输入 slot 数量 |
+| `value` | `string` | - | 受控值（未提供则为非受控） |
+| `onChange` | `(value: string) => void` | - | 值变化时的回调 |
+| `onComplete` | `(value: string) => void` | - | 所有 slot 填满时的回调 |
+| `className` | `string` | - | 容器的附加 CSS 类 |
+| `containerClassName` | `string` | - | 内部容器的 CSS 类 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 |
+| `children` | `React.ReactNode` | - | InputOTP.Group、InputOTP.Slot 与 InputOTP.Separator 组件 |

 #### Validation Props

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `isDisabled` | `boolean` | `false` | 是否禁用输入。 |
-| `isInvalid` | `boolean` | `false` | 输入是否处于无效状态。 |
-| `validationErrors` | `string[]` | - | 服务端或自定义校验错误。 |
-| `validationDetails` | `ValidityState` | - | HTML5 校验详情。 |
+|------|------|---------|-------------|
+| `isDisabled` | `boolean` | `false` | 是否禁用 |
+| `isInvalid` | `boolean` | `false` | 是否处于无效状态 |
+| `validationErrors` | `string[]` | - | 服务端或自定义校验错误 |
+| `validationDetails` | `ValidityState` | - | HTML5 校验详情 |

 #### Input Props

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `pattern` | `string` | - | 允许字符的正则表达式（例如 `REGEXP_ONLY_DIGITS`）。 |
-| `textAlign` | `'left' \| 'center' \| 'right'` | `'left'` | 槽位内文本对齐方式。 |
-| `inputMode` | `'numeric' \| 'text' \| 'decimal' \| 'tel' \| 'search' \| 'email' \| 'url'` | `'numeric'` | 移动设备上的虚拟键盘类型。 |
-| `placeholder` | `string` | - | 空槽位的占位符文本。 |
-| `pasteTransformer` | `(text: string) => string` | - | 转换粘贴文本（例如移除连字符）。 |
+|------|------|---------|-------------|
+| `pattern` | `string` | - | 允许字符的正则模式（如 `REGEXP_ONLY_DIGITS`） |
+| `textAlign` | `'left' \| 'center' \| 'right'` | `'left'` | slot 内文本对齐 |
+| `inputMode` | `'numeric' \| 'text' \| 'decimal' \| 'tel' \| 'search' \| 'email' \| 'url'` | `'numeric'` | 移动设备虚拟键盘类型 |
+| `placeholder` | `string` | - | 空 slot 的占位文本 |
+| `pasteTransformer` | `(text: string) => string` | - | 转换粘贴文本（如移除连字符） |

 #### Form Props

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `name` | `string` | - | 表单提交时使用的 name 属性。 |
-| `autoFocus` | `boolean` | - | 挂载时是否聚焦第一个槽位。 |
+|------|------|---------|-------------|
+| `name` | `string` | - | 表单提交的 name 属性 |
+| `autoFocus` | `boolean` | - | 挂载时是否聚焦第一个 slot |

-### InputOTP.Group Props
+### InputOTP.Group

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `className` | `string` | - | 分组的额外 CSS 类名。 |
-| `children` | `React.ReactNode` | - | InputOTP.Slot 组件。 |
+|------|------|---------|-------------|
+| `className` | `string` | - | 组的附加 CSS 类 |
+| `children` | `React.ReactNode` | - | InputOTP.Slot 组件 |

-### InputOTP.Slot Props
+### InputOTP.Slot

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `index` | `number` | - | **必填。** 槽位从 0 开始的索引。 |
-| `className` | `string` | - | 槽位的额外 CSS 类名。 |
+|------|------|---------|-------------|
+| `index` | `number` | - | **必填。** slot 的从零开始索引 |
+| `className` | `string` | - | slot 的附加 CSS 类 |

-### InputOTP.Separator Props
+### InputOTP.Separator

 | Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `className` | `string` | - | 分隔符的额外 CSS 类名。 |
+|------|------|---------|-------------|
+| `className` | `string` | - | 分隔符的附加 CSS 类 |

-### 导出的 pattern
+### Exported Patterns

-HeroUI 会为了方便而从 input-otp 再导出常用正则 pattern：
+HeroUI 重新导出 input-otp 的常用正则模式以便使用：

 ```tsx
 import { REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS_AND_CHARS } from '@heroui/react';
@@ -284,6 +237,10 @@ import { REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS_AND_CHARS } f
 </InputOTP>
 ```

- **REGEXP_ONLY_DIGITS** — 仅数字字符（0-9）
- **REGEXP_ONLY_CHARS** — 仅字母字符（a-z、A-Z）
- **REGEXP_ONLY_DIGITS_AND_CHARS** — 字母数字字符（0-9、a-z、A-Z）
+- **REGEXP_ONLY_DIGITS** - 仅数字字符（0-9）
+- **REGEXP_ONLY_CHARS** - 仅字母字符（a-z、A-Z）
+- **REGEXP_ONLY_DIGITS_AND_CHARS** - 字母数字字符（0-9、a-z、A-Z）
+
+## 相关组件
+
+<RelatedComponents component="inputotp" />
@@ -1,6 +1,6 @@
 ---
 title: Input 输入框
-description: 单行文本输入原语，可接受标准 HTML 属性。
+description: 接受标准 HTML 属性的原生单行文本输入组件
 links:
  rac: Input
  source: input/input.tsx
@@ -8,73 +8,56 @@ links:
  storybook: Components/Forms/Input
 ---

-## 引入
+## 用法

 ```tsx
 import { Input } from '@heroui/react';
 ```

-<Callout>
-  关于校验、标签与错误信息，请参见 **[TextField](/docs/components/text-field)**。
-</Callout>
-
-### 用法
-
 <ComponentPreview name="input-basic" />

-### Input 类型
+<Callout>
+  校验、标签与错误消息请参阅 **[TextField](/docs/components/text-field)**。
+</Callout>

-<ComponentPreview name="input-types" />
-
-### 受控
-
-<ComponentPreview name="input-controlled" />
-
-### 全宽
-
-<ComponentPreview name="input-full-width" />
+## 示例

 ### 变体

-Input 支持两种视觉变体：
+Input 组件支持两种视觉变体：

- **`primary`**（默认）— 常规样式并带阴影，适用于大多数场景
- **`secondary`** — 弱强调变体，无阴影，适合用于 Surface 组件内
+- **`primary`**（默认）- 标准样式带阴影，适用于大多数场景
+- **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内

 <ComponentPreview name="input-variants" />

-### 在 Surface 内
+### 表面样式

-在 [Surface](/docs/components/surface) 组件内使用时，请使用 `variant="secondary"`，以应用适合表面背景的弱强调变体。
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。

 <ComponentPreview name="input-on-surface" />

-<RelatedComponents component="input" />
+### 宽度充满

-## 样式
+<ComponentPreview name="input-full-width" />

-### 传入 Tailwind CSS 类
+### 输入类型

-```tsx
-import {Input, Label} from '@heroui/react';
+<ComponentPreview name="input-types" />

-function CustomInput() {
-  return (
-    <div className="flex flex-col gap-2">
-      <Label htmlFor="custom-input">Project name</Label>
-      <Input
-        id="custom-input"
-        className="rounded-xl border border-border/70 bgsurface px-4 py-2 text-sm shadow-sm focus-visible:border-primary"
-        placeholder="New web app"
-      />
-    </div>
-  );
-}
-```
+### 受控组件

-### 自定义组件类
+<ComponentPreview name="input-controlled" />

-基础类 `.input` 驱动每个实例。使用 `@layer components` 一次性覆盖即可。
+## 自定义样式
+
+### Tailwind CSS
+
+<ComponentPreview name="input-custom-styles" />
+
+### 全局 CSS
+
+基础类 `.input` 驱动每个实例。使用 `@layer components` 一次性覆盖。

 ```css
@layer components {
@@ -98,44 +81,54 @@ function CustomInput() {
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

- `.input` — 原生 input 元素样式
+#### 基础类 [!toc]
+
+- `.input` – 原生 input 元素样式

 ### 交互状态

- **悬停**：`:hover` 或 `[data-hovered="true"]`
- **可见焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`
- **无效**：`[data-invalid="true"]`（并与 `aria-invalid` 同步）
- **禁用**：`:disabled` 或 `[aria-disabled="true"]`
- **只读**：`[aria-readonly="true"]`
+- **Hover**：`:hover` 或 `[data-hovered="true"]`
+- **Focus Visible**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **Invalid**：`[data-invalid="true"]`（与 `aria-invalid` 同步）
+- **Disabled**：`:disabled` 或 `[aria-disabled="true"]`
+- **Read Only**：`[aria-readonly="true"]`

 ## API 参考

-### Input Props
+### Input

-除标准 HTML `<input>` 属性外，还支持以下 props：
+Input 接受所有标准 HTML `<input>` 属性，以及以下 props：

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 与组件样式合并的 Tailwind 类。 |
-| `type` | `string` | `"text"` | Input 类型（text、email、password、number 等）。 |
-| `value` | `string` | - | 受控值。 |
-| `defaultValue` | `string` | - | 非受控初始值。 |
-| `onChange` | `(event: React.ChangeEvent<HTMLInputElement>) => void` | - | 变更事件处理函数。 |
-| `placeholder` | `string` | - | 占位符文本。 |
-| `disabled` | `boolean` | `false` | 禁用输入框。 |
-| `readOnly` | `boolean` | `false` | 将输入框设为只读。 |
-| `required` | `boolean` | `false` | 将输入框标记为必填。 |
-| `name` | `string` | - | 用于表单提交的 name。 |
-| `autoComplete` | `string` | - | 浏览器自动完成提示。 |
-| `maxLength` | `number` | - | 最大字符数。 |
-| `minLength` | `number` | - | 最小字符数。 |
-| `pattern` | `string` | - | 用于校验的正则表达式。 |
-| `min` | `number \| string` | - | 最小值（用于 number/date 输入）。 |
-| `max` | `number \| string` | - | 最大值（用于 number/date 输入）。 |
-| `step` | `number \| string` | - | 步进间隔（用于 number 输入）。 |
-| `fullWidth` | `boolean` | `false` | 输入框是否占满容器宽度。 |
-| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为无阴影的弱强调变体，适合用于 surface 内。 |
+| `className` | `string` | - | 与组件样式合并的 Tailwind 类 |
+| `type` | `string` | `"text"` | 输入类型（text、email、password、number 等） |
+| `value` | `string` | - | 受控值 |
+| `defaultValue` | `string` | - | 非受控初始值 |
+| `onChange` | `(event: React.ChangeEvent<HTMLInputElement>) => void` | - | 变化处理函数 |
+| `placeholder` | `string` | - | 占位文本 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readOnly` | `boolean` | `false` | 是否只读 |
+| `required` | `boolean` | `false` | 是否必填 |
+| `name` | `string` | - | 表单提交时的 name |
+| `autoComplete` | `string` | - | 浏览器自动完成提示 |
+| `maxLength` | `number` | - | 最大字符数 |
+| `minLength` | `number` | - | 最小字符数 |
+| `pattern` | `string` | - | 校验用正则模式 |
+| `min` | `number \| string` | - | 最小值（number/date 输入） |
+| `max` | `number \| string` | - | 最大值（number/date 输入） |
+| `step` | `number \| string` | - | 步进间隔（number 输入） |
+| `fullWidth` | `boolean` | `false` | 是否占满容器宽度 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 |

-> 如需 `isInvalid`、`isRequired` 等校验相关 props 与错误处理，请使用 **[TextField](/docs/components/text-field)**，并将 Input 作为其子组件。
+> 校验 props 如 `isInvalid`、`isRequired` 与错误处理，请使用 **[TextField](/docs/components/text-field)** 并将 Input 作为子组件。
+
+## 相关组件
+
+<RelatedComponents component="input" />
@@ -7,65 +7,16 @@ links:
  styles: label.css
 ---

-## 引入
+## 用法

 ```tsx
 import { Label } from '@heroui/react';
 ```

-## 用法
-
 <ComponentPreview
  name="label-basic"
 />

-<RelatedComponents component="label" />
-
-## API 参考
-
-### Label Props
-
-| Prop | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `htmlFor` | `string` | - | 标签所关联元素的 id |
-| `isRequired` | `boolean` | `false` | 是否显示必填指示符 |
-| `isDisabled` | `boolean` | `false` | 标签是否处于禁用状态 |
-| `isInvalid` | `boolean` | `false` | 标签是否处于无效状态 |
-| `className` | `string` | - | 附加的 CSS 类 |
-| `children` | `ReactNode` | - | 标签内容 |
-
-## 无障碍
-
-Label 基于原生 HTML `<label>`（[MDN 参考](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)），并遵循 WAI-ARIA 最佳实践：
-
- 使用 `htmlFor` 与表单控件关联
- 提供语义化的 `<label>` 元素
- 与表单控件关联时支持键盘导航
- 向屏幕阅读器传达必填与无效状态
- 点击标签可聚焦/激活关联的表单控件
-
-<RelatedComponents component="label" />
-
-## 样式
-
-### CSS 类
-
-Label 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/label.css)）：
-
-#### 基础类
- `.label` — 基础标签文本样式
-
-#### 状态修饰类
- `.label--required` 或 `[data-required="true"] > .label` — 显示必填星号
- `.label--disabled` 或 `[data-disabled="true"] .label` — 禁用状态样式
- `.label--invalid` 或 `[data-invalid="true"] .label` 或 `[aria-invalid="true"] .label` — 无效状态样式（危险/红色文本）
- 
-**说明：** 必填星号会基于 role 与 `data-slot` 智能应用，并排除：
- `role="group"`、`role="radiogroup"`、`role="checkboxgroup"` 的元素
- `data-slot="radio"` 或 `data-slot="checkbox"` 的元素
-
-从而在分组组件与必填字段组合时避免重复星号。
-
 ## 示例

 ### 带必填指示符
@@ -94,3 +45,74 @@ Label 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/
 </Label>
 <Input id="password" isInvalid />
 ```
+
+## 自定义样式
+
+### Tailwind CSS
+
+<ComponentPreview name="label-custom-styles" />
+
+### 全局 CSS
+
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .label {
+    @apply font-semibold text-foreground;
+  }
+
+  .label--required::after {
+    @apply text-accent;
+  }
+}
+```
+
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Label 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/label.css)）：
+
+#### 基础类 [!toc]
+- `.label` — 基础标签文本样式
+
+#### 状态修饰类 [!toc]
+- `.label--required` 或 `[data-required="true"] > .label` — 显示必填星号
+- `.label--disabled` 或 `[data-disabled="true"] .label` — 禁用状态样式
+- `.label--invalid` 或 `[data-invalid="true"] .label` 或 `[aria-invalid="true"] .label` — 无效状态样式（危险/红色文本）
+ 
+**说明：** 必填星号会基于 role 与 `data-slot` 智能应用，并排除：
+- `role="group"`、`role="radiogroup"`、`role="checkboxgroup"` 的元素
+- `data-slot="radio"` 或 `data-slot="checkbox"` 的元素
+
+从而在分组组件与必填字段组合时避免重复星号。
+
+## API 参考
+
+### Label
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `htmlFor` | `string` | - | 标签所关联元素的 id |
+| `isRequired` | `boolean` | `false` | 是否显示必填指示符 |
+| `isDisabled` | `boolean` | `false` | 标签是否处于禁用状态 |
+| `isInvalid` | `boolean` | `false` | 标签是否处于无效状态 |
+| `className` | `string` | - | 附加的 CSS 类 |
+| `children` | `ReactNode` | - | 标签内容 |
+
+## 无障碍
+
+Label 基于原生 HTML `<label>`（[MDN 参考](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)），并遵循 WAI-ARIA 最佳实践：
+
+- 使用 `htmlFor` 与表单控件关联
+- 提供语义化的 `<label>` 元素
+- 与表单控件关联时支持键盘导航
+- 向屏幕阅读器传达必填与无效状态
+- 点击标签可聚焦/激活关联的表单控件
+
+
+## 相关组件
+
+<RelatedComponents component="label" />
@@ -9,17 +9,15 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { NumberField } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="number-field-basic" />

-### 组件结构
+## 组件结构

 ```tsx
 import {NumberField, Label, Description, FieldError} from '@heroui/react';
@@ -40,7 +38,24 @@ export default () => (

 > **NumberField** 允许用户输入数值，并可选择是否显示增减按钮。它支持国际化格式化、校验与键盘导航。

-### 带说明
+## 示例
+
+### 变体
+
+NumberField 组件支持两种视觉变体：
+
+- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
+- **`secondary`** — 低强调、无阴影，适合在 Surface 等表面背景上使用
+
+<ComponentPreview name="number-field-variants" />
+
+### 表面样式
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="number-field-on-surface" />
+
+### 带描述

 <ComponentPreview name="number-field-with-description" />

@@ -48,111 +63,77 @@ export default () => (

 <ComponentPreview name="number-field-required" />

-### 校验
+### 禁用状态

-将 `isInvalid` 与 `FieldError` 配合使用，以展示校验信息。
+<ComponentPreview name="number-field-disabled" />
+
+### 宽度充满
+
+<ComponentPreview name="number-field-full-width" />
+
+### 表单校验
+
+将 `isInvalid` 与 `FieldError` 配合使用，以展示校验消息。

 <ComponentPreview name="number-field-validation" />

-### 受控
+### 受控组件

-控制值以与其他组件同步，或执行自定义格式化。
+控制 value 以与其他组件同步或执行自定义格式化。

 <ComponentPreview name="number-field-controlled" />

-### 带校验
-
-在受控数值的基础上实现自定义校验逻辑。
-
-<ComponentPreview name="number-field-with-validation" />
-
 ### 步进值

-配置增减步进值，以实现更精确的控制。
+配置增减步进值以实现精确控制。

 <ComponentPreview name="number-field-with-step" />

 ### 格式化选项

-将数字格式化为货币、百分比、小数或单位，并支持国际化。
+支持将数字格式化为货币、百分比、小数或单位，并具备国际化能力。

 <ComponentPreview name="number-field-with-format-options" />

-### 自定义图标
-
-自定义增减按钮的图标。
-
-<ComponentPreview name="number-field-custom-icons" />
-
-### 搭配 Chevron
-
-在纵向布局中使用 chevron 图标，以获得不同的视觉风格。
-
-<ComponentPreview name="number-field-with-chevrons" />
-
-### 禁用状态
-
-<ComponentPreview name="number-field-disabled" />
-
-### 全宽
-
-<ComponentPreview name="number-field-full-width" />
-
-### 变体
-
-NumberField 支持两种视觉变体：
-
- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
- **`secondary`** — 低强调、无阴影的变体，适合用在 Surface 组件内
-
-<ComponentPreview name="number-field-variants" />
-
-### 在 Surface 内
-
-在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
-
-<ComponentPreview name="number-field-on-surface" />
-
 ### 表单示例

-包含校验与提交处理的完整表单集成示例。
+完整的表单集成示例，包含校验与提交处理。

 <ComponentPreview name="number-field-form-example" />

-<RelatedComponents component="numberfield" />
+### 带校验

-<RelatedShowcases component="NumberField" />
+通过受控 value 实现自定义校验逻辑。

-### 自定义渲染函数
+<ComponentPreview name="number-field-with-validation" />
+
+### 自定义图标
+
+自定义增减按钮图标。
+
+<ComponentPreview name="number-field-custom-icons" />
+
+### 步进箭头
+
+使用垂直布局的 chevron 图标，呈现不同的视觉风格。
+
+<ComponentPreview name="number-field-with-chevrons" />
+
+### 渲染函数

 <ComponentPreview
-  name="number-field-custom-render-function"
+  name="number-field-render-function"
 />

-## 样式
+## 自定义样式

-### 传入 Tailwind CSS 类
+### Tailwind CSS

-```tsx
-import {NumberField, Label} from '@heroui/react';
+<ComponentPreview name="number-field-custom-styles" />

-function CustomNumberField() {
-  return (
-    <NumberField className="gap-2">
-      <Label className="text-sm font-semibold">Quantity</Label>
-      <NumberField.Group className="rounded-xl border-2">
-        <NumberField.DecrementButton className="bg-gray-100" />
-        <NumberField.Input className="text-center font-bold" />
-        <NumberField.IncrementButton className="bg-gray-100" />
-      </NumberField.Group>
-    </NumberField>
-  );
-}
-```
+### 全局 CSS

-### 自定义组件类
-
-NumberField 使用可自定义的 CSS 类。你可以覆盖这些类名以匹配自己的设计系统。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -181,13 +162,22 @@ NumberField 使用可自定义的 CSS 类。你可以覆盖这些类名以匹配
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

+#### 基础类 [!toc]
+
 - `.number-field` – 根容器，样式非常克制（`flex flex-col gap-1`）
 - `.number-field__group` – 输入与按钮的容器，包含边框与背景样式
 - `.number-field__input` – 数字输入字段
 - `.number-field__increment-button` – 用于增加数值的按钮
 - `.number-field__decrement-button` – 用于减少数值的按钮
+
+#### 变体类 [!toc]
+
 - `.number-field--primary` – 带阴影的主变体（默认）
 - `.number-field--secondary` – 无阴影的次变体，适合用在 surface 上

@@ -207,8 +197,7 @@ NumberField 会根据状态自动管理以下 data 属性：

 ## API 参考

-### NumberField Props
-
+### NumberField
 NumberField 继承 React Aria [NumberField](https://react-spectrum.adobe.com/react-aria/NumberField.html) 组件的全部 props。

 #### Base Props
@@ -361,3 +350,11 @@ NumberField.DecrementButton 继承 React Aria [Button](https://react-spectrum.ad
 | `minValue` | `number \| undefined` | 允许的最小值。 |
 | `maxValue` | `number \| undefined` | 允许的最大值。 |
 | `step` | `number` | 增减步进值。 |
+
+## 相关案例
+
+<RelatedShowcases component="NumberField" />
+
+## 相关组件
+
+<RelatedComponents component="numberfield" />
@@ -9,19 +9,17 @@ links:
  storybook: Components/Forms/RadioGroup
 ---

-## 引入
+## 用法

 ```tsx
 import { RadioGroup, Radio } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="radio-group-basic"
 />

-### 组件结构
+## 组件结构

 导入 RadioGroup 组件后，可通过点号访问各个子部分。

@@ -49,11 +47,7 @@ export default () => (
 )
 ```

-### 自定义指示器
-
-<ComponentPreview
-  name="radio-group-custom-indicator"
-/>
+## 示例

 ### 水平排列

@@ -61,24 +55,21 @@ export default () => (
  name="radio-group-horizontal"
 />

-### 受控
+### 变体
+
+RadioGroup 组件支持两种视觉变体：
+
+- **`primary`**（默认）— 带默认背景的标准样式，适用于大多数场景
+- **`secondary`** — 低强调变体，适合在 Surface 等表面背景上使用
+
+<ComponentPreview name="radio-group-variants" />
+
+### 表面样式
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。

 <ComponentPreview
-  name="radio-group-controlled"
-/>
-
-### 非受控
-
-当你只需要响应更新时，可组合使用 `defaultValue` 与 `onChange`。
-
-<ComponentPreview
-  name="radio-group-uncontrolled"
-/>
-
-### 校验
-
-<ComponentPreview
-  name="radio-group-validation"
+  name="radio-group-on-surface"
 />

 ### 禁用
@@ -87,21 +78,24 @@ export default () => (
  name="radio-group-disabled"
 />

-### 变体
-
-RadioGroup 支持两种视觉变体：
-
- **`primary`**（默认）— 带默认背景的标准样式，适用于大多数场景
- **`secondary`** — 低强调变体，适合用在 Surface 组件内
-
-<ComponentPreview name="radio-group-variants" />
-
-### 在 Surface 内
-
-在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+### 受控组件

 <ComponentPreview
-  name="radio-group-on-surface"
+  name="radio-group-controlled"
+/>
+
+### 非受控
+
+仅需响应更新时，将 `defaultValue` 与 `onChange` 配合使用。
+
+<ComponentPreview
+  name="radio-group-uncontrolled"
+/>
+
+### 表单校验
+
+<ComponentPreview
+  name="radio-group-validation"
 />

 ### 配送与支付
@@ -112,54 +106,27 @@ RadioGroup 支持两种视觉变体：
  name="radio-group-delivery-and-payment"
 />

-<RelatedShowcases component="RadioGroup" />
-
-<RelatedComponents component="radiogroup" />
-
-### 自定义渲染函数
+### 自定义指示器

 <ComponentPreview
-  name="radio-group-custom-render-function"
+  name="radio-group-custom-indicator"
 />

-## 样式
+### 渲染函数

-### 传入 Tailwind CSS 类
+<ComponentPreview
+  name="radio-group-render-function"
+/>

-```tsx
-import { RadioGroup, Radio } from '@heroui/react';
+## 自定义样式

-export default () => (
-  <RadioGroup defaultValue="premium" name="plan">
-    <Radio
-      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-blue-300 data-[selected=true]:border-blue-500 data-[selected=true]:bg-blue-500/10"
-      value="basic"
-    >
-      <Radio.Indicator className="border-border border-2 group-hover:border-blue-400 group-data-[selected=true]:border-blue-500 group-data-[selected=true]:bg-blue-500" />
-      Basic Plan
-    </Radio>
-    <Radio
-      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-purple-300 data-[selected=true]:border-purple-500 data-[selected=true]:bg-purple-500/10"
-      value="premium"
-    >
-      <Radio.Indicator className="border-border border-2 group-hover:border-purple-400 group-data-[selected=true]:border-purple-500 group-data-[selected=true]:bg-purple-500" />
-      Premium Plan
-    </Radio>
-    <Radio
-      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-emerald-300 data-[selected=true]:border-emerald-500 data-[selected=true]:bg-emerald-500/10"
-      value="business"
-    >
-      <Radio.Indicator className="border-border border-2 group-hover:border-emerald-400 group-data-[selected=true]:border-emerald-500 group-data-[selected=true]:bg-emerald-500" />
-      Business Plan
-    </Radio>
-  </RadioGroup>
-);
-```
+### Tailwind CSS

-### 自定义组件类
+<ComponentPreview name="radio-group-custom-styles" />

-要自定义 RadioGroup 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+### 全局 CSS
+
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -185,20 +152,22 @@ export default () => (
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 RadioGroup 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/radio-group.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.radio-group` - 单选组基础容器
 - `.radio` - 单个单选项
 - `.radio__control` - 单选控件（圆形按钮）
 - `.radio__indicator` - 单选指示器（内部圆点）
 - `.radio__content` - 单选内容包裹层

-#### 修饰类
+#### 修饰类 [!toc]
 - `.radio--disabled` - 禁用状态

 ### 交互状态
@@ -214,8 +183,7 @@ RadioGroup 使用以下 CSS 类（[查看源码样式](https://github.com/heroui

 ## API 参考

-### RadioGroup Props
-
+### RadioGroup
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `value` | `string` | - | 当前值（受控） |
@@ -231,8 +199,7 @@ RadioGroup 使用以下 CSS 类（[查看源码样式](https://github.com/heroui
 | `children` | `React.ReactNode \| (values: RadioGroupRenderProps) => React.ReactNode` | - | 单选组内容或渲染 prop |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioGroupRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Radio Props
-
+### Radio
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `value` | `string` | - | 单选项的值 |
@@ -241,24 +208,21 @@ RadioGroup 使用以下 CSS 类（[查看源码样式](https://github.com/heroui
 | `children` | `React.ReactNode \| (values: RadioFieldRenderProps) => React.ReactNode` | - | 单选内容或字段级渲染 prop |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Radio.Control Props
-
+### Radio.Control
 继承 `React.HTMLAttributes<HTMLSpanElement>`。

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 控件包裹层内要渲染的内容（通常为 Radio.Indicator） |

-### Radio.Indicator Props
-
+### Radio.Indicator
 继承 `React.HTMLAttributes<HTMLSpanElement>`。

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode \| (values: RadioButtonRenderProps) => React.ReactNode` | - | 可选内容或接收当前单选按钮状态的渲染 prop。 |

-### Radio.Content Props
-
+### Radio.Content
 单选项的可点击区域（包裹隐藏 input 的 `<label>`）。请将 `Radio.Control` 与 `Label` 放在其中。`className` 支持接收 `RadioButtonRenderProps` 的渲染函数。

 | Prop | 类型 | 默认值 | 描述 |
@@ -280,3 +244,11 @@ RadioGroup 使用以下 CSS 类（[查看源码样式](https://github.com/heroui
 ### RadioButtonRenderProps

 `Radio.Control` 和 `Radio.Indicator` 使用按钮级渲染 prop（`isHovered`、`isPressed`、`isFocusVisible` 等）。将函数作为 `Radio.Control` 子节点或传给 `Radio.Indicator` 即可访问它们。
+
+## 相关案例
+
+<RelatedShowcases component="RadioGroup" />
+
+## 相关组件
+
+<RelatedComponents component="radiogroup" />
@@ -9,17 +9,15 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { SearchField } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="search-field-basic" />

-### 组件结构
+## 组件结构

 ```tsx
 import {SearchField, Label, Description, FieldError} from '@heroui/react';
@@ -40,7 +38,24 @@ export default () => (

 > **SearchField** 允许用户输入并清空搜索关键词。它包含搜索图标，并提供可选的清除按钮以便快速重置。

-### 带说明
+## 示例
+
+### 变体
+
+SearchField 组件支持两种视觉变体：
+
+- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
+- **`secondary`** — 低强调、无阴影，适合在 Surface 等表面背景上使用
+
+<ComponentPreview name="search-field-variants" />
+
+### 表面样式
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="search-field-on-surface" />
+
+### 带描述

 <ComponentPreview name="search-field-with-description" />

@@ -48,25 +63,35 @@ export default () => (

 <ComponentPreview name="search-field-required" />

-### 校验
-
-将 `isInvalid` 与 `FieldError` 配合使用，以展示校验信息。
-
-<ComponentPreview name="search-field-validation" />
-
 ### 禁用状态

 <ComponentPreview name="search-field-disabled" />

-### 受控
+### 宽度充满

-控制值以与其他组件同步，或执行自定义格式化。
+<ComponentPreview name="search-field-full-width" />
+
+### 表单校验
+
+将 `isInvalid` 与 `FieldError` 配合使用，以展示校验消息。
+
+<ComponentPreview name="search-field-validation" />
+
+### 受控组件
+
+控制 value 以与其他组件同步或执行自定义格式化。

 <ComponentPreview name="search-field-controlled" />

+### 表单示例
+
+完整的表单集成示例，包含校验与提交处理。
+
+<ComponentPreview name="search-field-form-example" />
+
 ### 带校验

-在受控数值的基础上实现自定义校验逻辑。
+通过受控 value 实现自定义校验逻辑。

 <ComponentPreview name="search-field-with-validation" />

@@ -76,71 +101,27 @@ export default () => (

 <ComponentPreview name="search-field-custom-icons" />

-### 全宽
-
-<ComponentPreview name="search-field-full-width" />
-
-### 变体
-
-SearchField 支持两种视觉变体：
-
- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
- **`secondary`** — 低强调、无阴影的变体，适合用在 Surface 组件内
-
-<ComponentPreview name="search-field-variants" />
-
-### 在 Surface 内
-
-在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
-
-<ComponentPreview name="search-field-on-surface" />
-
-### 表单示例
-
-包含校验与提交处理的完整表单集成示例。
-
-<ComponentPreview name="search-field-form-example" />
-
 ### 键盘快捷键

-添加快捷键以快速聚焦搜索字段。
+添加快捷键以快速聚焦搜索框。

 <ComponentPreview name="search-field-with-keyboard-shortcut" />

-<RelatedComponents component="searchfield" />
-
-<RelatedShowcases component="SearchField" />
-
-### 自定义渲染函数
+### 渲染函数

 <ComponentPreview
-  name="search-field-custom-render-function"
+  name="search-field-render-function"
 />

-## 样式
+## 自定义样式

-### 传入 Tailwind CSS 类
+### Tailwind CSS

-```tsx
-import {SearchField, Label} from '@heroui/react';
+<ComponentPreview name="search-field-custom-styles" />

-function CustomSearchField() {
-  return (
-    <SearchField className="gap-2">
-      <Label className="text-sm font-semibold">Search</Label>
-      <SearchField.Group className="rounded-xl border-2">
-        <SearchField.SearchIcon className="text-blue-500" />
-        <SearchField.Input className="text-center font-bold" />
-        <SearchField.ClearButton className="text-red-500" />
-      </SearchField.Group>
-    </SearchField>
-  );
-}
-```
+### 全局 CSS

-### 自定义组件类
-
-SearchField 使用可自定义的 CSS 类。你可以覆盖这些类名以匹配自己的设计系统。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -174,13 +155,22 @@ SearchField 使用可自定义的 CSS 类。你可以覆盖这些类名以匹配
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

+#### 基础类 [!toc]
+
 - `.search-field` – 根容器，样式非常克制（`flex flex-col gap-1`）
 - `.search-field__group` – 搜索图标、输入框与清除按钮的容器，包含边框与背景样式
 - `.search-field__input` – 搜索输入字段
 - `.search-field__search-icon` – 左侧显示的搜索图标
 - `.search-field__clear-button` – 用于清空搜索字段的按钮
+
+#### 变体类 [!toc]
+
 - `.search-field--primary` – 带阴影的主变体（默认）
 - `.search-field--secondary` – 无阴影的次变体，适合用在 surface 上

@@ -201,8 +191,7 @@ SearchField 会根据状态自动管理以下 data 属性：

 ## API 参考

-### SearchField Props
-
+### SearchField
 SearchField 继承 React Aria [SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html) 组件的全部 props。

 #### Base Props
@@ -346,3 +335,11 @@ SearchField.ClearButton 继承 React Aria [Button](https://react-spectrum.adobe.
 | `isFocusVisible` | `boolean` | 是否为可见焦点（键盘导航）。 |
 | `value` | `string` | 当前值。 |
 | `isEmpty` | `boolean` | 字段是否为空。 |
+
+## 相关案例
+
+<RelatedShowcases component="SearchField" />
+
+## 相关组件
+
+<RelatedComponents component="searchfield" />
@@ -8,21 +8,40 @@ links:
  storybook: Components/Forms/Textarea
 ---

-## 引入
+## 用法

 ```tsx
 import { TextArea } from '@heroui/react';
 ```

-<Callout>
-  关于校验、标签与错误信息，请参阅 **[TextField](/docs/components/text-field)**。
-</Callout>
-
-### 用法
-
 <ComponentPreview name="textarea-basic" />

-### 受控
+<Callout>
+  校验、标签与错误消息请参阅 **[TextField](/docs/components/text-field)**。
+</Callout>
+
+## 示例
+
+### 变体
+
+TextArea 组件支持两种视觉变体：
+
+- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
+- **`secondary`** — 低强调、无阴影，适合在 Surface 等表面背景上使用
+
+<ComponentPreview name="textarea-variants" />
+
+### 表面样式
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="textarea-on-surface" />
+
+### 宽度充满
+
+<ComponentPreview name="textarea-full-width" />
+
+### 受控组件

 <ComponentPreview name="textarea-controlled" />

@@ -30,55 +49,15 @@ import { TextArea } from '@heroui/react';

 <ComponentPreview name="textarea-rows" />

-### 全宽
+## 自定义样式

-<ComponentPreview name="textarea-full-width" />
+### Tailwind CSS

-### 变体
+<ComponentPreview name="text-area-custom-styles" />

-TextArea 支持两种视觉变体：
+### 全局 CSS

- **`primary`**（默认）— 常规带阴影样式，适用于大多数场景
- **`secondary`** — 弱强调、无阴影变体，适合用于 Surface 组件内部
-
-<ComponentPreview name="textarea-variants" />
-
-### 在 Surface 内
-
-在 [Surface](/docs/components/surface) 组件内部使用时，请使用 `variant="secondary"`，以应用适合 surface 背景的弱强调变体。
-
-<ComponentPreview name="textarea-on-surface" />
-
-<RelatedComponents component="textarea" />
-
-<RelatedShowcases component="TextArea" />
-
-## 样式
-
-### 传入 Tailwind CSS 类
-
-```tsx
-import {Label, TextArea} from '@heroui/react';
-
-function CustomTextArea() {
-  return (
-    <div className="flex flex-col gap-2">
-      <Label htmlFor="custom-textarea">Message</Label>
-      <TextArea
-        id="custom-textarea"
-        className="rounded-xl border border-border/70 bgsurface px-4 py-3 text-sm leading-6 shadow-sm"
-        placeholder="Let us know how we can help..."
-        rows={5}
-        style={{resize: "vertical"}}
-      />
-    </div>
-  );
-}
-```
-
-### 自定义组件类
-
-使用 Tailwind 的 `@layer components` 一次性覆盖共享的 `.textarea` 类。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -102,8 +81,14 @@ function CustomTextArea() {
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

+#### 基础类 [!toc]
+
 - `.textarea` – 底层 `<textarea>` 元素样式

 ### 交互状态
@@ -115,8 +100,7 @@ function CustomTextArea() {

 ## API 参考

-### TextArea Props
-
+### TextArea
 TextArea 接受所有标准 HTML `<textarea>` 属性，以及以下属性：

 | Prop | 类型 | 默认值 | 描述 |
@@ -140,3 +124,11 @@ TextArea 接受所有标准 HTML `<textarea>` 属性，以及以下属性：
 | `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为弱强调、无阴影变体，适合用于 surface 上。 |

 > 对于 `isInvalid`、`isRequired` 等校验 prop 以及错误处理，请将 TextArea 作为子组件与 **[TextField](/docs/components/text-field)** 一起使用。
+
+## 相关案例
+
+<RelatedShowcases component="TextArea" />
+
+## 相关组件
+
+<RelatedComponents component="textarea" />
@@ -9,17 +9,15 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { TextField } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="textfield-basic" />

-### 组件结构
+## 组件结构

 ```tsx
 import {TextField, Label, Input, Description, FieldError} from '@heroui/react';
@@ -36,7 +34,15 @@ export default () => (

 > **TextField** 将标签、输入、说明与错误信息整合为单个无障碍组件。若只需独立输入，请使用 **[Input](/docs/components/input)** 或 **[TextArea](/docs/components/textarea)**。

-### 带说明
+## 示例
+
+### 表面样式
+
+在 [Surface](/docs/components/surface) 内使用时，请在 Input 或 TextArea 组件上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="textfield-on-surface" />
+
+### 带描述

 <ComponentPreview name="textfield-with-description" />

@@ -44,15 +50,23 @@ export default () => (

 <ComponentPreview name="textfield-required" />

-### 校验
+### 禁用状态

-使用 `isInvalid` 与 `FieldError` 展示校验信息。
+<ComponentPreview name="textfield-disabled" />
+
+### 宽度充满
+
+<ComponentPreview name="textfield-full-width" />
+
+### 表单校验
+
+将 `isInvalid` 与 `FieldError` 配合使用，以展示校验消息。

 <ComponentPreview name="textfield-validation" />

-### 受控
+### 受控组件

-通过受控 `value` 同步计数器、预览或格式化。
+控制 value 以同步计数器、预览或格式化逻辑。

 <ComponentPreview name="textfield-controlled" />

@@ -60,13 +74,9 @@ export default () => (

 <ComponentPreview name="textfield-with-error" />

-### 禁用状态
+### 文本域

-<ComponentPreview name="textfield-disabled" />
-
-### TextArea
-
-多行内容请使用 [TextArea](/docs/components/textarea) 替代 [Input](/docs/components/input)。
+多行内容请使用 [TextArea](/docs/components/textarea)，而非 [Input](/docs/components/input)。

 <ComponentPreview name="textfield-textarea" />

@@ -74,51 +84,21 @@ export default () => (

 <ComponentPreview name="textfield-input-types" />

-### 全宽
-
-<ComponentPreview name="textfield-full-width" />
-
-### 在 Surface 内
-
-置于 [Surface](/docs/components/surface) 中时，请在 Input 或 TextArea 上使用 `variant="secondary"`，以应用适合表面背景的弱强调变体。
-
-<ComponentPreview name="textfield-on-surface" />
-
-<RelatedComponents component="textfield" />
-
-<RelatedShowcases component="TextField" />
-
-### 自定义渲染函数
+### 渲染函数

 <ComponentPreview
-  name="textfield-custom-render-function"
+  name="textfield-render-function"
 />

-## 样式
+## 自定义样式

-### 传入 Tailwind CSS 类
+### Tailwind CSS

-```tsx
-import {TextField, Label, Input, Description} from '@heroui/react';
+<ComponentPreview name="text-field-custom-styles" />

-function CustomTextField() {
-  return (
-    <TextField className="gap-2 rounded-xl border border-border/60 bgsurface p-4 shadow-sm">
-      <Label className="text-sm font-semibold text-default-700">
-        Project name
-      </Label>
-      <Input className="rounded-lg border border-border/60 bgsurface px-3 py-2" />
-      <Description className="text-xs text-default-500">
-        Keep it short and memorable.
-      </Description>
-    </TextField>
-  );
-}
-```
+### 全局 CSS

-### 自定义组件类
-
-TextField 默认样式很少。覆盖 `.textfield` 类即可自定义容器样式。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -126,19 +106,23 @@ TextField 默认样式很少。覆盖 `.textfield` 类即可自定义容器样
    @apply flex flex-col gap-1;
  }

-  /* 无效时自动隐藏说明 */
+  /* When invalid, the description is hidden automatically */
  .textfield[data-invalid="true"] [data-slot="description"],
  .textfield[aria-invalid="true"] [data-slot="description"] {
    @apply hidden;
  }

-  /* Description 默认内边距 */
+  /* Description has default padding */
  .textfield [data-slot="description"] {
    @apply px-1;
  }
 }
 ```

+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
 ### CSS 类

 - `.textfield` – 根容器，样式极少（`flex flex-col gap-1`）
@@ -158,8 +142,7 @@ TextField 会根据状态自动管理以下 data 属性：

 ## API 参考

-### TextField Props
-
+### TextField
 继承 React Aria [TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) 的全部 props。

 #### Base Props
@@ -248,3 +231,11 @@ TextField 与以下独立组件配合使用，请直接按需引入并组合：
 | `isFocused` | `boolean` | 字段是否聚焦（已弃用 — 请使用 `isFocusWithin`）。 |
 | `isFocusWithin` | `boolean` | 是否有任一子元素聚焦。 |
 | `isFocusVisible` | `boolean` | 是否为可见键盘焦点。 |
+
+## 相关案例
+
+<RelatedShowcases component="TextField" />
+
+## 相关组件
+
+<RelatedComponents component="textfield" />
@@ -1,27 +1,23 @@
 ---
 title: Card 卡片
-description: 用于分组相关内容与操作的灵活容器组件。
+description: 灵活容器组件，用于分组相关内容与操作
 links:
  source: card/card.tsx
  styles: card.css
  storybook: Components/Layout/Card
 ---

-## 引入
+## 用法

 ```tsx
 import { Card } from "@heroui/react";
 ```

-### 用法
-
 <ComponentPreview
  name="card-default"
 />

-### 组件结构
-
-导入 Card 组件后，可通过点语法访问所有子部分。
+## 组件结构

 ```tsx
 import { Card } from "@heroui/react";
@@ -38,20 +34,22 @@ export default () => (
 );
 ```

+## 示例
+
 ### 变体

-卡片提供语义化变体，用于表达层级强弱而非固定视觉样式，主题可按需诠释：
+Card 提供语义变体，描述 prominence 级别而非具体视觉样式，允许主题以不同方式解读：

 <ComponentPreview
  name="card-variants"
 />

- **`transparent`** — 层次最低，透明背景（适合嵌套卡片）
- **`default`** — 常规卡片，适用于大多数场景（surface-secondary）
- **`secondary`** — 中等突出，吸引适度注意（surface-tertiary）
- **`tertiary`** — 更高突出，用于重要内容（surface-tertiary）
+- **`transparent`** - 最低 prominence，透明背景（适合嵌套卡片）
+- **`default`** - 大多数场景的标准卡片（surface-secondary）
+- **`secondary`** - 中等 prominence 以吸引适度注意（surface-tertiary）
+- **`tertiary`** - 更高 prominence 用于重要内容（surface-tertiary）

-### 横向布局
+### 水平布局

 <ComponentPreview
  name="card-horizontal"
@@ -69,125 +67,123 @@ export default () => (
  name="card-with-images"
 />

-### 带表单
+### 搭配表单

 <ComponentPreview
  name="card-with-form"
 />

+## 自定义样式
+
+### Tailwind CSS
+
+<ComponentPreview name="card-custom-styles" />
+
+### 全局 CSS
+
+可使用 `@layer components` 指令自定义 Card 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .card--secondary {
+    @apply bg-gradient-to-br from-blue-50 to-purple-50;
+  }
+
+  .card__title {
+    @apply text-xl font-bold;
+  }
+}
+```
+
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Card 使用 [BEM](https://getbem.com/) 命名以实现可预测的样式（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/card.css)）：
+
+#### 基础类 [!toc]
+
+- `.card` - 带 padding 与边框的基础容器
+- `.card__header` - 头部区域容器
+- `.card__title` - 基础字号与字重的标题
+- `.card__description` - 弱化描述文本
+- `.card__content` - 灵活内容容器
+- `.card__footer` - 行布局的页脚
+
+#### 变体类 [!toc]
+
+- `.card--transparent` - 最低 prominence，透明背景（对应 `transparent` 变体）
+- `.card--default` - 标准外观，surface-secondary（默认）
+- `.card--secondary` - 中等 prominence，surface-tertiary（对应 `secondary` 变体）
+- `.card--tertiary` - 更高 prominence，surface-tertiary（对应 `tertiary` 变体）
+
+## API 参考
+
+### Card
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `"transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | 表示 prominence 级别的语义变体 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `React.ReactNode` | - | 卡片内容 |
+
+### Card.Header
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `React.ReactNode` | - | 头部内容 |
+
+### Card.Title
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `React.ReactNode` | - | 标题内容（渲染为 `h3`） |
+
+### Card.Description
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `React.ReactNode` | - | 描述内容（渲染为 `p`） |
+
+### Card.Content
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `React.ReactNode` | - | 主要内容 |
+
+### Card.Footer
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `React.ReactNode` | - | 页脚内容 |
+
 ## 无障碍

 ```tsx
 import { Card } from '@heroui/react';
 import { cardVariants } from '@heroui/styles';

-// 语义化标记
+// Semantic markup
 <Card role="article" aria-labelledby="card-title">
  <Card.Header>
    <Card.Title id="card-title">Article Title</Card.Title>
  </Card.Header>
 </Card>

-// 可交互卡片
+// Interactive cards
 <a className={cardVariants().base()} href="/details" aria-label="View product details">
  <Card.Title>Product Name</Card.Title>
 </a>
 ```

-<RelatedComponents component="card" />
+## 相关组件

-## 样式
-
-### 组件定制
-
-```tsx
-<Card className="border-2 border-blue-500 bg-gradient-to-r from-blue-50 to-purple-50">
-  <Card.Header>
-    <Card.Title className="text-blue-900">Custom Styled Card</Card.Title>
-    <Card.Description className="text-blue-700">Custom colors applied</Card.Description>
-  </Card.Header>
-  <Card.Content>
-    <p className="text-blue-800">Content with custom styling</p>
-  </Card.Content>
-</Card>
-```
-
-### CSS 变量覆盖
-
-```css
-/* 覆盖特定变体 */
-.card--secondary {
-  @apply bg-gradient-to-br from-blue-50 to-purple-50;
-}
-
-/* 自定义元素样式 */
-.card__title {
-  @apply text-xl font-bold;
-}
-```
-
-## CSS 类
-
-Card 使用 [BEM](https://getbem.com/) 命名以便样式可预期（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/card.css)）：
-
-
-#### 基础类
-
- `.card` — 基础容器，含内边距与边框
- `.card__header` — 头部区域容器
- `.card__title` — 标题的基础字号与字重
- `.card__description` — 弱化说明文字
- `.card__content` — 弹性主内容区
- `.card__footer` — 底部行布局
-
-#### 变体类
-
- `.card--transparent` — 层次最低，透明背景（对应 `transparent` 变体）
- `.card--default` — 常规外观，surface-secondary（默认）
- `.card--secondary` — 中等突出，surface-tertiary（对应 `secondary` 变体）
- `.card--tertiary` — 更高突出，surface-tertiary（对应 `tertiary` 变体）
-
-## API 参考
-
-### Card
-
-| Prop        | 类型                                                      | 默认值      | 描述                                       |
-| ----------- | --------------------------------------------------------- | ----------- | ------------------------------------------ |
-| `variant`   | `"transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | 表示层次强弱的语义变体                     |
-| `className` | `string`                                                  | -           | 附加的 CSS 类                              |
-| `children`  | `React.ReactNode`                                         | -           | 卡片内容                                   |
-
-### Card.Header
-
-| Prop        | 类型              | 默认值 | 描述                    |
-| ----------- | ----------------- | ------ | ----------------------- |
-| `className` | `string`          | -      | 附加的 CSS 类           |
-| `children`  | `React.ReactNode` | -      | 头部内容                |
-
-### Card.Title
-
-| Prop        | 类型              | 默认值 | 描述                                 |
-| ----------- | ----------------- | ------ | ------------------------------------ |
-| `className` | `string`          | -      | 附加的 CSS 类                        |
-| `children`  | `React.ReactNode` | -      | 标题内容（渲染为 `h3`）              |
-
-### Card.Description
-
-| Prop        | 类型              | 默认值 | 描述                                |
-| ----------- | ----------------- | ------ | ----------------------------------- |
-| `className` | `string`          | -      | 附加的 CSS 类                       |
-| `children`  | `React.ReactNode` | -      | 说明内容（渲染为 `p`）              |
-
-### Card.Content
-
-| Prop        | 类型              | 默认值 | 描述                    |
-| ----------- | ----------------- | ------ | ----------------------- |
-| `className` | `string`          | -      | 附加的 CSS 类           |
-| `children`  | `React.ReactNode` | -      | 主内容                  |
-
-### Card.Footer
-
-| Prop        | 类型              | 默认值 | 描述                    |
-| ----------- | ----------------- | ------ | ----------------------- |
-| `className` | `string`          | -      | 附加的 CSS 类           |
-| `children`  | `React.ReactNode` | -      | 底部内容                |
+<RelatedComponents component="card" />
@@ -9,18 +9,32 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Separator } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="separator-basic"
 />

+## 示例
+
+### 变体
+
+<ComponentPreview
+  name="separator-variants"
+/>
+
+### 与 Surface 组合
+
+Separator 组件会根据不同的表面背景自动适配，以获得更好的可见性。
+
+<ComponentPreview
+  name="separator-with-surface"
+/>
+
 ### 垂直方向

 <ComponentPreview
@@ -33,46 +47,21 @@ import { Separator } from '@heroui/react';
  name="separator-with-content"
 />

-### 变体
+### 渲染函数

 <ComponentPreview
-  name="separator-variants"
+  name="separator-render-function"
 />

-### 与 Surface 组合
+## 自定义样式

-Separator 会适配不同的 surface 背景，以获得更好的可见性。
+### Tailwind CSS

-<ComponentPreview
-  name="separator-with-surface"
-/>
+<ComponentPreview name="separator-custom-styles" />

-<RelatedComponents component="separator" />
+### 全局 CSS

-### 自定义渲染函数
-
-<ComponentPreview
-  name="separator-custom-render-function"
-/>
-
-## 样式
-
-### 传入 Tailwind CSS 类
-
-```tsx
-import {Separator} from '@heroui/react';
-
-function CustomSeparator() {
-  return (
-    <Separator className="my-8 bg-linear-to-r from-transparent via-default-500 to-transparent" />
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Separator 的组件类名，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -86,29 +75,34 @@ function CustomSeparator() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Separator 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/separator.css)）：

-#### 基础类与方向类
+#### 基础类与方向类 [!toc]
 - `.separator` - 基础 Separator 样式，默认水平方向
 - `.separator--horizontal` - 水平方向（全宽，高度 1px）
 - `.separator--vertical` - 垂直方向（全高，宽度 1px）

-#### 变体类
+#### 变体类 [!toc]
 - `.separator--default` - 默认变体，标准对比度
 - `.separator--secondary` - 次要变体，中等对比度
 - `.separator--tertiary` - 第三级变体，较弱对比度

 ## API 参考

-### Separator Props
-
+### Separator
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Separator 的方向 |
 | `variant` | `'default' \| 'secondary' \| 'tertiary'` | `'default'` | Separator 的视觉变体 |
 | `className` | `string` | - | 额外的 CSS 类名 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+## 相关组件
+
+<RelatedComponents component="separator" />
@@ -7,73 +7,41 @@ links:
  storybook: surface
 ---

-## 引入
+## 用法

 ```tsx
 import { Surface } from '@heroui/react';
 ```

-### 用法
+<ComponentPreview name="surface-basic" />

-<ComponentPreview
-  name="surface-variants"
-/>
-
-## 概述
-
-Surface 组件是语义化容器，通过变体提供不同的视觉层次。
+## 示例

 ### 变体

-Surface 提供描述视觉层次的语义化变体：
+Surface 提供描述 prominence 层级的语义变体：

- **`default`** — 标准表面外观（bg-surface）
- **`secondary`** — 中等层次（bg-surface-secondary）
- **`tertiary`** — 更高层次（bg-surface-tertiary）
+- **`default`** - 标准表面外观（bg-surface）
+- **`secondary`** - 中等 prominence（bg-surface-secondary）
+- **`tertiary`** - 较高 prominence（bg-surface-tertiary）

-## 与表单组件配合
+<ComponentPreview name="surface-variants" />

-在 Surface 内使用表单组件时，请为这些组件设置 `variant="secondary"`，以应用适合表面背景的低强调变体。
+### 搭配表单

-```tsx
-import { Surface, Input, TextArea } from '@heroui/react';
+在 Surface 内使用表单组件时，请使用 `variant="secondary"` 以应用适合表面背景的低强调变体。

-function App() {
-  return (
-    <Surface variant="default">
-      <Input placeholder="Input with secondary variant" variant="secondary" />
-      <TextArea placeholder="TextArea with secondary variant" variant="secondary" />
-    </Surface>
-  );
-}
-```
+<ComponentPreview name="surface-with-form-components" />

-<RelatedComponents component="surface" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="surface-custom-styles" />

-```tsx
-import { Surface } from '@heroui/react';
+### 全局 CSS

-function CustomSurface() {
-  return (
-    <Surface
-      className="rounded-2xl p-8 shadow-lg"
-      variant="secondary"
-    >
-      <h2>Custom Styled Surface</h2>
-      <p>Content goes here</p>
-    </Surface>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Surface 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -87,24 +55,25 @@ function CustomSurface() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Surface 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/surface.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.surface` - Surface 根容器

-#### 变体类
+#### 变体类 [!toc]
 - `.surface--default` - 默认 Surface 变体（bg-surface）
 - `.surface--secondary` - Secondary Surface 变体（bg-surface-secondary）
 - `.surface--tertiary` - Tertiary Surface 变体（bg-surface-tertiary）

 ## API 参考

-### Surface Props
-
+### Surface
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `variant` | ` "transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | Surface 的视觉变体。 |
@@ -126,3 +95,7 @@ function MyComponent() {
  // variant 为 "transparent" | "default" | "secondary" | "tertiary" | undefined
 }
 ```
+
+## 相关组件
+
+<RelatedComponents component="surface" />
@@ -8,61 +8,45 @@ links:
  storybook: Components/Layout/Toolbar
 ---

-## 引入
+## 用法

 ```tsx
 import { Toolbar } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="toolbar-basic"
 />

+## 示例
+
 ### 垂直方向

 <ComponentPreview
  name="toolbar-vertical"
 />

+### 组合模式
+
+<ComponentPreview
+  name="toolbar-attached"
+/>
+
 ### 与 ButtonGroup 组合

 <ComponentPreview
  name="toolbar-with-button-group"
 />

-### Attached
+## 自定义样式

-<ComponentPreview
-  name="toolbar-attached"
-/>
+### Tailwind CSS

-<RelatedComponents component="toolbar" />
+<ComponentPreview name="toolbar-custom-styles" />

-## 样式
+### 全局 CSS

-### 传入 Tailwind CSS 类
-
-```tsx
-import { Toolbar } from '@heroui/react';
-
-function CustomToolbar() {
-  return (
-    <Toolbar
-      aria-label="Actions"
-      className="rounded-xl border border-default bg-surface p-2"
-    >
-      {/* toolbar content */}
-    </Toolbar>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Toolbar 的组件类名，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -72,7 +56,9 @@ function CustomToolbar() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

@@ -85,8 +71,7 @@ Toolbar 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-in

 ## API 参考

-### Toolbar Props
-
+### Toolbar
 继承 [React Aria Toolbar](https://react-spectrum.adobe.com/react-aria/Toolbar.html)。

 | Prop | 类型 | 默认值 | 描述 |
@@ -105,3 +90,7 @@ Toolbar 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-in
 | Prop | 类型 | 描述 |
 |------|------|------|
 | `orientation` | `"horizontal" \| "vertical"` | 当前 Toolbar 的方向 |
+
+## 相关组件
+
+<RelatedComponents component="toolbar" />
@@ -1,6 +1,6 @@
 ---
 title: Avatar 头像
-description: 展示用户头像图片，并提供可定制的回退内容。
+description: 显示用户头像，支持自定义 fallback 内容
 links:
  radix: avatar
  source: avatar/avatar.tsx
@@ -9,19 +9,15 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Avatar } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview name="avatar-basic" />

-### 组件结构
-
-引入 Avatar 组件，并通过点语法访问各部分。
+## 组件结构

 ```tsx
 import { Avatar } from '@heroui/react';
@@ -34,6 +30,8 @@ export default () => (
 )
 ```

+## 示例
+
 ### 尺寸

 <ComponentPreview name="avatar-sizes" />
@@ -54,33 +52,16 @@ export default () => (

 <ComponentPreview name="avatar-group" />

-### 自定义样式
+## 自定义样式
+
+### Tailwind CSS

 <ComponentPreview name="avatar-custom-styles" />

-<RelatedComponents component="avatar" />
+### 全局 CSS

-## 样式
-
-### 传入 Tailwind CSS 类
-
-```tsx
-import { Avatar } from '@heroui/react';
-
-function CustomAvatar() {
-  return (
-    <Avatar className="size-20">
-      <Avatar.Image src="..." alt="..." />
-      <Avatar.Fallback>XL</Avatar.Fallback>
-    </Avatar>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Avatar 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 Avatar 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -94,61 +75,67 @@ function CustomAvatar() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Avatar 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/avatar.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.avatar` - 基础容器，默认尺寸（size-10）
- `.avatar__image` - 图片元素，方形比例
- `.avatar__fallback` - 回退容器，内容居中
+- `.avatar__image` - 图片元素，aspect-square 尺寸
+- `.avatar__fallback` - 居中内容的 fallback 容器

-#### 尺寸修饰
- `.avatar--sm` - 小尺寸（size-8）
- `.avatar--md` - 中尺寸（默认，无额外样式）
- `.avatar--lg` - 大尺寸（size-12）
+#### 尺寸修饰符 [!toc]
+- `.avatar--sm` - 小头像（size-8）
+- `.avatar--md` - 中头像（默认，无额外样式）
+- `.avatar--lg` - 大头像（size-12）

-#### 变体修饰
- `.avatar--soft` - Soft 变体，背景更浅
+#### 变体修饰符 [!toc]
+- `.avatar--soft` - 浅色背景的 soft 变体

-#### 颜色修饰
+#### 颜色修饰符 [!toc]
 - `.avatar__fallback--default` - 默认文字颜色
- `.avatar__fallback--accent` - 强调文字颜色
- `.avatar__fallback--success` - 成功文字颜色
- `.avatar__fallback--warning` - 警告文字颜色
- `.avatar__fallback--danger` - 危险文字颜色
+- `.avatar__fallback--accent` - 强调色文字
+- `.avatar__fallback--success` - 成功色文字
+- `.avatar__fallback--warning` - 警告色文字
+- `.avatar__fallback--danger` - 危险色文字

 ## API 参考

-### Avatar Props
+### Avatar

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar 尺寸 |
-| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | 回退区域的颜色主题 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 头像尺寸 |
+| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Fallback 颜色主题 |
 | `variant` | `'default' \| 'soft'` | `'default'` | 视觉样式变体 |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |

-### Avatar.Image Props
+### Avatar.Image

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `src` | `string` | - | 图片地址 |
-| `srcSet` | `string` | - | 响应式图片的 `srcset` |
-| `sizes` | `string` | - | 响应式图片的 `sizes` |
+| `src` | `string` | - | 图片 URL |
+| `srcSet` | `string` | - | 响应式图片的 `srcset` 属性 |
+| `sizes` | `string` | - | 响应式图片的 `sizes` 属性 |
 | `alt` | `string` | - | 图片替代文本 |
-| `onLoad` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | 图片加载成功时的事件处理函数 |
-| `onError` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | 图片加载失败时的事件处理函数 |
+| `onLoad` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | 图片加载成功时的回调 |
+| `onError` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | 图片加载失败时的回调 |
 | `crossOrigin` | `'anonymous' \| 'use-credentials'` | - | 图片请求的 CORS 设置 |
 | `loading` | `'eager' \| 'lazy'` | - | 原生懒加载属性 |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |

-### Avatar.Fallback Props
+### Avatar.Fallback

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `delayMs` | `number` | - | 显示回退内容前的延迟（减轻闪烁） |
-| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | 覆盖父级的颜色 |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `delayMs` | `number` | - | 显示 fallback 前的延迟（防止闪烁） |
+| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | 覆盖父级颜色 |
+| `className` | `string` | - | 附加 CSS 类 |
+
+## 相关组件
+
+<RelatedComponents component="avatar" />
@@ -1,6 +1,6 @@
 ---
 title: Accordion 手风琴
-description: 用于在紧凑空间中组织信息的可折叠内容面板。
+description: 用于在紧凑空间中组织信息的可折叠内容面板
 links:
  rac: Disclosure
  source: accordion/accordion.tsx
@@ -9,23 +9,18 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Accordion } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="accordion-basic"
  minHeight="400px"
 />

-
-### 组件结构
-
-引入 Accordion 组件并通过点语法访问所有子部分。
+## 组件结构

 ```tsx
 import { Accordion } from '@heroui/react';
@@ -46,21 +41,37 @@ export default () => (
 )
 ```

-### Surface
+## 示例
+
+### 表面样式

 <ComponentPreview
  name="accordion-surface"
- minHeight="400px"
+  minHeight="400px"
 />

-### 多项同时展开
+### 无分隔线
+
+<ComponentPreview
+  name="accordion-without-separator"
+  minHeight="400px"
+/>
+
+### 多项展开

 <ComponentPreview
  name="accordion-multiple"
-   minHeight="524px"
+  minHeight="524px"
 />

-### 受控
+### 禁用状态
+
+<ComponentPreview
+  name="accordion-disabled"
+  minHeight="524px"
+/>
+
+### 受控组件

 <ComponentPreview
  name="accordion-controlled"
@@ -71,123 +82,33 @@ export default () => (

 <ComponentPreview
  name="accordion-custom-indicator"
-   minHeight="320px"
+  minHeight="320px"
 />

-### 禁用状态
+### 渲染函数

 <ComponentPreview
-  name="accordion-disabled"
-   minHeight="524px"
+  name="accordion-render-function"
+  minHeight="400px"
 />

-### FAQ 布局
+### 常见问题布局

 <ComponentPreview
  name="accordion-faq"
  minHeight="720px"
 />

-### 自定义样式
+## 自定义样式

-<ComponentPreview
-  name="accordion-custom-styles"
-  minHeight="420px"
-/>
+### Tailwind CSS

-### 无分隔线
+<ComponentPreview name="accordion-custom-styles" />

-<ComponentPreview
-  name="accordion-without-separator"
-  minHeight="400px"
-/>
-
-### 自定义渲染函数
-
-<ComponentPreview
-  name="accordion-custom-render-function"
-  minHeight="400px"
-/>
-
-<RelatedComponents component="accordion" />
-
-## 样式
-
-### 传入 Tailwind CSS 类
-
-<CollapsibleCode lang="tsx" code={`"use client";
-
-import { Accordion, cn } from "@heroui/react";
-import {Icon} from "@iconify/react";
-
-const items = [
-  {
-    content:
-      "Stay informed about your account activity with real-time notifications. You'll receive instant alerts for important events like transactions, new messages, security updates, and system announcements. ",
-    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png",
-    title: "Set Up Notifications",
-    subtitle: "Receive account activity updates",
-  },
-  {
-    content:
-      "Enhance your browsing experience by installing our official browser extension. The extension provides seamless integration with your account, allowing you to receive notifications directly in your browser, quickly access your dashboard, and interact with web3 applications securely. Compatible with Chrome, Firefox, Edge, and Brave browsers.",
-    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png",
-    title: "Set up Browser Extension",
-    subtitle: "Connect you browser to your account",
-  },
-  {
-    content:
-      "Begin your journey into the world of digital collectibles by creating your first NFT. Our intuitive minting process guides you through uploading your artwork, setting metadata, choosing royalty percentages, and deploying to the blockchain. Whether you're an artist, creator, or collector, you'll find all the tools you need to bring your digital assets to life. Your collectibles are stored on IPFS for permanent decentralized storage.",
-    iconUrl:
-      "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png",
-    title: "Mint Collectible",
-    subtitle: "Create your first collectible",
-  },
-];
-
-export function CustomStyles() {
-  return (
-    <Accordion className="bg-surface-secondary w-full max-w-md rounded-2xl" variant="surface">
-      {items.map((item, index) => (
-        <Accordion.Item
-          key={index}
-          className={cn(
-            "group/item",
-            "first:[&_[data-slot=accordion-trigger]]:rounded-t-2xl", // 第一个触发器：圆角顶部
-            "last:[&:not(:has([data-slot=accordion-trigger][aria-expanded='true']))_[data-slot=accordion-trigger]]:rounded-b-2xl", // 最后一个触发器：圆角底部
-          )}
-        >
-          <Accordion.Heading>
-            <Accordion.Trigger className="hover:bg-surface-tertiary group flex items-center gap-2">
-              {item.iconUrl ? (
-                <img
-                  alt={item.title}
-                  className="group-hover/item:scale-120 group-hover/item:-rotate-10 h-11 w-11 transition-[scale,rotate] duration-300 ease-out group-hover/item:drop-shadow-lg"
-                  src={item.iconUrl}
-                />
-              ) : null}
-              <div className="flex flex-col gap-0">
-                <span className="font-medium leading-5">{item.title}</span>
-                <span className="text-muted/80 font-normal leading-6">{item.subtitle}</span>
-              </div>
-              <Accordion.Indicator className="text-muted/50 [&>svg]:size-4">
-                <Icon icon="gravity-ui:chevron-down" />
-              </Accordion.Indicator>
-            </Accordion.Trigger>
-          </Accordion.Heading>
-          <Accordion.Panel>
-            <Accordion.Body className="text-muted/80">{item.content}</Accordion.Body>
-          </Accordion.Panel>
-        </Accordion.Item>
-      ))}
-    </Accordion>
-  );
-}`} />
-
-### 自定义组件类
+### 全局 CSS

 若要自定义 Accordion 组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -205,13 +126,15 @@ export function CustomStyles() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Accordion 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/accordion.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.accordion` - Accordion 根容器
 - `.accordion__body` - 正文容器
 - `.accordion__heading` - 标题包裹层
@@ -220,10 +143,10 @@ Accordion 组件使用以下 CSS 类（[查看源码样式](https://github.com/h
 - `.accordion__panel` - 可折叠面板容器
 - `.accordion__trigger` - 可点击的触发按钮

-#### 变体类
+#### 变体类 [!toc]
 - `.accordion--outline` - 描边变体（边框与背景）

-#### 状态类
+#### 状态类 [!toc]
 - `.accordion__trigger[aria-expanded="true"]` - 展开状态
 - `.accordion__panel[aria-hidden="false"]` - 面板可见状态

@@ -238,63 +161,66 @@ Accordion 组件使用以下 CSS 类（[查看源码样式](https://github.com/h

 ## API 参考

-### Accordion Props
+### Accordion

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `allowsMultipleExpanded` | `boolean` | `false` | 是否允许多项同时展开。 |
-| `defaultExpandedKeys` | `Iterable<Key>` | - | 初始展开的 key。 |
-| `expandedKeys` | `Iterable<Key>` | - | 受控的展开 key。 |
-| `onExpandedChange` | `(keys: Set<Key>) => void` | - | 展开 key 变化时调用的事件处理函数。 |
-| `isDisabled` | `boolean` | `false` | 是否禁用整个 Accordion。 |
-| `variant` | `"default" \| "surface"` | `"default"` | Accordion 的视觉变体。 |
-| `hideSeparator` | `boolean` | `false` | 是否隐藏 Accordion 项之间的分隔线。 |
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | Accordion 项。 |
+| `allowsMultipleExpanded` | `boolean` | `false` | 是否允许多项同时展开 |
+| `defaultExpandedKeys` | `Iterable<Key>` | - | 初始展开的 key |
+| `expandedKeys` | `Iterable<Key>` | - | 受控的展开 key |
+| `onExpandedChange` | `(keys: Set<Key>) => void` | - | 展开 key 变化时调用的事件处理函数 |
+| `isDisabled` | `boolean` | `false` | 是否禁用整个 Accordion |
+| `variant` | `"default" \| "surface"` | `"default"` | Accordion 的视觉变体 |
+| `hideSeparator` | `boolean` | `false` | 是否隐藏 Accordion 项之间的分隔线 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | Accordion 项 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-
-### Accordion.Item Props
+### Accordion.Item

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `id` | `Key` | - | 该项的唯一标识。 |
-| `isDisabled` | `boolean` | `false` | 是否禁用该项。 |
-| `defaultExpanded` | `boolean` | `false` | 初始是否展开。 |
-| `isExpanded` | `boolean` | - | 受控展开状态。 |
-| `onExpandedChange` | `(isExpanded: boolean) => void` | - | 展开状态变化时调用的事件处理函数。 |
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | 项内容。 |
+| `id` | `Key` | - | 该项的唯一标识 |
+| `isDisabled` | `boolean` | `false` | 是否禁用该项 |
+| `defaultExpanded` | `boolean` | `false` | 初始是否展开 |
+| `isExpanded` | `boolean` | - | 受控展开状态 |
+| `onExpandedChange` | `(isExpanded: boolean) => void` | - | 展开状态变化时调用的事件处理函数 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 项内容 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionItemRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Accordion.Trigger Props
+### Accordion.Trigger

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode \| RenderFunction` | - | 触发器内容或渲染函数。 |
-| `onPress` | `() => void` | - | 额外的按下事件处理函数。 |
-| `isDisabled` | `boolean` | - | 是否禁用触发器。 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 触发器内容或渲染函数 |
+| `onPress` | `() => void` | - | 额外的按下事件处理函数 |
+| `isDisabled` | `boolean` | - | 是否禁用触发器 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TriggerRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Accordion.Panel Props
+### Accordion.Panel

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | 面板内容。 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 面板内容 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionPanelRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Accordion.Indicator Props
+### Accordion.Indicator

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | 自定义指示图标。 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 自定义指示图标 |

-### Accordion.Body Props
+### Accordion.Body

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | 正文内容。 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 正文内容 |
+
+## 相关组件
+
+<RelatedComponents component="accordion" />
@@ -1,6 +1,6 @@
 ---
 title: Breadcrumbs 面包屑
-description: 面包屑导航，用于展示当前页面在层级结构中的位置。
+description: 导航面包屑，显示当前页面在层级结构中的位置
 links:
  rac: Breadcrumbs
  source: breadcrumbs/breadcrumbs.tsx
@@ -8,21 +8,17 @@ links:
  storybook: Components/Navigation/Breadcrumbs
 ---

-## 引入
+## 用法

 ```tsx
 import { Breadcrumbs } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="breadcrumbs-basic"
 />

-### 组件结构
-
-导入 Breadcrumbs 组件后，可通过点语法访问各个子部分。
+## 组件结构

 ```tsx
 import { Breadcrumbs } from '@heroui/react';
@@ -36,6 +32,8 @@ export default () => (
 )
 ```

+## 示例
+
 ### 导航层级

 <ComponentPreview
@@ -46,47 +44,34 @@ export default () => (
  name="breadcrumbs-level-3"
 />

-### 自定义分隔符
-
-<ComponentPreview
-  name="breadcrumbs-custom-separator"
-/>
-
 ### 禁用状态

 <ComponentPreview
  name="breadcrumbs-disabled"
 />

-### 自定义渲染函数
+### 自定义分隔符

 <ComponentPreview
-  name="breadcrumbs-custom-render-function"
+  name="breadcrumbs-custom-separator"
 />

-## 样式
+### 渲染函数

-### 传入 Tailwind CSS 类
+<ComponentPreview
+  name="breadcrumbs-render-function"
+/>

-```tsx
-import { Breadcrumbs } from '@heroui/react';
+## 自定义样式

-function CustomBreadcrumbs() {
-  return (
-    <Breadcrumbs className="gap-2">
-      <Breadcrumbs.Item href="#" className="text-blue-600">
-        Home
-      </Breadcrumbs.Item>
-      <Breadcrumbs.Item>Current</Breadcrumbs.Item>
-    </Breadcrumbs>
-  );
-}
-```
+### Tailwind CSS

-### 自定义组件类
+<ComponentPreview name="breadcrumbs-custom-styles" />

-要自定义 Breadcrumbs 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+### 全局 CSS
+
+可使用 `@layer components` 指令自定义 Breadcrumbs 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -104,59 +89,63 @@ function CustomBreadcrumbs() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-Breadcrumbs 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/breadcrumbs.css)）：
-
-#### 基础类
+Breadcrumbs 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/breadcrumbs.css)）：

+#### 基础类 [!toc]
 - `.breadcrumbs` - 面包屑根容器
- `.breadcrumbs__item` - 单个面包屑项的包裹层
+- `.breadcrumbs__item` - 单个面包屑项包装器
 - `.breadcrumbs__link` - 面包屑链接元素
- `.breadcrumbs__separator` - 项之间的分隔图标
-
-#### 状态类
+- `.breadcrumbs__separator` - 项之间的分隔符图标

+#### 状态类 [!toc]
 - `.breadcrumbs__link[data-current="true"]` - 当前页指示（非链接）

 ### 交互状态

-组件同时支持 CSS 伪类与 data 属性，便于灵活编写样式：
+组件同时支持 CSS 伪类与 data 属性：

- **当前页**：链接上的 `[data-current="true"]`
- **悬停**：链接元素支持常规悬停态
- **禁用**：`isDisabled` prop 会禁用所有链接
+- **Current**：链接上的 `[data-current="true"]`（表示当前页）
+- **Hover**：链接元素支持标准 hover 状态
+- **Disabled**：`isDisabled` 属性禁用所有链接

 ## API 参考

-### Breadcrumbs Props
+### Breadcrumbs

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `separator` | `ReactNode` | chevron-right icon | 面包屑项之间的自定义分隔符 |
 | `isDisabled` | `boolean` | `false` | 是否禁用所有面包屑链接 |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |
 | `children` | `ReactNode` | - | 面包屑项 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### Breadcrumbs.Item Props
+### Breadcrumbs.Item

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `href` | `string` | - | 链接 URL（当前页可省略） |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `children` | `ReactNode \| RenderFunction` | - | 项内容或渲染函数 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, BreadcrumbRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 项内容或 render 函数 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, BreadcrumbRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

 ## 无障碍

-Breadcrumbs 基于 React Aria Components 的 Breadcrumbs 原语，提供：
+Breadcrumbs 使用 React Aria Components 的 Breadcrumbs 原语，提供：

- 导航地标的合适 ARIA 属性
- 通过 `aria-current="page"` 标示当前页
+- 导航地标的正确 ARIA 属性
+- 通过 `aria-current="page"` 指示当前页
 - 键盘导航支持
- 屏幕阅读器对导航上下文的播报
+- 导航上下文的屏幕阅读器播报

-最后一项（无 `href`）会自动作为当前页指示。
+最后一项（无 `href`）自动成为当前页指示。
+
+## 相关组件
+
+<RelatedComponents component="breadcrumbs" />
@@ -1,6 +1,6 @@
 ---
 title: DisclosureGroup 折叠面板组
-description: 管理多个 Disclosure 的容器，用于协调展开状态。
+description: 管理多个 Disclosure 项展开状态的容器
 links:
  rac: DisclosureGroup
  source: disclosure-group/disclosure-group.tsx
@@ -8,23 +8,18 @@ links:
  storybook: Components/Navigation/DisclosureGroup
 ---

-## 引入
+## 用法

 ```tsx
 import { DisclosureGroup } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="disclosure-group-basic"
  minHeight="580px"
 />

-
-### 组件结构
-
-导入所有子部分并组合使用。
+## 组件结构

 ```tsx
 import {DisclosureGroup, Disclosure} from '@heroui/react';
@@ -43,53 +38,27 @@ export default () => (
 )
 ```

-### 受控
+## 示例

-你可以使用 `expandedKeys` 与 `onExpandedChange` props，通过外部导航控件控制哪些 Disclosure 处于展开状态。
+### 受控组件
+
+可使用 `expandedKeys` 与 `onExpandedChange` props 配合外部导航控件控制哪些 Disclosure 处于展开状态。

 <ComponentPreview
  name="disclosure-group-controlled"
  minHeight="580px"
 />

+## 自定义样式

+### Tailwind CSS

-<RelatedShowcases component="DisclosureGroup" />
+<ComponentPreview name="disclosure-group-custom-styles" />

-<RelatedComponents component="disclosuregroup" />
+### 全局 CSS

-## 样式
-
-### 传入 Tailwind CSS 类
-
-```tsx
-import {
-  DisclosureGroup,
-  Disclosure,
-  DisclosureTrigger,
-  DisclosurePanel
-} from '@heroui/react';
-
-function CustomDisclosureGroup() {
-  return (
-    <DisclosureGroup className="border rounded-lg p-4 space-y-2">
-      <Disclosure id="first" className="border-b pb-2">
-        <DisclosureTrigger>Item 1</DisclosureTrigger>
-        <DisclosurePanel>Content 1</DisclosurePanel>
-      </Disclosure>
-      <Disclosure id="second">
-        <DisclosureTrigger>Item 2</DisclosureTrigger>
-        <DisclosurePanel>Content 2</DisclosurePanel>
-      </Disclosure>
-    </DisclosureGroup>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 DisclosureGroup 组件类，可以使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+可使用 `@layer components` 指令自定义 DisclosureGroup 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -102,42 +71,51 @@ function CustomDisclosureGroup() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 DisclosureGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure-group.css)）：

-#### 基础类
-
- `.disclosure-group` - 带布局 containment 的基础容器样式
+#### 基础类 [!toc]
+- `.disclosure-group` - 基础容器样式，含布局 containment

 ### 交互状态

-组件同时支持 CSS 伪类与 data 属性，以便灵活控制状态：
+组件同时支持 CSS 伪类与 data 属性：

- **禁用**：在整个组合上使用 `:disabled` 或 `[aria-disabled="true"]`
- **展开管理**：自动管理子 Disclosure 项上的 `[data-expanded]` 等状态
+- **Disabled**：整个分组上 `:disabled` 或 `[aria-disabled="true"]`
+- **Expanded Management**：自动管理子 Disclosure 项上的 `[data-expanded]` 状态

 ## API 参考

-### DisclosureGroup Props
+### DisclosureGroup

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `expandedKeys` | `Set<Key>` | - | 当前展开项（受控） |
 | `defaultExpandedKeys` | `Iterable<Key>` | - | 初始展开项（非受控） |
-| `onExpandedChange` | `(keys: Set<Key>) => void` | - | 展开项变化时调用的处理函数 |
+| `onExpandedChange` | `(keys: Set<Key>) => void` | - | 展开项变化时的回调 |
 | `allowsMultipleExpanded` | `boolean` | `false` | 是否允许多项同时展开 |
-| `isDisabled` | `boolean` | `false` | 是否禁用组内全部 Disclosure |
+| `isDisabled` | `boolean` | `false` | 是否禁用组内所有 Disclosure |
 | `children` | `ReactNode \| RenderFunction` | - | 要渲染的 Disclosure 项 |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |

-### RenderProps
+### Render Props

-使用渲染 prop 模式时，会提供以下值：
+使用 render prop 模式时，提供以下值：

 | Prop | 类型 | 描述 |
 |------|------|------|
-| `expandedKeys` | `Set<Key>` | 当前展开的 key |
-| `isDisabled` | `boolean` | 组合是否禁用 |
+| `expandedKeys` | `Set<Key>` | 当前展开项的 key |
+| `isDisabled` | `boolean` | 分组是否禁用 |
+
+## 相关案例
+
+<RelatedShowcases component="DisclosureGroup" />
+
+## 相关组件
+
+<RelatedComponents component="disclosuregroup" />
@@ -1,6 +1,6 @@
 ---
 title: Disclosure 折叠面板
-description: Disclosure 是一种可折叠区域：头部包含标题与触发按钮，面板包裹正文内容。
+description: 可折叠区块，包含标题、触发按钮与内容面板
 links:
  rac: Disclosure
  source: disclosure/disclosure.tsx
@@ -9,22 +9,18 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Disclosure } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="disclosure-basic"
  minHeight="440px"
 />

-### 组件结构
-
-导入 Disclosure 组件后，可通过点号访问各个子部分。
+## 组件结构

 ```tsx
 import { Disclosure } from '@heroui/react';
@@ -41,46 +37,24 @@ export default () => (
 )
 ```

-<RelatedShowcases component="Disclosure" />
+## 示例

-<RelatedComponents component="disclosure" />
-
-### 自定义渲染函数
+### 渲染函数

 <ComponentPreview
-  name="disclosure-custom-render-function"
+  name="disclosure-render-function"
 />

-## 样式
+## 自定义样式

-### 传入 Tailwind CSS 类
+### Tailwind CSS

-```tsx
-import { Disclosure } from '@heroui/react';
+<ComponentPreview name="disclosure-custom-styles" />

-function CustomDisclosure() {
-  return (
-    <Disclosure className="border rounded-lg p-4">
-      <Disclosure.Heading>
-        <Disclosure.Trigger className="text-lg font-semibold">
-          Click to expand
-          <Disclosure.Indicator />
-        </Disclosure.Trigger>
-      </Disclosure.Heading>
-      <Disclosure.Content>
-        <Disclosure.Body className="mt-4 text-gray-600">
-          Hidden content
-        </Disclosure.Body>
-      </Disclosure.Content>
-    </Disclosure>
-  );
-}
-```
+### 全局 CSS

-### 自定义组件类
-
-要自定义 Disclosure 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 Disclosure 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -102,63 +76,71 @@ function CustomDisclosure() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-Disclosure 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure.css)）：
+Disclosure 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.disclosure` - 基础容器样式
 - `.disclosure__heading` - 标题包裹层
 - `.disclosure__trigger` - 触发按钮样式
- `.disclosure__indicator` - Chevron 指示器样式
+- `.disclosure__indicator` - 箭头指示器样式
 - `.disclosure__content` - 带动画的内容容器

 ### 交互状态

-组件同时支持 CSS 伪类与 data 属性，便于灵活定制：
+组件同时支持 CSS 伪类与 data 属性：

- **Expanded**：指示器上 `[data-expanded="true"]`，用于旋转等效果
+- **Expanded**：指示器上 `[data-expanded="true"]` 用于旋转
 - **Focus**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
 - **Disabled**：触发器上 `:disabled` 或 `[aria-disabled="true"]`
- **Hidden**：内容上 `[aria-hidden="false"]` 表示可见
-
+- **Hidden**：内容上 `[aria-hidden="false"]` 控制可见性

 ## API 参考

-### Disclosure Props
+### Disclosure

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `isExpanded` | `boolean` | `false` | 控制展开状态 |
 | `onExpandedChange` | `(isExpanded: boolean) => void` | - | 展开状态变化时的回调 |
-| `isDisabled` | `boolean` | `false` | 是否禁用 Disclosure |
+| `isDisabled` | `boolean` | `false` | 是否禁用 |
 | `children` | `ReactNode \| RenderFunction` | - | 要渲染的内容 |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+| `className` | `string` | - | 附加 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### DisclosureTrigger Props
+### DisclosureTrigger

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `ReactNode \| RenderFunction` | - | 触发器内容 |
-| `className` | `string` | - | 额外的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |

-### DisclosureContent Props
+### DisclosureContent

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `children` | `ReactNode` | - | 要显示/隐藏的内容 |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureContentRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+| `children` | `ReactNode` | - | 显示/隐藏的内容 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureContentRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

+### Render Props

-### RenderProps
-
-使用渲染 prop 模式时，会提供以下值：
+使用 render prop 模式时，提供以下值：

 | Prop | 类型 | 描述 |
 |------|------|------|
-| `isExpanded` | `boolean` | 当前是否展开 |
-| `isDisabled` | `boolean` | Disclosure 是否禁用 |
+| `isExpanded` | `boolean` | 当前展开状态 |
+| `isDisabled` | `boolean` | 是否禁用 |
+
+## 相关案例
+
+<RelatedShowcases component="Disclosure" />
+
+## 相关组件
+
+<RelatedComponents component="disclosure" />
@@ -9,19 +9,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Link } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="link-basic"
 />

-### 组件结构
+## 组件结构

 导入 Link 组件后，可通过点语法访问所有子部分。

@@ -36,11 +34,7 @@ export default () => (
 );
 ```

-### 自定义图标
-
-<ComponentPreview
-  name="link-custom-icon"
-/>
+## 示例

 ### 图标位置

@@ -85,58 +79,49 @@ Link 默认在悬浮时显示下划线。可使用 Tailwind CSS 的 text-decorat
 - [text-decoration-thickness](https://tailwindcss.com/docs/text-decoration-thickness)
 - [text-underline-offset](https://tailwindcss.com/docs/text-underline-offset)

-
 可用的 BEM 类：
 - 基础：`link`
 - 图标：`link__icon`

-<RelatedComponents component="link" />
-
-### 自定义渲染函数
+### 自定义图标

 <ComponentPreview
-  name="link-custom-render-function"
+  name="link-custom-icon"
 />

-## 样式
+### 渲染函数

-### 传入 Tailwind CSS 类
+<ComponentPreview
+  name="link-render-function"
+/>

-```tsx
-import { Link } from '@heroui/react';
+## 自定义样式

-function CustomLink() {
-  return (
-    <Link
-      href="#"
-      className="text-lg font-bold text-accent hover:text-accent/80"
-    >
-      Custom styled link
-    </Link>
-  );
-}
-```
+### Tailwind CSS

-### 自定义组件类
+<ComponentPreview name="link-custom-styles" />

-要自定义 Link 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+### 全局 CSS
+
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
  .link {
-    @apply font-semibold;
+    @apply font-semibold no-underline hover:underline;
  }
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Link 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/link.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.link` — 链接基础样式
 - `.link__icon` — 链接图标样式

@@ -151,8 +136,7 @@ Link 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/h

 ## API 参考

-### Link Props
-
+### Link
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `href` | `string` | - | 锚点的目标 URL |
@@ -166,8 +150,7 @@ Link 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/h
 | `autoFocus` | `boolean` | - | 元素挂载时是否应获得焦点 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, LinkRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |

-### Link.Icon Props
-
+### Link.Icon
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 自定义图标元素；省略时使用内置箭头图标 |
@@ -222,3 +205,7 @@ export default function NativeLink() {
  );
 }
 ```
+
+## 相关组件
+
+<RelatedComponents component="link" />
@@ -7,19 +7,17 @@ links:
  storybook: Components/Navigation/Pagination
 ---

-## 引入
+## 用法

 ```tsx
 import { Pagination } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="pagination-basic"
 />

-### 组件结构
+## 组件结构

 导入 Pagination 组件后，可通过点号访问各个子部分。

@@ -56,16 +54,18 @@ export default () => (
 );
 ```

+## 示例
+
 ### 尺寸

 <ComponentPreview
  name="pagination-sizes"
 />

-### 带省略号
+### 禁用

 <ComponentPreview
-  name="pagination-with-ellipsis"
+  name="pagination-disabled"
 />

 ### 简化（上一页 / 下一页）
@@ -74,6 +74,18 @@ export default () => (
  name="pagination-simple-prev-next"
 />

+### 受控组件
+
+<ComponentPreview
+  name="pagination-controlled"
+/>
+
+### 带省略号
+
+<ComponentPreview
+  name="pagination-with-ellipsis"
+/>
+
 ### 带摘要

 <ComponentPreview
@@ -82,52 +94,21 @@ export default () => (

 ### 自定义图标

-你可以通过为 `PreviousIcon` 与 `NextIcon` 传入自定义子节点来替换默认的 chevron 图标。
+可通过向 `PreviousIcon` 与 `NextIcon` 传入自定义子元素来替换默认 chevron 图标。

 <ComponentPreview
  name="pagination-custom-icons"
 />

-### 受控
+## 自定义样式

-<ComponentPreview
-  name="pagination-controlled"
-/>
+### Tailwind CSS

-### 禁用
+<ComponentPreview name="pagination-custom-styles" />

-<ComponentPreview
-  name="pagination-disabled"
-/>
+### 全局 CSS

-<RelatedComponents component="pagination" />
-
-## 样式
-
-### 传入 Tailwind CSS 类
-
-你可以单独定制 Pagination 的各个子部分：
-
-```tsx
-import { Pagination } from '@heroui/react';
-
-function CustomPagination() {
-  return (
-    <Pagination className="gap-8">
-      <Pagination.Content className="gap-2">
-        <Pagination.Item>
-          <Pagination.Link className="rounded-md" isActive>1</Pagination.Link>
-        </Pagination.Item>
-      </Pagination.Content>
-    </Pagination>
-  );
-}
-```
-
-### 自定义组件类
-
-要自定义 Pagination 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -145,13 +126,15 @@ function CustomPagination() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Pagination 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/pagination.css)）：

-#### 基础与布局类
+#### 基础与布局类 [!toc]
 - `.pagination` - 根导航容器（flex 布局）
 - `.pagination__summary` - 左侧信息文本容器
 - `.pagination__content` - 分页项容器
@@ -160,7 +143,7 @@ Pagination 使用以下 CSS 类（[查看源码样式](https://github.com/heroui
 - `.pagination__link--nav` - 导航按钮修饰符（Previous/Next）
 - `.pagination__ellipsis` - 省略号指示器

-#### 尺寸类
+#### 尺寸类 [!toc]
 - `.pagination--sm` - 小尺寸变体
 - `.pagination--md` - 中尺寸变体（默认）
 - `.pagination--lg` - 大尺寸变体
@@ -177,37 +160,32 @@ Pagination 使用以下 CSS 类（[查看源码样式](https://github.com/heroui

 ## API 参考

-### Pagination Props
-
+### Pagination
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `size` | `"sm" \| "md" \| "lg"` | `"md"` | 分页控件的尺寸 |
 | `className` | `string` | - | 额外的 CSS 类 |
 | `children` | `ReactNode` | - | 分页部件（Summary、Content 等） |

-### Pagination.Summary Props
-
+### Pagination.Summary
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类 |
 | `children` | `ReactNode` | - | 摘要内容（例如 "Showing 1-10 of 120"） |

-### Pagination.Content Props
-
+### Pagination.Content
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类 |
 | `children` | `ReactNode` | - | 分页项 |

-### Pagination.Item Props
-
+### Pagination.Item
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类 |
 | `children` | `ReactNode` | - | 项内容（Link、Previous、Next 或 Ellipsis） |

-### Pagination.Link Props
-
+### Pagination.Link
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `isActive` | `boolean` | `false` | 是否为当前页 |
@@ -216,8 +194,7 @@ Pagination 使用以下 CSS 类（[查看源码样式](https://github.com/heroui
 | `className` | `string` | - | 额外的 CSS 类 |
 | `children` | `ReactNode` | - | 页码内容 |

-### Pagination.Previous / Pagination.Next Props
-
+### Pagination.Previous / Pagination.Next
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `isDisabled` | `boolean` | `false` | 是否禁用按钮 |
@@ -225,19 +202,21 @@ Pagination 使用以下 CSS 类（[查看源码样式](https://github.com/heroui
 | `className` | `string` | - | 额外的 CSS 类 |
 | `children` | `ReactNode` | - | 按钮内容（可与 PreviousIcon/NextIcon 组合） |

-### Pagination.PreviousIcon / Pagination.NextIcon Props
-
+### Pagination.PreviousIcon / Pagination.NextIcon
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类 |
 | `children` | `ReactNode` | Default chevron SVG | 用于替换默认 chevron 的自定义图标 |

-### Pagination.Ellipsis Props
-
+### Pagination.Ellipsis
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 额外的 CSS 类 |

+## 说明
+
+Pagination 按钮使用 `onPress` 而非 `onClick`。React Aria 的 `onPress` 处理函数会统一不同指针类型的按压行为，并内置无障碍改进。
+
 ## 无障碍

 Pagination 基于 [React Aria 的 Button](https://react-spectrum.adobe.com/react-aria/Button.html) 原语实现所有可交互元素，并提供：
@@ -251,3 +230,7 @@ Pagination 基于 [React Aria 的 Button](https://react-spectrum.adobe.com/react
 - 通过 `isDisabled` 向辅助技术正确传达禁用状态

 > **说明：** Pagination 按钮请使用 `onPress` 而不是 `onClick`。React Aria 的 `onPress` 会规范化不同指针类型的按下行为，并提供开箱即用的无障碍改进。
+
+## 相关组件
+
+<RelatedComponents component="pagination" />
@@ -10,20 +10,18 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Tabs } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  isBgSolid
  name="tabs-basic"
 />

-### 组件结构
+## 组件结构

 导入 Tabs 组件后，可通过点语法访问所有子部分。

@@ -45,6 +43,8 @@ export default () => (
 )
 ```

+## 示例
+
 ### 垂直布局

 <ComponentPreview
@@ -77,116 +77,99 @@ export default () => (
  name="tabs-with-separator"
 />

-### 自定义样式
-
-<ComponentPreview
-  isBgSolid
-  name="tabs-custom-styles"
-/>
-
-### Secondary 变体
+### 次要类型

 <ComponentPreview
  isBgSolid
  name="tabs-secondary"
 />

-### Secondary 变体（垂直）
+### 次要类型（垂直）

 <ComponentPreview
  isBgSolid
  name="tabs-secondary-vertical"
 />

-<RelatedShowcases component="Tabs" />
-
-<RelatedComponents component="tabs" />
-
-### 自定义渲染函数
+### 渲染函数

 <ComponentPreview
-  name="tabs-custom-render-function"
+  name="tabs-render-function"
 />

-## 样式
+## 自定义样式

-### 传入 Tailwind CSS 类
+### Tailwind CSS

-<CollapsibleCode lang="tsx" code={`
-import { Tabs } from '@heroui/react';
+<ComponentPreview name="tabs-custom-styles" />

-function CustomTabs() {
-  return (
-    <Tabs className="w-full max-w-lg text-center">
-      <Tabs.ListContainer>
-        <Tabs.List
-          aria-label="Options"
-          className="*:data-[selected=true]:text-accent-foreground w-fit *:h-6 *:w-fit *:px-3 *:text-sm *:font-normal"
-        >
-          <Tabs.Tab id="daily">Daily<Tabs.Indicator /></Tabs.Tab>
-          <Tabs.Tab id="weekly">Weekly<Tabs.Indicator /></Tabs.Tab>
-          <Tabs.Tab id="bi-weekly">Bi-Weekly<Tabs.Indicator /></Tabs.Tab>
-          <Tabs.Tab id="monthly">Monthly<Tabs.Indicator /></Tabs.Tab>
-        </Tabs.List>
-      </Tabs.ListContainer>
-      <Tabs.Panel className="px-4" id="daily">
-        <h3 className="mb-2 font-semibold">Daily</h3>
-        <p className="text-sm text-gray-600">Manage your daily tasks and goals.</p>
-      </Tabs.Panel>
-      <Tabs.Panel className="px-4" id="weekly">
-        <h3 className="mb-2 font-semibold">Weekly</h3>
-        <p className="text-sm text-gray-600">Manage your weekly tasks and goals.</p>
-      </Tabs.Panel>
-      <Tabs.Panel className="px-4" id="bi-weekly">
-        <h3 className="mb-2 font-semibold">Bi-Weekly</h3>
-        <p className="text-sm text-gray-600">Manage your bi-weekly tasks and goals.</p>
-      </Tabs.Panel>
-      <Tabs.Panel className="px-4" id="monthly">
-        <h3 className="mb-2 font-semibold">Monthly</h3>
-        <p className="text-sm text-gray-600">Manage your monthly tasks and goals.</p>
-      </Tabs.Panel>
-    </Tabs>
-  );
+### 全局 CSS
+
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .tabs__list {
+    @apply rounded-xl border border-border bg-surface p-1;
+  }
+
+  .tabs__tab {
+    @apply rounded-lg font-medium;
+  }
+
+  .tabs__indicator {
+    @apply rounded-lg bg-foreground shadow-sm;
+  }
+
+  .tabs--secondary > .tabs__list-container > .tabs__list {
+    @apply border-b border-border bg-transparent p-0;
+  }
+
+  .tabs--secondary > .tabs__list-container .tabs__indicator {
+    @apply rounded-none bg-accent;
+  }
 }
-`} />
+```
+
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-Tabs 使用以下 CSS 类：
+Tabs 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tabs.css)）：

-#### 基础类
- `.tabs` — Tabs 根容器
- `.tabs__list-container` — 标签列表容器外层包裹
- `.tabs__list-container__scroller` — 标签列表的可滚动容器（处理溢出与渐隐边缘）
- `.tabs__list-container__scroll-prev` — 向前（左 / 上）滚动的箭头按钮
- `.tabs__list-container__scroll-next` — 向后（右 / 下）滚动的箭头按钮
- `.tabs__list` — 标签列表容器
- `.tabs__tab` — 单个标签按钮
- `.tabs__separator` — 标签之间的分隔线
- `.tabs__panel` — 标签面板内容
- `.tabs__indicator` — 标签指示器
+#### 基础类 [!toc]
+- `.tabs` - Tabs 根容器
+- `.tabs__list-container` - 标签列表容器外层包裹
+- `.tabs__list-container__scroller` - 标签列表的可滚动容器（处理溢出与渐隐边缘）
+- `.tabs__list-container__scroll-prev` - 向前（左 / 上）滚动的箭头按钮
+- `.tabs__list-container__scroll-next` - 向后（右 / 下）滚动的箭头按钮
+- `.tabs__list` - 标签列表容器
+- `.tabs__tab` - 单个标签按钮
+- `.tabs__separator` - 标签之间的分隔线
+- `.tabs__panel` - 标签面板内容
+- `.tabs__indicator` - 标签指示器

-#### 方向属性
- `.tabs[data-orientation="horizontal"]` — 水平标签布局（默认）
- `.tabs[data-orientation="vertical"]` — 垂直标签布局
+#### 方向属性 [!toc]
+- `.tabs[data-orientation="horizontal"]` - 水平标签布局（默认）
+- `.tabs[data-orientation="vertical"]` - 垂直标签布局

-#### 变体类
- `.tabs--secondary` — Secondary 变体，使用下划线指示器
+#### 变体类 [!toc]
+- `.tabs--secondary` - 次要类型变体，使用下划线指示器

 ### 交互状态

 组件同时支持 CSS 伪类与 data 属性：

- **已选中**：`[aria-selected="true"]`
- **悬停**：`:hover` 或 `[data-hovered="true"]`
- **焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`
- **禁用**：`[aria-disabled="true"]`
-
-
+- **Selected**：`[aria-selected="true"]`
+- **Hover**：`:hover` 或 `[data-hovered="true"]`
+- **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **Disabled**：`[aria-disabled="true"]`

 ## API 参考

-### Tabs Props
+### Tabs

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
@@ -194,37 +177,45 @@ Tabs 使用以下 CSS 类：
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 标签布局方向 |
 | `selectedKey` | `string` | - | 受控选中标签的 key |
 | `defaultSelectedKey` | `string` | - | 默认选中标签的 key |
-| `onSelectionChange` | `(key: Key) => void` | - | 选中变化事件处理函数 |
-| `className` | `string` | - | 附加的 CSS 类 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabsRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+| `onSelectionChange` | `(key: Key) => void` | - | 选中变化回调 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabsRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### Tabs.List Props
+### Tabs.List

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `aria-label` | `string` | - | 标签列表的无障碍标签 |
-| `className` | `string` | - | 附加的 CSS 类 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabListRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabListRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### Tabs.Tab Props
+### Tabs.Tab

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `id` | `string` | - | 标签唯一标识 |
 | `isDisabled` | `boolean` | `false` | 是否禁用该标签 |
-| `className` | `string` | - | 附加的 CSS 类 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### Tabs.Separator Props
+### Tabs.Separator

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 附加的 CSS 类 |
+| `className` | `string` | - | 附加 CSS 类 |

-### Tabs.Panel Props
+### Tabs.Panel

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `id` | `string` | - | 与对应 Tab id 匹配的面板标识 |
-| `className` | `string` | - | 附加的 CSS 类 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabPanelRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabPanelRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |
+
+## 相关案例
+
+<RelatedShowcases component="Tabs" />
+
+## 相关组件
+
+<RelatedComponents component="tabs" />
@@ -1,6 +1,6 @@
 ---
 title: AlertDialog 警告对话框
-description: 用于关键确认的模态对话框，需要用户关注并执行明确操作。
+description: 用于关键确认操作的模态对话框，需要用户关注并明确操作
 links:
  rac: AlertDialog
  source: alert-dialog/alert-dialog.tsx
@@ -8,19 +8,15 @@ links:
  storybook: Components/Overlays/AlertDialog
 ---

-## 引入
+## 用法

 ```tsx
 import { AlertDialog } from "@heroui/react";
 ```

-### 用法
-
 <ComponentPreview name="alert-dialog-default" />

-### 组件结构
-
-导入 AlertDialog 组件后，可通过点语法访问各个子部分。
+## 组件结构

 ```tsx
 import {AlertDialog, Button} from "@heroui/react";
@@ -45,27 +41,37 @@ export default () => (
 );
 ```

-### 状态
+## 示例
+
+### 状态类型

 <ComponentPreview name="alert-dialog-statuses" />

-### 位置
+### 弹出位置

 <ComponentPreview name="alert-dialog-placements" />

-### 背景变体
-
-<ComponentPreview name="alert-dialog-backdrop-variants" />
-
 ### 尺寸

 <ComponentPreview name="alert-dialog-sizes" />

+### 受控模式
+
+<ComponentPreview name="alert-dialog-controlled" />
+
 ### 自定义图标

 <ComponentPreview name="alert-dialog-custom-icon" />

-### 自定义背景
+### 自定义触发器
+
+<ComponentPreview name="alert-dialog-custom-trigger" />
+
+### 遮罩变体
+
+<ComponentPreview name="alert-dialog-backdrop-variants" />
+
+### 自定义遮罩

 <ComponentPreview name="alert-dialog-custom-backdrop" />

@@ -77,14 +83,6 @@ export default () => (

 <ComponentPreview name="alert-dialog-close-methods" />

-### 受控状态
-
-<ComponentPreview name="alert-dialog-controlled" />
-
-### 自定义触发器
-
-<ComponentPreview name="alert-dialog-custom-trigger" />
-
 ### 自定义动画

 <ComponentPreview name="alert-dialog-custom-animations" />
@@ -93,52 +91,17 @@ export default () => (

 <ComponentPreview name="alert-dialog-custom-portal" />

-<RelatedComponents component="alert-dialog" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="alert-dialog-custom-styles" />

-```tsx
-import {AlertDialog, Button} from "@heroui/react";
+### 全局 CSS

-function CustomAlertDialog() {
-  return (
-    <AlertDialog>
-      <Button variant="danger">Delete</Button>
-      <AlertDialog.Backdrop className="bg-red-950/90">
-        <AlertDialog.Container className="items-start pt-20">
-          <AlertDialog.Dialog className="border-2 border-red-500 sm:max-w-[400px]">
-            <AlertDialog.CloseTrigger />
-            <AlertDialog.Header>
-              <AlertDialog.Icon status="danger" />
-              <AlertDialog.Heading>Custom Styled Alert</AlertDialog.Heading>
-            </AlertDialog.Header>
-            <AlertDialog.Body>
-              <p>This alert dialog has custom styling applied via Tailwind classes</p>
-            </AlertDialog.Body>
-            <AlertDialog.Footer>
-              <Button slot="close" variant="tertiary">
-                Cancel
-              </Button>
-              <Button slot="close" variant="danger">
-                Delete
-              </Button>
-            </AlertDialog.Footer>
-          </AlertDialog.Dialog>
-        </AlertDialog.Container>
-      </AlertDialog.Backdrop>
-    </AlertDialog>
-  );
-}
-```
+若要自定义 AlertDialog 组件类，可使用 `@layer components` 指令。

-### 自定义组件类
-
-要自定义 AlertDialog 的组件类，可使用 `@layer components` 指令。
-
-<br />
-[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -164,32 +127,34 @@ function CustomAlertDialog() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-AlertDialog 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert-dialog.css)）：
+AlertDialog 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert-dialog.css)）：

-#### 基础类
+#### 基础类 [!toc]

- `.alert-dialog__trigger` - 打开对话框的触发元素
+- `.alert-dialog__trigger` - 打开警告对话框的触发元素
 - `.alert-dialog__backdrop` - 对话框背后的遮罩层
- `.alert-dialog__container` - 支持位置配置的包裹层
+- `.alert-dialog__container` - 支持 placement 的定位包裹层
 - `.alert-dialog__dialog` - 对话框内容容器
- `.alert-dialog__header` - 图标与标题区域
+- `.alert-dialog__header` - 图标与标题的头部区域
 - `.alert-dialog__heading` - 标题文本样式
 - `.alert-dialog__body` - 主内容区域
- `.alert-dialog__footer` - 操作按钮区域
+- `.alert-dialog__footer` - 操作按钮的底部区域
 - `.alert-dialog__icon` - 带状态色的图标容器
 - `.alert-dialog__close-trigger` - 关闭按钮元素

-#### 背景变体
+#### 遮罩变体 [!toc]

- `.alert-dialog__backdrop--opaque` - 不透明有色背景（默认）
- `.alert-dialog__backdrop--blur` - 带玻璃效果的模糊背景
- `.alert-dialog__backdrop--transparent` - 透明背景（无遮罩）
+- `.alert-dialog__backdrop--opaque` - 不透明彩色遮罩（默认）
+- `.alert-dialog__backdrop--blur` - 带玻璃效果的模糊遮罩
+- `.alert-dialog__backdrop--transparent` - 透明遮罩（无覆盖层）

-#### 状态变体（图标）
+#### 状态变体（图标）[!toc]

 - `.alert-dialog__icon--default` - 默认灰色状态
 - `.alert-dialog__icon--accent` - 强调蓝色状态
@@ -199,93 +164,93 @@ AlertDialog 使用以下 CSS 类（[查看源码样式](https://github.com/herou

 ### 交互状态

-组件支持以下交互状态：
+该组件支持以下交互状态：

- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]` — 应用于触发器、对话框与关闭按钮
- **悬停**：`:hover` 或 `[data-hovered="true"]` — 应用于关闭按钮悬停时
- **激活**：`:active` 或 `[data-pressed="true"]` — 应用于关闭按钮按下时
- **进入**：`[data-entering]` — 应用于对话框打开动画期间
- **离开**：`[data-exiting]` — 应用于对话框关闭动画期间
- **位置**：`[data-placement="*"]` — 根据对话框位置应用（auto、top、center、bottom）
+- **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]` — 应用于 trigger、dialog 和 close 按钮
+- **Hover**：`:hover` 或 `[data-hovered="true"]` — 应用于 close 按钮悬停时
+- **Active**：`:active` 或 `[data-pressed="true"]` — 应用于 close 按钮按下时
+- **Entering**：`[data-entering]` — 对话框打开动画期间
+- **Exiting**：`[data-exiting]` — 对话框关闭动画期间
+- **Placement**：`[data-placement="*"]` — 根据对话框位置应用（auto、top、center、bottom）

 ## API 参考

 ### AlertDialog

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
+|------|------|--------|------|
 | `children` | `ReactNode` | - | 触发器与容器元素 |

 ### AlertDialog.Trigger

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
+|------|------|--------|------|
 | `children` | `ReactNode` | - | 自定义触发器内容 |
 | `className` | `string` | - | CSS 类 |

 ### AlertDialog.Backdrop

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
-| `variant` | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 背景遮罩样式 |
-| `isDismissable` | `boolean` | `false` | 点击背景是否关闭 |
-| `isKeyboardDismissDisabled` | `boolean` | `true` | 是否禁用 ESC 关闭 |
+|------|------|--------|------|
+| `variant` | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 遮罩覆盖层样式 |
+| `isDismissable` | `boolean` | `false` | 点击遮罩是否关闭 |
+| `isKeyboardDismissDisabled` | `boolean` | `true` | 是否禁用 ESC 键关闭 |
 | `isOpen` | `boolean` | - | 受控的打开状态 |
-| `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化的事件处理函数 |
-| `className` | `string \| (values) => string` | - | 背景的 CSS 类 |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化处理函数 |
+| `className` | `string \| (values) => string` | - | 遮罩 CSS 类 |
 | `UNSTABLE_portalContainer` | `HTMLElement` | - | 自定义 portal 容器 |

 ### AlertDialog.Container

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
+|------|------|--------|------|
 | `placement` | `"auto" \| "center" \| "top" \| "bottom"` | `"auto"` | 对话框在屏幕上的位置 |
-| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "cover"` | `"md"` | AlertDialog 尺寸变体 |
-| `className` | `string \| (values) => string` | - | 容器的 CSS 类 |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "cover"` | `"md"` | Alert Dialog 尺寸变体 |
+| `className` | `string \| (values) => string` | - | 容器 CSS 类 |

 ### AlertDialog.Dialog

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
+|------|------|--------|------|
 | `children` | `ReactNode \| ({close}) => ReactNode` | - | 内容或渲染函数 |
 | `className` | `string` | - | CSS 类 |
 | `role` | `string` | `"alertdialog"` | ARIA role |
 | `aria-label` | `string` | - | 无障碍标签 |
-| `aria-labelledby` | `string` | - | 标签元素的 id |
-| `aria-describedby` | `string` | - | 描述元素的 id |
+| `aria-labelledby` | `string` | - | 标签元素的 ID |
+| `aria-describedby` | `string` | - | 描述元素的 ID |

 ### AlertDialog.Header

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
-| `children` | `ReactNode` | - | 头部内容（通常为 Icon 与 Heading） |
+|------|------|--------|------|
+| `children` | `ReactNode` | - | 头部内容（通常为 Icon 和 Heading） |
 | `className` | `string` | - | CSS 类 |

 ### AlertDialog.Heading

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
+|------|------|--------|------|
 | `children` | `ReactNode` | - | 标题文本 |
 | `className` | `string` | - | CSS 类 |

 ### AlertDialog.Body

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
+|------|------|--------|------|
 | `children` | `ReactNode` | - | 正文内容 |
 | `className` | `string` | - | CSS 类 |

 ### AlertDialog.Footer

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
+|------|------|--------|------|
 | `children` | `ReactNode` | - | 底部内容（通常为操作按钮） |
 | `className` | `string` | - | CSS 类 |

 ### AlertDialog.Icon

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
+|------|------|--------|------|
 | `children` | `ReactNode` | - | 自定义图标元素 |
 | `status` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"danger"` | 状态颜色变体 |
 | `className` | `string` | - | CSS 类 |
@@ -293,7 +258,7 @@ AlertDialog 使用以下 CSS 类（[查看源码样式](https://github.com/herou
 ### AlertDialog.CloseTrigger

 | Prop | 类型 | 默认值 | 描述 |
-| ---- | ---- | ------ | ---- |
+|------|------|--------|------|
 | `children` | `ReactNode` | - | 自定义关闭按钮 |
 | `className` | `string \| (values) => string` | - | CSS 类 |

@@ -318,8 +283,12 @@ state.setOpen(); // Set state directly

 实现 [WAI-ARIA AlertDialog 模式](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/)：

- **焦点陷阱**：焦点限制在 AlertDialog 内
- **键盘**：`ESC` 关闭（若启用）、`Tab` 在可聚焦元素间循环
- **屏幕阅读器**：`role="alertdialog"` 等合适的 ARIA 属性
+- **焦点陷阱**：焦点锁定在警告对话框内
+- **键盘**：`ESC` 关闭（启用时）、`Tab` 循环切换元素
+- **屏幕阅读器**：使用 `role="alertdialog"` 的正确 ARIA 属性
 - **滚动锁定**：打开时禁用 body 滚动
- **需要明确操作**：默认需要用户明确操作（不通过点击背景/ESC 轻易关闭）
+- **必需操作**：默认需要用户明确操作（不可通过遮罩/ESC 关闭）
+
+## 相关组件
+
+<RelatedComponents component="alert-dialog" />
@@ -1,6 +1,6 @@
 ---
 title: Drawer 抽屉
-description: 用于补充内容与操作的侧滑面板。
+description: 用于补充内容与操作的滑出面板
 links:
  rac: Modal
  source: drawer/drawer.tsx
@@ -8,17 +8,15 @@ links:
  storybook: Components/Overlays/Drawer
 ---

-## 引入
+## 用法

 ```tsx
 import { Drawer, Button } from "@heroui/react";
 ```

-### 用法
-
 <ComponentPreview name="drawer-basic" />

-### 组件结构
+## 组件结构

 ```tsx
 import { Drawer, Button } from "@heroui/react";
@@ -43,31 +41,29 @@ export default () => (
 );
 ```

-### 位置
+## 示例
+
+### 弹出位置

 <ComponentPreview name="drawer-placements" />

-### 遮罩变体
-
-<ComponentPreview name="drawer-backdrop-variants" />
-
 ### 不可关闭

-在 `Drawer.Backdrop` 上设置 `isDismissable={false}`，可阻止通过点击外部或拖动关闭。用户必须与抽屉内的操作按钮交互才能关闭。
+在 `Drawer.Backdrop` 上设置 `isDismissable={false}` 可阻止点击外部或拖拽关闭。用户必须通过抽屉内的操作按钮交互。

 <ComponentPreview name="drawer-non-dismissable" />

 ### 可滚动内容

-`Drawer.Body` 会使用原生滚动处理溢出。为避免与滚动冲突，拖拽关闭不会在 body 区域生效。
+`Drawer.Body` 通过原生滚动自动处理溢出。拖拽关闭在 body 区域被排除，以避免与滚动冲突。

 <ComponentPreview name="drawer-scrollable-content" />

-### 受控状态
+### 受控模式

 <ComponentPreview name="drawer-controlled" />

-### 带表单
+### 搭配表单

 <ComponentPreview name="drawer-with-form" />

@@ -75,45 +71,20 @@ export default () => (

 <ComponentPreview name="drawer-navigation" />

-<RelatedComponents component="drawer" />
+### 遮罩变体

-## 样式
+<ComponentPreview name="drawer-backdrop-variants" />

-### 传入 Tailwind CSS 类
+## 自定义样式

-```tsx
-import { Drawer, Button } from "@heroui/react";
+### Tailwind CSS

-function CustomDrawer() {
-  return (
-    <Drawer>
-      <Button>Open Drawer</Button>
-      <Drawer.Backdrop className="bg-black/80">
-        <Drawer.Content>
-          <Drawer.Dialog className="bg-linear-to-br from-purple-500 to-pink-500 text-white">
-            <Drawer.CloseTrigger />
-            <Drawer.Header>
-              <Drawer.Heading>Custom Styled Drawer</Drawer.Heading>
-            </Drawer.Header>
-            <Drawer.Body>
-              <p>This drawer has custom styling applied via Tailwind classes.</p>
-            </Drawer.Body>
-            <Drawer.Footer>
-              <Button slot="close">Close</Button>
-            </Drawer.Footer>
-          </Drawer.Dialog>
-        </Drawer.Content>
-      </Drawer.Backdrop>
-    </Drawer>
-  );
-}
-```
+<ComponentPreview name="drawer-custom-styles" />

-### 自定义组件类
+### 全局 CSS

-若要自定义 Drawer 组件类，可以使用 `@layer components` 指令。
+可使用 `@layer components` 指令自定义 Drawer 组件类。

-<br />
 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@@ -136,140 +107,142 @@ function CustomDrawer() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Drawer 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/drawer.css)）：

-#### 基础类
+#### 基础类 [!toc]

- `.drawer__trigger` - 打开 Drawer 的触发元素
- `.drawer__backdrop` - Drawer 背后的遮罩
- `.drawer__content` - Drawer 面板的定位包裹层
- `.drawer__dialog` - Drawer 面板本体
- `.drawer__header` - 表头区域
+- `.drawer__trigger` - 打开抽屉的触发元素
+- `.drawer__backdrop` - 抽屉背后的遮罩层
+- `.drawer__content` - 抽屉面板的定位包裹层
+- `.drawer__dialog` - 抽屉面板本身
+- `.drawer__header` - 标题区域
 - `.drawer__heading` - 主标题文本
- `.drawer__body` - 可滚动主体内容区域
- `.drawer__footer` - 表底操作区域
- `.drawer__handle` - 视觉拖拽把手
+- `.drawer__body` - 主可滚动内容区域
+- `.drawer__footer` - 操作按钮区域
+- `.drawer__handle` - 视觉拖拽手柄指示器
 - `.drawer__close-trigger` - 关闭按钮元素

-#### 遮罩变体
+#### 遮罩变体 [!toc]

- `.drawer__backdrop--opaque` - 不透明有色遮罩（默认）
- `.drawer__backdrop--blur` - 带玻璃效果的模糊遮罩
- `.drawer__backdrop--transparent` - 透明遮罩（无叠加层）
+- `.drawer__backdrop--opaque` - 不透明彩色遮罩（默认）
+- `.drawer__backdrop--blur` - 模糊遮罩，玻璃效果
+- `.drawer__backdrop--transparent` - 透明遮罩（无覆盖层）

-#### 位置变体
+#### 位置变体 [!toc]

- `.drawer__content--bottom` - 自底边上滑（默认）
- `.drawer__content--top` - 自顶边下滑
- `.drawer__content--left` - 自左侧滑入
- `.drawer__content--right` - 自右侧滑入
+- `.drawer__content--bottom` - 从底部边缘滑入（默认）
+- `.drawer__content--top` - 从顶部边缘滑入
+- `.drawer__content--left` - 从左侧边缘滑入
+- `.drawer__content--right` - 从右侧边缘滑入

-#### 对话框变体
+#### 对话框变体 [!toc]

- `.drawer__dialog--top` - 自顶边下滑
- `.drawer__dialog--bottom` - 自底边上滑
- `.drawer__dialog--left` - 自左侧滑入
- `.drawer__dialog--right` - 自右侧滑入
+- `.drawer__dialog--top` - 从顶部边缘滑入
+- `.drawer__dialog--bottom` - 从底部边缘滑入
+- `.drawer__dialog--left` - 从左侧边缘滑入
+- `.drawer__dialog--right` - 从右侧边缘滑入

 ### 交互状态

-该组件支持以下交互状态：
+组件支持以下交互状态：

- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]` — 应用于触发器与关闭按钮
- **悬停**：`:hover` 或 `[data-hovered="true"]` — 关闭按钮悬停时应用
- **激活**：`:active` 或 `[data-pressed="true"]` — 触发器与关闭按钮被按压时应用
- **进入**：`[data-entering]` — Drawer 打开动画期间应用
- **离开**：`[data-exiting]` — Drawer 关闭动画期间应用
- **位置**：`[data-placement="*"]` — 根据 Drawer 位置应用（top、bottom、left、right）
+- **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]` - 应用于触发器与关闭按钮
+- **Hover**：`:hover` 或 `[data-hovered="true"]` - 悬停时应用于关闭按钮
+- **Active**：`:active` 或 `[data-pressed="true"]` - 按下时应用于触发器与关闭按钮
+- **Entering**：`[data-entering]` - 抽屉打开动画期间
+- **Exiting**：`[data-exiting]` - 抽屉关闭动画期间
+- **Placement**：`[data-placement="*"]` - 根据抽屉位置（top、bottom、left、right）应用

 ## API 参考

 ### Drawer

-| Prop       | Type                   | 默认值 | 描述                    |
-| ---------- | ---------------------- | ------ | ----------------------- |
-| `children` | `ReactNode`            | -      | 触发器与遮罩子元素。    |
-| `state`    | `UseOverlayStateReturn` | -    | 受控的叠加层状态。      |
+| Prop       | 类型                   | 默认值 | 描述                    |
+| ---------- | ---------------------- | ------- | ------------------------------ |
+| `children` | `ReactNode`            | -       | 触发器与 backdrop 元素  |
+| `state`    | `UseOverlayStateReturn` | -      | 受控 overlay 状态       |

 ### Drawer.Trigger

-| Prop        | Type        | 默认值 | 描述            |
-| ----------- | ----------- | ------ | --------------- |
-| `children`  | `ReactNode` | -      | 自定义触发内容。 |
-| `className` | `string`    | -      | CSS 类。        |
+| Prop        | 类型        | 默认值 | 描述            |
+| ----------- | ----------- | ------- | ---------------------- |
+| `children`  | `ReactNode` | -       | 自定义触发器内容 |
+| `className` | `string`    | -       | CSS 类            |

 ### Drawer.Backdrop

-| Prop                        | Type                                  | 默认值    | 描述               |
-| --------------------------- | ------------------------------------- | --------- | ------------------ |
-| `variant`                   | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 遮罩叠加样式。     |
-| `isDismissable`             | `boolean`                             | `true`     | 点击遮罩是否关闭。 |
-| `isKeyboardDismissDisabled` | `boolean`                             | `false`    | 是否禁用 ESC 关闭。 |
-| `isOpen`                    | `boolean`                             | -          | 受控打开状态。     |
-| `onOpenChange`              | `(isOpen: boolean) => void`           | -          | 打开状态变化时的事件处理函数。 |
-| `className`                 | `string \| (values) => string`        | -          | 遮罩 CSS 类。      |
+| Prop                        | 类型                                  | 默认值    | 描述               |
+| --------------------------- | ------------------------------------- | ---------- | ------------------------- |
+| `variant`                   | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 遮罩覆盖层样式    |
+| `isDismissable`             | `boolean`                             | `true`     | 点击 backdrop 关闭   |
+| `isKeyboardDismissDisabled` | `boolean`                             | `false`    | 禁用 ESC 关闭  |
+| `isOpen`                    | `boolean`                             | -          | 受控打开状态     |
+| `onOpenChange`              | `(isOpen: boolean) => void`           | -          | 打开状态变化处理函数 |
+| `className`                 | `string \| (values) => string`        | -          | Backdrop CSS 类      |

 ### Drawer.Content

-| Prop        | Type                                          | 默认值    | 描述               |
-| ----------- | --------------------------------------------- | --------- | ------------------ |
-| `placement` | `"top" \| "bottom" \| "left" \| "right"`      | `"bottom"` | Drawer 从哪一侧滑入。 |
-| `className` | `string \| (values) => string`                | -          | Content CSS 类。   |
+| Prop        | 类型                                          | 默认值    | 描述               |
+| ----------- | --------------------------------------------- | ---------- | ------------------------- |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"`      | `"bottom"` | 抽屉滑入的边缘 |
+| `className` | `string \| (values) => string`                | -          | Content CSS 类       |

 ### Drawer.Dialog

-| Prop               | Type                           | 默认值    | 描述            |
-| ------------------ | ------------------------------ | --------- | --------------- |
-| `children`         | `ReactNode`                    | -         | 对话框内容。    |
-| `className`        | `string`                       | -         | CSS 类。        |
-| `role`             | `string`                       | `"dialog"` | ARIA role。     |
-| `aria-label`       | `string`                       | -         | 无障碍标签。    |
-| `aria-labelledby`  | `string`                       | -         | 标签元素 ID。   |
+| Prop               | 类型                           | 默认值    | 描述                |
+| ------------------ | ------------------------------ | ---------- | -------------------------- |
+| `children`         | `ReactNode`                    | -          | Dialog 内容             |
+| `className`        | `string`                       | -          | CSS 类                |
+| `role`             | `string`                       | `"dialog"` | ARIA role                  |
+| `aria-label`       | `string`                       | -          | 无障碍标签        |
+| `aria-labelledby`  | `string`                       | -          | 标签元素 ID        |

 ### Drawer.Header

-| Prop        | Type        | 默认值 | 描述        |
-| ----------- | ----------- | ------ | ----------- |
-| `children`  | `ReactNode` | -      | 表头内容。  |
-| `className` | `string`    | -      | CSS 类。    |
+| Prop        | 类型        | 默认值 | 描述    |
+| ----------- | ----------- | ------- | -------------- |
+| `children`  | `ReactNode` | -       | Header 内容 |
+| `className` | `string`    | -       | CSS 类    |

 ### Drawer.Heading

-| Prop        | Type        | 默认值 | 描述      |
-| ----------- | ----------- | ------ | --------- |
-| `children`  | `ReactNode` | -      | 标题文本。 |
-| `className` | `string`    | -      | CSS 类。   |
+| Prop        | 类型        | 默认值 | 描述  |
+| ----------- | ----------- | ------- | ------------ |
+| `children`  | `ReactNode` | -       | 标题文本   |
+| `className` | `string`    | -       | CSS 类  |

 ### Drawer.Body

-| Prop        | Type        | 默认值 | 描述      |
-| ----------- | ----------- | ------ | --------- |
-| `children`  | `ReactNode` | -      | 主体内容。 |
-| `className` | `string`    | -      | CSS 类。   |
+| Prop        | 类型        | 默认值 | 描述  |
+| ----------- | ----------- | ------- | ------------ |
+| `children`  | `ReactNode` | -       | Body 内容 |
+| `className` | `string`    | -       | CSS 类  |

 ### Drawer.Footer

-| Prop        | Type        | 默认值 | 描述        |
-| ----------- | ----------- | ------ | ----------- |
-| `children`  | `ReactNode` | -      | 表底内容。  |
-| `className` | `string`    | -      | CSS 类。    |
+| Prop        | 类型        | 默认值 | 描述    |
+| ----------- | ----------- | ------- | -------------- |
+| `children`  | `ReactNode` | -       | Footer 内容 |
+| `className` | `string`    | -       | CSS 类    |

 ### Drawer.Handle

-| Prop        | Type     | 默认值 | 描述   |
-| ----------- | -------- | ------ | ------ |
-| `className` | `string` | -      | CSS 类。 |
+| Prop        | 类型     | 默认值 | 描述          |
+| ----------- | -------- | ------- | -------------------- |
+| `className` | `string` | -       | CSS 类          |

 ### Drawer.CloseTrigger

-| Prop        | Type                           | 默认值 | 描述            |
-| ----------- | ------------------------------ | ------ | --------------- |
-| `children`  | `ReactNode`                    | -      | 自定义关闭按钮。 |
-| `className` | `string \| (values) => string` | -      | CSS 类。        |
+| Prop        | 类型                           | 默认值 | 描述         |
+| ----------- | ------------------------------ | ------- | ------------------- |
+| `children`  | `ReactNode`                    | -       | 自定义关闭按钮 |
+| `className` | `string \| (values) => string` | -       | CSS 类         |

 ### useOverlayState Hook

@@ -292,8 +265,12 @@ state.setOpen(); // Set state directly

 实现 [WAI-ARIA Dialog 模式](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)：

- **焦点陷阱**：打开时将焦点锁定在 Drawer 内
- **键盘**：可关闭时 `ESC` 关闭，`Tab` 在可聚焦元素间循环
- **屏幕阅读器**：通过 React Aria 提供合适的 ARIA 属性
+- **焦点陷阱**：打开时焦点锁定在抽屉内
+- **键盘**：`ESC` 关闭（可关闭时），`Tab` 循环元素
+- **屏幕阅读器**：通过 React Aria 提供正确的 ARIA 属性
 - **滚动锁定**：打开时禁用 body 滚动
- **拖拽关闭**：支持在把手、表头与表底等区域的指针拖拽手势
+- **拖拽关闭**：在 handle、header 和 footer 区域支持指针拖拽手势
+
+## 相关组件
+
+<RelatedComponents component="drawer" />
@@ -8,17 +8,15 @@ links:
  storybook: modal
 ---

-## 引入
+## 用法

 ```tsx
 import { Modal } from "@heroui/react";
 ```

-### 用法
-
 <ComponentPreview name="modal-default" />

-### 组件结构
+## 组件结构

 导入 Modal 组件后，可通过点语法访问所有子部分。

@@ -45,18 +43,36 @@ export default () => (
 );
 ```

-### 位置
-
-<ComponentPreview name="modal-placements" />
-
-### 遮罩变体
-
-<ComponentPreview name="modal-backdrop-variants" />
+## 示例

 ### 尺寸

 <ComponentPreview name="modal-sizes" />

+### 位置
+
+<ComponentPreview name="modal-placements" />
+
+### 滚动行为
+
+<ComponentPreview name="modal-scroll-comparison" />
+
+### 受控状态
+
+<ComponentPreview name="modal-controlled" />
+
+### 搭配表单
+
+<ComponentPreview name="modal-with-form" />
+
+### 自定义触发器
+
+<ComponentPreview name="modal-custom-trigger" />
+
+### 遮罩变体
+
+<ComponentPreview name="modal-backdrop-variants" />
+
 ### 自定义遮罩

 <ComponentPreview name="modal-custom-backdrop" />
@@ -69,22 +85,6 @@ export default () => (

 <ComponentPreview name="modal-close-methods" />

-### 滚动行为
-
-<ComponentPreview name="modal-scroll-comparison" />
-
-### 受控状态
-
-<ComponentPreview name="modal-controlled" />
-
-### 带表单
-
-<ComponentPreview name="modal-with-form" />
-
-### 自定义触发器
-
-<ComponentPreview name="modal-custom-trigger" />
-
 ### 自定义动画

 <ComponentPreview name="modal-custom-animations" />
@@ -93,44 +93,15 @@ export default () => (

 <ComponentPreview name="modal-custom-portal" />

-## 样式
+## 自定义样式

-### 传入 Tailwind CSS 类
+### Tailwind CSS

-```tsx
-import {Modal, Button} from "@heroui/react";
+<ComponentPreview name="modal-custom-styles" />

-function CustomModal() {
-  return (
-    <Modal>
-      <Button>Open Modal</Button>
-      <Modal.Backdrop className="bg-black/80">
-        <Modal.Container className="items-start pt-20">
-          <Modal.Dialog className="bg-linear-to-br from-purple-500 to-pink-500 text-white">
-            <Modal.CloseTrigger />
-            <Modal.Header>
-              <Modal.Heading>Custom Styled Modal</Modal.Heading>
-            </Modal.Header>
-            <Modal.Body>
-              <p>This modal has custom styling applied via Tailwind classes</p>
-            </Modal.Body>
-            <Modal.Footer>
-              <Button slot="close">Close</Button>
-            </Modal.Footer>
-          </Modal.Dialog>
-        </Modal.Container>
-      </Modal.Backdrop>
-    </Modal>
-  );
-}
-```
+### 全局 CSS

-### 自定义组件类
-
-要自定义 Modal 的组件类，可使用 `@layer components` 指令。
-
-<br />
-[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -152,13 +123,15 @@ function CustomModal() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Modal 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/modal.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.modal__trigger` — 打开 Modal 的触发元素
 - `.modal__backdrop` — Modal 背后的遮罩层
 - `.modal__container` — 支持 placement 的定位包裹层
@@ -168,12 +141,12 @@ Modal 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/
 - `.modal__footer` — 操作区域
 - `.modal__close-trigger` — 关闭按钮元素

-#### 遮罩变体
+#### 遮罩变体 [!toc]
 - `.modal__backdrop--opaque` — 不透明有色遮罩（默认）
 - `.modal__backdrop--blur` — 带玻璃效果的模糊遮罩
 - `.modal__backdrop--transparent` — 透明遮罩（无叠加层）

-#### 滚动变体
+#### 滚动变体 [!toc]
 - `.modal__container--scroll-outside` — 允许整个 Modal 滚动
 - `.modal__dialog--scroll-inside` — 限制 Modal 高度，由 body 区域滚动
 - `.modal__body--scroll-inside` — 仅 body 区域可滚动
@@ -290,3 +263,7 @@ state.setOpen(); // 直接设置状态
 - **键盘**：`ESC` 关闭（启用时）、`Tab` 在元素间循环
 - **屏幕阅读器**：正确的 ARIA 属性
 - **滚动锁定**：打开时禁用 body 滚动
+
+## 相关组件
+
+<RelatedComponents component="modal" />
@@ -8,21 +8,17 @@ links:
  storybook: Components/Overlays/Popover
 ---

-## 引入
+## 用法

 ```tsx
 import { Popover } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="popover-basic"
 />

-### 组件结构
-
-引入 Popover 后，可通过点语法访问各个部分。
+## 组件结构

 ```tsx
 import { Popover } from '@heroui/react';
@@ -41,60 +37,41 @@ export default () => (
 )
 ```

+## 示例
+
 ### 带箭头

 <ComponentPreview
  name="popover-with-arrow"
 />

-### 位置
-
-<ComponentPreview
-  name="popover-placement"
-/>
-
 ### 可交互内容

 <ComponentPreview
  name="popover-interactive"
 />

-<RelatedComponents component="popover" />
-
-### 自定义渲染函数
+### 位置

 <ComponentPreview
-  name="popover-custom-render-function"
+  name="popover-placement"
 />

-## 样式
+### 渲染函数

-### 传入 Tailwind CSS 类
+<ComponentPreview
+  name="popover-render-function"
+/>

-```tsx
-import { Popover, Button } from '@heroui/react';
+## 自定义样式

-function CustomPopover() {
-  return (
-    <Popover>
-      <Popover.Trigger>
-        <Button>Open</Button>
-      </Popover.Trigger>
-      <Popover.Content className="bg-accent text-accent-foreground">
-        <Popover.Dialog>
-          <h3>Custom Styled</h3>
-          <p>This popover has custom styling</p>
-        </Popover.Dialog>
-      </Popover.Content>
-    </Popover>
-  );
-}
-```
+### Tailwind CSS

-### 自定义组件类
+<ComponentPreview name="popover-custom-styles" />

-若要自定义 Popover 的组件类名，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+### 全局 CSS
+
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -112,13 +89,15 @@ function CustomPopover() {
 }
 ```

-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Popover 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/popover.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.popover` - Popover 根容器样式
 - `.popover__dialog` - 对话框内容包裹层
 - `.popover__heading` - 标题文本样式
@@ -135,8 +114,7 @@ Popover 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-in

 ## API 参考

-### Popover Props
-
+### Popover
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 触发器与内容元素 |
@@ -144,8 +122,7 @@ Popover 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-in
 | `defaultOpen` | `boolean` | `false` | 初始打开状态（非受控） |
 | `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化时调用 |

-### Popover.Content Props
-
+### Popover.Content
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 在 Popover 中展示的内容 |
@@ -155,24 +132,25 @@ Popover 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-in
 | `className` | `string` | - | 额外的 CSS 类名 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, PopoverRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |

-### Popover.Dialog Props
-
+### Popover.Dialog
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 对话框内容 |
 | `className` | `string` | - | 额外的 CSS 类名 |

-### Popover.Trigger Props
-
+### Popover.Trigger
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 触发 Popover 的元素 |
 | `className` | `string` | - | 额外的 CSS 类名 |

-### Popover.Arrow Props
-
+### Popover.Arrow
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 自定义箭头元素 |
 | `className` | `string` | - | 额外的 CSS 类名 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+## 相关组件
+
+<RelatedComponents component="popover" />
@@ -9,15 +9,86 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Toast, toast } from '@heroui/react';
 ```

-## 设置
+<ComponentPreview
+  name="toast-default"
+/>

-在应用根部渲染 Provider。
+## 组件结构
+
+```tsx
+<Toast.Provider>
+  <Toast>
+    <Toast.Indicator />
+    <Toast.Content>
+      <Toast.Title />
+      <Toast.Description />
+    </Toast.Content>
+    <Toast.ActionButton />
+    <Toast.CloseButton />
+  </Toast>
+</Toast.Provider>
+```
+
+
+## 示例
+
+### 变体
+
+<ComponentPreview
+  name="toast-variants"
+/>
+
+### 放置位置
+
+<ComponentPreview
+  name="toast-placements"
+/>
+
+### 简单 Toast
+
+<ComponentPreview
+  name="toast-simple"
+/>
+
+### 自定义指示器
+
+<ComponentPreview
+  name="toast-custom-indicator"
+/>
+
+### 自定义 Toast 渲染
+
+<ComponentPreview
+  name="toast-custom-toast"
+/>
+
+### Promise 与加载中
+
+<ComponentPreview
+  name="toast-promise"
+/>
+
+### 回调
+
+<ComponentPreview
+  name="toast-callbacks"
+/>
+
+### 自定义队列
+
+<ComponentPreview
+  name="toast-custom-queue"
+/>
+
+### 配置
+
+在应用根节点渲染 Provider。

 ```tsx
 import { Toast, Button, toast } from '@heroui/react';
@@ -34,90 +105,15 @@ function App() {
 }
 ```

-### 用法
+## 自定义样式

-<ComponentPreview
-  name="toast-default"
-/>
+### Tailwind CSS

-### 简单 Toast
+<ComponentPreview name="toast-custom-styles" />

-<ComponentPreview
-  name="toast-simple"
-/>
+### 全局 CSS

-### 变体
-
-<ComponentPreview
-  name="toast-variants"
-/>
-
-### 自定义指示器
-
-<ComponentPreview
-  name="toast-custom-indicator"
-/>
-
-### Promise 与加载中
-
-<ComponentPreview
-  name="toast-promise"
-/>
-
-### 回调
-
-<ComponentPreview
-  name="toast-callbacks"
-/>
-
-### 放置位置
-
-<ComponentPreview
-  name="toast-placements"
-/>
-
-### 自定义 Toast 渲染
-
-<ComponentPreview
-  name="toast-custom-toast"
-/>
-
-### 自定义队列
-
-<ComponentPreview
-  name="toast-custom-queue"
-/>
-
-### 组件结构
-
-```tsx
-<Toast.Provider>
-  <Toast>
-    <Toast.Indicator />
-    <Toast.Content>
-      <Toast.Title />
-      <Toast.Description />
-    </Toast.Content>
-    <Toast.ActionButton />
-    <Toast.CloseButton />
-  </Toast>
-</Toast.Provider>
-```
-
-<RelatedComponents component="toast" />
-
-## 样式
-
-### 传入 Tailwind CSS 类
-
-```tsx
-<Toast.Provider className="bottom-8 right-8" placement="bottom end" />
-```
-
-### 自定义组件类
-
-要自定义 Toast 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -131,13 +127,15 @@ function App() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Toast 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toast.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.toast` — Toast 根容器
 - `.toast__region` — Toast 区域容器
 - `.toast__content` — 包裹标题与说明的内容容器
@@ -147,7 +145,7 @@ Toast 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/
 - `.toast__action` — 操作按钮容器
 - `.toast__close` — 关闭按钮容器

-#### 变体类
+#### 变体类 [!toc]
 - `.toast--default` — 默认灰色变体
 - `.toast--accent` — 强调蓝色变体
 - `.toast--success` — 成功绿色变体
@@ -164,8 +162,7 @@ Toast 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/

 ## API 参考

-### Toast.Provider Props
-
+### Toast.Provider
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `placement` | `"top start" \| "top" \| "top end" \| "bottom start" \| "bottom" \| "bottom end"` | `"bottom"` | Toast 区域的放置位置 |
@@ -177,8 +174,7 @@ Toast 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/
 | `children` | `ReactNode \| ((props: {toast: QueuedToast<T>}) => ReactNode)` | - | 自定义渲染函数或子节点 |
 | `className` | `string` | - | 附加的 CSS 类 |

-### Toast Props
-
+### Toast
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `toast` | `QueuedToast<T>` | - | 来自队列的 Toast 数据（必填） |
@@ -188,45 +184,39 @@ Toast 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/
 | `className` | `string` | - | 附加的 CSS 类 |
 | `children` | `ReactNode` | - | Toast 内容（ToastContent、ToastIndicator 等） |

-### Toast.Content Props
-
+### Toast.Content
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `ReactNode` | - | 内容（通常为 ToastTitle 与 ToastDescription） |
 | `className` | `string` | - | 附加的 CSS 类 |

-### Toast.Indicator Props
-
+### Toast.Indicator
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `variant` | `ToastVariants["variant"]` | - | 默认图标的变体 |
 | `children` | `ReactNode` | - | 自定义指示图标（默认使用变体图标） |
 | `className` | `string` | - | 附加的 CSS 类 |

-### Toast.Title Props
-
+### Toast.Title
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `ReactNode` | - | 标题文本 |
 | `className` | `string` | - | 附加的 CSS 类 |

-### Toast.Description Props
-
+### Toast.Description
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `ReactNode` | - | 说明文本 |
 | `className` | `string` | - | 附加的 CSS 类 |

-### Toast.ActionButton Props
-
+### Toast.ActionButton
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `ReactNode` | - | 操作按钮内容 |
 | `className` | `string` | - | 附加的 CSS 类 |
 | All `Button` props | - | - | 接受 Button 组件的全部 props |

-### Toast.CloseButton Props
-
+### Toast.CloseButton
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `className` | `string` | - | 附加的 CSS 类 |
@@ -330,3 +320,7 @@ toast.resumeAll();
 | `loading` | `ReactNode` | - | Promise pending 时显示的消息 |
 | `success` | `ReactNode \| ((data: T) => ReactNode)` | - | 成功时显示的消息（可为函数） |
 | `error` | `ReactNode \| ((error: Error) => ReactNode)` | - | 失败时显示的消息（可为函数） |
+
+## 相关组件
+
+<RelatedComponents component="toast" />
@@ -10,21 +10,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Tooltip } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="tooltip-basic"
 />

-### 组件结构
-
-引入 Tooltip 后，可通过点语法访问各个部分。
+## 组件结构

 ```tsx
 import { Tooltip, Button } from '@heroui/react';
@@ -36,17 +32,13 @@ export default () => (
    </Tooltip.Trigger>
    <Tooltip.Content>
      <Tooltip.Arrow />
-      Helpful information about this element
+      关于此元素的有用信息
    </Tooltip.Content>
  </Tooltip>
 )
 ```

-### 带箭头
-
-<ComponentPreview
-  name="tooltip-with-arrow"
-/>
+## 示例

 ### 位置

@@ -54,21 +46,49 @@ export default () => (
  name="tooltip-placement"
 />

+### 带箭头
+
+<ComponentPreview
+  name="tooltip-with-arrow"
+/>
+
 ### 自定义触发

 <ComponentPreview
  name="tooltip-custom-trigger"
 />

-<RelatedComponents component="tooltip" />
-
-### 自定义渲染函数
+### 渲染函数

 <ComponentPreview
-  name="tooltip-custom-render-function"
+  name="tooltip-render-function"
 />

-## 样式
+## 自定义样式
+
+### Tailwind CSS
+
+<ComponentPreview name="tooltip-custom-styles" />
+
+### 全局 CSS
+
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .tooltip {
+    @apply rounded-xl shadow-lg;
+  }
+
+  .tooltip__trigger {
+    @apply cursor-help;
+  }
+}
+```
+
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### 全局延迟配置

@@ -93,49 +113,13 @@ export default () => (

 值支持 `ms`、`s` 等 CSS 时间单位。在单个 Tooltip 上指定 `delay` 或 `closeDelay` 时，会覆盖这些全局设置。

-### 传入 Tailwind CSS 类

-```tsx
-import { Tooltip, Button } from '@heroui/react';
-
-function CustomTooltip() {
-  return (
-    <Tooltip>
-      <Tooltip.Trigger>
-        <Button>Hover me</Button>
-      </Tooltip.Trigger>
-      <Tooltip.Content className="bg-accent text-accent-foreground">
-        <p>Custom styled tooltip</p>
-      </Tooltip.Content>
-    </Tooltip>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 Tooltip 的组件类名，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
-
-```css
-@layer components {
-  .tooltip {
-    @apply rounded-xl shadow-lg;
-  }
-
-  .tooltip__trigger {
-    @apply cursor-help;
-  }
-}
-```
-
-HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。

 ### CSS 类

 Tooltip 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tooltip.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.tooltip` - 带动画的基础 Tooltip 样式
 - `.tooltip__trigger` - 触发元素样式

@@ -149,8 +133,7 @@ Tooltip 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-in

 ## API 参考

-### Tooltip Props
-
+### Tooltip
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 触发元素与内容 |
@@ -159,8 +142,7 @@ Tooltip 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-in
 | `trigger` | `"hover" \| "focus"` | `"hover"` | Tooltip 的触发方式 |
 | `isDisabled` | `boolean` | `false` | 是否禁用 Tooltip |

-### Tooltip.Content Props
-
+### Tooltip.Content
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 在 Tooltip 中展示的内容 |
@@ -170,17 +152,19 @@ Tooltip 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-in
 | `className` | `string` | - | 额外的 CSS 类名 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TooltipRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |

-### Tooltip.Trigger Props
-
+### Tooltip.Trigger
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 触发 Tooltip 的元素 |
 | `className` | `string` | - | 额外的 CSS 类名 |

-### Tooltip.Arrow Props
-
+### Tooltip.Arrow
 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `children` | `React.ReactNode` | - | 自定义箭头元素 |
 | `className` | `string` | - | 额外的 CSS 类名 |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+## 相关组件
+
+<RelatedComponents component="tooltip" />
@@ -1,6 +1,6 @@
 ---
 title: Autocomplete 自动完成
-description: 自动完成将选择与过滤结合，让用户可以搜索并从选项列表中选择。
+description: 结合选择与过滤，让用户从选项列表中搜索并选择
 links:
  rac: Select
  source: autocomplete/autocomplete.tsx
@@ -8,19 +8,15 @@ links:
  storybook: Components/Pickers/Autocomplete
 ---

-## 引入
+## 用法

 ```tsx
 import { Autocomplete, useFilter } from "@heroui/react";
 ```

-### 用法
-
 <ComponentPreview name="autocomplete-default" />

-### 组件结构
-
-导入 Autocomplete 组件后，可通过点语法访问各个子部分。
+## 组件结构

 ```tsx
 import {Autocomplete, Label, Description, SearchField, ListBox} from "@heroui/react";
@@ -54,153 +50,122 @@ export default () => (
 );
 ```

+## 示例
+
+### 变体
+
+Autocomplete 组件支持两种视觉变体：
+
+- **`primary`**（默认）- 标准样式带阴影，适用于大多数场景
+- **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内
+
+<ComponentPreview name="autocomplete-variants" />
+
+### 宽度充满
+
+<ComponentPreview name="autocomplete-full-width" />
+
 ### 带描述

 <ComponentPreview name="autocomplete-with-description" />

-### 多选
-
-<ComponentPreview name="autocomplete-multiple-select" />
-
-### 分组
-
-<ComponentPreview name="autocomplete-with-sections" />
-
-### 含禁用选项
-
-<ComponentPreview name="autocomplete-with-disabled-options" />
-
-### 允许空集合
-
-`allowsEmptyCollection` prop 让自动完成在集合中没有任何条目时仍可使用。适用于列表初始可能为空，或过滤后没有结果等场景。
-
-<ComponentPreview name="autocomplete-allows-empty-collection" />
-
-### 自定义指示器
-
-<ComponentPreview name="autocomplete-custom-indicator" />
-
 ### 必填

 <ComponentPreview name="autocomplete-required" />

-### 全宽
+### 禁用

-<ComponentPreview name="autocomplete-full-width" />
+<ComponentPreview name="autocomplete-disabled" />

-### 变体
+### 含禁用选项

-Autocomplete 支持两种视觉变体：
+<ComponentPreview name="autocomplete-with-disabled-options" />

- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
- **`secondary`** — 低强调、无阴影，适合用于 Surface 组件
+### 允许空选项

-<ComponentPreview name="autocomplete-variants" />
+`allowsEmptyCollection` 属性允许集合为空时仍可使用自动完成，适用于列表初始为空或全部被过滤掉的场景。

-### 在 Surface 中
+<ComponentPreview name="autocomplete-allows-empty-collection" />

-在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+### 分组选项

-<ComponentPreview name="autocomplete-full-width" />
+<ComponentPreview name="autocomplete-with-sections" />

-### 自定义值
+### 多选

-你可以使用渲染 prop 自定义展示的值：
+<ComponentPreview name="autocomplete-multiple-select" />

-<ComponentPreview name="autocomplete-user-selection" />
-
-### 受控
+### 受控组件

 <ComponentPreview name="autocomplete-controlled" />

 ### 受控多选

-<ComponentPreview name="autocomplete-multiple-select" />
+<ComponentPreview name="autocomplete-controlled-multiple" />

 ### 受控展开状态

 <ComponentPreview name="autocomplete-controlled-open-state" />

-### 异步过滤
+### 异步搜索

 <ComponentPreview name="autocomplete-asynchronous-filtering" />

-### 虚拟化
+### 自定义指示器

-Autocomplete 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见的行，从而高效展示大数据集。
+<ComponentPreview name="autocomplete-custom-indicator" />
+
+### 自定义展示值
+
+可使用 render props 自定义显示值：
+
+<ComponentPreview name="autocomplete-custom-value" />
+
+### 表面样式
+
+在 [Surface](/docs/components/surface) 组件内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。
+
+<ComponentPreview name="autocomplete-on-surface" />
+
+### 虚拟滚动
+
+Autocomplete 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见行以高效处理大数据集。

 <ComponentPreview name="autocomplete-virtualization" />

-### 禁用
+## 高级示例

-<ComponentPreview name="autocomplete-disabled" />
-
-### 进阶示例
-
-#### 用户选择
+### 用户选择

 <ComponentPreview name="autocomplete-user-selection" />

-#### 用户多选
+### 用户多选

 <ComponentPreview name="autocomplete-user-selection-multiple" />

-#### 地点搜索
+### 地点搜索

 <ComponentPreview name="autocomplete-location-search" />

-#### Tag Group 选择
+### 标签组选择

 <ComponentPreview name="autocomplete-tag-group-selection" />

-#### 邮件收件人
+### 邮件收件人

 <ComponentPreview name="autocomplete-email-recipients" />

-<RelatedComponents component="autocomplete" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="autocomplete-custom-styles" />

-```tsx
-import {Autocomplete, SearchField, ListBox} from "@heroui/react";
+### 全局 CSS

-function CustomAutocomplete() {
-  return (
-    <Autocomplete className="w-full">
-      <Label>State</Label>
-      <Autocomplete.Trigger className="rounded-lg border bg-surface p-2">
-        <Autocomplete.Value />
-        <Autocomplete.ClearButton />
-        <Autocomplete.Indicator />
-      </Autocomplete.Trigger>
-      <Autocomplete.Popover>
-        <Autocomplete.Filter>
-          <SearchField>
-            <SearchField.Group>
-              <SearchField.SearchIcon />
-              <SearchField.Input placeholder="Search..." />
-            </SearchField.Group>
-          </SearchField>
-          <ListBox>
-            <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
-              Item 1
-            </ListBox.Item>
-          </ListBox>
-        </Autocomplete.Filter>
-      </Autocomplete.Popover>
-    </Autocomplete>
-  );
-}
-```
+可使用 `@layer components` 指令自定义 Autocomplete 组件类。

-### 自定义组件类
-
-要自定义 Autocomplete 的组件类，可使用 `@layer components` 指令。
-
-<br />
-[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -227,20 +192,18 @@ function CustomAutocomplete() {
  .autocomplete__popover {
    @apply rounded-lg border border-border bg-surface p-2;
  }
-
-  .autocomplete__popover-dialog {
-    @apply outline-none;
-  }
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-Autocomplete 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/autocomplete.css)）：
+Autocomplete 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/autocomplete.css)）：

-#### 基础类
+#### 基础类 [!toc]

 - `.autocomplete` - 自动完成根容器
 - `.autocomplete__trigger` - 触发自动完成的按钮
@@ -248,106 +211,105 @@ Autocomplete 使用以下 CSS 类（[查看源码样式](https://github.com/hero
 - `.autocomplete__clear-button` - 清除已选值的按钮
 - `.autocomplete__indicator` - 下拉指示图标
 - `.autocomplete__popover` - 弹出层容器
- `.autocomplete__popover-dialog` - 弹出层内部的 dialog 包裹层，用于焦点管理（与 [Popover](/docs/components/popover) 行为一致）
- `.autocomplete__filter` - 过滤区域包裹层
+- `.autocomplete__filter` - 过滤包装器

-#### 变体类
+#### 变体类 [!toc]

- `.autocomplete--primary` - 主变体，带阴影（默认）
- `.autocomplete--secondary` - 次变体，无阴影，适合用于 Surface
+- `.autocomplete--primary` - 带阴影的主变体（默认）
+- `.autocomplete--secondary` - 无阴影的次变体，适用于 Surface 内

-#### 状态类
+#### 状态类 [!toc]

 - `.autocomplete[data-invalid="true"]` - 无效状态
 - `.autocomplete__trigger[data-focus-visible="true"]` - 触发器聚焦状态
 - `.autocomplete__trigger[data-disabled="true"]` - 触发器禁用状态
 - `.autocomplete__value[data-placeholder="true"]` - 占位符状态
- `.autocomplete__clear-button[data-empty="true"]` - 无选中时隐藏清除按钮
- `.autocomplete__indicator[data-open="true"]` - 展开时的指示器状态
+- `.autocomplete__clear-button[data-empty="true"]` - 无选择时隐藏清除按钮
+- `.autocomplete__indicator[data-open="true"]` - 打开时的指示器状态

 ### 交互状态

-组件同时支持 CSS 伪类与 data 属性，便于灵活编写样式：
+组件同时支持 CSS 伪类与 data 属性：

- **悬停**：触发器上 `:hover` 或 `[data-hovered="true"]`
- **聚焦**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
- **禁用**：自动完成上 `:disabled` 或 `[data-disabled="true"]`
- **展开**：指示器上 `[data-open="true"]`
+- **Hover**：触发器上的 `:hover` 或 `[data-hovered="true"]`
+- **Focus**：触发器上的 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **Disabled**：Autocomplete 上的 `:disabled` 或 `[data-disabled="true"]`
+- **Open**：指示器上的 `[data-open="true"]`

 ## API 参考

-### Autocomplete Props
+### Autocomplete

 | Prop | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| `placeholder` | `string` | `'Select an item'` | 自动完成为空时显示的占位文本 |
+|------|------|--------|------|
+| `placeholder` | `string` | `'Select an item'` | 为空时显示的占位文本 |
 | `selectionMode` | `"single" \| "multiple"` | `"single"` | 启用单选或多选 |
-| `allowsEmptyCollection` | `boolean` | `false` | 是否允许空集合。为 `true` 时，即使没有任何条目也可使用自动完成。 |
-| `isOpen` | `boolean` | - | 设置弹出层的打开状态（受控） |
-| `defaultOpen` | `boolean` | - | 设置弹出层的默认打开状态（非受控） |
-| `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化时触发的事件处理函数 |
-| `disabledKeys` | `Iterable<Key>` | - | 禁用条目的 key |
-| `isDisabled` | `boolean` | - | 是否禁用自动完成 |
+| `allowsEmptyCollection` | `boolean` | `false` | 是否允许空集合；为 true 时无选项也可使用 |
+| `isOpen` | `boolean` | - | 弹出层打开状态（受控） |
+| `defaultOpen` | `boolean` | - | 弹出层默认打开状态（非受控） |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化时的回调 |
+| `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key |
+| `isDisabled` | `boolean` | - | 是否禁用 |
 | `value` | `Key \| Key[] \| null` | - | 当前值（受控） |
 | `defaultValue` | `Key \| Key[] \| null` | - | 默认值（非受控） |
-| `onChange` | `(value: Key \| Key[] \| null) => void` | - | 值变化时触发的事件处理函数 |
-| `isRequired` | `boolean` | - | 是否要求用户输入 |
-| `isInvalid` | `boolean` | - | 自动完成的值是否无效 |
-| `name` | `string` | - | 输入的 name，用于提交 HTML 表单 |
-| `fullWidth` | `boolean` | `false` | 自动完成是否占满容器宽度 |
-| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `children` | `ReactNode \| RenderFunction` | - | 自动完成内容或渲染函数 |
+| `onChange` | `(value: Key \| Key[] \| null) => void` | - | 值变化时的回调 |
+| `isRequired` | `boolean` | - | 是否必填 |
+| `isInvalid` | `boolean` | - | 值是否无效 |
+| `name` | `string` | - | 提交 HTML 表单时使用的名称 |
+| `fullWidth` | `boolean` | `false` | 是否占满容器宽度 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 内容或 render 函数 |

-### Autocomplete.Trigger Props
+### Autocomplete.Trigger

 | Prop | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `children` | `ReactNode \| RenderFunction` | - | 触发器内容或渲染函数 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 触发器内容或 render 函数 |

-### Autocomplete.Value Props
+### Autocomplete.Value

 | Prop | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `children` | `ReactNode \| RenderFunction` | - | 值区域内容或渲染函数 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 值内容或 render 函数 |

-### Autocomplete.Indicator Props
+### Autocomplete.Indicator

 | Prop | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| `className` | `string` | - | 额外的 CSS 类 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
 | `children` | `ReactNode` | - | 自定义指示器内容 |

-### Autocomplete.ClearButton Props
+### Autocomplete.ClearButton

 | Prop | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| `className` | `string` | - | 额外的 CSS 类 |
-| `onClick` | `(e: MouseEvent) => void` | - | 点击按钮时触发的事件处理函数 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加 CSS 类 |
+| `onClick` | `(e: MouseEvent) => void` | - | 点击按钮时的回调 |
 | `ref` | `RefObject<HTMLButtonElement>` | - | 清除按钮元素的 ref |

-### Autocomplete.Popover Props
-
-| Prop        | 类型                                                                                                                                                                                                                                                                                                                     | 默认值    | 描述 |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------------------------------------ |
-| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | 弹出层相对触发器的位置 |
-| `className` | `string`                                                                                                                                                                                                                                                                                                                 | -          | 额外的 CSS 类 |
-| `children`  | `ReactNode`                                                                                                                                                                                                                                                                                                              | -          | 子内容。内部会包裹在 dialog 元素中以管理焦点，样式类为 `.autocomplete__popover-dialog`。 |
-
-### Autocomplete.Filter Props
+### Autocomplete.Popover

 | Prop | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
+|------|------|--------|------|
+| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | 弹出层相对触发器的位置 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode` | - | 子内容 |
+
+### Autocomplete.Filter
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
 | `filter` | `(text: string, input: string) => boolean` | - | 自定义过滤函数 |
-| `inputValue` | `string` | - | 受控的输入值 |
-| `onInputChange` | `(value: string) => void` | - | 输入值变化时触发的事件处理函数 |
+| `inputValue` | `string` | - | 受控输入值 |
+| `onInputChange` | `(value: string) => void` | - | 输入值变化时的回调 |
 | `children` | `ReactNode` | - | 过滤内容（SearchField 与 ListBox） |

 ### useFilter Hook

-React Aria 的 `useFilter` hook 为自动完成提供过滤函数。
+React Aria 的 `useFilter` hook 提供自动完成过滤函数。

 ```tsx
 import {useFilter} from "@heroui/react";
@@ -360,42 +322,44 @@ const {contains} = useFilter({sensitivity: "base"});
 </Autocomplete.Filter>
 ```

-**选项：**
+**Options:**

-| 选项 | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| `sensitivity` | `"base" \| "accent" \| "case" \| "variant"` | `"base"` | 匹配的本地化敏感度 |
+| Option | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `sensitivity` | `"base" \| "accent" \| "case" \| "variant"` | `"base"` | 匹配的 locale 敏感度 |

-**返回值：**
+**Returns:**

-| 函数 | 类型 | 描述 |
-| --- | --- | --- |
-| `contains` | `(string: string, substring: string) => boolean` | 判断字符串是否包含给定子串 |
-| `startsWith` | `(string: string, substring: string) => boolean` | 判断字符串是否以给定子串开头 |
-| `endsWith` | `(string: string, substring: string) => boolean` | 判断字符串是否以给定子串结尾 |
+| Function | 类型 | 描述 |
+|----------|------|------|
+| `contains` | `(string: string, substring: string) => boolean` | 判断字符串是否包含子串 |
+| `startsWith` | `(string: string, substring: string) => boolean` | 判断字符串是否以子串开头 |
+| `endsWith` | `(string: string, substring: string) => boolean` | 判断字符串是否以子串结尾 |

-### RenderProps
+### Render Props

-对 `Autocomplete.Value` 使用渲染函数时，会提供以下值：
+使用 Autocomplete.Value 的 render 函数时，提供以下值：

 | Prop | 类型 | 描述 |
-| --- | --- | --- |
+|------|------|------|
 | `defaultChildren` | `ReactNode` | 默认渲染的值 |
-| `isPlaceholder` | `boolean` | 值是否为占位符 |
+| `isPlaceholder` | `boolean` | 是否为占位符 |
 | `state` | `SelectState` | 自动完成的状态 |
-| `selectedItems` | `Node[]` | 当前选中的条目 |
+| `selectedItems` | `Node[]` | 当前选中项 |

 ## 无障碍

-Autocomplete 实现带过滤的 ARIA 选择模式，并提供：
+Autocomplete 组件实现带过滤的 ARIA select 模式，提供：

 - 完整键盘导航支持
- 选择变化时的屏幕阅读器播报
- 与 [Popover](/docs/components/popover) 一致的焦点管理：`Autocomplete.Popover` 会在内部用 dialog 包裹内容，避免触摸交互时在弹出层 overlay 上出现多余的焦点环
+- 选择变化的屏幕阅读器播报
+- 正确的焦点管理
 - 禁用状态支持
- 可搜索与过滤
+- 带过滤的搜索功能
 - HTML 表单集成

-若希望在弹出层打开时不立即唤起移动端键盘，可在 `SearchField` 上设置 `autoFocus={false}`。用户聚焦搜索输入框后仍可正常过滤。
+更多信息请参阅 [React Aria Select 文档](https://react-spectrum.adobe.com/react-aria/Select.html)。

-更多信息见 [React Aria Select 文档](https://react-spectrum.adobe.com/react-aria/Select.html)。
+## 相关组件
+
+<RelatedComponents component="autocomplete" />
@@ -1,6 +1,6 @@
 ---
 title: ComboBox 组合框
-description: 将文本输入与 ListBox 结合，用户可通过输入查询把选项列表过滤为匹配项。
+description: 将文本输入与 ListBox 结合，用户可通过输入查询把选项列表过滤为匹配项
 links:
  rac: ComboBox
  source: combo-box/combo-box.tsx
@@ -8,21 +8,17 @@ links:
  storybook: Components/Pickers/ComboBox
 ---

-## 引入
+## 用法

 ```tsx
 import { ComboBox } from '@heroui/react';
 ```

-### 用法
-
 <ComponentPreview
  name="combo-box-default"
 />

-### 组件结构
-
-引入 ComboBox 组件并通过点语法访问所有子部分。
+## 组件结构

 ```tsx
 import { ComboBox, Input, Label, Description, Header, ListBox, Separator } from '@heroui/react';
@@ -54,43 +50,45 @@ export default () => (
 )
 ```

+## 示例
+
+### 宽度充满
+
+<ComponentPreview
+  name="combo-box-full-width"
+/>
+
 ### 带描述

 <ComponentPreview
  name="combo-box-with-description"
 />

-### 带分组
-
-<ComponentPreview
-  name="combo-box-with-sections"
-/>
-
-### 带禁用选项
-
-<ComponentPreview
-  name="combo-box-with-disabled-options"
-/>
-
-### 自定义指示器
-
-<ComponentPreview
-  name="combo-box-custom-indicator"
-/>
-
 ### 必填

 <ComponentPreview
  name="combo-box-required"
 />

-### 自定义值
+### 禁用

 <ComponentPreview
-  name="combo-box-custom-value"
+  name="combo-box-disabled"
 />

-### 受控
+### 含禁用选项
+
+<ComponentPreview
+  name="combo-box-with-disabled-options"
+/>
+
+### 分组选项
+
+<ComponentPreview
+  name="combo-box-with-sections"
+/>
+
+### 受控组件

 <ComponentPreview
  name="combo-box-controlled"
@@ -108,10 +106,10 @@ export default () => (
  name="combo-box-asynchronous-loading"
 />

-### 自定义过滤
+### 默认选中项

 <ComponentPreview
-  name="combo-box-custom-filtering"
+  name="combo-box-default-selected-key"
 />

 ### 允许自定义值
@@ -120,33 +118,31 @@ export default () => (
  name="combo-box-allows-custom-value"
 />

-### 禁用
+### 自定义指示器

 <ComponentPreview
-  name="combo-box-disabled"
+  name="combo-box-custom-indicator"
 />

-### 默认选中项
+### 自定义展示值

 <ComponentPreview
-  name="combo-box-default-selected-key"
+  name="combo-box-custom-value"
 />

-### 全宽
+### 自定义过滤

 <ComponentPreview
-  name="combo-box-full-width"
+  name="combo-box-custom-filtering"
 />

-### 在 Surface 内
-
-在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的弱强调变体。
+### 渲染函数

 <ComponentPreview
-  name="combo-box-on-surface"
+  name="combo-box-render-function"
 />

-### 菜单触发
+### 菜单触发方式

 使用 `menuTrigger` prop 控制 Popover 何时打开：

@@ -158,45 +154,24 @@ export default () => (
  name="combo-box-menu-trigger"
 />

-### 自定义渲染函数
+### 表面样式
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。

 <ComponentPreview
-  name="combo-box-custom-render-function"
+  name="combo-box-on-surface"
 />

-<RelatedComponents component="combo-box" />
+## 自定义样式

-## 样式
+### Tailwind CSS

-### 传入 Tailwind CSS 类
+<ComponentPreview name="combo-box-custom-styles" />

-```tsx
-import { ComboBox, Input } from '@heroui/react';
+### 全局 CSS

-function CustomComboBox() {
-  return (
-    <ComboBox className="w-full">
-      <Label>Favorite Animal</Label>
-      <ComboBox.InputGroup className="border rounded-lg p-2 bg-surface">
-        <Input placeholder="Search animals..." />
-        <ComboBox.Trigger className="text-muted" />
-      </ComboBox.InputGroup>
-      <ComboBox.Popover>
-        <ListBox>
-          <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
-            Item 1
-          </ListBox.Item>
-        </ListBox>
-      </ComboBox.Popover>
-    </ComboBox>
-  );
-}
-```
-
-### 自定义组件类
-
-若要自定义 ComboBox 组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 ComboBox 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -218,19 +193,21 @@ function CustomComboBox() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 ComboBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/combo-box.css)）：

-#### 基础类
+#### 基础类 [!toc]
 - `.combo-box` - ComboBox 根容器
 - `.combo-box__input-group` - 输入框与触发按钮的容器
 - `.combo-box__trigger` - 打开 Popover 的按钮
 - `.combo-box__popover` - Popover 容器

-#### 状态类
+#### 状态类 [!toc]
 - `.combo-box[data-invalid="true"]` - 无效状态
 - `.combo-box[data-disabled="true"]` - 禁用状态
 - `.combo-box__trigger[data-focus-visible="true"]` - 触发器聚焦
@@ -239,87 +216,87 @@ ComboBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/he

 ### 交互状态

-组件同时支持伪类与 data 属性：
+组件同时支持 CSS 伪类与 data 属性：

- **悬停**：触发器上 `:hover` 或 `[data-hovered="true"]`
- **聚焦**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
- **禁用**：ComboBox 上 `:disabled` 或 `[data-disabled="true"]`
- **打开**：触发器上 `[data-open="true"]`
+- **Hover**：触发器上 `:hover` 或 `[data-hovered="true"]`
+- **Focus**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **Disabled**：ComboBox 上 `:disabled` 或 `[data-disabled="true"]`
+- **Open**：触发器上 `[data-open="true"]`

 ## API 参考

-### ComboBox Props
+### ComboBox

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `inputValue` | `string` | - | 当前输入值（受控）。 |
-| `defaultInputValue` | `string` | - | 默认输入值（非受控）。 |
-| `onInputChange` | `(value: string) => void` | - | 输入值变化时调用的事件处理函数。 |
-| `selectedKey` | `Key \| null` | - | 当前选中的 key（受控）。 |
-| `defaultSelectedKey` | `Key \| null` | - | 默认选中的 key（非受控）。 |
-| `onSelectionChange` | `(key: Key \| null) => void` | - | 选中变化时调用的事件处理函数。 |
-| `isOpen` | `boolean` | - | Popover 是否打开（受控）。 |
-| `defaultOpen` | `boolean` | - | Popover 默认是否打开（非受控）。 |
-| `onOpenChange` | `(isOpen: boolean) => void` | - | Popover 打开状态变化时调用的事件处理函数。 |
-| `items` | `Iterable<T>` | - | 在 ListBox 中展示的 items。 |
-| `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key。 |
-| `defaultFilter` | `(text: string, inputValue: string) => boolean` | - | 用于过滤 items 的自定义过滤函数。 |
-| `isDisabled` | `boolean` | - | 是否禁用 ComboBox。 |
-| `isReadOnly` | `boolean` | - | 输入是否可选中但不可由用户更改。 |
-| `isRequired` | `boolean` | - | 是否必填。 |
-| `isInvalid` | `boolean` | - | ComboBox 的值是否无效。 |
-| `validate` | `(value: ComboBoxValidationValue) => ValidationError \| true \| null \| undefined` | - | 若给定值无效则返回错误信息的函数。当 `validationBehavior="native"` 时，提交表单会向用户展示校验错误；实时校验请改用 `isInvalid` prop。 |
-| `validationBehavior` | `"native" \| "aria"` | `"native"` | 使用原生 HTML 表单校验在值缺失或无效时阻止提交，还是通过 ARIA 将字段标记为必填或无效。 |
-| `name` | `string` | - | 提交 HTML 表单时 input 的 name。 |
-| `form` | `string` | - | 要关联的 `<form>` 元素 id。 |
-| `formValue` | `"text" \| "key"` | `"key"` | 在 HTML 表单提交时提交选中项的文本还是 key。当 `allowsCustomValue` 为 `true` 时该选项不适用，始终提交文本。 |
-| `autoComplete` | `string` | - | 自动完成行为类型。 |
-| `autoFocus` | `boolean` | - | 是否在挂载时自动聚焦。 |
-| `allowsCustomValue` | `boolean` | - | 是否允许不在列表中的自定义值。 |
-| `allowsEmptyCollection` | `boolean` | - | 是否允许空集合。 |
-| `menuTrigger` | `"focus" \| "input" \| "manual"` | `"focus"` | 展示 ComboBox 菜单所需的交互。 |
-| `shouldFocusWrap` | `boolean` | - | 键盘导航是否循环。 |
-| `fullWidth` | `boolean` | `false` | ComboBox 是否占满容器宽度。 |
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode \| RenderFunction` | - | ComboBox 内容或渲染函数。 |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ComboBoxRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+| `inputValue` | `string` | - | 当前输入值（受控） |
+| `defaultInputValue` | `string` | - | 默认输入值（非受控） |
+| `onInputChange` | `(value: string) => void` | - | 输入值变化时的回调 |
+| `selectedKey` | `Key \| null` | - | 当前选中的 key（受控） |
+| `defaultSelectedKey` | `Key \| null` | - | 默认选中的 key（非受控） |
+| `onSelectionChange` | `(key: Key \| null) => void` | - | 选中变化时的回调 |
+| `isOpen` | `boolean` | - | Popover 是否打开（受控） |
+| `defaultOpen` | `boolean` | - | Popover 默认是否打开（非受控） |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | Popover 打开状态变化时的回调 |
+| `items` | `Iterable<T>` | - | 在 ListBox 中展示的 items |
+| `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key |
+| `defaultFilter` | `(text: string, inputValue: string) => boolean` | - | 用于过滤 items 的自定义过滤函数 |
+| `isDisabled` | `boolean` | - | 是否禁用 ComboBox |
+| `isReadOnly` | `boolean` | - | 输入是否可选中但不可由用户更改 |
+| `isRequired` | `boolean` | - | 是否必填 |
+| `isInvalid` | `boolean` | - | ComboBox 的值是否无效 |
+| `validate` | `(value: ComboBoxValidationValue) => ValidationError \| true \| null \| undefined` | - | 若给定值无效则返回错误信息的函数。当 `validationBehavior="native"` 时，提交表单会向用户展示校验错误；实时校验请改用 `isInvalid` prop |
+| `validationBehavior` | `"native" \| "aria"` | `"native"` | 使用原生 HTML 表单校验在值缺失或无效时阻止提交，还是通过 ARIA 将字段标记为必填或无效 |
+| `name` | `string` | - | 提交 HTML 表单时 input 的 name |
+| `form` | `string` | - | 要关联的 `<form>` 元素 id |
+| `formValue` | `"text" \| "key"` | `"key"` | 在 HTML 表单提交时提交选中项的文本还是 key。当 `allowsCustomValue` 为 `true` 时该选项不适用，始终提交文本 |
+| `autoComplete` | `string` | - | 自动完成行为类型 |
+| `autoFocus` | `boolean` | - | 是否在挂载时自动聚焦 |
+| `allowsCustomValue` | `boolean` | - | 是否允许不在列表中的自定义值 |
+| `allowsEmptyCollection` | `boolean` | - | 是否允许空集合 |
+| `menuTrigger` | `"focus" \| "input" \| "manual"` | `"focus"` | 展示 ComboBox 菜单所需的交互 |
+| `shouldFocusWrap` | `boolean` | - | 键盘导航是否循环 |
+| `fullWidth` | `boolean` | `false` | ComboBox 是否占满容器宽度 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | ComboBox 内容或 render 函数 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ComboBoxRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

-### ComboBox.InputGroup Props
+### ComboBox.InputGroup

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | InputGroup 内容。 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode` | - | InputGroup 内容 |

-### ComboBox.Trigger Props
+### ComboBox.Trigger

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | 自定义触发器内容。 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode` | - | 自定义触发器内容 |

-### ComboBox.Popover Props
+### ComboBox.Popover

 | Prop | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | 相对于触发器的 Popover 位置。 |
-| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
-| `children` | `ReactNode` | - | 子内容。 |
+| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | 相对于触发器的 Popover 位置 |
+| `className` | `string` | - | 附加 CSS 类 |
+| `children` | `ReactNode` | - | 子内容 |

-### RenderProps
+### Render Props

-对 ComboBox 使用渲染函数时，会传入以下值：
+对 ComboBox 使用 render 函数时，会传入以下值：

 | Prop | 类型 | 描述 |
 |------|------|------|
-| `state` | `ComboBoxState` | ComboBox 状态。 |
-| `inputValue` | `string` | 当前输入值。 |
-| `selectedKey` | `Key \| null` | 当前选中的 key。 |
-| `selectedItem` | `Node \| null` | 当前选中的 item。 |
+| `state` | `ComboBoxState` | ComboBox 状态 |
+| `inputValue` | `string` | 当前输入值 |
+| `selectedKey` | `Key \| null` | 当前选中的 key |
+| `selectedItem` | `Node \| null` | 当前选中的 item |

 ## 示例

-### 基础用法
+### 基本用法

 ```tsx
 import { ComboBox, Input, Label, ListBox } from '@heroui/react';
@@ -345,7 +322,7 @@ import { ComboBox, Input, Label, ListBox } from '@heroui/react';
 </ComboBox>
 ```

-### 带分组
+### 代码示例：分组选项

 ```tsx
 import { ComboBox, Input, Label, ListBox, Header, Separator } from '@heroui/react';
@@ -378,7 +355,7 @@ import { ComboBox, Input, Label, ListBox, Header, Separator } from '@heroui/reac
 </ComboBox>
 ```

-### 受控选中
+### 受控选择

 ```tsx
 import type { Key } from '@heroui/react';
@@ -417,7 +394,7 @@ function ControlledComboBox() {
 }
 ```

-### 受控输入值
+### 代码示例：受控输入值

 ```tsx
 import { ComboBox, Input, Label, ListBox } from '@heroui/react';
@@ -454,7 +431,7 @@ function ControlledInputComboBox() {
 }
 ```

-### 异步加载
+### 代码示例：异步加载

 ```tsx
 import { Collection, ComboBox, EmptyState, Input, Label, ListBox, ListBoxLoadMoreItem, Spinner } from '@heroui/react';
@@ -518,7 +495,7 @@ function AsyncComboBox() {
 }
 ```

-### 自定义过滤
+### 代码示例：自定义过滤

 ```tsx
 import { ComboBox, Input, Label, ListBox } from '@heroui/react';
@@ -550,7 +527,7 @@ import { ComboBox, Input, Label, ListBox } from '@heroui/react';
 </ComboBox>
 ```

-### 菜单触发
+### 代码示例：菜单触发方式

 使用 `menuTrigger` prop 控制 Popover 何时打开：

@@ -811,6 +788,7 @@ import { ComboBox, Input, Label, ListBox } from '@heroui/react';
 </ComboBox>
 ```

+
 ## 无障碍

 ComboBox 实现 ARIA ComboBox 模式，并提供：
@@ -825,3 +803,6 @@ ComboBox 实现 ARIA ComboBox 模式，并提供：

 更多信息见 [React Aria ComboBox 文档](https://react-spectrum.adobe.com/react-aria/ComboBox.html)。

+## 相关组件
+
+<RelatedComponents component="combo-box" />
@@ -8,19 +8,15 @@ links:
  storybook: Components/Pickers/Select
 ---

-## 引入
+## 用法

 ```tsx
 import { Select } from "@heroui/react";
 ```

-### 用法
-
 <ComponentPreview name="select-default" />

-### 组件结构
-
-引入 Select 组件，并通过点语法访问各部分。
+## 组件结构

 ```tsx
 import {Select, Label, Description, Header, ListBox, Separator} from "@heroui/react";
@@ -52,33 +48,7 @@ export default () => (
 );
 ```

-### 带描述
-
-<ComponentPreview name="select-with-description" />
-
-### 多选
-
-<ComponentPreview name="select-multiple-select" />
-
-### 分区
-
-<ComponentPreview name="select-with-sections" />
-
-### 含禁用项
-
-<ComponentPreview name="select-with-disabled-options" />
-
-### 自定义指示器
-
-<ComponentPreview name="select-custom-indicator" />
-
-### 必填
-
-<ComponentPreview name="select-required" />
-
-### 全宽
-
-<ComponentPreview name="select-full-width" />
+## 示例

 ### 变体

@@ -89,17 +59,35 @@ Select 组件支持两种视觉变体：

 <ComponentPreview name="select-variants" />

-### 在 Surface 内
+### 宽度充满

-在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+<ComponentPreview name="select-full-width" />

-<ComponentPreview name="select-on-surface" />
+### 带描述

-### 自定义展示值
+<ComponentPreview name="select-with-description" />

-<ComponentPreview name="select-custom-value" />
+### 必填

-### 受控
+<ComponentPreview name="select-required" />
+
+### 禁用
+
+<ComponentPreview name="select-disabled" />
+
+### 含禁用选项
+
+<ComponentPreview name="select-with-disabled-options" />
+
+### 多选
+
+<ComponentPreview name="select-multiple-select" />
+
+### 分组选项
+
+<ComponentPreview name="select-with-sections" />
+
+### 受控组件

 <ComponentPreview name="select-controlled" />

@@ -115,51 +103,35 @@ Select 组件支持两种视觉变体：

 <ComponentPreview name="select-asynchronous-loading" />

-### 禁用
+### 自定义指示器

-<ComponentPreview name="select-disabled" />
+<ComponentPreview name="select-custom-indicator" />

-<RelatedComponents component="select" />
+### 自定义展示值

-### 自定义渲染函数
+<ComponentPreview name="select-custom-value" />
+
+### 渲染函数

 <ComponentPreview
-  name="select-custom-render-function"
+  name="select-render-function"
 />

-## 样式
+### 表面样式

-### 传入 Tailwind CSS 类
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。

-```tsx
-import {Select} from "@heroui/react";
+<ComponentPreview name="select-on-surface" />

-function CustomSelect() {
-  return (
-    <Select className="w-full">
-      <Label>State</Label>
-      <Select.Trigger className="rounded-lg border bg-surface p-2">
-        <Select.Value />
-        <Select.Indicator />
-      </Select.Trigger>
-      <Select.Popover>
-        <ListBox>
-          <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
-            Item 1
-          </ListBox.Item>
-        </ListBox>
-      </Select.Popover>
-    </Select>
-  );
-}
-```
+## 自定义样式

-### 自定义组件类
+### Tailwind CSS

-若要自定义 Select 组件类，可以使用 `@layer components` 指令。
+<ComponentPreview name="select-custom-styles" />

-<br />
-[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+### 全局 CSS
+
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -185,13 +157,15 @@ function CustomSelect() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 Select 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/select.css)）：

-#### 基础类
+#### 基础类 [!toc]

 - `.select` - Select 根容器
 - `.select__trigger` - 打开下拉的触发按钮
@@ -199,12 +173,12 @@ Select 组件使用以下 CSS 类（[查看源码样式](https://github.com/hero
 - `.select__indicator` - 下拉指示图标
 - `.select__popover` - 弹出层容器

-#### 变体类
+#### 变体类 [!toc]

 - `.select--primary` - Primary 变体，带阴影（默认）
 - `.select--secondary` - Secondary 变体，无阴影，适合在 Surface 上使用

-#### 状态类
+#### 状态类 [!toc]

 - `.select[data-invalid="true"]` - 无效状态
 - `.select__trigger[data-focus-visible="true"]` - 触发器聚焦状态
@@ -223,8 +197,7 @@ Select 组件使用以下 CSS 类（[查看源码样式](https://github.com/hero

 ## API 参考

-### Select Props
-
+### Select
 | Prop            | 类型                                    | 默认值            | 描述                                              |
 | --------------- | --------------------------------------- | ----------------- | ------------------------------------------------- |
 | `placeholder`   | `string`                                | `'Select an item'` | Select 为空时显示的占位符文本。                   |
@@ -247,30 +220,26 @@ Select 组件使用以下 CSS 类（[查看源码样式](https://github.com/hero
 | `children`      | `ReactNode \| RenderFunction`           | -                 | Select 内容或渲染函数。                           |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SelectRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Select.Trigger Props
-
+### Select.Trigger
 | Prop        | 类型                          | 默认值 | 描述                        |
 | ----------- | ----------------------------- | ------ | --------------------------- |
 | `className` | `string`                      | -      | 额外的 CSS 类。             |
 | `children`  | `ReactNode \| RenderFunction` | -      | 触发器内容或渲染函数。      |

-### Select.Value Props
-
+### Select.Value
 | Prop        | 类型                          | 默认值 | 描述                      |
 | ----------- | ----------------------------- | ------ | ------------------------- |
 | `className` | `string`                      | -      | 额外的 CSS 类。           |
 | `children`  | `ReactNode \| RenderFunction` | -      | 值区域内容或渲染函数。    |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SelectValueRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

-### Select.Indicator Props
-
+### Select.Indicator
 | Prop        | 类型        | 默认值 | 描述              |
 | ----------- | ----------- | ------ | ----------------- |
 | `className` | `string`    | -      | 额外的 CSS 类。   |
 | `children`  | `ReactNode` | -      | 自定义指示器内容。 |

-### Select.Popover Props
-
+### Select.Popover
 | Prop        | 类型                                                                                                                                                                                                                                                                                                                     | 默认值    | 描述                                      |
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ----------------------------------------- |
 | `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | 弹出层相对触发器的位置。                  |
@@ -300,3 +269,7 @@ Select 组件实现 ARIA 列表框模式，并提供：
 - 与 HTML 表单的集成

 更多信息见 [React Aria Select 文档](https://react-spectrum.adobe.com/react-aria/Select.html)。
+
+## 相关组件
+
+<RelatedComponents component="select" />
@@ -1,6 +1,6 @@
 ---
 title: Kbd 键盘按键
-description: 用于展示键盘快捷键与组合键。
+description: 展示键盘快捷键与按键组合
 links:
  source: kbd/kbd.tsx
  styles: kbd.css
@@ -8,21 +8,17 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { Kbd } from "@heroui/react";
 ```

-### 用法
-
 <ComponentPreview 
  name="kbd-basic"
 />

-### 组件结构
-
-导入 Kbd 组件后，可通过点语法访问所有子部分。
+## 组件结构

 ```tsx
 import { Kbd } from "@heroui/react";
@@ -35,7 +31,15 @@ export default () => (
 );
 ```

-### 导航键
+## 示例
+
+### 变体
+
+<ComponentPreview 
+  name="kbd-variants"
+/>
+
+### 导航按键

 <ComponentPreview 
  name="kbd-navigation-keys"
@@ -47,46 +51,28 @@ export default () => (
  name="kbd-inline-usage"
 />

-### 说明性文本
+### 说明文字

 <ComponentPreview 
  name="kbd-instructional-text"
 />

-### 特殊键
+### 特殊按键

 <ComponentPreview 
  name="kbd-special-keys"
 />

-### 变体
+## 自定义样式

-<ComponentPreview 
-  name="kbd-variants"
-/>
+### Tailwind CSS

-<RelatedComponents component="kbd" />
+<ComponentPreview name="kbd-custom-styles" />

-## 样式
+### 全局 CSS

-### 传入 Tailwind CSS 类
-
-```tsx
-import { Kbd } from "@heroui/react";
-
-function CustomKbd() {
-  return (
-    <Kbd className="bg-gray-100 dark:bg-gray-800">
-      <Kbd.Content>K</Kbd.Content>
-    </Kbd>
-  );
-}
-```
-
-### 自定义组件类
-
-要自定义 Kbd 的组件类，可使用 `@layer components` 指令。
-<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+可使用 `@layer components` 指令自定义 Kbd 组件类。
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -104,46 +90,48 @@ function CustomKbd() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

-Kbd 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/kbd.css)）：
+Kbd 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/kbd.css)）：

-#### 基础类
+#### 基础类 [!toc]

- `.kbd` — 按键基础样式（背景、边框与间距）
- `.kbd__abbr` — 修饰键的缩写元素
- `.kbd__content` — 按键文字的包裹层
+- `.kbd` - 基础按键样式，含背景、边框与间距
+- `.kbd__abbr` - 修饰键的缩写元素
+- `.kbd__content` - 按键文本的内容包裹层

 ## API 参考

-### Kbd Props
+### Kbd

-| Prop        | 类型              | 默认值    | 描述                   |
-| ----------- | ----------------- | --------- | ---------------------- |
-| `children`  | `React.ReactNode` | -         | 按键内容               |
-| `variant`   | `"default" \| "light"` | `default`       | 键盘按键的视觉变体 |
-| `className` | `string`          | -         | 自定义 CSS 类          |
+| Prop        | 类型              | 默认值 | 描述            |
+| ----------- | ----------------- | ------- | ---------------------- |
+| `children`  | `React.ReactNode` | -       | 按键内容     |
+| `variant`   | `"default" | "light"` | `default`       | 按键视觉变体 |
+| `className` | `string`          | -       | 自定义 CSS 类     |

-### Kbd.Abbr Props
+### Kbd.Abbr

-| Prop        | 类型              | 默认值 | 描述                                                                 |
-| ----------- | ----------------- | ------ | -------------------------------------------------------------------- |
-| `title`     | `string`          | -      | 无障碍 `title`（例如 ⌘ 对应 “Command”）                            |
-| `children`  | `React.ReactNode` | -      | 显示的符号或文本（例如 ⌘、⌥、⇧）                                   |
-| `className` | `string`          | -      | 自定义 CSS 类                                                       |
+| Prop        | 类型     | 默认值 | 描述                                                                                                                               |
+| ----------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`     | `string` | -       | 无障碍 title 属性（如 ⌘ 对应 "Command"）                                                                               |
+| `children`  | `React.ReactNode` | -       | 要显示的符号或文本（如 ⌘、⌥、⇧）                                                                                          |
+| `className` | `string` | -       | 自定义 CSS 类                                                                                                                       |

-### Kbd.Key Props
+### Kbd.Key

-| Prop        | 类型              | 默认值 | 描述                 |
-| ----------- | ----------------- | ------ | -------------------- |
-| `children`  | `React.ReactNode` | -      | 按键上的文本         |
-| `className` | `string`          | -      | 自定义 CSS 类        |
+| Prop        | 类型              | 默认值 | 描述                        |
+| ----------- | ----------------- | ------- | ---------------------------------- |
+| `children`  | `React.ReactNode` | -       | 按键文本内容            |
+| `className` | `string`          | -       | 自定义 CSS 类                 |

 ### Kbd.Content Type

-`keyValue` 属性可用的按键取值：
+`keyValue` prop 可用的按键值：

 | Modifier Keys | Special Keys | Navigation Keys | Function Keys |
 | ------------- | ------------ | --------------- | ------------- |
@@ -155,3 +143,7 @@ Kbd 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/he
 | `win`         | `capslock`   | `pagedown`      |               |
 |               | `help`       | `home`          |               |
 |               |              | `end`           |               |
+
+## 相关组件
+
+<RelatedComponents component="kbd" />
@@ -7,19 +7,33 @@ links:
  storybook: Components/Typography
 ---

-## 引入
+## 用法

 ```tsx
 import {Typography} from "@heroui/react";
 ```

-## 用法
+<ComponentPreview name="typography-default" />

-<ComponentPreview name="typography-typography-scale" />
+## 组件结构

 默认情况下，`Typography` 会将视觉上的 `type` 映射到对应的语义化元素。

-## 子组件
+```tsx
+import {Typography} from "@heroui/react";
+
+export default () => (
+  <Typography type="h1">Heading</Typography>
+);
+```
+
+## 示例
+
+### 层级
+
+<ComponentPreview name="typography-typography-scale" />
+
+### 原语

 <ComponentPreview name="typography-primitives" />

@@ -28,30 +42,58 @@ import {Typography} from "@heroui/react";
 - `Typography.Code` 映射为行内代码样式。
 - `Typography.Prose` 为以常规 HTML 子节点传入的富文本内容提供排版样式。

-## Prose
+### 富文本排版

 <ComponentPreview name="typography-prose" />

-## Render Prop
+### 渲染属性

 <ComponentPreview name="typography-render-props" />

 需要自定义实际渲染的元素时，可使用 React Aria Components 风格的 `render` prop。

-## CSS 类名
+## 自定义样式

-### 基础类
+### Tailwind CSS
+
+<ComponentPreview name="typography-custom-styles" />
+
+### 全局 CSS
+
+若要自定义 Typography 组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .typography--h1 {
+    @apply font-extrabold tracking-tight;
+  }
+
+  .typography--code {
+    @apply rounded-md bg-default-100 font-mono dark:bg-default-50/20;
+  }
+}
+```
+
+## 样式参考
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Typography 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/typography.css)）：
+
+#### 基础类 [!toc]

 - `.typography` - 排版基础原语
 - `.typography-prose` - 富文本文章体容器

-### 类型类
+#### 类型类 [!toc]

 - `.typography--h1` 至 `.typography--h6`
 - `.typography--body`、`.typography--body-sm`、`.typography--body-xs`
 - `.typography--code`

-### 修饰类
+#### 修饰类 [!toc]

 - `.typography--align-start`、`.typography--align-center`、`.typography--align-end`、`.typography--align-justify`
 - `.typography--color-default`、`.typography--color-muted`
@@ -60,7 +102,7 @@ import {Typography} from "@heroui/react";

 ## API 参考

-### Typography 属性
+### Typography

 | 属性       | 类型                                                                                           | 默认值     | 说明                                    |
 | ---------- | ---------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------- |
@@ -71,3 +113,7 @@ import {Typography} from "@heroui/react";
 | `truncate` | `boolean`                                                                                      | -           | 将文本截断为单行并显示省略号。  |
 | `render`   | `DOMRenderFunction`                                                                            | -           | 来自 React Aria 的自定义渲染函数。        |
 | `children` | `ReactNode`                                                                                    | -           | 文本内容。                                  |
+
+## 相关组件
+
+<RelatedComponents component="typography" />
@@ -8,65 +8,45 @@ links:
  figma: true
 ---

-## 引入
+## 用法

 ```tsx
 import { ScrollShadow } from "@heroui/react";
 ```

-## 用法
-
 <ComponentPreview name="scroll-shadow-default" />

-## 方向
+## 示例
+
+### 方向

 <ComponentPreview name="scroll-shadow-orientation" />

-## 隐藏滚动条
+### 阴影尺寸

-<ComponentPreview name="scroll-shadow-hide-scroll-bar" />
+<ComponentPreview name="scroll-shadow-size" />

-## 自定义阴影尺寸
-
-<ComponentPreview name="scroll-shadow-custom-size" />
-
-## 可见性变化
-
-<ComponentPreview name="scroll-shadow-visibility-change" />
-
-## 与 Card 组合
+### 与 Card 组合

 <ComponentPreview name="scroll-shadow-with-card" />

-## 样式
+### 隐藏滚动条

-### 传入 Tailwind CSS 类
+<ComponentPreview name="scroll-shadow-hide-scroll-bar" />

-```tsx
-import {ScrollShadow, Card} from "@heroui/react";
+### 可见性变化

-function CustomScrollShadow() {
-  return (
-    <Card className="w-full p-0 sm:max-w-md">
-      <ScrollShadow className="max-h-[300px] p-6 bg-gradient-to-b from-purple-50 to-pink-50">
-        <div className="space-y-4">
-          {Array.from({length: 10}).map((_, idx) => (
-            <p key={idx}>
-              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
-              risus hendrerit venenatis.
-            </p>
-          ))}
-        </div>
-      </ScrollShadow>
-    </Card>
-  );
-}
-```
+<ComponentPreview name="scroll-shadow-visibility-change" />

-### 自定义组件类
+## 自定义样式

-若要自定义 ScrollShadow 组件类，可以使用 `@layer components` 指令。
-<br />[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+### Tailwind CSS
+
+<ComponentPreview name="scroll-shadow-custom-styles" />
+
+### 全局 CSS
+
+若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

 ```css
@layer components {
@@ -84,22 +64,24 @@ function CustomScrollShadow() {
 }
 ```

+## 样式参考
+
 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

 ### CSS 类

 ScrollShadow 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/scroll-shadow.css)）：

-#### 基础类
+#### 基础类 [!toc]

 - `.scroll-shadow` - 根容器元素

-#### 方向变体
+#### 方向变体 [!toc]

 - `.scroll-shadow--vertical` - 纵向滚动（默认）
 - `.scroll-shadow--horizontal` - 横向滚动

-#### 状态修饰符
+#### 状态修饰符 [!toc]

 - `.scroll-shadow--hide-scrollbar` - 隐藏原生滚动条

@@ -137,3 +119,7 @@ ScrollShadow 组件使用 CSS 变量设置渐变遮罩尺寸，并为可见的
 | `onVisibilityChange` | `(visibility: ScrollShadowVisibility) => void`                                | -            | 阴影可见性变化时调用的回调         |
 | `className`          | `string`                                                                      | -            | 应用到根元素上的额外 CSS 类     |
 | `children`           | `ReactNode`                                                                   | -            | 可滚动的子内容                                  |
+
+## 相关组件
+
+<RelatedComponents component="scrollshadow" />
@@ -24,10 +24,10 @@
    "(buttons)/close-button",
    "(colors)/color-area",
    "(colors)/color-field",
+    "(colors)/color-picker",
    "(colors)/color-slider",
    "(colors)/color-swatch",
    "(colors)/color-swatch-picker",
-    "(colors)/color-picker",
    "(pickers)/combo-box",
    "(date-and-time)/date-field",
    "(date-and-time)/date-picker",
@@ -69,14 +69,14 @@
    "(data-display)/table",
    "(navigation)/tabs",
    "(collections)/tag-group",
-    "(typography)/typography",
-    "(forms)/text-field",
    "(forms)/text-area",
+    "(forms)/text-field",
    "(date-and-time)/time-field",
    "(overlays)/toast",
-    "(layout)/toolbar",
    "(buttons)/toggle-button",
    "(buttons)/toggle-button-group",
-    "(overlays)/tooltip"
+    "(layout)/toolbar",
+    "(overlays)/tooltip",
+    "(typography)/typography"
  ]
 }
@@ -10,7 +10,7 @@
    "(overview)/design-principles",
    "(overview)/frameworks",
    "(overview)/cli",
-    "[sparkles][展示](/showcase)",
+    "[sparkles][组件案例](/showcase)",
    "[route][路线图](https://herouiv3.featurebase.app/roadmap)",
    "[figma][Figma](https://www.figma.com/community/file/1546526812159103429)",
    "---手册---",
@@ -163,7 +163,7 @@ github:
 为 [Button](/docs/components/button) 与 [ButtonGroup](/docs/components/button-group) 同时新增 `outline` 变体，用于呈现描边样式。

 <ComponentPreview
-  name="button-outline-variant"
+  name="release-button-outline-variant"
 />

 ### AlertDialog 尺寸支持
@@ -132,7 +132,7 @@ github:
 ```

 <ComponentPreview
-  name="date-range-picker-input-container"
+  name="release-date-range-picker-input-container"
 />

 ## ⚠️ 破坏性变更
@@ -78,7 +78,7 @@ Soft 状态不再直接套语义色，而是使用专门的 foreground token，
 </html>
 ```

-<ComponentPreview name="chip-vibrant-palette" />
+<ComponentPreview name="release-chip-vibrant-palette" />

 ### 统一滚动条系统

@@ -101,7 +101,7 @@ Soft 状态不再直接套语义色，而是使用专门的 foreground token，
  <span>垂直滚动</span>
 </div>

-<ComponentPreview name="list-box-scrollbar-modes" />
+<ComponentPreview name="release-list-box-scrollbar-modes" />

 Select、ComboBox、Autocomplete、Dropdown、DatePicker、DateRangePicker、ColorPicker、Table、Tabs、Modal、Drawer 和 ScrollShadow 已接入同一套工具。

@@ -1,7 +1,6 @@
 ---
 title: ButtonGroup
 description: Group related buttons together with consistent styling and spacing
-
 links:
  rac: Button
  source: button-group/button-group.tsx
@@ -10,21 +9,17 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { ButtonGroup, Button } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="button-group-basic"
 />

-### Anatomy
-
-Import the ButtonGroup component and access all parts using dot notation.
+## Anatomy

 ```tsx
 import { ButtonGroup, Button } from '@heroui/react';
@@ -46,6 +41,8 @@ export default () => (

 > **ButtonGroup** wraps multiple Button components together, applying consistent styling, spacing, and automatic border radius handling. It uses React Context to pass `size`, `variant`, and `isDisabled` props to all child buttons.

+## Examples
+
 ### Variants

 <ComponentPreview
@@ -92,36 +89,16 @@ Simply omit the `<ButtonGroup.Separator />` component from your buttons.
  name="button-group-without-separator"
 />

-<RelatedComponents component="button-group" />
+## Customization

-## Styling
+### Tailwind CSS

-### Passing Tailwind CSS classes
+<ComponentPreview name="button-group-custom-styles" />

-```tsx
-import { ButtonGroup, Button } from '@heroui/react';
-
-function CustomButtonGroup() {
-  return (
-    <ButtonGroup className="gap-2">
-      <Button>First</Button>
-      <Button>
-        <ButtonGroup.Separator />
-        Second
-      </Button>
-      <Button>
-        <ButtonGroup.Separator />
-        Third
-      </Button>
-    </ButtonGroup>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the ButtonGroup component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -135,13 +112,15 @@ To customize the ButtonGroup component classes, you can use the `@layer componen
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The ButtonGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.button-group` - Base button group container
 - `.button-group--full-width` - Full width modifier
 - `.button-group__separator` - Separator element between buttons
@@ -156,7 +135,7 @@ Add `<ButtonGroup.Separator />` inside each Button (except the first) to show di

 ## API Reference

-### ButtonGroup Props
+### ButtonGroup

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -168,13 +147,13 @@ Add `<ButtonGroup.Separator />` inside each Button (except the first) to show di
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `React.ReactNode` | - | Button components to group together |

-### ButtonGroup.Separator Props
+### ButtonGroup.Separator

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |

-### Notes
+## Note

 - ButtonGroup uses React Context to pass `size`, `variant`, and `isDisabled` props to all child Button components
 - **Only direct child buttons receive the ButtonGroup props** - Buttons nested inside other components (like Modal, Dropdown, etc.) will not inherit the group's props even if they are descendants of the ButtonGroup
@@ -182,3 +161,7 @@ Add `<ButtonGroup.Separator />` inside each Button (except the first) to show di
 - The component automatically handles border radius between buttons
 - Add `<ButtonGroup.Separator />` inside each Button (except the first) to show dividers between buttons
 - Buttons in a group have their active/pressed scale transform removed for a more cohesive appearance
+
+## Related Components
+
+<RelatedComponents component="button-group" />
@@ -9,25 +9,30 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { Button } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="button-basic"
 />

-### Variants
+## Examples

+### Variants

 <ComponentPreview
  name="button-variants"
 />

+### Sizes
+
+<ComponentPreview
+  name="button-sizes"
+/>
+
 ### With Icons

 <ComponentPreview
@@ -52,12 +57,6 @@ import { Button } from '@heroui/react';
  name="button-loading-state"
 />

-### Sizes
-
-<ComponentPreview
-  name="button-sizes"
-/>
-
 ### Full Width

 <ComponentPreview
@@ -66,7 +65,6 @@ import { Button } from '@heroui/react';

 ### Disabled State

-
 <ComponentPreview
  name="button-disabled"
 />
@@ -77,51 +75,12 @@ import { Button } from '@heroui/react';
  name="button-social"
 />

-### Custom Render Function
+### Render Function

 <ComponentPreview
-  name="button-custom-render-function"
+  name="button-render-function"
 />

-<RelatedComponents component="button" />
-
-<RelatedShowcases component="Button" />
-
-## Styling
-
-### Passing Tailwind CSS classes
-
-```tsx
-import { Button } from '@heroui/react';
-
-function CustomButton() {
-  return (
-    <Button className="bg-purple-500 text-white hover:bg-purple-600">
-      Purple Button
-    </Button>
-  );
-}
-```
-
-### Customizing the component classes
-
-To customize the Button component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
-
-```css
-@layer components {
-  .button {
-    @apply bg-purple-500 text-white hover:bg-purple-600;
-  }
-
-  .button--icon-only {
-    @apply rounded-lg bg-blue-500;
-  }
-}
-```
-
-HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
-
 ### Adding custom variants

 You can extend HeroUI components by wrapping them and adding your own custom variants.
@@ -138,17 +97,44 @@ The Button component supports ripple effects through composition, allowing you t
  name="button-ripple-effect"
 />

+## Customization
+
+### Tailwind CSS
+
+<ComponentPreview name="button-custom-styles" />
+
+### Global CSS
+
+To customize the Button component classes, you can use the `@layer components` directive.
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .button {
+    @apply bg-purple-500 text-white hover:bg-purple-600;
+  }
+
+  .button--icon-only {
+    @apply rounded-lg bg-blue-500;
+  }
+}
+```
+
+## Styling Reference
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
 ### CSS Classes

 The Button component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css)):

-#### Base & Size Classes
+#### Base & Size Classes [!toc]
 - `.button` - Base button styles
 - `.button--sm` - Small size variant
 - `.button--md` - Medium size variant
 - `.button--lg` - Large size variant

-#### Variant Classes
+#### Variant Classes [!toc]
 - `.button--primary`
 - `.button--secondary`
 - `.button--tertiary`
@@ -156,7 +142,7 @@ The Button component uses these CSS classes ([View source styles](https://github
 - `.button--ghost`
 - `.button--danger`

-#### Modifier Classes
+#### Modifier Classes [!toc]
 - `.button--icon-only`
 - `.button--icon-only.button--sm`
 - `.button--icon-only.button--lg`
@@ -173,7 +159,7 @@ The button supports both CSS pseudo-classes and data attributes for flexibility:

 ## API Reference

-### Button Props
+### Button

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -187,7 +173,7 @@ The button supports both CSS pseudo-classes and data attributes for flexibility:
 | `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | Button content or render prop |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### ButtonRenderProps
+### Render Props

 When using the render prop pattern, these values are provided:

@@ -200,3 +186,10 @@ When using the render prop pattern, these values are provided:
 | `isFocusVisible` | `boolean` | Whether the button should show focus indicator |
 | `isDisabled` | `boolean` | Whether the button is disabled |

+## Related Showcases
+
+<RelatedShowcases component="Button" />
+
+## Related Components
+
+<RelatedComponents component="button" />
@@ -8,48 +8,40 @@ links:
  storybook: Components/Buttons/CloseButton
 ---

-## Import
+## Usage

 ```tsx
 import { CloseButton } from "@heroui/react";
 ```

-### Usage
-
 <ComponentPreview
  name="close-button-default"
 />

+## Examples
+
+### Interactive
+
+<ComponentPreview
+  name="close-button-interactive"
+/>
+
 ### With Custom Icon

 <ComponentPreview
  name="close-button-with-custom-icon"
 />

-### Interactive
+## Customization

-<ComponentPreview
-  name="close-button-interactive"
-/>
+### Tailwind CSS

-<RelatedComponents component="closebutton" />
+<ComponentPreview name="close-button-custom-styles" />

-## Styling
-
-### Passing Tailwind CSS classes
-
-```tsx
-import {CloseButton} from "@heroui/react";
-
-function CustomCloseButton() {
-  return <CloseButton className="text-red-600 hover:bg-red-100">Close</CloseButton>;
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the CloseButton component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -63,17 +55,19 @@ To customize the CloseButton component classes, you can use the `@layer componen
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The CloseButton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/close-button.css)):

-#### Base Classes
+#### Base Classes [!toc]

 - `.close-button` - Base component styles

-#### Variant Classes
+#### Variant Classes [!toc]

 - `.close-button--default` - Default variant

@@ -88,7 +82,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 ## API Reference

-### CloseButton Props
+### CloseButton

 | Prop       | Type                    | Default     | Description |
 | ---------- | ----------------------- | ----------- | ----------- |
@@ -107,7 +101,7 @@ CloseButton extends all React Aria Button props. Common props include:
 | `aria-labelledby` | `string`  | ID of element that labels the button |
 | `aria-describedby`| `string`  | ID of element that describes the button |

-### RenderProps
+### Render Props

 When using the render prop pattern, these values are provided:

@@ -117,3 +111,7 @@ When using the render prop pattern, these values are provided:
 | `isPressed`   | `boolean` | Whether the button is pressed |
 | `isFocused`   | `boolean` | Whether the button is focused |
 | `isDisabled`  | `boolean` | Whether the button is disabled |
+
+## Related Components
+
+<RelatedComponents component="closebutton" />
@@ -9,21 +9,17 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="toggle-button-group-basic"
 />

-### Anatomy
-
-Import the ToggleButtonGroup component and access all parts using dot notation.
+## Anatomy

 ```tsx
 import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
@@ -43,6 +39,8 @@ export default () => (
 );
 ```

+## Examples
+
 ### Sizes

 <ComponentPreview
@@ -55,34 +53,12 @@ export default () => (
  name="toggle-button-group-orientation"
 />

-### Detached
-
-Use `isDetached` to separate buttons with gaps instead of connecting them.
-
-<ComponentPreview
-  name="toggle-button-group-attached"
-/>
-
 ### Full Width

 <ComponentPreview
  name="toggle-button-group-full-width"
 />

-### Selection Mode
-
-Use `selectionMode="single"` for mutually exclusive choices or `selectionMode="multiple"` for independent toggles.
-
-<ComponentPreview
-  name="toggle-button-group-selection-mode"
-/>
-
-### Controlled
-
-<ComponentPreview
-  name="toggle-button-group-controlled"
-/>
-
 ### Disabled

 <ComponentPreview
@@ -97,32 +73,38 @@ Simply omit the `<ToggleButtonGroup.Separator />` component from your buttons.
  name="toggle-button-group-without-separator"
 />

-<RelatedComponents component="toggle-button-group" />
+### Detached

-## Styling
+Use `isDetached` to separate buttons with gaps instead of connecting them.

-### Passing Tailwind CSS classes
+<ComponentPreview
+  name="toggle-button-group-attached"
+/>

-```tsx
-import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
+### Selection Mode

-function CustomToggleButtonGroup() {
-  return (
-    <ToggleButtonGroup className="bg-purple-100" selectionMode="single">
-      <ToggleButton id="a">Option A</ToggleButton>
-      <ToggleButton id="b">
-        <ToggleButtonGroup.Separator />
-        Option B
-      </ToggleButton>
-    </ToggleButtonGroup>
-  );
-}
-```
+Use `selectionMode="single"` for mutually exclusive choices or `selectionMode="multiple"` for independent toggles.

-### Customizing the component classes
+<ComponentPreview
+  name="toggle-button-group-selection-mode"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="toggle-button-group-controlled"
+/>
+
+## Customization
+
+### Tailwind CSS
+
+<ComponentPreview name="toggle-button-group-custom-styles" />
+
+### Global CSS

 To customize the ToggleButtonGroup component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -140,25 +122,27 @@ To customize the ToggleButtonGroup component classes, you can use the `@layer co
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The ToggleButtonGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button-group.css)):

-#### Base & Layout Classes
+#### Base & Layout Classes [!toc]
 - `.toggle-button-group` - Base container styles
 - `.toggle-button-group--horizontal` - Horizontal orientation
 - `.toggle-button-group--vertical` - Vertical orientation
 - `.toggle-button-group--full-width` - Full width modifier
 - `.toggle-button-group__separator` - Separator element between buttons

-#### Modifier Classes
+#### Modifier Classes [!toc]
 - `.toggle-button-group--detached` - Detached mode (separated buttons with gaps)

 ## API Reference

-### ToggleButtonGroup Props
+### ToggleButtonGroup

 Inherits from [React Aria ToggleButtonGroup](https://react-aria.adobe.com/ToggleButtonGroup).

@@ -176,13 +160,13 @@ Inherits from [React Aria ToggleButtonGroup](https://react-aria.adobe.com/Toggle
 | `isDisabled` | `boolean` | `false` | Disables all buttons in the group |
 | `className` | `string` | - | Additional CSS classes |

-### ToggleButtonGroup.Separator Props
+### ToggleButtonGroup.Separator

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |

-### Notes
+## Note

 - ToggleButtonGroup uses React Context to pass `size` to all child ToggleButton components
 - Each ToggleButton must have a unique `id` prop that corresponds to the keys used in `selectedKeys` / `defaultSelectedKeys`
@@ -190,3 +174,7 @@ Inherits from [React Aria ToggleButtonGroup](https://react-aria.adobe.com/Toggle
 - The component automatically handles border radius between buttons
 - Add `<ToggleButtonGroup.Separator />` inside each ToggleButton (except the first) to show dividers between buttons
 - Use `disallowEmptySelection` with `selectionMode="single"` to ensure one option is always selected
+
+## Related Components
+
+<RelatedComponents component="toggle-button-group" />
@@ -9,18 +9,18 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { ToggleButton } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="toggle-button-basic"
 />

+## Examples
+
 ### Variants

 <ComponentPreview
@@ -39,6 +39,11 @@ import { ToggleButton } from '@heroui/react';
  name="toggle-button-sizes"
 />

+### Disabled
+
+<ComponentPreview
+  name="toggle-button-disabled"
+/>

 ### Controlled

@@ -46,34 +51,16 @@ import { ToggleButton } from '@heroui/react';
  name="toggle-button-controlled"
 />

-### Disabled
+## Customization

-<ComponentPreview
-  name="toggle-button-disabled"
-/>
+### Tailwind CSS

-<RelatedComponents component="togglebutton" />
+<ComponentPreview name="toggle-button-custom-styles" />

-## Styling
-
-### Passing Tailwind CSS classes
-
-```tsx
-import { ToggleButton } from '@heroui/react';
-
-function CustomToggleButton() {
-  return (
-    <ToggleButton className="bg-purple-500 text-white">
-      Toggle
-    </ToggleButton>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the ToggleButton component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -87,23 +74,25 @@ To customize the ToggleButton component classes, you can use the `@layer compone
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The ToggleButton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button.css)):

-#### Base & Size Classes
+#### Base & Size Classes [!toc]
 - `.toggle-button` - Base toggle button styles
 - `.toggle-button--sm` - Small size variant
 - `.toggle-button--md` - Medium size variant (default)
 - `.toggle-button--lg` - Large size variant

-#### Variant Classes
+#### Variant Classes [!toc]
 - `.toggle-button--default` - Default variant with filled background
 - `.toggle-button--ghost` - Ghost variant with transparent background

-#### Modifier Classes
+#### Modifier Classes [!toc]
 - `.toggle-button--icon-only` - Icon-only toggle button
 - `.toggle-button--icon-only.toggle-button--sm` - Small icon-only
 - `.toggle-button--icon-only.toggle-button--lg` - Large icon-only
@@ -120,7 +109,7 @@ The toggle button supports both CSS pseudo-classes and data attributes for flexi

 ## API Reference

-### ToggleButton Props
+### ToggleButton

 Inherits from [React Aria ToggleButton](https://react-spectrum.adobe.com/react-aria/ToggleButton.html).

@@ -136,7 +125,7 @@ Inherits from [React Aria ToggleButton](https://react-spectrum.adobe.com/react-a
 | `onPress` | `(e: PressEvent) => void` | - | Handler called when the button is pressed |
 | `children` | `React.ReactNode \| (values: ToggleButtonRenderProps) => React.ReactNode` | - | Button content or render prop |

-### ToggleButtonRenderProps
+### Render Props

 When using the render prop pattern, these values are provided:

@@ -148,3 +137,7 @@ When using the render prop pattern, these values are provided:
 | `isFocused` | `boolean` | Whether the button is focused |
 | `isFocusVisible` | `boolean` | Whether the button should show focus indicator |
 | `isDisabled` | `boolean` | Whether the button is disabled |
+
+## Related Components
+
+<RelatedComponents component="togglebutton" />
@@ -8,21 +8,17 @@ links:
  storybook: Components/Collections/Dropdown
 ---

-## Import
+## Usage

 ```tsx
 import { Dropdown } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="dropdown-default"
 />

-### Anatomy
-
-Import the Dropdown component and access all parts using dot notation.
+## Anatomy

 ```tsx
 import { Dropdown, Button, Label, Description, Header, Kbd, Separator } from '@heroui/react';
@@ -62,35 +58,7 @@ export default () => (
 )
 ```

-### With Single Selection
-
-<ComponentPreview
-  name="dropdown-with-single-selection"
-/>
-
-### Single With Custom Indicator
-
-<ComponentPreview
-  name="dropdown-single-with-custom-indicator"
-/>
-
-### With Multiple Selection
-
-<ComponentPreview
-  name="dropdown-with-multiple-selection"
-/>
-
-### With Section Level Selection
-
-<ComponentPreview
-  name="dropdown-with-section-level-selection"
-/>
-
-### With Keyboard Shortcuts
-
-<ComponentPreview
-  name="dropdown-with-keyboard-shortcuts"
-/>
+## Examples

 ### With Icons

@@ -98,40 +66,28 @@ export default () => (
  name="dropdown-with-icons"
 />

-### Long Press Trigger
-
-<ComponentPreview
-  name="dropdown-long-press-trigger"
-/>
-
 ### With Descriptions

 <ComponentPreview
  name="dropdown-with-descriptions"
 />

-### With Sections
-
-<ComponentPreview
-  name="dropdown-with-sections"
-/>
-
 ### With Disabled Items

 <ComponentPreview
  name="dropdown-with-disabled-items"
 />

-### With Submenus
+### With Sections

 <ComponentPreview
-  name="dropdown-with-submenus"
+  name="dropdown-with-sections"
 />

-### With Custom Submenu Indicator
+### With Multiple Selection

 <ComponentPreview
-  name="dropdown-with-custom-submenu-indicator"
+  name="dropdown-with-multiple-selection"
 />

 ### Controlled
@@ -146,43 +102,64 @@ export default () => (
  name="dropdown-controlled-open-state"
 />

+### With Single Selection
+
+<ComponentPreview
+  name="dropdown-with-single-selection"
+/>
+
+### Single With Custom Indicator
+
+<ComponentPreview
+  name="dropdown-single-with-custom-indicator"
+/>
+
+### With Section Level Selection
+
+<ComponentPreview
+  name="dropdown-with-section-level-selection"
+/>
+
+### With Keyboard Shortcuts
+
+<ComponentPreview
+  name="dropdown-with-keyboard-shortcuts"
+/>
+
+### With Submenus
+
+<ComponentPreview
+  name="dropdown-with-submenus"
+/>
+
+### With Custom Submenu Indicator
+
+<ComponentPreview
+  name="dropdown-with-custom-submenu-indicator"
+/>
+
 ### Custom Trigger

 <ComponentPreview
  name="dropdown-custom-trigger"
 />

-<RelatedComponents component="dropdown" />
- 
-## Styling
+### Long Press Trigger

-### Passing Tailwind CSS classes
+<ComponentPreview
+  name="dropdown-long-press-trigger"
+/>

-```tsx
-import { Dropdown, Button } from '@heroui/react';
+## Customization

-function CustomDropdown() {
-  return (
-    <Dropdown>
-      <Dropdown.Trigger className="rounded-lg border p-2 bg-surface">
-        <Button>Actions</Button>
-      </Dropdown.Trigger>
-      <Dropdown.Popover className="min-w-[200px]">
-        <Dropdown.Menu>
-          <Dropdown.Item id="item-1" textValue="Item 1" className="hover:bg-surface-secondary">
-            Item 1
-          </Dropdown.Item>
-        </Dropdown.Menu>
-      </Dropdown.Popover>
-    </Dropdown>
-  );
-}
-```
+### Tailwind CSS

-### Customizing the component classes
+<ComponentPreview name="dropdown-custom-styles" />
+
+### Global CSS

 To customize the Dropdown component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -204,19 +181,21 @@ To customize the Dropdown component classes, you can use the `@layer components`
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The Dropdown component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/dropdown.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.dropdown` - Base dropdown container
 - `.dropdown__trigger` - The button or element that triggers the dropdown
 - `.dropdown__popover` - The popover container
 - `.dropdown__menu` - The menu container inside the popover

-#### State Classes
+#### State Classes [!toc]
 - `.dropdown__trigger[data-focus-visible="true"]` - Focused trigger state
 - `.dropdown__trigger[data-disabled="true"]` - Disabled trigger state
 - `.dropdown__trigger[data-pressed="true"]` - Pressed trigger state
@@ -229,11 +208,11 @@ The Dropdown component uses these CSS classes ([View source styles](https://gith

 The Dropdown component uses Menu, MenuItem, and MenuSection as base components. These classes are also available for customization:

-#### Menu Classes
+#### Menu Classes [!toc]
 - `.menu` - Base menu container ([menu.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu.css))
  - `[data-slot="separator"]` - Separator elements within the menu

-#### MenuItem Classes
+#### MenuItem Classes [!toc]
 - `.menu-item` - Base menu item container ([menu-item.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-item.css))
 - `.menu-item__indicator` - Selection indicator (checkmark or dot)
  - `[data-slot="menu-item-indicator--checkmark"]` - Checkmark indicator SVG
@@ -242,7 +221,7 @@ The Dropdown component uses Menu, MenuItem, and MenuSection as base components.
 - `.menu-item--default` - Default variant styling
 - `.menu-item--danger` - Danger variant styling

-#### MenuItem State Classes
+#### MenuItem State Classes [!toc]
 - `.menu-item[data-focus-visible="true"]` - Focused item state (keyboard focus)
 - `.menu-item[data-focus="true"]` - Focused item state
 - `.menu-item[data-pressed]` - Pressed item state
@@ -255,7 +234,7 @@ The Dropdown component uses Menu, MenuItem, and MenuSection as base components.
 - `.menu-item[aria-checked="true"]` - Checked item (ARIA)
 - `.menu-item[aria-selected="true"]` - Selected item (ARIA)

-#### MenuSection Classes
+#### MenuSection Classes [!toc]
 - `.menu-section` - Base menu section container ([menu-section.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-section.css))

 ### Interactive States
@@ -270,7 +249,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 ## API Reference

-### Dropdown Props
+### Dropdown

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -281,7 +260,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `ReactNode` | - | Dropdown content |

-### Dropdown.Trigger Props
+### Dropdown.Trigger

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -290,7 +269,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 All [Button](https://react-spectrum.adobe.com/react-aria/Button.html) props are also supported when using a Button as the trigger.

-### Dropdown.Popover Props
+### Dropdown.Popover

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -300,7 +279,7 @@ All [Button](https://react-spectrum.adobe.com/react-aria/Button.html) props are

 All [Popover](https://react-spectrum.adobe.com/react-aria/Popover.html) props are also supported.

-### Dropdown.Menu Props
+### Dropdown.Menu

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -315,7 +294,7 @@ All [Popover](https://react-spectrum.adobe.com/react-aria/Popover.html) props ar

 All [Menu](https://react-spectrum.adobe.com/react-aria/Menu.html#menu) props are also supported.

-### Dropdown.Section Props
+### Dropdown.Section

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -329,7 +308,7 @@ All [Menu](https://react-spectrum.adobe.com/react-aria/Menu.html#menu) props are

 All [MenuSection](https://react-spectrum.adobe.com/react-aria/Menu.html#menusection) props are also supported.

-### Dropdown.Item Props
+### Dropdown.Item

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -341,7 +320,7 @@ All [MenuSection](https://react-spectrum.adobe.com/react-aria/Menu.html#menusect

 All [MenuItem](https://react-spectrum.adobe.com/react-aria/Menu.html#menuitem) props are also supported.

-### Dropdown.ItemIndicator Props
+### Dropdown.ItemIndicator

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -356,14 +335,14 @@ When using a render function, these values are provided:
 | `isSelected` | `boolean` | Whether the item is selected |
 | `isIndeterminate` | `boolean` | Whether the item is in an indeterminate state |

-### Dropdown.SubmenuIndicator Props
+### Dropdown.SubmenuIndicator

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `ReactNode` | - | Custom indicator content |

-### Dropdown.SubmenuTrigger Props
+### Dropdown.SubmenuTrigger

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -372,7 +351,7 @@ When using a render function, these values are provided:

 All [SubmenuTrigger](https://react-spectrum.adobe.com/react-aria/Menu.html#submenutrigger) props are also supported.

-### RenderProps
+### Render Props

 When using render functions with Dropdown.Item, these values are provided:

@@ -527,3 +506,6 @@ The Dropdown component implements the ARIA menu pattern and provides:

 For more information, see the [React Aria Menu documentation](https://react-spectrum.adobe.com/react-aria/Menu.html#menu).

+## Related Components
+
+<RelatedComponents component="dropdown" />
@@ -8,21 +8,17 @@ links:
  storybook: Components/Collections/ListBox
 ---

-## Import
+## Usage

 ```tsx
 import { ListBox } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="list-box-default"
 />

-### Anatomy
-
-Import the ListBox component and access all parts using dot notation.
+## Anatomy

 ```tsx
 import { ListBox, Label, Description, Header } from '@heroui/react';
@@ -44,6 +40,14 @@ export default () => (
 )
 ```

+## Examples
+
+### With Disabled Items
+
+<ComponentPreview
+  name="list-box-with-disabled-items"
+/>
+
 ### With Sections

 <ComponentPreview
@@ -56,30 +60,12 @@ export default () => (
  name="list-box-multi-select"
 />

-### With Disabled Items
-
-<ComponentPreview
-  name="list-box-with-disabled-items"
-/>
-
-### Custom Check Icon
-
-<ComponentPreview
-  name="list-box-custom-check-icon"
-/>
-
 ### Controlled

 <ComponentPreview
  name="list-box-controlled"
 />

-### Custom Render Function
-
-<ComponentPreview
-  name="list-box-custom-render-function"
-/>
-
 ### Virtualization

 ListBox supports virtualization through [Virtualizer](https://react-aria.adobe.com/Virtualizer), enabling efficient rendering of large datasets by displaying only the rows visible within the viewport.
@@ -88,30 +74,28 @@ ListBox supports virtualization through [Virtualizer](https://react-aria.adobe.c
  name="list-box-virtualization"
 />

-<RelatedComponents component="list-box" />
+### Custom Check Icon

-## Styling
+<ComponentPreview
+  name="list-box-custom-check-icon"
+/>

-### Passing Tailwind CSS classes
+### Render Function

-```tsx
-import { ListBox } from '@heroui/react';
+<ComponentPreview
+  name="list-box-render-function"
+/>

-function CustomListBox() {
-  return (
-    <ListBox className="border rounded-lg p-2 bg-surface">
-      <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
-        Item 1
-      </ListBox.Item>
-    </ListBox>
-  );
-}
-```
+## Customization

-### Customizing the component classes
+### Tailwind CSS
+
+<ComponentPreview name="list-box-custom-styles" />
+
+### Global CSS

 To customize the ListBox component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -133,25 +117,27 @@ To customize the ListBox component classes, you can use the `@layer components`
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The ListBox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/list-box.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.list-box` - Base listbox container
 - `.list-box-item` - Individual listbox item
 - `.list-box-item__indicator` - Selection indicator icon
 - `.list-box-section` - Section container for grouping items

-#### Variant Classes
+#### Variant Classes [!toc]
 - `.list-box--default` - Default variant styling
 - `.list-box--danger` - Danger variant styling
 - `.list-box-item--default` - Default item variant
 - `.list-box-item--danger` - Danger item variant

-#### State Classes
+#### State Classes [!toc]
 - `.list-box-item[data-selected="true"]` - Selected item state
 - `.list-box-item[data-focus-visible="true"]` - Focused item state
 - `.list-box-item[data-disabled="true"]` - Disabled item state
@@ -168,7 +154,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 ## API Reference

-### ListBox Props
+### ListBox

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -185,7 +171,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 | `children` | `ReactNode` | - | ListBox items and sections |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ListBoxRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### ListBox.Item Props
+### ListBox.Item

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -197,21 +183,21 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 | `children` | `ReactNode \| RenderFunction` | - | Item content or render function |
 | `render` | `(props: DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> \| React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], renderProps: ListBoxItemRenderProps) => ReactElement` | - | Overrides the default DOM element with a custom render function.|

-### ListBox.ItemIndicator Props
+### ListBox.ItemIndicator

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `ReactNode \| RenderFunction` | - | Custom indicator content or render function |

-### ListBox.Section Props
+### ListBox.Section

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `ReactNode` | - | Section content including Header and Items |

-### RenderProps
+### Render Props

 When using render functions with ListBox.Item or ListBox.ItemIndicator, these values are provided:

@@ -327,3 +313,6 @@ The ListBox component implements the ARIA listbox pattern and provides:

 For more information, see the [React Aria ListBox documentation](https://react-spectrum.adobe.com/react-aria/ListBox.html).

+## Related Components
+
+<RelatedComponents component="list-box" />
@@ -8,19 +8,17 @@ links:
  storybook: Components/Collections/TagGroup
 ---

-## Import
+## Usage

 ```tsx
 import { TagGroup } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="tag-group-basic"
 />

-### Anatomy
+## Anatomy

 ```tsx
 import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';
@@ -39,6 +37,8 @@ export default () => (
 )
 ```

+## Examples
+
 ### Sizes

 <ComponentPreview
@@ -75,6 +75,12 @@ export default () => (
  name="tag-group-with-error-message"
 />

+### With List Data
+
+<ComponentPreview
+  name="tag-group-with-list-data"
+/>
+
 ### With Prefix

 <ComponentPreview
@@ -87,45 +93,22 @@ export default () => (
  name="tag-group-with-remove-button"
 />

-### With List Data
+### Render Function

 <ComponentPreview
-  name="tag-group-with-list-data"
+  name="tag-group-render-function"
 />

-### Custom Render Function
+## Customization

-<ComponentPreview
-  name="tag-group-custom-render-function"
-/>
+### Tailwind CSS

-<RelatedComponents component="taggroup" />
+<ComponentPreview name="tag-group-custom-styles" />

-## Styling
-
-### Passing Tailwind CSS classes
-
-```tsx
-import { TagGroup, Tag, Label } from '@heroui/react';
-
-function CustomTagGroup() {
-  return (
-    <TagGroup className="w-full">
-      <Label>Categories</Label>
-      <TagGroup.List className="gap-2">
-        <Tag className="rounded-lg px-4 py-2 font-bold">
-          Custom Styled
-        </Tag>
-      </TagGroup.List>
-    </TagGroup>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the TagGroup component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -147,32 +130,34 @@ To customize the TagGroup component classes, you can use the `@layer components`
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The TagGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag-group.css) and [tag.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.tag-group` - Base tag group container
 - `.tag-group__list` - Container for the list of tags
 - `.tag` - Base tag styles
 - `.tag__remove-button` - Remove button trigger

-#### Slot Classes
+#### Slot Classes [!toc]
 - `.tag-group [slot="description"]` - Description slot styles
 - `.tag-group [slot="errorMessage"]` - ErrorMessage slot styles

-#### Size Classes
+#### Size Classes [!toc]
 - `.tag--sm` - Small size tag
 - `.tag--md` - Medium size tag (default)
 - `.tag--lg` - Large size tag

-#### Variant Classes
+#### Variant Classes [!toc]
 - `.tag--default` - Default variant
 - `.tag--surface` - Surface variant with surface background

-#### State Classes
+#### State Classes [!toc]
 - `.tag[data-selected="true"]` - Selected tag state
 - `.tag[data-disabled="true"]` - Disabled tag state
 - `.tag[data-hovered="true"]` - Hovered tag state
@@ -191,7 +176,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 ## API Reference

-### TagGroup Props
+### TagGroup

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -208,7 +193,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 | `children` | `ReactNode \| RenderFunction` | - | TagGroup content or render function |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | Overrides the default DOM element with a custom render function.|

-### TagGroup.List Props
+### TagGroup.List

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -218,7 +203,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 | `children` | `ReactNode \| RenderFunction` | - | TagList content or render function |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagListRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### Tag Props
+### Tag

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -231,7 +216,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 **Note**: `size`, `variant` are inherited from the parent `TagGroup` component and cannot be set directly on individual `Tag` components.

-### Tag.RemoveButton Props
+### Tag.RemoveButton

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -284,7 +269,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 </Tag>
 ```

-### RenderProps
+### Render Props

 When using render functions with TagGroup.List, these values are provided:

@@ -296,3 +281,7 @@ When using render functions with TagGroup.List, these values are provided:
 | `isPressed` | `boolean` | Whether the tag is pressed |
 | `isFocused` | `boolean` | Whether the tag is focused |
 | `isFocusVisible` | `boolean` | Whether the tag has keyboard focus |
+
+## Related Components
+
+<RelatedComponents component="taggroup" />
@@ -9,19 +9,17 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { ColorArea } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="color-area-basic"
 />

-### Anatomy
+## Anatomy

 ```tsx
 import { ColorArea } from '@heroui/react';
@@ -33,19 +31,14 @@ export default () => (
 );
 ```

+## Examples
+
 ### With Dots

 <ComponentPreview
  name="color-area-with-dots"
 />

-### Controlled
-
-<ComponentPreview
-  name="color-area-controlled"
-/>
-
-
 ### Color Space & Channels

 Use `colorSpace` to set the color space (RGB, HSL, HSB) and `xChannel`/`yChannel` props to customize which color channels are displayed on each axis.
@@ -60,34 +53,28 @@ Use `colorSpace` to set the color space (RGB, HSL, HSB) and `xChannel`/`yChannel
  name="color-area-disabled"
 />

-### Custom Render Function
+### Controlled

 <ComponentPreview
-  name="color-area-custom-render-function"
+  name="color-area-controlled"
 />

-<RelatedComponents component="color-area" />
+### Render Function

-## Styling
+<ComponentPreview
+  name="color-area-render-function"
+/>

-### Passing Tailwind CSS classes
+## Customization

-```tsx
-import { ColorArea } from '@heroui/react';
+### Tailwind CSS

-function CustomColorArea() {
-  return (
-    <ColorArea className="max-w-72 rounded-3xl">
-      <ColorArea.Thumb />
-    </ColorArea>
-  );
-}
-```
+<ComponentPreview name="color-area-custom-styles" />

-### Customizing the component classes
+### Global CSS

 To customize the ColorArea component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -101,17 +88,19 @@ To customize the ColorArea component classes, you can use the `@layer components
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The ColorArea component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-area.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.color-area` - Base styles with gradient background and inner shadow
 - `.color-area--show-dots` - Adds dot grid overlay for precision picking

-#### Element Classes
+#### Element Classes [!toc]
 - `.color-area__thumb` - Draggable thumb indicator

 ### Interactive States
@@ -124,7 +113,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 ## API Reference

-### ColorArea Props
+### ColorArea

 Inherits from [React Aria ColorArea](https://react-spectrum.adobe.com/react-aria/ColorArea.html).

@@ -142,10 +131,14 @@ Inherits from [React Aria ColorArea](https://react-spectrum.adobe.com/react-aria
 | `className` | `string` | - | Additional CSS classes |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorAreaRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### ColorArea.Thumb Props
+### ColorArea.Thumb

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |
 | `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | Inline styles or render props function |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorThumbRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+## Related Components
+
+<RelatedComponents component="color-area" />
@@ -8,17 +8,15 @@ links:
  storybook: Components/Colors/ColorField
 ---

-## Import
+## Usage

 ```tsx
 import { ColorField, parseColor } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview name="color-field-basic" />

-### Anatomy
+## Anatomy

 ```tsx
 import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
@@ -40,6 +38,23 @@ export default () => (

 > **ColorField** combines label, color input, description, and error into a single accessible component.

+## Examples
+
+### Variants
+
+The ColorField.Group component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="color-field-variants" />
+
+### On Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on ColorField.Group to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="color-field-on-surface" />
+
 ### With Description

 <ComponentPreview name="color-field-with-description" />
@@ -48,6 +63,14 @@ export default () => (

 <ComponentPreview name="color-field-required" />

+### Disabled State
+
+<ComponentPreview name="color-field-disabled" />
+
+### Full Width
+
+<ComponentPreview name="color-field-full-width" />
+
 ### Validation

 Use `isInvalid` together with `FieldError` to surface validation messages.
@@ -66,71 +89,25 @@ Control the value to synchronize with other components or state management.

 <ComponentPreview name="color-field-controlled" />

-### Disabled State
-
-<ComponentPreview name="color-field-disabled" />
-
-### Full Width
-
-<ComponentPreview name="color-field-full-width" />
-
-### Variants
-
-The ColorField.Group component supports two visual variants:
-
- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
-
-<ComponentPreview name="color-field-variants" />
-
-### On Surface
-
-When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on ColorField.Group to apply the lower emphasis variant suitable for surface backgrounds.
-
-<ComponentPreview name="color-field-on-surface" />
-
 ### Form Example

 Complete form example with validation and submission handling.

 <ComponentPreview name="color-field-form-example" />

-### Custom Render Function
+### Render Function

 <ComponentPreview
-  name="color-field-custom-render-function"
+  name="color-field-render-function"
 />

-<RelatedComponents component="colorfield" />
+## Customization

-## Styling
+### Tailwind CSS

-### Passing Tailwind CSS classes
+<ComponentPreview name="color-field-custom-styles" />

-```tsx
-import {ColorField, Label, ColorSwatch, Description} from '@heroui/react';
-
-function CustomColorField() {
-  return (
-    <ColorField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
-      <Label className="text-sm font-semibold text-default-700">
-        Brand Color
-      </Label>
-      <ColorField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
-        <ColorField.Prefix>
-          <ColorSwatch color="#3B82F6" />
-        </ColorField.Prefix>
-        <ColorField.Input />
-      </ColorField.Group>
-      <Description className="text-xs text-default-500">
-        Select your brand's primary color.
-      </Description>
-    </ColorField>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 ColorField has minimal default styling. Override the `.color-field` class to customize the container styling.

@@ -157,6 +134,10 @@ ColorField has minimal default styling. Override the `.color-field` class to cus
 }
 ```

+## Styling Reference
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
 ### CSS Classes

 - `.color-field` – Root container with minimal styling (`flex flex-col gap-1`)
@@ -174,7 +155,7 @@ ColorField automatically manages these data attributes based on its state:

 ## API Reference

-### ColorField Props
+### ColorField

 ColorField inherits all props from React Aria's [ColorField](https://react-aria.adobe.com/ColorField.md) component.

@@ -294,7 +275,7 @@ const rgb = color.toString('rgb'); // "rgb(59, 130, 246)"
 </ColorField>
 ```

-### ColorFieldRenderProps
+### Render Props

 When using render props with `className`, `style`, or `children`, these values are available:

@@ -308,7 +289,7 @@ When using render props with `className`, `style`, or `children`, these values a
 | `isFocusWithin` | `boolean` | Whether any child element is focused. |
 | `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |

-### ColorField.Group Props
+### ColorField.Group

 ColorField.Group accepts all props from React Aria's `Group` component plus the following:

@@ -319,7 +300,7 @@ ColorField.Group accepts all props from React Aria's `Group` component plus the
 | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, GroupRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### ColorField.Input Props
+### ColorField.Input

 ColorField.Input accepts all props from React Aria's `Input` component plus the following:

@@ -328,7 +309,7 @@ ColorField.Input accepts all props from React Aria's `Input` component plus the
 | `className` | `string` | - | Tailwind classes merged with the component styles. |
 | `placeholder` | `string` | - | Placeholder text shown when empty. |

-### ColorField.Prefix Props
+### ColorField.Prefix

 ColorField.Prefix accepts standard HTML `div` attributes:

@@ -337,7 +318,7 @@ ColorField.Prefix accepts standard HTML `div` attributes:
 | `className` | `string` | - | Tailwind classes merged with the component styles. |
 | `children` | `ReactNode` | - | Content to display in the prefix slot. |

-### ColorField.Suffix Props
+### ColorField.Suffix

 ColorField.Suffix accepts standard HTML `div` attributes:

@@ -401,3 +382,7 @@ The base classes power every instance. Override them once with `@layer component
 - **Focus Within**: `[data-focus-within="true"]` or `:focus-within`
 - **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
 - **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]`
+
+## Related Components
+
+<RelatedComponents component="colorfield" />
@@ -9,7 +9,7 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import {
@@ -22,13 +22,11 @@ import {
 } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="color-picker-basic"
 />

-### Anatomy
+## Anatomy

 The ColorPicker is a composable component that combines multiple color components:

@@ -55,6 +53,8 @@ export default () => (
 );
 ```

+## Examples
+
 ### Controlled

 <ComponentPreview
@@ -83,36 +83,16 @@ Use multiple `ColorSlider` components to adjust each channel of a color value.
  name="color-picker-with-sliders"
 />

-<RelatedComponents component="color-picker" />
+## Customization

-## Styling
+### Tailwind CSS

-### Passing Tailwind CSS classes
+<ComponentPreview name="color-picker-custom-styles" />

-```tsx
-import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
-
-function CustomColorPicker() {
-  return (
-    <ColorPicker defaultValue="#0485F7">
-      <ColorPicker.Trigger className="gap-4">
-        <ColorSwatch className="rounded-lg" />
-        <Label>Pick a color</Label>
-      </ColorPicker.Trigger>
-      <ColorPicker.Popover className="p-4 rounded-xl">
-        <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness">
-          <ColorArea.Thumb />
-        </ColorArea>
-      </ColorPicker.Popover>
-    </ColorPicker>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the ColorPicker component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -130,13 +110,15 @@ To customize the ColorPicker component classes, you can use the `@layer componen
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The ColorPicker component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-picker.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.color-picker` - Base container
 - `.color-picker__trigger` - Trigger button
 - `.color-picker__popover` - Popover container
@@ -150,7 +132,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 ## API Reference

-### ColorPicker Props
+### ColorPicker

 Inherits from [React Aria ColorPicker](https://react-spectrum.adobe.com/react-aria/ColorPicker.html).

@@ -162,14 +144,14 @@ Inherits from [React Aria ColorPicker](https://react-spectrum.adobe.com/react-ar
 | `children` | `React.ReactNode` | - | Content of the color picker (Trigger, Popover, etc.) |
 | `className` | `string` | - | Additional CSS classes |

-### ColorPicker.Trigger Props
+### ColorPicker.Trigger

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `children` | `React.ReactNode \| ((renderProps) => React.ReactNode)` | - | Trigger content or render prop |
 | `className` | `string` | - | Additional CSS classes |

-### ColorPicker.Popover Props
+### ColorPicker.Popover

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -199,3 +181,7 @@ import { parseColor } from 'react-aria-components';
 const color = parseColor('#ff0000');
 const hslColor = parseColor('hsl(0, 100%, 50%)');
 ```
+
+## Related Components
+
+<RelatedComponents component="color-picker" />
@@ -1,6 +1,7 @@
 ---
 title: ColorSlider
 description: A color slider allows users to adjust an individual channel of a color value
+
 links:
  rac: ColorSlider
  source: color-slider/color-slider.tsx
@@ -9,21 +10,17 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { ColorSlider, Label } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="color-slider-basic"
 />

-### Anatomy
-
-Import the ColorSlider component and access all parts using dot notation.
+## Anatomy

 ```tsx
 import { ColorSlider, Label } from '@heroui/react';
@@ -38,11 +35,7 @@ export default () => (
  </ColorSlider>
 )
 ```
-### Vertical
-
-<ComponentPreview
-  name="color-slider-vertical"
-/>
+## Examples

 ### Disabled

@@ -50,6 +43,12 @@ export default () => (
  name="color-slider-disabled"
 />

+### Vertical
+
+<ComponentPreview
+  name="color-slider-vertical"
+/>
+
 ### Controlled

 <ComponentPreview
@@ -80,38 +79,22 @@ You can also use RGB color space with red, green, and blue channels.
  name="color-slider-rgb-channels"
 />

-### Custom Render Function
+### Render Function

 <ComponentPreview
-  name="color-slider-custom-render-function"
+  name="color-slider-render-function"
 />

-<RelatedComponents component="color-slider" />
+## Customization

-## Styling
+### Tailwind CSS

-### Passing Tailwind CSS classes
+<ComponentPreview name="color-slider-custom-styles" />

-```tsx
-import { ColorSlider, Label } from '@heroui/react';
-
-function CustomColorSlider() {
-  return (
-    <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)" className="w-full">
-      <Label>Hue</Label>
-      <ColorSlider.Output className="text-muted text-sm" />
-      <ColorSlider.Track className="h-6 rounded-full">
-        <ColorSlider.Thumb className="size-5 rounded-full border-2 border-white" />
-      </ColorSlider.Track>
-    </ColorSlider>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the ColorSlider component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -133,19 +116,21 @@ To customize the ColorSlider component classes, you can use the `@layer componen
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The ColorSlider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-slider.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.color-slider` - Base slider container
 - `.color-slider__output` - Output element displaying current value
 - `.color-slider__track` - Track element with color gradient
 - `.color-slider__thumb` - Thumb element showing current color

-#### State Classes
+#### State Classes [!toc]
 - `.color-slider[data-disabled="true"]` - Disabled slider state
 - `.color-slider[data-orientation="vertical"]` - Vertical orientation
 - `.color-slider__thumb[data-dragging="true"]` - Thumb being dragged
@@ -163,7 +148,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 ## API Reference

-### ColorSlider Props
+### ColorSlider

 Inherits from [React Aria ColorSlider](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).

@@ -183,14 +168,14 @@ Inherits from [React Aria ColorSlider](https://react-spectrum.adobe.com/react-ar
 | `children` | `ReactNode \| RenderFunction` | - | Slider content or render function |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSliderRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### ColorSlider.Output Props
+### ColorSlider.Output

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `ReactNode \| RenderFunction` | - | Output content or render function |

-### ColorSlider.Track Props
+### ColorSlider.Track

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -198,7 +183,7 @@ Inherits from [React Aria ColorSlider](https://react-spectrum.adobe.com/react-ar
 | `style` | `CSSProperties \| RenderFunction` | - | Inline styles or render function |
 | `children` | `ReactNode \| RenderFunction` | - | Track content or render function |

-### ColorSlider.Thumb Props
+### ColorSlider.Thumb

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -206,7 +191,7 @@ Inherits from [React Aria ColorSlider](https://react-spectrum.adobe.com/react-ar
 | `style` | `CSSProperties \| RenderFunction` | - | Inline styles or render function |
 | `children` | `ReactNode \| RenderFunction` | - | Thumb content or render function |

-### RenderProps
+### Render Props

 When using render functions, these values are provided:

@@ -229,3 +214,7 @@ The ColorSlider component implements the ARIA slider pattern and provides:
 - Internationalization support with locale-aware value formatting

 For more information, see the [React Aria ColorSlider documentation](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).
+
+## Related Components
+
+<RelatedComponents component="color-slider" />
@@ -9,21 +9,17 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { ColorSwatchPicker, parseColor } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="color-swatch-picker-basic"
 />

-### Anatomy
-
-Import the ColorSwatchPicker component and access all parts using dot notation.
+## Anatomy

 ```tsx
 import { ColorSwatchPicker } from '@heroui/react';
@@ -46,6 +42,8 @@ export default () => (
 );
 ```

+## Examples
+
 ### Variants

 <ComponentPreview
@@ -58,6 +56,12 @@ export default () => (
  name="color-swatch-picker-sizes"
 />

+### Disabled
+
+<ComponentPreview
+  name="color-swatch-picker-disabled"
+/>
+
 ### Stack Layout

 <ComponentPreview
@@ -76,54 +80,28 @@ export default () => (
  name="color-swatch-picker-controlled"
 />

-### Disabled
-
-<ComponentPreview
-  name="color-swatch-picker-disabled"
-/>
-
 ### Custom Indicator

 <ComponentPreview
  name="color-swatch-picker-custom-indicator"
 />

-### Custom Render Function
+### Render Function

 <ComponentPreview
-  name="color-swatch-picker-custom-render-function"
+  name="color-swatch-picker-render-function"
 />

-<RelatedComponents component="color-swatch-picker" />
+## Customization

+### Tailwind CSS

-## Styling
+<ComponentPreview name="color-swatch-picker-custom-styles" />

-### Passing Tailwind CSS classes
-
-You can customize the ColorSwatchPicker using className props:
-
-```tsx
-import { ColorSwatchPicker } from '@heroui/react';
-
-function CustomColorSwatchPicker() {
-  return (
-    <ColorSwatchPicker className="gap-4">
-      <ColorSwatchPicker.Item color="#F43F5E" className="shadow-lg">
-        <ColorSwatchPicker.Swatch />
-      </ColorSwatchPicker.Item>
-      <ColorSwatchPicker.Item color="#D946EF">
-        <ColorSwatchPicker.Swatch />
-      </ColorSwatchPicker.Item>
-    </ColorSwatchPicker>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the ColorSwatchPicker component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -141,29 +119,31 @@ To customize the ColorSwatchPicker component classes, you can use the `@layer co
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The ColorSwatchPicker component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch-picker.css)):

-#### Base & Structure
+#### Base & Structure [!toc]
 - `.color-swatch-picker` - Base container (flex layout)
 - `.color-swatch-picker__item` - Individual swatch item wrapper
 - `.color-swatch-picker__swatch` - The color swatch visual element

-#### Size Classes
+#### Size Classes [!toc]
 - `.color-swatch-picker--xs` - Extra small (16px)
 - `.color-swatch-picker--sm` - Small (24px)
 - `.color-swatch-picker--md` - Medium (32px, default)
 - `.color-swatch-picker--lg` - Large (36px)
 - `.color-swatch-picker--xl` - Extra large (40px)

-#### Shape Variants
+#### Shape Variants [!toc]
 - `.color-swatch-picker--circle` - Circle shape (default)
 - `.color-swatch-picker--square` - Square shape with rounded corners

-#### Layout Classes
+#### Layout Classes [!toc]
 - `.color-swatch-picker--grid` - Horizontal wrapping layout (default)
 - `.color-swatch-picker--stack` - Vertical stacked layout

@@ -178,7 +158,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 ## API Reference

-### ColorSwatchPicker Props
+### ColorSwatchPicker

 Inherits from [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/react-aria/ColorSwatchPicker.html).

@@ -194,7 +174,7 @@ Inherits from [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/re
 | `children` | `React.ReactNode` | - | ColorSwatchPicker.Item elements |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### ColorSwatchPicker.Item Props
+### ColorSwatchPicker.Item

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -204,7 +184,7 @@ Inherits from [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/re
 | `children` | `React.ReactNode` | - | ColorSwatchPicker.Swatch element |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerItemRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### ColorSwatchPicker.Swatch Props
+### ColorSwatchPicker.Swatch

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -226,3 +206,7 @@ const green = parseColor('rgb(0, 255, 0)');
 // Parse HSL
 const blue = parseColor('hsl(240, 100%, 50%)');
 ```
+
+## Related Components
+
+<RelatedComponents component="color-swatch-picker" />
@@ -8,18 +8,18 @@ links:
  storybook: Components/Colors/ColorSwatch
 ---

-## Import
+## Usage

 ```tsx
 import { ColorSwatch } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="color-swatch-basic"
 />

+## Examples
+
 ### Sizes

 <ComponentPreview
@@ -38,12 +38,12 @@ import { ColorSwatch } from '@heroui/react';
  name="color-swatch-transparency"
 />

-### Custom Styles with Render Props
+### Render Function

 You can use the `style` render props to access the color value and create custom visual effects.

 <ComponentPreview
-  name="color-swatch-custom-styles"
+  name="color-swatch-render-function"
 />

 ### Accessibility
@@ -54,35 +54,16 @@ Use `colorName` to provide a custom accessible name for the color, and `aria-lab
  name="color-swatch-accessibility"
 />

-### Custom Render Function
+## Customization

-<ComponentPreview
-  name="color-swatch-custom-render-function"
-/>
+### Tailwind CSS

-<RelatedComponents component="color-swatch" />
+<ComponentPreview name="color-swatch-custom-styles" />

-## Styling
-
-### Passing Tailwind CSS classes
-
-```tsx
-import {ColorSwatch} from '@heroui/react';
-
-function CustomColorSwatch() {
-  return (
-    <ColorSwatch
-      className="size-12 rounded-lg"
-      color="#0485F7"
-    />
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the ColorSwatch component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -92,20 +73,22 @@ To customize the ColorSwatch component classes, you can use the `@layer componen
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The ColorSwatch component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.color-swatch` - Base swatch styles with checkered background for transparency

-#### Shape Classes
+#### Shape Classes [!toc]
 - `.color-swatch--circle` - Circular shape (default)
 - `.color-swatch--square` - Square shape with rounded corners

-#### Size Classes
+#### Size Classes [!toc]
 - `.color-swatch--xs` - Extra small (16px)
 - `.color-swatch--sm` - Small (24px)
 - `.color-swatch--md` - Medium (32px, default)
@@ -114,7 +97,7 @@ The ColorSwatch component uses these CSS classes ([View source styles](https://g

 ## API Reference

-### ColorSwatch Props
+### ColorSwatch

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -144,3 +127,7 @@ The `color` object provides methods like:
 - `color.toString("css")` - Returns CSS color string
 - `color.toString("hex")` - Returns hex color string
 - `color.getChannelValue("alpha")` - Returns alpha channel value
+
+## Related Components
+
+<RelatedComponents component="color-swatch" />
@@ -1,6 +1,7 @@
 ---
 title: Slider
 description: A slider allows a user to select one or more values within a range
+
 links:
  rac: Slider
  source: slider/slider.tsx
@@ -8,21 +9,17 @@ links:
  storybook: Components/Controls/Slider
 ---

-## Import
+## Usage

 ```tsx
 import { Slider } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="slider-default"
 />

-### Anatomy
-
-Import the Slider component and access all parts using dot notation.
+## Anatomy

 ```tsx
 import { Slider, Label } from '@heroui/react';
@@ -39,6 +36,14 @@ export default () => (
 )
 ```

+## Examples
+
+### Disabled
+
+<ComponentPreview
+  name="slider-disabled"
+/>
+
 ### Range Slider Anatomy

 ```tsx
@@ -74,45 +79,22 @@ export default () => (
  name="slider-range"
 />

-### Disabled
+### Render Function

 <ComponentPreview
-  name="slider-disabled"
+  name="slider-render-function"
 />

-### Custom Render Function
+## Customization

-<ComponentPreview
-  name="slider-custom-render-function"
-/>
+### Tailwind CSS

-<RelatedComponents component="slider" />
+<ComponentPreview name="slider-custom-styles" />

-## Styling
-
-### Passing Tailwind CSS classes
-
-```tsx
-import { Slider, Label } from '@heroui/react';
-
-function CustomSlider() {
-  return (
-    <Slider className="w-full">
-      <Label>Volume</Label>
-      <Slider.Output className="text-muted-fg text-sm" />
-      <Slider.Track className="h-2 rounded-full bg-surface-secondary">
-        <Slider.Fill className="bg-accent" />
-        <Slider.Thumb className="size-4 rounded-full bg-accent" />
-      </Slider.Track>
-    </Slider>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the Slider component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -138,20 +120,22 @@ To customize the Slider component classes, you can use the `@layer components` d
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The Slider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/slider.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.slider` - Base slider container
 - `.slider__output` - Output element displaying current value(s)
 - `.slider-track` - Track element containing fill and thumbs
 - `.slider-fill` - Fill element showing selected range
 - `.slider-thumb` - Individual thumb element

-#### State Classes
+#### State Classes [!toc]
 - `.slider[data-disabled="true"]` - Disabled slider state
 - `.slider[data-orientation="vertical"]` - Vertical orientation
 - `.slider-thumb[data-dragging="true"]` - Thumb being dragged
@@ -171,7 +155,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili

 ## API Reference

-### Slider Props
+### Slider

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -191,7 +175,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 | `children` | `ReactNode \| RenderFunction` | - | Slider content or render function |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### Slider.Output Props
+### Slider.Output

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -199,7 +183,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 | `children` | `ReactNode \| RenderFunction` | - | Output content or render function |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderOutputRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### Slider.Track Props
+### Slider.Track

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -207,14 +191,14 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 | `children` | `ReactNode \| RenderFunction` | - | Track content or render function |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderTrackRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### Slider.Fill Props
+### Slider.Fill

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |
 | `style` | `CSSProperties` | - | Inline styles |

-### Slider.Thumb Props
+### Slider.Thumb

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -225,7 +209,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 | `children` | `ReactNode \| RenderFunction` | - | Thumb content or render function |
 | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderThumbRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### RenderProps
+### Render Props

 When using render functions with Slider.Output or Slider.Track, these values are provided:

@@ -378,3 +362,6 @@ The Slider component implements the ARIA slider pattern and provides:

 For more information, see the [React Aria Slider documentation](https://react-spectrum.adobe.com/react-aria/Slider.html).

+## Related Components
+
+<RelatedComponents component="slider" />
@@ -3,44 +3,39 @@ title: Switch
 description: A toggle switch component for boolean states
 icon: updated
 links:
-  rac: SwitchField
+  rac: Switch
  source: switch/switch.tsx
  styles: switch.css
  storybook: Components/Controls/Switch
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { Switch, SwitchGroup, Label } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="switch-basic"
 />

-### Anatomy
-
-Import the Switch component and access all parts using dot notation.
+## Anatomy

 ```tsx
-import { Switch, Description, FieldError } from '@heroui/react';
+import { Switch, Label, Description } from '@heroui/react';

 export default () => (
  <Switch>
+    <Switch.Control>
+      <Switch.Thumb>
+        <Switch.Icon/> {/* Optional */}
+      </Switch.Thumb>
+    </Switch.Control>
    <Switch.Content>
-      <Switch.Control>
-        <Switch.Thumb>
-          <Switch.Icon /> {/* Optional */}
-        </Switch.Thumb>
-      </Switch.Control>
-      Label {/* plain text — the clickable label + accessible name */}
+      <Label />
+      <Description /> {/* Optional */}
    </Switch.Content>
-    <Description /> {/* Optional — field-level help text */}
-    <FieldError /> {/* Optional — validation message */}
  </Switch>
 );
 ```
@@ -53,31 +48,53 @@ import { Switch, SwitchGroup, Label } from '@heroui/react';
 export default () => (
  <SwitchGroup>
    <Switch>
-      <Switch.Content>
-        <Switch.Control>
-          <Switch.Thumb />
-        </Switch.Control>
-        Option 1
-      </Switch.Content>
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Label>Option 1</Label>
    </Switch>
    <Switch>
-      <Switch.Content>
-        <Switch.Control>
-          <Switch.Thumb />
-        </Switch.Control>
-        Option 2
-      </Switch.Content>
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Label>Option 2</Label>
    </Switch>
  </SwitchGroup>
 );
 ```

+## Examples
+
+### Sizes
+
+<ComponentPreview
+  name="switch-sizes"
+/>
+
+### With Icons
+
+<ComponentPreview
+  name="switch-with-icons"
+/>
+
 ### Disabled

 <ComponentPreview
  name="switch-disabled"
 />

+### Without Label
+
+<ComponentPreview
+  name="switch-without-label"
+/>
+
+### With Description
+
+<ComponentPreview
+  name="switch-with-description"
+/>
+
 ### Default Selected

 <ComponentPreview
@@ -90,36 +107,12 @@ export default () => (
  name="switch-controlled"
 />

-### Without Label
-
-<ComponentPreview
-  name="switch-without-label"
-/>
-
-### Sizes
-
-<ComponentPreview
-  name="switch-sizes"
-/>
-
 ### Label Position

 <ComponentPreview
  name="switch-label-position"
 />

-### With Icons
-
-<ComponentPreview
-  name="switch-with-icons"
-/>
-
-### With Description
-
-<ComponentPreview
-  name="switch-with-description"
-/>
-
 ### Group

 <ComponentPreview
@@ -132,94 +125,34 @@ export default () => (
  name="switch-group-horizontal"
 />

-### Render Props
-
-<ComponentPreview
-  name="switch-render-props"
-/>
-
 ### Form Integration

 <ComponentPreview
  name="switch-form"
 />

-### Custom Styles
+### Render Props

 <ComponentPreview
-  name="switch-custom-styles"
+  name="switch-render-props"
 />

-### Custom Render Function
+### Render Function

 <ComponentPreview
-  name="switch-custom-render-function"
+  name="switch-render-function"
 />

-<RelatedComponents component="switch" />
+## Customization

-## Styling
+### Tailwind CSS

-### Passing Tailwind CSS classes
+<ComponentPreview name="switch-custom-styles" />

-You can customize individual Switch components:
-
-```tsx
-import { Switch, Label } from '@heroui/react';
-
-function CustomSwitch() {
-  return (
-    <Switch>
-      {({isSelected}) => (
-        <>
-          <Switch.Control
-            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
-          >
-            <Switch.Thumb
-              className={`size-[27px] bg-white shadow-sm ${isSelected ? "translate-x-5 shadow-lg" : ""}`}
-            />
-          </Switch.Control>
-          Custom Switch
-        </>
-      )}
-    </Switch>
-  );
-}
-```
-
-Or customize the SwitchGroup layout:
-
-```tsx
-import { Switch, SwitchGroup, Label } from '@heroui/react';
-
-function CustomSwitchGroup() {
-  return (
-    <SwitchGroup className="gap-8" orientation="horizontal">
-      <Switch>
-        <Switch.Content>
-          <Switch.Control>
-            <Switch.Thumb />
-          </Switch.Control>
-          Option 1
-        </Switch.Content>
-      </Switch>
-      <Switch>
-        <Switch.Content>
-          <Switch.Control>
-            <Switch.Thumb />
-          </Switch.Control>
-          Option 2
-        </Switch.Content>
-      </Switch>
-    </SwitchGroup>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the Switch component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -236,7 +169,7 @@ To customize the Switch component classes, you can use the `@layer components` d
  }

  .switch__content {
-    @apply items-center gap-3;
+    @apply flex flex-col gap-1;
  }

  .switch__icon {
@@ -245,16 +178,18 @@ To customize the Switch component classes, you can use the `@layer components` d
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

-#### Switch Classes
+#### Switch Classes [!toc]

 The Switch component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch.css)):

- `.switch` - Base switch container (the field)
- `.switch__content` - Clickable label wrapping the control and label text
+- `.switch` - Base switch container
+- `.switch__content` - Optional content container
 - `.switch__control` - Switch control track
 - `.switch__thumb` - Switch thumb that moves
 - `.switch__icon` - Optional icon inside the thumb
@@ -262,7 +197,7 @@ The Switch component uses these CSS classes ([View source styles](https://github
 - `.switch--md` - Medium size variant (default)
 - `.switch--lg` - Large size variant

-#### SwitchGroup Classes
+#### SwitchGroup Classes [!toc]

 The SwitchGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch-group.css)):

@@ -276,16 +211,16 @@ The SwitchGroup component uses these CSS classes ([View source styles](https://g
 The switch supports both CSS pseudo-classes and data attributes for flexibility:

 - **Selected**: `[data-selected="true"]` (thumb position and background color change)
- **Hover**: `:hover` or `[data-hovered="true"]` on `Switch.Control` (button)
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on the button (shows focus ring on track)
- **Disabled**: `[data-disabled="true"]` on the field (reduced opacity, including help text)
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
+- **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
 - **Pressed**: `:active` or `[data-pressed="true"]`

 ## API Reference

-### Switch Props
+### Switch

-Inherits from [React Aria SwitchField](https://react-spectrum.adobe.com/react-aria/Switch.html).
+Inherits from [React Aria Switch](https://react-spectrum.adobe.com/react-aria/Switch.html).

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -302,39 +237,34 @@ Inherits from [React Aria SwitchField](https://react-spectrum.adobe.com/react-ar
 | `value` | `string` | - | The value of the input element, used when submitting an HTML form |
 | `onChange` | `(isSelected: boolean) => void` | - | Handler called when the switch value changes |
 | `onPress` | `(e: PressEvent) => void` | - | Handler called when the switch is pressed |
-| `children` | `React.ReactNode \| (values: SwitchFieldRenderProps) => React.ReactNode` | - | Switch content or field render prop |
-| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SwitchFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+| `children` | `React.ReactNode \| (values: SwitchRenderProps) => React.ReactNode` | - | Switch content or render prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SwitchRenderProps>` | - | Overrides the default DOM element with a custom render function.|

-### Switch.Content Props
+### Render Props

-The clickable `<label>` that wraps the control and label text. Put `Switch.Control` and the `Label` inside it; keep `Description`/`FieldError` as siblings of `Switch.Content`. For a switch with no label, omit the `Label` and pass an `aria-label` on `Switch`.
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `React.ReactNode \| (values: SwitchButtonRenderProps) => React.ReactNode` | - | Button content (control + label), or a button render prop |
-| `className` | `string \| (values: SwitchButtonRenderProps) => string` | - | Classes applied to the clickable label |
-
-### SwitchFieldRenderProps
-
-When using a render prop on the root `Switch`, these field-level values are provided:
+When using the render prop pattern, these values are provided:

 | Prop | Type | Description |
 |------|------|-------------|
 | `isSelected` | `boolean` | Whether the switch is currently on |
+| `isHovered` | `boolean` | Whether the switch is hovered |
+| `isPressed` | `boolean` | Whether the switch is currently pressed |
+| `isFocused` | `boolean` | Whether the switch is focused |
+| `isFocusVisible` | `boolean` | Whether the switch is keyboard focused |
 | `isDisabled` | `boolean` | Whether the switch is disabled |
 | `isReadOnly` | `boolean` | Whether the switch is read only |
 | `isInvalid` | `boolean` | Whether the switch is invalid |
 | `isRequired` | `boolean` | Whether the switch is required |
-| `state` | `ToggleState` | State of the switch |
+| `state` | `-` | State of the switch. |

-### SwitchButtonRenderProps
-
-`Switch.Control` uses button-level render props (`isHovered`, `isPressed`, `isFocusVisible`, etc.). Pass a function as `Switch.Control` children to access them.
-
-### SwitchGroup Props
+### SwitchGroup

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | The orientation of the switch group |
 | `children` | `React.ReactNode` | - | The switch items to render |
 | `className` | `string` | - | Additional CSS class names |
+
+## Related Components
+
+<RelatedComponents component="switch" />
@@ -1,6 +1,7 @@
 ---
 title: Badge
 description: Displays a small indicator positioned relative to another element, commonly used for notification counts, status dots, and labels
+
 links:
  source: badge/badge.tsx
  styles: badge.css
@@ -8,12 +9,16 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { Badge } from '@heroui/react';
 ```

+<ComponentPreview
+  name="badge-basic"
+/>
+
 ## Anatomy

 Badge is designed to be positioned relative to another element using `Badge.Anchor`. Plain-text children are automatically wrapped in `<Badge.Label>`.
@@ -27,16 +32,12 @@ Badge is designed to be positioned relative to another element using `Badge.Anch
 </Badge.Anchor>
 ```

-### Usage
+## Examples
+
+### Variants

 <ComponentPreview
-  name="badge-basic"
-/>
-
-### Colors
-
-<ComponentPreview
-  name="badge-colors"
+  name="badge-variants"
 />

 ### Sizes
@@ -45,10 +46,10 @@ Badge is designed to be positioned relative to another element using `Badge.Anch
  name="badge-sizes"
 />

-### Variants
+### Colors

 <ComponentPreview
-  name="badge-variants"
+  name="badge-colors"
 />

 ### Placements
@@ -57,14 +58,6 @@ Badge is designed to be positioned relative to another element using `Badge.Anch
  name="badge-placements"
 />

-### With Content
-
-Badge supports text, numbers, and icons as content. When no children are provided, it renders as a dot indicator.
-
-<ComponentPreview
-  name="badge-with-content"
-/>
-
 ### Dot Badge

 Empty badges act as status indicators — useful for online/offline states or activity signals.
@@ -73,33 +66,24 @@ Empty badges act as status indicators — useful for online/offline states or ac
  name="badge-dot"
 />

-<RelatedComponents component="badge" />
+### With Content

-## Styling
+Badge supports text, numbers, and icons as content. When no children are provided, it renders as a dot indicator.

-### Passing Tailwind CSS classes
+<ComponentPreview
+  name="badge-with-content"
+/>

-You can style the root container and individual slots:
+## Customization

-```tsx
-import {Badge, Avatar} from '@heroui/react';
+### Tailwind CSS

-function CustomBadge() {
-  return (
-    <Badge.Anchor>
-      <Avatar />
-      <Badge className="border-2 border-white" color="danger">
-        <Badge.Label className="font-bold">99+</Badge.Label>
-      </Badge>
-    </Badge.Anchor>
-  );
-}
-```
+<ComponentPreview name="badge-custom-styles" />

-### Customizing the component classes
+### Global CSS

 To customize the Badge component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -117,41 +101,43 @@ To customize the Badge component classes, you can use the `@layer components` di
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The Badge component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/badge.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.badge` - Base badge container styles
 - `.badge__label` - Label text slot styles
 - `.badge-anchor` - Positioning wrapper for the anchored element

-#### Color Classes
+#### Color Classes [!toc]
 - `.badge--accent` - Accent color variant
 - `.badge--danger` - Danger color variant
 - `.badge--default` - Default color variant
 - `.badge--success` - Success color variant
 - `.badge--warning` - Warning color variant

-#### Variant Classes
+#### Variant Classes [!toc]
 - `.badge--primary` - Primary variant with filled background
 - `.badge--secondary` - Secondary variant with default background
 - `.badge--soft` - Soft variant with lighter background

-#### Size Classes
+#### Size Classes [!toc]
 - `.badge--sm` - Small size
 - `.badge--md` - Medium size (default)
 - `.badge--lg` - Large size

-#### Placement Classes
+#### Placement Classes [!toc]
 - `.badge--top-right` - Position at top-right corner (default)
 - `.badge--top-left` - Position at top-left corner
 - `.badge--bottom-right` - Position at bottom-right corner
 - `.badge--bottom-left` - Position at bottom-left corner

-#### Compound Variant Classes
+#### Compound Variant Classes [!toc]

 Badges support combining variant and color classes (e.g., `.badge--primary.badge--accent`). The following combinations have default styles defined:

@@ -171,7 +157,7 @@ Badges support combining variant and color classes (e.g., `.badge--primary.badge

 ## API Reference

-### Badge Props
+### Badge

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -182,16 +168,20 @@ Badges support combining variant and color classes (e.g., `.badge--primary.badge
 | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the badge |
 | `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | Position of the badge relative to its anchor |

-### Badge.Anchor Props
+### Badge.Anchor

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `children` | `React.ReactNode` | - | The element to anchor the badge to, plus the Badge itself |
 | `className` | `string` | - | Additional CSS classes for the anchor wrapper |

-### Badge.Label Props
+### Badge.Label

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `children` | `React.ReactNode` | - | Label text content |
 | `className` | `string` | - | Additional CSS classes for the label slot |
+
+## Related Components
+
+<RelatedComponents component="badge" />
@@ -8,15 +8,17 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { Chip } from '@heroui/react';
 ```

-## Anatomy
+<ComponentPreview
+  name="chip-basic"
+/>

-Import the Chip component and access all parts using dot notation.
+## Anatomy

 > Plain-text children are automatically wrapped in `<Chip.Label>`.

@@ -26,11 +28,7 @@ Import the Chip component and access all parts using dot notation.
 </Chip>
 ```

-### Usage
-
-<ComponentPreview
-  name="chip-basic"
-/>
+## Examples

 ### Variants

@@ -38,44 +36,28 @@ Import the Chip component and access all parts using dot notation.
  name="chip-variants"
 />

-### With Icons
-
-<ComponentPreview
-  name="chip-with-icon"
-/>
-
 ### Statuses

 <ComponentPreview
  name="chip-statuses"
 />

-<RelatedComponents component="chip" />
+### With Icons

-## Styling
+<ComponentPreview
+  name="chip-with-icon"
+/>

-### Passing Tailwind CSS classes
+## Customization

-You can style the root container and individual slots:
+### Tailwind CSS

-```tsx
-import {Chip} from '@heroui/react';
+<ComponentPreview name="chip-custom-styles" />

-function CustomChip() {
-  return (
-    <Chip className="rounded-full px-4 py-2 font-bold">
-      <Chip.Label className="text-lg uppercase">
-        Custom Styled
-      </Chip.Label>
-    </Chip>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the Chip component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -97,35 +79,37 @@ To customize the Chip component classes, you can use the `@layer components` dir
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The Chip component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/chip.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.chip` - Base chip container styles
 - `.chip__label` - Label text slot styles

-#### Color Classes
+#### Color Classes [!toc]
 - `.chip--accent` - Accent color variant
 - `.chip--danger` - Danger color variant
 - `.chip--default` - Default color variant
 - `.chip--success` - Success color variant
 - `.chip--warning` - Warning color variant

-#### Variant Classes
+#### Variant Classes [!toc]
 - `.chip--primary` - Primary variant with filled background
 - `.chip--secondary` - Secondary variant with border
 - `.chip--tertiary` - Tertiary variant with transparent background
 - `.chip--soft` - Soft variant with lighter background

-#### Size Classes
+#### Size Classes [!toc]
 - `.chip--sm` - Small size
 - `.chip--md` - Medium size (default)
 - `.chip--lg` - Large size

-#### Compound Variant Classes
+#### Compound Variant Classes [!toc]

 Chips support combining variant and color classes (e.g., `.chip--secondary.chip--accent`). The following combinations have default styles defined:

@@ -145,7 +129,7 @@ Chips support combining variant and color classes (e.g., `.chip--secondary.chip-

 ## API Reference

-### Chip Props
+### Chip

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -155,9 +139,13 @@ Chips support combining variant and color classes (e.g., `.chip--secondary.chip-
 | `variant` | `"primary" \| "secondary" \| "tertiary" \| "soft"` | `"secondary"` | Visual style variant |
 | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the chip |

-### Chip.Label Props
+### Chip.Label

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `children` | `React.ReactNode` | - | Label text content |
 | `className` | `string` | - | Additional CSS classes for the label slot |
+
+## Related Components
+
+<RelatedComponents component="chip" />
@@ -2,6 +2,7 @@
 title: Table
 description: Tables display structured data in rows and columns with support for sorting, selection, column resizing, and infinite scrolling.
 icon: updated
+
 links:
  rac: Table
  source: table/table.tsx
@@ -9,22 +10,18 @@ links:
  storybook: Components/Data Display/Table
 ---

-## Import
+## Usage

 ```tsx
 import { Table } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview
  name="table-basic"
  minHeight="320px"
 />

-### Anatomy
-
-Import the Table component and access all parts using dot notation.
+## Anatomy

 ```tsx
 import { Table } from '@heroui/react';
@@ -34,13 +31,7 @@ export default () => (
    <Table.ScrollContainer>
      <Table.Content aria-label="Example table">
        <Table.Header>
-          <Table.Column allowsSorting>
-            {({ sortDirection }) => (
-              <Table.SortableColumnHeader sortDirection={sortDirection}>
-                Name
-              </Table.SortableColumnHeader>
-            )}
-          </Table.Column>
+          <Table.Column>Name</Table.Column>
          <Table.Column>Role</Table.Column>
        </Table.Header>
        <Table.Body>
@@ -56,6 +47,8 @@ export default () => (
 );
 ```

+## Examples
+
 ### Secondary Variant

 <ComponentPreview
@@ -63,6 +56,15 @@ export default () => (
  minHeight="320px"
 />

+### Async Loading
+
+Use `Table.LoadMore` for infinite scrolling. It renders a sentinel row that triggers `onLoadMore` when scrolled into view.
+
+<ComponentPreview
+  name="table-async-loading"
+  minHeight="380px"
+/>
+
 ### Sorting

 Columns can be made sortable using the `allowsSorting` prop on `Table.Column`. Use `sortDescriptor` and `onSortChange` on `Table.Content` to manage sort state. Wrap the label in `Table.SortableColumnHeader` and forward the `sortDirection` from the column's render prop to render the default ascending/descending indicator.
@@ -81,13 +83,6 @@ Enable row selection with `selectionMode` on `Table.Content`. Use `Checkbox` wit
  minHeight="380px"
 />

-### Custom Cells
-
-<ComponentPreview
-  name="table-custom-cells"
-  minHeight="420px"
-/>
-
 ### Expandable Rows

 Rows can be nested to display hierarchical data. Use the `treeColumn` prop to designate a column, and render a `Button` with `slot="chevron"` in that column’s cells so users can expand and collapse the row. Use the `expandedKeys` prop to control which rows are expanded.
@@ -124,15 +119,6 @@ Use `renderEmptyState` on `Table.Body` to display a custom message when the tabl
  minHeight="300px"
 />

-### Async Loading
-
-Use `Table.LoadMore` for infinite scrolling. It renders a sentinel row that triggers `onLoadMore` when scrolled into view.
-
-<ComponentPreview
-  name="table-async-loading"
-  minHeight="380px"
-/>
-
 ### Virtualization

 Table supports virtualization through [Virtualizer](https://react-aria.adobe.com/Virtualizer), enabling efficient rendering of large datasets by displaying only the rows visible within the viewport.
@@ -154,41 +140,23 @@ accessibility.
  minHeight="420px"
 />

-<RelatedComponents component="table" />
+### Custom Cells

-## Styling
+<ComponentPreview
+  name="table-custom-cells"
+  minHeight="420px"
+/>

-### Passing Tailwind CSS classes
+## Customization

-You can customize individual Table parts:
+### Tailwind CSS

-```tsx
-import { Table } from '@heroui/react';
+<ComponentPreview name="table-custom-styles" />

-function CustomTable() {
-  return (
-    <Table className="border border-purple-200">
-      <Table.ScrollContainer>
-        <Table.Content aria-label="Custom styled table">
-          <Table.Header className="bg-purple-50">
-            <Table.Column>Name</Table.Column>
-          </Table.Header>
-          <Table.Body>
-            <Table.Row className="hover:bg-purple-50">
-              <Table.Cell>Kate Moore</Table.Cell>
-            </Table.Row>
-          </Table.Body>
-        </Table.Content>
-      </Table.ScrollContainer>
-    </Table>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize the Table component classes, you can use the `@layer components` directive.
-<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

 ```css
@layer components {
@@ -218,13 +186,15 @@ To customize the Table component classes, you can use the `@layer components` di
 }
 ```

+## Styling Reference
+
 HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

 The Table component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/table.css)):

-#### Base Classes
+#### Base Classes [!toc]
 - `.table-root` - Root container (named `table-root` instead of `table` because `table` is a built-in Tailwind CSS utility class for `display: table`)
 - `.table__scroll-container` - Horizontal scroll wrapper with custom scrollbar
 - `.table__content` - The `<table>` element
@@ -235,15 +205,13 @@ The Table component uses these CSS classes ([View source styles](https://github.
 - `.table__cell` - Data cell (`<td>`)
 - `.table__footer` - Footer container (outside table)

-#### Advanced Classes
+#### Advanced Classes [!toc]
 - `.table__column-resizer` - Drag handle for column resizing
 - `.table__resizable-container` - Wrapper enabling column resizing
 - `.table__load-more` - Sentinel row for infinite scrolling
 - `.table__load-more-content` - Styled container for the loading indicator
- `.table__sortable-column-header` - Sortable column label + indicator wrapper
- `.table__sortable-column-indicator` - Sort direction chevron (rotates via `[data-direction="descending"]`)

-#### Variant Classes
+#### Variant Classes [!toc]
 - `.table-root--primary` - Gray background container with card-style body (default)
 - `.table-root--secondary` - No background, standalone rounded headers

@@ -261,7 +229,7 @@ The Table supports both CSS pseudo-classes and data attributes for flexibility:

 ## API Reference

-### Table Props
+### Table

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -269,14 +237,14 @@ The Table supports both CSS pseudo-classes and data attributes for flexibility:
 | `className` | `string` | - | Additional CSS classes for the root container |
 | `children` | `React.ReactNode` | - | Table content (ScrollContainer, Footer, etc.) |

-### Table.ScrollContainer Props
+### Table.ScrollContainer

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `React.ReactNode` | - | Table.Content element |

-### Table.Content Props
+### Table.Content

 Inherits from [React Aria Table](https://react-spectrum.adobe.com/react-aria/Table.html).

@@ -290,7 +258,7 @@ Inherits from [React Aria Table](https://react-spectrum.adobe.com/react-aria/Tab
 | `onSortChange` | `(descriptor: SortDescriptor) => void` | - | Sort change handler |
 | `className` | `string` | - | Additional CSS classes |

-### Table.Header Props
+### Table.Header

 Inherits from [React Aria TableHeader](https://react-spectrum.adobe.com/react-aria/Table.html#tableheader).

@@ -299,7 +267,7 @@ Inherits from [React Aria TableHeader](https://react-spectrum.adobe.com/react-ar
 | `columns` | `T[]` | - | Dynamic column data for render prop pattern |
 | `children` | `React.ReactNode \| (column: T) => React.ReactNode` | - | Static columns or render prop |

-### Table.Column Props
+### Table.Column

 Inherits from [React Aria Column](https://react-spectrum.adobe.com/react-aria/Table.html#column).

@@ -312,7 +280,7 @@ Inherits from [React Aria Column](https://react-spectrum.adobe.com/react-aria/Ta
 | `minWidth` | `number` | - | Minimum width for resizable columns |
 | `children` | `React.ReactNode \| (values: ColumnRenderProps) => React.ReactNode` | - | Column content or render prop with sort direction |

-### Table.Body Props
+### Table.Body

 Inherits from [React Aria TableBody](https://react-spectrum.adobe.com/react-aria/Table.html#tablebody).

@@ -322,7 +290,7 @@ Inherits from [React Aria TableBody](https://react-spectrum.adobe.com/react-aria
 | `renderEmptyState` | `() => React.ReactNode` | - | Content to display when the table is empty |
 | `children` | `React.ReactNode \| (item: T) => React.ReactNode` | - | Static rows or render prop |

-### Table.Row Props
+### Table.Row

 Inherits from [React Aria Row](https://react-spectrum.adobe.com/react-aria/Table.html#row).

@@ -332,7 +300,7 @@ Inherits from [React Aria Row](https://react-spectrum.adobe.com/react-aria/Table
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `React.ReactNode` | - | Row cells |

-### Table.Cell Props
+### Table.Cell

 Inherits from [React Aria Cell](https://react-spectrum.adobe.com/react-aria/Table.html#cell).

@@ -341,7 +309,7 @@ Inherits from [React Aria Cell](https://react-spectrum.adobe.com/react-aria/Tabl
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `React.ReactNode` | - | Cell content |

-### Table.SortableColumnHeader Props
+### Table.SortableColumnHeader

 Renders a sortable column label with an ascending/descending indicator. Use it inside a `Table.Column` render-prop callback and forward the `sortDirection` value.

@@ -351,16 +319,16 @@ Renders a sortable column label with an ascending/descending indicator. Use it i
 | `showIndicator` | `boolean` | `true` | Whether to render the sort indicator icon when a direction is set. |
 | `indicator` | `React.ReactNode` | - | Custom indicator element. Overrides the default chevron and receives a `data-direction` attribute. |
 | `className` | `string` | - | Additional CSS classes for the wrapper. |
-| `children` | `React.ReactNode` | - | Column label content. |
+| `children` | `React.ReactNode` | - | Column label content |

-### Table.Footer Props
+### Table.Footer

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `React.ReactNode` | - | Footer content (e.g., pagination) |

-### Table.ColumnResizer Props
+### Table.ColumnResizer

 Inherits from [React Aria ColumnResizer](https://react-spectrum.adobe.com/react-aria/Table.html#columnresizer).

@@ -368,7 +336,7 @@ Inherits from [React Aria ColumnResizer](https://react-spectrum.adobe.com/react-
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |

-### Table.ResizableContainer Props
+### Table.ResizableContainer

 Inherits from [React Aria ResizableTableContainer](https://react-spectrum.adobe.com/react-aria/Table.html#resizabletablecontainer).

@@ -377,7 +345,7 @@ Inherits from [React Aria ResizableTableContainer](https://react-spectrum.adobe.
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `React.ReactNode` | - | Table.Content element |

-### Table.LoadMore Props
+### Table.LoadMore

 Inherits from [React Aria TableLoadMoreItem](https://react-spectrum.adobe.com/react-aria/Table.html).

@@ -387,14 +355,14 @@ Inherits from [React Aria TableLoadMoreItem](https://react-spectrum.adobe.com/re
 | `onLoadMore` | `() => void` | - | Handler called when the sentinel row is visible |
 | `children` | `React.ReactNode` | - | Loading indicator content |

-### Table.LoadMoreContent Props
+### Table.LoadMoreContent

 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `React.ReactNode` | - | Loading indicator content (e.g., Spinner) |

-### Table.Collection Props
+### Table.Collection

 Re-exported from React Aria `Collection`. Used to render dynamic cells within rows alongside static cells (e.g., checkboxes).

@@ -403,7 +371,6 @@ Re-exported from React Aria `Collection`. Used to render dynamic cells within ro
 | `items` | `T[]` | - | Collection items |
 | `children` | `(item: T) => React.ReactNode` | - | Render prop for each item |

-
 ### TableLayout

 | Name | Type | Default | Description |
@@ -415,4 +382,8 @@ Re-exported from React Aria `Collection`. Used to render dynamic cells within ro
 | `loaderHeight` | `number \| undefined` | 48 | The fixed height of a loader element in px. This loader is specifically for "load more" elements rendered when loading more rows at the root level or inside nested row/sections. |
 | `dropIndicatorThickness` | `number \| undefined` | 2 | The thickness of the drop indicator. |
 | `gap` | `number \| undefined` | 0 | The gap between items. |
-| `padding` | `number \| undefined` | 0 | The padding around the list. |
+| `padding` | `number \| undefined` | 0 | The padding around the list. |
+
+## Related Components
+
+<RelatedComponents component="table" />
@@ -9,17 +9,15 @@ links:
  storybook: Components/Date and Time/Calendar
 ---

-## Import
+## Usage

 ```tsx
 import { Calendar } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview name="calendar-basic" />

-### Anatomy
+## Anatomy

 ```tsx
 import {Calendar} from '@heroui/react';
@@ -43,16 +41,26 @@ export default () => (
 )
 ```

+## Examples
+
+### Disabled
+
+<ComponentPreview name="calendar-disabled" />
+
+### Read Only
+
+<ComponentPreview name="calendar-read-only" />
+
+### Default Value
+
+<ComponentPreview name="calendar-default-value" />
+
 ### Year Picker

 `Calendar.YearPickerTrigger`, `Calendar.YearPickerGrid`, and their body/cell subcomponents provide an integrated year navigation pattern.

 <ComponentPreview name="calendar-year-picker" />

-### Default Value
-
-<ComponentPreview name="calendar-default-value" />
-
 ### Controlled

 Use controlled `value` and `focusedValue` for external state coordination and custom shortcuts.
@@ -93,14 +101,6 @@ Set `selectionMode="multiple"` to let users select several dates. `value`, `defa

 <ComponentPreview name="calendar-multiple-selection" />

-### Disabled
-
-<ComponentPreview name="calendar-disabled" />
-
-### Read Only
-
-<ComponentPreview name="calendar-read-only" />
-
 ### Focused Value

 Programmatically control which date is focused using `focusedValue` and `onFocusChange`.
@@ -113,12 +113,22 @@ You can customize `Calendar.Cell` children and use `Calendar.CellIndicator` to d

 <ComponentPreview name="calendar-with-indicators" />

+### Custom Navigation Icons
+
+Pass children to `Calendar.NavButton` to replace the default chevron icons.
+
+<ComponentPreview name="calendar-custom-icons" />
+
 ### Multiple Months

-Render multiple grids with `visibleDuration` and `offset` for booking and planning experiences. Use `Calendar.Heading` with an `offset` (for example, `offset={{ months: 1 }}`) in each column header to label that month.
+Render multiple grids with `visibleDuration` and `offset` for booking and planning experiences.

 <ComponentPreview name="calendar-multiple-months" />

+### Real-World Example
+
+<ComponentPreview name="calendar-booking-calendar" />
+
 ### International Calendars

 By default, Calendar displays dates using the calendar system for the user's locale. You can override this by wrapping your Calendar with `I18nProvider` and setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string).
@@ -129,51 +139,13 @@ The example below shows the Indian calendar system:

 **Note:** The `onChange` event always returns a date in the same calendar system as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale. This ensures your application logic works consistently with a single calendar system while still displaying dates in the user's preferred format.

-### Custom Navigation Icons
+## Customization

-Pass children to `Calendar.NavButton` to replace the default chevron icons.
-
-<ComponentPreview name="calendar-custom-icons" />
-
-### Real-World Example
-
-<ComponentPreview name="calendar-booking-calendar" />
-
-### Custom Styles
+### Tailwind CSS

 <ComponentPreview name="calendar-custom-styles" />

-<RelatedComponents component="calendar" />
-
-## Styling
-
-### Passing Tailwind CSS classes
-
-```tsx
-import {Calendar} from '@heroui/react';
-
-function CustomCalendar() {
-  return (
-    <Calendar aria-label="Custom calendar" className="w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm">
-      <Calendar.Header className="pb-3">
-        <Calendar.Heading className="text-default" />
-        <Calendar.NavButton slot="previous" className="text-default" />
-        <Calendar.NavButton slot="next" className="text-default" />
-      </Calendar.Header>
-      <Calendar.Grid>
-        <Calendar.GridHeader>
-          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
-        </Calendar.GridHeader>
-        <Calendar.GridBody>
-          {(date) => <Calendar.Cell date={date} />}
-        </Calendar.GridBody>
-      </Calendar.Grid>
-    </Calendar>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 ```css
@layer components {
@@ -191,6 +163,10 @@ function CustomCalendar() {
 }
 ```

+## Styling Reference
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
 ### CSS Classes

 Calendar uses these classes in `packages/styles/components/calendar.css` and `packages/styles/components/calendar-year-picker.css`:
@@ -226,7 +202,7 @@ Calendar supports both pseudo-classes and React Aria data attributes:

 ## API Reference

-### Calendar Props
+### Calendar

 Calendar inherits all props from React Aria [Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html).

@@ -304,3 +280,7 @@ For a complete list of supported calendar systems and their identifiers, see:
 - [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components
 - [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree
 - [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction
+
+## Related Components
+
+<RelatedComponents component="calendar" />
@@ -1,6 +1,7 @@
 ---
 title: DateField
 description: Date input field with labels, descriptions, and validation built on React Aria DateField
+
 links:
  rac: DateField
  source: date-field/date-field.tsx
@@ -8,17 +9,15 @@ links:
  storybook: Components/Date and Time/DateField
 ---

-## Import
+## Usage

 ```tsx
 import { DateField } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview name="date-field-basic" />

-### Anatomy
+## Anatomy

 ```tsx
 import {DateField, Label, Description, FieldError} from '@heroui/react';
@@ -39,39 +38,7 @@ export default () => (

 > **DateField** combines label, date input, description, and error into a single accessible component.

-### With Description
-
-<ComponentPreview name="date-field-with-description" />
-
-### Required Field
-
-<ComponentPreview name="date-field-required" />
-
-### Validation
-
-Use `isInvalid` together with `FieldError` to surface validation messages.
-
-<ComponentPreview name="date-field-invalid" />
-
-### With Validation
-
-DateField supports validation with `minValue`, `maxValue`, and custom validation logic.
-
-<ComponentPreview name="date-field-with-validation" />
-
-### Granularity
-
-<ComponentPreview name="date-field-granularity" />
-
-### Controlled
-
-Control the value to synchronize with other components or state management.
-
-<ComponentPreview name="date-field-controlled" />
-
-### Disabled State
-
-<ComponentPreview name="date-field-disabled" />
+## Examples

 ### With Icons

@@ -83,10 +50,6 @@ Add prefix or suffix icons to enhance the date field.

 <ComponentPreview name="date-field-with-prefix-and-suffix" />

-### Full Width
-
-<ComponentPreview name="date-field-full-width" />
-
 ### Variants

 The DateField.Group component supports two visual variants:
@@ -102,47 +65,63 @@ When used inside a [Surface](/docs/components/surface) component, use `variant="

 <ComponentPreview name="date-field-on-surface" />

+### With Description
+
+<ComponentPreview name="date-field-with-description" />
+
+### Required Field
+
+<ComponentPreview name="date-field-required" />
+
+### Disabled State
+
+<ComponentPreview name="date-field-disabled" />
+
+### Full Width
+
+<ComponentPreview name="date-field-full-width" />
+
+### Validation
+
+Use `isInvalid` together with `FieldError` to surface validation messages.
+
+<ComponentPreview name="date-field-invalid" />
+
+### Granularity
+
+<ComponentPreview name="date-field-granularity" />
+
+### Controlled
+
+Control the value to synchronize with other components or state management.
+
+<ComponentPreview name="date-field-controlled" />
+
 ### Form Example

 Complete form example with validation and submission handling.

 <ComponentPreview name="date-field-form-example" />

-<RelatedComponents component="datefield" />
+### With Validation

-### Custom Render Function
+DateField supports validation with `minValue`, `maxValue`, and custom validation logic.
+
+<ComponentPreview name="date-field-with-validation" />
+
+### Render Function

 <ComponentPreview
-  name="date-field-custom-render-function"
+  name="date-field-render-function"
 />

-## Styling
+## Customization

-### Passing Tailwind CSS classes
+### Tailwind CSS

-```tsx
-import {DateField, Label, Description} from '@heroui/react';
+<ComponentPreview name="date-field-custom-styles" />

-function CustomDateField() {
-  return (
-    <DateField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
-      <Label className="text-sm font-semibold text-default-700">
-        Appointment date
-      </Label>
-      <DateField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
-        <DateField.Input>
-          {(segment) => <DateField.Segment segment={segment} />}
-        </DateField.Input>
-      </DateField.Group>
-      <Description className="text-xs text-default-500">
-        Select a date for your appointment.
-      </Description>
-    </DateField>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 DateField has minimal default styling. Override the `.date-field` class to customize the container styling.

@@ -169,6 +148,10 @@ DateField has minimal default styling. Override the `.date-field` class to custo
 }
 ```

+## Styling Reference
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
 ### CSS Classes

 - `.date-field` – Root container with minimal styling (`flex flex-col gap-1`)
@@ -186,7 +169,7 @@ DateField automatically manages these data attributes based on its state:

 ## API Reference

-### DateField Props
+### DateField

 DateField inherits all props from React Aria's [DateField](https://react-aria.adobe.com/DateField.md) component.

@@ -320,7 +303,7 @@ const todayDate = today(getLocalTimeZone());

 > **Note:** DateField uses the [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) package for date manipulation, parsing, and type definitions. See the [Internationalized Date documentation](https://react-aria.adobe.com/internationalized/date/) for more information about available types and functions.

-### DateFieldRenderProps
+### Render Props

 When using render props with `className`, `style`, or `children`, these values are available:

@@ -334,7 +317,7 @@ When using render props with `className`, `style`, or `children`, these values a
 | `isFocusWithin` | `boolean` | Whether any child element is focused. |
 | `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |

-### DateField.Group Props
+### DateField.Group

 DateField.Group accepts all props from React Aria's `Group` component plus the following:

@@ -344,7 +327,7 @@ DateField.Group accepts all props from React Aria's `Group` component plus the f
 | `fullWidth` | `boolean` | `false` | Whether the date input group should take full width of its container |
 | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |

-### DateField.Input Props
+### DateField.Input

 DateField.Input accepts all props from React Aria's `DateInput` component plus the following:

@@ -355,7 +338,7 @@ DateField.Input accepts all props from React Aria's `DateInput` component plus t

 The `DateField.Input` component accepts a render prop function that receives date segments. Each segment represents a part of the date (year, month, day, etc.).

-### DateField.Segment Props
+### DateField.Segment

 DateField.Segment accepts all props from React Aria's `DateSegment` component:

@@ -364,7 +347,7 @@ DateField.Segment accepts all props from React Aria's `DateSegment` component:
 | `segment` | `DateSegment` | - | The date segment object from the DateField.Input render prop. |
 | `className` | `string` | - | Tailwind classes merged with the component styles. |

-### DateField.InputContainer Props
+### DateField.InputContainer

 DateField.InputContainer accepts standard HTML `div` attributes:

@@ -373,7 +356,7 @@ DateField.InputContainer accepts standard HTML `div` attributes:
 | `className` | `string` | - | Tailwind classes merged with the component styles. |
 | `children` | `ReactNode` | - | Content to display inside the scrollable container (typically multiple `DateField.Input` components). |

-### DateField.Prefix Props
+### DateField.Prefix

 DateField.Prefix accepts standard HTML `div` attributes:

@@ -382,7 +365,7 @@ DateField.Prefix accepts standard HTML `div` attributes:
 | `className` | `string` | - | Tailwind classes merged with the component styles. |
 | `children` | `ReactNode` | - | Content to display in the prefix slot. |

-### DateField.Suffix Props
+### DateField.Suffix

 DateField.Suffix accepts standard HTML `div` attributes:

@@ -466,3 +449,7 @@ The base classes power every instance. Override them once with `@layer component
 - **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]`
 - **Segment Focus**: `:focus` or `[data-focused="true"]` on segment elements
 - **Segment Placeholder**: `[data-placeholder="true"]` on segment elements
+
+## Related Components
+
+<RelatedComponents component="datefield" />
@@ -1,6 +1,7 @@
 ---
 title: DatePicker
 description: Composable date picker built on React Aria DatePicker with DateField and Calendar composition
+
 links:
  rac: DatePicker
  source: date-picker/date-picker.tsx
@@ -9,17 +10,15 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { DatePicker, DateField, Calendar, Label } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview name="date-picker-basic" />

-### Anatomy
+## Anatomy

 `DatePicker` follows a composition-first API. Compose `DateField` and `Calendar` explicitly to control structure and styling.

@@ -61,6 +60,12 @@ export default () => (
 )
 ```

+## Examples
+
+### Disabled
+
+<ComponentPreview name="date-picker-disabled" />
+
 ### Controlled

 <ComponentPreview name="date-picker-controlled" />
@@ -75,9 +80,9 @@ Control how DatePicker values are displayed with props such as `granularity`, `h

 <ComponentPreview name="date-picker-format-options" />

-### Disabled
+### Form Example

-<ComponentPreview name="date-picker-disabled" />
+<ComponentPreview name="date-picker-form-example" />

 ### Custom Indicator

@@ -85,9 +90,11 @@ Control how DatePicker values are displayed with props such as `granularity`, `h

 <ComponentPreview name="date-picker-with-custom-indicator" />

-### Form Example
+### Render Function

-<ComponentPreview name="date-picker-form-example" />
+<ComponentPreview
+  name="date-picker-render-function"
+/>

 ### International Calendar

@@ -103,48 +110,13 @@ For a complete list of supported calendar systems and their identifiers, see:
 - [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
 - [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)

-### Custom Render Function
+## Customization

-<ComponentPreview
-  name="date-picker-custom-render-function"
-/>
+### Tailwind CSS

-<RelatedComponents component="datepicker" />
+<ComponentPreview name="date-picker-custom-styles" />

-## Styling
-
-### Passing Tailwind CSS classes
-
-You can style each composition part independently:
-
-```tsx
-import {Calendar, DateField, DatePicker, Label} from '@heroui/react';
-
-function CustomDatePicker() {
-  return (
-    <DatePicker className="w-[320px] gap-2">
-      <Label className="text-sm font-semibold">Date</Label>
-      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
-        <DateField.Input>
-          {(segment) => <DateField.Segment segment={segment} />}
-        </DateField.Input>
-        <DateField.Suffix>
-          <DatePicker.Trigger className="w-full">
-            <DatePicker.TriggerIndicator className="text-default-600" />
-          </DatePicker.Trigger>
-        </DateField.Suffix>
-      </DateField.Group>
-      <DatePicker.Popover className="rounded-xl p-2">
-        <Calendar aria-label="Custom date picker calendar">
-          {/* Calendar parts */}
-        </Calendar>
-      </DatePicker.Popover>
-    </DatePicker>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize DatePicker base classes, use `@layer components`.

@@ -168,6 +140,8 @@ To customize DatePicker base classes, use `@layer components`.
 }
 ```

+## Styling Reference
+
 HeroUI follows [BEM](https://getbem.com/) naming for reusable customization.

 ### CSS Classes
@@ -190,7 +164,7 @@ DatePicker supports React Aria data attributes and pseudo states:

 ## API Reference

-### DatePicker Props
+### DatePicker

 DatePicker inherits all props from React Aria [DatePicker](https://react-aria.adobe.com/DatePicker.md).

@@ -223,3 +197,7 @@ DatePicker inherits all props from React Aria [DatePicker](https://react-aria.ad
 - [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components
 - [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree
 - [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction
+
+## Related Components
+
+<RelatedComponents component="datepicker" />
@@ -1,6 +1,7 @@
 ---
 title: DateRangePicker
 description: Composable date range picker built on React Aria DateRangePicker with DateField and RangeCalendar composition
+
 links:
  rac: DateRangePicker
  source: date-range-picker/date-range-picker.tsx
@@ -9,17 +10,15 @@ links:
  figma: true
 ---

-## Import
+## Usage

 ```tsx
 import { DateField, DateRangePicker, Label, RangeCalendar } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview name="date-range-picker-basic" />

-### Anatomy
+## Anatomy

 `DateRangePicker` follows a composition-first API. Compose `DateField` and `RangeCalendar` explicitly to control structure and styling.

@@ -67,6 +66,12 @@ export default () => (
 )
 ```

+## Examples
+
+### Disabled
+
+<ComponentPreview name="date-range-picker-disabled" />
+
 ### Controlled

 <ComponentPreview name="date-range-picker-controlled" />
@@ -81,9 +86,9 @@ Control how DateRangePicker values are displayed with props such as `granularity

 <ComponentPreview name="date-range-picker-format-options" />

-### Disabled
+### Form Example

-<ComponentPreview name="date-range-picker-disabled" />
+<ComponentPreview name="date-range-picker-form-example" />

 ### Custom Indicator

@@ -91,9 +96,11 @@ Control how DateRangePicker values are displayed with props such as `granularity

 <ComponentPreview name="date-range-picker-with-custom-indicator" />

-### Form Example
+### Render Function

-<ComponentPreview name="date-range-picker-form-example" />
+<ComponentPreview
+  name="date-range-picker-render-function"
+/>

 ### International Calendar

@@ -109,54 +116,13 @@ For a complete list of supported calendar systems and their identifiers, see:
 - [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
 - [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)

-### Custom Render Function
+## Customization

-<ComponentPreview
-  name="date-range-picker-custom-render-function"
-/>
+### Tailwind CSS

-<RelatedComponents component="daterangepicker" />
+<ComponentPreview name="date-range-picker-custom-styles" />

-## Styling
-
-### Passing Tailwind CSS classes
-
-You can style each composition part independently:
-
-```tsx
-import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react';
-
-function CustomDateRangePicker() {
-  return (
-    <DateRangePicker className="w-[360px] gap-2">
-      <Label className="text-sm font-semibold">Trip dates</Label>
-      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
-        <DateField.InputContainer>
-          <DateField.Input slot="start">
-            {(segment) => <DateField.Segment segment={segment} />}
-          </DateField.Input>
-          <DateRangePicker.RangeSeparator className="px-2 text-default" />
-          <DateField.Input slot="end">
-            {(segment) => <DateField.Segment segment={segment} />}
-          </DateField.Input>
-        </DateField.InputContainer>
-        <DateField.Suffix>
-          <DateRangePicker.Trigger className="w-full">
-            <DateRangePicker.TriggerIndicator className="text-default" />
-          </DateRangePicker.Trigger>
-        </DateField.Suffix>
-      </DateField.Group>
-      <DateRangePicker.Popover className="rounded-xl p-2">
-        <RangeCalendar aria-label="Custom range picker calendar">
-          {/* RangeCalendar parts */}
-        </RangeCalendar>
-      </DateRangePicker.Popover>
-    </DateRangePicker>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 To customize DateRangePicker base classes, use `@layer components`.

@@ -184,7 +150,9 @@ To customize DateRangePicker base classes, use `@layer components`.
 }
 ```

-HeroUI follows [BEM](https://getbem.com/) naming for reusable customization.
+## Styling Reference
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

 ### CSS Classes

@@ -207,7 +175,7 @@ DateRangePicker supports React Aria data attributes and pseudo states:

 ## API Reference

-### DateRangePicker Props
+### DateRangePicker

 DateRangePicker inherits all props from React Aria [DateRangePicker](https://react-aria.adobe.com/DateRangePicker).

@@ -242,3 +210,7 @@ DateRangePicker inherits all props from React Aria [DateRangePicker](https://rea
 - [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components
 - [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree
 - [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction
+
+## Related Components
+
+<RelatedComponents component="daterangepicker" />
@@ -1,6 +1,7 @@
 ---
 title: RangeCalendar
 description: Composable date range picker with month grid, navigation, and year picker support built on React Aria RangeCalendar
+
 links:
  rac: RangeCalendar
  source: range-calendar/range-calendar.tsx
@@ -8,17 +9,15 @@ links:
  storybook: Components/Date and Time/RangeCalendar
 ---

-## Import
+## Usage

 ```tsx
 import { RangeCalendar } from '@heroui/react';
 ```

-### Usage
-
 <ComponentPreview name="range-calendar-basic" />

-### Anatomy
+## Anatomy

 ```tsx
 import {RangeCalendar} from '@heroui/react';
@@ -42,6 +41,12 @@ export default () => (
 )
 ```

+## Examples
+
+### Disabled
+
+<ComponentPreview name="range-calendar-disabled" />
+
 ### Year Picker

 `RangeCalendar.YearPickerTrigger`, `RangeCalendar.YearPickerGrid`, and their body/cell subcomponents provide an integrated year navigation pattern.
@@ -96,10 +101,6 @@ Enable `allowsNonContiguousRanges` to allow selection across unavailable dates.

 <ComponentPreview name="range-calendar-allows-non-contiguous-ranges" />

-### Disabled
-
-<ComponentPreview name="range-calendar-disabled" />
-
 ### Read Only

 <ComponentPreview name="range-calendar-read-only" />
@@ -118,9 +119,13 @@ You can customize `RangeCalendar.Cell` children and use `RangeCalendar.CellIndic

 <ComponentPreview name="range-calendar-with-indicators" />

+### Real-World Example
+
+<ComponentPreview name="range-calendar-booking-calendar" />
+
 ### Multiple Months

-Render multiple grids with `visibleDuration` and `offset` for booking and planning experiences. Use `RangeCalendar.Heading` with an `offset` (for example, `offset={{ months: 1 }}`) in each column header to label that month.
+Render multiple grids with `visibleDuration` and `offset` for booking and planning experiences.

 <ComponentPreview name="range-calendar-multiple-months" />

@@ -134,41 +139,13 @@ The example below shows the Indian calendar system:

 **Note:** The `onChange` event always returns a date in the same calendar system as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale.

-### Real-World Example
+## Customization

-<ComponentPreview name="range-calendar-booking-calendar" />
+### Tailwind CSS

-<RelatedComponents component="range-calendar" />
+<ComponentPreview name="range-calendar-custom-styles" />

-## Styling
-
-### Passing Tailwind CSS classes
-
-```tsx
-import {RangeCalendar} from '@heroui/react';
-
-function CustomRangeCalendar() {
-  return (
-    <RangeCalendar aria-label="Trip dates" className="w-80 rounded-2xl border border-border bg-surface p-3 shadow-sm">
-      <RangeCalendar.Header className="pb-3">
-        <RangeCalendar.Heading className="text-default" />
-        <RangeCalendar.NavButton slot="previous" className="text-default" />
-        <RangeCalendar.NavButton slot="next" className="text-default" />
-      </RangeCalendar.Header>
-      <RangeCalendar.Grid>
-        <RangeCalendar.GridHeader>
-          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
-        </RangeCalendar.GridHeader>
-        <RangeCalendar.GridBody>
-          {(date) => <RangeCalendar.Cell date={date} />}
-        </RangeCalendar.GridBody>
-      </RangeCalendar.Grid>
-    </RangeCalendar>
-  );
-}
-```
-
-### Customizing the component classes
+### Global CSS

 ```css
@layer components {
@@ -186,6 +163,10 @@ function CustomRangeCalendar() {
 }
 ```

+## Styling Reference
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
 ### CSS Classes

 RangeCalendar uses these classes in `packages/styles/components/range-calendar.css` and `packages/styles/components/calendar-year-picker.css`:
@@ -225,7 +206,7 @@ RangeCalendar supports both pseudo-classes and React Aria data attributes:

 ## API Reference

-### RangeCalendar Props
+### RangeCalendar

 RangeCalendar inherits all props from React Aria [RangeCalendar](https://react-spectrum.adobe.com/react-aria/RangeCalendar.html).

@@ -305,3 +286,7 @@ For a complete list of supported calendar systems and their identifiers, see:
 - [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components
 - [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree
 - [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction
+
+## Related Components
+
+<RelatedComponents component="range-calendar" />
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
WK Wong	a7775f24f8	fix(styles): handle search icon in RTL	2026-07-18 21:38:03 +08:00
WK Wong	b5aabc4dcc	fix(styles): handle RTL	2026-07-16 17:27:40 +08:00
WK Wong	64b70de3fa	fix(tabs): handle RTL	2026-07-16 17:27:25 +08:00
WK Wong	453cde44af	fix(scroll-shadow): handle RTL	2026-07-16 17:27:08 +08:00
WK Wong	5f36e6a55c	Merge branch 'v3.2.3' into fix/HHTA-969	2026-07-14 10:54:53 +08:00
Tianen Pang	2ce851c5e9	docs(web): polish component docs (#6690 ) * docs(web): polish english component docs * docs(web): polish custom style demos * docs(web): polish chinese component docs * docs(web): update release demos * docs(web): polish tabs component docs * docs(web): polish chinese component docs * docs(web): polish chinese component docs * docs(web): prevent href scroll jumps in card and link demos * docs(web): sync status icons * fix(docs): preserve locale in showcase and component doc links * docs(web): align showcase terminology of chinese version	2026-07-14 10:51:43 +08:00
WK Wong	e0167e4e60	fix(pagination): add dir="auto"	2026-07-12 12:20:24 +08:00
WK Wong	f1c2c95551	fix(styles): handle rtl for icons	2026-07-12 12:19:59 +08:00
WK Wong	39504302db	fix(storybook): handle rtl for icons	2026-07-12 12:19:49 +08:00
WK Wong	efd805dd8e	fix(docs): handle rtl for icons	2026-07-12 12:19:29 +08:00
Stybo	35e6c65843	fix(styles): center table sortable column indicator icon (#6705 )	2026-07-12 11:36:30 +08:00
WK Wong	c41d87c00b	Merge branch 'v3.2.3' into fix/HHTA-969	2026-07-10 23:46:58 +08:00
WK Wong	9f90369563	fix(storybook): adopt logical CSS properties for RTL support	2026-07-10 12:20:56 +08:00
WK Wong	98fe452875	fix(react): adopt logical CSS properties for RTL support	2026-07-10 12:20:41 +08:00
WK Wong	59a2ed511d	fix(docs): adopt logical CSS properties for RTL support	2026-07-10 12:20:17 +08:00
WK Wong	00c833cf28	fix(styles): adopt logical CSS properties for RTL support	2026-07-09 15:47:15 +08:00