@aithe/aithe-ui 26.2.2 → 26.2.3

package/docs/api/summary.md

@@ -1,8 +1,8 @@
 # Aithe UI API Reference / Aithe UI API 文档
 
-Aithe UI is a Lit 3.x Web Components library developed by the Archest team, providing a comprehensive set of reusable UI primitives for modern web applications.
+Aithe UI is a Lit 3.x Web Components library developed by the Archest team, providing a comprehensive set of reusable UI primitives for modern web applications. The library features a **Theme × Shape × Shadow × Typo** orthogonal customization system — color themes, shape styles, shadow styles, and typography styles can be freely combined without coupling.
 
-Aithe UI 是 Archest 团队基于 Lit 3.x 开发的 Web Components UI 库，为现代 Web 应用提供一套完整的可复用 UI 基础组件。
+Aithe UI 是 Archest 团队基于 Lit 3.x 开发的 Web Components UI 库，为现代 Web 应用提供一套完整的可复用 UI 基础组件。库内置 **Theme × Shape × Shadow × Typo** 正交定制体系——颜色主题、形状风格、阴影风格和排版风格可自由组合，互不耦合。
 
 ---
 
@@ -10,20 +10,20 @@ Aithe UI 是 Archest 团队基于 Lit 3.x 开发的 Web Components UI 库，为
 
 Common UI primitives used across all applications. 通用 UI 基础组件，适用于各类应用场景。
 
-| Component | Tag | Description |
-|-----------|-----|-------------|
-| [Button](basic/button.md) | `<aithe-button>` | Action trigger with variants, sizes, and loading state. 按钮，支持变体、尺寸和加载状态。 |
-| [Button Group](basic/button-group.md) | `<aithe-button-group>` | Layout helper for consistent button spacing. 按钮组布局辅助，提供统一间距。 |
-| [Icon](basic/icon.md) | `<aithe-icon>` | Vector icon with built-in glyph map. 矢量图标，内置图标映射。 |
-| [Input](basic/input.md) | `<aithe-input>` | Single-line text input with validation support. 单行文本输入，支持校验。 |
-| [Textarea](basic/textarea.md) | `<aithe-textarea>` | Multi-line text input with auto-grow. 多行文本输入，支持自动增长。 |
-| [Card](basic/card.md) | `<aithe-card>` | Container with header, body, and footer sections. 卡片容器，含标题、正文和底部区域。 |
-| [Tag](basic/tag.md) | `<aithe-tag>` | Colored label with close and select behavior. 彩色标签，支持关闭和选中。 |
-| [Badge](basic/badge.md) | `<aithe-badge>` | Count/dot indicator overlaid on an anchor. 徽标/计数指示器，覆盖在锚点上。 |
-| [Avatar](basic/avatar.md) | `<aithe-avatar>` | Image, initials, or custom content display. 头像，显示图片、首字母或自定义内容。 |
-| [Divider](basic/divider.md) | `<aithe-divider>` | Horizontal or vertical separator line. 水平或垂直分割线。 |
-| [Empty](basic/empty.md) | `<aithe-empty>` | Empty state placeholder with icon and text. 空状态占位组件。 |
-| [Chip](basic/chip.md) | `<aithe-chip>` | Compact selectable chip with close button. 紧凑可选中芯片，支持关闭按钮。 |
+| Component                             | Tag                    | Description                                                                              |
+| ------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------- |
+| [Button](basic/button.md)             | `<aithe-button>`       | Action trigger with variants, sizes, and loading state. 按钮，支持变体、尺寸和加载状态。 |
+| [Button Group](basic/button-group.md) | `<aithe-button-group>` | Layout helper for consistent button spacing. 按钮组布局辅助，提供统一间距。              |
+| [Icon](basic/icon.md)                 | `<aithe-icon>`         | Vector icon with built-in glyph map. 矢量图标，内置图标映射。                            |
+| [Input](basic/input.md)               | `<aithe-input>`        | Single-line text input with validation support. 单行文本输入，支持校验。                 |
+| [Textarea](basic/textarea.md)         | `<aithe-textarea>`     | Multi-line text input with auto-grow. 多行文本输入，支持自动增长。                       |
+| [Card](basic/card.md)                 | `<aithe-card>`         | Container with header, body, and footer sections. 卡片容器，含标题、正文和底部区域。     |
+| [Tag](basic/tag.md)                   | `<aithe-tag>`          | Colored label with close and select behavior. 彩色标签，支持关闭和选中。                 |
+| [Badge](basic/badge.md)               | `<aithe-badge>`        | Count/dot indicator overlaid on an anchor. 徽标/计数指示器，覆盖在锚点上。               |
+| [Avatar](basic/avatar.md)             | `<aithe-avatar>`       | Image, initials, or custom content display. 头像，显示图片、首字母或自定义内容。         |
+| [Divider](basic/divider.md)           | `<aithe-divider>`      | Horizontal or vertical separator line. 水平或垂直分割线。                                |
+| [Empty](basic/empty.md)               | `<aithe-empty>`        | Empty state placeholder with icon and text. 空状态占位组件。                             |
+| [Chip](basic/chip.md)                 | `<aithe-chip>`         | Compact selectable chip with close button. 紧凑可选中芯片，支持关闭按钮。                |
 
 ---
 
@@ -31,20 +31,34 @@ Common UI primitives used across all applications. 通用 UI 基础组件，适
 
 Structural layout primitives for page composition. 页面结构布局基础组件。
 
