suanming/TYPOGRAPHY_GUIDE.md

神机阁字体规范指南

📖 概述

本指南定义了神机阁项目的统一字体规范系统，旨在解决项目中字体大小混乱的问题，建立一致的视觉层次和用户体验。

🎯 设计原则

1. 语义化命名 - 使用语义化的类名，如 text-heading-lg 而不是 text-2xl
2. 响应式优先 - 所有字体规范都考虑了移动端适配
3. 可访问性 - 确保足够的对比度和可读性
4. 一致性 - 统一的行高、字重和字间距规范
5. 中文优化 - 专门为中文内容优化的字体栈

📏 字体规范系统

🏆 显示级标题 (Display)

用于首页主标题和重要页面的超大标题

.text-display-xl  /* 56px - 首页主标题 */
.text-display-lg  /* 48px - 重要页面标题 */
.text-display-md  /* 40px - 次要页面标题 */

使用场景：

• 首页 Hero 区域主标题
• 重要功能页面的主标题
• 营销页面的大标题

📝 标题系列 (Heading)

用于页面内容的层次化标题

.text-heading-xl  /* 32px - H1 标题 */
.text-heading-lg  /* 28px - H2 标题 */
.text-heading-md  /* 24px - H3 标题 */
.text-heading-sm  /* 20px - H4 标题 */
.text-heading-xs  /* 18px - H5 标题 */

使用场景：

• 页面主标题 (H1)
• 章节标题 (H2-H3)
• 卡片标题 (H4-H5)
• 组件内部标题

📄 正文系列 (Body)

用于页面的主要内容文字

.text-body-xl     /* 18px - 重要描述文字 */
.text-body-lg     /* 16px - 标准正文 (默认) */
.text-body-md     /* 14px - 次要正文 */
.text-body-sm     /* 12px - 辅助信息 */

使用场景：

• 重要的介绍文字 (body-xl)
• 标准正文内容 (body-lg)
• 卡片描述文字 (body-md)
• 提示信息、时间戳 (body-sm)

🏷️ 标签系列 (Label)

用于表单标签和小标签

.text-label-lg    /* 14px - 表单标签 */
.text-label-md    /* 12px - 小标签 */
.text-label-sm    /* 11px - 微小标签 */

使用场景：

• 表单字段标签
• 状态标签
• 分类标签
• 徽章文字

🔘 按钮系列 (Button)

用于按钮内的文字

.text-button-lg   /* 16px - 大按钮 */
.text-button-md   /* 14px - 标准按钮 */
.text-button-sm   /* 12px - 小按钮 */

使用场景：

• 主要操作按钮 (button-lg)
• 标准按钮 (button-md)
• 次要按钮和图标按钮 (button-sm)

🎨 字体族规范

中文字体栈

.font-chinese
/* 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', '微软雅黑', 'Noto Sans SC', 'STHeiti', 'WenQuanYi Micro Hei', sans-serif */

中文衬线字体

.font-chinese-serif
/* 'Noto Serif SC', 'STSong', 'SimSun', '宋体', serif */

英文字体

.font-english
/* 'Inter', 'Helvetica Neue', 'Arial', sans-serif */

数字字体

.font-numeric
/* 确保数字对齐的等宽字体 */

📱 响应式规范

所有字体规范都内置了响应式适配：

• 移动端 (≤768px): 字体大小适当缩小
• 超小屏 (≤480px): 进一步优化字体大小
• 桌面端 (>768px): 使用标准字体大小

🔧 使用方法

1. HTML 中使用

<!-- 页面主标题 -->
<h1 class="text-heading-xl font-chinese text-red-600">神机阁</h1>

<!-- 卡片标题 -->
<h3 class="text-heading-sm font-chinese">八字命理</h3>

<!-- 正文内容 -->
<p class="text-body-lg font-chinese">这是标准正文内容</p>

<!-- 按钮文字 -->
<button class="text-button-md font-chinese">立即分析</button>

2. React 组件中使用

