diff --git a/packages/opendesign/src/badge/__docs__/__case__/badgeUsage.ts b/packages/opendesign/src/badge/__docs__/__case__/BadgeUsage.vue
similarity index 34%
rename from packages/opendesign/src/badge/__docs__/__case__/badgeUsage.ts
rename to packages/opendesign/src/badge/__docs__/__case__/BadgeUsage.vue
index 4742ae0383b6e0da5bf176923706911d5149fc27..67ee2061e976e0f22d4e4f43a1045930180c7942 100644
--- a/packages/opendesign/src/badge/__docs__/__case__/badgeUsage.ts
+++ b/packages/opendesign/src/badge/__docs__/__case__/BadgeUsage.vue
@@ -1,6 +1,33 @@
+<docs lang="md">
+<!-- zh-CN -->
+
+### 使用
+
+徽标包含 `primary`、`success`、`warning`、`danger` 四种主题色。
+
+徽标 `value` 参数支持数字和文本两种类型的值，当为数字时 `max` 参数会影响值的显示。
+
+徽标支持小红点样式，小红点中不会显示徽标内容。
+
+徽标可以通过 `offset` 设置偏移位置。
+
+<!-- en-US -->
+
+### Usage
+
+The badge includes four theme colors: `primary`, `success`, `warning`, and `danger`.
+
+The `value` parameter of the badge supports both numeric and text values. When it is numeric, the `max` parameter affects how the value is displayed.
+
+The badge supports a small dot style, where the content is not displayed in the dot.
+
+The badge can set an offset position using the `offset` property.
+</docs>
+<script setup lang="ts">
 import { propsToAttrStr } from '../../../_demo/utils';
+import { DocDemoSchema, DocDemoTemplate } from '../../../_demo/types';
 
