@aithe/aithe-ui 26.2.2

package/docs/api/data/table.md

@@ -0,0 +1,89 @@
+# AitheTable / AitheTable 数据表格
+
+> Data table with sorting, row selection, and striped/bordered styling.
+> 数据表格，支持排序、行选择以及斑马纹/边框样式。
+
+## Column Definition Modes / 列定义模式
+
+AitheTable supports two column definition modes:
+AitheTable 支持两种列定义模式：
+
+| Mode | How to define | Custom rendering | Description |
+|------|---------------|------------------|-------------|
+| Data-driven | `columns` / `columns-json` attribute | Not supported | Columns defined as JSON data. Suitable for simple display. |
+| DOM-defined | `<aithe-table-column>` children | Supported via `.cellRenderer` | Columns defined as child elements. Supports custom cell rendering. |
+
+| 模式 | 定义方式 | 自定义渲染 | 说明 |
+|------|----------|-----------|------|
+| 数据驱动 | `columns` / `columns-json` 属性 | 不支持 | 列以 JSON 数据定义，适用于简单展示。 |
+| DOM 定义 | `<aithe-table-column>` 子元素 | 支持，通过 `.cellRenderer` | 列以子元素定义，支持自定义单元格渲染。 |
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for `<aithe-table-column>` children (DOM-defined mode). | 用于 `<aithe-table-column>` 子元素的默认插槽（DOM 定义模式）。 |
+| empty | Content shown when the table has no data. | 无数据时显示的内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| columnsJson | String | '' | JSON string of column definitions (parsed into `columns`). Data-driven mode only. | 列定义的 JSON 字符串（解析为 `columns`）。仅数据驱动模式。 |
+| columns | AitheTableColumnMeta[] | [] | Array of column definitions (prefer this over `columnsJson` in JS). Data-driven mode only. | 列定义数组（在 JS 中优先使用此属性而非 `columnsJson`）。仅数据驱动模式。 |
+| dataJson | String | '' | JSON string of row data (parsed into `data`). | 行数据的 JSON 字符串（解析为 `data`）。 |
+| data | TableRecord[] | [] | Array of row data (prefer this over `dataJson` in JS). | 行数据数组（在 JS 中优先使用此属性而非 `dataJson`）。 |
+| rowKey | String | 'id' | Unique key field for each row. | 每行的唯一键字段。 |
+| striped | Boolean | false | Whether rows use alternating background colors. | 行是否使用交替背景色。 |
+| bordered | Boolean | true | Whether cells have vertical border lines. | 单元格是否有垂直边框线。 |
+| hoverable | Boolean | true | Whether rows highlight on hover. | 行是否在悬停时高亮。 |
+| selectable | Boolean | false | Whether rows can be selected via checkboxes. | 行是否可通过复选框选择。 |
+| sortKey | String | '' | Current sort column key. | 当前排序的列键。 |
+| sortOrder | 'asc' \| 'desc' \| '' | '' | Current sort direction. | 当前排序方向。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-sort-change | { sortKey, sortOrder } | Emitted when a sortable column header is clicked. | 可排序列头被点击时触发。 |
+| aithe-selection-change | { selectedKeys } | Emitted when row selection changes. | 行选择变更时触发。 |
+| aithe-row-click | { record, rowIndex } | Emitted when a row is clicked. | 行被点击时触发。 |
+
+## Column Fields (Data-driven) / 列字段（数据驱动模式）
+
+| Field | Type | Description (EN) | Description (CN) |
+|-------|------|-------------------|-------------------|
+| id | `string` | Unique column key. | 唯一列键。 |
+| title | `string` | Header title. | 表头标题。 |
+| dataIndex | keyof T \| string | Property path on the data record. | 数据记录上的属性路径。 |
+| width | `string` | Fixed column width. | 固定列宽。 |
+| align | 'left' \| 'center' \| 'right' | Text alignment. | 文本对齐方式。 |
+| sortable | `boolean` | Enable client-side sorting. | 启用客户端排序。 |
+| icon | `string` | Icon name rendered in the header via aithe-icon. | 通过 aithe-icon 在表头渲染的图标名称。 |
+| intent | AitheIntent | Visual intent / semantic color for the column cells. | 列单元格的视觉意图/语义色。 |
+
+## Examples / 示例
+
+### Data-driven mode / 数据驱动模式
+
+```html
+<aithe-table
+  columns-json='[{"id":"name","title":"Name","sortable":true}]'
+  data-json='[{"name":"Alice"},{"name":"Bob"}]'
+  striped
+  selectable
+></aithe-table>
+```
+
+### DOM-defined mode / DOM 定义模式
+
+```html
+<aithe-table .data=${records} striped selectable>
+  <aithe-table-column id="name" title="Name" sortable></aithe-table-column>
+  <aithe-table-column id="owner" title="Owner"></aithe-table-column>
+  <aithe-table-column id="status" title="Status" intent="success" sortable></aithe-table-column>
+  <aithe-table-column id="action" title="Action" align="center"
+    .cellRenderer=${(value, record, rowIndex) => html`<aithe-button type="primary" size="sm">Edit</aithe-button>`}
+  ></aithe-table-column>
+</aithe-table>
+```

