@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/theming.md

@@ -1,6 +1,6 @@
 # 主题系统 / Theming
 
-Aithe UI 提供完整的主题系统，包含 22 种内置主题、全局/局部切换、CSS 变量定制和程序化 API。
+Aithe UI 提供完整的主题系统，包含 25 种内置主题、8 种形状风格、9 种阴影风格、4 种排版风格、全局/局部切换、CSS 变量定制和程序化 API。颜色主题（Theme）、形状风格（Shape）、阴影风格（Shadow）与排版风格（Typo）正交设计，可自由组合。
 
 ---
 
@@ -38,6 +38,16 @@ Aithe UI 提供完整的主题系统，包含 22 种内置主题、全局/局部
 | `navy`     | 海军蓝暗色主题   |
 | `raisin`   | 葡萄干色暗色主题 |
 
+### Cloud 系（3 种）
+
+| 主题名    | 说明                 | 品牌色     |
+| --------- | -------------------- | ---------- |
+| `huawei`  | 华为云风格主题       | `#CF102D`  |
+| `tianyi`  | 天翼云风格主题       | `#0052CC`  |
+| `aliyun`  | 阿里云风格主题       | `#FF6A00`  |
+
+Cloud 系主题模拟主流云厂商官网色彩风格，背景为白色系带极淡品牌色倾向，品牌色仅用于按钮/强调元素，不铺大面积色块。
+
 ---
 
 ## 切换主题
@@ -45,31 +55,36 @@ Aithe UI 提供完整的主题系统，包含 22 种内置主题、全局/局部
 ### 程序化 API
 
 ```ts
-import { setAitheTheme, getAitheTheme } from 'aithe-ui';
+import { aitheUI } from '@aithe/aithe-ui';
 
 // 切换主题（自动持久化到 localStorage）
-setAitheTheme('dark');
+aitheUI.setTheme('dark');
 
 // 切换主题但不持久化
-setAitheTheme('midnight', false);
+aitheUI.setTheme('midnight', false);
 
 // 获取当前主题
-const current = getAitheTheme(); // 'dark'
+const current = aitheUI.getTheme(); // 'dark'
+
+// 订阅主题变更
+const unsubscribe = aitheUI.onThemeChange(() => {
+  console.log('Theme changed to:', aitheUI.getTheme());
+});
+
+// 取消订阅
+unsubscribe();
 ```
 
-### 使用主题选择器组件
+### 使用统一外观切换器
+
+[`<aithe-theme-switch>`](api/theme/theme-switch.md) 在单个下拉菜单中整合主题、阴影、形状和排版选择，适合页头等紧凑场景：
 
 ```html
 <!-- 基本用法 -->
-<aithe-theme-picker></aithe-theme-picker>
-
-<!-- 指定下拉位置 -->
-<aithe-theme-picker placement="bottom-start"></aithe-theme-picker>
+<aithe-theme-switch></aithe-theme-switch>
 
-<!-- 监听主题变更 -->
-<aithe-theme-picker @aithe-theme-change="${(e)" ="">
-  console.log(e.detail.theme)}>
-</aithe-theme-picker>
+<!-- 仅图标模式 -->
+<aithe-theme-switch icon-only></aithe-theme-switch>
 ```
 
 ### 使用主题预览组件
@@ -79,24 +94,341 @@ const current = getAitheTheme(); // 'dark'
 <aithe-theme-preview></aithe-theme-preview>
 
 <!-- 监听确认应用 -->
