BestBlogs UI 执行规范与落地手册

更新时间：2026-03-27 状态：Draft / Execution

---

1. 文档定位

本文件用于承接 5-DESIGN.md 中定义的设计原则，并将其转化为可执行的 UI 规范。

本文档主要回答：

• 颜色、字体、间距、布局如何使用
• 组件与状态如何落地
• 页面模板如何在不同设备上实现
• 前端与设计执行时应遵循哪些统一规则

若具体实现与顶层设计原则冲突，以 5-DESIGN.md 为准。

---

2. 总体执行原则

2.1 语义优先于硬编码

优先使用设计 token 和语义变量，不直接在新代码中使用硬编码颜色和零散样式。
现有设计规范已经明确禁止在新代码中继续扩散 slate-* 等硬编码色，应逐步迁移到语义 token。

2.2 复用优先于新增

同类对象尽量复用已有组件与样式，不轻易另起一套视觉语言。
现有设计规范已明确禁止另起卡片样式，优先复用统一卡片组件。

2.3 内容对象优先于装饰元素

卡片、列表项、详情页的重点是标题、摘要、来源、标签、状态，而不是视觉填充。

2.4 响应式不是等比缩放

移动端与桌面端要根据任务差异调整信息优先级，而不是简单压缩桌面布局。

---

3. 设计 Token

3.1 品牌色

现有规范定义如下：

• Ink：#1a365d
• Amber：#d97706
• Paper：#fefdfb

语义说明：

• Ink：知识深度、专业性、主品牌色
• Amber：高亮、精选、重要操作
• Paper：温和纸张感背景

3.2 语义变量

变量来源：

• bestblogs-app/src/styles/globals.css
• bestblogs-app/tailwind.config.ts

建议维持以下主语义层：

• 背景：--bg-paper / --bg-surface
• 文本：--text-primary / --text-secondary / --text-tertiary / --text-muted
• 边框：--border-default / --border-muted / --border-emphasis
• 交互：--color-link / --focus-ring

3.3 Amber 使用规范

Amber 仅用于“值得注意”的信号位。
当前推荐用法如下：

场景	建议
侧边栏 active 项	bg-amber-muted text-ink
Featured / 精选内容	左侧强调线或小面积高亮
主 CTA 按钮	Amber 主按钮
评分 / 星标	Amber 文本或图标
Pro 标识	弱化 amber 底 + 深色文字
选中态指示器	细窄 amber 指示线

禁止：

• 破坏性操作
• 普通正文文字
• 大面积背景填充
• 纯装饰边框

3.4 暗色模式

现有规范要求：使用 next-themes + class 切换；新增 light token 时必须补齐 dark token；暗色背景使用 near-black 而非纯黑；暗色文字使用 off-white 而非纯白。

执行要求：

• 新增 token 时同步定义 light / dark
• 不允许只在浅色模式下验证页面
• 暗色下卡片阴影应转为更克制的边框与轻阴影组合
• Amber 在暗色下自动亮化，但不提高饱和度到抢眼程度

---

4. 字体与排版

4.1 字体角色

现有规范已定义四种字体语义：

• 标题：font-heading
• 正文 / UI：font-body / font-sans
• 代码：font-mono
• 数字：font-numeric

约束：

• 全站标题统一使用 font-heading
• 正文和 UI 不混用装饰性 serif
• 代码区只使用等宽字体
• 数值型信息优先使用数字字体以保证对齐

4.2 排版层级

现有三层语义模型保留：

层级	用途	建议
L1	卡片 / 列表项标题	text-lg font-heading font-semibold leading-snug
L2	摘要 / 描述	text-sm text-muted-foreground leading-relaxed
L3	来源 / 日期 / 时长	text-xs text-muted-foreground

补充规则：

• L1 与 L2 字号差距至少 4px
• L3 必须明显弱于 L2
• 页面 H1 使用 text-2xl md:text-3xl font-heading font-bold

4.3 元信息格式

统一格式：

来源名 · 日期 · 阅读时长

现有规范已明确：分隔符统一使用 ·，最多 3 个维度，评分 / 星标独立展示。

补充要求：

• 元信息默认单行
• 优先级顺序：来源 > 日期 > 成本 / 时长
• 不把营销语和功能性文字混入元信息区

4.4 标签规则

