@aithe/aithe-ui 26.2.2

package/docs/issue/issue_26.2.2.2.md

@@ -0,0 +1,53 @@
+# Issue 26.2.2.2
+
+## 版本信息
+
+- **版本号**: 26.2.2.2
+- **基线版本**: 26.2.2
+- **类型**: Feature
+- **日期**: 2026-05-11
+
+## 变更概述
+
+1. 新增 `aithe-theme-picker` 主题选择器组件，替代原有 `aithe-dropdown` 主题切换方案
+2. 新增 `aithe-theme-preview` 主题预览组件，支持局部预览 + 确认应用全局主题
+3. 内置主题从 4 个扩展至 22 个（Light 系 11 个 + Dark 系 11 个）
+4. `aithe-dropdown` 从 feedback 分类迁移至 navigation 分类
+5. Blue 主题从 Dark 系调整为 Light 系
+
+## 破坏性变更
+
+| 变更项 | 旧值 | 新值 |
+|--------|------|------|
+| `AitheBuiltinTheme` 类型 | `'light' \| 'dark' \| 'gray' \| 'blue'` | `'light' \| 'dark' \| 'gray' \| 'blue' \| 'festive' \| 'orange' \| 'purple' \| 'pink' \| 'teal' \| 'indigo' \| 'cyan' \| 'amber' \| 'slate' \| 'charcoal' \| 'midnight' \| 'obsidian' \| 'graphite' \| 'ink' \| 'onyx' \| 'ebony' \| 'navy' \| 'raisin'` |
+| `aithe-dropdown` 组件路径 | `src/components/feedback/dropdown.ts` | `src/components/navigation/dropdown.ts` |
+| `aithe-dropdown` 文档路径 | `docs/api/feedback/dropdown.md` | `docs/api/navigation/dropdown.md` |
+| `aithe-dropdown` 导出路径 | `./components/feedback/dropdown` | `./components/navigation/dropdown` |
+| Blue 主题 `color-scheme` | `dark` | `light` |
+| Blue 主题背景色 | `#09111f`（深蓝） | `#f0f5ff`（浅蓝） |
+| API 文档 Dropdown 分类 | feedback（key: `fb-dropdown`） | navigation（key: `nav-dropdown`） |
+
+## 变更内容
+
+### 新增
+
+- **AitheThemePicker 组件** — 主题选择器，支持 Light/Dark 分组展示、色点预览、键盘导航，通过 `aithe-theme-change` 事件通知主题变更。属性：`value`（当前主题）、`placement`（下拉位置）
+- **AitheThemePreview 组件** — 主题预览面板，包含工具栏（theme-picker + Apply Theme 按钮）和预览区（侧边导航 + 组件展示区，含 Button、Input、Tag、Table）。预览区通过 Shadow DOM 内注入主题样式表实现局部主题切换，点击 Apply Theme 按钮调用 `setAitheTheme()` 应用全局主题，同时发出 `aithe-theme-apply` 事件
+- **18 个新内置主题** — Light 系：festive、orange、purple、pink、teal、indigo、cyan、amber；Dark 系：slate、charcoal、midnight、obsidian、graphite、ink、onyx、ebony、navy、raisin。每个主题包含完整的 primary/success/warning/danger/neutral 色阶及语义颜色变量
+- **Theme API 文档分类** — `docs.ts` 中新增 Theme 分类，包含 theme-picker 和 theme-preview 两个条目
+- **Theme Demo 页面** — `apps/demo/pages/theme.ts`，包含 Theme Picker、Theme Picker With Change Handler、Theme Picker Placement、Theme Preview 四个示例
+- **Dropdown Demo 示例** — 在 navigation Demo 页面新增 Dropdown 示例（含 click 和 hover 两种触发方式）
+
+### 修改
+
+- **API/Demo 应用主题切换方式** — 将原有 `aithe-dropdown` + 自定义主题列表方案替换为 `aithe-theme-picker` 组件，移除硬编码的 `themes` 数组、`themeColors` 映射、`.action-btn` / `.dot` 样式，改用 `aithe-theme-change` 事件监听
+- **Dropdown 组件分类迁移** — `aithe-dropdown` 从 feedback 分类迁移至 navigation 分类，源码路径、文档路径、导出路径、API 文档条目（`fb-dropdown` → `nav-dropdown`）同步更新
+- **Dropdown 文档更新** — `placement` 属性描述增加"自动适应视口"，新增 `offset` 属性（锚点与下拉面板间距，默认 8px）
+- **Feedback Demo 页面** — 移除 Dropdown 示例，标题从"Tooltip Popover And Dropdown"改为"Tooltip And Popover"
+- **Blue 主题调整为 Light 系** — `color-scheme` 从 `dark` 改为 `light`，背景色从深蓝 `#09111f` 改为浅蓝 `#f0f5ff`，surface 从深色半透明改为白色半透明，文字色从浅色改为深色，neutral 色阶整体调亮，边框和文字色适配浅色背景
+- **`AitheBuiltinTheme` 类型扩展** — 从 4 个主题名扩展至 22 个，覆盖所有新增内置主题
+- **`aitheThemeText` 拼接** — `src/styles/theme.ts` 中引入并拼接全部 22 个主题的 CSS 变量定义
+
+### 删除
+
+- **API/Demo 应用中的旧主题切换代码** — 移除 `apps/api/app.ts` 和 `apps/demo/app.ts` 中的 `themes` 常量、`themeColors` 映射、`themeItems` 构建逻辑、`.action-btn` / `.action-btn .dot` 样式，以及 `aithe-dropdown` 主题切换模板

