Hugo 博客项目设计规范文档

项目视觉总览

视觉气质

本项目的视觉基调不是“互联网产品界面”，而是更接近纸面阅读物、档案页、轻印刷海报的混合风格。整体感受有以下几个稳定特征：

低饱和、中高对比：背景偏浅灰或深灰，正文与标题对比明确，但不使用高饱和强调色。
阅读优先：主体内容宽度固定，留白充足，文本节奏稳定。
轻拟物但不过度装饰：通过背景纹理、柔和阴影、半透明面板、圆角卡片制造层次，而不是依赖复杂插画。
轻印刷感标题：通过 .xerox 的细微字距与双重阴影，制造“复印/印刷偏移”的视觉效果。
结构化归档感：section 列表、目录、元信息条、标签、日期等元素都强调“可归档、可扫描、可回溯”。

实现锚点

主要样式入口在 main.css ，主要页面结构来自：

布局与页面结构

全局布局骨架

页面基础结构来自 baseof.html ：

<main class="site-main">
  <div class="page-shell">
    {{ block "main" . }}{{ end }}
  </div>
</main>

这意味着全站布局有两层宽度控制：

.site-main：负责上下留白
.page-shell：负责页面外层总宽度

宽度规则

可直接提炼为设计 token：

--page-width: 650px;

对应实现：

.page-shell {
  width: min(calc(100% - 2rem), calc(var(--page-width) + 4rem));
}

.content-shell,
.site-footer {
  width: min(100%, var(--page-width));
}

含义如下：

正文最大阅读宽度：650px
页面外层左右安全边距：移动端至少保留 1rem + 1rem
正文与页脚等核心内容容器：严格收敛到 650px 内

纵向留白规则

--page-margin-y: 3rem;
@media (min-width: 768px) {
  --page-margin-y: 5rem;
}

对应：

.site-main {
  padding: var(--page-margin-y) 0;
}

结论：

移动端页面顶部和底部留白为 3rem
桌面端页面顶部和底部留白为 5rem

页面结构规律

当前项目页面遵循稳定的结构模式：

页头 header.html
页面专属 hero 区或标题区
主体内容区
辅助模块区（目录、标签、推荐、操作区）
页脚 footer.html

典型页面模块结构

首页

来自 home.html ：

header
home-nav
intro-card
posts-feed
footer

特征：

顶部先显示品牌与主导航
中间是简介卡片
下方是文章卡片流

文章详情页

来自 posts/single.html ：

header
article-header
toc
markdown-body
action-menu
now-read-this
comment
back-to-top
footer

特征：

使用最完整的内容型页面结构
模块分层最清晰，适合作为复刻主模板

书籍详情页

来自 library/single.html ：

header
centered book-hero
markdown-body
meta-strip
book-grid
footer

特征：

顶部居中
封面作为主要视觉对象
书籍推荐区域使用栅格

小说页

来自 fictions/single.html ：

hero 区居中
正文优先
辅助信息尽量少

这是当前项目中最“简”的内容页类型。

色彩系统

颜色 token

可直接按以下 token 复刻：

:root {
  --background-color: #f5f5f7;
  --block-background-color-rgb: 233, 232, 237;
  --block-background-color: rgb(var(--block-background-color-rgb));
  --border-color: #d0d7de;
  --text-color: #1d1d1f;
  --secondary-text-color: #6e6e73;
  --link-color: #313135;
  --bright-background-color: #fafafa;
}

暗色模式：

@media (prefers-color-scheme: dark) {
  :root {
    --background-color: #1d2021;
    --block-background-color-rgb: 24, 26, 27;
    --border-color: rgba(255, 255, 255, 0.18);
    --text-color: #d2cec9;
    --secondary-text-color: #a1998d;
    --link-color: #e3dfda;
    --bright-background-color: #666;
  }
}

颜色角色定义

`--background-color`

用途：页面主背景
出现位置：body
视觉效果：大面积底色，亮色为浅灰，暗色为深灰

`--block-background-color`

