PJL Blog 设计规范（Clay 主题）

本文档基于当前访客站实际使用的样式源码整理，设计令牌以 src/main/resources/static/css/var.css 为唯一来源。新增或修改页面样式时，应优先复用本文档中的变量与组件类名。

1. 设计风格

1.1 核心关键词

1.2 设计原则

1. 变量优先：颜色、圆角、间距一律使用 var(--clay-*) 或布局变量，禁止在页面 CSS 中硬编码色值。
2. 阴影成套：每个表面色都有对应的 -shadow / -shadow-hover / -shadow-active 三态阴影。
3. 对比清晰：深色文字 --clay-text-dark 用于标题，中等灰 --clay-text-medium 用于正文与辅助信息。
4. 动效克制：过渡时长 0.2s–0.3s，悬停以 translateY + 阴影变化为主，避免剧烈缩放。

2. 色彩系统

2.1 背景色

2.2 表面色（组件填充）

2.3 文字色

2.4 语义色映射（开发约定）

项目中已统一以下语义对应关系，新增样式请保持一致：

2.5 渐变

2.6 装饰阴影（半透明）

3. 阴影系统

每个表面色配套三组粘土阴影，通过外投影 + 内高光/内暗部模拟立体感。

文章卡片 .post-card 使用独立的复合阴影（偏紫色调），悬停时阴影加深并 translateY(-5px) scale(1.01)。

4. 字体与排版

4.1 字体族

4.2 字号阶梯

4.3 文章正文（Markdown）

定义于 markdown.css：

• 行高 1.75，颜色 --clay-text-dark
• 链接色 --clay-surface-purple，带下划线
• 引用块左边框 --clay-bg-secondary
• 代码块背景 --clay-bg-secondary，圆角 --btn-radius

5. 布局与间距

5.1 布局变量

5.2 页面结构

┌─────────────────────────────────────┐
│  .nav（fixed, z-index: 101）         │  ← top: 20px, max-width: 1060px
├─────────────────────────────────────┤
│  .bg-blobs（fixed, z-index: -1）    │  ← 背景浮动色块
├─────────────────────────────────────┤
│  .site-main（max-width: 1060px）    │  ← padding-top 补偿顶栏
│    页面内容                          │
├─────────────────────────────────────┤
│  .site-footer                       │
└─────────────────────────────────────┘

主内容区顶部内边距：

padding-top: calc(var(--header-height) + var(--header-top) + 20px);

5.3 响应式断点

6. 组件规范

6.1 按钮 .clay-btn

• 基础：border-radius: var(--btn-radius)，padding: 16px 36px
• 小尺寸：.clay-btn.small → 8px 16px
• 悬停：translateY(-3px) + 对应 -shadow-hover
• 变体：--white --dark --blue --green --purple --peach --pink --mint --coral

6.2 卡片

6.3 徽章 .clay-badge

• 全圆角胶囊：border-radius: 999px
• padding: 8px 20px，字重 700

6.4 导航 .nav

• 白色粘土顶栏：.nav.white
• 毛玻璃：backdrop-filter: blur(16px)
• 圆角 20px，内边距 0 16px
• Logo 点缀块 .logo-dot：紫色粘土方块 36×36，圆角 12px
• 链接悬停：background: rgba(214, 162, 255, 0.15)

移动端（≤ 640px）

• 显示 .nav-toggle 汉堡按钮（44×44，白底粘土阴影）
• 菜单面板：固定定位白卡片，box-shadow: var(--white-shadow-hover)
• 全屏遮罩 .nav-backdrop：rgba(45, 53, 87, 0.28)，独立于 .nav 外渲染
• 打开时 body.is-nav-open { overflow: hidden }

6.5 背景装饰 .bg-blobs

五个模糊圆形色块（purple / coral / blue / mint / peach），filter: blur(80px)，opacity: 0.35，缓慢浮动动画。

6.6 分页 .pagination

• 居中对齐，padding: 2rem 0
• 禁用态 .pagination__btn--disabled：透明度 0.55

6.7 错误页 .error-page

• 错误码颜色：--clay-surface-purple
• 主按钮：紫色底 + --purple-shadow，悬停 --purple-shadow-hover

7. 动效与无障碍

7.1 过渡时长

7.2 动画

7.3 无障碍

• 汉堡按钮：aria-expanded、aria-controls、aria-label
• 菜单：aria-hidden 随开关切换
• 键盘：Escape 关闭菜单
• prefers-reduced-motion: reduce 时禁用动画（见 layout.css）

8. 样式文件结构

static/css/
├── var.css          # 设计令牌（唯一色板来源）
├── base.css         # 重置、排版、按钮、卡片、工具类
├── header.css       # 顶栏与移动端导航
├── layout.css       # 背景 blob、减少动效
├── footer.css       # 页脚
├── banner.css       # Hero 区域
├── home.css         # 首页文章网格与分页
├── post.css         # 文章详情、回到顶部
├── markdown.css     # 正文 Markdown 排版
├── error.css        # 404 / 错误页
├── archives.css     # 归档页
├── categories.css   # 分类页
├── about.css        # 关于页
└── index.css        # 入口（import 公共样式）

各页面模板通过 layout:fragment="head-extra" 引入页面级 CSS。

9. 主题切换说明

若后续补齐暗黑模式，应在 var.css 中为 [data-theme="dark"] 增加对应变量覆盖，并同步更新本文档。

10. 开发检查清单

新增 UI 时逐项确认：

• [ ] 颜色来自 var.css 已有变量
• [ ] 圆角使用 --card-radius 或 --btn-radius
• [ ] 间距优先使用 --gap 或 1rem 倍数
• [ ] 可点击元素有 cursor: pointer 与悬停反馈
• [ ] 焦点态可见（如 outline: 2px solid var(--clay-surface-purple)）
• [ ] 移动端在 640px / 576px 断点下检查布局
• [ ] 未引入已废弃的 --color-* / --shadow-* / --radius-* 变量

11. 色板速查

背景
  primary    #f5f5fa    secondary #eee8ff    tertiary  #eefbf5

文字
  dark       #2d3557    medium    #555b7a    light     #f1f1f1

强调 & 装饰
  purple     #d6a2ff ★   coral     #f76d6d    blue      #62cdff
  green      #7ae582      peach     #ffb347    pink      #ff9eb5
  mint       #a8e6cf      dark      #2d3557    white     #ffffff

布局
  header     64px         top       20px       max-width 1060px
  card-r     32px         btn-r     12px       gap       16px

文档版本：与 var.css 当前实现同步。修改色板时请同时更新 var.css 与本文档。