@aithe/aithe-ui 26.2.2

package/docs/api/navigation/steps.md

@@ -0,0 +1,32 @@
+# AitheSteps / AitheSteps 步骤条
+
+> Stepper component with JSON-driven items for process flow visualization.
+> 步骤条组件，支持 JSON 驱动的步骤项，用于流程可视化。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| — | — | No slots (items are driven by the `items` property). | 无插槽（步骤项由 `items` 属性驱动）。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| current | `number` | `0` | Current active step index (0-based). | 当前活动步骤索引（从 0 开始）。 |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | Step size preset. | 步骤尺寸预设。 |
+| direction | `'horizontal' \| 'vertical'` | `'horizontal'` | Steps layout direction. | 步骤布局方向。 |
+| items | `string` | `'[]'` | JSON string or comma-separated list of step items. | 步骤项的 JSON 字符串或逗号分隔列表。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-steps current="1" direction="horizontal" items='["Step 1","Step 2","Step 3"]'></aithe-steps>
+<aithe-steps current="2" items='[{"title":"Account","description":"Create account"},{"title":"Profile","description":"Fill info"}]'></aithe-steps>
+```

package/docs/api/navigation/sub-menu.md

@@ -0,0 +1,38 @@
+# AitheSubMenu / AitheSubMenu 子菜单
+
+> Nested branch (sub-menu) item for `aithe-menu` with expandable children.
+> aithe-menu 的嵌套分支（子菜单）项，支持展开子项。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for nested `aithe-menu-item` elements. | 嵌套的 aithe-menu-item 元素。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| name | `string` | `''` | Unique key identifying this sub-menu. | 子菜单唯一标识键。 |
+| title | `string` | `''` | Display title for the sub-menu trigger. | 子菜单触发器的显示标题。 |
+| icon | `string` | `''` | Icon name to display before the title. Uses built-in `aithe-icon` names. | 在标题前显示的图标名称，使用 aithe-icon 内置图标名。 |
+| disabled | `boolean` | `false` | Whether the sub-menu is disabled. | 是否禁用子菜单。 |
+| open | `boolean` | `false` | Whether the sub-menu is currently expanded. | 是否当前展开。 |
+| active | `boolean` | `false` | Whether any child item is currently active. | 是否有子项当前选中。 |
+| menuMode | `'horizontal' \| 'vertical'` | `'vertical'` | Inherited menu mode from parent `aithe-menu`. | 从父级 aithe-menu 继承的菜单模式。 |
+| collapsed | `boolean` | `false` | Inherited collapsed state from parent `aithe-menu`. | 从父级 aithe-menu 继承的折叠状态。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events (toggle is handled internally). | 无自定义事件（切换由内部处理）。 |
+
+## Examples / 示例
+
+```html
+<aithe-sub-menu title="Settings" name="settings" icon="settings">
+  <aithe-menu-item name="profile">Profile</aithe-menu-item>
+  <aithe-menu-item name="security">Security</aithe-menu-item>
+</aithe-sub-menu>
+```

package/docs/api/progress/progress-bar.md

@@ -0,0 +1,30 @@
+# AitheProgressBar / Aithe进度条
+
+> Linear progress bar with status colors and optional percentage label.
+> 线性进度条，支持状态颜色和可选百分比标签。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| — | — | No slots. | 无插槽。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| percent | `number` | `0` | Current progress percentage (0–100). | 当前进度百分比（0–100）。 |
+| status | `'default' | 'success' | 'warning' | 'danger'` | `'default'` | Status color variant. | 状态颜色类型。 |
+| show-info | `boolean` | `true` | Whether to display the percentage text. | 是否显示百分比文本。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-progress-bar percent="75" status="success" show-info></aithe-progress-bar>
+```

package/docs/api/progress/progress-ring.md