package/docs/api/data/tabs.md

@@ -0,0 +1,35 @@
+# AitheTabs / AitheTabs 标签页
+
+> Tab navigation container that manages tab-pane children.
+> 标签页导航容器，管理 tab-pane 子组件。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for `aithe-tab-pane` children. | 默认插槽，用于 `aithe-tab-pane` 子组件。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| type | 'line' \| 'card' \| 'button' | 'line' | Visual style of the tab navigation. | 标签页导航的视觉样式。 |
+| activeKey | String | '' | Key of the currently active tab pane. | 当前活动标签页的键。 |
+| addable | Boolean | false | Whether to show an add button in the tab bar. | 是否在标签栏中显示添加按钮。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-change | { activeKey } | Emitted when the active tab changes. | 活动标签页变更时触发。 |
+| aithe-tab-remove | { key } | Emitted when a closable tab is removed. | 可关闭标签页被移除时触发。 |
+| aithe-tab-add | — | Emitted when the add button is clicked. | 添加按钮被点击时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-tabs type="card" active-key="a">
+  <aithe-tab-pane tab-id="a" label="Tab A">Content A</aithe-tab-pane>
+  <aithe-tab-pane tab-id="b" label="Tab B">Content B</aithe-tab-pane>
+</aithe-tabs>
+```

package/docs/api/data/timeline-item.md

@@ -0,0 +1,32 @@
+# AitheTimelineItem / AitheTimelineItem 时间线节点
+
+> Single node inside `aithe-timeline` with timestamp and color variant.
+> 时间线节点，用于 aithe-timeline 内部，包含时间戳和颜色类型。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for timeline item content. | 时间线节点内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| timestamp | `string` | `''` | Timestamp label text. | 时间戳标签文本。 |
+| type | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Color variant for the dot indicator. | 圆点指示器的颜色类型。 |
+| dot | `string` | `''` | Custom dot content (overrides default circle). | 自定义圆点内容（覆盖默认圆圈）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-timeline-item timestamp="2024-03-15" type="success" dot="✓">
+  Task completed successfully
+</aithe-timeline-item>
+```

package/docs/api/data/timeline.md

