@aithe/aithe-ui 26.2.2 → 26.3.1

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

@@ -0,0 +1,94 @@
+# AitheShapePicker / AitheShapePicker 形状选择器
+
+> Shape style picker with preview thumbnails, keyboard navigation, and built-in shape switch.
+> 形状风格选择器，支持预览缩略图、键盘导航和内置形状切换。
+>
+> **Note:** For most use cases, consider using the unified [`<aithe-theme-switch>`](theme-switch.md) component instead, which integrates theme, shadow, shape, and typo selection in a single dropdown.
+> **注意：** 大多数场景建议使用统一的 [`<aithe-theme-switch>`](theme-switch.md) 组件，它在单个下拉菜单中整合了主题、阴影、形状和排版选择。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                               | Description (CN)                |
+| --------- | ---------------------------------------------- | ------------------------------- |
+| (default) | No slots — the trigger is rendered internally. | 无插槽 — 触发器由组件内部渲染。 |
+
+## Properties / 属性
+
+| Name      | Type                                                       | Default      | Description (EN)                                                                                                                 | Description (CN)                                                                  |
+| --------- | ---------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| value     | `AitheShapeName`                                           | —            | Controlled shape selection. When set, the picker displays this value instead of the global shape. Used by `aithe-theme-preview`. | 受控形状选择。设置后，选择器显示此值而非全局形状。由 `aithe-theme-preview` 使用。 |
+| placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-end' | Dropdown panel placement. Auto-adapts to viewport.                                                                               | 下拉面板位置。自动适应视口。                                                      |
+
+## Events / 事件
+
+| Name               | Detail              | Cancelable | Description (EN)                                                                                                                                                                               | Description (CN)                                                                                                           |
+| ------------------ | ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| aithe-shape-change | `{ shape: string }` | Yes        | Emitted when a shape is selected. Built-in shape switch (`aitheUI.setShape()`) runs by default. Call `preventDefault()` to suppress the built-in behavior and handle shape switching manually. | 形状风格选中时发出。默认执行内置切换逻辑（`aitheUI.setShape()`）。调用 `preventDefault()` 可阻止内置切换，由外部自行处理。 |
+
+## Built-in Shapes / 内置形状风格
+
+| Shape   | Description (EN)              | Description (CN) | Preview Radius                      |
+| ------- | ----------------------------- | ---------------- | ----------------------------------- |
+| sharp   | Sharp corners (0px)           | 直角             | `0px`                               |
+| smooth  | Slightly rounded (2-8px)      | 微圆角           | `4px`                               |
+| rounded | Standard rounded (6-20px)     | 标准圆角         | `10px`                              |
+| rounder | More rounded (10-28px)        | 大圆角           | `16px`                              |
+| pill    | Pill / Capsule (999px)        | 胶囊             | `999px`                             |
+| circle  | Circle (50%)                  | 圆形             | `50%`                               |
+| chamfer | Chamfered corners             | 斜切角           | `0px 8px 0px 8px`                   |
+| organic | Organic curves (asymmetric %) | 有机曲线         | `30% 70% 70% 30% / 30% 30% 70% 70%` |
+
+## CSS Variables / CSS 变量
+
+Shape styles control the following CSS custom properties on `:root`:
+
+| Variable                        | Description (EN)                  | Description (CN) |
+| ------------------------------- | --------------------------------- | ---------------- |
+| `--aithe-radius-sm`             | Small control radius              | 小控件圆角       |
+| `--aithe-radius-md`             | Medium control radius             | 中控件圆角       |
+| `--aithe-radius-lg`             | Large control radius              | 大控件圆角       |
+| `--aithe-radius-xl`             | Extra-large control radius        | 超大控件圆角     |
+| `--aithe-radius-full`           | Full control radius (pill/circle) | 全圆控件圆角     |
+| `--aithe-container-radius-sm`   | Small container radius            | 小容器圆角       |
+| `--aithe-container-radius-md`   | Medium container radius           | 中容器圆角       |
+| `--aithe-container-radius-lg`   | Large container radius            | 大容器圆角       |
+| `--aithe-container-radius-xl`   | Extra-large container radius      | 超大容器圆角     |
+| `--aithe-container-radius-full` | Full container radius             | 全圆容器圆角     |
+
+> **Note:** Pill, Circle, and Organic shapes apply extreme values only to controls (`--aithe-radius-*`). Containers (`--aithe-container-radius-*`) use conservative values to prevent layout distortion.
+> **注意：** 胶囊、圆形和有机曲线仅对控件（`--aithe-radius-*`）应用极端值。容器（`--aithe-container-radius-*`）使用保守值以避免布局变形。
+
+## Examples / 示例
+
+### Default usage (built-in shape switch) / 默认用法（内置切换）
+
+```html
+<aithe-shape-picker placement="bottom-end"></aithe-shape-picker>
+```
+
+No event listener is required — the component calls `aitheUI.setShape()` internally by default.
+
+无需监听事件 — 组件默认在内部调用 `aitheUI.setShape()`。
+
+### Custom shape handling (prevent default) / 自定义形状处理（阻止默认行为）
+
+```js
+const picker = document.querySelector('aithe-shape-picker');
+picker.addEventListener('aithe-shape-change', (e) => {
+  e.preventDefault();
+  console.log('Shape selected:', e.detail.shape);
+});
+```
+
+### Programmatic API / 编程式 API
+
+```js
+import { aitheUI } from '@aithe/aithe-ui';
+
+aitheUI.setShape('pill');
+console.log(aitheUI.getShape()); // 'pill'
+
+const unsubscribe = aitheUI.onShapeChange(() => {
+  console.log('Shape changed to:', aitheUI.getShape());
+});
+```

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