用途：卡片、面板、按钮底色
出现位置：.hero-badge、.pill、.tag-link、.action-button
视觉效果：相对背景更实的中间层

`--border-color`

用途：边框、虚线分隔线、目录辅助线、链接装饰线
出现位置：hr、.site-footer、.toc-card li ul、.nav-link
视觉效果：柔和、不抢眼的边界

`--text-color`

用途：正文、主标题、当前激活态文字
视觉效果：主信息承载色

`--secondary-text-color`

用途：副标题、元信息、说明文字、目录非激活链接
视觉效果：层级退后

`--link-color`

用途：全站链接主色
注意：Markdown 链接额外叠加波浪下划线，而不是靠颜色单独强调

`--bright-background-color`

用途：代码块背景
特征：比普通块背景更干净、更亮

纹理背景

背景纹理不是外部图片，而是内联 SVG：

--texture-light: url("data:image/svg+xml,...");
--texture-dark: url("data:image/svg+xml,...");

统一设置：

body {
  background-image: var(--texture-light);
  background-size: 5rem;
}

复刻重点：

纹理必须非常轻
仅作为空气感，不应形成明显图案噪音
暗色模式纹理可见度比亮色稍高

字体与排版

字体系统

正文主字体：

--serif-font-family: "Noto Serif", "Noto Serif SC", "Noto Serif TC",
  "Noto Serif CJK SC", "Source Han Serif SC", "Songti SC",
  "Times New Roman", Times, serif;

等宽字体：

--mono-font-family: "Courier New", Menlo, Monaco, Consolas, monospace;

字体角色划分

衬线字体 `--serif-font-family`

用于：正文、标题、品牌标题、长文内容
目标效果：营造阅读感与文档感

等宽字体 `--mono-font-family`

用于：日期、元信息、页脚、辅助说明
对应类：
- .posts-item-meta
- .post-meta
- .book-meta
- .archive-item-meta
- .muted
- .site-footer

字号层级

当前源码中最明确的字号 token：

.brand-title {
  font-size: clamp(2rem, 4vw, 3rem);
}

.article-title,
.book-title,
.fiction-title,
.page-title {
  font-size: clamp(2rem, 4vw, 3.2rem);
}

.posts-item-title {
  font-size: clamp(1.5rem, 3.3vw, 2.1rem);
}

.brand-subtitle {
  font-size: 0.9rem;
}

.pill,
.tag-link,
.action-button {
  font-size: 0.9rem;
}

.markdown-body {
  font-size: 1.06rem;
}

.posts-item-meta,
.muted,
.site-footer {
  font-size: 0.88rem ~ 0.9rem;
}

行高规则

body {
  line-height: 1.7;
}

.markdown-body {
  line-height: 1.9;
}

结论：

全站基础阅读行高：1.7
正文阅读区行高：1.9

这会让长文本显得更舒展。

标题风格：`.xerox`

.xerox {
  letter-spacing: 0.03em;
  text-shadow: 0.03em 0 rgba(0, 0, 0, 0.12), -0.025em 0 rgba(0, 0, 0, 0.08);
}

规范解释：

用途：品牌标题、文章标题、书名标题、页面标题
目标效果：模拟轻微印刷偏移
不应加大阴影模糊值，否则会变成普通发光效果

Markdown 排版规范

来自 main.css ：

正文使用 .markdown-body
标题滚动偏移：scroll-margin-top: 5rem
列表缩进：1.75rem
无序列表符号：square
行内代码：灰底、小圆角、等宽字体
代码块：不对称圆角 1rem 0 1rem 1rem
引用：左侧 3px 竖线
高亮：浅黄底 + 下划线
删除线：降低透明度，不做真正删除感特效

链接规范

普通全局链接：

a:hover {
  text-decoration: underline;
}

正文内链接：

.markdown-body a:not(.tag-link):not(.pill):not(.nav-link) {
  text-decoration: underline wavy;
  text-decoration-color: var(--border-color);
}

外链额外标识：

.markdown-body a.external-link::after {
  content: "↗";
}

复刻重点：