-<aithe-theme-preview @aithe-theme-apply="${(e)" ="">
-  console.log('Applied:', e.detail.theme)}>
-</aithe-theme-preview>
+<aithe-theme-preview
+  @aithe-theme-apply="${(e) => console.log('Applied:', e.detail)}"
+></aithe-theme-preview>
 ```
 
 ---
 
-## 主题作用域
+## 形状风格（Shape）
 
-### 全局主题
+形状风格与颜色主题正交——任意主题可与任意形状风格自由组合，互不影响。
+
+### 内置形状风格（8 种）
+
+| 形状名    | 说明             | 控件圆角特征                       | 容器圆角特征               |
+| --------- | ---------------- | ---------------------------------- | -------------------------- |
+| `sharp`   | 直角             | 0px                                | 0px                        |
+| `smooth`  | 微圆角           | 2–8px                              | 2–8px                      |
+| `rounded` | 标准圆角（默认） | 6–20px                             | 6–20px                     |
+| `rounder` | 大圆角           | 10–28px                            | 10–28px                    |
+| `pill`    | 胶囊             | 999px（控件全圆）                  | 10–28px（容器保守值）      |
+| `circle`  | 圆形             | 50%（控件圆形）                    | 10–28px（容器保守值）      |
+| `chamfer` | 斜切角           | 不对称 px 值（如 0px 8px 0px 8px） | 同控件值                   |
+| `organic` | 有机曲线         | 不对称百分比（30%–70%）            | 不对称 px 值（温和有机感） |
+
+> **关键约束**：`pill`、`circle`、`organic` 三种极端形状仅对**控件类组件**（button、input、tag 等）生效；**容器类组件**（card、dialog、table 等）使用保守值，避免布局变形。
+
+### 切换形状风格
+
+#### 程序化 API
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+// 切换形状风格（自动持久化到 localStorage）
+aitheUI.setShape('pill');
+
+// 切换但不持久化
+aitheUI.setShape('pill', false);
+
+// 获取当前形状风格
+const shape = aitheUI.getShape(); // 'pill'
+
+// 订阅形状风格变更
+const unsubscribe = aitheUI.onShapeChange(() => {
+  console.log('Shape changed to:', aitheUI.getShape());
+});
+```
+
+#### 使用形状选择器组件
+
+```html
+<!-- 基本用法 -->
+<aithe-shape-picker></aithe-shape-picker>
+
+<!-- 指定下拉位置 -->
+<aithe-shape-picker placement="bottom-start"></aithe-shape-picker>
+
+<!-- 受控模式（由外部控制选中状态） -->
+<aithe-shape-picker .value="${currentShape}"></aithe-shape-picker>
+
+<!-- 监听形状变更 -->
+<aithe-shape-picker @aithe-shape-change="${(e) => console.log(e.detail)}"></aithe-shape-picker>
+```
+
+#### 使用主题预览组件
+
+`aithe-theme-preview` 同时包含主题选择器和形状选择器，预览区局部生效，点击"应用主题"按钮将主题和形状同时应用到全局：
+
+```html
+<aithe-theme-preview></aithe-theme-preview>
+```
+
+### 双轨圆角 Token 体系
+
+形状风格通过两套独立的 CSS 变量控制圆角，实现控件与容器的差异化处理：
+
+| Token 系列                   | 作用域     | 说明                                    |
+| ---------------------------- | ---------- | --------------------------------------- |
+| `--aithe-radius-*`           | 控件类组件 | button、input、tag、select 等交互控件   |
+| `--aithe-container-radius-*` | 容器类组件 | card、dialog、table、popover、dashboard-panel 等容器组件 |
+
+每套包含 5 个尺寸级别：`sm`、`md`、`lg`、`xl`、`full`。
+
+- `sharp` / `smooth` / `rounded` / `rounder` / `chamfer`：两套 token 值相同
+- `pill`：控件 = 999px，容器 = rounder 值（10/16/22/28px），但 `--aithe-container-radius-full` 仍为 999px
+- `circle`：控件 = 50%，容器 = rounder 值（10/16/22/28px），但 `--aithe-container-radius-full` 仍为 999px
+- `organic`：控件 = 不对称百分比，容器 = 不对称 px 值模拟温和有机感
+
+---
+
+## 阴影风格（Shadow）
+
+阴影风格与颜色主题、形状风格正交——任意主题可与任意形状风格、任意阴影风格自由组合，互不影响。
+
+### 内置阴影风格（9 种）
+
+| 阴影名           | 说明           | 视觉特征                             |
+| ---------------- | -------------- | ------------------------------------ |
+| `flat`           | 无阴影（扁平） | 无 box-shadow                        |
+| `neumorphism`    | 新拟态         | 柔和的双层阴影（亮+暗），凸起/凹陷感 |
+| `skeuomorphic`   | 拟物           | 多层深阴影，强立体感                 |
+| `glassmorphism`  | 玻璃拟态       | 半透明模糊背景 + 淡阴影              |
+| `cyber`          | 赛博朋克       | 霓虹发光阴影（primary 色辉光）       |
+| `deep`           | 深层阴影       | 大偏移深阴影，强层次感               |
+| `diffuse`        | 漫射阴影       | 大模糊半径、低透明度，柔和扩散       |
+| `sharp-business` | 锐利商务       | 小模糊、清晰边缘，专业商务风格       |
+| `retro`          | 复古           | 偏移硬阴影，复古印刷/像素风格        |
+
+### 切换阴影风格
+
+#### 程序化 API
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+// 切换阴影风格（自动持久化到 localStorage）
+aitheUI.setShadow('neumorphism');
+
+// 切换但不持久化
+aitheUI.setShadow('neumorphism', false);
+
+// 获取当前阴影风格
+const shadow = aitheUI.getShadow(); // 'neumorphism'
+
+// 订阅阴影风格变更
+const unsubscribe = aitheUI.onShadowChange(() => {
+  console.log('Shadow changed to:', aitheUI.getShadow());
+});
+```
+
+#### 使用阴影选择器组件
+
+```html
+<!-- 基本用法 -->
+<aithe-shadow-picker></aithe-shadow-picker>
+
+<!-- 指定下拉位置 -->
+<aithe-shadow-picker placement="bottom-start"></aithe-shadow-picker>
+
+<!-- 受控模式（由外部控制选中状态） -->
+<aithe-shadow-picker .value="${currentShadow}"></aithe-shadow-picker>
+
+<!-- 监听阴影变更 -->
+<aithe-shadow-picker @aithe-shadow-change="${(e) => console.log(e.detail)}"></aithe-shadow-picker>
+```
+
+#### 使用主题预览组件
 
-通过 `setAitheTheme()` 设置全局主题，作用于 `<html>` 元素的 `data-aithe-theme` 属性：
+`aithe-theme-preview` 同时包含主题选择器、形状选择器和阴影选择器，预览区局部生效，点击"应用主题"按钮将主题、形状和阴影同时应用到全局：
+
+```html
+<aithe-theme-preview></aithe-theme-preview>
+```
+
+### 阴影 Token 体系
+
+阴影风格通过 5 个级别的 CSS 变量控制：
+
+| Token 系列         | 说明             |
+| ------------------ | ---------------- |
+| `--aithe-shadow-1` | 最轻阴影         |
+| `--aithe-shadow-2` | 轻阴影           |
+| `--aithe-shadow-3` | 中等阴影（默认） |
+| `--aithe-shadow-4` | 深阴影           |
+| `--aithe-shadow-5` | 最深阴影         |
+
+---
+
+## 排版风格（Typography）
+
+排版风格与颜色主题、形状风格、阴影风格正交——任意主题可与任意形状风格、任意阴影风格、任意排版风格自由组合，互不影响。
+
+排版体系作为四大核心风格维度之一（色彩、形状、阴影、排版），统一管控字号层级、字重、行高、字间距、段落间距、标题间距等排版参数。所有组件文字尺寸、文本间距、布局留白均严格遵循排版规范变量，禁止硬编码固定数值。全局 `:root` 定义通用排版风格变量，组件 `:host` 继承并局部适配。
+
+### 内置排版风格（4 种）
+
+| 排版名     | 说明         | 视觉特征                                                                    |
+| ---------- | ------------ | --------------------------------------------------------------------------- |
+| `minimal`  | 极简         | 3 级以内层级，宽松间距，高行高，呼吸感与秩序感，禁止密集排布                |
+| `business` | 商务（默认） | 完整清晰层级，标题层级差明确，列表数据严格对齐，规整分段，适合高效扫读      |
+| `luxury`   | 轻奢         | 宽松字间距与行高，段落留白充裕，字重对比营造节奏，轻盈有序，精致阅读感      |
+| `compact`  | 紧凑信息流   | 高信息密度，字号行高间距偏小，摘要限制 1–3 行截断，最小化间距，高屏幕承载量 |
+
+#### 极简风格（minimal）
+
+文字层级控制在 3 级以内，标题与正文间距宽松，段落间距显著大于行间距，文本严格基线对齐，禁止密集排布；正文行高舒适，超长文本按需截断，同一区域文本数量克制，整体排版追求呼吸感与秩序感，无多余文字层级。
+
+#### 商务风格（business）
+
+文字层级完整清晰，标题层级差明确，正文字号与行高统一规范；列表、数据类内容严格对齐，关键信息突出排版，辅助文本弱化处理；段落结构规整，分段逻辑清晰，支持多行文本自适应，保证长时间高效扫读与信息核对。
+
+#### 轻奢风格（luxury）
+
+标题字间距与行高偏宽松，正文字号适中、行高舒展；信息点间距充足，排版对称均衡，段落留白充裕；以短句为主，避免大段密集文本，通过字重对比营造节奏，整体轻盈有序，强调精致阅读感。
+
+#### 紧凑信息流（compact）
+
+高信息密度，字号、行高、间距统一偏小；标题优先单行展示，正文摘要限制 1–3 行并自动截断；模块内外间距最小化，文本统一左对齐与基线对齐；辅助信息紧凑排布，图片与文字间距极窄，所有条目排版结构高度一致，提升一屏承载量。
+
+### 切换排版风格
+
+#### 程序化 API
 
 ```ts