-| Component | Tag | Description |
-|-----------|-----|-------------|
-| [Container](layout/container.md) | `<aithe-container>` | Top-level page layout container. 顶层页面布局容器。 |
-| [Row](layout/row.md) | `<aithe-row>` | 24-grid row for grid layout system. 24栅格行容器。 |
-| [Col](layout/col.md) | `<aithe-col>` | 24-grid column item. 24栅格列元素。 |
-| [Flex](layout/flex.md) | `<aithe-flex>` | Quick flex layout helper. 快速弹性布局辅助。 |
-| [Space](layout/space.md) | `<aithe-space>` | Equal spacing helper for child elements. 等间距辅助组件。 |
-| [Page Container](layout/page-container.md) | `<aithe-page-container>` | Standard page shell with title and spacing. 标准页面外壳。 |
-| [Page](layout/page.md) | `<aithe-page>` | Full-page layout with header and content area. 全页布局，含标题区和内容区。 |
-| [Collapse](layout/collapse.md) | `<aithe-collapse>` | Accordion / multi-expand collapse container. 手风琴/多展开折叠容器。 |
-| [Collapse Item](layout/collapse-item.md) | `<aithe-collapse-item>` | Single collapsible panel. 单个可折叠面板。 |
-| [Timeline](layout/timeline.md) | `<aithe-timeline>` | Timeline container for process records. 时间线容器。 |
-| [Timeline Item](layout/timeline-item.md) | `<aithe-timeline-item>` | Single timeline node. 时间线节点。 |
-| [Affix](layout/affix.md) | `<aithe-affix>` | Sticky wrapper that pins content on scroll. 固定/吸顶包装器。 |
+| Component                                | Tag                     | Description                                                          |
+| ---------------------------------------- | ----------------------- | -------------------------------------------------------------------- |
+| [Container](layout/container.md)         | `<aithe-container>`     | Top-level page layout container. 顶层页面布局容器。                  |
+| [Row](layout/row.md)                     | `<aithe-row>`           | 24-grid row for grid layout system. 24栅格行容器。                   |
+| [Col](layout/col.md)                     | `<aithe-col>`           | 24-grid column item. 24栅格列元素。                                  |
+| [Flex](layout/flex.md)                   | `<aithe-flex>`          | Quick flex layout helper. 快速弹性布局辅助。                         |
+| [Space](layout/space.md)                 | `<aithe-space>`         | Equal spacing helper for child elements. 等间距辅助组件。            |
+| [Collapse](layout/collapse.md)           | `<aithe-collapse>`      | Accordion / multi-expand collapse container. 手风琴/多展开折叠容器。 |
+| [Collapse Item](layout/collapse-item.md) | `<aithe-collapse-item>` | Single collapsible panel. 单个可折叠面板。                           |
+| [Timeline](data/timeline.md)             | `<aithe-timeline>`      | Timeline container for process records. 时间线容器。                 |
+| [Timeline Item](data/timeline-item.md)   | `<aithe-timeline-item>` | Single timeline node. 时间线节点。                                   |
+| [Affix](layout/affix.md)                 | `<aithe-affix>`         | Sticky wrapper that pins content on scroll. 固定/吸顶包装器。        |
+
+---
+
+## Framework / 框架组件
+
+Application-level layout and routing components for admin-style applications. 管理后台类应用的框架级布局和路由组件。
+
+| Component                                       | Tag                       | Description                                                                                                                |
+| ----------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| [Header](framework/header.md)                   | `<aithe-header>`          | Top navigation bar with brand, actions, and slots. 顶部导航栏，含品牌、操作区和插槽。                                      |
+| [Body](framework/body.md)                       | `<aithe-body>`            | Main content area with centered/wide layout modes. 主内容区，支持居中/舒展布局模式。                                       |
+| [Sidebar](framework/sidebar.md)                 | `<aithe-sidebar>`         | Collapsible sidebar with brand, menu tree, and action buttons. 可折叠侧边栏，含品牌、菜单树和操作按钮。                    |
+| [Page](framework/page.md)                       | `<aithe-page>`            | Route container that renders the matched page component. 路由容器，渲染匹配到的页面组件。                                  |
+| [Dashboard](framework/dashboard.md)             | `<aithe-dashboard>`       | Drag-and-drop dashboard with grid layout, toolbar, and state persistence. 拖拽式仪表盘，支持格子布局、工具栏和状态持久化。 |
+| [Dashboard Panel](framework/dashboard-panel.md) | `<aithe-dashboard-panel>` | Dashboard panel card with drag, close, maximize and slot content. 仪表盘面板卡片，支持拖拽、关闭、最大化和插槽内容。       |
+
 
 ---
 
@@ -52,15 +66,15 @@ Structural layout primitives for page composition. 页面结构布局基础组
 
 Components for site navigation and wayfinding. 站点导航和路径指引组件。
 