package/docs/issue/issue_26.2.2.3.md

@@ -0,0 +1,86 @@
+# Issue 26.2.2.3
+
+## 版本信息
+
+- **版本号**: 26.2.2.3
+- **基线版本**: 26.2.2
+- **类型**: Quality / Bug Fix
+- **日期**: 2026-05-11
+
+## 变更概述
+
+1. 新增 ESLint + Prettier 代码质量工具链，配置 SonarJS 规则集
+2. 修复所有 ESLint errors 和 warnings（嵌套三元表达式、未使用导入、慢正则、嵌套模板字面量）
+3. 为所有箭头函数类属性添加 `readonly` 修饰符（SonarQube S2933）
+4. 修复 Badge 组件角标无法显示、定位偏移、value=0 行为错误等 Bug
+5. 修正 Badge 示例代码属性名错误（`count` → `value`）
+6. 全量 Prettier 格式化
+
+## 破坏性变更
+
+无。
+
+## 变更内容
+
+### 新增
+
+- **ESLint 工具链** — 集成 `eslint`、`typescript-eslint`、`eslint-plugin-lit`、`eslint-plugin-wc`、`eslint-plugin-sonarjs`、`eslint-config-prettier`，使用 flat config 格式（`eslint.config.js`）
+- **Prettier 工具链** — 添加 `.prettierrc` 和 `.prettierignore` 配置
+- **npm 脚本** — `lint`、`lint:fix`、`format`、`format:fix` 四个新脚本
+- **TSDoc 注释** — 为 `theme-picker.ts` 和 `theme-preview.ts` 补充标准双语 TSDoc 注释
+
+### 修改
+
+#### Bug 修复
+
+- **aithe-badge 角标无法显示** — Demo 和 API 应用中示例代码使用了不存在的 `count` 属性，修正为 `value`（影响文件：`apps/demo/pages/basic.ts`、`apps/api/demo-data.ts`）
+- **aithe-badge 角标定位偏移** — `.anchor` 缺少 `position: relative`，导致 `.badge`（`position: absolute`）的定位参考为 `:host` 而非 `.anchor`，角标未紧贴锚点元素
+- **aithe-badge value="0" 行为** — `value="0"` 时角标显示数字 "0"，与主流 UI 库行为不一致（Ant Design / Element Plus 在 count=0 时不显示角标），增加 `parsed === 0` 时返回空字符串的逻辑
+- **aithe-badge 示例代码** — 组件 `@example` 和 `docs/api/basic/badge.md` 中示例使用 `<aithe-avatar>` 和多余的 `max-count="99"`，修正为 `<aithe-button>` 并移除默认值属性
+
+#### ESLint 修复（sonarjs/no-nested-conditional）
+
+将嵌套三元表达式提取为独立变量或方法，消除所有 9 处 warnings：
+
+| 组件                | 修复方式                                                                              |
+| ------------------- | ------------------------------------------------------------------------------------- |
+| `button.ts`         | 提取 `prefixSlot` 变量                                                                |
+| `card.ts`           | 提取 `titleIcon` 变量                                                                 |
+| `divider.ts`        | 提取 `dashedClass`、`contentSlot`、`trailingLine` 变量                                |
+| `input.ts`          | 提取 `clearTabindex` 变量，添加 `nothing` 导入                                        |
+| `callout.ts`        | 提取 `titleIcon` 变量                                                                 |
+| `table.ts`          | 提取 `getSortIcon()`、`renderColumnHeader()` 方法，`selectAllTh` 变量                 |
+| `tree.ts`           | 提取 `toggleSymbol`、`nodeIcon`、`toggleBtn`、`checkbox`、`headerIcon`、`header` 变量 |
+| `animated-image.ts` | 提取 `duration`、`iterationCount`、`playState` 变量，改用 if/else 结构                |
+| `alert.ts`          | 提取 `titleIcon`、`titleBlock`、`closeBtn` 变量，改用 if/else 结构                    |
+| `drawer.ts`         | 提取 `drawerIcon` 变量                                                                |
+| `loading.ts`        | 提取 `tipContent` 变量                                                                |
+| `modal.ts`          | 提取 `modalIcon` 变量                                                                 |
+| `notification.ts`   | 提取 `notifIcon` 变量，改用 if/else 结构                                              |
+| `toast.ts`          | 提取 `toastIcon` 变量                                                                 |
+| `tooltip.ts`        | 提取 `tooltipIcon` 变量                                                               |
+| `combobox.ts`       | 提取 `renderOptionList()` 方法                                                        |
+| `form-item.ts`      | 提取 `labelIcon`、`requiredMark`、`labelBlock` 变量                                   |
+| `select.ts`         | 提取 `selectedLabel` 变量、`renderOptionList()` 方法                                  |
+| `docs-viewer.ts`    | 改用 IIFE + if/else 结构，提取 `previewStyle`、`demoErrorBlock`、`demoSection` 变量   |
+
+#### ESLint 修复（其他规则）
+
+| 规则                                  | 文件               | 修复方式                                                          |
+| ------------------------------------- | ------------------ | ----------------------------------------------------------------- |
+| `sonarjs/no-unused-imports`           | `progress-ring.ts` | 移除未使用的 `html` 导入                                          |
+| `sonarjs/no-unused-imports`           | `button.ts`        | 移除未使用的 `nothing` 导入                                       |
+| `sonarjs/slow-regex`                  | `markdown.ts`      | 限制量词范围：`[^\]]+` → `[^\]]{1,200}`，`[^)]+?` → `[^)]{1,500}` |
+| `sonarjs/no-nested-template-literals` | `affix.ts`         | 提取嵌套模板字面量为独立变量                                      |
+
+#### SonarQube S2933 修复
+
+为所有 61 个缺少 `readonly` 的箭头函数类属性添加 `readonly` 修饰符，涉及 35 个组件文件。
+
+#### Prettier 格式化
+
+对 `src/` 和 `apps/` 下全部文件执行 Prettier 格式化，统一代码风格。
+
+### 删除
+
+- **`.eslintignore`** — ESLint flat config 中已废弃，ignores 配置移至 `eslint.config.js`