-setAitheTheme('dark');
-// <html data-aithe-theme="dark">
+import { aitheUI } from '@aithe/aithe-ui';
+
+// 切换排版风格（自动持久化到 localStorage）
+aitheUI.setTypo('minimal');
+
+// 切换但不持久化
+aitheUI.setTypo('minimal', false);
+
+// 获取当前排版风格
+const typo = aitheUI.getTypo(); // 'minimal'
+
+// 订阅排版风格变更
+const unsubscribe = aitheUI.onTypoChange(() => {
+  console.log('Typo changed to:', aitheUI.getTypo());
+});
 ```
 
+#### 使用排版选择器组件
+
+```html
+<!-- 基本用法 -->
+<aithe-typo-picker></aithe-typo-picker>
+
+<!-- 指定下拉位置 -->
+<aithe-typo-picker placement="bottom-start"></aithe-typo-picker>
+
+<!-- 受控模式（由外部控制选中状态） -->
+<aithe-typo-picker .value="${currentTypo}"></aithe-typo-picker>
+
+<!-- 监听排版变更 -->
+<aithe-typo-picker @aithe-typo-change="${(e) => console.log(e.detail)}"></aithe-typo-picker>
+```
+
+#### 使用主题预览组件
+
+`aithe-theme-preview` 同时包含主题选择器、形状选择器、阴影选择器和排版选择器，预览区局部生效，点击"应用主题"按钮将主题、形状、阴影和排版同时应用到全局：
+
+```html
+<aithe-theme-preview></aithe-theme-preview>
+```
+
+### 排版 Token 体系
+
+排版风格通过覆盖以下组件已使用的 CSS 变量实现切换：
+
+| Token 系列                              | 说明           |
+| --------------------------------------- | -------------- |
+| `--aithe-font-size-xs`                  | 超小字号       |
+| `--aithe-font-size-sm`                  | 小字号         |
+| `--aithe-font-size-md`                  | 中字号（默认） |
+| `--aithe-font-size-lg`                  | 大字号         |
+| `--aithe-font-size-xl`                  | 特大字号       |
+| `--aithe-font-size-2xl`                 | 超大字号       |
+| `--aithe-font-weight-regular`           | 常规字重       |
+| `--aithe-font-weight-medium`            | 中等字重       |
+| `--aithe-font-weight-semibold`          | 半粗字重       |
+| `--aithe-font-weight-bold`              | 粗体字重       |
+| `--aithe-line-height-tight`             | 紧凑行高       |
+| `--aithe-line-height-base`              | 基础行高       |
+| `--aithe-line-height-loose`             | 宽松行高       |
+| `--aithe-space-1` ~ `--aithe-space-10`  | 数字刻度间距   |
+| `--aithe-space-xs` ~ `--aithe-space-xl` | 语义间距别名   |
+| `--aithe-control-height-sm`             | 小控件高度     |
+| `--aithe-control-height-md`             | 中控件高度     |
+| `--aithe-control-height-lg`             | 大控件高度     |
+
+### 各风格 Token 值对比
+
+#### 字号
+
+| Token                   | minimal | business | luxury | compact |
+| ----------------------- | ------- | -------- | ------ | ------- |
+| `--aithe-font-size-xs`  | 12px    | 12px     | 11px   | 11px    |
+| `--aithe-font-size-sm`  | 14px    | 13px     | 13px   | 12px    |
+| `--aithe-font-size-md`  | 15px    | 14px     | 15px   | 13px    |
+| `--aithe-font-size-lg`  | 18px    | 16px     | 18px   | 14px    |
+| `--aithe-font-size-xl`  | 22px    | 20px     | 24px   | 16px    |
+| `--aithe-font-size-2xl` | 32px    | 28px     | 36px   | 20px    |
+
+#### 字重
+
+| Token                          | minimal | business | luxury | compact |
+| ------------------------------ | ------- | -------- | ------ | ------- |
+| `--aithe-font-weight-regular`  | 400     | 400      | 400    | 400     |
+| `--aithe-font-weight-medium`   | 500     | 500      | 500    | 500     |
+| `--aithe-font-weight-semibold` | 600     | 600      | 500    | 600     |
+| `--aithe-font-weight-bold`     | 700     | 700      | 600    | 700     |
+
+#### 行高
+
+| Token                       | minimal | business | luxury | compact |
+| --------------------------- | ------- | -------- | ------ | ------- |
+| `--aithe-line-height-tight` | 1.25    | 1.25     | 1.3    | 1.15    |
+| `--aithe-line-height-base`  | 1.7     | 1.5      | 1.7    | 1.35    |
+| `--aithe-line-height-loose` | 1.9     | 1.7      | 1.9    | 1.5     |
+
+#### 间距（数字刻度）
+
+| Token              | minimal | business | luxury | compact |
+| ------------------ | ------- | -------- | ------ | ------- |
+| `--aithe-space-1`  | 4px     | 4px      | 4px    | 2px     |
+| `--aithe-space-2`  | 8px     | 8px      | 8px    | 4px     |
+| `--aithe-space-3`  | 14px    | 12px     | 14px   | 8px     |
+| `--aithe-space-4`  | 18px    | 16px     | 20px   | 12px    |
+| `--aithe-space-5`  | 22px    | 20px     | 24px   | 16px    |
+| `--aithe-space-6`  | 28px    | 24px     | 30px   | 20px    |
+| `--aithe-space-7`  | 36px    | 32px     | 38px   | 24px    |
+| `--aithe-space-8`  | 44px    | 40px     | 48px   | 32px    |
+| `--aithe-space-9`  | 52px    | 48px     | 56px   | 40px    |
+| `--aithe-space-10` | 68px    | 64px     | 72px   | 48px    |
+
+#### 控件高度
+
+| Token                       | minimal | business | luxury | compact |
+| --------------------------- | ------- | -------- | ------ | ------- |
+| `--aithe-control-height-sm` | 32px    | 32px     | 34px   | 28px    |
+| `--aithe-control-height-md` | 40px    | 40px     | 42px   | 36px    |
+| `--aithe-control-height-lg` | 48px    | 48px     | 50px   | 44px    |
+
+---
+
+## 主题作用域
+
+### 全局主题
+
+通过 `aitheUI.setTheme()` 设置全局主题，作用于 `<html>` 元素的 `data-aithe-theme` 属性：
+
+````ts
+aitheUI.setTheme('dark');
+// <html data-aithe-theme="dark">```
+
 ### 局部主题覆盖
 
 通过组件的 `theme` 属性为单个组件指定不同主题：