-| Component | Tag | Description |
-|-----------|-----|-------------|
-| [Menu](navigation/menu.md) | `<aithe-menu>` | Navigation menu with vertical/horizontal modes. 导航菜单，支持垂直/水平模式。 |
-| [Menu Item](navigation/menu-item.md) | `<aithe-menu-item>` | Leaf navigation item. 叶子导航项。 |
-| [Sub Menu](navigation/sub-menu.md) | `<aithe-sub-menu>` | Nested expandable sub-menu. 嵌套可展开子菜单。 |
-| [Breadcrumb](navigation/breadcrumb.md) | `<aithe-breadcrumb>` | Page hierarchy breadcrumb. 面包屑导航。 |
-| [Breadcrumb Item](navigation/breadcrumb-item.md) | `<aithe-breadcrumb-item>` | Single breadcrumb link or text. 单个面包屑项。 |
-| [Steps](navigation/steps.md) | `<aithe-steps>` | Stepper for process flow visualization. 步骤条，用于流程可视化。 |
-| [Back Top](navigation/back-top.md) | `<aithe-back-top>` | Floating button to scroll back to top. 回到顶部浮动按钮。 |
+| Component                                        | Tag                       | Description                                                                   |
+| ------------------------------------------------ | ------------------------- | ----------------------------------------------------------------------------- |
+| [Menu](navigation/menu.md)                       | `<aithe-menu>`            | Navigation menu with vertical/horizontal modes. 导航菜单，支持垂直/水平模式。 |
+| [Menu Item](navigation/menu-item.md)             | `<aithe-menu-item>`       | Leaf navigation item. 叶子导航项。                                            |
+| [Sub Menu](navigation/sub-menu.md)               | `<aithe-sub-menu>`        | Nested expandable sub-menu. 嵌套可展开子菜单。                                |
+| [Breadcrumb](navigation/breadcrumb.md)           | `<aithe-breadcrumb>`      | Page hierarchy breadcrumb. 面包屑导航。                                       |
+| [Breadcrumb Item](navigation/breadcrumb-item.md) | `<aithe-breadcrumb-item>` | Single breadcrumb link or text. 单个面包屑项。                                |
+| [Steps](navigation/steps.md)                     | `<aithe-steps>`           | Stepper for process flow visualization. 步骤条，用于流程可视化。              |
+| [Back Top](navigation/back-top.md)               | `<aithe-back-top>`        | Floating button to scroll back to top. 回到顶部浮动按钮。                     |
 
 ---
 
@@ -68,24 +82,25 @@ Components for site navigation and wayfinding. 站点导航和路径指引组件
 
 Interactive form controls for data entry and selection. 交互式表单控件，用于数据输入和选择。
 
-| Component | Tag | Description |
-|-----------|-----|-------------|
-| [Checkbox](form/checkbox.md) | `<aithe-checkbox>` | Binary selection control. 二选控件。 |
-| [Checkbox Group](form/checkbox-group.md) | `<aithe-checkbox-group>` | Multi-select group of checkboxes. 多选复选框组。 |
-| [Radio](form/radio.md) | `<aithe-radio>` | Single selection control. 单选控件。 |
-| [Radio Group](form/radio-group.md) | `<aithe-radio-group>` | Group of mutually exclusive radios. 单选按钮组。 |
-| [Select](form/select.md) | `<aithe-select>` | Dropdown single/multi selector. 下拉单选/多选器。 |
-| [Switch](form/switch.md) | `<aithe-switch>` | Toggle switch for on/off state. 开关切换控件。 |
-| [Color Picker](form/color-picker.md) | `<aithe-color-picker>` | Color selection input. 颜色选择器。 |
-| [Combobox](form/combobox.md) | `<aithe-combobox>` | Searchable dropdown with free input. 可搜索下拉输入框。 |
-| [Date Picker](form/date-picker.md) | `<aithe-date-picker>` | Date selection input. 日期选择器。 |
-| [Time Picker](form/time-picker.md) | `<aithe-time-picker>` | Time selection input. 时间选择器。 |
-| [Slider](form/slider.md) | `<aithe-slider>` | Range slider for numeric input. 滑块数值输入。 |
-| [Rate](form/rate.md) | `<aithe-rate>` | Star rating input. 星级评分输入。 |
-| [Form](form/form.md) | `<aithe-form>` | Form container with validation. 表单容器，支持校验。 |
-| [Form Item](form/form-item.md) | `<aithe-form-item>` | Form field wrapper with label and validation. 表单字段包装器。 |
-| [Upload](form/upload.md) | `<aithe-upload>` | File upload control. 文件上传控件。 |
-| [Transfer](form/transfer.md) | `<aithe-transfer>` | Dual-list transfer selector. 双栏穿梭选择器。 |
+| Component                                | Tag                      | Description                                                                              |
+| ---------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
+| [Checkbox](form/checkbox.md)             | `<aithe-checkbox>`       | Binary selection control. 二选控件。                                                     |
+| [Checkbox Group](form/checkbox-group.md) | `<aithe-checkbox-group>` | Multi-select group of checkboxes. 多选复选框组。                                         |
+| [Radio](form/radio.md)                   | `<aithe-radio>`          | Single selection control. 单选控件。                                                     |
+| [Radio Group](form/radio-group.md)       | `<aithe-radio-group>`    | Group of mutually exclusive radios. 单选按钮组。                                         |
+| [Select](form/select.md)                 | `<aithe-select>`         | Dropdown single/multi selector. 下拉单选/多选器。                                        |
+| [Switch](form/switch.md)                 | `<aithe-switch>`         | Toggle switch for on/off state. 开关切换控件。                                           |
+| [Color Picker](form/color-picker.md)     | `<aithe-color-picker>`   | Color selection input. 颜色选择器。                                                      |
+| [Combobox](form/combobox.md)             | `<aithe-combobox>`       | Searchable dropdown with free input. 可搜索下拉输入框。                                  |
+| [Date Picker](form/date-picker.md)       | `<aithe-date-picker>`    | Date selection input. 日期选择器。                                                       |
+| [Time Picker](form/time-picker.md)       | `<aithe-time-picker>`    | Time selection input. 时间选择器。                                                       |
+| [Slider](form/slider.md)                 | `<aithe-slider>`         | Range slider for numeric input. 滑块数值输入。                                           |
+| [Rate](form/rate.md)                     | `<aithe-rate>`           | Star rating input. 星级评分输入。                                                        |
+| [Form](form/form.md)                     | `<aithe-form>`           | Form container with validation. 表单容器，支持校验。                                     |
+| [Form Item](form/form-item.md)           | `<aithe-form-item>`      | Form field wrapper with label and validation. 表单字段包装器。                           |
+| [Upload](form/upload.md)                 | `<aithe-upload>`         | File upload control. 文件上传控件。                                                      |
+| [Transfer](form/transfer.md)             | `<aithe-transfer>`       | Dual-list transfer selector. 双栏穿梭选择器。                                            |
+| [Autoform](form/autoform.md)             | `<aithe-autoform>`       | JSON-driven auto-rendering form with validation. JSON 配置驱动的自动渲染表单，支持校验。 |
 
 ---
 