@@ -0,0 +1,67 @@
+# AitheTimeline / AitheTimeline 时间线
+
+> Timeline container for displaying process and audit records.
+> 时间线容器，用于展示流程和审计记录。
+
+## Item Definition Modes / 节点定义模式
+
+AitheTimeline supports two item definition modes:
+AitheTimeline 支持两种节点定义模式：
+
+| Mode | How to define | Description |
+|------|---------------|-------------|
+| Data-driven | `items` / `items-json` attribute | Items defined as JSON data. Suitable for simple display. |
+| DOM-defined | `<aithe-timeline-item>` children | Items defined as child elements. Supports rich content via slots. |
+
+| 模式 | 定义方式 | 说明 |
+|------|----------|------|
+| 数据驱动 | `items` / `items-json` 属性 | 节点以 JSON 数据定义，适用于简单展示。 |
+| DOM 定义 | `<aithe-timeline-item>` 子元素 | 节点以子元素定义，支持通过插槽放置富内容。 |
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for `aithe-timeline-item` elements (DOM-defined mode). | aithe-timeline-item 时间线节点元素（DOM 定义模式）。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| itemsJson | String | '' | JSON string of timeline items (parsed into `items`). Data-driven mode only. | 时间线节点的 JSON 字符串（解析为 `items`）。仅数据驱动模式。 |
+| items | AitheTimelineItemMeta[] | [] | Array of timeline items (prefer this over `itemsJson` in JS). Data-driven mode only. | 时间线节点数组（在 JS 中优先使用此属性而非 `itemsJson`）。仅数据驱动模式。 |
+| reverse | Boolean | false | Whether to reverse the order of timeline items. | 是否反转时间线节点顺序。 |
+
+## Item Fields (Data-driven) / 节点字段（数据驱动模式）
+
+| Field | Type | Description (EN) | Description (CN) |
+|-------|------|-------------------|-------------------|
+| content | `string` | Item content text. | 节点内容文本。 |
+| timestamp | `string` | Timestamp label text. | 时间戳标签文本。 |
+| type | 'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' | Color variant for the dot indicator. | 圆点指示器的颜色类型。 |
+| dot | `string` | Custom dot content (overrides default circle). | 自定义圆点内容（覆盖默认圆圈）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+### Data-driven mode / 数据驱动模式
+
+```html
+<aithe-timeline
+  items='[{"content":"Design tokens published","timestamp":"09:00","type":"primary"},{"content":"Demo routing completed","timestamp":"11:30","type":"success"},{"content":"Accessibility audit pending","timestamp":"15:20","type":"warning"}]'
+></aithe-timeline>
+```
+
+### DOM-defined mode / DOM 定义模式
+
+```html
+<aithe-timeline reverse>
+  <aithe-timeline-item timestamp="2024-01-01" type="primary">Step 1</aithe-timeline-item>
+  <aithe-timeline-item timestamp="2024-01-02" type="success">Step 2</aithe-timeline-item>
+</aithe-timeline>
+```

package/docs/api/data/tree-menu.md

@@ -0,0 +1,58 @@
+# AitheTreeMenu / AitheTreeMenu 树形菜单
+
+> Data-driven tree menu with menu-style active highlighting, expand/collapse, and vertical/horizontal layout.
+> 数据驱动的树形菜单，支持菜单样式高亮、展开/折叠以及垂直/水平布局。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| — | — | No slots (content driven by `items` property). | 无插槽（内容由 items 属性控制）。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| items | String (JSON) | `''` | JSON string of tree menu items (maps to `items` HTML attribute). | 树菜单项的 JSON 字符串（映射到 `items` HTML 属性）。 |
+| items | `AitheTreeNodeMeta[]` | `[]` | Array of tree menu items (prefer this in JS). | 树菜单项数组（在 JS 中优先使用）。 |
+| active | `string` | `''` | Active (selected) menu item value. | 当前选中的菜单项值。 |
+| expandAll | Boolean | false | Whether all nodes are expanded by default. | 是否默认展开所有节点。 |
+| direction | 'vertical' \| 'horizontal' | 'vertical' | Layout direction. Vertical stacks items; horizontal arranges top-level items in a row with dropdown sub-menus. | 布局方向。垂直堆叠菜单项；水平将顶级菜单项排列为一行，子菜单以下拉方式展开。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-select | `{ value }` | Emitted when a menu item is selected. | 菜单项选中时触发。 |
+
+## Data Item Fields / 数据项字段
+
+| Field | Type | Description (EN) | Description (CN) |
+|-------|------|-------------------|-------------------|
+| label | `string` | Display text of the menu item. | 菜单项的显示文本。 |
+| id | `string` | Unique value identifying this node. | 节点唯一标识值。 |
+| icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
+| disabled | `boolean` | Whether the menu item is non-interactive. | 是否禁用菜单项。 |
+| intent | `AitheIntent` | Visual intent / semantic color for the node. | 节点的视觉意图/语义色。 |
+| children | `AitheTreeNodeMeta[]` | Nested sub-menu items. | 嵌套子菜单项。 |
+
+## Examples / 示例
+
+### Vertical layout (default) / 垂直布局（默认）
+
+```html
+<aithe-tree-menu
+  items='[{"label":"Dashboard","id":"dashboard","icon":"home"},{"label":"Settings","id":"settings","icon":"settings","children":[{"label":"Profile","id":"profile"},{"label":"Security","id":"security"}]}]'
+  active="dashboard"
+></aithe-tree-menu>
+```
+
+### Horizontal layout / 水平布局
+
+```html
+<aithe-tree-menu
+  direction="horizontal"
+  items='[{"label":"Dashboard","id":"dashboard","icon":"home"},{"label":"Settings","id":"settings","icon":"settings","children":[{"label":"Profile","id":"profile"},{"label":"Security","id":"security"}]}]'
+  active="dashboard"
+></aithe-tree-menu>
+```