@@ -2,36 +2,54 @@
 
 > Theme picker with grouped light/dark themes, color dot previews, and keyboard navigation.
 > 主题选择器，支持亮色/暗色分组、色点预览和键盘导航。
+>
+> **Note:** For most use cases, consider using the unified [`<aithe-theme-switch>`](theme-switch.md) component instead, which integrates theme, shadow, shape, and typo selection in a single dropdown.
+> **注意：** 大多数场景建议使用统一的 [`<aithe-theme-switch>`](theme-switch.md) 组件，它在单个下拉菜单中整合了主题、阴影、形状和排版选择。
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
+| Name      | Description (EN)                               | Description (CN)                |
+| --------- | ---------------------------------------------- | ------------------------------- |
 | (default) | No slots — the trigger is rendered internally. | 无插槽 — 触发器由组件内部渲染。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| value | `AitheBuiltinTheme \| string` | `'light'` | Currently active theme identifier. | 当前激活的主题标识。 |
+| Name      | Type                                                       | Default      | Description (EN)                                   | Description (CN)             |
+| --------- | ---------------------------------------------------------- | ------------ | -------------------------------------------------- | ---------------------------- |
+| value     | `AitheThemeName`                                           | `'light'`    | Currently active theme identifier.                 | 当前激活的主题标识。         |
 | placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-end' | Dropdown panel placement. Auto-adapts to viewport. | 下拉面板位置。自动适应视口。 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-theme-change | { theme } | Emitted when a theme is selected. | 主题选中时触发。 |
+| Name               | Detail              | Cancelable | Description (EN)                                                                                                                                                                               | Description (CN)                                                                                                       |
+| ------------------ | ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| aithe-theme-change | `{ theme: string }` | Yes        | Emitted when a theme is selected. Built-in theme switch (`aitheUI.setTheme()`) runs by default. Call `preventDefault()` to suppress the built-in behavior and handle theme switching manually. | 主题选中时发出。默认执行内置切换逻辑（`aitheUI.setTheme()`）。调用 `preventDefault()` 可阻止内置切换，由外部自行处理。 |
 
 ## Built-in Themes / 内置主题
 
-| Group | Themes |
-|-------|--------|
-| Light | light, gray, blue, festive, orange, purple, pink, teal, indigo, cyan, amber |
-| Dark | dark, slate, charcoal, midnight, obsidian, graphite, ink, onyx, ebony, navy, raisin |
+| Group | Themes                                                                              |
+| ----- | ----------------------------------------------------------------------------------- |
+| Light | light, gray, blue, festive, orange, purple, pink, teal, indigo, cyan, amber         |
+| Dark  | dark, slate, charcoal, midnight, obsidian, graphite, ink, onyx, ebony, navy, raisin |
 
 ## Examples / 示例
 
