refactor: 重构文档结构，采用渐进式信息披露模式

将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
2026-03-06 15:11:36 +08:00
parent 98098dc911
commit 124ef0e5ce
41 changed files with 5238 additions and 2228 deletions
--- a/docs/fonts.md
+++ b/docs/fonts.md
@@ -0,0 +1,198 @@
+# 字体主题系统
+
+字体主题系统允许你定义可复用的字体配置，统一管理演示文稿的字体样式。
+
+## 定义字体主题
+
+在 `metadata.fonts` 中定义命名字体配置：
+
+```yaml
+metadata:
+  size: "16:9"
+  fonts:
+    title:
+      family: "cjk-sans"
+      size: 44
+      bold: true
+      color: "#2c3e50"
+    body:
+      family: "sans"
+      size: 18
+      color: "#34495e"
+      line_spacing: 1.5
+  fonts_default: "@body"  # 默认字体（可选）
+
+slides:
+  - elements:
+      - type: text
+        content: "标题文本"
+        box: [1, 1, 8, 1]
+        font: "@title"  # 引用字体主题
+
+      - type: text
+        content: "正文内容"
+        box: [1, 2.5, 8, 2]
+        # 未定义 font 时使用 fonts_default
+```
+
+## 预设字体类别
+
+系统提供五种预设字体类别，自动映射到跨平台通用字体：
+
+| 类别 | 映射字体 | 说明 |
+|------|---------|------|
+| `sans` | Arial | 西文无衬线 |
+| `serif` | Times New Roman | 西文衬线 |
+| `mono` | Courier New | 等宽字体 |
+| `cjk-sans` | Microsoft YaHei | 中文无衬线 |
+| `cjk-serif` | SimSun | 中文衬线 |
+
+### 使用预设类别
+
+```yaml
+metadata:
+  fonts:
+    body:
+      family: "cjk-sans"  # 自动映射到 Microsoft YaHei
+      size: 18
+```
+
+## 字体引用方式
+
+### 1. 整体引用
+
+完全使用定义的字体配置：
+
+```yaml
+font: "@title"
+```
+
+### 2. 继承覆盖
+
+继承字体配置并覆盖特定属性：
+
+```yaml
+font:
+  parent: "@title"
+  size: 60  # 覆盖字号
+  color: "#ff0000"  # 覆盖颜色
+```
+
+### 3. 独立定义
+
+完全自定义字体：
+
+```yaml
+font:
+  family: "SimSun"
+  size: 24
+  bold: true
+```
+
+## 扩展字体属性
+
+除了基础属性（size、bold、italic、color、align），还支持：
+
+### 字体样式
+
+- `family`：字体族名称或预设类别
+- `underline`：下划线（true/false）
+- `strikethrough`：删除线（true/false）
+
+### 段落属性
+
+- `line_spacing`：行距倍数（如 1.5）
+- `space_before`：段前间距（磅）
+- `space_after`：段后间距（磅）
+
+### 高级属性
+
+- `baseline`：基线位置（normal/superscript/subscript）
+- `caps`：大小写转换（normal/allcaps/smallcaps）
+
+## 完整示例
+
+```yaml
+metadata:
+  size: "16:9"
+  fonts:
+    heading:
+      family: "cjk-sans"
+      size: 32
+      bold: true
+      color: "#2c3e50"
+      line_spacing: 1.2
+      space_after: 12
+    body:
+      family: "sans"
+      size: 18
+      color: "#34495e"
+      line_spacing: 1.5
+  fonts_default: "@body"
+
+slides:
+  - elements:
+      - type: text
+        content: "章节标题"
+        box: [1, 1, 8, 1]
+        font: "@heading"
+
+      - type: text
+        content: "正文内容\n支持多行文本"
+        box: [1, 2, 8, 2]
+        font:
+          parent: "@body"
+          underline: true
+
+      - type: table
+        position: [1, 4]
+        col_widths: [3, 3]
+        data:
+          - ["列1", "列2"]
+          - ["数据1", "数据2"]
+        font: "@body"
+        header_font:
+          parent: "@body"
+          bold: true
+          color: "#ffffff"
+        style:
+          header_bg: "#3498db"
+```
+
+## 跨域引用
+
+### 文档元素引用模板库字体
+
+```yaml
+# templates.yaml（模板库）
+metadata:
+  size: "16:9"
+  fonts:
+    template-title:
+      family: "cjk-sans"
+      size: 44
+      bold: true
+
+# presentation.yaml（文档）
+metadata:
+  size: "16:9"
+
+slides:
+  - elements:
+      - type: text
+        content: "标题"
+        font: "@template-title"  # 文档元素可以引用模板库字体
+```
+
+### 引用规则
+
+- 文档元素 → 文档字体
+- 文档元素 → 模板库字体
+- 模板元素 → 模板库字体
+
+## 相关文档
+
+- [外部模板库](templates/external-library.md) - 模板库字体配置
+- [作用域系统](../development/scope-system.md) - 字体作用域详细规则
+
+[返回文档索引](../README.md)