@aithe/aithe-ui 26.2.2 → 26.2.3

package/docs/api/basic/icon.md

@@ -2,6 +2,8 @@
 
 > Vector icon entry for the Aithe UI icon system. Renders an SVG glyph from the built-in icon map based on the `name` property. All icons use a 24×24 viewBox, stroke-based rendering with `stroke-width: 1.8`, and inherit color via `currentColor`.
 > 矢量图标组件，用于 Aithe UI 图标系统。根据 `name` 属性从内置图标映射中渲染 SVG 图形。所有图标使用 24×24 视口，基于描边渲染（stroke-width: 1.8），颜色继承 currentColor。
+>
+> For `auto` and `url` types, rendering is delegated to `IconUtil.render`. Size presets are resolved via `IconUtil.resolveSize` against `ICON_SIZE_MAP`. `auto` 和 `url` 类型委托给 `IconUtil.render` 渲染。尺寸预设通过 `IconUtil.resolveSize` 结合 `ICON_SIZE_MAP` 解析。
 
 ## Slots / 插槽
 
@@ -13,9 +15,9 @@
 
 | Name | Type | Default | Description (EN) | Description (CN) |
 |------|------|---------|-------------------|-------------------|
-| name | `string` | `'sparkles'` | Icon glyph name from the built-in map. If the name is not found, renders an empty SVG. | 内置图标名称。若名称不存在，渲染空 SVG。 |
+| name | `string` | `'sparkles'` | Icon glyph name or extended format. Supports built-in names (e.g. `sparkles`), or extended `(type)value` syntax. See [Extended Name Format](#extended-name-format--扩展名称格式) below. | 图标名称或扩展格式。支持内置名称或扩展 `(type)value` 语法。详见下方扩展名称格式。 |
 | color | `string` | `''` | Custom stroke/fill color. When empty, falls back to `currentColor` (inherits from parent). | 自定义颜色。为空时继承父元素 currentColor。 |
-| size | `string` | `'md'` | Icon size. Accepts preset aliases (`sm` → 14px, `md` → 18px, `lg` → 22px) or any explicit CSS value (e.g. `"32px"`, `"2rem"`). Bare numbers get `px` appended. | 图标尺寸。支持预设别名（sm→14px, md→18px, lg→22px）或显式 CSS 值。纯数字自动追加 px。 |
+| size | `string` | `'md'` | Icon size. Accepts preset aliases or any explicit CSS value. Resolved via `IconUtil.resolveSize` against `ICON_SIZE_MAP`. See [Size Presets](#size-presets--尺寸预设) below. | 图标尺寸。支持预设别名或显式 CSS 值。通过 `IconUtil.resolveSize` 结合 `ICON_SIZE_MAP` 解析。详见下方尺寸预设。 |
 
 ## Events / 事件
 
@@ -27,16 +29,23 @@
 
 | Variable | Default | Description (EN) | Description (CN) |
 |----------|---------|-------------------|-------------------|
-| `--aithe-icon-size` | `18px` | Controls the SVG width/height. Set dynamically from the `size` property. | 控制 SVG 宽高。由 `size` 属性动态设置。 |
+| `--aithe-icon-size` | `20px` | Controls the SVG width/height. Set dynamically from the `size` property. | 控制 SVG 宽高。由 `size` 属性动态设置。 |
 | `--aithe-icon-color` | `currentColor` | Controls the host `color` which cascades to `stroke: currentColor`. | 控制宿主 `color`，级联至 `stroke: currentColor`。 |
 
 ## Size Presets / 尺寸预设
 
 | Preset | Pixel Value | Description (EN) | Description (CN) |
 |--------|-------------|-------------------|-------------------|
-| `sm` | 14px | Small icon for inline text or tight layouts. | 小图标，用于行内文本或紧凑布局。 |
-| `md` | 18px | Default medium icon. | 默认中等图标。 |
-| `lg` | 22px | Large icon for headings or standalone display. | 大图标，用于标题或独立展示。 |
+| `xs` | 12px | Extra small for dense inline text. | 超小，用于紧凑行内文本。 |
+| `sm` | 16px | Small icon for inline text or tight layouts. | 小图标，用于行内文本或紧凑布局。 |
+| `md` | 20px | Default medium icon. | 默认中等图标。 |
+| `lg` | 24px | Large icon for headings or standalone display. | 大图标，用于标题或独立展示。 |
+| `xl` | 28px | Extra large for section headers. | 超大，用于章节标题。 |
+| `2xl` | 32px | Double extra large. | 2 倍超大。 |
+| `3xl` | 48px | Triple extra large for hero areas. | 3 倍超大，用于主视觉区域。 |
+| `4xl` | 64px | 4× extra large. | 4 倍超大。 |
+| `5xl` | 96px | 5× extra large. | 5 倍超大。 |
+| `6xl` | 128px | Maximum preset for large displays. | 最大预设，用于大屏展示。 |
 
 You can also pass any valid CSS dimension (e.g. `"32px"`, `"2rem"`, `"24"` → `24px`).
 也可以传入任意合法 CSS 尺寸值（如 `"32px"`、`"2rem"`、`"24"` → `24px`）。
@@ -174,8 +183,27 @@ You can also pass any valid CSS dimension (e.g. `"32px"`, `"2rem"`, `"24"` → `
 - **Stroke-based**: `fill: none`, `stroke: currentColor`, `stroke-width: 1.8`, `stroke-linecap: round`, `stroke-linejoin: round`.
 - **Unknown name**: If `name` does not match any entry in the icon map, the SVG renders with no glyph (empty).
 - **Slot override**: Content placed in the default slot replaces the built-in glyph entirely.
+- **Delegated types**: `auto` and `url` types are delegated to `IconUtil.render` for unified rendering.
+- **Size resolution**: Size presets are resolved via `IconUtil.resolveSize` against `ICON_SIZE_MAP`.
+- **Remote image fallback**: When a `(url)` / `(share)` / `(remote)` image fails to load, the alt text first character is shown as a placeholder. If no alt text is provided, no fallback is displayed.
+- **Extended format**: See [Extended Name Format](#extended-name-format--扩展名称格式).
 
-所有图标在 `<svg viewBox="0 0 24 24">` 内渲染。基于描边：fill: none, stroke: currentColor, stroke-width: 1.8。未知名称渲染空 SVG。默认插槽内容覆盖内置图形。
+ 所有图标在 `<svg viewBox="0 0 24 24">` 内渲染。基于描边：fill: none, stroke: currentColor, stroke-width: 1.8。未知名称渲染空 SVG。默认插槽内容覆盖内置图形。`auto` 和 `url` 类型委托给 `IconUtil.render` 统一渲染。尺寸预设通过 `IconUtil.resolveSize` 结合 `ICON_SIZE_MAP` 解析。远程图片加载失败时显示 alt 首字符占位（无 alt 则不显示）。
+
+## Extended Name Format / 扩展名称格式
+
+The `name` property supports an extended syntax: `(type)value`. This allows `<aithe-icon>` to render not only built-in SVG glyphs but also auto-generated text avatars and remote images.
+`name` 属性支持扩展语法 `(type)value`，使 `<aithe-icon>` 不仅能渲染内置 SVG 图形，还能渲染文本首字母头像和远程图片。
+
+| Format | Type | Description (EN) | Description (CN) |
+|--------|------|-------------------|-------------------|
+| `sparkles` | `class` | Bare name — built-in SVG icon (default). | 裸名称 — 内置 SVG 图标（默认）。 |
+| `(class)sparkles` | `class` | Explicit built-in SVG icon. | 显式指定内置 SVG 图标。 |
+| `(auto)User Name` | `auto` | Auto-generate from the first character of the text. | 取文本首字符自动生成图标。 |
+| `(url)https://example.com/icon.svg` | `url` | Load icon from a URL via `<img>`. | 通过 URL 加载图标。 |
+| `(url)https://example.com/icon.svg\|Alt` | `url` | Load from URL with alt fallback. Shows "A" on load failure. | 从 URL 加载，带 alt 占位，加载失败时显示 "A"。 |
+| `(share)https://example.com/icon.svg` | `share` | Alias for `url`. | `url` 的别名。 |
+| `(remote)https://example.com/icon.svg` | `remote` | Alias for `url`. | `url` 的别名。 |
 
 ## Examples / 示例
 
@@ -190,9 +218,16 @@ You can also pass any valid CSS dimension (e.g. `"32px"`, `"2rem"`, `"24"` → `
 ### Size presets / 尺寸预设
 
 ```html
+<aithe-icon name="search" size="xs"></aithe-icon>
 <aithe-icon name="search" size="sm"></aithe-icon>
 <aithe-icon name="search" size="md"></aithe-icon>
 <aithe-icon name="search" size="lg"></aithe-icon>
+<aithe-icon name="search" size="xl"></aithe-icon>
+<aithe-icon name="search" size="2xl"></aithe-icon>
+<aithe-icon name="search" size="3xl"></aithe-icon>
+<aithe-icon name="search" size="4xl"></aithe-icon>
+<aithe-icon name="search" size="5xl"></aithe-icon>
+<aithe-icon name="search" size="6xl"></aithe-icon>
 <aithe-icon name="search" size="32px"></aithe-icon>
 ```
 
@@ -242,4 +277,25 @@ You can also pass any valid CSS dimension (e.g. `"32px"`, `"2rem"`, `"24"` → `
     <path d="M8 12l4 4 4-8"></path>
   </svg>
 </aithe-icon>
-```
+```
+
+### Extended format: auto-generated text / 扩展格式：文本首字母
+
+```html
+<aithe-icon name="(auto)User Name" size="md"></aithe-icon>
+<aithe-icon name="(auto)A" size="lg"></aithe-icon>
+```
+
+### Extended format: remote image / 扩展格式：远程图片
+
+```html
+<aithe-icon name="(url)https://example.com/icon.svg" size="md"></aithe-icon>
+<aithe-icon name="(share)https://example.com/icon.svg" size="lg"></aithe-icon>
+```
+
+### Extended format: remote image with alt fallback / 扩展格式：远程图片带 alt 占位
+
+```html
+<aithe-icon name="(url)https://example.com/icon.svg|User" size="md"></aithe-icon>
+<aithe-icon name="(url)https://example.com/icon.svg|A" size="lg"></aithe-icon>
+```

package/docs/api/data/dropdown.md

@@ -0,0 +1,73 @@
+# AitheDropdown / AitheDropdown 下拉菜单
+
+> Dropdown menu with nested submenus, keyboard navigation, and hover/click triggers.
+> Internally uses `<aithe-tree-menu>` for menu rendering.
+> 下拉菜单，支持嵌套子菜单、键盘导航和悬停/点击触发。内部使用 `<aithe-tree-menu>` 渲染菜单。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                      | Description (CN) |
+| --------- | ------------------------------------- | ---------------- |
+| (default) | Default slot for the trigger element. | 触发元素内容。   |
+
+## Properties / 属性
+
+| Name      | Type                                                       | Default        | Description (EN)                                                                                   | Description (CN)                                                      |
+| --------- | ---------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| trigger   | 'click' \| 'hover'                                         | 'click'        | Trigger mode: click or hover.                                                                      | 触发方式：点击或悬停。                                                |
+| title     | `string`                                                   | `''`           | Display title (shown as tooltip).                                                                  | 显示标题（作为工具提示）。                                            |
+| icon      | `string`                                                   | `''`           | Icon name to display before the trigger slot content.                                              | 在触发器插槽内容前显示的图标名称。                                    |
+| itemsJson | String                                                     | ''             | JSON string of dropdown menu items.                                                                | 下拉菜单项的 JSON 字符串。                                            |
+| items     | AitheTreeNodeMeta[]                                        | []             | Array of dropdown menu item objects. Each item supports `icon` and `variant` (AitheVariant) fields. | 下拉菜单项对象数组。每项支持 `icon` 和 `variant`（AitheVariant）字段。 |
+| placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-start' | Dropdown panel placement. Auto-adapts to viewport.                                                 | 下拉面板位置。自动适应视口。                                          |
+| offset    | `number`                                                   | 8              | Pixel gap between anchor and dropdown panel.                                                       | 锚点与下拉面板之间的像素间距。                                        |
+
+## Events / 事件
+
+| Name              | Detail             | Description (EN)                      | Description (CN)     |
+| ----------------- | ------------------ | ------------------------------------- | -------------------- |
+| aithe-select      | { item, path, id } | Emitted when a menu item is selected. | 菜单项选中时触发。   |
+| aithe-open-change | { open }           | Emitted when open state changes.      | 开关状态变更时触发。 |
+
+## Item Fields / 菜单项字段
+
+| Field    | Type                | Description (EN)                                                                                                      | Description (CN)                                                           |
+| -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| label    | `string`            | Display text. Used as i18n fallback when `i18n` is set.                                                               | 显示文本。设置 `i18n` 时作为缺省值。                                       |
+| id       | `string`            | Unique value emitted on select.                                                                                       | 选择时发出的唯一值。                                                       |
+| type     | `'item' \| 'divider' \| 'theme'` | Node type: `item` (default), `divider` (visual separator), `theme` (embedded theme picker).              | 节点类型：`item`（默认）、`divider`（视觉分隔线）、`theme`（嵌入主题选择器）。 |
+| disabled | `boolean`           | Whether the item is non-interactive.                                                                                  | 是否不可交互。                                                             |
+| variant  | AitheVariant        | Visual variant / semantic color for the item.                                                                         | 项的视觉变体/语义色。                                                      |
+| shortcut | `string`            | Keyboard shortcut hint.                                                                                               | 键盘快捷键提示。                                                           |
+| icon     | `string`            | Icon name rendered before the label via aithe-icon.                                                                   | 通过 aithe-icon 在标签前渲染的图标名称。                                   |
+| children | AitheTreeNodeMeta[] | Nested sub-menu items.                                                                                                | 嵌套子菜单项。                                                             |
+| i18n     | `string`            | i18n translation key. When set, `t(i18n, label)` is used to translate the label; `label` serves as the default value. | 国际化翻译键。设置后通过 `t(i18n, label)` 翻译 label，`label` 作为缺省值。 |
+
+## Examples / 示例
+
+### Basic usage / 基础用法
+
+```html
+<aithe-dropdown
+  trigger="click"
+  title="Actions"
+  icon="menu"
+  items='[{"id":"a","label":"Action"},{"id":"b","label":"Another"}]'
+>
+  <button>Menu</button>
+</aithe-dropdown>
+```
+
+### With i18n / 国际化
+
+```html
+<aithe-dropdown
+  items='[{"id":"a","label":"Action","i18n":"app.menu.action"},{"id":"b","label":"Another","i18n":"app.menu.another"}]'
+>
+  <button>Menu</button>
+</aithe-dropdown>
+```
+
+When `i18n` is set, the component automatically translates the label via `t(i18n, label)`. The `label` field serves as the fallback default value when the translation key is not found.
+
+设置 `i18n` 后，组件自动通过 `t(i18n, label)` 翻译 label。`label` 字段作为翻译键未找到时的缺省值。

package/docs/api/data/metrics-group.md

@@ -0,0 +1,120 @@
+# AitheMetricsGroup / AitheMetricsGroup 业务指标组
+
+> Container that groups multiple `<aithe-metrics>` children with configurable layout direction and gap.
+> 业务指标组容器，以水平或垂直方向排列多个 `<aithe-metrics>` 子元素，支持自定义间距。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/data/metrics-group';
+```
+
+## Description / 描述
+
+`<aithe-metrics-group>` is a flex container that lays out its `<aithe-metrics>` children in either a horizontal row or vertical column. The `gap` property controls spacing between items. It is designed for use inside `<aithe-dashboard-panel>` or any card context where multiple metrics need to be grouped together.
+
+`<aithe-metrics-group>` 是一个 flex 容器，将其 `<aithe-metrics>` 子元素按水平行或垂直列排列。`gap` 属性控制项之间的间距。设计用于 `<aithe-dashboard-panel>` 内部或任何需要将多个指标组合在一起的卡片场景。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                              | Description (CN)                 |
+| --------- | --------------------------------------------- | -------------------------------- |
+| (default) | One or more `<aithe-metrics>` elements.       | 一个或多个 `<aithe-metrics>` 元素。 |
+
+## CSS Parts / CSS 部件
+
+| Name      | Description (EN)                          | Description (CN)       |
+| --------- | ----------------------------------------- | ---------------------- |
+| container | The flex container wrapping the metrics.  | 包裹指标的 flex 容器。 |
+
+## Properties / 属性
+
+| Name      | Type                                             | Default        | Attribute   | Description (EN)                                                       | Description (CN)                          |
+| --------- | ------------------------------------------------ | -------------- | ----------- | ---------------------------------------------------------------------- | ----------------------------------------- |
+| direction | `'horizontal' \| 'vertical'`                     | `'horizontal'` | `direction` | Layout direction of the metrics group.                                 | 指标组的排列方向。                        |
+| gap       | `number`                                         | `16`           | `gap`       | Gap between metrics items, in pixels.                                  | 指标项之间的间距，单位为像素。            |
+| align     | `'left' \| 'center' \| 'right'`                  | `'left'`       | `align`     | Alignment of items within the group (only effective when vertical).    | 指标项在组内的对齐方式（仅在垂直时生效）。|
+| data      | `MetricsData \| MetricsData[] \| null`           | `null`         | —           | Data-driven mode: auto-renders children. Single object wraps to array. | 数据驱动模式：自动渲染子元素。单个对象自动转为数组。 |
+| params    | `MetricsGroupParams`                             | `{}`           | —           | Generic config object. Overrides `direction`, `gap`, `align` for overlapping keys. | 通用配置对象。同名键覆盖 `direction`/`gap`/`align`。 |
+
+## Usage / 用法
+
+### Horizontal Group / 水平排列
+
+```html
+<aithe-metrics-group direction="horizontal" gap="32">
+  <aithe-metrics label="Users" value="1,024" variant="primary"></aithe-metrics>
+  <aithe-metrics label="Revenue" value="$42.5K" variant="success"></aithe-metrics>
+  <aithe-metrics label="Errors" value="3" variant="danger"></aithe-metrics>
+</aithe-metrics-group>
+```
+
+### Vertical Group / 垂直排列
+
+```html
+<aithe-metrics-group direction="vertical" gap="12">
+  <aithe-metrics label="CPU Usage" value="23%" variant="neutral"></aithe-metrics>
+  <aithe-metrics label="Memory" value="1.2 GB" variant="neutral"></aithe-metrics>
+  <aithe-metrics label="Disk" value="45% Used" variant="warning"></aithe-metrics>
+</aithe-metrics-group>
+```
+
+### Vertical Alignment / 垂直对齐方式
+
+```html
+<aithe-metrics-group direction="vertical" gap="8" align="left">
+  <aithe-metrics label="Left Aligned" value="100" variant="primary"></aithe-metrics>
+  <aithe-metrics label="Left Aligned" value="200" variant="success"></aithe-metrics>
+</aithe-metrics-group>
+
+<aithe-metrics-group direction="vertical" gap="8" align="center">
+  <aithe-metrics label="Centered" value="100" variant="primary"></aithe-metrics>
+  <aithe-metrics label="Centered" value="200" variant="success"></aithe-metrics>
+</aithe-metrics-group>
+
+<aithe-metrics-group direction="vertical" gap="8" align="right">
+  <aithe-metrics label="Right Aligned" value="100" variant="primary"></aithe-metrics>
+  <aithe-metrics label="Right Aligned" value="200" variant="success"></aithe-metrics>
+</aithe-metrics-group>
+```
+
+### Inside Dashboard Panel / 在仪表盘面板中使用
+
+```html
+<aithe-dashboard-panel panel-id="stats" x="0" y="0" w="4" h="3" label="Statistics">
+  <aithe-metrics-group direction="vertical" gap="4" style="padding:8px;">
+    <aithe-metrics label="Active Users" value="1,024" variant="primary"></aithe-metrics>
+    <aithe-metrics label="New Today" value="47" variant="neutral"></aithe-metrics>
+  </aithe-metrics-group>
+</aithe-dashboard-panel>
+```
+
+### Data-driven / 数据驱动
+
+```html
+<aithe-metrics-group direction="horizontal" gap="24" id="my-metrics"></aithe-metrics-group>
+<script>
+  document.getElementById('my-metrics').items = [
+    { label: 'Users', value: '1,024', variant: 'primary', showDivider: true },
+    { label: 'Revenue', value: '$42.5K', variant: 'success', showDivider: true },
+    { label: 'Errors', value: '3', variant: 'danger' },
+  ];
+</script>
+```
+
+### Data-driven with params / params 覆盖
+
+```html
+<aithe-metrics-group id="my-metrics-2"></aithe-metrics-group>
+<script>
+  const el = document.getElementById('my-metrics-2');
+  el.params = { direction: 'horizontal', gap: 24 };
+  el.data = [
+    { label: 'Users', value: '1,024', variant: 'primary' },
+    { label: 'Revenue', value: '$42.5K', variant: 'success' },
+  ];
+</script>
+```
+
+> `data` accepts both a single `MetricsData` object and an array; a single object is automatically wrapped into a one-element array.
+> `data` 支持单个 `MetricsData` 对象或数组，传入单个对象时自动转为单元素数组。

package/docs/api/data/metrics.md

@@ -0,0 +1,153 @@
+# AitheMetrics / AitheMetrics 业务指标
+
+> Displays a business metric with label, value, and an optional slot for custom content. Supports variant-based color styling for the value, configurable alignment, and size scale.
+> 展示业务指标，含标签、数值和可选的自定义内容插槽。数值支持基于 variant 的颜色样式，支持配置对齐方式和尺寸规格。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/data/metrics';
+```
+
+## Description / 描述
+
+`<aithe-metrics>` renders a metric value prominently on top with an optional slot for inline custom content (such as an icon or badge), and a label below. It is designed for use inside `<aithe-metrics-group>`, `<aithe-dashboard-panel>`, or any statistic card context. The `variant` property controls the color of the value text, the `align` property controls text alignment, and the `scale` property controls the size of the value and label.
+
+`<aithe-metrics>` 上方突出显示指标数值，带可选的自定义内容插槽（如图标或徽章），下方显示标签。设计用于 `<aithe-metrics-group>`、`<aithe-dashboard-panel>` 内部或任何统计卡片场景。`variant` 属性控制数值文本的颜色，`align` 属性控制对齐方式，`scale` 属性控制数值和标签的尺寸。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                          | Description (CN)           |
+| --------- | ----------------------------------------- | -------------------------- |
+| (default) | Custom content displayed next to the value. | 显示在数值旁边的自定义内容。 |
+
+## CSS Parts / CSS 部件
+
+| Name  | Description (EN)          | Description (CN) |
+| ----- | ------------------------- | ---------------- |
+| value | The metric value element. | 指标数值元素。   |
+| label | The metric label element. | 指标标签元素。   |
+
+## Properties / 属性
+
+| Name        | Type                                                                  | Default     | Attribute      | Description (EN)                                                    | Description (CN)                         |
+| ----------- | --------------------------------------------------------------------- | ----------- | -------------- | ------------------------------------------------------------------- | ---------------------------------------- |
+| label       | `string`                                                              | `''`        | `label`        | Metric label text displayed below the value.                        | 显示在数值下方的标签文本。               |
+| value       | `string`                                                              | `''`        | `value`        | Metric value text displayed prominently.                            | 突出显示的数值文本。                     |
+| showDivider | `boolean`                                                             | `false`      | `show-divider` | Whether to show a primary-colored divider on the left side.         | 是否在左侧显示 primary 颜色的分割线。    |
+| align       | `'left' \| 'center' \| 'right'`                                       | `'center'`    | `align`        | Text alignment of the metric content.                                | 指标内容的对齐方式。                     |
+| scale       | `'small' \| 'normal' \| 'large'`                                      | `'small'`  | `scale`        | Size scale of the metric.                                            | 指标的尺寸规格。                         |
+| data        | `MetricsData \| MetricsData[] \| null`                                | `null`       | —              | Data-driven mode: set all properties from one object. Array uses first item. | 数据驱动模式：通过单个对象设置所有属性。数组仅取首项。 |
+| params      | `MetricsData`                                                         | `{}`         | —              | Generic config object. Overrides `data` for overlapping keys.        | 通用配置对象。同名键优先级高于 `data`。 |
+
+### MetricsData
+
+| Field       | Type                                                                  | Default     | Description (EN)                    | Description (CN)         |
+| ----------- | --------------------------------------------------------------------- | ----------- | ----------------------------------- | ------------------------ |
+| label       | `string`                                                              | `''`        | Metric label text.                  | 指标标签文本。           |
+| value       | `string`                                                              | `''`        | Metric value text.                  | 指标数值文本。           |
+| variant      | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'default'` | Color variant for the value text.    | 数值文本的颜色变体。     |
+| showDivider | `boolean`                                                             | `false`     | Whether to show a divider.          | 是否显示分割线。         |
+| align       | `'left' \| 'center' \| 'right'`                                       | `'center'`    | Text alignment of the metric content.| 指标内容的对齐方式。     |
+| scale       | `'small' \| 'normal' \| 'large'`                                      | `'small'`  | Size scale of the metric.            | 指标的尺寸规格。         |
+
+## Usage / 用法
+
+### Basic / 基础用法
+
+```html
+<aithe-metrics label="Active Users" value="1,024" variant="primary"></aithe-metrics>
+```
+
+### With Custom Slot / 自定义插槽
+
+```html
+<aithe-metrics label="Revenue" value="$42.5K" variant="success">
+  <aithe-icon name="arrowUp" size="16"></aithe-icon>
+</aithe-metrics>
+```
+
+### With Divider / 带分割线
+
+```html
+<aithe-metrics label="Users" value="1,024" variant="primary" show-divider></aithe-metrics>
+```
+
+### Alignment / 对齐方式
+
+```html
+<aithe-metrics label="Left" value="100" variant="primary" align="left"></aithe-metrics>
+<aithe-metrics label="Center" value="200" variant="success" align="center"></aithe-metrics>
+<aithe-metrics label="Right" value="300" variant="danger" align="right"></aithe-metrics>
+```
+
+### Scale / 尺寸规格
+
+```html
+<aithe-metrics label="Small" value="1K" variant="primary" scale="small"></aithe-metrics>
+<aithe-metrics label="Normal" value="1K" variant="success" scale="normal"></aithe-metrics>
+<aithe-metrics label="Large" value="1K" variant="danger" scale="large"></aithe-metrics>
+```
+
+### In a Group / 在组中使用
+
+```html
+<aithe-metrics-group direction="horizontal" gap="24">
+  <aithe-metrics label="Users" value="1,024" variant="primary"></aithe-metrics>
+  <aithe-metrics label="Revenue" value="$42.5K" variant="success"></aithe-metrics>
+  <aithe-metrics label="Errors" value="3" variant="danger"></aithe-metrics>
+</aithe-metrics-group>
+```
+
+### With Intent / 带颜色意图
+
+```html
+<aithe-metrics label="Revenue" value="$42.5K" variant="success"></aithe-metrics>
+<aithe-metrics label="Errors" value="3" variant="danger"></aithe-metrics>
+<aithe-metrics label="Pending" value="12" variant="warning"></aithe-metrics>
+```
+
+### With Slot Content / 带插槽内容
+
+```html
+<aithe-metrics-group direction="horizontal" gap="32">
+  <aithe-metrics label="Conversion Rate" value="68.5%" variant="primary">
+    <aithe-icon name="arrowUp" size="16"></aithe-icon>
+  </aithe-metrics>
+  <aithe-metrics label="Bounce Rate" value="12.3%" variant="warning">
+    <aithe-icon name="arrowDown" size="16"></aithe-icon>
+  </aithe-metrics>
+</aithe-metrics-group>
+```
+
+### Inside Dashboard Panel / 在仪表盘面板中使用
+
+```html
+<aithe-dashboard-panel panel-id="stats" x="0" y="0" w="4" h="2" label="Statistics">
+  <aithe-metrics-group direction="horizontal" gap="24">
+    <aithe-metrics label="Users" value="1,024" variant="primary"></aithe-metrics>
+    <aithe-metrics label="Revenue" value="$42.5K" variant="success"></aithe-metrics>
+    <aithe-metrics label="Errors" value="3" variant="danger"></aithe-metrics>
+  </aithe-metrics-group>
+</aithe-dashboard-panel>
+```
+
+### Data-driven / 数据驱动
+
+```html
+<aithe-metrics data='{"label":"Users","value":"1,024","variant":"primary","showDivider":true}'></aithe-metrics>
+```
+
+### Data-driven with params override / params 覆盖
+
+```html
+<aithe-metrics id="my-metrics"></aithe-metrics>
+<script>
+  const el = document.getElementById('my-metrics');
+  el.params = { align: 'center', scale: 'large', showDivider: true };
+  el.data = { label: 'Users', value: '1,024', variant: 'primary' };
+</script>
+```
+
+> `data` also accepts an array; when an array is provided, only the first item is used.
+> `data` 也接受数组，传入数组时仅取第一个元素。

package/docs/api/data/table-column.md

@@ -18,7 +18,7 @@ Place `<aithe-table-column>` elements as children of `<aithe-table>` to define c
 | align | 'left' \| 'center' \| 'right' | 'left' | `align` | Text alignment. | 文本对齐方式。 |
 | sortable | `boolean` | false | `sortable` | Enable client-side sorting. | 启用客户端排序。 |
 | icon | `string` | '' | `icon` | Icon name rendered in the header via aithe-icon. | 通过 aithe-icon 在表头渲染的图标名称。 |
-| intent | AitheIntent | 'default' | `intent` | Visual intent / semantic color for the column cells. | 列单元格的视觉意图/语义色。 |
+| variant | AitheVariant | 'default' | `variant` | Visual variant / semantic color for the column cells. | 列单元格的视觉变体/语义色。 |
 | cellRenderer | Function | undefined | — | Custom cell renderer: `(value, record, rowIndex) => unknown`. Only settable via JS property (not an HTML attribute). | 自定义单元格渲染器：`(value, record, rowIndex) => unknown`。仅可通过 JS 属性设置（非 HTML 属性）。 |
 
 ## cellRenderer Signature / cellRenderer 签名
@@ -50,7 +50,7 @@ Place `<aithe-table-column>` elements as children of `<aithe-table>` to define c
 ```html
 <aithe-table .data=${records} striped>
   <aithe-table-column id="name" title="Name" sortable></aithe-table-column>
-  <aithe-table-column id="status" title="Status" intent="success"></aithe-table-column>
+  <aithe-table-column id="status" title="Status" variant="success"></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>

package/docs/api/data/table.md

@@ -60,7 +60,7 @@ AitheTable 支持两种列定义模式：
 | 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. | 列单元格的视觉意图/语义色。 |
+| variant | AitheVariant | Visual variant / semantic color for the column cells. | 列单元格的视觉变体/语义色。 |
 
 ## Examples / 示例
 
@@ -81,7 +81,7 @@ AitheTable 支持两种列定义模式：
 <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="status" title="Status" variant="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>

package/docs/api/data/timeline.md

@@ -38,7 +38,7 @@ AitheTimeline 支持两种节点定义模式：
 |-------|------|-------------------|-------------------|
 | content | `string` | Item content text. | 节点内容文本。 |
 | timestamp | `string` | Timestamp label text. | 时间戳标签文本。 |
-| type | 'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' | Color variant for the dot indicator. | 圆点指示器的颜色类型。 |
+| variant | 'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' | Color variant for the dot indicator. | 圆点指示器的颜色变体。 |
 | dot | `string` | Custom dot content (overrides default circle). | 自定义圆点内容（覆盖默认圆圈）。 |
 
 ## Events / 事件
@@ -53,7 +53,7 @@ AitheTimeline 支持两种节点定义模式：
 
 ```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"}]'
+  items='[{"content":"Design tokens published","timestamp":"09:00","variant":"primary"},{"content":"Demo routing completed","timestamp":"11:30","variant":"success"},{"content":"Accessibility audit pending","timestamp":"15:20","variant":"warning"}]'
 ></aithe-timeline>
 ```
 
@@ -61,7 +61,7 @@ AitheTimeline 支持两种节点定义模式：
 
 ```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-item timestamp="2024-01-01" variant="primary">Step 1</aithe-timeline-item>
+  <aithe-timeline-item timestamp="2024-01-02" variant="success">Step 2</aithe-timeline-item>
 </aithe-timeline>
 ```