package/docs/issue/issue_26.2.2.4.md

@@ -0,0 +1,95 @@
+# Issue 26.2.2.4
+
+## 版本信息
+
+- **版本号**: 26.2.2.4
+- **基线版本**: 26.2.2
+- **类型**: Feature / i18n
+- **日期**: 2026-05-12
+
+## 变更概述
+
+1. 新增国际化（i18n）核心框架：`src/core/i18n/`，支持 `en-US` / `zh-CN` 两种语言（BCP 47 标准）
+2. 新增 `aithe-locale-switch` 语言切换组件（主题分类），基于 dropdown 浮层模式
+3. 19 个含硬编码文本的组件全部接入 `t()` 翻译函数
+4. 核心库与应用层翻译分离：`registerAitheTranslations()` 支持用户注册自定义翻译资源
+5. Demo / API 应用均集成 i18n，顶栏提供语言切换入口
+6. 修复 SonarQube 问题：S6551、S2933、S1854、S1481、S3776
+7. 为所有新增/修改代码添加中英文双语注释
+8. 新增 API 文档：`docs/api/theme/locale-switch.md`
+
+## 破坏性变更
+
+无。
+
+## 变更内容
+
+### 新增
+
+- **i18n 核心框架** — `src/core/i18n/index.ts`，提供 `AitheLocale` 类型（`'en-US' | 'zh-CN'`，BCP 47 标准）、`registerAitheLocale()`（注册完整 locale，替换）、`registerAitheTranslations()`（合并追加翻译）、`setAitheLocale()` / `getAitheLocale()`、`initAitheLocale()`（初始化 + 旧值 `'en'`/`'zh'` 自动迁移）、`t(key, ...args)` 翻译函数（en-US 回退）、`onAitheLocaleChange()` 订阅
+- **核心英文翻译资源** — `src/core/i18n/locales/en-US.ts`，73 个翻译键，覆盖 19 个组件
+- **核心中文翻译资源** — `src/core/i18n/locales/zh-CN.ts`，73 个翻译键，覆盖 19 个组件
+- **locale 资源导出入口** — `src/core/i18n/locales/index.ts`
+- **AitheLocaleSwitch 组件** — 语言切换器，基于 dropdown 浮层模式，支持 `en-US` / `zh-CN` 切换、键盘导航，通过 `aithe-locale-change` 事件通知语言变更
+- **locale-switch API 文档** — `docs/api/theme/locale-switch.md`
+- **API 应用翻译资源** — `apps/api/i18n/en-US.ts`、`apps/api/i18n/zh-CN.ts`、`apps/api/i18n/index.ts`（`registerApiTranslations()`）
+- **Demo 应用翻译资源** — `apps/demo/i18n/en-US.ts`、`apps/demo/i18n/zh-CN.ts`、`apps/demo/i18n/index.ts`（`registerDemoTranslations()`）
+
+### 修改
+
+#### 组件国际化（19 个组件）
+
+| 分类       | 组件          | 变更说明                                                                                                        |
+| ---------- | ------------- | --------------------------------------------------------------------------------------------------------------- |
+| Basic      | input         | aria-label 从硬编码 `'Input'` 改为 `t('basic.input.ariaLabel')`                                                 |
+| Basic      | avatar        | aria-label 从硬编码 `'Avatar'` 改为 `t('basic.avatar.ariaLabel')`                                               |
+| Basic      | empty         | 默认文本从硬编码 `'暂无数据'` 改为 `t('basic.empty.defaultText')`；默认 `text` 属性改为空字符串                 |
+| Navigation | breadcrumb    | aria-label 从硬编码 `'Breadcrumb'` 改为 `t('navigation.breadcrumb.ariaLabel')`                                  |
+| Navigation | back-top      | aria-label 从硬编码改为 `t('navigation.backTop.ariaLabel')`                                                     |
+| Form       | select        | placeholder、搜索提示、清除按钮、空文本等硬编码改为 `t()` 调用                                                  |
+| Form       | combobox      | placeholder 和空文本从硬编码改为 `t()` 调用；默认 `placeholder` 属性改为空字符串                                |
+| Form       | rate          | aria-label 从硬编码改为 `t('form.rate.ariaLabel')` 插值函数                                                     |
+| Form       | upload        | "Choose files" 和 "KB" 改为 `t()` 调用                                                                          |
+| Form       | transfer      | "Source"/"Target" 标题改为 `t()` 调用                                                                           |
+| Form       | form-item     | 必填验证消息改为 `t('form.formItem.required')` 插值函数                                                         |
+| Feedback   | dialog        | confirmText/cancelText 默认值改为空字符串，渲染时通过 `t()` 回退；关闭按钮 aria-label 国际化                    |
+| Feedback   | modal         | 关闭按钮 aria-label 从硬编码改为 `t('feedback.modal.closeAriaLabel')`                                           |
+| Feedback   | drawer        | 关闭按钮 aria-label 从硬编码改为 `t('feedback.drawer.closeAriaLabel')`                                          |
+| Data       | tabs          | "Remove tab"/"Add tab" aria-label 改为 `t()` 调用                                                               |
+| Data       | table         | "Select all"/"Select row" aria-label 和空文本改为 `t()` 调用                                                    |
+| Display    | carousel      | "Previous slide"/"Next slide" aria-label 改为 `t()` 调用                                                        |
+| Display    | comparison    | "Before"/"After" alt 文本改为 `t()` 调用                                                                        |
+| Container  | details       | 默认 summary 从硬编码 `'Details'` 改为 `t('container.details.defaultSummary')`；默认 `summary` 属性改为空字符串 |
+| Theme      | theme-picker  | "Light"/"Dark" 分组标签改为 `t()` 调用                                                                          |
+| Theme      | theme-preview | 所有硬编码文本（标题、按钮、侧边栏、组件示例）改为 `t()` 调用                                                   |
+
+#### 核心库导出
+
+- **`src/index.ts`** — 新增 `core/i18n` 和 `locale-switch` 导出
+- **`src/global.ts`** — `initializeAitheUI()` 中注册 en-US/zh-CN locale 并调用 `initAitheLocale('en-US')`
+
+#### API 应用
+
+- **`apps/api/app.ts`** — 集成 i18n：添加 `localeVersion` 状态、`onAitheLocaleChange` 订阅、`<aithe-locale-switch>` 组件、`registerApiTranslations()` 调用
+- **`apps/api/docs-viewer.ts`** — 集成 i18n：`DocCategory.label`/`DocEntry.label` 类型改为 `string | (() => string)`；添加 `localeVersion` 状态；重构 `render()` 为 `renderSidebar()`/`renderEmpty()`/`renderDemoSection()`/`renderContent()` 私有方法；移除死代码 `currentHtml` getter
+- **`apps/api/pages/docs.ts`** — 所有分类和条目标签改为 `() => t('api.*')` 模式
+
+#### Demo 应用
+
+- **`apps/demo/app.ts`** — 集成 i18n：添加 `localeVersion` 状态、`onAitheLocaleChange` 订阅、`<aithe-locale-switch>` 组件、`registerDemoTranslations()` 调用
+- **`apps/demo/editor.ts`** — "Code"/"Reset" 标签改为 `t()` 调用；`DemoExample.title`/`description` 类型改为 `string | (() => string)`
+- **`apps/demo/pages/*.ts`** — 全部 10 个页面文件硬编码文本改为 `() => t('demo.*')` 模式
+
+#### SonarQube 修复
+
+| 规则  | 严重度 | 文件                                                             | 修复方式                                                                    |
+| ----- | ------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| S1854 | Major  | `apps/api/app.ts`、`apps/demo/app.ts`、`apps/api/docs-viewer.ts` | `localeVersion` 写而未读：在 `render()` 顶部添加 `void this.localeVersion;` |
+| S1481 | Minor  | `apps/api/docs-viewer.ts`                                        | 移除未使用的 `currentHtml` getter                                           |
+| S2933 | Major  | `src/components/navigation/dropdown.ts`                          | `items` 属性类型添加 `readonly` 修饰符                                      |
+| S3776 | Major  | `apps/api/docs-viewer.ts`                                        | 重构 `render()` 方法，提取 4 个私有方法降低认知复杂度                       |
+| S6551 | Major  | `src/core/i18n/locales/en-US.ts`、`zh-CN.ts`                     | 插值函数中使用 `String(index)` 替代隐式字符串化                             |
+
+### 删除
+
+- **根目录 `issue_26.2.2.4.md`** — 误放于项目根目录，已迁移至 `docs/issue/issue_26.2.2.4.md`