+### Default usage (built-in theme switch) / 默认用法（内置切换）
+
 ```html
-<aithe-theme-picker value="light" @aithe-theme-change=${(e) => console.log(e.detail.theme)}>
-</aithe-theme-picker>
+<aithe-theme-picker value="light" placement="bottom-end"></aithe-theme-picker>
+```
+
+No event listener is required — the component calls `aitheUI.setTheme()` internally by default.
+
+无需监听事件 — 组件默认在内部调用 `aitheUI.setTheme()`。
+
+### Custom theme handling (prevent default) / 自定义主题处理（阻止默认行为）
+
+```js
+const picker = document.querySelector('aithe-theme-picker');
+picker.addEventListener('aithe-theme-change', (e) => {
+  e.preventDefault();
+  console.log('Theme selected:', e.detail.theme);
+});
 ```

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

@@ -1,29 +1,76 @@
 # AitheThemePreview / AitheThemePreview 主题预览
 
-> Theme preview panel with a toolbar (theme picker + apply button) and a live preview area containing sidebar navigation and component showcase. The preview area switches theme locally; clicking "Apply Theme" propagates the choice to the page.
-> 主题预览面板，包含工具栏（主题选择器 + 应用按钮）和实时预览区（侧边导航 + 组件展示）。预览区局部切换主题，点击"Apply Theme"将选择应用到页面。
+> Live preview panel with a toolbar (theme picker + shape picker + shadow picker + typo picker + apply button) and a preview area containing sidebar navigation and component showcase. Theme, shape, shadow, and typo changes are applied locally within the preview; clicking "Apply Theme" propagates the theme, shape, shadow, and typo to the global page.
+> 实时预览面板，包含工具栏（主题选择器 + 形状选择器 + 阴影选择器 + 排版选择器 + 应用按钮）和预览区（侧边导航 + 组件展示）。主题、形状、阴影和排版变更仅在预览区内生效；点击"应用主题"将主题、形状、阴影和排版同时应用到全局页面。
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
+| Name      | Description (EN)                           | Description (CN)              |
+| --------- | ------------------------------------------ | ----------------------------- |
 | (default) | No slots — content is rendered internally. | 无插槽 — 内容由组件内部渲染。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
+| Name  | Type                          | Default   | Description (EN)                    | Description (CN)     |
+| ----- | ----------------------------- | --------- | ----------------------------------- | -------------------- |
 | value | `AitheBuiltinTheme \| string` | `'light'` | Currently applied theme identifier. | 当前应用的主题标识。 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-theme-apply | { theme } | Emitted when the "Apply Theme" button is clicked, carrying the selected theme name. | 点击"Apply Theme"按钮时触发，携带选中的主题名称。 |
+| Name              | Detail              | Description (EN)                                                                                                                             | Description (CN)                                                                     |
+| ----------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| aithe-theme-apply | `{ theme: string }` | Emitted when the "Apply Theme" button is clicked, carrying the selected theme name. Theme, shape, shadow, and typo are all applied globally. | 点击"应用主题"按钮时触发，携带选中的主题名称。主题、形状、阴影和排版同时应用到全局。 |
+
+## Behavior / 行为说明
+
+- **Theme preview**: Switching themes in the embedded theme picker only affects the preview area, not the global page.
+- **Shape preview**: Switching shapes in the embedded shape picker only affects the preview area, not the global page.
+- **Shadow preview**: Switching shadows in the embedded shadow picker only affects the preview area, not the global page.
+- **Typo preview**: Switching typo styles in the embedded typo picker only affects the preview area, not the global page.
+- **Apply**: Clicking the "Apply Theme" button calls `aitheUI.setTheme()`, `aitheUI.setShape()`, `aitheUI.setShadow()`, and `aitheUI.setTypo()` globally, persisting the preview selections.
+
+- **主题预览**：在内嵌主题选择器中切换主题仅影响预览区，不影响全局页面。
+- **形状预览**：在内嵌形状选择器中切换形状仅影响预览区，不影响全局页面。
+- **阴影预览**：在内嵌阴影选择器中切换阴影仅影响预览区，不影响全局页面。
+- **排版预览**：在内嵌排版选择器中切换排版风格仅影响预览区，不影响全局页面。
+- **应用**：点击"应用主题"按钮同时调用 `aitheUI.setTheme()`、`aitheUI.setShape()`、`aitheUI.setShadow()` 和 `aitheUI.setTypo()` 将预览选择应用到全局。
 
 ## Examples / 示例
 
