项目: Blog-Hexo (Butterfly 主题定制)
阶段: 全站视觉系统重构
提交范围: 00973e8 至 26adced
样式入口: source/css/custom.css
模块目录: source/css/modules/

目录

  • 提交范围
  • 重构目标
  • 文件分类
  • 主题变量与全局基础
  • 首页首屏、导航与页脚
  • 文章列表、侧栏与卡片
  • 文章正文、代码块与目录
  • 移动端与打印样式
  • 主题配置统一
  • 验证要点

提交范围

提交 日期 说明
00973e8 2026-07-11 重构全站视觉基础与主题变量
40e2962 2026-07-11 优化首页首屏导航与页脚体验
6103719 2026-07-11 重塑文章列表侧栏与内容卡片
ad6a1bb 2026-07-11 提升文章排版代码块与目录可读性
610d322 2026-07-11 完善移动端适配与打印体验
26adced 2026-07-11 统一主题配色文案与内容密度

重构目标

本阶段将站点从 Butterfly 默认视觉逐步调整为更适合技术博客的界面系统。

主要目标：

  • 建立统一设计变量，减少零散颜色和阴影。
  • 优化首页 Hero、导航、页脚和列表区域。
  • 提升文章页长文阅读体验。
  • 强化代码块、表格、目录等技术内容组件。
  • 完善移动端与打印场景。
  • 用 _config.butterfly.yml 统一站点文案和内容密度。

文件分类

分类 文件 作用
主题系统 variables.css 明暗主题变量、颜色、阴影、圆角
全局基础 base.css / background.css / scrollbar.css 基础字体、背景、滚动条
布局组件 header-text.css / navigation.css / footer.css 首屏、导航、页脚
卡片系统 cards.css / about-page.css 首页卡片、侧栏、关于页
内容排版 typography.css / tables.css 正文、标题、列表、表格
代码阅读 code-highlight.css 代码块、行内代码、语法颜色
文章元信息 post-meta.css 文章头图、目录、版权、标签
响应式 responsive.css 移动端、窄屏、打印
主题配置 _config.butterfly.yml 站点文案、侧栏、文章密度、配色

主题变量与全局基础

涉及提交：

  • 00973e8

涉及文件：

  • variables.css
  • base.css
  • background.css
  • scrollbar.css

1. 主题变量体系

variables.css 建立统一变量：

1
2
3
4
5
6
7
8
9
10
11
--ui-accent
--ui-accent-strong
--ui-accent-secondary
--ui-text
--ui-text-muted
--ui-heading
--ui-surface
--ui-border
--ui-shadow-sm
--ui-shadow-md
--ui-shadow-lg

这些变量覆盖：

  • 明亮模式。
  • 暗黑模式。
  • Butterfly 主题变量。
  • 代码块、引用块、目录链接等组件颜色。

2. 全局基础样式

base.css 统一了：

  • 字体栈。
  • 行高。
  • 选中文本颜色。
  • 焦点态。
  • 页面宽度。
  • 卡片基础背景和阴影。
  • prefers-reduced-motion 降级规则。

3. 背景与滚动条

background.css 将页面背景从装饰性背景转为安静底色。

scrollbar.css 统一滚动条：

  • 更细。
  • 主题感更弱。
  • 明暗模式颜色不同。

设计原则：

技术博客的背景应服务阅读，不喧宾夺主。

首页首屏、导航与页脚

涉及提交：

  • 40e2962

涉及文件：

  • header-text.css
  • navigation.css
  • footer.css

1. 首页 Hero

header-text.css 负责：

  • 首页全屏头图。
  • 站点标题。
  • 副标题。
  • 社交图标。
  • 滚动按钮。
  • 文章页头图。

优化目标：

  • 首页有更强个人识别。
  • 内页头图更克制。
  • 文案在图片上保持对比度。

2. 导航栏

navigation.css 负责：

  • 顶部导航尺寸。
  • 白色导航在 Hero 上的显示。
  • 固定导航时的毛玻璃背景。
  • 移动端侧边栏菜单。
  • 右侧工具栏。

3. 页脚

footer.css 做了页脚视觉统一：

  • 弱化页脚装饰。
  • 统一链接悬停状态。
  • 与页面背景保持一致。