package/docs/quickstart.md

@@ -0,0 +1,115 @@
+# Quick Start / 快速上手
+
+Aithe UI 是基于 Lit 3.x 的 Web Components 组件库，提供 79 个可复用 UI 组件、22 种内置主题和完整的国际化支持。
+
+## 安装
+
+```bash
+npm install aithe-ui
+```
+
+## 基本使用
+
+### 1. 导入并初始化
+
+```ts
+// 导入整个库（自动注册所有组件 + 初始化主题和 i18n）
+import 'aithe-ui';
+```
+
+仅此一行即可使用所有组件——`import 'aithe-ui'` 会自动完成：
+
+- 注册全部 79 个 Custom Elements
+- 注入 22 种主题的 CSS 变量
+- 初始化 i18n（默认 `en-US`）
+
+### 2. 在 HTML 中使用组件
+
+```html
+<aithe-button type="primary" size="medium">Submit</aithe-button>
+
+<aithe-input placeholder="Enter your name" clearable></aithe-input>
+
+<aithe-select
+  .options=${[{ label: 'Option A', id: 'a' }, { label: 'Option B', id: 'b' }]}
+></aithe-select>
+```
+
+### 3. 按需导入（Tree-shaking）
+
+```ts
+// 仅导入需要的组件
+import { AitheButton } from 'aithe-ui';
+import { AitheInput } from 'aithe-ui';
+```
+
+> **注意**：按需导入时需手动调用 `initializeAitheUI()` 以注入主题和 i18n。
+
+```ts
+import { initializeAitheUI, AitheButton, AitheInput } from 'aithe-ui';
+
+initializeAitheUI(); // 必须手动调用
+```
+
+### 4. 切换主题
+
+```ts
+import { setAitheTheme } from 'aithe-ui';
+
+// 切换到暗色主题（自动持久化到 localStorage）
+setAitheTheme('dark');
+```
+
+或使用内置的主题选择器组件：
+
+```html
+<aithe-theme-picker></aithe-theme-picker>
+```
+
+### 5. 切换语言
+
+```ts
+import { setAitheLocale } from 'aithe-ui';
+
+// 切换到中文（自动持久化到 localStorage）
+setAitheLocale('zh-CN');
+```
+
+或使用内置的语言切换组件：
+
+```html
+<aithe-locale-switch></aithe-locale-switch>
+```
+
+## 完整示例
+
+```html
+<!DOCTYPE html>
+<html lang="en-US">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Aithe UI App</title>
+  </head>
+  <body>
+    <script type="module">
+      import 'aithe-ui';
+      import { setAitheTheme, setAitheLocale } from 'aithe-ui';
+
+      // 可选：设置初始主题和语言
+      setAitheTheme('light');
+      setAitheLocale('en-US');
+    </script>
+
+    <aithe-button type="primary">Hello Aithe</aithe-button>
+  </body>
+</html>
+```
+
+## 下一步
+
+- [使用指南](guide.md) — 组件通用 API、事件、插槽
+- [主题系统](theming.md) — 22 种内置主题、自定义主题、CSS 变量
+- [国际化](i18n.md) — 多语言支持、自定义翻译
+- [框架集成](framework-integration.md) — React / Vue / Angular / Svelte 集成
+- [API 参考](api/summary.md) — 全部 79 个组件的详细 API 文档