现有规范：

• 每卡最多 3 个标签
• 多余折叠为 +N
• 使用统一 BbBadge 组件

补充要求：

• 标签只起补充判断作用
• 不得用标签替代标题与摘要
• 分类 / 语言 / 主题标签应有稳定 variant
• 标签行不应压缩标题可读性

4.5 正文排版

详情页正文区执行要求：

• 控制单行长度，避免过宽
• 行高优先阅读舒适度
• 标题、正文、引用、列表、代码块需清晰分层
• 正文中的强调色极度克制
• 正文区不嵌入与阅读无关的高噪音操作

---

5. 间距系统

5.1 语义间距

现有规范采用 4px grid，定义如下：

Token	值	用途
tight	8px	同一元素内部间距
element	16px	相关元素之间
component	32px	独立组件之间
section	80px	页面大区块，主要用于营销页

5.2 间距使用规则

现有规范建议：

• 页面标题区 → 内容区：mb-component
• 筛选器 → 列表：mb-component
• 列表项之间：space-y-element 或 gap-element
• 卡片内部：p-element，内部 gap-tight
• 侧边栏分组：组间 mt-component
• 标题上下比例：上方间距大于下方

执行补充：

• 卡片内部偏紧，组件之间偏松
• 营销页 section 间距可以更大
• 设置页不要沿用营销页的大节奏

---

6. 容器与布局

6.1 页面宽度策略

• 营销页：允许更宽的 section 容器
• 列表页：强调主内容区稳定宽度，避免内容过散
• 阅读页：正文区宽度优先阅读舒适度
• 设置页：优先明确表单路径与说明关系

6.2 侧栏策略

适用于内容工作台型页面：

• 左侧：导航 / 入口
• 中间：主内容区
• 右侧：辅助信息区（如有）

执行要求：

• 主内容区永远是视觉中心
• 右侧辅助区对比度低于主内容区
• 辅助区不承载主决策信息
• 中小屏不强制保留三栏

6.3 正文宽度

阅读页正文需保持可长时间阅读的宽度，不追求“多列塞满”。
若提供宽窄模式，需保持阅读逻辑不变。现有规范已包含阅读页宽窄模式和 serif 偏好存储。

---

7. 页面模板执行规范

7.1 模板 A：品牌 / 营销页

执行要点：

• H1 + 副标题 + 关键路径 CTA 构成首屏
• 视觉强调品牌态度与核心工作流，不堆砌功能点
• 插图与视觉辅助服从信息表达
• 可使用更大的留白和 section 节奏

不应出现：

• Dashboard 式大面板
• 复杂功能矩阵
• 过强 AI 炫技视觉

7.2 模板 B：内容列表 / 工作台页

执行要点：

• 页头信息简洁，突出当前入口含义
• 筛选器默认轻量化
• 列表项优先显示标题、摘要、来源、少量标签、状态
• 卡片动作默认弱化，hover 或选中时再增强

不应出现：

• 一屏塞入过多筛选与排序控件
• 标题被缩略图压制
• 列表中出现多个主按钮

7.3 模板 C：阅读详情页

执行要点：

• 顶部区域快速说明主题、来源、价值线索
• 正文区最大化
• AI 伴读在结构上从属于阅读区
• 相关推荐放在次级位置
• 划线、收藏、提问等动作轻量存在

不应出现：

• 正文旁过重的操作区
• 频繁闪动或吸附的浮层
• 与正文竞争的视觉噪音

7.4 模板 D：设置 / 管理页

执行要点：

• 信息分组明确
• 每组只解决一个问题
• 配置项后应尽量说明结果
• 表单控件、说明文字、保存反馈形成稳定结构

不应出现：

• 技术术语堆叠
• 不可解释的系统状态
• 过大的装饰模块

---

8. 内容卡片规范

8.1 通用卡片结构

推荐结构：

1. 标题（L1）
2. 摘要（L2，可选）
3. 元信息（L3）
4. 标签区（可选）
5. 轻量操作区（按需显示）

统一原则：

• 标题优先于封面
• 摘要不宜过长
• 元信息和标签保持弱化
• 操作区默认不抢眼

8.2 文章卡片

重点字段：

• 标题
• 摘要
• 来源
• 日期
• 阅读时长
• 标签

执行要求：