+### Basic usage / 基本用法
+
 ```html
-<aithe-theme-preview value="light" @aithe-theme-apply=${(e) => setAitheTheme(e.detail.theme)}>
-</aithe-theme-preview>
+<aithe-theme-preview value="light"></aithe-theme-preview>
+```
+
+The component manages theme, shape, shadow, and typo internally. No event listener is required for basic usage — clicking "Apply Theme" applies all four selections globally.
+
+组件内部管理主题、形状、阴影和排版。基本用法无需监听事件——点击"应用主题"会将四者同时应用到全局。
+
+### Listening for apply / 监听应用事件
+
+```js
+const preview = document.querySelector('aithe-theme-preview');
+preview.addEventListener('aithe-theme-apply', (e) => {
+  console.log('Theme applied:', e.detail.theme);
+  // Shape, shadow, and typo are also applied globally via aitheUI.setShape(), aitheUI.setShadow(), and aitheUI.setTypo()
+  // 形状、阴影和排版也通过 aitheUI.setShape()、aitheUI.setShadow() 和 aitheUI.setTypo() 应用到全局
+});
+```
+
+### Programmatic API / 编程式 API
+
+```js
+import { aitheUI } from '@aithe/aithe-ui';
+
+// Apply theme, shape, shadow, and typo independently / 独立应用主题、形状、阴影和排版
+aitheUI.setTheme('dark');
+aitheUI.setShape('pill');
+aitheUI.setShadow('neumorphism');
+aitheUI.setTypo('luxury');
+
+console.log(aitheUI.getTheme()); // 'dark'
+console.log(aitheUI.getShape()); // 'pill'
+console.log(aitheUI.getShadow()); // 'neumorphism'
+console.log(aitheUI.getTypo()); // 'luxury'
 ```

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

