@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/issue/issue_26.2.3.2.md

@@ -0,0 +1,83 @@
+# Issue 26.2.3.2
+
+## 版本信息
+
+- **版本号**: 26.2.3.2
+- **基线版本**: 26.2.3
+- **类型**: 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`，描述从"意图"统一为"变体"
+
+## 破坏性变更
+
+| 变更项 | 旧值 | 新值 |
+|--------|------|------|
+| `AitheIntent` 类型 | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'default'` | 已移除，统一使用 `AitheVariant`（含 `'neutral'` 和 `(string & {})` 扩展） |
+| `AitheTimelineItemMeta.type` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `AitheVariant`（类型更宽泛，新增 `'neutral'` 及字符串扩展） |
+| `global.ts` 路径 | `src/global.ts` | `src/core/global.ts` |
+| `AitheCommonProps` 接口 | `src/types/component.ts` | 已删除（无组件引用） |
+| `src/types/index.ts` 导出 | 含 `export * from './component'` | 移除该行 |
+| 构建命令 | `vite build && tsc -p tsconfig.json --emitDeclarationOnly` | `vite build && tsc -p tsconfig.json --emitDeclarationOnly && tsc-alias` |
+
+## 变更内容
+
+### 新增
+
+- **路径别名体系** — 从 `@/*` 单一通配别名改为按 `src` 二级目录单独建立别名：`@base/*`、`@components/*`、`@core/*`、`@styles/*`、`@types/*`（含裸引用 `@types`）、`@utils/*`（含裸引用 `@utils`），在 `tsconfig.json` 的 `baseUrl` + `paths`、`vite.config.ts`/`vite.demo.config.ts`/`vite.api.config.ts` 的 `resolve.alias` 中同步配置
+- **`tsc-alias` 构建步骤** — 安装 `tsc-alias` 开发依赖，build 命令追加 `tsc-alias`，自动替换 `.d.ts` 中的别名为相对路径，确保 dist 产物无别名残留
+- **`CONTRIBUTING.md` 开发规范文档** — 涵盖导入规范、readonly 修饰符规范、Lit 组件编码规范、SonarQube 合规要求、代码格式规范、文档提交与版本规范、别名构建规范、AI 生成代码要求共八个章节
+- **`.opencode/skills/generate-issue/` skill** — 定义可复用的 issue 文档生成指令，用于代码开发完成后自动比对 git diff 生成本次更新的 issue 文档
+
+### 修改
+
+#### 路径别名替换（87+ 文件）
+
+- **所有组件源文件** — `src/components/` 下 10 个子目录（basic、form、data、navigation、feedback、layout、display、progress、container、theme）共 60+ 组件文件，将 `../../core/`、`../../base/`、`../../styles/`、`../../utils/`、`../../types/` 等相对路径替换为 `@core/*`、`@base/*`、`@styles/*`、`@utils/*`、`@types/*` 别名
+- **核心模块** — `src/core/aithe-element.ts`、`src/core/styles.ts`、`src/core/types.ts`、`src/utils/theme.ts`、`src/utils/index.ts`、`src/base/aithe-element.ts` 内部相对路径替换为别名
+- **主入口** — `src/index.ts` 全部 102 行 `export * from './...'` 替换为 `@components/*`、`@core/*`、`@base/*`、`@styles/*`、`@types/*`、`@utils/*` 别名
+- **应用层** — `src/apps/api/app.ts`、`src/apps/demo/app.ts` 中 `../../src/` 相对路径替换为别名
+
+#### 类型统一（AitheIntent → AitheVariant）
+
+- **`src/core/types.ts`** — 移除 `AitheIntent` 类型定义，4 个接口（`AitheDropdownItem`、`AitheSelectOption`、`AitheTableColumnMeta`、`AitheTreeNodeMeta`）的 `intent` 字段类型从 `AitheIntent` 改为 `AitheVariant`；`AitheTimelineItemMeta.type` 从硬编码联合类型改为 `AitheVariant`；注释从"视觉意图"更新为"视觉变体"
+- **`src/components/form/switch.ts`** — `type` 属性类型从 `AitheIntent` 改为 `AitheVariant`，注释从"颜色意图"更新为"颜色变体"
+- **`src/components/form/combobox.ts`** — `ComboboxOption.intent` 类型从 `AitheIntent` 改为 `AitheVariant`
+- **`src/components/data/table.ts`** — `col.intent` 类型断言从 `AitheIntent` 改为 `AitheVariant`
+- **`src/components/data/table-column.ts`** — `intent` 属性类型从 `AitheIntent` 改为 `AitheVariant`，注释从"视觉意图"更新为"视觉变体"
+
+#### SonarQube 修复
+
+- **`sub-menu.ts` any 类型** — `(item as any).collapsed` 和 `(sm as any).collapsed` 改为 `(item as HTMLElement & { collapsed: boolean }).collapsed`，消除 `any` 类型告警
+- **`input.ts` 重复字符串** — 抽取 `'aithe-input'` 为 `INPUT_EVENT` 常量
+- **`tooltip.ts` 重复字符串** — 抽取 `'aria-describedby'` 为 `ARIA_DESCRIBED_BY` 常量
+- **`theme.ts` 重复字符串** — 抽取 `'aithe-theme-'` 为 `THEME_CLASS_PREFIX` 常量
+- **`theme-preview.ts` readonly** — `sidebarItems` 属性补加 `readonly` 修饰符
+
+#### 文档更新
+
+- **`docs/guide.md`** — 数据项通用字段章节：`AitheIntent` → `AitheVariant`，"意图字段" → "变体字段"
+- **`docs/api/navigation/dropdown.md`** — items 属性和 intent 字段类型引用 `AitheIntent` → `AitheVariant`，描述"视觉意图" → "视觉变体"
+- **`docs/api/form/select.md`** — options 属性和 intent 字段类型引用及描述更新
+- **`docs/api/form/combobox.md`** — options 属性和 intent 字段类型引用及描述更新
+- **`docs/api/form/switch.md`** — type 属性类型 `AitheIntent` → `AitheVariant`，描述"颜色意图" → "颜色变体"
+- **`docs/api/data/tree.md`** — data 属性和 intent 字段类型引用及描述更新
+- **`docs/api/data/tree-menu.md`** — intent 字段类型引用及描述更新
+- **`docs/api/data/table.md`** — intent 字段类型引用及描述更新
+- **`docs/api/data/table-column.md`** — intent 属性类型引用及描述更新
+- **`docs/issue/issue_26.2.2.1.md`** — 变更说明中 `AitheIntent 类型` → `AitheVariant 类型`
+
+### 删除
+
+- **`src/global.ts`** — 迁移至 `src/core/global.ts`，原文件移除
+- **`src/types/component.ts`** — `AitheCommonProps` 接口无任何组件引用，文件移除；`src/types/index.ts` 中 `export * from './component'` 同步移除

package/docs/issue/issue_26.2.3.3.md