@@ -106,7 +438,7 @@ setAitheTheme('dark');
 <aithe-card theme="dark">
   <aithe-button type="primary">Dark Button</aithe-button>
 </aithe-card>
-```
+````
 
 组件内部通过 `computedTheme` getter 解析最终主题（本地覆盖 → 最近带主题祖先 → 全局）。
 
@@ -159,13 +491,20 @@ setAitheTheme('dark');
 --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-container-radius-sm   /* 6px */
+--aithe-container-radius-md   /* 10px */
+--aithe-container-radius-lg   /* 14px */
+--aithe-container-radius-xl   /* 20px */
+--aithe-container-radius-full /* 999px */
+
 /* 阴影 */
 --aithe-shadow-1 ~ --aithe-shadow-5
 
@@ -173,6 +512,8 @@ setAitheTheme('dark');
 --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-font-weight-regular ~ --aithe-font-weight-bold  /* 400 ~ 700 */
+--aithe-line-height-tight ~ --aithe-line-height-loose  /* 1.2 ~ 1.7 */
 
 /* 动画 */
 --aithe-duration-fast  /* 140ms */
@@ -234,24 +575,72 @@ setAitheTheme('dark');
 }
 ```
 
-然后通过 `setAitheTheme('custom')` 应用。
+然后通过 `aitheUI.setTheme('custom')` 应用。
 
 ---
 
 ## 持久化
 