• 封面图可有可无
• 无图时不补无意义占位图
• 阅读时长清晰但不抢标题注意力

8.3 播客卡片

重点字段：

• 标题
• 节目 / 嘉宾
• 时长
• 摘要
• 是否有转录

执行要求：

• 时长信息必须明显
• 摘要比文章卡片更偏“值得听什么”
• 若有转录标识，可作为辅助判断信号

8.4 视频卡片

重点字段：

• 标题
• 时长
• 摘要 / 章节
• 来源

执行要求：

• 不让大缩略图主导整个卡片
• 章节存在时优先展示价值
• 时长与标题组合帮助判断阅读成本

8.5 推文 / 线程卡片

重点字段：

• 作者
• 文本片段
• 线程上下文
• 价值说明

执行要求：

• 优先头像 + 文本，不必强求缩略图
• 更强调“是否值得展开”
• 弱化社交平台式互动元素

8.6 早报条目

重点字段：

• 条目标题
• 条目摘要
• 来源
• 快速动作（稍后读 / 收藏 / 打开）

执行要求：

• 像可信赖编辑递交内容
• 条目密度较高但层次清晰
• 单条操作简洁，不做重卡片化堆叠

8.7 研究报告卡片 / 列表项

重点字段：

• 标题
• 主题
• 结构摘要
• 最近更新或章节数

执行要求：

• 更强调“结构化成果”
• 不与普通文章卡片完全同构
• 可增加更强的目录 / 结构提示

---

9. 组件规范

9.1 Button

层级：

• Primary：当前场景唯一主动作
• Secondary：常见但非主线动作
• Ghost / Tertiary：辅助动作

规则：

• 一个区域尽量只有一个 Primary
• 破坏性动作不用 Amber
• 文案使用结果导向表达

9.2 Icon Button

适用：

• 收藏
• 分享
• 稍后读
• 标记已读
• 更多操作

规则：

• 必须有 aria-label
• 不单独承担关键主路径
• 小尺寸时确保可触控面积满足可访问性要求

9.3 Badge / Tag

variant 建议：

• category
• language
• topic
• status
• pro
• featured

规则：

• 单行不超过 3 个主要标签
• Featured / Pro / 状态类需明显区分
• 不能形成 badge 墙

9.4 Tabs

适用：

• 内容入口切换
• 阅读模式切换
• 设置分组切换

规则：

• tab 数量不宜过多
• 选中态清晰
• 在移动端避免过于拥挤，可横向滚动

9.5 Search

适用：

• 内容搜索
• 来源搜索
• 设置项搜索

规则：

• 输入框优先简洁
• 不叠加过多高级筛选入口
• 占位提示使用用户语言而非内部术语

9.6 Filters

适用：

• 列表页筛选
• 内容广场与推荐流精细筛选

规则：

• 默认轻量显示
• 常用项先展示
• 高级项折叠
• 移动端优先使用横向 pills、底部抽屉或轻量弹层

9.7 Dropdown / More Menu

适用：

• 辅助操作
• 管理型动作
• 次级导航

规则：

• 重要操作不应藏在过深层级
• 菜单项命名使用统一术语
• 危险操作分组并明显区隔

9.8 Dialog / Sheet

适用：

• 确认操作
• 快速配置
• 移动端补充面板

规则：

• 对话框只解决一个问题
• 避免在对话框里再堆多层流程
• 移动端可用 bottom sheet 承载轻量配置

9.9 Toast / Feedback

适用：

• 保存成功
• 标记完成
• 错误反馈
• 撤销入口

规则：

• 信息短、明确
• 成功反馈不过度抢眼
• 错误反馈提供可理解原因或下一步

---

10. 状态规范

10.1 基础交互状态

所有交互组件至少定义：

• default
• hover
• focus-visible
• active
• selected
• disabled

现有规范已经要求键盘可操作和明确 focus ring。

10.2 内容状态

统一支持：

• 未读
• 已读
• 稍后读
• 已收藏
• 已划线
• 不感兴趣
• 已分享

术语与命名应使用 10-TERMINOLOGY.md 中已确认的用户可见表达。

10.3 已读状态

推荐组合表达：

• 标题对比度略降
• 摘要权重降低
• 操作按钮更隐性
• 可选轻量“已读”提示