package/docs/api/data/tree.md

@@ -0,0 +1,51 @@
+# AitheTree / AitheTree 树形视图
+
+> Recursive tree view with expand/collapse and optional checkbox support.
+> 递归树形视图，支持展开/折叠和可选的复选框功能。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| — | — | No slots (content driven by `data` property). | 无插槽（内容由 data 属性控制）。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| data | String | '[]' | JSON string of tree node data. Each node supports `icon` and `intent` (AitheIntent) fields. | 树节点数据的 JSON 字符串。每个节点支持 `icon` 和 `intent`（AitheIntent）字段。 |
+| title | `string` | `''` | Display title (shown as tooltip). | 显示标题（作为工具提示）。 |
+| icon | `string` | `''` | Icon name to display before the tree title. | 在树标题前显示的图标名称。 |
+| checkable | Boolean | false | Whether nodes show checkboxes for selection. | 节点是否显示复选框以供选择。 |
+| expandAll | Boolean | false | Whether all nodes are expanded by default. | 是否默认展开所有节点。 |
+| renderer | Function | undefined | Custom renderer function for tree nodes. Receives a TreeNode and returns a TemplateResult. | 树节点的自定义渲染函数。接收 TreeNode 并返回 TemplateResult。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-check | { checked } | Emitted when a checkbox is toggled. | 复选框切换时触发。 |
+| aithe-node-click | { node } | Emitted when a node label is clicked. | 节点标签被点击时触发。 |
+
+## Data Node Fields / 数据节点字段
+
+| Field | Type | Description (EN) | Description (CN) |
+|-------|------|-------------------|-------------------|
+| label | `string` | Display text of the node. | 节点的显示文本。 |
+| id | `string` | Unique identifier of the node. | 节点的唯一标识。 |
+| children | `AitheTreeNodeMeta[]` | Nested child nodes. | 嵌套子节点。 |
+| disabled | `boolean` | Whether the node is non-interactive. | 是否不可交互。 |
+| icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
+| intent | `AitheIntent` | Visual intent / semantic color for the node label. | 节点标签的视觉意图/语义色。 |
+
+## Examples / 示例
+
+```html
+<aithe-tree
+  data='[{"label":"Root","id":"root","children":[{"label":"Child","id":"child"}]}]'
+  title="Navigation tree"
+  icon="folder"
+  checkable
+  expand-all
+></aithe-tree>
+```

package/docs/api/display/animated-image.md

@@ -0,0 +1,31 @@
+# AitheAnimatedImage / Aithe动画图片
+
+> Animated image display with pan/zoom motion effect.
+> 带平移/缩放动效的动画图片展示组件。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for fallback content when `src` is empty. | `src` 为空时的回退内容插槽。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| src | `string` | `''` | Image source URL. | 图片源 URL。 |
+| loop | `boolean` | `true` | Whether the animation loops infinitely. | 动画是否无限循环。 |
+| speed | `number` | `1` | Animation speed multiplier (higher = faster). | 动画速度倍数（越高越快）。 |
+| play | `boolean` | `true` | Whether the animation is currently playing. | 动画是否正在播放。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-animated-image src="hero.jpg" loop speed="2" play></aithe-animated-image>
+```

package/docs/api/display/carousel.md

@@ -0,0 +1,35 @@
+# AitheCarousel / Aithe轮播
+
+> Slot-based carousel for cycling through child elements with autoplay, arrows, and indicators.
+> 基于插槽的轮播组件，支持自动播放、箭头导航和指示器。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for carousel slide content. | 轮播幻灯片内容的默认插槽。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| autoplay | `boolean` | `false` | Whether the carousel auto-advances slides. | 轮播是否自动切换幻灯片。 |
+| interval | `number` | `3200` | Auto-advance interval in milliseconds. | 自动切换间隔（毫秒）。 |
+| indicators | `boolean` | `true` | Whether to show dot indicators. | 是否显示指示器圆点。 |
+| arrows | `boolean` | `true` | Whether to show prev/next arrow buttons. | 是否显示前进/后退箭头按钮。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-change | `{ current }` | Emitted when the active slide changes. | 当前幻灯片切换时发出。 |
+
+## Examples / 示例
+
+```html
+<aithe-carousel autoplay interval="4000" arrows indicators>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</aithe-carousel>
+```

package/docs/api/display/comparison.md

@@ -0,0 +1,31 @@
+# AitheComparison / Aithe对比
+
+> Before/after image comparison slider with adjustable split ratio.
+> 前后对比图片滑块组件，支持可调节的分割比例。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| before | Content for the "before" pane (falls back to `beforeSrc` image). | "之前"面板内容（回退到 `beforeSrc` 图片）。 |
+| after | Content for the "after" pane (falls back to `afterSrc` image). | "之后"面板内容（回退到 `afterSrc` 图片）。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| before | `string` | `''` | URL of the "before" image. | "之前"图片的 URL。 |
+| after | `string` | `''` | URL of the "after" image. | "之后"图片的 URL。 |
+| ratio | `number` | `50` | Split ratio percentage (0–100). | 分割比例百分比（0–100）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-comparison before="old.jpg" after="new.jpg" ratio="60"></aithe-comparison>
+```