-主题选择自动保存到 `localStorage`（键名 `aithe-theme`），页面刷新后自动恢复。
+主题选择自动保存到 `localStorage`（键名 `aithe-theme`），形状风格保存到 `aithe-shape`，阴影风格保存到 `aithe-shadow`，排版风格保存到 `aithe-typo`，页面刷新后自动恢复。
 
 ```ts
-// 初始化时指定默认主题（无存储偏好时使用）
-import { initializeAitheUI } from 'aithe-ui';
-initializeAitheUI('dark'); // 默认使用 dark 主题
+import { aitheUI } from '@aithe/aithe-ui';
+
+// 切换主题
+aitheUI.setTheme('dark');
 ```
 
 ---
 
-## 下一步
+## 基于 AitheElement 开发组件
+
+所有继承 `AitheElement` 的自定义组件**必须**在 `static styles` 中包含 `aitheBaseStyles`，否则 CSS 变量令牌（`--aithe-*`）和全局重置样式无法注入 Shadow DOM，主题切换、形状风格等将不生效。
+
+### 正确用法
+
+```ts
+import { AitheElement, aitheBaseStyles, aitheUI } from '@aithe/aithe-ui';
+import { css, html } from 'lit';
+import { customElement } from 'lit/decorators.js';
+
+@customElement('my-component')
+export class MyComponent extends AitheElement {
+  static override readonly styles = [
+    aitheBaseStyles,           // ← 必须：注入 CSS 变量令牌 + 全局重置
+    css`
+      :host {
+        display: block;
+        color: var(--aithe-color-text);  /* 使用主题变量 */
+      }
+    `,
+  ];
+
+  render() {
+    return html`<div>Hello</div>`;
+  }
+}
+```
+
+### 错误用法（主题变量不生效）
+
+```ts
+// ❌ 缺少 aitheBaseStyles，--aithe-* 变量在 Shadow DOM 中不可用
+static override readonly styles = [
+  css`
+    :host {
+      color: var(--aithe-color-text);  /* 不会生效 */
+    }
+  `,
+];
+```
+
+### 说明
+
+- `aitheBaseStyles` 由 `aithePrimitiveTokens`（CSS 变量令牌）和 `aitheGlobalResetStyles`（全局重置样式）组成，定义在 `@aithe/aithe-ui` 的 `core/styles.ts` 中。
+- 所有 aithe-ui 内置组件（`aithe-label`、`aithe-button`、`aithe-input` 等）均已包含 `aitheBaseStyles`。
+- 如果组件没有自定义样式，`static styles` 可以只包含 `aitheBaseStyles`。
+- 如果组件继承自另一个已包含 `aitheBaseStyles` 的组件，子类可以省略（但建议显式包含以保持清晰）。
 
 - [国际化](i18n.md) — 多语言支持