@@ -93,18 +108,17 @@ Interactive form controls for data entry and selection. 交互式表单控件，
 
 Components for user feedback, overlays, and notifications. 用户反馈、浮层和通知组件。
 
-| Component | Tag | Description |
-|-----------|-----|-------------|
-| [Dialog](feedback/dialog.md) | `<aithe-dialog>` | Modal dialog overlay. 模态对话框浮层。 |
-| [Modal](feedback/modal.md) | `<aithe-modal>` | Lightweight modal wrapper. 轻量模态包装器。 |
-| [Drawer](feedback/drawer.md) | `<aithe-drawer>` | Side panel drawer. 侧边抽屉面板。 |
-| [Tooltip](feedback/tooltip.md) | `<aithe-tooltip>` | Hover tooltip overlay. 悬停提示浮层。 |
-| [Popover](feedback/popover.md) | `<aithe-popover>` | Click-triggered popover. 点击触发弹出框。 |
-| [Dropdown](feedback/dropdown.md) | `<aithe-dropdown>` | Dropdown menu overlay. 下拉菜单浮层。 |
-| [Toast](feedback/toast.md) | `<aithe-toast>` | Auto-dismiss toast notification. 自动消失的轻提示。 |
-| [Alert](feedback/alert.md) | `<aithe-alert>` | Inline alert banner. 内嵌警告提示。 |
-| [Notification](feedback/notification.md) | `<aithe-notification>` | Corner notification card. 角落通知卡片。 |
-| [Loading](feedback/loading.md) | `<aithe-loading>` | Loading spinner overlay. 加载旋转浮层。 |
+| Component                                | Tag                    | Description                                         |
+| ---------------------------------------- | ---------------------- | --------------------------------------------------- |
+| [Dialog](feedback/dialog.md)             | `<aithe-dialog>`       | Modal dialog overlay. 模态对话框浮层。              |
+| [Modal](feedback/modal.md)               | `<aithe-modal>`        | Lightweight modal wrapper. 轻量模态包装器。         |
+| [Drawer](feedback/drawer.md)             | `<aithe-drawer>`       | Side panel drawer. 侧边抽屉面板。                   |
+| [Tooltip](feedback/tooltip.md)           | `<aithe-tooltip>`      | Hover tooltip overlay. 悬停提示浮层。               |
+| [Popover](feedback/popover.md)           | `<aithe-popover>`      | Click-triggered popover. 点击触发弹出框。           |
+| [Toast](feedback/toast.md)               | `<aithe-toast>`        | Auto-dismiss toast notification. 自动消失的轻提示。 |
+| [Alert](feedback/alert.md)               | `<aithe-alert>`        | Inline alert banner. 内嵌警告提示。                 |
+| [Notification](feedback/notification.md) | `<aithe-notification>` | Corner notification card. 角落通知卡片。            |
+| [Loading](feedback/loading.md)           | `<aithe-loading>`      | Loading spinner overlay. 加载旋转浮层。             |
 
 ---
 
@@ -112,15 +126,18 @@ Components for user feedback, overlays, and notifications. 用户反馈、浮层
 
 Components for displaying and interacting with structured data. 结构化数据展示和交互组件。
 
-| Component | Tag | Description |
-|-----------|-----|-------------|
-| [Table](data/table.md) | `<aithe-table>` | Data table with sorting and selection. 数据表格，支持排序和选择。 |
-| [Table Column](data/table-column.md) | `<aithe-table-column>` | Column definition for DOM-defined mode. DOM 定义模式的列定义。 |
-| [Tabs](data/tabs.md) | `<aithe-tabs>` | Tab navigation container. 标签页导航容器。 |
-| [Tab Pane](data/tab-pane.md) | `<aithe-tab-pane>` | Single tab content panel. 单个标签页内容面板。 |
-| [Tree](data/tree.md) | `<aithe-tree>` | Hierarchical tree view. 层级树视图。 |
-| [Tree Menu](data/tree-menu.md) | `<aithe-tree-menu>` | Data-driven tree menu with active highlighting. 数据驱动树形菜单，支持高亮选中。 |
-| [Pagination](data/pagination.md) | `<aithe-pagination>` | Page navigation for large datasets. 大数据集分页导航。 |
+| Component                            | Tag                    | Description                                                                      |
+| ------------------------------------ | ---------------------- | -------------------------------------------------------------------------------- |
+| [Table](data/table.md)               | `<aithe-table>`        | Data table with sorting and selection. 数据表格，支持排序和选择。                |
+| [Table Column](data/table-column.md) | `<aithe-table-column>` | Column definition for DOM-defined mode. DOM 定义模式的列定义。                   |
+| [Tabs](data/tabs.md)                 | `<aithe-tabs>`         | Tab navigation container. 标签页导航容器。                                       |
+| [Tab Pane](data/tab-pane.md)         | `<aithe-tab-pane>`     | Single tab content panel. 单个标签页内容面板。                                   |
+| [Tree](data/tree.md)                 | `<aithe-tree>`         | Hierarchical tree view. 层级树视图。                                             |
+| [Tree Menu](data/tree-menu.md)       | `<aithe-tree-menu>`    | Data-driven tree menu with active highlighting. 数据驱动树形菜单，支持高亮选中。 |
+| [Dropdown](data/dropdown.md)         | `<aithe-dropdown>`     | Dropdown menu overlay. 下拉菜单浮层。                                           |
+| [Metrics](data/metrics.md)                 | `<aithe-metrics>`         | Business metric display with label, value and variant colors. 业务指标展示，含标签、数值和 variant 颜色样式。                 |
+| [Metrics Group](data/metrics-group.md)     | `<aithe-metrics-group>`   | Container that groups multiple metrics with direction and gap. 业务指标组容器，支持方向和间距配置。                         |
+| [Pagination](data/pagination.md)     | `<aithe-pagination>`   | Page navigation for large datasets. 大数据集分页导航。                           |
 
 ---
 