package/docs/api/display/markdown.md

@@ -0,0 +1,29 @@
+# AitheMarkdown / AitheMarkdown渲染器
+
+> Lightweight inline markdown renderer that converts markdown text to styled HTML.
+> 轻量级内联 Markdown 渲染器，将 Markdown 文本转换为带样式的 HTML。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| — | — | No slots; content is provided via the `content` property. | 无插槽；内容通过 `content` 属性提供。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| content | `string` | `''` | Raw markdown source string. | Markdown 源文本字符串。 |
+| theme | `'default' | 'article'` | `'default'` | Visual theme preset. | 视觉主题预设。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-markdown content="# Hello\n**Bold** text and `code`." theme="article"></aithe-markdown>
+```

package/docs/api/feedback/alert.md

@@ -0,0 +1,35 @@
+# AitheAlert / AitheAlert 警告
+
+> Inline banner / alert strip with optional close button.
+> 内联横幅/警告条，支持可选关闭按钮。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for alert body content. | 警告正文内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| type | 'default' \| 'success' \| 'warning' \| 'danger' | 'default' | Alert color variant. | 警告颜色类型。 |
+| title | String | '' | Alert title text. | 警告标题文本。 |
+| icon | `string` | `''` | Icon name to display before the title. Uses built-in `aithe-icon` names. | 在标题前显示的图标名称，使用 aithe-icon 内置图标名。 |
+| closable | Boolean | false | Whether the alert shows a close button. | 是否显示关闭按钮。 |
+| banner | Boolean | false | Whether the alert renders as a full-width banner. | 是否以全宽横幅样式渲染。 |
+| open | Boolean | true | Whether the alert is visible (open). | 是否可见（打开）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-close | — | Emitted when the alert is closed. | 关闭时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-alert type="warning" title="Warning" icon="warning" closable>
+  Please review before proceeding.
+</aithe-alert>
+```

package/docs/api/feedback/dialog.md

