@aithe/aithe-ui 26.2.2 → 26.2.3

package/docs/changelog/VERSION_26.2.3.md

@@ -0,0 +1,877 @@
+# Aithe UI 26.2.3 版本详细说明
+
+## 版本信息
+
+- **版本号**: 26.2.3
+- **发布日期**: 2026-05-14
+- **最新子版本**: 26.2.3.15
+- **版本类型**: 基线版本
+- **版本描述**: 2026年第2季度第3个月版本 — 代码规范与架构质量提升
+
+## 版本变更记录
+
+### Issue 26.2.3.15 — Refactor / Quality (2026-06-08)
+
+1. **SonarQube 深度代码质量修复** — `code-editor.ts` `renderToolbar` 中 6 个嵌套三元提取为 7 个独立方法，Cognitive Complexity 降至 15 以下；`autoform.ts` `FormRuleEngine.evaluate` 中 `switch` → `RULE_HANDLERS` 查找表，Cognitive Complexity 从 22 降至远低于 15；`parser.ts` `parseBlocks`/`_parseInlines`/`renderAst` 三个超标函数重构（提取 `_matchBlockPlugin`、`_collectParagraph`、`_isBlockStart`、`_matchInlinePlugin`、`_collectPlainText`、`renderCodeBlock`、`renderListItem`、`renderTable` 等独立函数），`esc`/`renderAst`/`renderChildren` 移入 `MarkdownParser` 类作为 `static`/`private static` 方法；`docs-viewer.ts` `handleContentClick` Cognitive Complexity 从 26 降至远低于 15（拆分为 `parseMdLink`/`trySelectGuide`/`trySelectComponent`）；`plugins.ts` 嵌套 `if/else if` 提取为 `parseListItem()`；`condition.ts` `expr.match()` → `re.exec()` + 可选链 + `[a-zA-Z0-9_]` → `\w`；`lang-perl.ts` 分支 `(?:q|w|x|r)` → `[qwxr]`；38 个高亮语言文件 `[a-zA-Z0-9_]` → `\w`
+2. **`intent` → `variant` 属性重命名** — `AitheSelectOption`、`AitheTableColumnMeta`、`AitheTimelineItemMeta`、`AitheTreeNodeMeta` 中 `intent` 字段重命名为 `variant`；所有消费组件同步更新（avatar、icon、table、table-column、timeline、tree、tree-menu、combobox、select、switch、rate、form-item、autoform-item、markdown-editor、header、sidebar、dashboard、admin-layout、dashboard-page、login-page、datahub/auth、datahub/dashboard、datahub/index、datahub/menu、demo/pages/autoform、demo/pages/basic、demo/pages/data、demo/pages/navigation、demo/editor）
+3. **`AitheTreeNodeMeta.divider` 移除** — 替换为 `type?: 'item' | 'divider'`，节点类型语义更清晰
+4. **`AitheDropdownItem` 类型移除** — 统一使用 `AitheTreeNodeMeta`
+5. **`aithe-dropdown` 迁移** — 从 `@components/navigation/dropdown` 迁移至 `@components/data/dropdown`，内部实现改为委托 `<aithe-tree-menu>` 渲染
+6. **Theme picker 组件重构** — `aithe-theme-picker`、`aithe-shape-picker`、`aithe-shadow-picker`、`aithe-typo-picker` 全面改用 `<aithe-tree-menu>` 渲染选项列表，移除内联选项渲染和浮层定位逻辑
+7. **`aithe-locale-switch` 重构** — 移除内联 locale 选项数据，改为使用 `@styles/i18n` 导出的 `localeMenu`
+8. **`aithe-theme-switch` 新增** — 统一外观切换器组件，一键切换主题/形状/阴影/排版
+9. **`aithe-metrics` / `aithe-metrics-group` 新增** — 指标展示组件，支持标签和数值展示
+10. **`AitheSidebarItemFilter` 类型新增**
+11. **`AitheTranslationValue` 类型删除** — 28 个 locale 文件中引用改为 `string`，移除对应 `import type`
+12. **国际化扩展** — `code-editor.ts` 硬编码中文 title 替换为 `t('display.codeEditor.xxx', 'English fallback')` 国际化调用；10 个 locale 文件添加 `display.codeEditor.*` 翻译键
+13. **`admin/router/index.ts` 类型重新导出** — 添加 `export type { RouteConfig, RouteLocation } from '@core/router'`
+14. **构建优化** — `vite.config.ts` 新增 `litExternalPlugin()` 将 lit 标记为外部依赖；`build` 脚本顺序调整为先类型声明后构建；`package.json` lit 升级到 `^3.3.3`，新增 `lit-html` 依赖
+15. **文档同步更新** — `docs/api/` 新增 `data/dropdown.md`、`framework/metrics.md`、`framework/metrics-group.md`、`theme/theme-switch.md`；删除 `navigation/dropdown.md`；多个 API 文档同步更新属性名；`docs/` 下多个指南文档更新
+16. **类型检查** — `pnpm check` 全部通过（零错误）
+
+### Issue 26.2.3.14 — Feature (2026-06-01)
+
+1. **DataHub APIStyle 业务协议解析机制** — 新增 `DataHubAPIStyle` 接口体系，支持通过 `setAPIStyle()` 设置全局业务协议解析器，自动进行请求体包装和响应解包；内置 `default`（标准 `{ code, message, data }` 结构）和 `k8s`（Kubernetes 风格）两种风格；新增 `getBuiltinStyle()`/`getBuiltinStyleNames()` 工具函数
+2. **DataHub 类型体系重构** — 类型名规范化：`AdapterRequest` → `DataHubAdapterRequest`、`AdapterResponse` → `DataHubAdapterResponse`、`StrategyConfig` → `DataHubStrategyConfig`、`StrategyType` → `DataHubStrategyType`；移除 `DataHubResponse` 类型，新增 `DataHubAPIResult` 类型；适配器 `request` 返回 `DataHubAdapterResponse`（`data` 为原始 JSON，不做业务语义假设）
+3. **DataHub 架构解耦** — 移除 `DataHubCore` 中与传输层无关的业务逻辑：移除 `ApiRegistry` API 注册机制、移除 `DataHubResponse` 业务响应假设；新增 `api-styles.ts` 独立模块管理内置风格
+4. **单次请求临时指定 APIStyle** — `DataHubRequestOptions` 新增 `apiStyle` 字段，支持在单次请求中临时覆盖全局 APIStyle，`request()` 方法优先使用 `options.apiStyle`，回退到 `this.apiStyle`
+5. **Autoform 模块重构** — `rule-engine.ts` 重命名为 `autoform.ts`，合并 `FormRuleEngine` 和 `FormRegistry`；条件表达式解析逻辑提取到独立 `condition.ts`；新增 `types.ts` 统一类型定义（`FormRule`、`FormRuleType`、`FormFieldConfig`、`FormItemOption`），组件层类型引用从本地接口改为 `@core/autoform` 导出
+6. **文档同步更新** — `docs/datahub.md` 全面更新：新增 APIStyle 章节、类型参考更新、移除 API 注册相关文档；`docs/autoform.md` 和 `docs/api/form/autoform.md` 同步更新
+
+### Issue 26.2.3.13 — Refactor (2026-05-29)
+
+1. **Markdown 解析引擎重构为 AST 架构** — 从正则替换架构全面重构为两阶段 AST 解析架构（块级 → 行内），`MarkdownPlugin` 接口废弃，新增 `AstPlugin` 接口；`SimpleMarkdownParser`/`FullMarkdownParser` 构造函数移除 `linkHooks` 参数，改为 `addLinkHook()` 方法；新增 `parseToAst()` 方法；移除 `createLinkPlugin()` 导出
+2. **AGENTS.md 文件体系** — 为 `src/` 和 `docs/` 下 21 个子目录创建 `AGENTS.md` 文件，用于指引 AI 编程；配置构建插件确保文件随 npm 包发布
+3. **文档同步更新** — `docs/markdown.md` 全面更新为 AST 架构文档；`docs/guide.md` 中 Markdown 解析器使用示例同步更新
+
+### Issue 26.2.3.12 — Feature (2026-05-28)
+
+1. **Markdown 渲染引擎自研** — 新增自研 Markdown 解析引擎（`src/core/markdown/`），包含插件化解析器、15 个内置插件（标题/粗斜体/链接/图片/代码块/引用/列表/表格/删除线/任务列表/锚点/脚注/数学公式/Emoji/目录），`<aithe-markdown>` 从 markdown-it 迁移至自研引擎
+2. **语法高亮引擎** — 新增 `src/core/highlight/` 语法高亮引擎，内置 38 种语言支持，基于正则匹配的轻量级实现
+3. **新 Display 组件** — 新增 `<aithe-code-editor>` 代码编辑器组件（语法高亮、行号、复制、折叠）、`<aithe-markdown-editor>` Markdown 编辑器组件（实时预览、分屏模式）、`<aithe-label>` 标签组件
+4. **Autoform 依赖联动规则引擎** — 新增 `autoform.ts` 规则引擎，支持字段间依赖联动、条件显隐、值计算
+5. **Theme CSS 变量扩展** — 22 个主题文件新增 `--aithe-code-*` CSS 变量系列（语法高亮配色）
+6. **Docs-viewer 增强** — 代码块自动转换为 `<aithe-code-editor>` 渲染；guide 文档链接导航修复
+7. **Demo 编辑器增强** — 新增 `displayCode`、`hideEditor`、`editedJson` 属性支持
+8. **Autoform Demo 重构** — 重构为 `setupWithFields` 模式，新增字段配置规范化示例
+9. **i18n 扩展** — 10 个语言文件新增 display 和 guides 翻译键
+10. **文档更新** — README 组件数更新（85→90+）、新增 6 个 API 文档、guide.md 新增语法高亮/Markdown 渲染章节
+
+### Issue 26.2.3.11 — Feature (2026-05-26)
+
+1. **Autoform 自动表单组件** — 新增 `<aithe-autoform>` JSON 配置驱动的自动渲染表单组件和 `<aithe-autoform-item>` 表单项组件，支持 13 种内置控件类型、自定义控件注册表（FormRegistry）、实时校验和提交校验
+2. **Dashboard Demo 页面** — 新增 Dashboard 独立 demo 页面，包含基础、锁定、无工具栏、自定义内容、状态持久化、紧凑网格 6 个示例
+3. **Demo/API 文档布局增强** — docs-viewer 和 demo-editor 新增 `layout` 属性支持 `vertical` 布局模式
+4. **SonarQube 代码质量修复** — replace→replaceAll（S7781）、移除冗余类型断言（S4325）、forEach→for…of（S7891）、readonly 修饰
+5. **Input/Textarea/Combobox/Select 样式修复** — 修复输入类控件对齐、padding、focus 样式和 disabled 状态显示问题
+6. **Radio Group 同步机制重构** — 从 `@queryAssignedElements` 改为 `querySelectorAll` 动态查询，修复 checked 状态同步问题
+
+### Issue 26.2.3.10 — Feature (2026-05-23)
+
+1. **Dashboard 仪表盘组件** — 新增 `<aithe-dashboard>` 拖拽式仪表盘组件和 `<aithe-dashboard-panel>` 面板卡片组件，支持格子布局、拖拽排列、面板调整大小、状态持久化和全屏模式
+2. **Theme Picker icon-only 模式** — 5 个风格选择器组件（theme-picker、shape-picker、shadow-picker、typo-picker、locale-switch）新增 `icon-only` 属性
+3. **SonarQube 代码质量修复** — 批量修复 forEach→for…of（S7891）、window→globalThis（S7764）、readonly 修饰、dataset 访问（S7761）、反转三元表达式（S7735）、冗余 String() 包装等合规问题
+4. **AitheForm 导出方式调整** — 从命名导出改为默认导出
+5. **AitheLocale 类型增强** — 使用 unique symbol 替代 `string & {}` 模式，提升类型安全性
+
+### Issue 26.2.3.9 — Feature (2026-05-22)
+
+1. **排版（Typography）正交风格系统** — 新增 4 种内置排版风格（minimal/business/luxury/compact），与 Theme/Shape/Shadow 正交，通过 CSS 变量动态切换字号/字重/行高/间距/控件高度
+2. **`<aithe-typo-picker>` 组件** — 排版风格选择器组件，基于 floating overlay 模式
+3. **日志系统** — 新增 `@core/logger` 日志核心模块（console 劫持、全局错误捕获、远程上报）和 `<aithe-log-panel>` 可视化面板组件
+4. CSS 变量默认值从 `:host` 硬编码迁移到排版系统动态注入
+5. `aithe-body` 重构为内部滚动容器，`aithe-theme-preview` 集成排版选择器
+
+### Issue 26.2.3.8 — Feature (2026-05-20)
+
+1. **Shadow 阴影风格系统** — 新增 9 种内置阴影风格：
+   - flat（扁平）、neumorphism（新拟态）、skeuomorphic（拟物化）
+   - glassmorphism（玻璃拟态）、cyber（赛博）、deep（深度）
+   - diffuse（扩散）、sharp-business（锐利商务）、retro（复古）
+2. **`<aithe-shadow-picker>`** 组件 — 阴影风格选择器，基于 floating overlay 模式，支持 `placement` 属性和 i18n
+3. **aitheUI 单例扩展** — `AitheUI` 类新增 `getShadow()`、`setShadow()`、`getShadows()`、`onShadowChange()` 方法
+4. **类型定义** — `src/styles/types.ts` 新增 `AitheBuiltinShadow` 和 `AitheShadowName` 类型
+5. 删除 `src/core/global.ts` 统一初始化模块，简化为 `aitheUI` 单例
+6. 重构 i18n 模块路径：`@core/i18n` 移动到 `@styles/i18n`
+7. 统一外部 API 命名规范，推荐使用 `aitheUI` 实例方法替代独立函数
+8. 优化文档，移除已过时的 `initializeAitheUI` 说明和 `translateNodeLabel` API 文档
+9. 清理代码中的旧版 locale 值兼容逻辑
+
+### Issue 26.2.3.7 — Feature (2026-05-19)
+
+1. **Shape 形状风格体系** — 新增 8 种内置形状风格：sharp、smooth、rounded、rounder、pill、circle、chamfer、organic，与颜色主题正交设计，支持自由组合（Theme × Shape）
+2. **双轨圆角 Token 体系** — 控件使用 `--aithe-radius-*`，容器使用 `--aithe-container-radius-*`，Pill/Circle/Organic 等极端形状仅对控件生效
+3. **`aithe-shape-picker` 组件** — 形状选择器，支持预览缩略图、键盘导航、`value` 受控属性和 `placement` 属性
+4. **`aithe-theme-preview` 集成** — 工具栏新增 shape-picker，预览区局部生效，点击"应用主题"同时应用到全局
+5. **20+ 容器类组件** — radius 变量从 `--aithe-radius-*` 迁移至 `--aithe-container-radius-*`
+6. **导出全局方法** — `setAitheShape` / `getAitheShape` / `getAitheShapes` / `getShapeTokens` / `onAitheShapeChange`
+
+### Issue 26.2.3.6 — Feature (2026-05-19)
+
+1. **DataHub 数据中间层** — Admin 应用集成 DataHub，菜单、仪表盘、登录均通过 DataHub 获取数据，开发阶段使用 Mock 模式
+2. **`t()` 函数签名变更** — 新增 `defaultValue` 参数，支持翻译缺失时返回缺省值
+3. **`translateNodeLabel()` 函数** — 统一翻译 `AitheTreeNodeMeta` 节点标签
+4. **`AitheTreeNodeMeta` 扩展** — 新增 `divider`、`shortcut`、`i18n` 字段及索引签名
+5. **组件 i18n 支持** — `aithe-dropdown`、`aithe-sidebar`、`aithe-tree`、`aithe-tree-menu` 标签自动翻译
+6. **类型别名** — `AitheDropdownItem` 标记 `@deprecated`，统一使用 `AitheTreeNodeMeta`
+7. **`docs/datahub.md`** — DataHub 独立开发指南文档
+
+### Issue 26.2.3.5 — Feature (2026-05-18)
+
+1. 新增 8 个主流国际化 locale 支持：zh-TW（繁體中文·台灣）、zh-HK（繁體中文·香港）、ja-JP（日本語）、ko-KR（한국어）、es-ES（Español）、pt-BR（Português Brasileiro）、fr-FR（Français）、de-DE（Deutsch）
+2. Core 层新增 8 个 locale 翻译文件，扩展 `AitheBuiltinLocale` 类型联合
+3. App 层（admin / demo / api）各新增 8 个 locale 翻译文件并注册
+4. `aithe-locale-switch` 组件新增 `locales` 属性，支持限定下拉菜单中显示的语言子集
+5. `aithe-locale-switch` 组件新增 `localeSwitch` 翻译键及 10 种语言标签映射
+6. 更新国际化文档和 locale-switch API 文档
+
+### Issue 26.2.3.4 — Feature (2026-05-18)
+
+1. 新增 Admin 应用独立构建配置 `vite.admin.config.ts`，构建产物输出至 `dist/apps/admin/`，包含 `index.html` 和 `aithe-admin.js`
+2. `package.json` 新增 `build:admin` 构建脚本
+
+### Issue 26.2.3.2 — Refactor / Quality (2026-05-14)
+
+1. 导入路径从 `../` 相对路径和 `@/` 单一通配别名统一为 `src` 二级目录对应别名（`@base/*`、`@components/*`、`@core/*`、`@styles/*`、`@types/*`、`@utils/*`）
+2. `AitheIntent` 类型合并至 `AitheVariant`，消除语义重复，统一视觉变体类型
+3. `global.ts` 从 `src/` 根目录迁移至 `src/core/`，符合二级目录别名规范
+4. 删除无组件引用的 `AitheCommonProps` 接口及 `src/types/component.ts` 文件
+5. 修复 SonarQube 告警：`sub-menu.ts` 的 `any` 类型、`input.ts`/`tooltip.ts`/`theme.ts` 的重复字符串常量
+6. `theme-preview.ts` 的 `sidebarItems` 补加 `readonly` 修饰符
+7. 构建流程新增 `tsc-alias` 步骤，确保 dist 产物无别名残留
+8. 新增 `CONTRIBUTING.md` 开发规范文档
+9. API 文档中 `AitheIntent` 类型引用全部更新为 `AitheVariant`，描述从"意图"统一为"变体"
+
+### Issue 26.2.3.1 — Patch (2026-05-13)
+
+1. 新增 `--aithe-color-text-on-primary` 设计令牌，统一主色背景上的文字颜色
+2. 组件内硬编码 `color: white` / `color: #fff` 替换为 `var(--aithe-color-text-on-primary, #ffffff)`
+3. `aithe-menu-item` 新增 `collapsed` 属性，支持侧边栏折叠模式
+4. `aithe-sub-menu` 新增 collapsed 模式渲染分支，折叠时仅显示图标按钮
+5. `src/index.ts` 新增 3 个导出：`core/anchored-overlay`、`core/floating`、`core/styles`
+6. `apps/` 目录迁移至 `src/apps/`，修复 VSCode 因 `rootDir: "src"` 导致的类型检查错误
+
+---
+
+## 概述
+
+Aithe UI 26.2.3 是 2026 年第 2 季度第 3 个月版本，聚焦于代码规范与架构质量提升。本版本在 26.2.2 基线版本的基础上，完成了路径别名体系重构、类型系统统一、SonarQube 合规修复、构建流程优化等核心改进，并新增了侧边栏折叠模式、设计令牌扩展、DataHub 数据中间层（含 APIStyle 业务协议解析机制）、形状风格系统、阴影风格系统、排版风格系统、日志系统、Dashboard 仪表盘、Autoform 自动表单、自研 Markdown 引擎、语法高亮引擎等。组件数量从 79 个扩展至 90 个。
+
+**26.2.3.15 子版本** 聚焦于 SonarQube 深度代码质量修复（Cognitive Complexity 超标函数重构、正则优化、类型安全增强）、`intent` → `variant` 属性重命名、`AitheTreeNodeMeta.divider` → `type` 字段变更、`AitheDropdownItem` 类型移除、`aithe-dropdown` 从 navigation 迁移至 data 分类（委托 `<aithe-tree-menu>` 渲染）、4 个 theme picker 组件全面改用 `<aithe-tree-menu>` 渲染、`aithe-locale-switch` 重构为使用 `localeMenu`、新增 `<aithe-theme-switch>` 统一外观切换器、新增 `<aithe-metrics>`/`<aithe-metrics-group>` 指标组件、`AitheTranslationValue` 类型删除、国际化扩展、构建优化（lit 外部化、lit 升级至 `^3.3.3`）及文档同步更新。
+
+## 核心特性
+
+### 1. 路径别名体系
+
+- **二级目录别名**: 从 `@/*` 单一通配别名改为按 `src` 二级目录单独建立别名：`@base/*`、`@components/*`、`@core/*`、`@styles/*`、`@types/*`、`@utils/*`
+- **全量替换**: 87+ 源文件中的 `../` 相对路径和 `@/` 通配别名全部替换为二级目录别名
+- **构建保障**: 安装 `tsc-alias`，build 命令追加 `tsc-alias` 步骤，自动替换 `.d.ts` 中的别名为相对路径，确保 dist 产物无别名残留
+- **配置同步**: `tsconfig.json`（baseUrl + paths）、`vite.config.ts`、`vite.demo.config.ts`、`vite.api.config.ts`（resolve.alias）同步配置
+
+### 2. 类型系统统一
+
+- **AitheIntent 合并至 AitheVariant**: 消除语义重复，`AitheVariant` 保留更完整的定义（含 `'neutral'` 和 `(string & {})` 扩展）
+- **4 个组件文件更新**: `switch.ts`、`combobox.ts`、table.ts`、`table-column.ts`的类型引用从`AitheIntent`改为`AitheVariant`
+- **核心类型更新**: `src/core/types.ts` 中 5 个接口的字段类型统一为 `AitheVariant`
+- **文档同步**: 9 个 API 文档 + `guide.md` + `issue_26.2.2.1.md` 中类型引用和描述全部更新
+
+### 3. SonarQube 合规
+
+- **any 类型消除**: `sub-menu.ts` 中 `(item as any).collapsed` 改为 `(item as HTMLElement & { collapsed: boolean }).collapsed`
+- **重复字符串常量化**: `input.ts` 抽取 `INPUT_EVENT`、`tooltip.ts` 抽取 `ARIA_DESCRIBED_BY`、`theme.ts` 抽取 `THEME_CLASS_PREFIX`
+- **readonly 规范**: `theme-preview.ts` 的 `sidebarItems` 补加 `readonly` 修饰符
+
+### 4. 侧边栏折叠模式
+
+- **`aithe-menu-item` collapsed 模式**: 新增 `collapsed` 布尔属性，折叠时隐藏文字标签仅保留图标
+- **`aithe-sub-menu` collapsed 模式**: 新增折叠渲染分支，collapsed 时仅显示图标按钮，子菜单以弹出面板形式展示
+
+### 5. 设计令牌扩展
+
+- **`--aithe-color-text-on-primary`**: 22 个主题文件全部新增此 CSS 变量，用于主色（primary）背景上的文字颜色
+- **硬编码颜色替换**: 9 个组件中的 `color: white` / `color: #fff` 替换为 `var(--aithe-color-text-on-primary, #ffffff)`
+
+### 6. 开发规范
+
+- **CONTRIBUTING.md**: 涵盖导入规范、readonly 修饰符规范、Lit 组件编码规范、SonarQube 合规要求、代码格式规范、文档提交与版本规范、别名构建规范、AI 生成代码要求共八个章节
+- **generate-issue skill**: 定义可复用的 issue 文档生成指令
+- **generate-changelog skill**: 定义可复用的 changelog 文档生成指令
+
+### 7. DataHub 数据中间层
+
+- **统一数据接口层**: Admin 应用通过 DataHub 获取菜单、仪表盘、登录等数据
+- **APIStyle 业务协议解析**: 新增 `DataHubAPIStyle` 接口体系，支持通过 `setAPIStyle()` 设置全局业务协议解析器，自动进行请求体包装和响应解包；内置 `default`（标准 `{ code, message, data }` 结构）和 `k8s`（Kubernetes 风格）两种风格
+- **单次请求临时指定**: `DataHubRequestOptions` 新增 `apiStyle` 字段，支持在单次请求中临时覆盖全局 APIStyle
+- **架构解耦**: 移除 `ApiRegistry` API 注册机制，DataHub 职责聚焦传输层，不关心业务协议
+- **Mock 模式**: 开发阶段使用 Mock 数据，支持热切换
+- **`docs/datahub.md`**: DataHub 独立开发指南文档
+
+### 8. 形状风格系统
+
+- **8 种内置形状风格**: sharp（锐角）、smooth（平滑）、rounded（圆角）、rounder（更圆）、pill（药丸）、circle（圆形）、chamfer（斜切）、organic（有机）
+- **双轨圆角 Token**: 控件使用 `--aithe-radius-*`，容器使用 `--aithe-container-radius-*`
+- **正交设计**: 形状风格与颜色主题相互独立，支持 Theme × Shape 自由组合
+- **`<aithe-shape-picker>` 组件**: 形状选择器，支持预览缩略图、键盘导航、`value` 受控属性
+
+### 9. 阴影风格系统
+
+- **9 种内置阴影风格**: flat（扁平）、neumorphism（新拟态）、skeuomorphic（拟物化）、glassmorphism（玻璃拟态）、cyber（赛博）、deep（深度）、diffuse（扩散）、sharp-business（锐利商务）、retro（复古）
+- **独立切换**: 阴影风格与颜色主题、形状相互独立，可自由组合（Theme × Shape × Shadow）
+- **CSS 变量令牌**: 每个阴影风格提供 `--aithe-shadow-1` 到 `--aithe-shadow-5` 等 CSS 变量
+- **`<aithe-shadow-picker>` 组件**: 阴影风格选择器，基于 floating overlay 模式，支持 `placement` 属性和 i18n
+
+### 10. aitheUI 单例
+
+- **统一配置管理**: `AitheUI` 类整合 theme、shape、shadow、layout、i18n 管理
+- **预初始化**: `aitheUI` 为预初始化单例，无需手动调用 `initializeAitheUI()`
+- **方法统一**: 推荐使用 `aitheUI.setTheme()` / `aitheUI.setShape()` / `aitheUI.setShadow()` / `aitheUI.setLocale()` 等实例方法
+
+### 11. 排版风格系统
+
+- **4 种内置排版风格**: minimal（极简）、business（商务）、luxury（轻奢）、compact（紧凑）
+- **CSS 变量动态切换**: 通过排版系统动态注入字号、字重、行高、间距、控件高度等 CSS 变量
+- **正交设计**: 排版风格与颜色主题、形状、阴影相互独立，支持 Theme × Shape × Shadow × Typo 自由组合
+- **`<aithe-typo-picker>` 组件**: 排版风格选择器，基于 floating overlay 模式，支持 `placement` 属性和 i18n
+
+### 12. 日志系统
+
+- **`@core/logger` 模块**: console 劫持、全局错误捕获、远程上报
+- **`<aithe-log-panel>` 组件**: 日志可视化面板，支持 overlay/inline 两种布局、可拖拽调整高度、按级别过滤、搜索、复制、展开详情
+
+### 13. Dashboard 仪表盘
+
+- **`<aithe-dashboard>` 组件**: 拖拽式仪表盘组件，支持 CSS Grid 布局、内置工具栏、面板拖拽交换与网格吸附、面板边缘调整大小、重叠检测与自动重排
+- **`<aithe-dashboard-panel>` 组件**: 面板卡片组件，支持拖拽头部移动、8 方向调整大小、关闭/最大化、锁定、可见性控制
+- **状态持久化**: localStorage 持久化面板布局状态
+- **全屏模式**: 支持全屏展示
+
+### 14. Autoform 自动表单
+
+- **`<aithe-autoform>` 组件**: JSON 配置驱动的自动渲染表单组件，支持 13 种内置控件类型
+- **`<aithe-autoform-item>` 组件**: 表单项容器组件，三段式布局（header + control + footer）
+- **FormRegistry**: 自定义控件注册表，支持注册自定义控件类型
+- **规则引擎**: 字段依赖联动规则引擎，支持条件显隐、必填控制、值计算、选项过滤
+- **校验**: 支持 required/pattern 实时校验和提交校验
+
+### 15. 自研 Markdown 引擎
+
+- **AST 架构重构**: 从正则替换架构重构为两阶段 AST 解析架构（块级 → 行内），`MarkdownPlugin` 接口废弃，新增 `AstPlugin` 接口
+- **插件化解析架构**: `SimpleMarkdownParser`（行内解析）和 `FullMarkdownParser`（完整块级+行内解析）
+- **15 个内置插件**: heading、bold、italic、link、image、code-block、blockquote、list、table、strikethrough、task-list、anchor、footnote、math、emoji、toc
+- **`<aithe-markdown>` 迁移**: 从 markdown-it 第三方库迁移至自研引擎
+
+### 16. 语法高亮引擎
+
+- **`@core/highlight` 模块**: 基于正则匹配的轻量级语法高亮实现
+- **38 种语言支持**: bash、c、cpp、css、dart、go、html、java、javascript、json、python、rust、typescript 等
+- **语言注册表**: 支持自定义语言注册
+- **22 个主题 CSS 变量**: 每个主题新增 `--aithe-code-*` 变量系列（背景色、前景色、关键字、字符串、注释等）
+
+### 17. 新 Display 组件
+
+- **`<aithe-code-editor>`**: 代码编辑器组件，支持语法高亮、行号显示、一键复制、代码折叠
+- **`<aithe-markdown-editor>`**: Markdown 编辑器组件，支持实时预览、分屏模式
+- **`<aithe-label>`**: 标签组件，支持 filled/outlined 变体、多种颜色、可移除、图标支持
+
+### 18. 26.2.3.15 — SonarQube 深度修复与架构重构
+
+- **SonarQube Cognitive Complexity 修复**: `code-editor.ts` `renderToolbar` 6 个嵌套三元提取为 7 个独立方法；`autoform.ts` `FormRuleEngine.evaluate` switch→查找表；`parser.ts` 3 个超标函数重构；`docs-viewer.ts` `handleContentClick` 拆分为 3 个方法；`plugins.ts` 提取 `parseListItem()`；`condition.ts` `expr.match()` → `re.exec()`
+- **正则优化**: `lang-perl.ts` `(?:q|w|x|r)` → `[qwxr]`；38 个高亮语言文件 `[a-zA-Z0-9_]` → `\w`
+- **`intent` → `variant` 重命名**: 统一跨组件属性命名规范，涉及 `AitheSelectOption`、`AitheTableColumnMeta`、`AitheTimelineItemMeta`、`AitheTreeNodeMeta` 及所有消费组件
+- **`AitheTreeNodeMeta.divider` → `type`**: 节点类型语义更清晰
+- **`AitheDropdownItem` 移除**: 统一使用 `AitheTreeNodeMeta`
+- **`aithe-dropdown` 迁移**: 从 navigation 迁移至 data，委托 `<aithe-tree-menu>` 渲染
+- **Theme picker 重构**: 4 个选择器组件全面改用 `<aithe-tree-menu>` 渲染
+- **`aithe-theme-switch` 新增**: 统一外观切换器
+- **`aithe-metrics` / `aithe-metrics-group` 新增**: 指标展示组件
+- **`AitheTranslationValue` 删除**: 28 个 locale 文件引用改为 `string`
+- **构建优化**: `litExternalPlugin()`、lit 升级 `^3.3.3`、新增 `lit-html`
+
+## 组件详细列表
+
+### 基础组件 (12个)
+
+#### 1. `<aithe-button>` - 按钮
+
+- **类型**: primary、default、dashed、text、link
+- **尺寸**: small、medium、large
+- **状态**: loading、disabled、danger
+- **特性**: 图标支持、块级显示、自定义事件
+
+#### 2. `<aithe-button-group>` - 按钮组
+
+- **功能**: 按钮组合布局
+- **特性**: 统一间距、对齐方式
+
+#### 3. `<aithe-icon>` - 图标
+
+- **功能**: 矢量图标显示
+- **特性**: 内置图标库、自定义图标、尺寸控制
+
+#### 4. `<aithe-input>` - 输入框
+
+- **类型**: text、password、number、email 等
+- **特性**: 验证状态、前缀后缀、清除按钮
+- **备注**: 26.2.3.2 抽取 `INPUT_EVENT` 常量，消除重复字符串
+
+#### 5. `<aithe-textarea>` - 文本域
+
+- **功能**: 多行文本输入
+- **特性**: 自动高度调整、字数统计
+
+#### 6. `<aithe-card>` - 卡片
+
+- **结构**: 标题、内容、操作区域
+- **特性**: 阴影、边框、悬停效果
+
+#### 7. `<aithe-tag>` - 标签
+
+- **类型**: 默认、可关闭、可选择
+- **特性**: 多种颜色、圆角样式
+
+#### 8. `<aithe-badge>` - 徽章
+
+- **类型**: 数字、圆点、状态
+- **特性**: 最大值显示、自定义内容
+
+#### 9. `<aithe-avatar>` - 头像
+
+- **类型**: 图片、文字、图标
+- **特性**: 尺寸控制、形状、组头像
+
+#### 10. `<aithe-divider>` - 分割线
+
+- **方向**: 水平、垂直
+- **特性**: 文字位置、虚线样式
+
+#### 11. `<aithe-empty>` - 空状态
+
+- **功能**: 数据为空时的占位显示
+- **特性**: 自定义图标、描述、操作按钮
+
+#### 12. `<aithe-chip>` - 芯片
+
+- **功能**: 紧凑的可选择标签
+- **特性**: 可关闭、可选择、多种颜色
+
+### 布局组件 (10个)
+
+#### 13. `<aithe-container>` - 容器
+
+- **类型**: fluid、fixed、full
+- **特性**: 响应式断点、内边距控制
+
+#### 14. `<aithe-row>` - 行
+
+- **功能**: 24 栅格系统的行容器
+- **特性**: 栅格间隔、对齐方式、换行控制
+
+#### 15. `<aithe-col>` - 列
+
+- **功能**: 24 栅格系统的列
+- **特性**: 响应式断点、偏移、排序
+
+#### 16. `<aithe-flex>` - 弹性布局
+
+- **功能**: 快速弹性布局容器
+- **特性**: 方向、对齐、换行、间距
+
+#### 17. `<aithe-space>` - 间距
+
+- **功能**: 子元素等间距布局
+- **特性**: 方向、大小、对齐
+
+#### 18. `<aithe-page-container>` - 页面容器
+
+- **功能**: 标准页面外壳
+- **特性**: 标题区域、内容区域、页脚区域
+
+#### 19. `<aithe-page>` - 页面
+
+- **功能**: 完整页面布局
+- **特性**: 头部、侧边栏、内容区、页脚
+
+#### 20. `<aithe-collapse>` - 折叠面板
+
+- **类型**: 手风琴、多展开
+- **特性**: 边框样式、图标位置
+
+#### 21. `<aithe-collapse-item>` - 折叠项
+
+- **功能**: 单个可折叠面板
+- **特性**: 标题、内容、禁用状态
+
+#### 22. `<aithe-affix>` - 固钉
+
+- **功能**: 滚动时固定元素
+- **特性**: 偏移量、目标容器、回调事件
+
+### 导航组件 (7个)
+
+#### 23. `<aithe-menu>` - 菜单
+
+- **模式**: 垂直、水平、内联
+- **特性**: 主题、选中状态、展开控制
+
+#### 24. `<aithe-menu-item>` - 菜单项
+
+- **功能**: 单个菜单项
+- **特性**: 图标、禁用状态、选中状态
+- **备注**: 26.2.3.1 新增 `collapsed` 属性，支持侧边栏折叠模式
+
+#### 25. `<aithe-sub-menu>` - 子菜单
+
+- **功能**: 可展开的子菜单
+- **特性**: 标题、图标、展开状态
+- **备注**: 26.2.3.1 新增 collapsed 模式渲染分支；26.2.3.2 修复 `any` 类型告警
+
+#### 26. `<aithe-breadcrumb>` - 面包屑
+
+- **功能**: 页面层级导航
+- **特性**: 分隔符、最大显示数量
+
+#### 27. `<aithe-breadcrumb-item>` - 面包屑项
+
+- **功能**: 单个面包屑项
+- **特性**: 链接、分隔符、当前项
+
+#### 28. `<aithe-steps>` - 步骤条
+
+- **方向**: 水平、垂直
+- **特性**: 当前步骤、状态、自定义图标
+
+#### 29. `<aithe-back-top>` - 回到顶部
+
+- **功能**: 滚动到页面顶部
+- **特性**: 可见阈值、自定义位置、动画
+
+#### 30. ~~`<aithe-dropdown>` - 下拉菜单~~ *(已迁移至 data 分类)*
+
+### 表单组件 (18个)
+
+#### 31. `<aithe-checkbox>` - 复选框
+
+- **功能**: 单个复选框
+- **特性**: 中间状态、禁用、自定义标签
+
+#### 32. `<aithe-checkbox-group>` - 复选框组
+
+- **功能**: 多个复选框组合
+- **特性**: 方向、最大选择数、全选
+
+#### 33. `<aithe-radio>` - 单选框
+
+- **功能**: 单个单选框
+- **特性**: 禁用状态、自定义标签
+
+#### 34. `<aithe-radio-group>` - 单选框组
+
+- **功能**: 多个单选框组合
+- **特性**: 方向、按钮样式、禁用状态
+
+#### 35. `<aithe-select>` - 选择器
+
+- **模式**: 单选、多选、标签模式
+- **特性**: 搜索、过滤、远程数据、分组
+
+#### 36. `<aithe-switch>` - 开关
+
+- **功能**: 开关切换
+- **特性**: 大小、加载状态、自定义内容
+- **备注**: 26.2.3.2 `type` 属性类型从 `AitheIntent` 改为 `AitheVariant`
+
+#### 37. `<aithe-color-picker>` - 颜色选择器
+
+- **模式**: 简单、高级
+- **特性**: 预设颜色、透明度、格式输出
+
+#### 38. `<aithe-combobox>` - 组合框
+
+- **功能**: 可搜索的下拉框
+- **特性**: 自动完成、远程搜索、多选
+- **备注**: 26.2.3.2 `ComboboxOption.intent` 类型从 `AitheIntent` 改为 `AitheVariant`
+
+#### 39. `<aithe-date-picker>` - 日期选择器
+
+- **类型**: 日期、周、月、年、范围
+- **特性**: 快捷选择、禁用日期、自定义格式
+
+#### 40. `<aithe-time-picker>` - 时间选择器
+
+- **功能**: 时间选择
+- **特性**: 步长、格式、禁用时间
+
+#### 41. `<aithe-slider>` - 滑块
+
+- **类型**: 单滑块、范围滑块
+- **特性**: 步长、标记点、垂直模式
+
+#### 42. `<aithe-rate>` - 评分
+
+- **功能**: 星级评分
+- **特性**: 半星、自定义图标、只读
+
+#### 43. `<aithe-form>` - 表单
+
+- **功能**: 表单容器
+- **特性**: 验证、布局、提交处理
+
+#### 44. `<aithe-form-item>` - 表单项
+
+- **功能**: 表单字段包装器
+- **特性**: 标签、验证信息、布局
+
+#### 45. `<aithe-upload>` - 上传
+
+- **模式**: 点击上传、拖拽上传
+- **特性**: 多文件、限制、预览、自定义请求
+
+#### 46. `<aithe-transfer>` - 穿梭框
+
+- **功能**: 双列表数据转移
+- **特性**: 搜索、分页、自定义渲染
+
+### 反馈组件 (9个)
+
+#### 47. `<aithe-dialog>` - 对话框
+
+- **功能**: 模态对话框
+- **特性**: 标题、内容、操作按钮、关闭控制
+
+#### 48. `<aithe-modal>` - 模态框
+
+- **功能**: 轻量级模态框
+- **特性**: 多种尺寸、全屏、自定义内容
+
+#### 49. `<aithe-drawer>` - 抽屉
+
+- **位置**: 上、下、左、右
+- **特性**: 大小、标题、遮罩、关闭控制
+
+#### 50. `<aithe-tooltip>` - 工具提示
+
+- **位置**: 12 个方向
+- **特性**: 延迟显示、主题、自定义内容
+- **备注**: 26.2.3.2 抽取 `ARIA_DESCRIBED_BY` 常量，消除重复字符串
+
+#### 51. `<aithe-popover>` - 弹出框
+
+- **功能**: 点击触发的弹出内容
+- **特性**: 触发方式、位置、箭头
+
+#### 52. `<aithe-toast>` - 轻提示
+
+- **类型**: 成功、警告、错误、信息
+- **特性**: 自动关闭、位置、自定义持续时间
+
+#### 53. `<aithe-alert>` - 警告提示
+
+- **类型**: 成功、信息、警告、错误
+- **特性**: 可关闭、图标、描述
+
+#### 54. `<aithe-notification>` - 通知提醒框
+
+- **功能**: 全局通知
+- **特性**: 位置、持续时间、自定义按钮
+
+#### 55. `<aithe-loading>` - 加载中
+
+- **类型**: 全屏、容器、内联
+- **特性**: 自定义文本、延迟显示
+
+### 数据展示组件 (12个)
+
+#### 56. `<aithe-table>` - 表格
+
+- **功能**: 数据表格
+- **特性**: 排序、筛选、分页、选择、虚拟滚动
+- **备注**: 26.2.3.2 `col.intent` 类型断言从 `AitheIntent` 改为 `AitheVariant`；26.2.3.15 `col.variant` 属性名统一
+
+#### 57. `<aithe-table-column>` - 表格列
+
+- **功能**: 声明式表格列定义
+- **特性**: 字段映射、排序、对齐、宽度
+- **备注**: 26.2.2.1 新增；26.2.3.2 `intent` 属性类型从 `AitheIntent` 改为 `AitheVariant`；26.2.3.15 `intent` → `variant`
+
+#### 58. `<aithe-tabs>` - 标签页
+
+- **类型**: 线型、卡片型
+- **特性**: 位置、大小、可关闭、懒加载
+
+#### 59. `<aithe-tab-pane>` - 标签页面板
+
+- **功能**: 单个标签页内容
+- **特性**: 禁用、懒加载、图标
+
+#### 60. `<aithe-tree>` - 树形控件
+
+- **功能**: 层级数据展示
+- **特性**: 选择、展开、搜索、拖拽
+
+#### 61. `<aithe-tree-menu>` - 树形菜单
+
+- **功能**: 基于 Tree 数据的菜单导航
+- **特性**: 递归渲染、意图着色、垂直/水平布局
+- **备注**: 26.2.2.1 新增
+
+#### 62. `<aithe-timeline>` - 时间线
+
+- **模式**: 垂直、水平
+- **特性**: 自定义节点、颜色、图标、数据驱动模式
+- **备注**: 26.2.2.1 从 layout 分类迁移至 data 分类
+
+#### 63. `<aithe-timeline-item>` - 时间线项
+
+- **功能**: 单个时间线节点
+- **特性**: 时间、内容、状态
+
+#### 64. `<aithe-pagination>` - 分页
+
+- **功能**: 数据分页
+- **特性**: 大小选择、快速跳转、简洁模式
+
+#### 65. `<aithe-dropdown>` - 下拉菜单 *(26.2.3.15 从 navigation 迁移至 data)*
+
+- **功能**: 下拉菜单容器
+- **特性**: 触发方式、位置、禁用状态
+- **备注**: 26.2.2.2 从 feedback 分类迁移至 navigation 分类；26.2.3.15 从 navigation 迁移至 data 分类，内部委托 `<aithe-tree-menu>` 渲染
+
+#### 66. `<aithe-metrics>` - 指标 *(26.2.3.15 新增)*
+
+- **功能**: 指标展示组件，支持标签和数值展示
+- **特性**: 自定义标签、数值、趋势指示
+
+#### 67. `<aithe-metrics-group>` - 指标组 *(26.2.3.15 新增)*
+
+- **功能**: 分组指标容器
+- **特性**: 水平/垂直排列、分组展示
+
+### 展示组件 (7个)
+
+#### 68. `<aithe-carousel>` - 走马灯
+
+- **功能**: 轮播图
+- **特性**: 自动播放、指示器、箭头、切换效果
+
+#### 69. `<aithe-comparison>` - 对比
+
+- **功能**: 前后对比滑块
+- **特性**: 方向、手柄样式、标签
+
+#### 70. `<aithe-animated-image>` - 动画图片
+
+- **功能**: 带动画的图片显示
+- **特性**: 缩放、平移、加载动画
+
+#### 71. `<aithe-markdown>` - Markdown 渲染
+
+- **功能**: Markdown 内容渲染
+- **特性**: 语法高亮、自定义渲染器
+- **备注**: 26.2.3.12 从 markdown-it 迁移至自研 Markdown 解析引擎
+
+#### 72. `<aithe-code-editor>` - 代码编辑器
+
+- **功能**: 代码显示与编辑组件
+- **特性**: 语法高亮（38 种语言）、行号显示、一键复制、代码折叠
+- **备注**: 26.2.3.12 新增；26.2.3.15 国际化重构，硬编码中文 title 替换为 `t()` 调用
+
+#### 73. `<aithe-markdown-editor>` - Markdown 编辑器
+
+- **功能**: Markdown 编辑与实时预览
+- **特性**: 分屏模式、实时预览
+- **备注**: 26.2.3.12 新增
+
+#### 74. `<aithe-label>` - 标签
+
+- **功能**: 标签展示组件
+- **特性**: filled/outlined 变体、多种颜色、可移除、图标支持
+- **备注**: 26.2.3.12 新增
+
+### 进度组件 (4个)
+
+#### 75. `<aithe-progress-bar>` - 进度条
+
+- **类型**: 线型、环形、仪表盘
+- **特性**: 颜色、条纹动画、自定义文本
+
+#### 73. `<aithe-progress-ring>` - 环形进度条
+
+- **功能**: 环形进度显示
+- **特性**: 大小、宽度、颜色渐变
+
+#### 74. `<aithe-spinner>` - 加载旋转器
+
+- **类型**: 旋转、脉冲、波浪
+- **特性**: 大小、颜色、速度
+
+#### 76. `<aithe-skeleton>` - 骨架屏
+
+### 容器组件 (4个)
+
+#### 77. `<aithe-callout>` - 提示框
+
+- **类型**: 信息、成功、警告、错误
+- **特性**: 图标、标题、可关闭
+
+#### 77. `<aithe-details>` - 详情
+
+- **功能**: 可展开的详情区域
+- **特性**: 摘要、展开状态、禁用
+
+#### 78. `<aithe-scroller>` - 滚动容器
+
+- **功能**: 自定义滚动区域
+- **特性**: 虚拟滚动、懒加载、滚动事件
+
+#### 80. `<aithe-split-panel>` - 分割面板
+
+### 主题组件 (7个)
+
+#### 81. `<aithe-theme-picker>` - 主题选择器
+
+- **功能**: 主题选择器，支持 Light/Dark 分组展示
+- **特性**: 色点预览、键盘导航、`aithe-theme-change` 事件
+- **备注**: 26.2.2.2 新增；26.2.3.15 重构为委托 `<aithe-tree-menu>` 渲染
+
+#### 82. `<aithe-theme-preview>` - 主题预览
+
+- **功能**: 主题预览面板，支持局部预览 + 确认应用全局主题
+- **特性**: 工具栏、预览区、`aithe-theme-apply` 事件
+- **备注**: 26.2.2.2 新增；26.2.3.2 `sidebarItems` 补加 `readonly` 修饰符
+
+#### 83. `<aithe-locale-switch>` - 语言切换
+
+- **功能**: 语言切换器，支持 en-US / zh-CN / zh-TW / zh-HK / ja-JP / ko-KR / es-ES / pt-BR / fr-FR / de-DE 切换
+- **特性**: 浮层下拉、键盘导航、`locales` 属性限定显示语言、`aithe-locale-change` 事件
+- **备注**: 26.2.2.4 新增；26.2.3.5 新增 8 个 locale 支持、`locales` 属性、`localeSwitch` 翻译键、10 种语言标签映射；26.2.3.15 重构为使用 `@styles/i18n` 导出的 `localeMenu`
+
+#### 84. `<aithe-shadow-picker>` - 阴影选择器
+
+- **功能**: 阴影风格选择器，支持 9 种内置阴影风格切换
+- **特性**: 浮层下拉、图标预览、i18n 支持、`placement` 属性控制弹出方向
+- **备注**: 26.2.3.8 新增；26.2.3.15 重构为委托 `<aithe-tree-menu>` 渲染
+
+#### 85. `<aithe-typo-picker>` - 排版风格选择器
+
+- **功能**: 排版风格选择器，支持 4 种内置排版风格切换（minimal/business/luxury/compact）
+- **特性**: 浮层下拉、图标预览、i18n 支持、`placement` 属性控制弹出方向
+- **备注**: 26.2.3.9 新增；26.2.3.15 重构为委托 `<aithe-tree-menu>` 渲染
+
+#### 86. `<aithe-shape-picker>` - 形状风格选择器 *(26.2.3.15 新增)*
+
+- **功能**: 形状风格选择器，支持 8 种内置形状风格切换
+- **特性**: 委托 `<aithe-tree-menu>` 渲染、预览缩略图、键盘导航
+
+#### 87. `<aithe-theme-switch>` - 统一外观切换器 *(26.2.3.15 新增)*
+
+- **功能**: 统一外观切换器组件，一键切换主题/形状/阴影/排版
+- **特性**: 整合 theme-picker、shape-picker、shadow-picker、typo-picker 为一体
+
+## 技术架构
+
+### 核心基类
+
+- **AitheElement**: 所有组件的基类，提供统一的属性、事件和样式管理
+- **主题系统**: 基于 CSS 自定义属性的主题切换机制
+- **工具函数**: DOM 操作、事件处理、验证工具
+
+### 样式系统
+
+- **设计令牌**: 统一的颜色、间距、字体、阴影等设计变量
+- **`--aithe-color-text-on-primary`**: 主色背景上的文字颜色令牌（26.2.3.1 新增）
+- **阴影令牌**: `--aithe-shadow-1` 到 `--aithe-shadow-5` 等阴影风格令牌（26.2.3.8 新增）
+- **代码高亮令牌**: `--aithe-code-*` 语法高亮 CSS 变量系列（26.2.3.12 新增）
+- **响应式**: 基于 CSS 媒体查询的响应式设计
+- **主题切换**: 通过 CSS 类名切换主题
+
+### 构建系统
+
+- **Vite**: 快速的开发服务器和构建工具
+- **TypeScript**: 完整的类型定义支持
+- **Lit 3.x**: 现代 Web Components 开发框架（26.2.3.15 升级至 `^3.3.3`）
+- **tsc-alias**: 构建后自动替换 `.d.ts` 中的别名为相对路径（26.2.3.2 新增）
+- **litExternalPlugin**: Vite 插件将 lit 标记为外部依赖（26.2.3.15 新增）
+
+### 路径别名体系
+
+- **`@base/*`** → `src/base/*`
+- **`@components/*`** → `src/components/*`
+- **`@core/*`** → `src/core/*`
+- **`@styles/*`** → `src/styles/*`
+- **`@types/*`** → `src/types/*`（含裸引用 `@types`）
+- **`@utils/*`** → `src/utils/*`（含裸引用 `@utils`）
+
+### 代码质量工具链
+
+- **ESLint**: 代码静态分析，集成 `typescript-eslint`、`eslint-plugin-lit`、`eslint-plugin-wc`、`eslint-plugin-sonarjs`、`eslint-config-prettier`，使用 flat config 格式
+- **Prettier**: 代码格式化，统一缩进、引号、行宽等风格
+- **npm 脚本**: `lint` / `lint:fix` / `format` / `format:fix`
+
+## 安装和使用
+
+### 安装
+
+```bash
+npm install aithe-ui
+```
+
+### 基本使用
+
+```javascript
+import 'aithe-ui';
+
+// 在 HTML 中使用
+<aithe-button type="primary" size="medium">
+  点击我
+</aithe-button>;
+```
+
+### 主题、形状、阴影设置
+
+```javascript
+import { aitheUI } from 'aithe-ui';
+
+// 设置全局主题
+aitheUI.setTheme('dark');
+
+// 设置形状风格
+aitheUI.setShape('rounded');
+
+// 设置阴影风格
+aitheUI.setShadow('neumorphism');
+```
+
+## 浏览器支持
+
+- Chrome 61+
+- Firefox 63+
+- Safari 10.1+
+- Edge 79+
+- iOS Safari 10.3+
+- Android Chrome 61+
+
+## 性能特点
+
+- **Tree-shaking 支持**: 支持按需导入
+- **零运行时依赖**: 仅依赖 Lit 库
+- **轻量级**: 组件按需加载
+- **服务端渲染友好**: 支持 SSR/SSG
+
+## 后续版本规划
+
+### 26.3.x (2026年第3季度)
+
+- 组件性能优化
+- 新增高级表单组件
+- 单元测试覆盖率提升
+
+### 26.4.x (2026年第4季度)
+
+- 响应式布局增强
+- 动画系统改进
+- 开发者工具集成
+- 主题定制工具
+
+## 许可证
+
+MIT License - Archest 团队