@@ -128,12 +145,15 @@ Components for displaying and interacting with structured data. 结构化数据
 
 Rich content display and media components. 富内容展示和媒体组件。
 
-| Component | Tag | Description |
-|-----------|-----|-------------|
-| [Carousel](display/carousel.md) | `<aithe-carousel>` | Slot-based image/content carousel. 轮播组件。 |
-| [Comparison](display/comparison.md) | `<aithe-comparison>` | Before/after comparison slider. 前后对比滑块。 |
-| [Animated Image](display/animated-image.md) | `<aithe-animated-image>` | Animated image with pan/zoom. 动画图片，支持平移/缩放。 |
-| [Markdown](display/markdown.md) | `<aithe-markdown>` | Lightweight markdown renderer. 轻量 Markdown 渲染器。 |
+| Component                                     | Tag                       | Description                                                                                      |
+| --------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------ |
+| [Carousel](display/carousel.md)               | `<aithe-carousel>`        | Slot-based image/content carousel. 轮播组件。                                                    |
+| [Comparison](display/comparison.md)           | `<aithe-comparison>`      | Before/after comparison slider. 前后对比滑块。                                                   |
+| [Animated Image](display/animated-image.md)   | `<aithe-animated-image>`  | Animated image with pan/zoom. 动画图片，支持平移/缩放。                                          |
+| [Markdown](display/markdown.md)               | `<aithe-markdown>`        | Lightweight markdown renderer. 轻量 Markdown 渲染器。                                            |
+| [Markdown Editor](display/markdown-editor.md) | `<aithe-markdown-editor>` | Markdown editor with live preview. Markdown 编辑器，带实时预览。                                 |
+| [Code Editor](display/code-editor.md)         | `<aithe-code-editor>`     | Syntax-highlighted code editor with toolbar. 语法高亮代码编辑器，带工具栏。                      |
+| [Label](display/label.md)                     | `<aithe-label>`           | Lightweight label component that renders a Markdown subset. 轻量级标签组件，渲染 Markdown 子集。 |
 
 ---
 
@@ -141,12 +161,12 @@ Rich content display and media components. 富内容展示和媒体组件。
 
 Progress indicators and loading placeholders. 进度指示器和加载占位组件。
 
-| Component | Tag | Description |
-|-----------|-----|-------------|
-| [Progress Bar](progress/progress-bar.md) | `<aithe-progress-bar>` | Linear progress bar. 线性进度条。 |
-| [Progress Ring](progress/progress-ring.md) | `<aithe-progress-ring>` | Circular progress indicator. 圆形进度指示器。 |
-| [Spinner](progress/spinner.md) | `<aithe-spinner>` | Generic loading spinner. 通用加载旋转器。 |
-| [Skeleton](progress/skeleton.md) | `<aithe-skeleton>` | Skeleton placeholder for content loading. 骨架屏占位组件。 |
+| Component                                  | Tag                     | Description                                                |
+| ------------------------------------------ | ----------------------- | ---------------------------------------------------------- |
+| [Progress Bar](progress/progress-bar.md)   | `<aithe-progress-bar>`  | Linear progress bar. 线性进度条。                          |
+| [Progress Ring](progress/progress-ring.md) | `<aithe-progress-ring>` | Circular progress indicator. 圆形进度指示器。              |
+| [Spinner](progress/spinner.md)             | `<aithe-spinner>`       | Generic loading spinner. 通用加载旋转器。                  |
+| [Skeleton](progress/skeleton.md)           | `<aithe-skeleton>`      | Skeleton placeholder for content loading. 骨架屏占位组件。 |
 
 ---
 
@@ -154,9 +174,27 @@ Progress indicators and loading placeholders. 进度指示器和加载占位组
 
 Specialized container components for content organization. 专用内容组织容器组件。
 
-| Component | Tag | Description |
-|-----------|-----|-------------|
-| [Callout](container/callout.md) | `<aithe-callout>` | Highlighted callout block. 高亮提示块。 |
-| [Details](container/details.md) | `<aithe-details>` | Themed disclosure widget. 主题化展开/收起组件。 |
-| [Scroller](container/scroller.md) | `<aithe-scroller>` | Themed scroll container. 主题化滚动容器。 |
+| Component                               | Tag                   | Description                                          |
+| --------------------------------------- | --------------------- | ---------------------------------------------------- |
+| [Callout](container/callout.md)         | `<aithe-callout>`     | Highlighted callout block. 高亮提示块。              |
+| [Details](container/details.md)         | `<aithe-details>`     | Themed disclosure widget. 主题化展开/收起组件。      |
+| [Scroller](container/scroller.md)       | `<aithe-scroller>`    | Themed scroll container. 主题化滚动容器。            |
 | [Split Panel](container/split-panel.md) | `<aithe-split-panel>` | Resizable two-panel layout. 可调整大小的双面板布局。 |
