BoosAPI/desktop/libs/markstream-vue/design/visual-review.md

视觉设计评审

基于 /example 页面的 light + dark 截图，逐组件审视当前视觉状态。 标注"需重设计"的项是 issue #343 视觉重设计的具体工作。

---

需要重设计的元素

1. 标题层级 — 需重设计

现状问题：

• h4/h5/h6 视觉上几乎无法区分，都是同样大小的 text-base
• h1 和 h2 之间跳跃太大（4xl → 2xl）
• h5/h6 没有任何视觉区分度（无字重差异、无颜色差异、无间距差异）

建议方向：

• h4 可用 muted-foreground 或小号全大写字母来区分
• h5/h6 可用更小字号或不同字重
• 整体建立更平滑的字号梯度

---

2. 表格 — 需重设计

现状问题：

• 表头没有背景色，和正文行无法区分
• 无斑马纹，多行时视觉追踪困难
• 边框太淡（尤其 dark 模式下几乎不可见）
• 无 hover 行高亮
• 整体非常朴素，缺乏结构感

建议方向：

• 表头加 --table-header-bg 背景
• 偶数行加微弱背景色（斑马纹）
• 增强 dark 模式下边框可见度
• 增加 hover 行高亮

---

3. 引用块（Blockquote） — 需重设计

现状问题：

• 左边框颜色太淡，dark 模式下几乎不可见
• 整体过于朴素，没有背景色区分
• 与正文的视觉层级差异不够

建议方向：

• 增加微弱的背景色（如 --ms-muted 低透明度）
• 左边框加粗或加深颜色
• 可考虑使用 accent 色作为左边框
• Dark 模式下需要明显更亮的边框

---

4. 代码块 — 需重设计

现状问题：

• Header 背景和页面背景融为一体，没有区分
• 代码区域在 light 模式下是白色底，和页面白色底无边界感
• 整个容器的阴影太轻（shadow-sm），不够突出
• Dark 模式下代码块容器和页面背景的对比度不足

建议方向：

• Header 需要明确的 --code-header-bg 背景（当前 token 已定义但视觉太淡）
• 考虑加深容器边框或增加阴影
• Light 模式代码区域可用微灰背景（而非纯白）
• 代码块作为"嵌入内容"应该在视觉上与正文有明确的层级分离

---

5. 分割线（HR） — 需微调

现状问题：

• 太细太淡，dark 模式下几乎不可见
• 上下间距很大（my-12）但线本身视觉权重不够

建议方向：

• 增加线的粗细或颜色深度
• 或改为渐变消隐风格（从中心向两侧淡出）

---

6. 列表标记 — 需微调

现状问题：

• 无序列表圆点颜色太淡（--list-marker = border 色）
• 有序列表数字颜色也偏淡
• Task list 的 checkbox 太小，无自定义样式

建议方向：

• 标记色加深一档（用 --ms-muted-foreground 而非 --ms-border）
• Checkbox 可自定义样式（圆角、颜色、大小）

---

7. 定义列表 — 需重设计

现状问题：

• 纯文本渲染，术语和描述之间缺乏视觉层级
• 没有背景、边框或缩进的视觉区分
• 和普通段落看起来没区别

建议方向：

• 术语可用 accent 色或加背景标签
• 描述增加左缩进 + 左边框（类似引用块）
• 或使用交替背景色

---

8. 脚注 — 需微调

现状问题：

• 脚注区域和正文的分隔线太淡
• 脚注内容在页面底部容易被忽略
• 缺乏"脚注区域"的整体框架感

建议方向：

• 分隔线加深或改用双线
• 增加微弱背景色标示脚注区域
• 脚注编号可加 accent 色

---

9. 高亮文本（Highlight） — 需微调

现状问题：

• Light 模式下亮黄色 OK
• Dark 模式下黄色变暗了但可能和文字对比度不够

建议方向：

• Dark 模式下可用更亮的荧光色或调整透明度
• 确保 WCAG AA 对比度达标

---

当前表现良好的元素

Admonitions — 良好

• 6 种类型颜色区分明显
• 左边框 + 标题栏 + 图标结构清晰
• Light/Dark 模式切换正常
• 有自定义标题功能

数学公式 — 良好

• 行内和块级都正确渲染
• KaTeX 排版质量好

链接 — 良好

• 蓝色链接色在两种模式下都清晰
• Hover 下划线效果正常

段落 & 内联元素 — 良好

• Bold、italic、strikethrough、inline code、subscript、superscript 都正常
• Inline code 有背景色和边框，辨识度高

Mermaid 图 — 良好

• 容器有 header + 模式切换
• 边框和阴影提供了层级感

图片 — 良好

• 正确加载并显示
• 有 max-width 限制

---

整体节奏问题

间距不统一

• 段落 1.25em、引用块 1.6em、列表 1.25rem、表格 2rem、分割线 3rem — 缺乏统一节奏
• 代码块和表格的上下间距不协调

Dark 模式对比度

• 多个元素在 dark 模式下对比度不足（分割线、表格边框、引用块边框、列表标记）
• 需要整体提升 dark 模式下的边框/分隔元素亮度

---

优先级排序

优先级	元素	原因
P0	表格	当前最朴素，用户感知最强
P0	代码块容器	高频组件，当前缺乏层级感
P1	引用块	dark 模式下几乎不可见
P1	标题层级	h4-h6 无法区分
P1	Dark 模式整体对比度	多个元素受影响
P2	定义列表	缺乏视觉结构
P2	分割线	视觉权重不够
P2	列表标记	太淡
P2	脚注	框架感不足
P3	高亮文本	dark 对比度