-export const schema = {
+const _schema = {
   value: {
     type: 'string',
     default: '100',
@@ -21,38 +48,27 @@ export const schema = {
   'offset-x': {
     type: 'number',
     default: 0,
-    // min: 0,
   },
   'offset-y': {
     type: 'number',
     default: 0,
   },
-};
+} satisfies Record<string, DocDemoSchema>;
+
 const NUMBER_REGEXP = /^\d+$/;
-export const template = (_props: Record<string, any>) => {
-  const { 'offset-x': offsetX, 'offset-y': offsetY, value } = _props;
+const _template: DocDemoTemplate<typeof _schema> = (props) => {
+  const { 'offset-x': offsetX, 'offset-y': offsetY, value } = props;
   const isNumber = NUMBER_REGEXP.test(value);
 
-  return `<OBadge 
-  ${propsToAttrStr(_props, ['offset-x', 'offset-y', 'value'])}
+  return `
+<OBadge
+  ${propsToAttrStr(props, ['offset-x', 'offset-y', 'value'])}
   ${isNumber ? `:value="${parseInt(value)}"` : `value="${value}"`}
   ${offsetX || offsetY ? `:offset="[${offsetX}, ${offsetY}]"` : ''}
-  >
-    <img src="/avatar.svg" alt="avatar" style="width: 48px; height: 48px;" />
-  </OBadge>`;
+>
+  <img src="/avatar.svg" alt="avatar" style="width: 48px; height: 48px;" />
+</OBadge>`;
 };
 
-export const docs = {
-  'zh-CN':
-    '### 使用\n' +
-    '徽标包含 `primary`、`success`、`warning`、`danger` 四种主题色。\n\n' +
-    '徽标 `value` 参数支持数字和文本两种类型的值，当为数字时 `max` 参数会影响值的显示。\n\n' +
-    '徽标支持小红点样式，小红点中不会显示徽标内容。\n\n' +
-    '徽标可以通过 `offset` 设置偏移位置。',
-  'en-US':
-    '### Usage\n' +
-    'The badge includes four theme colors: `primary`, `success`, `warning`, and `danger`.\n\n' +
-    'The `value` parameter of the badge supports both numeric and text values. When it is numeric, the `max` parameter affects how the value is displayed.\n\n' +
-    'The badge supports a small dot style, where the content is not displayed in the dot.\n\n' +
-    'The badge can set an offset position using the `offset` property.',
-};
+const _ctx = {};
+</script>
diff --git a/packages/opendesign/src/badge/__docs__/index.en-US.md b/packages/opendesign/src/badge/__docs__/index.en-US.md
index ad133c5cbaf993a710212f7f349344e55b148a9a..f75fa7269dae7ebd5d86f1ca5cf2f78bf6c1ad96 100644
--- a/packages/opendesign/src/badge/__docs__/index.en-US.md
+++ b/packages/opendesign/src/badge/__docs__/index.en-US.md
@@ -6,7 +6,7 @@ sidebar: OBadge
 
 ## Demo
 
-<!-- @usage badgeUsage -->
+<!-- @usage BadgeUsage -->
 
 <!-- @case BadgeSlot -->
 
diff --git a/packages/opendesign/src/badge/__docs__/index.zh-CN.md b/packages/opendesign/src/badge/__docs__/index.zh-CN.md
index 1b961e5c002054032647fd39ec9237973214db8e..77039325f863b16fa54217cce3b97f6362cf260d 100644
--- a/packages/opendesign/src/badge/__docs__/index.zh-CN.md
+++ b/packages/opendesign/src/badge/__docs__/index.zh-CN.md
@@ -6,7 +6,7 @@ sidebar: OBadge 徽标
 
 ## 示例
 
-<!-- @usage badgeUsage -->
+<!-- @usage BadgeUsage -->
 
 <!-- @case BadgeSlot -->
 
diff --git a/packages/opendesign/src/button/__docs__/__case__/btnUsage.ts b/packages/opendesign/src/button/__docs__/__case__/BtnUsage.vue
similarity index 39%
rename from packages/opendesign/src/button/__docs__/__case__/btnUsage.ts
rename to packages/opendesign/src/button/__docs__/__case__/BtnUsage.vue
index 2a90027e098afde7543d51e47a941be61e473f0f..84637fae79334694497ccaa30076442ed5e40308 100644
--- a/packages/opendesign/src/button/__docs__/__case__/btnUsage.ts
+++ b/packages/opendesign/src/button/__docs__/__case__/BtnUsage.vue
@@ -1,39 +1,41 @@
-import { propsToAttrStr } from '../../../_demo/utils';
+<docs lang="md">
+<!-- zh-CN -->
 
-// 该导出会作为该使用示例的文案，文案是markdown格式
-export const docs = {
-  'zh-CN':
-    '按钮包含 `primary`、`success`、`warning`、`danger` 四种主题色；\n\n' +
-    '三种尺寸：`small`、`medium`、`large` ；\n\n' +
-    '三种形状：`solid`、`outline`、`text` ；\n\n' +
-    '禁用状态：`disabled` ；\n\n' +
-    '加载状态：`loading` ；\n\n' +
-    '按钮的圆角可以通过 `pill` 设置为半圆，也可以是 css 属性 `border-radius` 能够接受的其它值。',
-  'en-US':
-    'The button includes four theme colors: `primary`, `success`, `warning`, and `danger`;\n\n' +
-    'Three sizes: `small`, `medium`, and `large`;\n\n' +
-    'Three shapes: `solid`, `outline`, and `text`;\n\n' +
-    'Disabled state: `disabled`;\n\n' +
-    'Loading state: `loading`;\n\n' +
-    'The button\'s radius can be set to half circle by setting `pill` to `true`, or to css property `border-radius` accepted values.',
-};
+### 使用
 
-// 该模板会在运行时被编译为vue组件，同时作为组件的源码供用户查看和复制
-export const template = (_props: Record<string, any>) => {
-  const { 'icon(slot)': iconSlot, 'suffix(slot)': suffixSlot } = _props;
-  let innerHTML = '';
-  if (iconSlot) {
-    innerHTML += '\n<template #icon><OIconChecked /></template>';
-  }
-  innerHTML += '\nButton';
-  if (suffixSlot) {
-    innerHTML += '\n<template #suffix><OIconSearch /></template>';
-  }
-  return `<OButton ${propsToAttrStr(_props, ['icon(slot)', 'suffix(slot)'])}>${innerHTML}\n</OButton>`;
-};
+按钮包含 `primary`、`success`、`warning`、`danger` 四种主题色；
+
+三种尺寸：`small`、`medium`、`large` ；
+
+三种形状：`solid`、`outline`、`text` ；
+
+禁用状态：`disabled` ；
+
+加载状态：`loading` ；
+
+按钮的圆角可以通过 `pill` 设置为半圆，也可以是 css 属性 `border-radius` 能够接受的其它值。
+
+<!-- en-US -->
+
+### Usage
 
-// 该配置会生成表单控件，表单控件选取的值会作为 template 函数的参数
-export const schema = {
+The button includes four theme colors: `primary`, `success`, `warning`, and `danger`;
+
+Three sizes: `small`, `medium`, and `large`;
+
+Three shapes: `solid`, `outline`, and `text`;
+
+Disabled state: `disabled`;
+
+Loading state: `loading`;
+
+The button's radius can be set to half circle by setting `pill` to `true`, or to css property `border-radius` accepted values.
+</docs>
+<script setup lang="ts">
+import { propsToAttrStr } from '../../../_demo/utils';
+import { DocDemoSchema, DocDemoTemplate } from '../../../_demo/types';
+
+const _schema = {
   color: {
     type: 'list',
     list: ['normal', 'primary', 'success', 'warning', 'danger'],
@@ -64,4 +66,20 @@ export const schema = {
     type: 'boolean',
     default: true,
   },
+} satisfies Record<string, DocDemoSchema>;
+
+const _template: DocDemoTemplate<typeof _schema> = (props) => {
+  const { 'icon(slot)': iconSlot, 'suffix(slot)': suffixSlot } = props;
+  let innerHTML = '';
+  if (iconSlot) {
+    innerHTML += '\n<template #icon><OIconChecked /></template>';
+  }
+  innerHTML += '\nButton';
+  if (suffixSlot) {
+    innerHTML += '\n<template #suffix><OIconSearch /></template>';
+  }
+  return `<OButton ${propsToAttrStr(props, ['icon(slot)', 'suffix(slot)'])}>${innerHTML}\n</OButton>`;
 };
+
+const _ctx = {};
+</script>
diff --git a/packages/opendesign/src/button/__docs__/index.en-US.md b/packages/opendesign/src/button/__docs__/index.en-US.md
index 182a2065273e4a52aa05d34e25fd7fff0b96e541..b81cf8ee88e5e2e9afa07209b0cf66fccba69a71 100644
--- a/packages/opendesign/src/button/__docs__/index.en-US.md
+++ b/packages/opendesign/src/button/__docs__/index.en-US.md
@@ -4,12 +4,9 @@ sidebar: OButton
 
 # Button
 
-## Usage
-
-<!-- @usage btnUsage -->
-
 ## Demo
 
+<!-- @usage BtnUsage -->
 <!-- @case BtnIconSize -->
 <!-- @case BtnLoading -->
 <!-- @case BtnRound -->
diff --git a/packages/opendesign/src/button/__docs__/index.zh-CN.md b/packages/opendesign/src/button/__docs__/index.zh-CN.md
index d5d0f33a231384e379ef9bd482679a86806984a6..e03921b6f6a33092ffd4602895708f9b02cb979f 100644
--- a/packages/opendesign/src/button/__docs__/index.zh-CN.md
+++ b/packages/opendesign/src/button/__docs__/index.zh-CN.md
@@ -4,12 +4,9 @@ sidebar: OButton 按钮
 
 # 按钮
 
-## 使用
-
-<!-- @usage btnUsage -->
-
 ## 示例
 
+<!-- @usage BtnUsage -->
 <!-- @case BtnIconSize -->
 <!-- @case BtnLoading -->
 <!-- @case BtnRound -->
diff --git a/packages/opendesign/src/card/__docs__/__case__/cardUsage.ts b/packages/opendesign/src/card/__docs__/__case__/CardUsage.vue
similarity index 36%
rename from packages/opendesign/src/card/__docs__/__case__/cardUsage.ts
rename to packages/opendesign/src/card/__docs__/__case__/CardUsage.vue
index 6863edc019caf4beb087aeebcd1ba0aa0757ebac..eefee6d8b7197565940ca9abfe50f2a762d5e7fb 100644
--- a/packages/opendesign/src/card/__docs__/__case__/cardUsage.ts
+++ b/packages/opendesign/src/card/__docs__/__case__/CardUsage.vue
@@ -1,8 +1,74 @@
+<docs lang="md">
+<!-- zh-CN -->
+
+### 使用
+
+OCard 分为图文卡片，和图标卡片。
+
+1. 图文卡片：给 `cover` 设置图片链接，并可通过 `coverRadio` 设置该图片长宽比，通过 `coverFit` 设置图片填充方式
+2. 图标卡片：给 `icon` 设置值，可以是图片链接或组件
+
+通过 `layout` 设置卡片布局方式，包含垂直布局、水平布局以及水平反向布局
+
+设置卡片标题
+
+1. 通过 `title` 设置标题内容
+2. 通过 `titleRow` 设置标题高度：`height: calc(title-row * line-height)`
+3. 通过 `titleMaxRow` 设置标题最大行数，高于该行数时显示省略号。**注**：通过`-webkit-line-clamp`实现；一般而言 `titleRow` 的值与 `titleMaxRow` 值应该一致
+
+设置卡片内容
+
+1. 通过 `detail` 设置标题内容
+2. 通过 `detailRow` 设置标题高度 `height: calc(detail-row * line-height)`
+3. 通过 `detailMaxRow` 设置标题最大行数，高于该行数时显示省略号。**注**：通过`-webkit-line-clamp`实现；一般而言 `detailRow` 的值与 `detailMaxRow` 值应该一致
+
+其它
+
+1. `hoverable` 控制卡片是否有鼠标悬停阴影
+2. `href` 设置卡片跳转链接；**注**：设置 `href` 属性后，卡片将以 `a` 标签渲染
+3. `cursor` 控制鼠标悬停样式；当值为 `auto` 时，若设置了 `href` 属性，鼠标悬停样式为 `pointer`
+4. `noResponsive` 值为真时，卡片尺寸 (间距、字体、行高等) 将不会随着视口尺寸改变而改变
+
+<!-- en-US -->
+
+### Usage
+
+OCard consists of image cards and icon cards.
+
+1. Image card: Set the image link to `cover`, and set the image aspect ratio through `coverRadio`, and set image fill mode through `coverFit`
+2. Icon card: Set `icon` value to an image link or component
+
+Set card layout mode via `layout`, which includes vertical layout, horizontal layout, and horizontal reverse layout
+
+Configure card title
+
+1. Set title content through `title`
+2. Set title height through `titleRow`: `height: calc(title-row * line-height)`
+3. Set maximum title rows through `titleMaxRow`. Ellipsis will display when exceeding this value.
+   **Note**: Implemented via `-webkit-line-clamp`; `titleRow` value should generally match `titleMaxRow`
+
+Configure card content
+
+1. Set content text through `detail`
+2. Set content height through `detailRow`: `height: calc(detail-row * line-height)`
+3. Set maximum content rows through `detailMaxRow`. Ellipsis will display when exceeding this value.
+   **Note**: Implemented via `-webkit-line-clamp`; `detailRow` value should generally match `detailMaxRow`
+
+Other features
+
+1. `hoverable` controls card shadow on mouse hover
+2. `href` sets card navigation link; **Note**: Setting `href` will render card as `a` tag
+3. `cursor` controls mouse hover style; when set to `auto`, cursor shows as `pointer` if `href` is configured
+4. When `noResponsive` is true, card dimensions (spacing, font size, line height, etc.) remain fixed regardless of viewport size changes
+</docs>
+<script setup lang="ts">
 import { propsToAttrStr } from '../../../_demo/utils';
+import { DocDemoSchema, DocDemoTemplate } from '../../../_demo/types';
 
 const LOREM =
   'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.';
-export const schema = {
+
+const _schema = {
   layout: {
     type: 'list',
     default: 'v',
@@ -58,9 +124,9 @@ export const schema = {
     default: false,
     label: 'close responsive',
   },
-};
+} satisfies Record<string, DocDemoSchema>;
 
-export const template = (props: Record<string, any>) => {
+const _template: DocDemoTemplate<typeof _schema> = (props) => {
   const { coverOrIcon, titleRow, detailRow } = props;
   let attrs = '';
   if (coverOrIcon === 'cover') {
@@ -79,43 +145,5 @@ export const template = (props: Record<string, any>) => {
   return `<OCard ${propsToAttrStr(props, ['coverOrIcon', 'titleRow', 'detailRow'])}${attrs} />`;
 };
 
-export const docs = {
-  'zh-CN':
-    '### 使用\n' +
-    'OCard 分为图文卡片，和图标卡片。\n' +
-    '1. 图文卡片：给 `cover` 设置图片链接，并可通过 `coverRadio` 设置该图片长宽比，通过 `coverFit` 设置图片填充方式\n' +
-    '2. 图标卡片：给 `icon` 设置值，可以是图片链接或组件\n\n' +
-    '通过 `layout` 设置卡片布局方式，包含垂直布局、水平布局以及水平反向布局\n\n' +
-    '设置卡片标题\n' +
-    '1. 通过 `title` 设置标题内容\n' +
-    '2. 通过 `titleRow` 设置标题高度：`height: calc(title-row * line-height)`\n' +
-    '3. 通过 `titleMaxRow` 设置标题最大行数，高于该行数时显示省略号。**注**：通过`-webkit-line-clamp`实现；一般而言 `titleRow` 的值与 `titleMaxRow` 值应该一致\n\n' +
-    '设置卡片内容\n' +
-    '1. 通过 `detail` 设置标题内容\n' +
-    '2. 通过 `detailRow` 设置标题高度 `height: calc(detail-row * line-height)`\n' +
-    '3. 通过 `detailMaxRow` 设置标题最大行数，高于该行数时显示省略号。**注**：通过`-webkit-line-clamp`实现；一般而言 `detailRow` 的值与 `detailMaxRow` 值应该一致\n\n' +
-    '其它\n' +
-    '1. `hoverable` 控制卡片是否有鼠标悬停阴影\n' +
-    '2. `href` 设置卡片跳转链接；**注**：设置 `href` 属性后，卡片将以 `a` 标签渲染\n' +
-    '3. `cursor` 控制鼠标悬停样式；当值为 `auto` 时，若设置了 `href` 属性，鼠标悬停样式为 `pointer`\n' +
-    '4. `noResponsive` 值为真时，卡片尺寸 (间距、字体、行高等) 将不会随着视口尺寸改变而改变',
-  'en-US':
-    '### Usage\n' +
-    'OCard consists of image cards and icon cards.\n' +
-    '1. Image card: Set the image link to `cover`, and set the image aspect ratio through `coverRadio`, and set image fill mode through `coverFit`\n' +
-    '2. Icon card: Set `icon` value to an image link or component\n\n' +
-    'Set card layout mode via `layout`, which includes vertical layout, horizontal layout, and horizontal reverse layout\n\n' +
-    'Configure card title\n' +
-    '1. Set title content through `title`\n' +
-    '2. Set title height through `titleRow`: `height: calc(title-row * line-height)`\n' +
-    '3. Set maximum title rows through `titleMaxRow`. Ellipsis will display when exceeding this value. **Note**: Implemented via `-webkit-line-clamp`; `titleRow` value should generally match `titleMaxRow`\n\n' +
-    'Configure card content\n' +
-    '1. Set content text through `detail`\n' +
-    '2. Set content height through `detailRow`: `height: calc(detail-row * line-height)`\n' +
-    '3. Set maximum content rows through `detailMaxRow`. Ellipsis will display when exceeding this value. **Note**: Implemented via `-webkit-line-clamp`; `detailRow` value should generally match `detailMaxRow`\n\n' +
-    'Other features\n' +
-    '1. `hoverable` controls card shadow on mouse hover\n' +
-    '2. `href` sets card navigation link; **Note**: Setting `href` will render card as `a` tag\n' +
-    '3. `cursor` controls mouse hover style; when set to `auto`, cursor shows as `pointer` if `href` is configured\n' +
-    '4. When `noResponsive` is true, card dimensions (spacing, font size, line height, etc.) remain fixed regardless of viewport size changes',
-};
+const _ctx = {};
+</script>
diff --git a/packages/opendesign/src/card/__docs__/index.en-US.md b/packages/opendesign/src/card/__docs__/index.en-US.md
index c1283830ecad68c5bc14b21ed92a046e39b7fff3..d14192e22fcd0432bf3f0f765edb44dc5a246e64 100644
--- a/packages/opendesign/src/card/__docs__/index.en-US.md
+++ b/packages/opendesign/src/card/__docs__/index.en-US.md
@@ -6,7 +6,7 @@ sidebar: OCard
 
 ## Demo
 
-<!-- @usage cardUsage -->
+<!-- @usage CardUsage -->
 <!-- @case CardSlot -->
 
 ## API
diff --git a/packages/opendesign/src/card/__docs__/index.zh-CN.md b/packages/opendesign/src/card/__docs__/index.zh-CN.md
index 64ca8a697c09873d5e2c5be31ad87470a11e8c6b..1d36e82266b183d1ca6bf9260f9352647e46aaf5 100644
--- a/packages/opendesign/src/card/__docs__/index.zh-CN.md
+++ b/packages/opendesign/src/card/__docs__/index.zh-CN.md
@@ -6,7 +6,7 @@ sidebar: OCard 卡片
 
 ## 示例
 
-<!-- @usage cardUsage -->
+<!-- @usage CardUsage -->
 <!-- @case CardSlot -->
 
 ## API
diff --git a/packages/opendesign/src/cascader/__docs__/__case__/CascaderUsage.vue b/packages/opendesign/src/cascader/__docs__/__case__/CascaderUsage.vue
new file mode 100644
index 0000000000000000000000000000000000000000..ac13117321db4ee5f2bb844a79be86baa816d417
--- /dev/null
+++ b/packages/opendesign/src/cascader/__docs__/__case__/CascaderUsage.vue
@@ -0,0 +1,172 @@
+<docs lang="md">
+<!-- zh-CN -->
+
+### 使用
+
+选中值: 通过 `modelValue` 完成双向绑定。`modelValue`的数据类型为`CascaderValueT`
+
+圆角：通过 `round` 属性设置圆角，值为 `border-radius` 的值，或者 `pill`(半圆) 这个特殊值
+
+按钮样式：通过 `variant` 属性设置按钮样式，值为 `solid`(实心)、`outline`(描边)、`text`(文字) 三种
+
+选项框显示位置：通过 `optionPosition` 属性设置：
+
+- `top`：顶部， `bottom`：底部，`left`：左侧，`right`：右侧
+- `tl`, `tr`, `bl`, `br`, `lt`, `lb`, `rt`, `rb`：第一个字母表示位置，第二个字母表示对齐方式
+
+  | 值  | 描述                 |
+  | --- | -------------------- |
+  | tl  | 显示在顶部，左对齐   |
+  | tr  | 显示在顶部，右对齐   |
+  | bl  | 显示在底部，左对齐   |
+  | br  | 显示在底部，右对齐   |
+  | lt  | 显示在左侧，顶部对齐 |
+  | lb  | 显示在左侧，底部对齐 |
+  | rt  | 显示在右侧，顶部对齐 |
+  | rb  | 显示在右侧，底部对齐 |
+
+选项: 通过 `options` 属性设置选项。`options` 的数据类型为 `CascaderOptionT[]`：
+
+```ts:line-numbers
+type CascaderNodeValueT = string | number;
+type CascaderNodePathT = Array<CascaderNodeValueT>;
+// modelValue 的数据类型
+type CascaderValueT = CascaderNodeValueT | CascaderNodePathT;
+
+// options 的数据类型
+type CascaderOptionT = {
+  value: CascaderNodeValueT;
+  label?: string;
+  children?: CascaderOptionT[];
+};
+```
+
+<!-- en-US -->
+
+### Usage
+
+Selected value: Achieve two-way binding via `modelValue`.The type of `options` is `Array<PopupOptionT>`
+
+Rounded corners: Set via the `round` property, accepts valid `border-radius` values or the special value `pill` (half-circle).
+
+Button style: Configure via the `variant` property, available values: `solid`, `outline`, `text`.
+
+Option box position: Set via `optionPosition`:
+
+- `top`, `bottom`, `left`, `right`: Basic positions
+- `tl`, `tr`, `bl`, `br`, `lt`, `lb`, `rt`, `rb`: First letter indicates position, second letter indicates alignment
+
+  | Value | Description           |
+  | ----- | --------------------- |
+  | tl    | Top, left-aligned     |
+  | tr    | Top, right-aligned    |
+  | bl    | Bottom, left-aligned  |
+  | br    | Bottom, right-aligned |
+  | lt    | Left, top-aligned     |
+  | lb    | Left, bottom-aligned  |
+  | rt    | Right, top-aligned    |
+  | rb    | Right, bottom-aligned |
+
+Options: Configure via the `options` property. The type of `options` is `Array<PopupOptionT>`:
+
+```ts:line-numbers
+type CascaderNodeValueT = string | number;
+type CascaderNodePathT = Array<CascaderNodeValueT>;
+// CascaderValueT is the type of modelValue.
+type CascaderValueT = CascaderNodeValueT | CascaderNodePathT;
+
+// CascaderOptionT is the type of options.
+type CascaderOptionT = {
+  value: CascaderNodeValueT;
+  label?: string;
+  children?: CascaderOptionT[];
+};
+```
+</docs>
+<script lang="ts" setup>
+import { reactive } from 'vue';
+import { DocDemoTemplate, DocDemoSchema } from '../../../_demo/types';
+import { propsToAttrStr } from '../../../_demo/utils';
+
+const _schema = {
+  'path-mode': {
+    type: 'boolean',
+    default: false,
+    label: 'path mode',
+  },
+  round: {
+    type: 'list',
+    list: ['pill', '12px', 'var(--o-radius-l)'],
+  },
+  variant: {
+    type: 'list',
+    list: ['solid', 'outline', 'text'],
+  },
+  placeholder: {
+    type: 'string',
+    default: 'Please select',
+  },
+  'option-position': {
+    type: 'list',
+    list: ['top', 'tl', 'tr', 'bottom', 'bl', 'br', 'left', 'lt', 'lb', 'right', 'rt', 'rb'],
+    default: 'bl',
+    label: 'option position',
+  },
+} satisfies Record<string, DocDemoSchema>;
+
+const _ctx = reactive({
+  modelValue: '' as string | number | Array<string | number>,
+  options: [
+    {
+      label: 'Option 1',
+      value: '1',
+      children: [
+        {
+          label: 'Sub-option 1-1',
+          value: '1-1',
+          children: [
+            {
+              label: 'Sub-option 1-1-1',
+              value: '1-1-1',
+            },
+            {
+              label: 'Sub-option 1-1-2',
+              value: '1-1-2',
+            },
+          ],
+        },
+        {
+          label: 'Sub-option 1-2',
+          value: '1-2',
+        },
+      ],
+    },
+    {
+      label: 'Option 2',
+      value: '2',
+      children: [
+        {
+          label: 'Sub-option 2.1',
+          value: '2.1',
+        },
+        {
+          label: 'Sub-option 2.2',
+          value: '2.2',
+        },
+      ],
+    },
+  ],
+});
+const _template: DocDemoTemplate<typeof _schema> = (props) => {
+  return `
+<OCascader
+  v-model="ctx.modelValue"
+  :options="ctx.options"
+  ${propsToAttrStr(props)}
+  class="cascader-doc-usage"
+/>
+<p>Selected: </p>
+<pre>{{ ctx.modelValue }}</pre>
+`;
+};
+</script>
diff --git a/packages/opendesign/src/cascader/__docs__/__case__/CustomContainer.vue b/packages/opendesign/src/cascader/__docs__/__case__/CustomContainer.vue
new file mode 100644
index 0000000000000000000000000000000000000000..d8481b0554e2b6728d0302ce4d4aa67732d74844
--- /dev/null
+++ b/packages/opendesign/src/cascader/__docs__/__case__/CustomContainer.vue
@@ -0,0 +1,109 @@
+<docs lang="md">
+<!-- zh-CN -->
+### 自定义级联选择器
+
+使用更底层的 `OCascaderPanel` 组件（配合 `OSelect` 组件），可以实现更复杂的交互效果。
+
+<!-- en-US -->
+### Custom Cascader
+
+By using the lower-level `OCascaderPanel` component (in combination with the `OSelect` component), more complex interactive effects can be achieved.
+
+</docs>
+<script lang="ts" setup>
+import { ref } from 'vue';
+import { OCascaderPanel, OSelect, OTag, ODivider} from '@opensig/opendesign';
+
+const options = [
+  {
+    label: 'Option 1',
+    value: '1',
+    children: [
+      {
+        label: 'Sub-option 1-1',
+        value: '1-1',
+        children: [
+          {
+            label: 'Sub-option 1-1-1',
+            value: '1-1-1',
+          },
+          {
+            label: 'Sub-option 1-1-2',
+            value: '1-1-2',
+          },
+        ],
+      },
+      {
+        label: 'Sub-option 1-2',
+        value: '1-2',
+      },
+    ],
+  },
+  {
+    label: 'Option 2',
+    value: '2',
+    children: [
+      {
+        label: 'Sub-option 2.1',
+        value: '2.1',
+      },
+      {
+        label: 'Sub-option 2.2',
+        value: '2.2',
+      },
+    ],
+  },
+];
+const cascaderValue = ref('1-1-2');
+const hotOption = [
+  {
+    label: 'Sub-option 1-1-2',
+    value: '1-1-2',
+  },
+  {
+    label: 'Sub-option 1-2',
+    value: '1-2',
+  },
+  {
+    label: 'Sub-option 2.1',
+    value: '2.1',
+  },
+];
+const selectHotOption = (val: string) => {
+  const option = hotOption.find((item) => item.value === val);
+  if (option) {
+    cascaderValue.value = option.value;
+  }
+};
+</script>
+
+<template>
+  <OSelect v-model="cascaderValue">
+    <div class="cascader-wrapper">
+      <div>Suggested options:</div>
+      <div class="hot-option">
+        <OTag v-for="item in hotOption" :key="item.value" class="tag" @click="selectHotOption(item.value)">{{ item.label }}</OTag>
+      </div>
+      <ODivider class="divider" />
+      <!-- Current `OCascaderPanel` controlled mode has issues, need to use `key` to force re-render, otherwise data won't update -->
+      <OCascaderPanel v-model="cascaderValue" :key="cascaderValue" :options="options" class="cascader-panel" />
+    </div>
+  </OSelect>
+</template>
+<style lang="scss" scoped>
+.cascader-wrapper {
+  position: relative;
+}
+.hot-option {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: 4px;
+}
+.tag {
+  cursor: pointer;
+}
+.divider {
+  --o-divider-gap: 4px;
+}
+</style>
\ No newline at end of file
diff --git a/packages/opendesign/src/cascader/__docs__/index.en-US.md b/packages/opendesign/src/cascader/__docs__/index.en-US.md
new file mode 100644
index 0000000000000000000000000000000000000000..2f98e014135b8b597ba9720827dcb04e7c4f56a8
--- /dev/null
+++ b/packages/opendesign/src/cascader/__docs__/index.en-US.md
@@ -0,0 +1,15 @@
+---
+sidebar: OCascader
+---
+
+# OCascader
+
+## Demo
+
+<!-- @usage CascaderUsage -->
+<!-- @case CustomContainer -->
+
+## API
+
+<!-- @api OCascader -->
+<!-- @api OCascaderPanel -->
diff --git a/packages/opendesign/src/cascader/__docs__/index.zh-CN.md b/packages/opendesign/src/cascader/__docs__/index.zh-CN.md
new file mode 100644
index 0000000000000000000000000000000000000000..5290933d59ba9143cec024261f73ab497ccd6eb1
--- /dev/null
+++ b/packages/opendesign/src/cascader/__docs__/index.zh-CN.md
@@ -0,0 +1,15 @@
+---
+sidebar: OCascader 级联选择
+---
+
+# OCascader 级联选择
+
+## 示例
+
+<!-- @usage CascaderUsage -->
+<!-- @case CustomContainer -->
+
+## API
+
+<!-- @api OCascader -->
+<!-- @api OCascaderPanel -->
diff --git a/packages/opendesign/src/cascader/types.ts b/packages/opendesign/src/cascader/types.ts
index 27b2006e1abcc44d3be2ff4e615335d318ea4a35..720cd2bcb673896dce3d7600f5aa8acaeeb20f39 100644
--- a/packages/opendesign/src/cascader/types.ts
+++ b/packages/opendesign/src/cascader/types.ts
@@ -14,74 +14,91 @@ export type CascaderOptionT = {
 
 export const cascaderProps = {
   /**
-   * 级联选择器双向绑定值 CascaderValueT
+   * @zh-CN 级联选择器选中值(v-model)
+   * @en-US Cascader selected value (v-model)
+   * @CascaderValueT string | number | Array<string | number>
    */
   modelValue: {
     type: [String, Number, Array] as PropType<CascaderValueT>,
     default: '',
   },
   /**
-   * 级联选择器选项值 CascaderOptionT
-   * */
+   * @zh-CN 级联选择器选项值
+   * @en-US Cascader option value
+   * @CascaderOptionT { value: string | number, label?: string, children?: Array<CascaderOptionT> }
+   */
   options: {
     type: Array as PropType<Array<CascaderOptionT>>,
   },
   /**
-   * 是否使用路径模式
-   *
-   * */
+   * @zh-CN modelValue 是否使用路径模式
+   * @en-US Whether to use path mode for modelValue
+   * @default false
+   */
   pathMode: {
     type: Boolean,
     default: false,
   },
   /**
-   * 圆角值 RoundT
+   * @zh-CN 圆角大小
+   * @en-US Round size
    */
   round: {
     type: String as PropType<RoundT>,
   },
   /**
-   * 级联选择器类型 VariantT
+   * @zh-CN 样式
+   * @en-US Style
+   * @default 'outline'
    */
   variant: {
     type: String as PropType<VariantT>,
     default: 'outline',
   },
   /**
-   * 提示文本
+   * @zh-CN 提示文本
+   * @en-US Placeholder
    */
   placeholder: {
     type: String,
   },
   /**
-   * 下拉选项触发方式 PopupTriggerT
+   * @zh-CN 触发方式
+   * @en-US Trigger
+   * @default 'click'
+   * @deprecated useless
    */
   trigger: {
     type: String as PropType<PopupTriggerT>,
     default: 'click',
   },
   /**
-   * 下拉选项位置 PopupPositionT
+   * @zh-CN 下拉选项位置
+   * @en-US Option position
+   * @default 'bl'
    */
   optionPosition: {
     type: String as PropType<PopupPositionT>,
     default: 'bl',
   },
   /**
-   * 下拉容器自定义类
+   * @zh-CN 下拉选项容器类名
+   * @en-US Option container class name
    */
   optionWrapClass: {
     type: [String, Array] as PropType<string | string[]>,
   },
   /**
-   * 是否在结束选择时，卸载下拉选项
+   * @zh-CN 是否在隐藏时销毁 DOM
+   * @en-US Whether to destroy DOM when hidden
    */
   unmountOnHide: {
     type: Boolean,
     default: true,
   },
   /**
-   * 过渡名称
+   * @zh-CN 过渡动画名称
+   * @en-US Transition animation name
    */
   transition: {
     type: String,
@@ -90,22 +107,25 @@ export const cascaderProps = {
 
 export const cascaderPanelProps = {
   /**
-   * 级联选择器双向绑定值 CascaderValueT
+   * @zh-CN 级联选择器选中值(v-model)
+   * @en-US Cascader selected value (v-model)
    */
   modelValue: {
     type: [String, Number, Array] as PropType<CascaderValueT>,
     default: '',
   },
   /**
-   * 级联选择器选项值 CascaderOptionT
-   * */
+   * @zh-CN 级联选择器选项值
+   * @en-US Cascader option value
+   */
   options: {
     type: Array as PropType<Array<CascaderOptionT>>,
   },
   /**
-   * 是否使用路径模式
-   *
-   * */
+   * @zh-CN modelValue 是否使用路径模式
+   * @en-US Whether to use path mode for modelValue
+   * @default false
+   */
   pathMode: {
     type: Boolean,
     default: false,