@@ -0,0 +1,31 @@
+# AitheProgressRing / Aithe进度环
+
+> Circular progress ring indicator with status colors and percentage label.
+> 圆形进度环指示器，支持状态颜色和百分比标签。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| — | — | No slots. | 无插槽。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| percent | `number` | `0` | Current progress percentage (0–100). | 当前进度百分比（0–100）。 |
+| size | `string` | `'120'` | Diameter of the ring in pixels. | 环的直径（像素）。 |
+| stroke-width | `number` | `10` | Stroke width of the ring in pixels. | 环的描边宽度（像素）。 |
+| status | `'default' | 'success' | 'warning' | 'danger'` | `'default'` | Status color variant. | 状态颜色类型。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-progress-ring percent="60" size="160" stroke-width="12" status="warning"></aithe-progress-ring>
+```

package/docs/api/progress/skeleton.md

@@ -0,0 +1,34 @@
+# AitheSkeleton / Aithe骨架屏
+
+> Skeleton placeholder for content loading states with line, circle, and rect shapes.
+> 骨架屏占位组件，用于内容加载状态，支持线条、圆形和矩形形状。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot shown when `active` is false. | `active` 为 false 时显示的默认插槽。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| rows | `number` | `3` | Number of placeholder rows. | 占位行数。 |
+| animated | `boolean` | `true` | Whether rows have a shimmer animation. | 行是否具有闪烁动画。 |
+| shape | `'line' | 'circle' | 'rect'` | `'line'` | Shape of each placeholder row. | 每行占位的形状。 |
+| active | `boolean` | `true` | Whether the skeleton is active (true = show placeholder, false = show slot content). | 骨架屏是否激活（true = 显示占位，false = 显示插槽内容）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-skeleton rows="4" shape="line" animated active></aithe-skeleton>
+<aithe-skeleton shape="circle" :active="loading">
+  <aithe-avatar src="user.jpg"></aithe-avatar>
+</aithe-skeleton>
+```

package/docs/api/progress/spinner.md