+
+---
+
+## Theme / 主题与外观组件
+
+Theme, shape, shadow, typo, and locale management components. The **Theme × Shape × Shadow × Typo** system is orthogonal — any color theme can be combined with any shape, shadow, and typo style independently.
+
+主题、形状、阴影、排版和语言管理组件。**Theme × Shape × Shadow × Typo** 体系正交设计——任意颜色主题可与任意形状、阴影和排版风格独立组合。
+
+| Component                               | Tag                     | Description                                                                                                                |
+| --------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| [Theme Switch](theme/theme-switch.md)   | `<aithe-theme-switch>`  | Unified appearance switch — theme, shadow, shape & typo in one dropdown. 统一外观切换器，整合主题、阴影、形状和排版。     |
+| [Theme Picker](theme/theme-picker.md)   | `<aithe-theme-picker>`  | Grouped theme selector with color dot previews. 分组主题选择器，带色点预览。                                               |
+| [Shape Picker](theme/shape-picker.md)   | `<aithe-shape-picker>`  | Shape style selector with preview thumbnails. 形状风格选择器，带预览缩略图。                                               |
+| [Shadow Picker](theme/shadow-picker.md) | `<aithe-shadow-picker>` | Shadow style selector with preview thumbnails. 阴影风格选择器，带预览缩略图。                                              |
+| [Typo Picker](theme/typo-picker.md)     | `<aithe-typo-picker>`   | Typography style selector with preview icons. 排版风格选择器，带预览图标。                                                 |
+| [Theme Preview](theme/theme-preview.md) | `<aithe-theme-preview>` | Live theme, shape, shadow & typo preview card with switch confirmation. 实时主题、形状、阴影与排版预览卡片，支持切换确认。 |
+| [Locale Switch](theme/locale-switch.md) | `<aithe-locale-switch>` | Locale switcher dropdown for i18n. 语言切换下拉菜单。                                                                      |

package/docs/api/theme/locale-switch.md

@@ -1,7 +1,7 @@
 # AitheLocaleSwitch / AitheLocaleSwitch 语言切换
 
-> Locale switcher dropdown for toggling between supported locales (English / 中文).
-> 语言切换下拉菜单，用于在支持的语言环境之间切换（English / 中文）。
+> Locale switcher dropdown for toggling between supported locales. Dynamically reflects all registered locales via `getAitheLocales()`, or a filtered subset via the `locales` property.
+> 语言切换下拉菜单，用于在支持的语言环境之间切换。通过 `getAitheLocales()` 动态反映所有已注册的语言环境，或通过 `locales` 属性限定显示子集。
 
 ## Slots / 插槽
 
@@ -11,16 +11,36 @@
 
 ## Properties / 属性
 
-| Name      | Type                                                       | Default      | Description (EN)                                   | Description (CN)             |
-| --------- | ---------------------------------------------------------- | ------------ | -------------------------------------------------- | ---------------------------- |
-| placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-end' | Dropdown panel placement. Auto-adapts to viewport. | 下拉面板位置。自动适应视口。 |
+| Name      | Type                                                       | Default      | Description (EN)                                                                                                                                | Description (CN)                                                                               |
+| --------- | ---------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-end' | Dropdown panel placement. Auto-adapts to viewport.                                                                                              | 下拉面板位置。自动适应视口。                                                                   |
+| locales   | `string` (JSON array)                                      | `''`         | JSON string of locale identifiers to show. When empty, all registered locales are displayed. Invalid/unregistered values are silently filtered. | 下拉菜单中显示的语言标识 JSON 字符串。为空时显示所有已注册语言。无效或未注册的值会被静默过滤。 |
+
+## Events / 事件
+
+| Name                | Detail               | Cancelable | Description (EN)                                                                                                                                                                              | Description (CN)                                                                                                   |
+| ------------------- | -------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| aithe-locale-change | `{ locale: string }` | Yes        | Emitted when a locale is selected. Built-in locale switch (`setAitheLocale`) runs by default. Call `preventDefault()` to suppress the built-in behavior and handle locale switching manually. | 选择语言时发出。默认执行内置切换逻辑（`setAitheLocale`）。调用 `preventDefault()` 可阻止内置切换，由外部自行处理。 |
 
 ## Supported Locales / 支持的语言
 