@@ -0,0 +1,93 @@
+# AitheThemeSwitch / AitheThemeSwitch 外观切换器
+
+> Unified appearance switch dropdown that integrates theme, shadow, shape, and typo selection in a single submenu. Replaces the individual `aithe-theme-picker`, `aithe-shadow-picker`, `aithe-shape-picker`, and `aithe-typo-picker` for common use cases.
+> 统一外观切换下拉菜单，在单个子菜单中整合主题、阴影、形状和排版选择。替代独立的 `aithe-theme-picker`、`aithe-shadow-picker`、`aithe-shape-picker` 和 `aithe-typo-picker` 的常见使用场景。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                               | Description (CN)                |
+| --------- | ---------------------------------------------- | ------------------------------- |
+| (default) | No slots — the trigger is rendered internally. | 无插槽 — 触发器由组件内部渲染。 |
+
+## Properties / 属性
+
+| Name      | Type                                                       | Default      | Description (EN)                                                                                                                              | Description (CN)                                                                           |
+| --------- | ---------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-end' | Dropdown panel placement. Auto-adapts to viewport.                                                                                            | 下拉面板位置。自动适应视口。                                                               |
+| icon-only | `boolean`                                                  | `false`      | Whether to show only the icon and arrow without the label text. Useful for compact header layouts.                                            | 是否仅显示图标和箭头，不显示标签文字。适用于紧凑的页头布局。                               |
+
+## Events / 事件
+
+| Name               | Detail                                       | Cancelable | Description (EN)                                                                                                                                                                                                                                                              | Description (CN)                                                                                                                                                          |
+| ------------------ | -------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| aithe-theme-change | `{ category: string, value: string }`        | Yes        | Emitted when any option (theme/shadow/shape/typo) is selected. `category` is read from `item.category` on the selected tree-menu item (one of `'theme'`, `'shadow'`, `'shape'`, `'typo'`). Built-in switch (`aitheUI.setTheme()` / `aitheUI.setShadow()` / `aitheUI.setShape()` / `aitheUI.setTypo()`) runs by default. Call `preventDefault()` to suppress the built-in behavior and handle switching manually. | 选择任意选项（主题/阴影/形状/排版）时发出。`category` 从选中项的 `item.category` 读取（`'theme'`、`'shadow'`、`'shape'` 或 `'typo'`）。默认执行内置切换逻辑。调用 `preventDefault()` 可阻止内置切换，由外部自行处理。 |
+
+## Menu Structure / 菜单结构
+
+The dropdown menu is organized into four groups, rendered via `<aithe-tree-menu>`:
+
+| Group        | i18n Key                  | Items                                                                              |
+| ------------ | ------------------------- | ---------------------------------------------------------------------------------- |
+| Theme        | `appearance.group.theme`  | Light themes (11) and Dark themes (11), nested under light-group / dark-group      |
+| Shadow       | `appearance.group.shadow` | 9 shadow styles (flat, neumorphism, skeuomorphic, glassmorphism, cyber, deep, diffuse, sharp-business, retro) |
+| Shape        | `appearance.group.shape`  | 8 shape styles (sharp, smooth, rounded, rounder, pill, circle, chamfer, organic)  |
+| Typo         | `appearance.group.typo`   | 4 typo styles (minimal, business, luxury, compact)                                |
+
+## Examples / 示例
+
+### Default usage (built-in switch) / 默认用法（内置切换）
+
+```html
+<aithe-theme-switch placement="bottom-end"></aithe-theme-switch>
+```
+
+No event listener is required — the component calls the appropriate `aitheUI` method internally by default.
+
+无需监听事件 — 组件默认在内部调用相应的 `aitheUI` 方法。
+
+### Icon-only mode / 仅图标模式
+
+```html
+<aithe-theme-switch icon-only placement="bottom-end"></aithe-theme-switch>
+```
+
+### Custom handling (prevent default) / 自定义处理（阻止默认行为）
+
+```js
+const switcher = document.querySelector('aithe-theme-switch');
+switcher.addEventListener('aithe-theme-change', (e) => {
+  e.preventDefault();
+  console.log('Category:', e.detail.category, 'Value:', e.detail.value);
+});
+```
+
+### Integration with header / 与页头集成
+
+```html
+<aithe-header show-locale-switch show-theme-switch>
+  <aithe-menu slot="center" mode="horizontal">...</aithe-menu>
+</aithe-header>
+```
+
+The header's `show-theme-switch` attribute renders `<aithe-theme-switch>` internally.
+
+页头的 `show-theme-switch` 属性在内部渲染 `<aithe-theme-switch>`。
+
+### Migration from individual pickers / 从独立选择器迁移
+
+Replace multiple pickers with a single `aithe-theme-switch`:
+
+```html
+<!-- Before / 之前 -->
+<aithe-theme-picker></aithe-theme-picker>
+<aithe-shape-picker></aithe-shape-picker>
+<aithe-shadow-picker></aithe-shadow-picker>
+<aithe-typo-picker></aithe-typo-picker>
+
+<!-- After / 之后 -->
+<aithe-theme-switch></aithe-theme-switch>
+```
+
+The individual pickers (`aithe-theme-picker`, `aithe-shadow-picker`, `aithe-shape-picker`, `aithe-typo-picker`) remain available for standalone use cases (e.g., settings pages, `aithe-theme-preview`).
+
+独立选择器（`aithe-theme-picker`、`aithe-shadow-picker`、`aithe-shape-picker`、`aithe-typo-picker`）仍可用于独立场景（如设置页面、`aithe-theme-preview`）。

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