@@ -0,0 +1,30 @@
+# AitheSpinner / Aithe旋转器
+
+> Generic loading spinner with ring and dots variants.
+> 通用加载旋转器，支持环形和圆点两种变体。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| — | — | No slots. | 无插槽。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| size | `'sm' | 'md' | 'lg'` | `'md'` | Size scale of the spinner. | 旋转器的尺寸规格。 |
+| color | `string` | `'var(--aithe-primary-6)'` | Custom color for the spinner (CSS value). | 旋转器的自定义颜色（CSS 值）。 |
+| variant | `'ring' | 'dots'` | `'ring'` | Visual variant of the spinner. | 旋转器的视觉变体。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-spinner size="lg" variant="dots" color="var(--aithe-danger-6)"></aithe-spinner>
+```

package/docs/api/summary.md

@@ -0,0 +1,162 @@
+# 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 是 Archest 团队基于 Lit 3.x 开发的 Web Components UI 库，为现代 Web 应用提供一套完整的可复用 UI 基础组件。
+
+---
+
+## Basic / 基础组件
+
+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. 紧凑可选中芯片，支持关闭按钮。 |
+
+---
+
+## Layout / 布局组件
+
+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. 固定/吸顶包装器。 |
+
+---
+
+## Navigation / 导航组件
+
+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. 回到顶部浮动按钮。 |
+
+---
+
+## Form / 表单组件
+
+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. 双栏穿梭选择器。 |
+
+---
+
+## Feedback / 反馈组件
+
+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. 加载旋转浮层。 |
+
+---
+
+## Data / 数据展示组件
+
+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. 大数据集分页导航。 |
+
+---
+
+## Display / 展示组件
+
+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 渲染器。 |
+
+---
+
+## Progress / 进度组件
+
+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. 骨架屏占位组件。 |
+
+---
+
+## Container / 容器组件
+
+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. 主题化滚动容器。 |
+| [Split Panel](container/split-panel.md) | `<aithe-split-panel>` | Resizable two-panel layout. 可调整大小的双面板布局。 |

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

@@ -0,0 +1,98 @@
+# AitheLocaleSwitch / AitheLocaleSwitch 语言切换
+
+> Locale switcher dropdown for toggling between supported locales (English / 中文).
+> 语言切换下拉菜单，用于在支持的语言环境之间切换（English / 中文）。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                               | Description (CN)                |
+| --------- | ---------------------------------------------- | ------------------------------- |
+| (default) | No slots — the trigger is rendered internally. | 无插槽 — 触发器由组件内部渲染。 |
+
+## 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. | 下拉面板位置。自动适应视口。 |
+
+## Supported Locales / 支持的语言
+
+| Locale | Label   | Description (EN)  | Description (CN) |
+| ------ | ------- | ----------------- | ---------------- |
+| en-US  | English | English language. | 英语。           |
+| zh-CN  | 中文    | Chinese language. | 中文。           |
+
+## Related i18n API / 相关国际化 API
+
+The locale switch component works with the Aithe UI i18n system. The following functions are exported from `@aithe-ui/core/i18n`:
+
+语言切换组件与 Aithe UI 国际化系统配合使用。以下函数从 `@aithe-ui/core/i18n` 导出：
+
+| Function                  | Signature                                                                            | Description (EN)                                                                                     | Description (CN)                                              |
+| ------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| 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.    | 将额外翻译合并到现有语言注册表中。用于应用级国际化键。        |
+| 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 / 示例
+
+```html
+<aithe-locale-switch placement="bottom-end"></aithe-locale-switch>
+```
+
+### Programmatic locale switching / 编程式语言切换
+
+```ts
+import { setAitheLocale, getAitheLocale, t, onAitheLocaleChange } from 'aithe-ui';
+
+// Switch locale / 切换语言
+setAitheLocale('zh-CN');
+
+// Get current locale / 获取当前语言
+console.log(getAitheLocale()); // 'zh-CN'
+
+// Translate a key / 翻译键
+console.log(t('basic.empty.defaultText')); // '暂无数据'
+
+// Listen for changes / 监听变更
+const unsubscribe = onAitheLocaleChange(() => {
+  console.log('Locale changed to:', getAitheLocale());
+});
+// Later: unsubscribe(); / 之后：取消订阅();
+```
+
+### Registering a custom locale / 注册自定义语言
+
+```ts
+import { registerAitheLocale, setAitheLocale } from 'aithe-ui';
+
+registerAitheLocale('ja-JP', {
+  'basic.empty.defaultText': 'データなし',
+  'form.dialog.confirmText': '確認',
+  'form.dialog.cancelText': 'キャンセル',
+  // ... more keys
+});
+
+setAitheLocale('ja-JP');
+```
+
+### Registering app-level translations / 注册应用级翻译
+
+```ts
+import { registerAitheTranslations } from 'aithe-ui';
+
+// Merge app-specific keys into existing locale registries
+registerAitheTranslations('en-US', {
+  'app.dashboard.title': 'Dashboard',
+  'app.settings.save': 'Save Settings',
+});
+
+registerAitheTranslations('zh-CN', {
+  'app.dashboard.title': '仪表盘',
+  'app.settings.save': '保存设置',
+});
+```

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

@@ -0,0 +1,37 @@
+# AitheThemePicker / AitheThemePicker 主题选择器
+
+> Theme picker with grouped light/dark themes, color dot previews, and keyboard navigation.
+> 主题选择器，支持亮色/暗色分组、色点预览和键盘导航。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | No slots — the trigger is rendered internally. | 无插槽 — 触发器由组件内部渲染。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| value | `AitheBuiltinTheme \| string` | `'light'` | Currently active theme identifier. | 当前激活的主题标识。 |
+| placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-end' | Dropdown panel placement. Auto-adapts to viewport. | 下拉面板位置。自动适应视口。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-theme-change | { theme } | Emitted when a theme is selected. | 主题选中时触发。 |
+
+## Built-in Themes / 内置主题
+
+| Group | Themes |
+|-------|--------|
+| Light | light, gray, blue, festive, orange, purple, pink, teal, indigo, cyan, amber |
+| Dark | dark, slate, charcoal, midnight, obsidian, graphite, ink, onyx, ebony, navy, raisin |
+
+## Examples / 示例
+
+```html
+<aithe-theme-picker value="light" @aithe-theme-change=${(e) => console.log(e.detail.theme)}>
+</aithe-theme-picker>
+```

package/docs/api/theme/theme-preview.md

@@ -0,0 +1,29 @@
+# AitheThemePreview / AitheThemePreview 主题预览
+
+> Theme preview panel with a toolbar (theme picker + apply button) and a live preview area containing sidebar navigation and component showcase. The preview area switches theme locally; clicking "Apply Theme" propagates the choice to the page.
+> 主题预览面板，包含工具栏（主题选择器 + 应用按钮）和实时预览区（侧边导航 + 组件展示）。预览区局部切换主题，点击"Apply Theme"将选择应用到页面。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | No slots — content is rendered internally. | 无插槽 — 内容由组件内部渲染。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| value | `AitheBuiltinTheme \| string` | `'light'` | Currently applied theme identifier. | 当前应用的主题标识。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-theme-apply | { theme } | Emitted when the "Apply Theme" button is clicked, carrying the selected theme name. | 点击"Apply Theme"按钮时触发，携带选中的主题名称。 |
+
+## Examples / 示例
+
+```html
+<aithe-theme-preview value="light" @aithe-theme-apply=${(e) => setAitheTheme(e.detail.theme)}>
+</aithe-theme-preview>
+```

package/docs/changelog/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Aithe UI 变更日志
+
+版本格式: 年.季度.小版本 (如 26.2.2)
+
+---
+
+## 26.2.2 (2026-05-09)
+
+### 2026年第2季度第2个月版本 - 基线版本
+
+- **初始版本发布**: 完整的 Web Components 组件库
+- **组件数量**: 78 个可复用的 UI 组件
+- **主题系统**: 22 套内置主题（11 Light + 11 Dark），支持全局和局部切换
+- **技术架构**: 基于 Lit 3.x 的现代 Web Components 实现
+- **类型支持**: 完整的 TypeScript 类型定义
+- **框架兼容**: 支持 React、Vue、Angular、Svelte 及原生 JavaScript
+
+### 组件分类
+
+| 分类              | 数量 | 组件                                                                                                                                                            |
+| ----------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 基础 (basic)      | 12   | button, button-group, icon, input, textarea, card, tag, badge, avatar, divider, empty, chip                                                                     |
+| 布局 (layout)     | 10   | container, row, col, flex, space, page-container, page, collapse, collapse-item, affix                                                                          |
+| 导航 (navigation) | 8    | menu, menu-item, sub-menu, breadcrumb, breadcrumb-item, steps, back-top, dropdown                                                                               |
+| 表单 (form)       | 16   | checkbox, checkbox-group, radio, radio-group, select, switch, color-picker, combobox, date-picker, time-picker, slider, rate, form, form-item, upload, transfer |
+| 反馈 (feedback)   | 9    | dialog, modal, drawer, tooltip, popover, toast, alert, notification, loading                                                                                    |
+| 数据展示 (data)   | 9    | table, table-column, tabs, tab-pane, tree, tree-menu, timeline, timeline-item, pagination                                                                       |
+| 展示 (display)    | 4    | carousel, comparison, animated-image, markdown                                                                                                                  |
+| 进度 (progress)   | 4    | progress-bar, progress-ring, spinner, skeleton                                                                                                                  |
+| 容器 (container)  | 4    | callout, details, scroller, split-panel                                                                                                                         |
+| 主题 (theme)      | 3    | theme-picker, theme-preview, locale-switch                                                                                                                      |
+
+### 主题列表
+
+**Light 系 (11)**: light, blue, festive, orange, purple, pink, teal, indigo, cyan, amber, gray
+
+**Dark 系 (11)**: dark, slate, charcoal, midnight, obsidian, graphite, ink, onyx, ebony, navy, raisin
+
+### 核心特性摘要
+
+- **跨框架兼容**: Web Components 标准，框架无关
+- **样式隔离**: Shadow DOM 确保组件样式不冲突
+- **多主题系统**: 22 套预设主题（11 Light + 11 Dark），支持全局和局部切换
+- **无障碍访问**: ARIA 语义、键盘导航、焦点管理
+- **企业级功能**: 表单验证、数据表格、布局系统
+- **自定义事件**: `aithe-*` 前缀的统一事件系统
+
+---
+
+## 版本规划策略
+
+### 版本格式
+
+- `年.季度.小版本` (如 26.2.2)
+- **年**: 发布年份 (如 2026)
+- **季度**: 季度编号 (1-4)
+- **小版本**: 月度小版本号 (1-3)
+
+### 发布周期
+
+- **季度版本**: 每季度发布一个主要版本
+- **月度版本**: 每月发布一个小版本
+- **紧急修复**: 按需发布修复版本
+
+### 版本兼容性
+
+- 季度版本间可能有 API 变更
+- 月度版本保持 API 兼容性
+- 重大变更提供迁移指南
+
+---