文中链接必须和导航按钮区分开
正文链接更像“批注线”而不是“按钮”

组件规范

导航栏

结构来源

来自 header.html 。

结构由两部分组成：

.site-brand
.site-nav

品牌区

.site-brand：

display: flex;
align-items: center;
justify-content: center;
gap: 1.25rem;

品牌结构是：

logo
标题与副标题的竖向堆叠

导航按钮

.nav-link token：

padding: 0.4rem 0.85rem;
border-radius: 999px;
border: 1px solid var(--border-color);
background: transparent;
transition: background-color 160ms ease, color 160ms ease, transform 160ms ease;

悬停与激活态：

.nav-link:hover,
.nav-link[aria-current="page"] {
  background: var(--text-color);
  color: var(--background-color);
  transform: translateY(-1px);
}

规范结论：

形态：胶囊按钮
状态：默认透明底，悬停/激活时反相
不要给导航加太厚阴影
激活态通过 aria-current="page" 控制，不依赖额外类名

首页分区导航 `home-nav`

.home-nav {
  margin-bottom: 2rem;
  justify-content: flex-start;
  font-size: 0.95rem;
}

特点：

不是按钮组
更像简洁的次级文字导航
左对齐

页脚

结构来源

来自 footer.html 。

样式特征：

.site-footer {
  margin-top: 4rem;
  padding-top: 1.5rem;
  border-top: 1px dashed var(--border-color);
  font-family: var(--mono-font-family);
  font-size: 0.9rem;
}

规范结论：

页脚与正文之间通过虚线分隔，而不是实线
字体切换到等宽，强调“文档尾注”感
链接组与图标组分离

卡片

通用卡片面板

以下类共享同一组面板规范：

.intro-card
.toc-card
.meta-strip
.action-menu
.comment-card
.archive-month
.book-card
.card-note
.empty-state

共性 token：

background: rgba(var(--block-background-color-rgb), 0.65);
border: 1px solid var(--border-color);
border-radius: 1.25rem;
box-shadow: var(--shadow-soft);
backdrop-filter: blur(8px);

这说明项目的面板语言是统一的：

半透明块底
细边框
大圆角
轻柔阴影
毛玻璃式背景模糊

文章卡片 `.posts-item`

.posts-item {
  padding: 1.2rem 1.25rem;
  border-radius: 1.4rem;
  border: 1px solid var(--border-color);
  background: linear-gradient(...);
  box-shadow: var(--shadow-card);
}

特点：

比普通面板更“实体”
使用渐变背景，而非纯色
阴影更明显，适合作为内容入口卡片

复刻建议：

首页内容流优先使用 .posts-item 风格
信息面板、目录、评论等优先使用通用面板风格

Hero 徽章 `.hero-badge`

出现在：

通用页
文章页
书籍页
小说页
卡片页

样式：

display: inline-flex;
align-items: center;
gap: 0.5rem;
padding: 0.55rem 0.85rem;
border-radius: 999px;
border: 1px solid var(--border-color);
background: var(--block-background-color);

作用：

标记页面类型
提供视觉起始点

图标固定尺寸：

.hero-badge img {
  width: 2rem;
  height: 2rem;
}

元信息条 `.meta-strip`

display: flex;
flex-wrap: wrap;
gap: 0.6rem;
align-items: center;
padding: 0.85rem 1rem;
margin-top: 1rem;

用于承载：

日期
分类
标签
补充说明

规范：

一律水平排列，可换行
适合内容型页面头部和书籍页底部信息区

标签、分类、动作按钮

三者共享统一基类风格：

.pill,
.tag-link,
.action-button {
  display: inline-flex;
  align-items: center;
  gap: 0.45rem;
  padding: 0.38rem 0.75rem;
  border-radius: 999px;
  background: var(--block-background-color);
  border: 1px solid var(--border-color);
  font-size: 0.9rem;
}

设计结论：

全项目中的“小型可交互单元”统一使用胶囊化语言
不建议某些页面改成矩形小按钮，否则风格会断裂

目录卡片 `.toc-card`

当前目录规范：