-- [使用指南](guide.md) — 组件通用 API
-- [API 参考](api/summary.md) — 全部组件详细 API
+- [使用指南](guide.md) — 组件通用 API、形状风格、阴影风格、排版风格、布局密度
+- [API 参考](api/summary.md) — 全部 83 个组件详细 API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithe/aithe-ui",
-  "version": "26.2.2",
+  "version": "26.3.1",
   "description": "A cross-framework Web Components design system built with Lit 3.x and TypeScript — 79 components, 22 themes, i18n, and accessible semantics.",
   "license": "MIT",
   "type": "module",
@@ -45,24 +45,28 @@
     "dev": "vite",
     "dev:demo": "vite --config vite.demo.config.ts",
     "dev:api": "vite --config vite.api.config.ts",
-    "build": "vite build && tsc -p tsconfig.json --emitDeclarationOnly",
+    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc-alias -p tsconfig.json && vite build",
     "build:demo": "vite build --config vite.demo.config.ts",
     "build:api": "vite build --config vite.api.config.ts",
+    "build:admin": "vite build --config vite.admin.config.ts",
     "preview": "vite preview",
-    "preview:api": "vite preview --outDir dist-api",
+    "preview:api": "vite preview --outDir dist/apps/api",
     "check": "tsc -p tsconfig.json --noEmit",