// 推荐：使用语义化类名
<ChineseCardTitle className="text-heading-md font-chinese">
  十二宫位详解
</ChineseCardTitle>

// 避免：使用数字类名
<ChineseCardTitle className="text-xl">
  十二宫位详解
</ChineseCardTitle>

3. CSS 中使用

/* 自定义组件样式 */
.custom-title {
  @apply text-heading-lg font-chinese font-semibold;
  color: var(--cinnabar-500);
}

🎯 迁移指南

常见替换映射

旧类名	新类名	用途
text-3xl	text-display-md	页面主标题
text-2xl	text-heading-xl	大标题
text-xl	text-heading-lg	中标题
text-lg	text-heading-md	小标题
text-base	text-body-lg	标准正文
text-sm	text-body-md	次要正文
text-xs	text-body-sm	辅助信息

迁移步骤

1. 识别用途 - 确定文字的语义用途（标题、正文、标签等）
2. 选择规范 - 根据用途选择对应的字体规范
3. 添加字体族 - 确保添加 font-chinese 类
4. 测试响应式 - 在不同设备上测试显示效果

✅ 最佳实践

✅ 推荐做法

<!-- 语义化命名 -->
<h1 class="text-display-lg font-chinese">神机阁</h1>
<h2 class="text-heading-xl font-chinese">命理分析</h2>
<p class="text-body-lg font-chinese">专业的命理分析服务</p>
<button class="text-button-md font-chinese">开始分析</button>

<!-- 数字内容使用数字字体 -->
<span class="text-body-lg font-numeric">2024</span>

<!-- 特殊标题使用衬线字体 -->
<h1 class="text-display-xl font-chinese-serif">神机阁</h1>

❌ 避免做法

<!-- 避免：混用数字类名 -->
<h1 class="text-4xl">标题</h1>
<p class="text-lg">正文</p>

<!-- 避免：忘记添加字体族 -->
<h1 class="text-heading-xl">标题</h1>

<!-- 避免：不合适的字体大小组合 -->
<button class="text-xs">按钮</button> <!-- 太小 -->
<p class="text-3xl">正文</p> <!-- 太大 -->

🔍 常见问题

Q: 什么时候使用 display 系列？

A: 仅用于首页主标题和重要页面的超大标题，不要在普通内容中使用。

Q: 如何选择合适的字体大小？

A: 根据内容的重要性和层次选择：

• 页面标题 → heading 系列
• 正文内容 → body 系列
• 表单标签 → label 系列
• 按钮文字 → button 系列

Q: 移动端需要特殊处理吗？

A: 不需要，所有字体规范都内置了响应式适配。

Q: 可以自定义字体大小吗？

A: 不推荐。如果确实需要，请先考虑是否可以使用现有规范，或者提出新的规范需求。

📊 字体规范对照表

类名	桌面端	移动端	行高	字重	用途
text-display-xl	56px	40px	1.1	800	首页主标题
text-display-lg	48px	36px	1.1	700	重要页面标题
text-display-md	40px	32px	1.2	700	次要页面标题
text-heading-xl	32px	28px	1.25	600	H1 标题
text-heading-lg	28px	24px	1.3	600	H2 标题
text-heading-md	24px	20px	1.35	600	H3 标题
text-heading-sm	20px	18px	1.4	600	H4 标题
text-heading-xs	18px	16px	1.4	600	H5 标题
text-body-xl	18px	16px	1.6	400	重要描述
text-body-lg	16px	16px	1.6	400	标准正文
text-body-md	14px	14px	1.6	400	次要正文
text-body-sm	12px	12px	1.5	400	辅助信息
text-label-lg	14px	14px	1.4	500	表单标签
text-label-md	12px	12px	1.4	500	小标签
text-label-sm	11px	11px	1.4	500	微小标签
text-button-lg	16px	16px	1.4	600	大按钮
text-button-md	14px	14px	1.4	600	标准按钮
text-button-sm	12px	12px	1.4	600	小按钮

---

更新日期: 2024年12月 版本: 1.0.0 维护者: 神机阁开发团队