外层是面板卡片
内部使用无序列表，但去掉默认列表样式
子级目录通过左侧虚线缩进
当前项通过文字颜色和前置短条变化表达

关键 token：

.toc-card a::before {
  width: 0.85rem;
  height: 0.25rem;
  border-radius: 999px;
}

这一小短条是目录视觉识别的重点，不要省略。

书籍封面 `.book-cover`

.book-cover {
  aspect-ratio: 3 / 4;
  border-radius: 0.85rem;
  background: linear-gradient(160deg, var(--text-color), var(--secondary-text-color));
  color: var(--background-color);
  display: grid;
  place-items: end start;
  padding: 1rem;
  font-size: 1.1rem;
  font-weight: 700;
  box-shadow: var(--shadow-card);
}

规范：

固定封面比例 3:4
文本落在左下角
背景使用深浅过渡
适合作为占位封面或无实图状态

返回顶部按钮

来自 back2top.js 和对应 partial。

视觉规范：

.back-to-top button {
  width: 4rem;
  height: 4rem;
  border-radius: 999px;
  border: 1px solid var(--border-color);
  background: var(--block-background-color);
  box-shadow: var(--shadow-card);
}

结论：

固定在右下角
圆形
比普通按钮更大，接近悬浮操作钮

列表与归档

归档月卡 .archive-month：

使用通用面板视觉
通过 <details> 与 <summary> 承载可展开结构
年份与月份之间依靠垂直节奏区分，而不是复杂图形

表单

当前源码状态

当前项目源码中未定义独立的表单输入框、搜索框、文本域、选择器样式。

已确认的仅有：

button {
  font: inherit;
  border: 0;
  color: inherit;
  background: none;
  cursor: pointer;
}

因此表单规范目前属于缺失项。如需继续复刻，应优先检查以下目录或新增实现：

layouts/_partials/ 中是否后续会新增搜索或评论输入组件
assets/css/ 是否未来拆分出表单专用样式
static/ 或第三方评论系统接入是否带来表单 UI

图片与图标处理方式

图片处理

全局图片规则：

img {
  max-width: 100%;
  display: block;
}

意味着：

图片默认不作为 inline 元素
不允许超过父容器

图标使用方式

当前图标主要来自 static/img/ 下的 SVG：

使用策略：

Logo 用于品牌与 hero badge
功能型图标尽量简单、轮廓清晰
页脚外链图标控制在 1rem × 1rem
hero badge 图标控制在 2rem × 2rem

图标风格要求

从现有 SVG 可归纳出以下规则：

使用简单几何形
线面结合，不追求复杂细节
适合在浅背景与深背景上都保持可辨识

响应式与适配

已定义断点

当前源码中只明确出现一个断点：

@media (min-width: 768px)

因此当前项目的响应式策略是：

默认样式即移动端
>= 768px 进入桌面/平板大屏布局

页头响应式

默认：

.site-header 为单列
.site-brand 居中
.site-nav 居中

大于 768px：

.site-header {
  grid-template-columns: 1fr auto;
  align-items: start;
}

.site-brand {
  justify-content: flex-start;
}

.site-nav {
  justify-content: flex-end;
}

即：

左侧品牌
右侧导航

书籍栅格响应式

.book-grid {
  grid-template-columns: repeat(2, minmax(0, 1fr));
}

@media (min-width: 768px) {
  .book-grid {
    grid-template-columns: repeat(4, minmax(0, 1fr));
  }
}

结论：

移动端 2 列
大屏 4 列

宽度适配原则

本项目不追求超宽屏内容扩展，而是始终把阅读内容锁定在 650px 左右。

复刻时不要：

把正文拉到 800px 以上
让首页卡片在桌面端变成多列瀑布

否则会破坏阅读型视觉逻辑。

动效与交互

过渡速度

源码中常见的时间值：

160ms ease
180ms ease

说明项目使用的是短时、轻量、低存在感的动画。

导航按钮动效

transition: background-color 160ms ease, color 160ms ease, transform 160ms ease;

交互表现：