@@ -0,0 +1,238 @@
+# AitheTypoPicker / AitheTypoPicker 排版选择器
+
+> Typography style picker dropdown with preview icons, keyboard navigation, and built-in typo switch.
+> 排版风格选择器，支持预览图标、键盘导航和内置排版切换。
+>
+> **Note:** For most use cases, consider using the unified [`<aithe-theme-switch>`](theme-switch.md) component instead, which integrates theme, shadow, shape, and typo selection in a single dropdown.
+> **注意：** 大多数场景建议使用统一的 [`<aithe-theme-switch>`](theme-switch.md) 组件，它在单个下拉菜单中整合了主题、阴影、形状和排版选择。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                               | Description (CN)                |
+| --------- | ---------------------------------------------- | ------------------------------- |
+| (default) | No slots — the trigger is rendered internally. | 无插槽 — 触发器由组件内部渲染。 |
+
+## Properties / 属性
+
+| Name      | Type                                                       | Default      | Description (EN)                                                                                                               | Description (CN)                                                                  |
+| --------- | ---------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| value     | `AitheTypoName`                                            | —            | Controlled typo selection. When set, the picker displays this value instead of the global typo. Used by `aithe-theme-preview`. | 受控排版选择。设置后，选择器显示此值而非全局排版。由 `aithe-theme-preview` 使用。 |
+| placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-end' | Dropdown panel placement. Auto-adapts to viewport.                                                                             | 下拉面板位置。自动适应视口。                                                      |
+
+## Events / 事件
+
+| Name              | Detail             | Cancelable | Description (EN)                                                                                                                                                                           | Description (CN)                                                                                                          |
+| ----------------- | ------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| aithe-typo-change | `{ typo: string }` | Yes        | Emitted when a typo is selected. Built-in typo switch (`aitheUI.setTypo()`) runs by default. Call `preventDefault()` to suppress the built-in behavior and handle typo switching manually. | 排版风格选中时发出。默认执行内置切换逻辑（`aitheUI.setTypo()`）。调用 `preventDefault()` 可阻止内置切换，由外部自行处理。 |
+
+## Built-in Typo Styles / 内置排版风格
+
+| Typo     | Description (EN)                                                                                        | Description (CN)                                                            |
+| -------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| minimal  | 3-level hierarchy max, generous spacing, high line-height, breathing room, no dense layout              | 3 级以内层级，宽松间距，高行高，呼吸感与秩序感，禁止密集排布                |
+| business | Complete clear hierarchy, distinct heading levels, strict list/data alignment, structured paragraphs    | 完整清晰层级，标题层级差明确，列表数据严格对齐，规整分段，适合高效扫读      |
+| luxury   | Loose letter-spacing & line-height, ample paragraph whitespace, weight contrast rhythm, refined reading | 宽松字间距与行高，段落留白充裕，字重对比营造节奏，轻盈有序，精致阅读感      |
+| compact  | High information density, small font/line-height/spacing, 1–3 line truncation, minimized gaps           | 高信息密度，字号行高间距偏小，摘要限制 1–3 行截断，最小化间距，高屏幕承载量 |
+
+## CSS Variables / CSS 变量
+
+Typo styles override the following component-used CSS custom properties on `:root`:
+
+| Variable                                | Description (EN)           | Description (CN) |
+| --------------------------------------- | -------------------------- | ---------------- |
+| `--aithe-font-size-xs`                  | Extra-small font size      | 超小字号         |
+| `--aithe-font-size-sm`                  | Small font size            | 小字号           |
+| `--aithe-font-size-md`                  | Medium font size (default) | 中字号（默认）   |
+| `--aithe-font-size-lg`                  | Large font size            | 大字号           |
+| `--aithe-font-size-xl`                  | Extra-large font size      | 特大字号         |
+| `--aithe-font-size-2xl`                 | 2X-large font size         | 超大字号         |
+| `--aithe-font-weight-regular`           | Regular font weight        | 常规字重         |
+| `--aithe-font-weight-medium`            | Medium font weight         | 中等字重         |
+| `--aithe-font-weight-semibold`          | Semibold font weight       | 半粗字重         |
+| `--aithe-font-weight-bold`              | Bold font weight           | 粗体字重         |
+| `--aithe-line-height-tight`             | Tight line height          | 紧凑行高         |
+| `--aithe-line-height-base`              | Base line height           | 基础行高         |
+| `--aithe-line-height-loose`             | Loose line height          | 宽松行高         |
+| `--aithe-space-1` ~ `--aithe-space-10`  | Numeric spacing scale      | 数字刻度间距     |
+| `--aithe-space-xs` ~ `--aithe-space-xl` | Semantic spacing aliases   | 语义间距别名     |
+| `--aithe-control-height-sm`             | Small control height       | 小控件高度       |
+| `--aithe-control-height-md`             | Medium control height      | 中控件高度       |
+| `--aithe-control-height-lg`             | Large control height       | 大控件高度       |
+
+### Token Values by Style / 各风格 Token 值
+
+#### minimal — 极简
+
+| Token                          | Value |
+| ------------------------------ | ----- |
+| `--aithe-font-size-xs`         | 12px  |
+| `--aithe-font-size-sm`         | 14px  |
+| `--aithe-font-size-md`         | 15px  |
+| `--aithe-font-size-lg`         | 18px  |
+| `--aithe-font-size-xl`         | 22px  |
+| `--aithe-font-size-2xl`        | 32px  |
+| `--aithe-font-weight-regular`  | 400   |
+| `--aithe-font-weight-medium`   | 500   |
+| `--aithe-font-weight-semibold` | 600   |
+| `--aithe-font-weight-bold`     | 700   |
+| `--aithe-line-height-tight`    | 1.25  |
+| `--aithe-line-height-base`     | 1.7   |
+| `--aithe-line-height-loose`    | 1.9   |
+| `--aithe-space-1`              | 4px   |
+| `--aithe-space-2`              | 8px   |
+| `--aithe-space-3`              | 14px  |
+| `--aithe-space-4`              | 18px  |
+| `--aithe-space-5`              | 22px  |
+| `--aithe-space-6`              | 28px  |
+| `--aithe-space-7`              | 36px  |
+| `--aithe-space-8`              | 44px  |
+| `--aithe-space-9`              | 52px  |
+| `--aithe-space-10`             | 68px  |
+| `--aithe-control-height-sm`    | 32px  |
+| `--aithe-control-height-md`    | 40px  |
+| `--aithe-control-height-lg`    | 48px  |
+
+#### business — 商务（默认）
+
+| Token                          | Value |
+| ------------------------------ | ----- |
+| `--aithe-font-size-xs`         | 12px  |
+| `--aithe-font-size-sm`         | 13px  |
+| `--aithe-font-size-md`         | 14px  |
+| `--aithe-font-size-lg`         | 16px  |
+| `--aithe-font-size-xl`         | 20px  |
+| `--aithe-font-size-2xl`        | 28px  |
+| `--aithe-font-weight-regular`  | 400   |
+| `--aithe-font-weight-medium`   | 500   |
+| `--aithe-font-weight-semibold` | 600   |
+| `--aithe-font-weight-bold`     | 700   |
+| `--aithe-line-height-tight`    | 1.25  |
+| `--aithe-line-height-base`     | 1.5   |
+| `--aithe-line-height-loose`    | 1.7   |
+| `--aithe-space-1`              | 4px   |
+| `--aithe-space-2`              | 8px   |
+| `--aithe-space-3`              | 12px  |
+| `--aithe-space-4`              | 16px  |
+| `--aithe-space-5`              | 20px  |
+| `--aithe-space-6`              | 24px  |
+| `--aithe-space-7`              | 32px  |
+| `--aithe-space-8`              | 40px  |
+| `--aithe-space-9`              | 48px  |
+| `--aithe-space-10`             | 64px  |
+| `--aithe-control-height-sm`    | 32px  |
+| `--aithe-control-height-md`    | 40px  |
+| `--aithe-control-height-lg`    | 48px  |
+
+#### luxury — 轻奢
+
+| Token                          | Value |
+| ------------------------------ | ----- |
+| `--aithe-font-size-xs`         | 11px  |
+| `--aithe-font-size-sm`         | 13px  |
+| `--aithe-font-size-md`         | 15px  |
+| `--aithe-font-size-lg`         | 18px  |
+| `--aithe-font-size-xl`         | 24px  |
+| `--aithe-font-size-2xl`        | 36px  |
+| `--aithe-font-weight-regular`  | 400   |
+| `--aithe-font-weight-medium`   | 500   |
+| `--aithe-font-weight-semibold` | 500   |
+| `--aithe-font-weight-bold`     | 600   |
+| `--aithe-line-height-tight`    | 1.3   |
+| `--aithe-line-height-base`     | 1.7   |
+| `--aithe-line-height-loose`    | 1.9   |
+| `--aithe-space-1`              | 4px   |
+| `--aithe-space-2`              | 8px   |
+| `--aithe-space-3`              | 14px  |
+| `--aithe-space-4`              | 20px  |
+| `--aithe-space-5`              | 24px  |
+| `--aithe-space-6`              | 30px  |
+| `--aithe-space-7`              | 38px  |
+| `--aithe-space-8`              | 48px  |
+| `--aithe-space-9`              | 56px  |
+| `--aithe-space-10`             | 72px  |
+| `--aithe-control-height-sm`    | 34px  |
+| `--aithe-control-height-md`    | 42px  |
+| `--aithe-control-height-lg`    | 50px  |
+
+#### compact — 紧凑信息流
+
+| Token                          | Value |
+| ------------------------------ | ----- |
+| `--aithe-font-size-xs`         | 11px  |
+| `--aithe-font-size-sm`         | 12px  |
+| `--aithe-font-size-md`         | 13px  |
+| `--aithe-font-size-lg`         | 14px  |
+| `--aithe-font-size-xl`         | 16px  |
+| `--aithe-font-size-2xl`        | 20px  |
+| `--aithe-font-weight-regular`  | 400   |
+| `--aithe-font-weight-medium`   | 500   |
+| `--aithe-font-weight-semibold` | 600   |
+| `--aithe-font-weight-bold`     | 700   |
+| `--aithe-line-height-tight`    | 1.15  |
+| `--aithe-line-height-base`     | 1.35  |
+| `--aithe-line-height-loose`    | 1.5   |
+| `--aithe-space-1`              | 2px   |
+| `--aithe-space-2`              | 4px   |
+| `--aithe-space-3`              | 8px   |
+| `--aithe-space-4`              | 12px  |
+| `--aithe-space-5`              | 16px  |
+| `--aithe-space-6`              | 20px  |
+| `--aithe-space-7`              | 24px  |
+| `--aithe-space-8`              | 32px  |
+| `--aithe-space-9`              | 40px  |
+| `--aithe-space-10`             | 48px  |
+| `--aithe-control-height-sm`    | 28px  |
+| `--aithe-control-height-md`    | 36px  |
+| `--aithe-control-height-lg`    | 44px  |
+
+> **Note:** Each typo style overrides the same set of component-used tokens (`--aithe-font-size-*`, `--aithe-font-weight-*`, `--aithe-line-height-*`, `--aithe-space-*`, `--aithe-control-height-*`), creating distinct visual hierarchies and reading experiences.
+> **注意：** 每种排版风格覆盖同一组组件已使用的 token（`--aithe-font-size-*`、`--aithe-font-weight-*`、`--aithe-line-height-*`、`--aithe-space-*`、`--aithe-control-height-*`），形成不同的视觉层级和阅读体验。
+
+## Examples / 示例
+
+### Default usage (built-in typo switch) / 默认用法（内置切换）
+
+```html
+<aithe-typo-picker placement="bottom-end"></aithe-typo-picker>
+```
+
+No event listener is required — the component calls `aitheUI.setTypo()` internally by default.
+
+无需监听事件 — 组件默认在内部调用 `aitheUI.setTypo()`。
+
+### Custom typo handling (prevent default) / 自定义排版处理（阻止默认行为）
+
+```js
+const picker = document.querySelector('aithe-typo-picker');
+picker.addEventListener('aithe-typo-change', (e) => {
+  e.preventDefault();
+  console.log('Typo selected:', e.detail.typo);
+});
+```
+
+### Programmatic API / 编程式 API
+
+```js
+import { aitheUI } from '@aithe/aithe-ui';
+
+aitheUI.setTypo('luxury');
+console.log(aitheUI.getTypo()); // 'luxury'
+
+const unsubscribe = aitheUI.onTypoChange(() => {
+  console.log('Typo changed to:', aitheUI.getTypo());
+});
+```
+
+### Typo × Theme × Shape × Shadow / 排版 × 主题 × 形状 × 阴影
+
+Typo styles are orthogonal to color themes, shapes, and shadows and can be freely combined:
+
+排版风格与颜色主题、形状、阴影相互独立，可自由组合：
+
+```html
+<!-- Dark theme + rounded shape + cyber shadow + luxury typo -->
+<aithe-theme-picker value="dark"></aithe-theme-picker>
+<aithe-shape-picker value="rounded"></aithe-shape-picker>
+<aithe-shadow-picker value="cyber"></aithe-shadow-picker>
+<aithe-typo-picker value="luxury"></aithe-typo-picker>
+```