不能只靠颜色细微变化。

10.4 稍后读 vs 收藏

必须区分：

• 稍后读：短期任务感
• 收藏：长期保存感

视觉不应完全相同，避免“都叫保存”。

10.5 不感兴趣

表现方向：

• 减少类似内容
• 让系统更懂我

避免表现成：

• 强烈删除
• 永久屏蔽世界
• 过度负面反馈

10.6 页面状态

所有页面都应设计：

• loading / skeleton
• empty
• error
• no permission
• onboarding needed

10.7 空状态

空状态至少要回答：

• 为什么这里为空
• 可以做什么
• 这样做之后会得到什么

品牌文档中已经强调，新用户引导应让用户感觉“BestBlogs 开始理解我了”，而不是“我在填一份问卷”。空状态与引导页应继承这一点。

10.8 信号系统组件映射（主映射 + 受控例外）

为避免质量信号、相关性信号、个性化信号在实现层混用，执行以下映射规则：

信号类型	主映射（默认）	允许的受控例外	禁止
质量信号	featured / quality 类 badge，或卡片左侧弱强调线	详情页可增加简短“为何推荐”说明区	冒充个性化文案（如“因为你看过”）
相关性信号	轻量说明文案或弱化标签（低于质量信号视觉权重）	在列表高密场景可折叠到 +N 或 tooltip	使用与质量信号同等高亮样式
个性化信号	来源于入口语义（如“为你推荐”“来自我的关注”）+ 轻提示	详情页可展示一条来源解释	伪装成公共权威判断（如“平台认证必读”）

执行补充：

• 同一内容对象同屏最多 1 个强信号（质量信号优先）
• 若同时展示多类信号，视觉权重必须满足：质量 > 个性化 > 相关性
• 复杂页面允许“主表达 + 次表达”组合，但必须在 PR 描述中说明理由

---

11. 动效规范

11.1 动效原则

现有规范明确：动效服务理解而非装饰。

执行要求：

• 动效只服务状态切换、结构变化、轻微反馈
• 不使用长时间循环动画
• 不使用无意义背景动效
• 不让动效与阅读主区竞争注意力

11.2 允许的动效场景

• hover 反馈
• 展开 / 折叠
• 轻量卡片入场
• 选中态切换
• 对话框 / 抽屉开合

11.3 约束

现有规范要求：禁止大面积无目的动画；opacity-0 初始态必须配合 animation-fill-mode: forwards；尊重 prefers-reduced-motion。

执行补充：

• 所有入场动画必须可被关闭或自然跳过
• 列表加载不使用炫目骨架动画
• 深读页尽量减少持续动画元素

---

12. 响应式规范

12.1 核心原则

• 移动端优先快速扫读和轻量操作
• 桌面端优先长时间阅读和多维筛选
• 不允许关键判断信息只在 hover 可见

12.2 移动端

现有规范要求：

• 最小触控区域 44×44
• 支持安全区
• 筛选器适合横向滚动或轻量入口

执行补充：

• 列表项可减少摘要长度，但不能省掉核心判断信息
• 操作收敛到主线和更多菜单
• 底部导航与浮层不能遮挡核心内容

12.3 桌面端

执行要求：

• 允许更完整的摘要与辅助信息
• 允许右侧辅助区，但不与主阅读区竞争
• 筛选维度可适度增加，但保持轻量默认态

12.4 Hover 替代策略

凡是在桌面依赖 hover 才暴露的信息，移动端都必须提供可见或可触达替代方案。

---

13. 可访问性规范

13.1 基础要求

现有规范要求：

• 触控区域最小 44×44
• 交互组件必须有 aria-label 或语义 role
• 键盘可操作
• 明确 focus-visible 样式

最小验收阈值：

• 正文与关键 UI 文本满足 WCAG AA 对比度（普通文本 >= 4.5:1，大文本 >= 3:1）
• 所有可交互控件必须可通过键盘到达并触发（Tab / Enter / Space）
• focus-visible 在浅色和暗色下均清晰可见，且不能被自定义样式移除
• 非文本状态（已读、错误、成功）必须同时有文本或图标语义，不可仅靠颜色

13.2 内容对象语义

现有规范建议卡片使用 role="article" 并支持键盘访问。

补充要求：

