diff --git a/docs/en/carousel.md b/docs/en/carousel.md
new file mode 100644
index 0000000..0274dcc
--- /dev/null
+++ b/docs/en/carousel.md
@@ -0,0 +1,64 @@
+# Carousel
+
+**Control Functionality:** An auto-rotating carousel widget. Cards are arranged in an arc with the center card being the largest and clearest, while side cards progressively shrink and fade. Auto-rotates on a timer, and supports hover-to-flip when used with FlipCard.
+**Type:** Basic Control
+**Parent Control:** `bricks.Layout`
+
+## Initialization Parameters
+
+| Parameter | Type | Description |
+|-------|------|------|
+| `cardWidth` | number | Width of center card in px. Default: `280`. |
+| `cardHeight` | number | Height of center card in px. Default: `360`. |
+| `interval` | number | Auto-rotation interval in ms. Default: `3000`. |
+| `css` | string/object | Custom CSS class name. |
+
+## Subwidget Structure
+
+Carousel 接受多个子控件，Each subwidget becomes a carousel card:
+
+```json
+{
+  "widgettype": "Carousel",
+  "subwidgets": [
+    {"widgettype": "FlipCard", ...},
+    {"widgettype": "FlipCard", ...},
+    ...
+  ]
+}
+```
+
+Recommended to use 7-8 cards for the best visual effect.
+
+## Main Events
+
+- **`rotate`**
+  Fires after each rotation completes. Can be used to sync external indicators.
+
+## Example
+
+```json
+{
+  "widgettype": "Carousel",
+  "options": {"cardWidth": 280, "cardHeight": 360, "interval": 3000},
+  "subwidgets": [
+    {
+      "widgettype": "FlipCard",
+      "subwidgets": [
+        {"widgettype": "VBox", "subwidgets": [
+          {"widgettype": "Text", "options": {"text": "洞察入微"}},
+          {"widgettype": "Text", "options": {"text": "机器视觉检测"}}
+        ]},
+        {"widgettype": "VBox", "subwidgets": [
+          {"widgettype": "Text", "options": {"text": "毫秒级检测速度"}},
+          {"widgettype": "Text", "options": {"text": "95% 漏检率降低"}}
+        ]}
+      ]
+    }
+  ]
+}
+```
+
+## Dependencies
+
+Requires `carousel.js` (provides auto-rotation and positioning logic) and corresponding CSS styles.
diff --git a/docs/en/draggable.md b/docs/en/draggable.md
new file mode 100644
index 0000000..e4cfe85
--- /dev/null
+++ b/docs/en/draggable.md
@@ -0,0 +1,52 @@
+# Draggable
+
+**Control Functionality:** A drag-only container widget. Child widgets can be dragged out into Droppable or Sortable containers, but it does not accept items dragged in from outside.
+**Type:** Basic Control
+**Parent Control:** `bricks.Layout`
+**Dependency:** SortableJS (`Sortable.min.js`)
+
+## Initialization Parameters
+
+| Parameter | Type | Description |
+|-------|------|------|
+| `group` | string | Group name. Only containers sharing the same group can exchange items. Default: `"default"`. |
+| `type` | string | (Optional) Drag item type identifier, used for `accepts` matching on Droppable. |
+| `animation` | number | Animation duration in ms. Default: `150`. |
+
+## Subwidget Structure
+
+Each subwidget is a draggable item:
+
+```json
+{
+  "widgettype": "Draggable",
+  "options": {"group": "mygroup"},
+  "subwidgets": [
+    {"widgettype": "Text", "options": {"text": "可拖拽项 1"}},
+    {"widgettype": "Text", "options": {"text": "可拖拽项 2"}}
+  ]
+}
+```
+
+## Main Events
+
+| Event | Description |
+|-------|------|
+| `dragstart` | Drag started |
+| `dragend` | Drag ended |
+
+Event params: `{item: DOM元素}`
+
+## Example — 与 Droppable 配合
+
+```json
+{
+  "widgettype": "Draggable",
+  "options": {"group": "demo", "type": "task"},
+  "subwidgets": [
+    {"widgettype": "VBox", "options": {"css": "task-card", "data-type": "task"},
+     "subwidgets": [{"widgettype": "Text", "options": {"text": "任务 A"}}]}
+  ],
+  "binds": [{"event": "dragend", "actiontype": "script", "script": "console.log('Drag ended')"}]
+}
+```
diff --git a/docs/en/droppable.md b/docs/en/droppable.md
new file mode 100644
index 0000000..bca7e0e
--- /dev/null
+++ b/docs/en/droppable.md
@@ -0,0 +1,55 @@
+# Droppable
+
+**Control Functionality:** A drop-only container widget. Accepts items dragged in from Draggable/Sortable containers, as well as **external files** dropped from the operating system. Its own children cannot be dragged out.
+**Type:** Basic Control
+**Parent Control:** `bricks.Layout`
+**Dependency:** SortableJS (`Sortable.min.js`)
+
+## Initialization Parameters
+
+| Parameter | Type | Description |
+|-------|------|------|
+| `group` | string | Group name. Only accepts drag sources from the same group. Default: `"default"`. |
+| `accepts` | string[] | Accepted type list. For internal elements, matches the `data-type` attribute; for external files, matches MIME type or extension. e.g. `["card", "image/*", ".pdf"]`. |
+| `animation` | number | 拖拽动画时间（毫秒）。 |
+
+## 外部文件拖入
+
+File dropping is automatically enabled when `accepts` is set. Supports:
+- MIME wildcard: `"image/*"` matches all images
+- Extension: `".pdf"`, `".docx"`
+- Custom types: `"card"`, `"task"` (matches internal elements)
+
+## Main Events
+
+| Event | Description |
+|-------|------|
+| `dropadd` | An item was dropped into this container |
+| `dropremove` | An item was removed from this container (won't fire, as Droppable cannot drag out) |
+| `filedrop` | External files were dropped. `event.params.files` is an array of `{name, size, type, file}` |
+
+## Example — 接收文件
+
+```json
+{
+  "widgettype": "Droppable",
+  "options": {"group": "upload", "accepts": ["image/*", ".pdf"]},
+  "subwidgets": [
+    {"widgettype": "Text", "options": {"text": "拖入图片或PDF文件"}}
+  ],
+  "binds": [{"event": "filedrop", "actiontype": "script",
+    "script": "var fs=event.params.files;alert('收到 '+fs.length+' 个文件');"}]
+}
+```
+
+## Example — 接收内部元素
+
+```json
+{
+  "widgettype": "Droppable",
+  "options": {"group": "demo", "accepts": ["task"]},
+  "subwidgets": [],
+  "binds": [{"event": "dropadd", "actiontype": "script",
+    "script": "console.log('有任务拖入')"}]
+}
+```
diff --git a/docs/en/flipcard.md b/docs/en/flipcard.md
new file mode 100644
index 0000000..773b9a0
--- /dev/null
+++ b/docs/en/flipcard.md
@@ -0,0 +1,60 @@
+# FlipCard
+
+**Control Functionality:** A 3D flip card widget. Shows title and subtitle on the front face, and flips to reveal detailed content on the back face on mouse hover. Commonly used for product displays, feature cards, and similar scenarios.
+**Type:** Basic Control
+**Parent Control:** `bricks.JsWidget`
+
+## Initialization Parameters
+
+| Parameter | Type | Description |
+|-------|------|------|
+| `width` | string | Card width in px. Default: `280px`. |
+| `height` | string | Card height in px. Default: `360px`. |
+| `css` | string/object | Custom CSS class name. |
+
+## Subwidget Structure
+
+FlipCard accepts 2 subwidgets for front and back content respectively:
+
+```json
+{
+  "widgettype": "FlipCard",
+  "subwidgets": [
+    {"widgettype": "VBox", "subwidgets": [...]},  // 正面
+    {"widgettype": "VBox", "subwidgets": [...]}   // 背面
+  ]
+}
+```
+
+## Main Events
+
+- **`click`**
+  Fires when the card is clicked.
+
+## Example
+
+```json
+{
+  "widgettype": "FlipCard",
+  "options": {"css": "product-card"},
+  "subwidgets": [
+    {
+      "widgettype": "VBox", "options": {"css": "card-front"},
+      "subwidgets": [
+        {"widgettype": "Text", "options": {"text": "产品名称"}},
+        {"widgettype": "Text", "options": {"text": "简短描述"}}
+      ]
+    },
+    {
+      "widgettype": "VBox", "options": {"css": "card-back"},
+      "subwidgets": [
+        {"widgettype": "Text", "options": {"text": "详细说明"}}
+      ]
+    }
+  ]
+}
+```
+
+## Dependencies
+
+Requires flip animation CSS (perspective, rotateY, backface-visibility) defined in the page stylesheet, or use built-in bricks CSS class `.bricks-flipcard`.
diff --git a/docs/en/sortable.md b/docs/en/sortable.md
new file mode 100644
index 0000000..e18bf60
--- /dev/null
+++ b/docs/en/sortable.md
@@ -0,0 +1,53 @@
+# Sortable
+
+**Control Functionality:** A bidirectional sortable container widget. Child widgets can be dragged out to other containers (Droppable/Sortable), can accept items dragged from outside, and also supports internal reordering within the container.
+**Type:** Basic Control
+**Parent Control:** `bricks.Layout`
+**Dependency:** SortableJS (`Sortable.min.js`)
+
+## Initialization Parameters
+
+| Parameter | Type | Description |
+|-------|------|------|
+| `group` | string | Group name. Only containers sharing the same group can exchange items. Default: `"default"`. |
+| `animation` | number | Animation duration in ms. Default: `150`. |
+| `handle` | string | (Optional) CSS selector for the drag handle. Only matching elements can initiate dragging. |
+
+## Main Events
+
+| Event | Description |
+|-------|------|
+| `dragstart` | Drag started |
+| `dragend` | Drag ended（含 `from`/`to` 容器信息） |
+| `dropadd` | An item was dropped into this container from outside |
+| `dropremove` | An item was dragged out of this container |
+| `reorder` | The order within this container changed |
+
+## Example — 任务看板列
+
+```json
+{
+  "widgettype": "Sortable",
+  "options": {"group": "kanban", "animation": 150},
+  "subwidgets": [
+    {"widgettype": "VBox", "options": {"css": "task-card", "data-type": "task"},
+     "subwidgets": [{"widgettype": "Text", "options": {"text": "待办 1"}}]},
+    {"widgettype": "VBox", "options": {"css": "task-card", "data-type": "task"},
+     "subwidgets": [{"widgettype": "Text", "options": {"text": "待办 2"}}]}
+  ],
+  "binds": [
+    {"event": "reorder", "actiontype": "script",
+     "script": "console.log('排序已改变')"},
+    {"event": "dropadd", "actiontype": "script",
+     "script": "console.log('新任务拖入')"}
+  ]
+}
+```
+
+## Comparison
+
+| Widget | pull | put | file drop | internal sort |
+|------|------------|-----------|---------|---------|
+| Draggable | ✅ | ❌ | ❌ | ❌ |
+| Droppable | ❌ | ✅ | ✅ | ❌ |
+| Sortable | ✅ | ✅ | ❌ | ✅ |
diff --git a/docs/zh/carousel.md b/docs/zh/carousel.md
new file mode 100644
index 0000000..3cf1127
--- /dev/null
+++ b/docs/zh/carousel.md
@@ -0,0 +1,64 @@
+# Carousel
+
+控件功能：自动轮播卡片走马灯控件，多个卡片以弧形排列，居中的卡片最大最清晰，两侧渐小渐淡。自动定时旋转，支持鼠标悬停翻牌（需配合 FlipCard 使用）。
+类型：普通控件
+父类控件：`bricks.Layout`
+
+## 初始化参数
+
+| 参数名 | 类型 | 说明 |
+|-------|------|------|
+| `cardWidth` | number | 居中卡片宽度（px），默认 `280`。 |
+| `cardHeight` | number | 居中卡片高度（px），默认 `360`。 |
+| `interval` | number | 自动旋转间隔（毫秒），默认 `3000`。 |
+| `css` | string/object | 自定义 CSS 样式类名。 |
+
+## 子控件结构
+
+Carousel 接受多个子控件，每个子控件作为一张走马灯卡片：
+
+```json
+{
+  "widgettype": "Carousel",
+  "subwidgets": [
+    {"widgettype": "FlipCard", ...},
+    {"widgettype": "FlipCard", ...},
+    ...
+  ]
+}
+```
+
+推荐使用 7-8 张卡片以获得最佳视觉效果。
+
+## 主要事件
+
+- **`rotate`**
+  每次完成一次旋转时触发。可用于同步外部指示器。
+
+## 示例
+
+```json
+{
+  "widgettype": "Carousel",
+  "options": {"cardWidth": 280, "cardHeight": 360, "interval": 3000},
+  "subwidgets": [
+    {
+      "widgettype": "FlipCard",
+      "subwidgets": [
+        {"widgettype": "VBox", "subwidgets": [
+          {"widgettype": "Text", "options": {"text": "洞察入微"}},
+          {"widgettype": "Text", "options": {"text": "机器视觉检测"}}
+        ]},
+        {"widgettype": "VBox", "subwidgets": [
+          {"widgettype": "Text", "options": {"text": "毫秒级检测速度"}},
+          {"widgettype": "Text", "options": {"text": "95% 漏检率降低"}}
+        ]}
+      ]
+    }
+  ]
+}
+```
+
+## 依赖
+
+需引入 `carousel.js`（提供自动旋转和定位逻辑），以及对应的 CSS 样式。
diff --git a/docs/zh/draggable.md b/docs/zh/draggable.md
new file mode 100644
index 0000000..4801664
--- /dev/null
+++ b/docs/zh/draggable.md
@@ -0,0 +1,52 @@
+# Draggable
+
+控件功能：可拖拽容器控件。子控件可从中拖出到其他 Droppable 或 Sortable 容器中，但自身不接收外部拖入。
+类型：普通控件
+父类控件：`bricks.Layout`
+依赖：SortableJS（`Sortable.min.js`）
+
+## 初始化参数
+
+| 参数名 | 类型 | 说明 |
+|-------|------|------|
+| `group` | string | 分组名称，相同 group 的控件之间可互相拖拽。默认 `"default"`。 |
+| `type` | string | （可选）拖拽项类型标识，用于 Droppable 的 `accepts` 类型匹配。 |
+| `animation` | number | 拖拽动画时间（毫秒），默认 `150`。 |
+
+## 子控件结构
+
+每个子控件即为一个可拖拽项：
+
+```json
+{
+  "widgettype": "Draggable",
+  "options": {"group": "mygroup"},
+  "subwidgets": [
+    {"widgettype": "Text", "options": {"text": "可拖拽项 1"}},
+    {"widgettype": "Text", "options": {"text": "可拖拽项 2"}}
+  ]
+}
+```
+
+## 主要事件
+
+| 事件名 | 说明 |
+|-------|------|
+| `dragstart` | 开始拖拽 |
+| `dragend` | 拖拽结束 |
+
+事件参数：`{item: DOM元素}`
+
+## 示例 — 与 Droppable 配合
+
+```json
+{
+  "widgettype": "Draggable",
+  "options": {"group": "demo", "type": "task"},
+  "subwidgets": [
+    {"widgettype": "VBox", "options": {"css": "task-card", "data-type": "task"},
+     "subwidgets": [{"widgettype": "Text", "options": {"text": "任务 A"}}]}
+  ],
+  "binds": [{"event": "dragend", "actiontype": "script", "script": "console.log('拖拽结束')"}]
+}
+```
diff --git a/docs/zh/droppable.md b/docs/zh/droppable.md
new file mode 100644
index 0000000..88ee9c1
--- /dev/null
+++ b/docs/zh/droppable.md
@@ -0,0 +1,55 @@
+# Droppable
+
+控件功能：可接收拖入的容器控件。支持接收从 Draggable/Sortable 拖出的内部元素，以及从操作系统拖入的**外部文件**。自身子控件不可拖出。
+类型：普通控件
+父类控件：`bricks.Layout`
+依赖：SortableJS（`Sortable.min.js`）
+
+## 初始化参数
+
+| 参数名 | 类型 | 说明 |
+|-------|------|------|
+| `group` | string | 分组名称，只接收同 group 的拖拽源。默认 `"default"`。 |
+| `accepts` | string[] | 接受的类型列表。对内部元素匹配 `data-type` 属性；对外部文件匹配 MIME 类型或扩展名。如 `["card", "image/*", ".pdf"]`。 |
+| `animation` | number | 拖拽动画时间（毫秒）。 |
+
+## 外部文件拖入
+
+设置 `accepts` 后自动启用文件拖入。支持：
+- MIME 通配：`"image/*"` 匹配所有图片
+- 扩展名：`".pdf"`、`".docx"`
+- 自定义类型：`"card"`、`"task"`（匹配内部元素）
+
+## 主要事件
+
+| 事件名 | 说明 |
+|-------|------|
+| `dropadd` | 有内部元素拖入本容器 |
+| `dropremove` | 有内部元素被拖出（不会发生，因 Droppable 不可拖出） |
+| `filedrop` | 有外部文件拖入。`event.params.files` 为文件数组，每项含 `{name, size, type, file}` |
+
+## 示例 — 接收文件
+
+```json
+{
+  "widgettype": "Droppable",
+  "options": {"group": "upload", "accepts": ["image/*", ".pdf"]},
+  "subwidgets": [
+    {"widgettype": "Text", "options": {"text": "拖入图片或PDF文件"}}
+  ],
+  "binds": [{"event": "filedrop", "actiontype": "script",
+    "script": "var fs=event.params.files;alert('收到 '+fs.length+' 个文件');"}]
+}
+```
+
+## 示例 — 接收内部元素
+
+```json
+{
+  "widgettype": "Droppable",
+  "options": {"group": "demo", "accepts": ["task"]},
+  "subwidgets": [],
+  "binds": [{"event": "dropadd", "actiontype": "script",
+    "script": "console.log('有任务拖入')"}]
+}
+```
diff --git a/docs/zh/flipcard.md b/docs/zh/flipcard.md
new file mode 100644
index 0000000..1d596c9
--- /dev/null
+++ b/docs/zh/flipcard.md
@@ -0,0 +1,60 @@
+# FlipCard
+
+控件功能：一个可翻转的卡片控件，正面显示标题和副标题，鼠标悬停时 3D 翻转为背面显示详细信息。常用于产品展示、功能卡片等场景。
+类型：普通控件
+父类控件：`bricks.JsWidget`
+
+## 初始化参数
+
+| 参数名 | 类型 | 说明 |
+|-------|------|------|
+| `width` | string | 卡片宽度，默认 `280px`。 |
+| `height` | string | 卡片高度，默认 `360px`。 |
+| `css` | string/object | 自定义 CSS 样式类名。 |
+
+## 子控件结构
+
+FlipCard 接受 2 个子控件（subwidgets），分别为正面和背面内容：
+
+```json
+{
+  "widgettype": "FlipCard",
+  "subwidgets": [
+    {"widgettype": "VBox", "subwidgets": [...]},  // 正面
+    {"widgettype": "VBox", "subwidgets": [...]}   // 背面
+  ]
+}
+```
+
+## 主要事件
+
+- **`click`**
+  当卡片被点击时触发。
+
+## 示例
+
+```json
+{
+  "widgettype": "FlipCard",
+  "options": {"css": "product-card"},
+  "subwidgets": [
+    {
+      "widgettype": "VBox", "options": {"css": "card-front"},
+      "subwidgets": [
+        {"widgettype": "Text", "options": {"text": "产品名称"}},
+        {"widgettype": "Text", "options": {"text": "简短描述"}}
+      ]
+    },
+    {
+      "widgettype": "VBox", "options": {"css": "card-back"},
+      "subwidgets": [
+        {"widgettype": "Text", "options": {"text": "详细说明"}}
+      ]
+    }
+  ]
+}
+```
+
+## 依赖
+
+需要在页面 CSS 中定义翻转动画样式（perspective、rotateY、backface-visibility），或使用 bricks 内置 CSS 类 `.bricks-flipcard`。
diff --git a/docs/zh/sortable.md b/docs/zh/sortable.md
new file mode 100644
index 0000000..ca899b8
--- /dev/null
+++ b/docs/zh/sortable.md
@@ -0,0 +1,53 @@
+# Sortable
+
+控件功能：双向拖拽排序容器控件。子控件可拖出到其他容器（Droppable/Sortable），也可接收外部拖入，同时支持本容器内拖拽排序。
+类型：普通控件
+父类控件：`bricks.Layout`
+依赖：SortableJS（`Sortable.min.js`）
+
+## 初始化参数
+
+| 参数名 | 类型 | 说明 |
+|-------|------|------|
+| `group` | string | 分组名称。相同 group 的控件之间可互相拖拽。默认 `"default"`。 |
+| `animation` | number | 拖拽动画时间（毫秒），默认 `150`。 |
+| `handle` | string | （可选）CSS 选择器，指定拖拽手柄，只有匹配的元素可触发拖拽。 |
+
+## 主要事件
+
+| 事件名 | 说明 |
+|-------|------|
+| `dragstart` | 开始拖拽 |
+| `dragend` | 拖拽结束（含 `from`/`to` 容器信息） |
+| `dropadd` | 有元素从外部拖入本容器 |
+| `dropremove` | 有元素被拖出本容器 |
+| `reorder` | 本容器内顺序发生变化 |
+
+## 示例 — 任务看板列
+
+```json
+{
+  "widgettype": "Sortable",
+  "options": {"group": "kanban", "animation": 150},
+  "subwidgets": [
+    {"widgettype": "VBox", "options": {"css": "task-card", "data-type": "task"},
+     "subwidgets": [{"widgettype": "Text", "options": {"text": "待办 1"}}]},
+    {"widgettype": "VBox", "options": {"css": "task-card", "data-type": "task"},
+     "subwidgets": [{"widgettype": "Text", "options": {"text": "待办 2"}}]}
+  ],
+  "binds": [
+    {"event": "reorder", "actiontype": "script",
+     "script": "console.log('排序已改变')"},
+    {"event": "dropadd", "actiontype": "script",
+     "script": "console.log('新任务拖入')"}
+  ]
+}
+```
+
+## 对比
+
+| 控件 | pull（拖出） | put（接收） | 文件拖入 | 内部排序 |
+|------|------------|-----------|---------|---------|
+| Draggable | ✅ | ❌ | ❌ | ❌ |
+| Droppable | ❌ | ✅ | ✅ | ❌ |
+| Sortable | ✅ | ✅ | ❌ | ✅ |