文章列表、侧栏与卡片

涉及提交：

  • 6103719

涉及文件：

  • cards.css
  • about-page.css

1. 首页文章卡片

cards.css 重塑首页文章卡片：

  • 增加左侧强调线。
  • 添加文章序号背景。
  • 统一圆角、边框、阴影。
  • 标题 hover 下划线动画。
  • 摘要使用多行截断。

2. 侧栏卡片

侧栏卡片统一为同一套表面系统：

  • 作者卡片。
  • 公告卡片。
  • 最近文章。
  • 分类。
  • 标签云。
  • 归档。

所有卡片共享：

  • var(--ui-surface)
  • var(--ui-border)
  • var(--ui-shadow-sm)

3. 关于页

about-page.css 用于 About 页面：

  • 头像。
  • Hero。
  • 信息网格。
  • 响应式布局。

文章正文、代码块与目录

涉及提交：

  • ad6a1bb

涉及文件：

  • typography.css
  • code-highlight.css
  • post-meta.css
  • tables.css

1. 正文排版

typography.css 优化：

  • 正文字号和行高。
  • H1/H2/H3 层级。
  • 标题锚点。
  • 链接样式。
  • 引用块。
  • 列表。
  • 图片与说明文字。
  • details/summary。
  • 嵌入视频。

目标是让长篇技术文档能稳定阅读。

2. 代码块

code-highlight.css 优化：

  • 代码块背景。
  • 工具栏。
  • 代码字体。
  • 行号。
  • hover 行。
  • token 颜色。
  • 行内代码。

3. 目录与文章元信息

post-meta.css 优化：

  • 文章页标题。
  • 文章元信息。
  • TOC 链接。
  • 当前目录项。
  • 标签。
  • 版权信息。
  • 上下篇导航。

4. 表格

tables.css 优化：

  • 横向滚动。
  • 表头背景。
  • 行 hover。
  • 单元格边框。

技术文档中表格频繁出现，因此表格需要比默认样式更清楚。

移动端与打印样式

涉及提交：

  • 610d322

涉及文件：

  • responsive.css

1. 移动端布局

优化内容：

  • 窄屏下主布局变为单列。
  • 侧栏卡片隐藏或切换为目录抽屉。
  • 正文字号和行高调整。
  • 导航栏高度和站点名尺寸调整。
  • 代码块、表格、引用块避免撑破屏幕。

2. 打印样式

打印模式隐藏：

  • 头图。
  • 侧栏。
  • 右侧工具栏。
  • 页脚。
  • 分享和上下篇组件。

打印保留：

  • 正文。
  • 链接。
  • 代码块。
  • 表格。
  • 引用块。

目的：

让技术文章可以被导出或打印为相对干净的文档。

主题配置统一

涉及提交：

  • 26adced

涉及文件：

  • _config.butterfly.yml

配置统一内容：

  • 主题色。
  • 首页文案。
  • 作者卡片描述。
  • 侧栏卡片显示。
  • 首页文章摘要长度。
  • 目录显示策略。
  • 分类和标签页 UI。

这一步让视觉 CSS 与 Butterfly 配置保持一致，避免 CSS 已经优化但配置仍停留在默认状态。

验证要点

构建验证

1
npm run build

需要确认：

  • CSS 模块正常生成。
  • 首页、文章页、分类、标签、归档页面正常生成。
  • 没有 YAML 配置错误。

视觉验证

重点检查：

  • 首页 Hero 是否完整。
  • 导航栏在首屏和滚动后是否清晰。
  • 首页卡片是否对齐。
  • 侧栏卡片是否统一。
  • 文章正文层级是否清楚。
  • 代码块是否可读。
  • 移动端是否无横向溢出。

结论

本阶段是 Butterfly 主题接入后的第一次系统性视觉重构。它建立了后续所有优化的基础：

  • 变量统一。
  • 模块边界清楚。
  • 首页和文章页都形成明确风格。
  • 长文阅读组件得到强化。
  • 移动端和打印场景补齐。

后续的素材压缩、全屏透明首页、代码主题对齐和目录锚点修复，都是在这个视觉系统基础上继续推进。