-    "lint": "eslint src/ apps/",
-    "lint:fix": "eslint src/ apps/ --fix",
-    "format": "prettier --check src/ apps/",
-    "format:fix": "prettier --write src/ apps/",
-    "publish": "node publish.js"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --check src/",
+    "format:fix": "prettier --write src/",
+    "release": "node publish.js"
   },
   "dependencies": {
-    "lit": "^3.2.1"
+    "lit": "^3.3.3",
+    "lit-html": "^3.3.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "concurrently": "^9.2.1",
+    "concurrently": "^10.0.3",
     "dotenv": "^17.4.2",
     "eslint": "^10.3.0",
     "eslint-config-prettier": "^10.1.8",
@@ -72,9 +76,11 @@
     "happy-dom": "^20.9.0",
     "marked": "^18.0.3",
     "prettier": "^3.8.3",
+    "tsc-alias": "^1.8.17",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.3",
     "vite": "^8.0.12",
-    "vite-plugin-markdown": "^2.2.0"
+    "vite-plugin-markdown": "^2.2.0",
+    "vitest": "^4.1.6"
   }
 }

package/dist/apps/api/index.html

@@ -1,13 +0,0 @@
-<!doctype html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Aithe UI API Documentation</title>
-    <script type="module" crossorigin src="/index2.js"></script>
-    <link rel="modulepreload" crossorigin href="/index-jd7NIlfT.js">
-  </head>
-  <body>
-    <aithe-api-app></aithe-api-app>
-  </body>
-</html>

package/dist/apps/demo/i18n/en.d.ts

@@ -1,3 +0,0 @@
-import type { AitheTranslationValue } from '../../../src/core/i18n';
-export declare const demoEn: Record<string, AitheTranslationValue>;
-//# sourceMappingURL=en.d.ts.map

package/dist/apps/demo/i18n/en.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../../../apps/demo/i18n/en.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAsJxD,CAAC"}

package/dist/apps/demo/i18n/zh.d.ts

@@ -1,3 +0,0 @@
-import type { AitheTranslationValue } from '../../../src/core/i18n';
-export declare const demoZh: Record<string, AitheTranslationValue>;
-//# sourceMappingURL=zh.d.ts.map

package/dist/apps/demo/i18n/zh.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"zh.d.ts","sourceRoot":"","sources":["../../../../apps/demo/i18n/zh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAiIxD,CAAC"}

package/dist/apps/demo/index.html

@@ -1,13 +0,0 @@
-<!doctype html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Aithe UI Demo</title>
-    <script type="module" crossorigin src="/index.js"></script>
-    <link rel="modulepreload" crossorigin href="/index-jd7NIlfT.js">
-  </head>
-  <body>
-    <aithe-demo-app></aithe-demo-app>
-  </body>
-</html>

package/dist/base/aithe-element.d.ts

@@ -1,29 +0,0 @@
-import { LitElement } from 'lit';
-/**
- * Minimal shared base element for all Aithe UI components.
- */
-export declare class AitheElement extends LitElement {
-    /** Visual variant. Default: `default`. */
-    variant: string;
-    /** Shared size scale. Default: `md`. */
-    size: string;
-    /** Optional local theme override. */
-    theme: string;
-    /** Disabled state. Default: `false`. */
-    disabled: boolean;
-    constructor();
-    /**
-     * Emits a composed custom event with standard Aithe defaults.
-     */
-    emit(type: string, detail?: unknown): void;
-    /**
-     * Final resolved theme name.
-     */
-    get computedTheme(): string;
-    connectedCallback(): void;
-    protected focusFirst(root?: ParentNode): void;
-    protected trapFocus(event: KeyboardEvent, root?: ParentNode): void;
-    private syncBaseA11yState;
-    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
-}
-//# sourceMappingURL=aithe-element.d.ts.map