-| Locale | Label   | Description (EN)  | Description (CN) |
-| ------ | ------- | ----------------- | ---------------- |
-| en-US  | English | English language. | 英语。           |
-| zh-CN  | 中文    | Chinese language. | 中文。           |
+The locale list is dynamically generated from all registered locales via `getAitheLocales()`. Built-in locales are shown with localized labels; custom locales display their locale identifier directly.
+
+语言列表通过 `getAitheLocales()` 从所有已注册的语言环境动态生成。内置语言环境显示本地化标签；自定义语言环境直接显示其语言标识。
+
+| Locale   | Label               | Description (EN)                                     | Description (CN)                                  |
+| -------- | ------------------- | ---------------------------------------------------- | ------------------------------------------------- |
+| en-US    | English             | Built-in English locale.                             | 内置英语语言环境。                                |
+| zh-CN    | 中文                | Built-in Simplified Chinese locale.                  | 内置简体中文语言环境。                            |
+| zh-TW    | 繁體中文            | Built-in Traditional Chinese (Taiwan) locale.        | 内置繁體中文（台灣）語言環境。                    |
+| zh-HK    | 繁體中文            | Built-in Traditional Chinese (Hong Kong) locale.     | 内置繁體中文（香港）語言環境。                    |
+| ja-JP    | 日本語              | Built-in Japanese locale.                            | 内置日本語言環境。                                |
+| ko-KR    | 한국어              | Built-in Korean locale.                              | 内置韓國語言環境。                                |
+| es-ES    | Español             | Built-in Spanish locale.                             | 内置西班牙語言環境。                              |
+| pt-BR    | Português           | Built-in Brazilian Portuguese locale.                | 内置巴西葡萄牙語言環境。                          |
+| fr-FR    | Français            | Built-in French locale.                              | 内置法語言環境。                                  |
+| de-DE    | Deutsch             | Built-in German locale.                              | 内置德語言環境。                                  |
+| (custom) | (locale identifier) | Custom locales registered via `registerAitheLocale`. | 通过 `registerAitheLocale` 注册的自定义语言环境。 |
 
 ## Related i18n API / 相关国际化 API
 
@@ -33,17 +53,51 @@ The locale switch component works with the Aithe UI i18n system. The following f
 | setAitheLocale            | `(locale: AitheLocale, persist?: boolean) => void`                                   | Switch the active locale and notify all listeners. Optionally persist to localStorage.               | 切换当前语言环境并通知所有监听器。可选持久化到 localStorage。 |
 | getAitheLocale            | `() => AitheLocale`                                                                  | Return the currently active locale.                                                                  | 返回当前活动的语言环境。                                      |
 | initAitheLocale           | `(defaultLocale?: AitheLocale) => void`                                              | Initialize locale from stored preference or the given default.                                       | 从存储的偏好或给定的默认值初始化语言环境。                    |
-| registerAitheLocale       | `(locale: AitheLocale, translations: Record<string, AitheTranslationValue>) => void` | Register a new locale with its full translation map.                                                 | 注册新的语言环境及其完整翻译映射。                            |
-| registerAitheTranslations | `(locale: AitheLocale, translations: Record<string, AitheTranslationValue>) => void` | Merge additional translations into an existing locale registry. Use this for app-level i18n keys.    | 将额外翻译合并到现有语言注册表中。用于应用级国际化键。        |
+| registerAitheLocale       | `(locale: AitheLocale, translations: Record<string, string>) => void` | Register a new locale with its full translation map.                                                 | 注册新的语言环境及其完整翻译映射。                            |
+| registerAitheTranslations | `(locale: AitheLocale, translations: Record<string, string>) => void` | Merge additional translations into an existing locale registry. Use this for app-level i18n keys.    | 将额外翻译合并到现有语言注册表中。用于应用级国际化键。        |
 | t                         | `(key: string, ...args: unknown[]) => string`                                        | Translate a key using the current locale, falling back to English. Supports interpolation functions. | 使用当前语言环境翻译键，回退到英语。支持插值函数。            |
 | onAitheLocaleChange       | `(fn: () => void) => () => void`                                                     | Subscribe to locale changes. Returns an unsubscribe function.                                        | 订阅语言环境变更。返回取消订阅函数。                          |
 
 ## Examples / 示例
 
+### Default usage (all locales) / 默认用法（显示所有语言）
+
 ```html
 <aithe-locale-switch placement="bottom-end"></aithe-locale-switch>
 ```
 