@@ -0,0 +1,37 @@
+# AitheDialog / AitheDialog 对话框
+
+> Lightweight confirm dialog with cancel/confirm actions.
+> 轻量级确认对话框，支持取消/确认操作。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for dialog body content. | 对话框正文内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| title | String | 'Confirm' | Dialog title text. | 对话框标题文本。 |
+| icon | `string` | `''` | Icon name to display before the title. Uses built-in `aithe-icon` names. | 在标题前显示的图标名称，使用 aithe-icon 内置图标名。 |
+| visible | Boolean | false | Whether the dialog is visible. | 是否显示对话框。 |
+| closeable | Boolean | true | Whether the dialog can be closed via close button or Escape. | 是否可通过关闭按钮或 Escape 关闭。 |
+| mask | Boolean | true | Whether a backdrop mask is shown. | 是否显示背景遮罩。 |
+| confirmText | String | 'Confirm' | Confirm button label text. | 确认按钮文本。 |
+| cancelText | String | 'Cancel' | Cancel button label text. | 取消按钮文本。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-confirm | — | Emitted when the confirm button is clicked. | 确认按钮点击时触发。 |
+| aithe-cancel | — | Emitted when the cancel button or close button is clicked. | 取消或关闭按钮点击时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-dialog title="Delete item?" icon="warning" visible confirm-text="Delete" cancel-text="Cancel">
+  This action cannot be undone.
+</aithe-dialog>
+```

package/docs/api/feedback/drawer.md

@@ -0,0 +1,39 @@
+# AitheDrawer / AitheDrawer 抽屉
+
+> Side drawer panel that slides in from any edge of the viewport.
+> 侧边抽屉面板，从视口任意边缘滑入。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for drawer body content. | 抽屉正文内容。 |
+| header | Custom header content (overrides title property). | 自定义头部内容。 |
+| footer | Footer action area. | 底部操作区域。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| open | Boolean | false | Whether the drawer is open. | 是否打开抽屉。 |
+| title | String | '' | Drawer title text. | 抽屉标题文本。 |
+| icon | `string` | `''` | Icon name to display before the title. Uses built-in `aithe-icon` names. | 在标题前显示的图标名称，使用 aithe-icon 内置图标名。 |
+| placement | 'top' \| 'right' \| 'bottom' \| 'left' | 'right' | Edge from which the drawer slides in. | 抽屉滑入的边缘方向。 |
+| size | String | '420px' | Drawer width (for left/right) or height (for top/bottom). | 抽屉宽度（左右）或高度（上下）。 |
+| mount | String | '' | CSS selector for a mount target element (teleports the drawer). | 挂载目标元素的 CSS 选择器。 |
+| closeOnMask | Boolean | true | Whether clicking the backdrop mask closes the drawer. | 点击遮罩是否关闭抽屉。 |
+| closeOnEsc | Boolean | true | Whether pressing Escape closes the drawer. | 按 Escape 是否关闭抽屉。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-open-change | { open } | Emitted when open state changes. | 开关状态变更时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-drawer title="Details" icon="info" placement="right" size="420px">
+  <p>Drawer content here.</p>
+</aithe-drawer>
+```

package/docs/api/feedback/loading.md

@@ -0,0 +1,34 @@
+# AitheLoading / AitheLoading 加载
+
+> Inline or fullscreen loading overlay with spinner and optional tip text.
+> 内联或全屏加载遮罩层，带旋转器和可选提示文本。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for content to be covered by the loading overlay. | 被加载遮罩层覆盖的内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| spinning | Boolean | true | Whether the loading spinner is active. | 是否显示加载旋转器。 |
+| size | 'sm' \| 'md' \| 'lg' | 'md' | Spinner size scale. | 旋转器尺寸规格。 |
+| tip | String | '' | Tip text displayed below the spinner. | 旋转器下方显示的提示文本。 |
+| fullscreen | Boolean | false | Whether the loading overlay covers the entire viewport. | 加载遮罩是否覆盖整个视口。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events emitted. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-loading spinning tip="Loading..." size="md">
+  <div>Content behind the overlay</div>
+</aithe-loading>
+<aithe-loading fullscreen tip="Please wait..."></aithe-loading>
+```

package/docs/api/feedback/modal.md

@@ -0,0 +1,40 @@
+# AitheModal / AitheModal 模态框
+
+> Full-featured modal dialog with header, body, footer slots and focus trapping.
+> 全功能模态对话框，支持头部、正文、底部插槽和焦点捕获。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for modal body content. | 模态框正文内容。 |
+| header | Custom header content (overrides title property). | 自定义头部内容。 |
+| footer | Footer action area. | 底部操作区域。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| open | Boolean | false | Whether the modal is open. | 是否打开模态框。 |
+| title | String | '' | Modal title text. | 模态框标题文本。 |
+| icon | `string` | `''` | Icon name to display before the title. Uses built-in `aithe-icon` names. | 在标题前显示的图标名称，使用 aithe-icon 内置图标名。 |
+| width | String | '640px' | Modal width (CSS value). | 模态框宽度（CSS 值）。 |
+| fullscreen | Boolean | false | Whether the modal takes up the full viewport. | 是否全屏显示。 |
+| closeOnMask | Boolean | true | Whether clicking the backdrop mask closes the modal. | 点击遮罩是否关闭模态框。 |
+| closeOnEsc | Boolean | true | Whether pressing Escape closes the modal. | 按 Escape 是否关闭模态框。 |
+| showClose | Boolean | true | Whether the close button is shown in the header. | 是否在头部显示关闭按钮。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-open-change | { open } | Emitted when open state changes. | 开关状态变更时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-modal title="Edit Profile" icon="user" width="520px">
+  <p>Modal body content here.</p>
+  <button slot="footer">Save</button>
+</aithe-modal>
+```