背景反相
文字反相
轻微上浮 translateY(-1px)

返回顶部显隐

.back-to-top {
  opacity: 0;
  transform: translateY(2rem);
  pointer-events: none;
  transition: opacity 180ms ease, transform 180ms ease;
}

.back-to-top.is-visible {
  opacity: 1;
  transform: translateY(0);
  pointer-events: auto;
}

特征：

不是突然显示
而是“从下方淡入浮起”

目录交互

目录的动态高亮由 toc.js 控制。

视觉变化非常克制：

当前项文字变深
前置短条变深

不会做复杂展开动画。

点赞交互

来自 like.js 。

当前源码中逻辑存在，但 is-liked 对应的专门视觉样式尚未在 main.css 中单独定义。
这属于现有实现信息不足的部分。

如果要继续精确复刻，应补查：

是否计划新增 .action-button.is-liked
是否后续为点赞状态增加颜色或图标变化

暗色模式规则

触发机制

当前仅使用：

@media (prefers-color-scheme: dark)

即：

没有显式手动切换按钮
完全跟随系统偏好

暗色模式下保持不变的东西

以下设计规律在暗色模式中不变：

内容宽度
组件圆角
阴影层级
纹理背景存在
字体系统
卡片化结构

暗色模式下变化的东西

页面背景由浅灰转深灰
文本由深灰转浅棕灰
边框透明度变低、更柔和
链接与正文色反转
纹理可见度提升

复刻要求

不要单独为暗色模式设计另一套完全不同的视觉风格
暗色模式应是同一视觉语言的反相版本

Hugo 结构映射

主题结构与模板职责

基础模板

baseof.html
- 全站 HTML 骨架
- 注入 head 与 scripts
- 承载 main block

通用页面模板

_default/single.html
- 通用单页
- 适用于非专属 section 页面
_default/list.html
- 通用列表页
- 用于归档型页面

首页模板

home.html
- 首页介绍卡片
- 首页文章流

section 专属模板

posts/single.html
- 文章详情页
essays/list.html
- 散文归档页
library/single.html
- 书籍详情页
fictions/single.html
- 小说页
cards/single.html
- 卡片页

partials 复用方式

当前 partial 明显分为两类：

页面公共 partial

header.html
footer.html
head.html
scripts.html
home-nav.html

组件型 partial

components/logo.html
components/date.html
components/category-pill.html
components/tags.html
components/back-to-top.html

内容型 partial

posts/toc.html
posts/action-menu.html
posts/now-read-this.html
posts/comment.html
posts/card.html
section-archive.html

复刻时建议维持这种拆分原则：

“全站结构” 与 “内容组件” 分开
“通用组件” 与 “文章专属组件” 分开

CSS 组织方式

当前项目样式集中在一个文件：

main.css

组织顺序大致为：

根变量
暗色模式变量
全局 reset / base
全局布局类
头部与页脚
通用面板与卡片
标题与排版
Markdown 内容样式
目录、书籍封面、悬浮按钮
响应式规则

如果后续拆分为 SCSS，建议按以下粒度拆：

assets/css/
├─ tokens.css
├─ base.css
├─ layout.css
├─ components.css
├─ markdown.css
└─ pages.css

但当前源码尚未拆分，因此复刻时应先遵循现状，而不是自行假设已有模块化结构。

复刻注意事项

最容易出错的点 1：把“阅读页”做成“应用页”

当前项目的核心是阅读体验，而不是后台型信息系统界面。
常见误差包括：

过度使用大色块按钮
多列化首页内容流
增加太多显眼的边框或投影

最容易出错的点 2：忽视 `650px` 宽度约束

如果正文宽度被拉宽，排版气质会立刻变差。
这是本项目最重要的基础约束之一。

最容易出错的点 3：把胶囊控件改成普通矩形按钮

导航、标签、分类、动作按钮、hero badge 都共享圆胶囊语言。
任意一处改成方角按钮都会破坏一致性。

最容易出错的点 4：把纹理背景做得过重

背景纹理只用于增加层次，不应用于成为“装饰主角”。