+No event listener is required — the component calls `setAitheLocale()` internally by default. All registered locales appear in the dropdown.
+
+无需监听事件 — 组件默认在内部调用 `setAitheLocale()`。下拉菜单显示所有已注册语言。
+
+### Limiting visible locales / 限定显示语言
+
+Use the `locales` property to show only a subset of registered locales. This is useful when an application only supports a few languages but the library has many registered.
+
+使用 `locales` 属性可仅显示已注册语言中的子集。当应用仅支持少数语言但库中注册了多种语言时非常有用。
+
+```html
+<!-- Show only English, Chinese, and Japanese -->
+<!-- 仅显示英语、中文和日语 -->
+<aithe-locale-switch locales='["en-US","zh-CN","ja-JP"]'></aithe-locale-switch>
+```
+
+```ts
+// Programmatic usage / 编程式用法
+const switcher = document.querySelector('aithe-locale-switch');
+switcher.locales = JSON.stringify(['en-US', 'zh-CN', 'ko-KR']);
+```
+
+### Custom locale handling (prevent default) / 自定义语言处理（阻止默认行为）
+
+```js
+const switcher = document.querySelector('aithe-locale-switch');
+switcher.addEventListener('aithe-locale-change', (e) => {
+  e.preventDefault();
+  console.log('Locale selected:', e.detail.locale);
+});
+```
+
 ### Programmatic locale switching / 编程式语言切换
 
 ```ts

package/docs/api/theme/shadow-picker.md

@@ -0,0 +1,103 @@
+# AitheShadowPicker / AitheShadowPicker 阴影选择器
+
+> Shadow style picker dropdown with preview icons, keyboard navigation, and built-in shadow switch.
+> 阴影风格选择器，支持预览图标、键盘导航和内置阴影切换。
+>
+> **Note:** For most use cases, consider using the unified [`<aithe-theme-switch>`](theme-switch.md) component instead, which integrates theme, shadow, shape, and typo selection in a single dropdown.
+> **注意：** 大多数场景建议使用统一的 [`<aithe-theme-switch>`](theme-switch.md) 组件，它在单个下拉菜单中整合了主题、阴影、形状和排版选择。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                | Description (CN)                |
+| --------- | ----------------------------------------------- | ------------------------------- |
+| (default) | No slots — the trigger is rendered internally. | 无插槽 — 触发器由组件内部渲染。 |
+
+## Properties / 属性
+
+| Name      | Type                                                       | Default      | Description (EN)                                                                                                                  | Description (CN)                                                                 |
+| --------- | ---------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| value     | `AitheShadowName`                                          | —            | Controlled shadow selection. When set, the picker displays this value instead of the global shadow. Used by `aithe-theme-preview`. | 受控阴影选择。设置后，选择器显示此值而非全局阴影。由 `aithe-theme-preview` 使用。 |
+| placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-end' | Dropdown panel placement. Auto-adapts to viewport.                                                                                | 下拉面板位置。自动适应视口。                                                    |
+
+## Events / 事件
+
+| Name                 | Detail               | Cancelable | Description (EN)                                                                                                                                                                                 | Description (CN)                                                                                                          |
+| -------------------- | -------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| aithe-shadow-change  | `{ shadow: string }` | Yes        | Emitted when a shadow is selected. Built-in shadow switch (`aitheUI.setShadow()`) runs by default. Call `preventDefault()` to suppress the built-in behavior and handle shadow switching manually. | 阴影风格选中时发出。默认执行内置切换逻辑（`aitheUI.setShadow()`）。调用 `preventDefault()` 可阻止内置切换，由外部自行处理。 |
+
+## Built-in Shadows / 内置阴影风格
+
+| Shadow         | Description (EN)                                   | Description (CN)                     |
+| -------------- | -------------------------------------------------- | ------------------------------------ |
+| flat           | No shadow, flat design                             | 无阴影，扁平化设计                    |
+| neumorphism    | Soft inner/outer shadows, tactile feel             | 柔和内外阴影，触感效果                |
+| skeuomorphic   | Realistic shadows, 3D embossed/debossed            | 写实阴影，3D 凹凸效果                 |
+| glassmorphism  | Semi-transparent with blur backdrop                | 半透明背景模糊效果                    |
+| cyber          | Neon glow with sharp edges, futuristic             | 霓虹光晕配锐利边缘，科技感             |
+| deep           | Deep layered shadows, strong depth                  | 深层叠加阴影，强纵深感                |
+| diffuse        | Soft diffused shadows, subtle glow                 | 柔和弥散阴影，微妙光晕                |
+| sharp-business | Precise shadows, corporate professional            | 精准阴影，企业专业风格                |
+| retro          | Vintage-style drop shadows                          | 复古风格投影                          |
+
+## CSS Variables / CSS 变量
+
+Shadow styles control the following CSS custom properties on `:root`:
+
+| Variable      | Description (EN)                   | Description (CN) |
+| ------------- | ---------------------------------- | ---------------- |
+| `--aithe-shadow-1` | Level 1 shadow for subtle elevation  | 一级阴影，微弱抬升   |
+| `--aithe-shadow-2` | Level 2 shadow for card elevation   | 二级阴影，卡片抬升   |
+| `--aithe-shadow-3` | Level 3 shadow for dropdown/popover | 三级阴影，下拉/气泡  |
+| `--aithe-shadow-4` | Level 4 shadow for modal/dialog    | 四级阴影，弹窗/对话框 |
+| `--aithe-shadow-5` | Level 5 shadow for navigation       | 五级阴影，导航层级   |
+
+> **Note:** Each shadow style defines unique values for all 5 shadow levels, creating distinct visual hierarchies.
+> **注意：** 每种阴影风格为 5 个阴影级别定义独特的值，形成不同的视觉层级。
+
+## Examples / 示例
+
+### Default usage (built-in shadow switch) / 默认用法（内置切换）
+
+```html
+<aithe-shadow-picker placement="bottom-end"></aithe-shadow-picker>
+```
+
+No event listener is required — the component calls `aitheUI.setShadow()` internally by default.
+
+无需监听事件 — 组件默认在内部调用 `aitheUI.setShadow()`。
+
+### Custom shadow handling (prevent default) / 自定义阴影处理（阻止默认行为）
+
+```js
+const picker = document.querySelector('aithe-shadow-picker');
+picker.addEventListener('aithe-shadow-change', (e) => {
+  e.preventDefault();
+  console.log('Shadow selected:', e.detail.shadow);
+});
+```
+
+### Programmatic API / 编程式 API
+
+```js
+import { aitheUI } from '@aithe/aithe-ui';
+
+aitheUI.setShadow('cyber');
+console.log(aitheUI.getShadow()); // 'cyber'
+
+const unsubscribe = aitheUI.onShadowChange(() => {
+  console.log('Shadow changed to:', aitheUI.getShadow());
+});
+```
+
+### Shadow × Theme × Shape / 阴影 × 主题 × 形状
+
+Shadow styles are orthogonal to color themes and shapes and can be freely combined:
+
+阴影风格与颜色主题、形状相互独立，可自由组合：
+
+```html
+<!-- Dark theme + rounded shape + cyber shadow -->
+<aithe-theme-picker value="dark"></aithe-theme-picker>
+<aithe-shape-picker value="rounded"></aithe-shape-picker>
+<aithe-shadow-picker value="cyber"></aithe-shadow-picker>
+```