• 列表页内容对象尽量保持语义化结构
• tab、dialog、menu 等使用标准语义角色
• 标题结构遵循文档层级，不随意跳级

13.3 状态可感知

• 已读 / 未读不能只靠颜色区分
• 状态类 badge 不能作为唯一信息来源
• 成功 / 错误反馈应同时具备文字提示

---

14. 页面级参考规范

14.1 内容广场

页面目标：

• 面向公共高质量内容的开放浏览入口

执行重点：

• 页面标题清晰
• 筛选器轻量化
• 卡片以扫描判断为核心
• 公共质量信号清楚但不泛滥
• Free 可见公共价值，Pro 触点只在“个性化收益”明确时出现
• 不在首屏列表中插入高干扰升级条

术语应统一为“内容广场（Explore）”。

14.2 我的早报

页面目标：

• 提供每天最值得先看的个人化内容

执行重点：

• 有“递交感”
• 条目紧凑但层次清楚
• 支持稍后读、收藏、打开
• 不做成普通瀑布流
• Pro 触点强调“工作流增益”（如更完整伴读能力），不抢正文入口
• 邮件与站内触点语气一致，保持编辑递交感

14.3 公共早报

页面目标：

• 面向所有用户的公共高质量内容整理

执行重点：

• 强调公共判断力
• 强调“今天值得看什么”
• 与我的早报形成配对体验，但语义上更偏公共
• 可出现轻量 Pro 升级入口，但不削弱公共早报本身的独立价值

14.4 为你推荐

页面目标：

• 围绕用户兴趣和行为形成持续推荐流

执行重点：

• 解释性优于神秘感
• 个性化信号清晰
• 轻量反馈入口明显，如“不感兴趣”
• Pro 触点优先绑定“更适合我”的具体收益，不用功能堆砌文案

14.5 我的关注

页面目标：

• 以用户关注来源为主组织内容入口

执行重点：

• 来源关系清晰
• “关注”与“订阅 Pro”严格区分
• 来源维度与内容维度组织有序
• 升级引导不得替代“关注来源”主路径，不制造动作歧义

术语上必须使用“关注”，而不是“订阅来源”。

14.6 阅读详情页

页面目标：

• 帮助用户快速理解并进入深读

执行重点：

• 顶部摘要、元信息、结构清晰
• 正文最大化
• AI 伴读位于辅助位置
• 划线、提问、收藏等动作轻量嵌入
• Pro 引导仅允许出现在自然断点（如章节末、侧栏次级位）
• 禁止在连续阅读区插入打断式升级弹层

14.7 研究报告页

页面目标：

• 面向更结构化、更可复用的阅读成果

执行重点：

• 强目录
• 强层级
• 强回顾感
• 支持在未来与研究会话、深度笔记等能力衔接
• Pro 能力可在工具区清晰标注，但不得影响报告主体阅读路径

产品文档已把研究与沉淀视为后续自然生长方向。

---

15. 实现与维护规则

15.1 新组件 Checklist

沿用现有规范并补充如下：

• [ ] 字体使用正确语义
• [ ] 颜色使用语义 token
• [ ] 间距使用语义 token
• [ ] 已验证 light / dark
• [ ] 已验证移动端
• [ ] 文案进入 messages 文件，不硬编码
• [ ] 已验证可访问性
• [ ] 已对照对应页面模板与内容对象规范
• [ ] 术语符合 10-TERMINOLOGY.md（无废弃表达）
• [ ] 已运行术语扫描（禁用词）并完成人工语境复核

15.2 设计决策记录

• 执行层的局部约束更新，优先写入本文件
• 若影响到顶层体验原则，再同步更新 5-DESIGN.md
• 若影响产品定位或跨模块边界，同步更新 2-PRODUCT.md 或 4-ARCHITECTURE.md
• DECISIONS.md 仅作为历史归档，不作为新增决策入口

15.3 冲突处理

• 顶层原则与局部实现冲突：以 5-DESIGN.md 为准
• 文案命名与术语冲突：以 10-TERMINOLOGY.md 为准
• 视觉表达与品牌边界冲突：以 3-BRAND.md 为准

---

16. 一句话总结

6-UI-SPEC.md 的目标，不是让界面元素越来越多，而是让 BestBlogs 的设计原则被稳定、可复用、可验证地执行出来。