最容易出错的点 5：标题阴影过重

.xerox 是轻印刷感，不是发光字。
不要使用高模糊、大偏移阴影替代。

最容易出错的点 6：把元信息做得比正文更醒目

.muted、日期、标签、目录非激活状态都应该退后。
如果颜色过深或字号过大，会打乱主次关系。

最容易出错的点 7：凭空补全不存在的设计系统

当前源码中缺失以下信息：

表单输入框规范
搜索框规范
多断点复杂栅格规范
点赞激活态专属视觉规范

这些内容在现有源码中没有被完整定义。
复刻时如需继续补，应先检查：

assets/css/ 是否新增文件
layouts/_partials/ 是否新增组件
static/ 是否新增图标或视觉资源

复刻优先级

建议按以下顺序复刻：

全局 token 与基础背景
- 先复刻颜色变量、宽度变量、背景纹理、字体栈和基础排版
基础布局骨架
- 复刻 baseof.html、page-shell、content-shell、site-main
页头与页脚
- 这是全站视觉识别最强的公共结构，应优先统一
标题系统与 .xerox 效果
- 品牌标题、文章标题、页面标题必须先统一气质
通用面板与胶囊组件
- 包括 .intro-card、.toc-card、.meta-strip、.pill、.tag-link、.action-button
Markdown 正文样式
- 包括段落、链接、列表、代码、blockquote、mark、del
文章详情页结构
- 文章页最能体现项目整体视觉规则，建议作为复刻主样板
首页文章卡片流
- 重点复刻 .posts-item 的渐变、圆角和层级关系
书籍页与封面栅格
- 这是项目中最明显的变体页面，应在基础视觉稳定后实现
目录高亮、返回顶部等轻交互

交互最后补，避免在视觉结构未稳定前过早耦合逻辑

暗色模式

建议在亮色模式稳定后再整体反相适配

缺失项补全

表单、搜索、点赞激活态等缺失规范应放在最后，并基于新增源码再定义

Hugo 博客项目设计规范文档

项目视觉总览

视觉气质

实现锚点

布局与页面结构

全局布局骨架

宽度规则

纵向留白规则

页面结构规律

典型页面模块结构

首页

文章详情页

书籍详情页

小说页

色彩系统

颜色 token

颜色角色定义

--background-color

--block-background-color

--border-color

--text-color

--secondary-text-color

--link-color

--bright-background-color

纹理背景

字体与排版

字体系统

字体角色划分

衬线字体 --serif-font-family

等宽字体 --mono-font-family

字号层级

行高规则

标题风格：.xerox

Markdown 排版规范

链接规范

组件规范

导航栏

结构来源

品牌区

导航按钮

首页分区导航 home-nav

页脚

结构来源

卡片

通用卡片面板

文章卡片 .posts-item

Hero 徽章 .hero-badge

元信息条 .meta-strip

标签、分类、动作按钮

目录卡片 .toc-card

书籍封面 .book-cover

返回顶部按钮

列表与归档

表单

当前源码状态

图片与图标处理方式

图片处理

图标使用方式

图标风格要求

响应式与适配

已定义断点

页头响应式

书籍栅格响应式

宽度适配原则

动效与交互

过渡速度

导航按钮动效

返回顶部显隐

目录交互

点赞交互

暗色模式规则

触发机制

暗色模式下保持不变的东西

暗色模式下变化的东西

复刻要求

Hugo 结构映射

主题结构与模板职责

基础模板

通用页面模板

首页模板

`--background-color`

`--block-background-color`

`--border-color`

`--text-color`

`--secondary-text-color`

`--link-color`

`--bright-background-color`

衬线字体 `--serif-font-family`

等宽字体 `--mono-font-family`

标题风格：`.xerox`

首页分区导航 `home-nav`

文章卡片 `.posts-item`

Hero 徽章 `.hero-badge`

元信息条 `.meta-strip`

目录卡片 `.toc-card`

书籍封面 `.book-cover`

最容易出错的点 2：忽视 `650px` 宽度约束