@@ -0,0 +1,131 @@
+# Issue 26.2.3.3
+
+## 版本信息
+
+- **版本号**: 26.2.3.3
+- **基线版本**: 26.2.3
+- **类型**: Feature
+- **日期**: 2026-05-17
+
+## 变更概述
+
+1. 新增 Framework 组件分类（4 个组件）：`aithe-header`、`aithe-body`、`aithe-sidebar`、`aithe-page`，提供企业级应用框架布局
+2. 新增轻量前端路由模块 `Router`（`src/core/router/`），支持 history/hash 模式、路由守卫、动态路由
+3. 新增布局密度管理模块（`src/core/layout/`），支持 compact/medium/wide 三种密度，全局切换与持久化
+4. `aithe-button` 新增 `href`/`target` 属性，支持链接按钮模式，渲染为 `<a>` 元素
+5. 事件系统重构：`emitAitheEvent` 返回值从 `void` 改为 `boolean`，`cancelable` 从 `false` 改为 `true`
+6. `aithe-theme-picker` 的 `value` 类型从 `AitheBuiltinTheme | string` 改为 `AitheThemeName`，新增 `preventDefault()` 支持
+7. `aithe-locale-switch` 新增 `aithe-locale-change` 事件，支持 `getAitheLocales()` 动态获取已注册 locale
+8. i18n 类型扩展：`AitheLocale` 从 `'en-US' | 'zh-CN'` 改为 `AitheBuiltinLocale | (string & {})`，新增 7 个翻译 key
+9. `global.ts` 新增 `setAitheLayout`/`getAitheLayout` 函数
+10. SonarQube 合规修复：`window` → `globalThis`、`forEach` → `for...of`、`@query`/`@queryAssignedElements` 属性加 `readonly`
+11. 删除 `aithe-page-container` 和 `aithe-page`（layout 分类），迁移至 framework 分类
+12. API Demo / API 应用重构为使用 framework 组件（`aithe-header` + `aithe-body`）
+13. 文档包名统一为 `@aithe/aithe-ui`，新增 Framework 分类 API 文档
+
+## 破坏性变更
+
+| 变更项                                | 旧值                                                                | 新值                                                                  |
+| ------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `emitAitheEvent` 返回值               | `void`                                                              | `boolean`（`dispatchEvent` 的返回值）                                 |
+| `emitAitheEvent` 的 `cancelable`      | `false`                                                             | `true`                                                                |
+| `AitheElement.emit` 返回值            | `void`                                                              | `boolean`                                                             |
+| `aithe-theme-picker` 的 `value` 类型  | `AitheBuiltinTheme \| string`                                       | `AitheThemeName`                                                      |
+| `aithe-theme-picker` 内置主题切换行为 | 自动调用 `setGlobalTheme`                                           | 需 `preventDefault()` 阻止后自行处理；不阻止时仍自动切换              |
+| `AitheLocale` 类型                    | `'en-US' \| 'zh-CN'`                                                | `AitheBuiltinLocale \| (string & {})`                                 |
+| `aithe-page-container` 组件           | `src/components/layout/page-container.ts`                           | 已删除，功能由 `aithe-body` 替代                                      |
+| `aithe-page` 组件（layout 分类）      | `src/components/layout/page.ts`                                     | 已删除，迁移至 `src/components/framework/page.ts`（路由容器）         |
+| `loadStoredLocale` 返回值             | `AitheLocale \| null`                                               | `AitheLocale \| undefined`                                            |
+| `src/index.ts` 导出                   | 含 `@components/layout/page-container` 和 `@components/layout/page` | 移除上述两项，新增 `@components/framework/*`（4 项）和 `@core/router` |
+
+## 变更内容
+
+### 新增
+
+- **Framework 组件分类** — `src/components/framework/` 目录，包含 4 个企业级应用框架组件：
+  - **`aithe-header`** — 顶部导航栏，支持品牌区（brand/slogan）、导航区（center 插槽）、国际化/主题切换开关、用户区（right 插槽），sticky 定位 + 毛玻璃背景
+  - **`aithe-body`** — 主内容区域，支持布局密度控制（compact/medium/wide 切换按钮）、浮动操作栏（show-actions）、返回顶部按钮，集成 `setAitheLayout`/`getAitheLayout`
+  - **`aithe-sidebar`** — 可折叠侧边栏，支持品牌图标/文字、菜单树（items-json 属性）、折叠/展开、active 高亮、路由导航，688 行完整实现
+  - **`aithe-page`** — 路由容器，连接 `Router` 实例，监听路由变更并动态渲染匹配的页面组件，支持 404 回退
+- **路由模块** — `src/core/router/index.ts`（313 行），提供 `Router` 类，支持 history/hash 模式、动态路由（`:param`）、通配符（`*`）、路由守卫（`addGuard`）、编程式导航（`navigate`/`replace`/`back`/`forward`）、路由元数据（`meta`）、变更订阅（`onChange`）
+- **布局密度模块** — `src/core/layout/index.ts`（104 行），提供 `AitheLayoutName` 类型（`'compact' | 'medium' | 'wide'`）、`initAitheLayout`、`setAitheLayout`、`getAitheLayout`、`onAitheLayoutChange`，通过 `data-aithe-layout` 属性设置在 `<html>` 上，支持 localStorage 持久化
+- **布局类型定义** — `src/types/layout.ts`，导出 `AitheLayoutName` 类型
+- **`aithe-button` 链接模式** — 新增 `href`（`string`）和 `target`（`string`）属性；设置 `href` 后渲染为 `<a>` 元素，默认执行导航，`aithe-click` 事件中调用 `preventDefault()` 可阻止
+- **`aithe-locale-switch` 事件** — 新增 `aithe-locale-change` 事件，选择语言时发出 `{ locale }`，支持 `preventDefault()` 阻止内置切换逻辑
+- **`getAitheLocales` 函数** — `src/core/i18n/index.ts` 新增，返回所有已注册 locale 标识列表
+- **`AitheBuiltinLocale` 类型** — `'en-US' | 'zh-CN'`，`AitheLocale` 改为 `AitheBuiltinLocale | (string & {})` 支持扩展
+- **i18n 翻译 key** — 新增 7 个：`body.backTop`、`body.switchLayout`、`body.layout.compact`、`body.layout.medium`、`body.layout.wide`、`sidebar.collapse`、`sidebar.expand`
+- **`setAitheLayout`/`getAitheLayout` 全局函数** — `src/core/global.ts` 新增，封装布局密度切换和读取
+- **Framework API 文档** — `docs/api/framework/` 目录，包含 `header.md`、`body.md`、`sidebar.md`、`page.md`
+- **`.opencode/skills/review-and-sync/` skill** — 定义可复用的代码审查与文档同步指令
+
+### 修改
+
+#### 事件系统重构
+
+- **`src/utils/events.ts`** — `emitAitheEvent` 返回值从 `void` 改为 `boolean`（返回 `dispatchEvent` 结果），`cancelable` 从 `false` 改为 `true`
+- **`src/base/aithe-element.ts`** — `emit` 方法返回值从 `void` 改为 `boolean`，透传 `emitAitheEvent` 返回值
+
+#### 组件功能增强
+
+- **`aithe-theme-picker`** — `value` 属性类型从 `AitheBuiltinTheme | string` 改为 `AitheThemeName`；`toggleOpen` 逻辑修正（open 时 bindViewport，close 时 unbindViewport）；选择主题时通过 `emit` 返回值判断是否执行 `setGlobalTheme`，支持 `preventDefault()` 阻止；`@query` 属性补加 `readonly`
+- **`aithe-locale-switch`** — 选项列表从硬编码 `LOCALE_OPTIONS` 改为动态 `getLocaleOptions()`（基于 `getAitheLocales()`）；内置 locale 显示名称映射抽取为 `BUILTIN_LOCALE_LABELS`；`handleSelect` 新增 `aithe-locale-change` 事件，支持 `preventDefault()`
+- **`aithe-theme-preview`** — `handleThemeChange` 中调用 `event.preventDefault()` 阻止 `aithe-theme-picker` 的内置主题切换，改为自行管理 `previewTheme`
+
+#### i18n 扩展
+
+- **`src/core/i18n/index.ts`** — `AitheLocale` 类型扩展为 `AitheBuiltinLocale | (string & {})`；`loadStoredLocale` 返回值从 `null` 改为 `undefined`；`t()` 函数优化：当前 locale 无资源包时直接回退 en-US，不再创建空对象；新增 `getAitheLocales()` 函数
+- **`src/core/i18n/locales/en-US.ts`** — 新增 7 个翻译 key（body/sidebar 相关）
+- **`src/core/i18n/locales/zh-CN.ts`** — 新增 7 个翻译 key（body/sidebar 相关）
+
+#### 全局函数
+
+- **`src/core/global.ts`** — `initializeAitheUI` 末尾新增 `initAitheLayout('medium')` 调用；新增 `setAitheLayout` 和 `getAitheLayout` 导出函数；导入 `AitheLayoutName` 类型和 `@core/layout` 模块
+
+#### SonarQube 合规修复
+
+- **`window` → `globalThis`** — `affix.ts`（2 处）、`back-top.ts`（1 处）、`carousel.ts`（3 处）、`body.ts`（4 处）、`sidebar.ts`（1 处）；`affix.ts`/`back-top.ts` 的 `resolveTarget` 回退值从 `window` 改为 `globalThis.window` 以保持 `HTMLElement | Window` 类型兼容
+- **`forEach` → `for...of`** — `carousel.ts`（`slides.entries()`）、`collapse.ts`（`this.items.entries()`）、`breadcrumb.ts`（`breadcrumbItems.entries()`）、`checkbox-group.ts`、`router/index.ts`（3 处）、`layout/index.ts`
+- **`@query`/`@queryAssignedElements` 属性加 `readonly`** — `card.ts`（2 处）、`details.ts`、`drawer.ts`（3 处）、`checkbox.ts`、`checkbox-group.ts`、`breadcrumb.ts`、`dropdown.ts`、`theme-picker.ts`（2 处）、`docs-viewer.ts`、`editor.ts`
+- **`page.ts`（framework）** — 移除未使用的 `nothing`、`RouteConfig`、`t` 导入
+- **`sidebar.ts`（framework）** — `renderIcon`/`renderTopIcon` 返回类型统一为 `TemplateResult`（`nothing` → `html``），嵌套三元表达式提取为 `renderTopIcon` 方法
+
+#### 导出更新
+
+- **`src/index.ts`** — 移除 `@components/layout/page-container` 和 `@components/layout/page` 导出，新增 `@components/framework/header`、`@components/framework/body`、`@components/framework/sidebar`、`@components/framework/page`、`@core/router` 导出
+- **`src/types/index.ts`** — 新增 `./layout` 导出
+
+#### 应用层重构
+
+- **`src/apps/api/app.ts`** — 移除手写 topbar 样式和逻辑，改用 `aithe-header` + `aithe-body` 框架组件；移除 `localeVersion` 状态，改用 `requestUpdate()`；移除 `theme` 状态和 `changeTheme` 方法（由 `aithe-theme-picker` 内部处理）
+- **`src/apps/demo/app.ts`** — 同上重构，移除手写 topbar，改用 `aithe-header` + `aithe-body`；移除 `localeVersion`/`theme` 状态
+- **`src/apps/api/docs-viewer.ts`** — `handleContentClick` 补加 `readonly`；`demoPreview` 补加 `readonly`；路由映射新增 `framework` 分类和 `theme` 分类；key 前缀映射优化（`keyPrefixMap`）；移除 `void this.localeVersion`
+- **`src/apps/api/demo-data.ts`** — 移除 `layout-page-container` 和 `layout-page` demo，新增 `framework-sidebar` demo
+- **`src/apps/api/pages/docs.ts`** — 移除 `page-container`/`page` 文档导入，新增 `framework/` 下 4 个文档导入；新增 Framework 分类
+- **`src/apps/demo/pages/layout.ts`** — 移除 `pageContainer` demo，新增 `header` demo
+- **`src/apps/api/i18n/en-US.ts`** — 新增 `api.category.framework` 和 4 个 framework 组件名翻译
+- **`src/apps/api/i18n/zh-CN.ts`** — 同上
+- **`src/apps/demo/i18n/en-US.ts`** — 新增 `demo.layout.header.title`/`description`
+- **`src/apps/demo/i18n/zh-CN.ts`** — 同上
+
+#### 文档更新
+
+- **`README.md`** — 组件数 79→81；版本 26.2.2→26.2.3；Layout 10→8；新增 Framework 分类(4)；i18n 描述更新为可扩展；项目结构更新（core 新增 layout/router，components 新增 framework/，global.ts 新增 setAitheLayout/getAitheLayout）
+- **`docs/quickstart.md`** — 包名 `aithe-ui` → `@aithe/aithe-ui`（7 处）；组件数 79→81
+- **`docs/theming.md`** — 包名 `aithe-ui` → `@aithe/aithe-ui`（2 处）
+- **`docs/guide.md`** — 包名 `aithe-ui` → `@aithe/aithe-ui`（6 处）；新增布局密度章节、路由章节
+- **`docs/framework-integration.md`** — 包名 `aithe-ui` → `@aithe/aithe-ui`（17 处）；新增路由集成章节（React/Vue/Angular/Svelte）；SSR 示例 `window` → `globalThis`
+- **`docs/api/basic/button.md`** — 新增 `href`/`target` 属性文档；事件表新增 Cancelable 列；新增链接按钮和自定义点击处理示例
+- **`docs/api/theme/theme-picker.md`** — `value` 类型更新为 `AitheThemeName`；新增 `preventDefault()` 说明
+- **`docs/api/theme/locale-switch.md`** — 新增 `aithe-locale-change` 事件文档
+- **`docs/api/summary.md`** — 新增 Framework 分类（4 个组件）；新增 Theme 分类（3 个组件）；Layout 分类移除 page-container 和 page
+- **`docs/api/framework/sidebar.md`** — `items` 属性名修正为 `items-json`
+- **`docs/api/framework/page.md`** — 事件表补充 Cancelable 列
+- **`CONTRIBUTING.md`** — SonarQube 规则新增第 7-11 条（S4325、S3735、S7735、S7764、S7891）
+
+### 删除
+
+- **`src/components/layout/page-container.ts`** — 功能由 `aithe-body` 替代，文件移除
+- **`src/components/layout/page.ts`** — 迁移至 `src/components/framework/page.ts`（语义从"页面布局"变为"路由容器"），原文件移除
+- **`docs/api/layout/page-container.md`** — 对应 API 文档移除
+- **`docs/api/layout/page.md`** — 对应 API 文档移除（framework/page.md 替代）

package/docs/issue/issue_26.2.3.4.md

@@ -0,0 +1,24 @@
+# Issue 26.2.3.4
+
+## 版本信息
+
+- **版本号**: 26.2.3.4
+- **基线版本**: 26.2.3
+- **类型**: Feature
+- **日期**: 2026-05-18
+
+## 变更概述
+
+1. 新增 Admin 应用独立构建配置 `vite.admin.config.ts`，构建产物输出至 `dist/apps/admin/`，包含 `index.html` 和 `aithe-admin.js`
+2. `package.json` 新增 `build:admin` 构建脚本
+
+## 破坏性变更
+
+无。
+
+## 变更内容
+
+### 新增
+
+- **`vite.admin.config.ts`** — Admin 应用独立构建配置，参照 `vite.api.config.ts` / `vite.demo.config.ts` 模式：entry 指向 `src/apps/admin/standalone.ts`，IIFE 格式输出 `aithe-admin.js`，通过 `aithe-admin-html` 插件在 `generateBundle` 钩子中手动发射 `index.html`，输出目录 `dist/apps/admin`
+- **`build:admin` 脚本** — `package.json` 新增 `"build:admin": "vite build --config vite.admin.config.ts"`

package/docs/issue/issue_26.2.3.5.md

@@ -0,0 +1,54 @@
+# Issue 26.2.3.5
+
+## 版本信息
+
+- **版本号**: 26.2.3.5
+- **基线版本**: 26.2.3
+- **类型**: 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 文档
+
+## 破坏性变更
+
+无。
+
+## 变更内容
+
+### 新增
+
+- **`src/core/i18n/locales/zh-TW.ts`** — 繁體中文（台灣）core 层翻译
+- **`src/core/i18n/locales/zh-HK.ts`** — 繁體中文（香港）core 层翻译
+- **`src/core/i18n/locales/ja-JP.ts`** — 日本語 core 层翻译
+- **`src/core/i18n/locales/ko-KR.ts`** — 한국어 core 层翻译
+- **`src/core/i18n/locales/es-ES.ts`** — Español core 层翻译
+- **`src/core/i18n/locales/pt-BR.ts`** — Português Brasileiro core 层翻译
+- **`src/core/i18n/locales/fr-FR.ts`** — Français core 层翻译
+- **`src/core/i18n/locales/de-DE.ts`** — Deutsch core 层翻译
+- **`src/apps/admin/i18n/zh-TW.ts`** 等 8 个文件 — admin 应用层翻译
+- **`src/apps/demo/i18n/zh-TW.ts`** 等 8 个文件 — demo 应用层翻译
+- **`src/apps/api/i18n/zh-TW.ts`** 等 8 个文件 — api 应用层翻译
+- **`AitheBuiltinLocale` 类型扩展** — 新增 `'zh-TW' | 'zh-HK' | 'ja-JP' | 'ko-KR' | 'es-ES' | 'pt-BR' | 'fr-FR' | 'de-DE'` 联合成员
+- **`AitheTranslationKeys.localeSwitch`** — 新增 localeSwitch 翻译键，用于语言切换器自身标签的国际化
+- **`aithe-locale-switch` 的 `locales` 属性** — JSON 数组字符串，限定下拉菜单中显示的语言子集，为空时显示所有已注册语言
+
+### 修改
+
+- **`src/core/i18n/locales/index.ts`** — 导出 8 个新 locale 模块
+- **`src/core/i18n/index.ts`** — 扩展 `AitheBuiltinLocale` 类型、新增 `localeSwitch` 翻译键、导出新 locale
+- **`src/core/i18n/locales/en-US.ts`** — 新增 `localeSwitch` 翻译条目
+- **`src/core/i18n/locales/zh-CN.ts`** — 新增 `localeSwitch` 翻译条目
+- **`src/core/global.ts`** — 注册 8 个新 locale 到 i18n 注册表
+- **`src/components/theme/locale-switch.ts`** — `BUILTIN_LOCALE_LABELS` 新增 10 种语言标签映射；新增 `locales` 属性支持限定显示语言子集
+- **`src/apps/admin/i18n/index.ts`** — 注册 8 个新 admin 翻译
+- **`src/apps/demo/i18n/index.ts`** — 注册 8 个新 demo 翻译
+- **`src/apps/api/i18n/index.ts`** — 注册 8 个新 api 翻译
+- **`docs/i18n.md`** — 更新 locale 列表、类型定义、示例代码、文件组织结构、`locales` 属性用法
+- **`docs/api/theme/locale-switch.md`** — 更新支持语言表格、新增 `locales` 属性文档和限定语言示例

package/docs/issue/issue_26.2.3.6.md

@@ -0,0 +1,84 @@
+# Issue 26.2.3.6
+
+## 版本信息
+
+- **版本号**: 26.2.3.6
+- **基线版本**: 26.2.3
+- **类型**: Feature
+- **日期**: 2026-05-19
+
+## 变更概述
+
+1. Admin 应用集成 DataHub 数据中间层，菜单、仪表盘、登录均通过 DataHub 获取数据，开发阶段使用 Mock 模式
+2. `t()` 函数签名变更：新增 `defaultValue` 参数，支持翻译缺失时返回缺省值
+3. 新增 `translateNodeLabel()` 函数，统一翻译 `AitheTreeNodeMeta` 节点标签
+4. `AitheDropdownItem` 类型标记为 `@deprecated`，统一使用 `AitheTreeNodeMeta`
+5. `AitheTreeNodeMeta` 新增 `divider`、`shortcut`、`i18n` 字段及索引签名
+6. `aithe-dropdown`、`aithe-sidebar`、`aithe-tree`、`aithe-tree-menu` 组件新增 i18n 支持，标签自动翻译
+7. Admin / API / Demo 应用中对核心库的相对路径引入统一替换为 `@core` 别名引入
+8. 新增 DataHub 独立开发指南文档，更新 guide.md 和 quickstart.md
+
+## 破坏性变更
+
+| 变更项                                                    | 旧值                                         | 新值                                                                |
+| --------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------- |
+| `t()` 函数签名                                            | `t(key: string, ...args: unknown[]): string` | `t(key: string, defaultValue?: string, ...args: unknown[]): string` |
+| `AitheDropdownItem`                                       | 独立接口定义                                 | `type AitheDropdownItem = AitheTreeNodeMeta`（标记 @deprecated）    |
+| `aithe-dropdown` 的 `items` 属性类型                      | `AitheDropdownItem[]`                        | `AitheTreeNodeMeta[]`                                               |
+| Admin `login()` 函数                                      | `store/auth.ts` 中导出                       | 已移除，登录逻辑迁移至 DataHub API 层                               |
+| Admin `MenuItem` / `getMenuData()` / `toAitheTreeItems()` | `store/menu.ts` 中导出                       | 已删除，菜单数据通过 DataHub 获取                                   |
+
+## 变更内容
+
+### 新增
+
+- **`src/apps/admin/datahub/index.ts`** — Admin 应用 DataHub 初始化与领域 API 注册入口
+- **`src/apps/admin/datahub/auth.ts`** — 认证领域 API 定义（LoginData 类型、login 接口）
+- **`src/apps/admin/datahub/dashboard.ts`** — 仪表盘领域 API 定义（DashboardStats 类型、getDashboardStats 接口）
+- **`src/apps/admin/datahub/menu.ts`** — 菜单领域 API 定义（getMenuData 接口）
+- **`src/apps/admin/datahub/mock/auth.ts`** — 认证 Mock 数据
+- **`src/apps/admin/datahub/mock/dashboard.ts`** — 仪表盘 Mock 数据
+- **`src/apps/admin/datahub/mock/menu.ts`** — 菜单 Mock 数据
+- **`translateNodeLabel()` 函数** — 翻译 AitheTreeNodeMeta 节点标签，i18n 字段有效时使用 t(i18n, label) 翻译，否则直接返回 label
+- **`AitheTreeNodeMeta.divider` 字段** — 是否在此项前渲染分割线（用于下拉菜单）
+- **`AitheTreeNodeMeta.shortcut` 字段** — 键盘快捷键提示文本（用于下拉菜单）
+- **`AitheTreeNodeMeta` 索引签名** — `[key: string]: unknown`，允许业务层传递自定义参数
+- **`AitheSelectOption` 索引签名** — `[key: string]: unknown`，允许业务层传递自定义参数
+- **`AitheTimelineItemMeta` 索引签名** — `[key: string]: unknown`，允许业务层传递自定义参数
+- **`docs/datahub.md`** — DataHub 独立开发指南文档
+
+### 修改
+
+- **`t()` 函数** — 新增 `defaultValue` 参数；key 为空时返回 defaultValue 或空字符串；翻译缺失时优先返回 defaultValue
+- **`AitheDropdownItem` 类型** — 标记 `@deprecated`，改为 `AitheTreeNodeMeta` 类型别名
+- **`aithe-dropdown`** — items 属性类型改为 `AitheTreeNodeMeta[]`；标签渲染使用 `translateNodeLabel()`；新增 locale 变更订阅自动刷新
+- **`aithe-sidebar`** — 标签渲染使用 `translateNodeLabel()` 替代 `item.label`；新增 locale 变更订阅自动刷新
+- **`aithe-tree`** — 标签渲染使用 `translateNodeLabel()` 替代 `node.label`；新增 locale 变更订阅自动刷新
+- **`aithe-tree-menu`** — 标签渲染使用 `translateNodeLabel()` 替代 `item.label`；新增 locale 变更订阅自动刷新
+- **`aithe-form-item`** — `t()` 调用适配新签名，传入 defaultValue 参数
+- **`aithe-rate`** — `t()` 调用适配新签名，传入 defaultValue 参数
+- **`src/apps/admin/app.ts`** — 引入路径 `../../core/global` → `@core/global`；新增 DataHub 初始化和 API 注册调用
+- **`src/apps/admin/components/admin-layout.ts`** — 菜单数据改用 DataHub 异步获取；`MenuItem` → `AitheTreeNodeMeta`；`item.key` → `item.id`；`item.titleKey` → `item.i18n`；移除 `toAitheTreeItems` 转换
+- **`src/apps/admin/pages/dashboard-page.ts`** — 仪表盘数据改用 DataHub 异步获取；新增 loading / error 状态；订阅 DataHub loading 变更
+- **`src/apps/admin/pages/login-page.ts`** — 登录逻辑改用 DataHub API；移除 `login()` 函数调用
+- **`src/apps/admin/store/auth.ts`** — 移除 `LoginParams`、`LoginResult` 类型和 `login()` 函数；新增 `setToken`、`setUser` 导出
+- **`src/apps/api/app.ts`** — 引入路径 `../../core/global` → `@core/global`、`../../core/i18n` → `@core/i18n`
+- **`src/apps/demo/app.ts`** — 引入路径 `../../core/global` → `@core/global`、`../../core/i18n` → `@core/i18n`
+- **`src/apps/api/docs-viewer.ts`** — 引入路径 `../../core/i18n` → `@core/i18n`
+- **`src/apps/demo/editor.ts`** — 引入路径 `../../core/i18n` → `@core/i18n`
+- **`src/apps/demo/pages/*.ts`**（9 个文件）— 引入路径 `../../../core/i18n` → `@core/i18n`
+- **`src/apps/api/pages/docs.ts`** — 引入路径 `../../../core/i18n` → `@core/i18n`
+- **`src/apps/*/i18n/index.ts`**（3 个文件）— 引入路径 `../../../core/i18n` → `@core/i18n`
+- **`src/apps/*/i18n/{locale}.ts`**（30 个文件）— 引入路径 `../../../core/i18n` → `@core/i18n`
+- **`src/index.ts`** — 新增 `export * from '@core/datahub'`
+- **`docs/guide.md`** — 新增 DataHub 数据中间层章节及"下一步"链接
+- **`docs/quickstart.md`** — 新增第 8 步"使用 DataHub 数据中间层"及"下一步"链接
+- **`docs/i18n.md`** — 更新 t() 函数签名文档、新增 translateNodeLabel 文档、新增 AitheTreeNodeMeta i18n 字段文档
+- **`docs/api/data/tree.md`** — 新增 i18n 字段和示例
+- **`docs/api/data/tree-menu.md`** — 新增 i18n 字段和示例
+- **`docs/api/framework/sidebar.md`** — 新增 i18n 字段和示例
+- **`docs/api/navigation/dropdown.md`** — 新增 i18n 字段和示例
+
+### 删除
+
+- **`src/apps/admin/store/menu.ts`** — 移除 `MenuItem` 接口、`getMenuData()` 函数、`toAitheTreeItems()` 函数，功能迁移至 DataHub

package/docs/issue/issue_26.2.3.7.md

@@ -0,0 +1,61 @@
+# Issue 26.2.3.7
+
+## 版本信息
+
+- **版本号**: 26.2.3.7
+- **基线版本**: 26.2.3
+- **类型**: Feature
+- **日期**: 2026-05-19
+
+## 变更概述
+
+1. 新增 Shape 形状风格体系，与颜色主题（Theme）正交设计，支持 8 种内置形状风格自由组合
+2. 实现双轨圆角 Token 体系（`--aithe-radius-*` 控件 + `--aithe-container-radius-*` 容器），Pill/Circle/Organic 极端形状仅对控件生效，容器使用保守值
+3. 新增 `aithe-shape-picker` 形状选择器组件，支持预览缩略图、键盘导航和内置形状切换
+4. `aithe-theme-preview` 集成形状选择器，预览区局部生效，点击"应用主题"同时将主题和形状应用到全局
+5. 20+ 容器类组件 radius 变量从 `--aithe-radius-*` 迁移至 `--aithe-container-radius-*`
+6. 导出全局方法 `setAitheShape` / `getAitheShape` / `onAitheShapeChange` / `getShapeTokens`
+7. 更新 theming.md、quickstart.md、guide.md 文档，补充形状风格章节
+
+## 破坏性变更
+
+无。
+
+## 变更内容
+
+### 新增
+
+- **`src/types/shape.ts`** — `AitheBuiltinShape`（8 种）和 `AitheShapeName` 类型定义
+- **`src/core/shape/index.ts`** — Shape 核心模块，含双轨 token 映射（`--aithe-radius-*` + `--aithe-container-radius-*`），Organic 容器使用不对称 px 值
+- **`src/components/theme/shape-picker.ts`** — `aithe-shape-picker` 组件，支持 `value` 受控属性和 `placement` 属性，overlay 使用 `--aithe-container-radius-lg`
+- **`docs/api/theme/shape-picker.md`** — shape-picker 组件 API 文档
+
+### 修改
+
+- **`src/types/index.ts`** — 导出 shape.ts
+- **`src/core/global.ts`** — 新增 `setAitheShape`、`getAitheShape`、`getAitheShapes`、`getShapeTokens`、`onAitheShapeChange` 全局方法；`initializeAitheUI` 中初始化 shape（默认 `rounded`）
+- **`src/index.ts`** — 导出 shape-picker
+- **`src/styles/global.css.ts`** — `:root` 新增 `--aithe-container-radius-*` 默认值
+- **`src/styles/mixins.ts`** — 从 `:host` 移除 radius 变量；`aitheSurfaceStyles` 改用 `--aithe-container-radius-lg`
+- **`src/core/i18n/index.ts`** — 新增 `shapePicker` 翻译键类型
+- **10 个 core i18n locale 文件** — 新增 `shapePicker` 翻译键
+- **10 个 api i18n 文件** — 新增 `api.theme.shapePicker` 翻译键
+- **`src/components/theme/theme-preview.ts`** — 工具栏新增 shape-picker；shape 隔离机制（通过 `this.style.setProperty` 应用到 `:host`）；点击"应用主题"同时调用 `setAitheShape()` 应用到全局；`previewShape` 初始值从 `getAitheShape()` 获取；shape-picker 绑定 `.value`
+- **`src/components/theme/theme-picker.ts`** — `.overlay` 改为 `--aithe-container-radius-lg`
+- **`src/components/theme/locale-switch.ts`** — `.overlay` 改为 `--aithe-container-radius-lg`
+- **20+ 容器类组件** — radius 变量从 `--aithe-radius-*` 改为 `--aithe-container-radius-*`：card、avatar(.square)、details、callout、scroller、split-panel、tooltip、toast、notification、alert、dropdown(.submenu)、sub-menu(.children horizontal)、table、tree-menu(.children)、carousel、comparison、animated-image、markdown(pre)、collapse-item、transfer(.panel)、combobox(.panel)、skeleton
+- **`src/apps/demo/pages/theme.ts`** — 新增 shape-picker 示例
+- **`src/apps/demo/editor.ts`** — 容器 radius 改为 `--aithe-container-radius-*`
+- **`src/apps/demo/app.ts`** — 容器 radius 改为 `--aithe-container-radius-*`
+- **`src/apps/api/docs-viewer.ts`** — 容器 radius 改为 `--aithe-container-radius-*`
+- **`src/apps/api/demo-data.ts`** — 新增 `theme-shape-picker` demo 数据
+- **`src/apps/api/pages/docs.ts`** — 新增 shape-picker 文档条目
+- **`docs/api/summary.md`** — 新增 shape-picker 条目；Theme 分类描述更新为"主题与外观组件"，补充 Theme × Shape 正交设计说明；Navigation 分类补充 Dropdown 条目
+- **`docs/api/theme/theme-preview.md`** — 重写描述，明确主题和形状预览均为局部生效，点击"应用主题"同时应用到全局；新增 Behavior 章节；更新示例
+- **`docs/theming.md`** — 新增"形状风格（Shape）"章节（内置形状风格表、切换 API、双轨圆角 Token 体系说明）；圆角变量部分补充 `--aithe-container-radius-*`
+- **`docs/quickstart.md`** — 新增第 5 步"切换形状风格"；完整示例加入 `setAitheShape`；更新"下一步"链接
+- **`docs/guide.md`** — 新增"形状风格（Shape Style）"章节（内置形状风格表、切换 API、订阅变更、双轨 Token、初始化、CSS 变量）；事件表新增 `aithe-shape-change`；更新"下一步"链接
+
+### 删除
+
+无。

package/docs/issue/issue_26.2.3.8.md

@@ -0,0 +1,90 @@
+# Issue 26.2.3.8
+
+## 版本信息
+
+- **版本号**: 26.2.3.8
+- **基线版本**: 26.2.3
+- **类型**: Refactor
+- **日期**: 2026-05-20
+
+## 变更概述
+
+1. **Shadow 阴影风格系统** — 新增 9 种内置阴影风格，支持独立切换
+2. **Shadow Picker 组件** — 新增 `<aithe-shadow-picker>` 阴影风格选择器组件
+3. 删除 `src/core/global.ts` 统一初始化模块，简化为 `src/styles/aithe-ui.ts` 中的 `aitheUI` 单例
+4. 重构 i18n 模块路径： `@core/i18n` 移动到 `@styles/i18n`
+5. 统一外部 API 命名规范，推荐使用 `aitheUI` 实例方法替代独立函数
+6. 优化文档，移除已过时的 `initializeAitheUI` 说明和 `translateNodeLabel` API 文档
+7. 清理代码中的旧版 locale 值兼容逻辑
+
+## 破坏性变更
+
+| 变更项 | 旧值 | 新值 |
+|--------|------|------|
+| 初始化方式 | `import { initializeAitheUI } from '@aithe/aithe-ui'; initializeAitheUI();` | 已删除，直接使用预初始化的 `aitheUI` 单例 |
+| i18n 导入路径 | `import { t, onAitheLocaleChange } from '@core/i18n';` | `import { t, onAitheLocaleChange } from '@styles/i18n';` |
+| 翻译函数调用 | `t('key')` / `import { t } from '@aithe/aithe-ui';` | 推荐 `aitheUI.t('key')` / `import { aitheUI } from '@aithe/aithe-ui';` |
+| 语言切换 | `import { setAitheLocale, getAitheLocale } from '@aithe/aithe-ui'; setAitheLocale('zh-CN');` | `aitheUI.setLocale('zh-CN')` |
+| 语言订阅 | `onAitheLocaleChange(fn)` | `aitheUI.onLocaleChange(fn)` |
+| 语言注册 | `registerAitheTranslations()` | `aitheUI.registerLocale()` |
+| 获取语言列表 | `getAitheLocales()` | `aitheUI.getLocales()` |
+| 获取当前语言 | `getAitheLocale()` | `aitheUI.getLocale()` |
+| 形状切换 | `setAitheShape('pill')` | `aitheUI.setShape('pill')` |
+| 主题切换 | `setAitheTheme('dark')` | `aitheUI.setTheme('dark')` |
+| 阴影切换 | `setAitheShadow('neumorphism')` | `aitheUI.setShadow('neumorphism')` |
+| 布局切换 | `setAitheLayout('compact')` | `aitheUI.setLayout('compact')` |
+
+## 变更内容
+
+### 新增
+
+- **`src/styles/shadow/`** — 阴影风格系统目录
+  - `index.ts` — 阴影管理核心 API：`setAitheShadow()`、`getAitheShadow()`、`initAitheShadow()`、`onAitheShadowChange()`、`getShadowTokens()`、`getAitheShadows()`
+  - `flat.ts` — 扁平阴影风格
+  - `neumorphism.ts` — 新拟态阴影风格
+  - `skeuomorphic.ts` — 拟物化阴影风格
+  - `glassmorphism.ts` — 玻璃拟态阴影风格
+  - `cyber.ts` — 赛博风格阴影
+  - `deep.ts` — 深度阴影风格
+  - `diffuse.ts` — 扩散阴影风格
+  - `sharp-business.ts` — 锐利商务阴影风格
+  - `retro.ts` — 复古阴影风格
+- **`src/styles/types.ts`** — 新增 `AitheBuiltinShadow` 和 `AitheShadowName` 类型定义
+- **`src/components/theme/shadow-picker.ts`** — `<aithe-shadow-picker>` 阴影风格选择器组件，基于 floating overlay 模式，支持 `placement` 属性和 i18n
+- **`docs/api/theme/shadow-picker.md`** — shadow-picker 组件 API 文档
+- **`src/styles/aithe-ui.ts`** — 统一的 `AitheUI` 类，提供 `aitheUI` 预初始化单例，整合 theme、shape、shadow、layout、i18n 管理
+- **`src/utils/utils.ts`** — 从 `src/core/utils.ts` 重命名而来
+
+### 修改
+
+- **`src/index.ts`** — 导出路径调整，移除 `@core/global` 导出，新增 `@styles/aithe-ui` 和 `@utils` 导出
+- **多个 i18n 导入路径** — 从 `@core/i18n` 改为 `@styles/i18n`：
+  - `src/apps/admin/i18n/*.ts`
+  - `src/apps/api/i18n/*.ts`
+  - `src/apps/demo/i18n/*.ts`
+  - `src/components/framework/sidebar.ts`
+  - `src/components/data/tree.ts`
+  - `src/components/data/tree-menu.ts`
+  - `src/components/navigation/dropdown.ts`
+- **`src/apps/admin/app.ts`** — 移除 `initializeAitheUI()` 调用
+- **`src/styles/aithe-ui.ts`** — `registerLocale` 方法注释更新为"合并追加翻译"
+- **`docs/i18n.md`** — 全面更新，统一使用 `aitheUI` 实例 API：
+  - 快速开始示例改用 `aitheUI.setLocale()` / `aitheUI.getLocale()`
+  - 核心 API 章节改用 `aitheUI.setLocale()` / `aitheUI.getLocale()` / `aitheUI.onLocaleChange()` / `aitheUI.registerLocale()` / `aitheUI.getLocales()`
+  - 删除 `translateNodeLabel` API 文档
+  - 删除旧版 locale 值迁移章节
+  - 删除 `AitheTreeNodeMeta i18n 字段` 章节
+  - 翻译函数示例改用 `aitheUI.t()`
+- **`docs/quickstart.md`** — 移除按需导入需手动初始化说明，语言切换改用 `aitheUI.setLocale()`
+- **`docs/theming.md`** — 移除 `initializeAitheUI()` 示例，改为 `aitheUI.setTheme()`
+- **`docs/guide.md`** — 移除 `initializeAitheUI()` 和 `aitheUI.init()` 示例，改为 `aitheUI.setShape()` 和 `aitheUI.setLayout()`
+- **`docs/framework-integration.md`** — 移除 SSR 章节中的"延迟初始化"步骤
+- **`docs/api/theme/shape-picker.md`** — 事件描述中的 `setAitheShape` 改为 `aitheUI.setShape()`
+- **`docs/api/theme/theme-picker.md`** — 事件描述更新
+- **`docs/api/theme/theme-preview.md`** — 事件描述和示例更新
+- **`docs/api/theme/shadow-picker.md`** — 新增 shadow-picker API 文档，包含属性、事件、示例
+
+### 删除
+
+- **`src/core/global.ts`** — 删除统一初始化模块，其功能由 `aitheUI` 单例和 `src/styles/aithe-ui.ts` 替代
+- **`src/core/utils.ts`** — 已重命名为 `src/utils/utils.ts`

package/docs/issue/issue_26.2.3.9.md

@@ -0,0 +1,76 @@
+# Issue 26.2.3.9
+
+## 版本信息
+
+- **版本号**: 26.2.3.9
+- **基线版本**: 26.2.3
+- **类型**: Feature
+- **日期**: 2026-05-22
+
+## 变更概述
+
+1. **排版（Typography）正交风格系统** — 新增 4 种内置排版风格（minimal/business/luxury/compact），与 Theme/Shape/Shadow 正交，通过 CSS 变量动态切换字号/字重/行高/间距/控件高度
+2. **Typo Picker 组件** — 新增 `<aithe-typo-picker>` 排版风格选择器组件
+3. **日志系统** — 新增 `@core/logger` 日志核心模块（console 劫持、全局错误捕获、远程上报）和 `<aithe-log-panel>` 可视化面板组件
+4. CSS 变量默认值从 `:host` 硬编码迁移到排版系统动态注入，spacing/typography/control-height 变量不再有静态默认值
+5. `aithe-body` 重构为内部滚动容器，`aithe-theme-preview` 集成排版选择器
+
+## 破坏性变更
+
+| 变更项                         | 旧值                                                                                                     | 新值                                                                                                   |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| CSS 变量默认值来源             | `src/styles/mixins.ts` 中 `:host` 硬编码 spacing/font-size/font-weight/line-height/control-height 默认值 | 由排版系统（`src/styles/typo/`）在 `:root` 上动态注入，未初始化排版系统时这些变量无值                  |
+| `aithe-body` 滚动行为          | `:host` 为 `display: block`，滚动监听 `globalThis.scrollY`                                               | `:host` 为 `display: flex; flex-direction: column; overflow: hidden`，滚动监听内部 `.body-scroll` 容器 |
+| `aithe-theme-apply` 事件副作用 | 点击"应用主题"同时应用 theme、shape、shadow                                                              | 点击"应用主题"同时应用 theme、shape、shadow、typo                                                      |
+
+## 变更内容
+
+### 新增
+
+- **`src/styles/typo/`** — 排版风格系统目录
+  - `index.ts` — 排版管理核心 API：`setAitheTypo()`、`getAitheTypo()`、`initAitheTypo()`、`onAitheTypoChange()`、`getTypoTokens()`，localStorage 持久化（key: `aithe-typo`），默认值 `business`
+  - `minimal.ts` — 极简排版 Token 映射
+  - `business.ts` — 商务排版 Token 映射（默认）
+  - `luxury.ts` — 轻奢排版 Token 映射
+  - `compact.ts` — 紧凑排版 Token 映射
+- **`src/styles/types.ts`** — 新增 `AitheBuiltinTypo`（`'minimal'|'business'|'luxury'|'compact'`）和 `AitheTypoName` 类型定义
+- **`src/components/theme/typo-picker.ts`** — `<aithe-typo-picker>` 排版风格选择器组件，基于 floating overlay 模式，支持 `placement` 属性、受控模式和 i18n
+- **`src/components/framework/log-panel.ts`** — `<aithe-log-panel>` 日志面板组件，支持 overlay/inline 两种布局、可拖拽调整高度、按级别过滤、搜索、复制、展开详情
+- **`src/core/logger/`** — 日志核心模块
+  - `index.ts` — 模块入口，导出 `LoggerCore`、`LogLevel`、`LogEntry` 等，创建默认单例 `logger`
+  - `LoggerCore.ts` — 核心日志器类：劫持 console、捕获全局错误/未处理 Promise 拒绝、远程上报（批量+防抖）、订阅/清空机制、序列化导出
+  - `types.ts` — 类型定义：`LogLevel` 枚举、`LogEntry`/`LogConfig`/`LogReporterConfig`/`LogSerializedPayload` 接口
+- **`src/core/aithe-element.ts`** — 新增 `log` 属性（`@property({ type: Boolean })`），当为 true 时组件 emit 的事件会被 logger 捕获
+- **`src/utils/events.ts`** — `emitAitheEvent` 新增日志记录逻辑：当 `detail.log === true` 时自动记录到 logger
+- **`docs/api/theme/typo-picker.md`** — typo-picker 组件 API 文档
+- **`docs/guide.md`** — 新增"排版风格（Typography）"完整章节（~165 行）：4 种内置风格说明、API 用法、Token 体系、各风格 Token 值对比表
+- **`docs/theming.md`** — 新增"排版风格（Typography）"完整章节（~157 行），含 Token 体系、值对比表、持久化说明
+- **`docs/quickstart.md`** — 新增"7. 切换排版风格"步骤，后续步骤编号顺延
+
+### 修改
+
+- **`src/styles/aithe-ui.ts`** — `AitheUI` 类新增 `setTypo()`/`getTypo()`/`getTypos()`/`getTypoTokens()`/`onTypoChange()` 方法；构造函数新增 `defaultTypo` 选项并调用 `initAitheTypo()`
+- **`src/index.ts`** — 新增导出 `@core/logger`、`@components/framework/log-panel`、`@components/theme/typo-picker`
+- **`src/styles/mixins.ts`** — 从 `aithePrimitiveTokens` 中移除硬编码的 spacing/font-size/font-weight/line-height/control-height 变量（约 30 行），这些值现在由排版系统动态注入
+- **`src/components/framework/body.ts`** — 重构滚动机制：`:host` 改为 `display: flex; flex-direction: column; overflow: hidden`；新增 `.body-scroll` 包裹层；新增 `showLogPanel`/`logPanelOpen` 属性、`bar` 插槽、日志面板切换按钮
+- **`src/components/theme/theme-preview.ts`** — 新增 `previewTypo` 状态、`handleTypoChange` 处理器、`applyTypoTokensLocally` 方法；内嵌 `<aithe-typo-picker>`；确认时调用 `aitheUI.setTypo()`
+- **`src/styles/i18n/index.ts`** — 新增 `typoPicker` 翻译键类型
+- **`src/styles/i18n/locales/*.ts`**（11 个文件）— 新增 `typoPicker` 翻译键
+- **`src/apps/api/i18n/*.ts`**（11 个文件）— 新增 `api.theme.typoPicker` 翻译键
+- **`src/apps/demo/i18n/*.ts`**（11 个文件）— 新增 `demo.theme.typoPicker.title/description` 翻译键
+- **`src/apps/api/demo-data.ts`** — 新增 `theme-typo-picker` demo 数据
+- **`src/apps/api/pages/docs.ts`** — 新增 typo-picker API 文档页面入口
+- **`src/apps/demo/pages/theme.ts`** — 新增 Typo Picker 独立 demo 页面
+- **`src/apps/demo/app.ts`** — 集成 log-panel：新增 `logPanelOpen` 状态、日志面板切换按钮、`<aithe-log-panel>` 组件；布局改为 `grid-template-rows: auto 1fr auto; height: 100vh`
+- **`docs/api/summary.md`** — 新增 Shadow Picker、Typo Picker 行；更新正交体系描述为 Theme × Shape × Shadow × Typo
+- **`docs/api/theme/theme-preview.md`** — 更新描述以包含 typo 维度
+- **`vite.admin.config.ts` / `vite.api.config.ts` / `vite.config.ts` / `vite.demo.config.ts`** — `import { resolve } from 'path'` 改为 `import { resolve } from 'node:path'`
+- **`tsconfig.json`** — `exclude` 新增 `"vite.*.config.ts"`、`"vite.config.ts"`
+- **`.gitignore`** — 新增忽略 `vite.config.js`、`vite.config.d.ts`、`vite.config.d.ts.map`
+- **`src/core/datahub/core/adapter/MockAdapter.ts`** — 解构中移除未使用的 `url` 变量
+- **`src/apps/api/i18n/fr-FR.ts`** — 修复引号风格
+
+### 删除
+
+- **`vite.config.d.ts` / `vite.config.d.ts.map` / `vite.config.js`** — Vite 构建产物，已加入 `.gitignore`
+- **`vite.demo.config.d.ts` / `vite.demo.config.d.ts.map` / `vite.demo.config.js`** — Vite 构建产物，已加入 `.gitignore`