package/docs/theming.md

@@ -0,0 +1,257 @@
+# 主题系统 / Theming
+
+Aithe UI 提供完整的主题系统，包含 22 种内置主题、全局/局部切换、CSS 变量定制和程序化 API。
+
+---
+
+## 内置主题
+
+### Light 系（11 种）
+
+| 主题名    | 说明             |
+| --------- | ---------------- |
+| `light`   | 默认浅色主题     |
+| `gray`    | 灰色调浅色主题   |
+| `blue`    | 蓝色调浅色主题   |
+| `festive` | 节日风格浅色主题 |
+| `orange`  | 橙色调浅色主题   |
+| `purple`  | 紫色调浅色主题   |
+| `pink`    | 粉色调浅色主题   |
+| `teal`    | 青色调浅色主题   |
+| `indigo`  | 靛蓝色调浅色主题 |
+| `cyan`    | 青蓝色调浅色主题 |
+| `amber`   | 琥珀色调浅色主题 |
+
+### Dark 系（11 种）
+
+| 主题名     | 说明             |
+| ---------- | ---------------- |
+| `dark`     | 默认暗色主题     |
+| `slate`    | 石板灰暗色主题   |
+| `charcoal` | 炭灰色暗色主题   |
+| `midnight` | 午夜蓝暗色主题   |
+| `obsidian` | 黑曜石暗色主题   |
+| `graphite` | 石墨色暗色主题   |
+| `ink`      | 墨色暗色主题     |
+| `onyx`     | 缟玛瑙暗色主题   |
+| `ebony`    | 乌木色暗色主题   |
+| `navy`     | 海军蓝暗色主题   |
+| `raisin`   | 葡萄干色暗色主题 |
+
+---
+
+## 切换主题
+
+### 程序化 API
+
+```ts
+import { setAitheTheme, getAitheTheme } from 'aithe-ui';
+
+// 切换主题（自动持久化到 localStorage）
+setAitheTheme('dark');
+
+// 切换主题但不持久化
+setAitheTheme('midnight', false);
+
+// 获取当前主题
+const current = getAitheTheme(); // 'dark'
+```
+
+### 使用主题选择器组件
+
+```html
+<!-- 基本用法 -->
+<aithe-theme-picker></aithe-theme-picker>
+
+<!-- 指定下拉位置 -->
+<aithe-theme-picker placement="bottom-start"></aithe-theme-picker>
+
+<!-- 监听主题变更 -->
+<aithe-theme-picker @aithe-theme-change="${(e)" ="">
+  console.log(e.detail.theme)}>
+</aithe-theme-picker>
+```
+
+### 使用主题预览组件
+
+```html
+<!-- 预览主题效果后再应用 -->
+<aithe-theme-preview></aithe-theme-preview>
+
+<!-- 监听确认应用 -->
+<aithe-theme-preview @aithe-theme-apply="${(e)" ="">
+  console.log('Applied:', e.detail.theme)}>
+</aithe-theme-preview>
+```
+
+---
+
+## 主题作用域
+
+### 全局主题
+
+通过 `setAitheTheme()` 设置全局主题，作用于 `<html>` 元素的 `data-aithe-theme` 属性：
+
+```ts
+setAitheTheme('dark');
+// <html data-aithe-theme="dark">
+```
+
+### 局部主题覆盖
+
+通过组件的 `theme` 属性为单个组件指定不同主题：
+
+```html
+<!-- 全局 light，此组件使用 dark -->
+<aithe-card theme="dark">
+  <aithe-button type="primary">Dark Button</aithe-button>
+</aithe-card>
+```
+
+组件内部通过 `computedTheme` getter 解析最终主题（本地覆盖 → 最近带主题祖先 → 全局）。
+
+---
+
+## CSS 变量体系
+
+### 色阶变量
+
+每个主题定义 4 组色阶（1-10，由浅到深）：
+
+```css
+--aithe-primary-1  /* 最浅 */
+--aithe-primary-2
+...
+--aithe-primary-10 /* 最深 */
+
+--aithe-success-1 ~ --aithe-success-10
+--aithe-warning-1 ~ --aithe-warning-10
+--aithe-danger-1 ~ --aithe-danger-10
+--aithe-neutral-1 ~ --aithe-neutral-10
+```
+
+### 语义颜色变量
+
+```css
+--aithe-color-bg              /* 页面背景 */
+--aithe-color-bg-subtle       /* 页面背景（渐变） */
+--aithe-color-surface         /* 卡片/面板背景 */
+--aithe-color-surface-elevated /* 浮层/弹窗背景 */
+--aithe-color-surface-muted   /* 次要表面背景 */
+--aithe-color-border          /* 默认边框 */
+--aithe-color-border-strong   /* 强调边框 */
+--aithe-color-text            /* 主文本 */
+--aithe-color-text-muted      /* 次要文本 */
+--aithe-color-text-subtle     /* 辅助文本 */
+--aithe-color-overlay         /* 遮罩层 */
+--aithe-color-selection       /* 选中高亮 */
+--aithe-color-focus-ring      /* 焦点环 */
+```
+
+### 原始设计令牌
+
+```css
+/* 间距 */
+--aithe-space-1 ~ --aithe-space-10  /* 4px ~ 64px */
+--aithe-space-xs                    /* 8px */
+--aithe-space-sm                    /* 12px */
+--aithe-space-md                    /* 16px */
+--aithe-space-lg                    /* 24px */
+--aithe-space-xl                    /* 40px */
+
+/* 圆角 */
+--aithe-radius-sm   /* 6px */
+--aithe-radius-md   /* 10px */
+--aithe-radius-lg   /* 14px */
+--aithe-radius-xl   /* 20px */
+--aithe-radius-full /* 999px */
+
+/* 阴影 */
+--aithe-shadow-1 ~ --aithe-shadow-5
+
+/* 字体 */
+--aithe-font-family       /* 'Sora', 'IBM Plex Sans', 'PingFang SC', 'Microsoft YaHei', sans-serif */
+--aithe-font-family-mono  /* 'JetBrains Mono', 'SFMono-Regular', 'Consolas', monospace */
+--aithe-font-size-xs ~ --aithe-font-size-2xl  /* 12px ~ 28px */
+
+/* 动画 */
+--aithe-duration-fast  /* 140ms */
+--aithe-duration-base  /* 220ms */
+--aithe-duration-slow  /* 320ms */
+--aithe-ease-standard  /* cubic-bezier(0.2, 0.8, 0.2, 1) */
+
+/* 控件高度 */
+--aithe-control-height-sm  /* 32px */
+--aithe-control-height-md  /* 40px */
+--aithe-control-height-lg  /* 48px */
+
+/* 层级 */
+--aithe-z-dropdown  /* 1000 */
+--aithe-z-popover   /* 1010 */
+--aithe-z-modal     /* 1080 */
+--aithe-z-drawer    /* 1090 */
+--aithe-z-tooltip   /* 1120 */
+```
+
+---
+
+## 自定义主题
+
+### 覆盖 CSS 变量
+
+最简单的方式是覆盖现有变量：
+
+```css
+:root {
+  --aithe-primary-6: #1890ff;
+  --aithe-primary-7: #096dd9;
+  --aithe-radius-md: 4px;
+}
+```
+
+### 创建完整自定义主题
+
+通过 CSS 类名定义新主题，遵循 Aithe UI 的变量命名规范：
+
+```css
+.aithe-theme-custom,
+[data-aithe-theme='custom'] {
+  color-scheme: light;
+
+  /* 色阶 */
+  --aithe-primary-1: #f0f5ff;
+  --aithe-primary-2: #d6e4ff;
+  --aithe-primary-3: #adc6ff;
+  --aithe-primary-4: #85a5ff;
+  --aithe-primary-5: #597ef7;
+  --aithe-primary-6: #2f54eb;
+  --aithe-primary-7: #1d39c4;
+  --aithe-primary-8: #10239e;
+  --aithe-primary-9: #061178;
+  --aithe-primary-10: #030852;
+
+  /* ... 其他色阶和语义变量 ... */
+}
+```
+
+然后通过 `setAitheTheme('custom')` 应用。
+
+---
+
+## 持久化
+
+主题选择自动保存到 `localStorage`（键名 `aithe-theme`），页面刷新后自动恢复。
+
+```ts
+// 初始化时指定默认主题（无存储偏好时使用）
+import { initializeAitheUI } from 'aithe-ui';
+initializeAitheUI('dark'); // 默认使用 dark 主题
+```
+
+---
+
+## 下一步
+
+- [国际化](i18n.md) — 多语言支持
+- [使用指南](guide.md) — 组件通用 API
+- [API 参考](api/summary.md) — 全部组件详细 API