03-主题与样式定制

本项目的全部视觉参数（颜色、阴影、圆角、字体、背景网格）都收敛为 --wp-* 前缀的 CSS 变量，定义在 src/styles/main.css。换肤、换主色、换字体都只需要动这一个文件。

1. 换肤架构（三层）

第 1 层：设计 token（CSS 变量）
  :root, .light { --wp-accent: #e86233; --wp-bg: #f5f4f0; ... }   ← 亮色值（.light 供子树强制亮色）
  .dark { --wp-accent: #db7753; --wp-bg: #141413; ... }     ← 暗色值
        │
        ▼
第 2 层：Tailwind 桥接（@theme inline）
  @theme inline {
    --color-accent: var(--wp-accent);
    --color-paper:  var(--wp-bg);
    ...
  }
  → 自动生成工具类：bg-accent / text-accent / border-line / shadow-card ...
        │
        ▼
第 3 层：组件使用语义类
  <article class="border border-line-light bg-surface shadow-card">
  <a class="hover:text-accent">

由此得到两条实践结论：

2. 换主色：最小改动步骤

场景：把柑橘橙（#e86233）换成蓝紫（#5b6ee1）。这是最常见的换肤需求，共用 6 步。

第 1 步：改亮色主色三件套

src/styles/main.css 的 :root 块：

:root {
  --wp-accent: #5b6ee1;        /* 原 #e86233 —— 主色，按钮/链接/高亮 */
  --wp-accent-hover: #7484e8;  /* 原 #ea7b53 —— hover 亮一档 */
  --wp-accent-deep: #3f4fb0;   /* 原 #b6502b —— 深一档，用于链接文字 */
  /* --wp-link / --wp-link-hover 默认引用上面两个变量，无需改 */
}

第 2 步：改暗色主色三件套

.dark 块（暗色下要降低饱和度并提亮，否则刺眼）：

.dark {
  --wp-accent: #8b9bf0;        /* 原 #db7753 */
  --wp-accent-hover: #a3b0f4;  /* 原 #e28969 */
  --wp-accent-deep: #7286e8;   /* 原 #c86541 */
}

第 3 步：改背景网格线颜色（最容易被忘的一步）

--wp-grid-image 是一段内联 SVG data URI，线条颜色硬编码在 URL 编码里，不会跟随 --wp-accent：

/* 亮色：stroke='%23E86233'  ← 注意 # 被编码成 %23 */
--wp-grid-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='28' height='28' viewBox='0 0 28 28'%3E%3Cpath d='M0 0L28 0M0 0L0 28' fill='none' stroke='%23E86233' stroke-opacity='0.14' stroke-width='1'/%3E%3C/svg%3E");
/* 暗色：stroke='%23DB7753'，透明度 0.11 */

把两处 %23E86233 / %23DB7753 分别替换成新主色的十六进制（不带 #，前面加 %23）。width='28' height='28' 是网格单元尺寸，改这里要同步改 body 的 background-size: 28px 28px。

第 4 步：检查 --wp-gradient-pink 与品牌色

第 5 步：AboutPage.astro 主题色（可选）

因为 about 是一个特殊的独立页面，为自定义页面，所以请自行参考修改。

第 6 步：验证

pnpm dev   # 切换明暗主题，检查：链接、按钮 hover、网格背景、分页当前页、置顶角标、代码块左侧色条、TOC 激活项

3. --wp-* 变量全表

3.1 背景与表面

3.2 主色与链接

注意亮/暗的链接策略不同：亮色模式链接用「深一档」保证对比度，暗色模式直接用主色（暗底上深色不可读）。改 --wp-link 时请维持这个思路。

3.3 文字

3.4 边框与阴影

3.5 语义色

3.6 提示容器标题色

只有标题文字色是变量，容器左边框色在 markdown.css 里写死：info #6fa8dc、tip #7ba05b、warning #d9a441、danger #c96a5b、details var(--wp-text-tertiary)。想换要同时改两处（见#8.2）。

3.7 代码高亮配色（Prism）

这些是构建期写进 HTML 的 <span class="token ...">，颜色由 CSS 变量在运行时决定，所以改颜色不需要重新构建。

4. Tailwind 桥接表（@theme inline）

main.css 第 94–116 行把这些变量注册为 Tailwind 主题变量，从而生成工具类：

新增一个语义色的完整示例（加一个「成功绿」）：

/* 1) 在 :root 里定义 */
:root  { --wp-success: #3f8f5f; }
.dark  { --wp-success: #7bc39a; }

/* 2) 在 @theme inline 里桥接 */
@theme inline {
  --color-success: var(--wp-success);
}

/* 3) 在组件里使用 */

<span class="text-success">已保存</span>

5. 字体与排版

5.1 当前字体策略

/* main.css */
@theme inline {
  --font-serif: sans-serif;   /* ← 注意：font-serif 实际也是无衬线 */
  --font-mono: monospace;
}

body {
  font-family: sans-serif;
  font-size: 16px;
  line-height: 1.7;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

设计取向：零字体网络请求（AboutPage 的「未来计划」中也写明「自定义字体」仍在评估，因为要考虑加载时间）。所以标题用的 font-serif 实际渲染为系统无衬线字体。

5.2 换成自定义字体（需权衡）

引入 web 字体会破坏「零请求」取向！

若确定要换，注意 astro.config.mjs 的 vite.build.assetsInlineLimit = 4096：小于 4KB 的资源会被内联，字体文件通常远大于此，会作为独立文件输出。

推荐把字体文件放 public/fonts/（astro.config.mjs 的 swup ignore 已包含 /fonts/ 前缀，不会走 SPA 导航），然后：

/* main.css 顶部 */
@font-face {
  font-family: 'MySans';
  src: url('/fonts/MySans.woff2') format('woff2');
  font-display: swap;          /* 避免文字长时间不可见 */
  unicode-range: U+0000-00FF;  /* 按需裁剪，减小体积 */
}

@theme inline {
  --font-serif: 'MySans', system-ui, sans-serif;
}

body { font-family: 'MySans', system-ui, sans-serif; }

5.3 常用排版参数调整位置

为什么 <main> 是 max-w-[832px] 而内容宽度算 800px？

832px 是玻璃卡片外框的宽度，正文实际可读宽度 = 外框 − 左右内边距。旧写法 max-w-[800px] + px-6（800 − 2×24 = 752），新写法 max-w-[832px] + px-4（832 − 2×16 = 800）。页脚 SiteFooter.astro 同步用 max-w-[832px] + px-4 保持外框对齐。因此若想改内容宽度到 W，应把两处改成 max-w-[W+32px] 且保持 px-4；页面内部的 max-w-[800px]（首页列表、文章页头/尾、评论等）则直接用内容宽度 W。

标题的「层级色条」机制：

.post-content :is(h1..h6)::before 用 --i（0–5）计算高度：height: calc(100% - var(--i) * 14%)。所以 h1 的色条最长、h6 最短。想改成等长，删掉 calc() 直接用 100% 即可。

6. 暗色模式实现细节

6.1 切换机制

移动端与桌面端对于 View Transition API 在实现上存在显著差异，所有做了两套动画方案：

• 桌面端：圆形扩散
• 移动端（max-width: 768px）：底部划入 + 淡出

6.2 主题状态 API（src/stores/theme.ts）

import { themeMode, resolvedTheme, toggleTheme, initTheme } from '@/stores/theme'

themeMode.get()        // 'light' | 'dark' | 'system'
themeMode.set('dark')  // 写入 localStorage 并立即生效
resolvedTheme.get()    // 'light' | 'dark'（'system' 已按系统偏好解析）
toggleTheme()          // 在亮/暗之间切换（写入 localStorage）

initTheme() 在 BaseLayout 的 <script> 中调用一次即全局生效。

6.3 写自定义样式时如何兼容暗色

方式一（推荐）：只用变量

.my-box {
  background: var(--wp-surface);
  border: 1px solid var(--wp-border-light);
  color: var(--wp-text);
}

方式二：需要在暗色下换具体值时

.my-box { background: rgba(255,255,255,0.35); }
.dark .my-box { background: rgba(255,255,255,0.03); }   /* markdown.css 的 .code-header 就是这么做的 */

方式三：Tailwind 的 dark: 变体

<span class="text-accent-deep dark:text-accent">CC BY-NC-SA 4.0</span>

7. 全局样式文件与工具类

7.1 CSS 文件清单

7.2 main.css 提供的全局工具类

全局元素规则必须放进 @layer

main.css 里针对裸元素的规则（a / a:hover 的颜色与过渡）统一写在 @layer base { … } 内。原因：Tailwind v4 的工具类都位于 utilities 层，而未分层的规则优先级高于任何层——裸 a { color: … } 一旦漏在层外，就会压掉组件里给锚点写的 text-*（V1.0.9 修对比度时实测踩过这个坑）。

• 新增全局 CSS 规则一律放进 @layer（默认放 base）；这是 R4 的硬约束；
• 想覆盖 base 层的裸元素颜色：用工具类（如 text-ink-2），或写有意不分层的作用域规则（markdown.css 的 .post-content a 就属于后者，优先级更高，正文链接仍取 --wp-link）；
• 排查手段：DevTools 里若看到 a { color: var(--wp-link) } 压过 .text-ink-2，说明该规则漏在层外了。

7.3 动画 keyframes 一览

已有 prefers-reduced-motion 降级的位置：

弹窗关闭动画不靠 CSS 降级，由 SearchModal / PostPage 的 close() 在 prefers-reduced-motion 时直接瞬时隐藏（跳过 0.16s 等待）。动画时长在 CSS 与 JS（setTimeout(done, 160)）各有写死，改时长需两处同步。

尚无降级：music-player.css:62 的 music-spin 6s linear infinite（keyframes 定义在 :64），以及 main.css 的 wp-spin / wp-fade-in / wp-pop-in / wp-slide-in-right / wp-slide-in-left。

加新动画时建议补上 prefers-reduced-motion 降级。

7.4 Swup 过渡样式

.transition-swup-fade { opacity: 1; will-change: opacity; transition: opacity .32s cubic-bezier(.22, 1, .36, 1); }
html.is-animating .transition-swup-fade { opacity: 0; transition: opacity .16s ease-in; }        /* 淡出：旧内容渐隐 */
html.is-changing:not(.is-animating) .transition-swup-fade { opacity: 1; transition: opacity .35s cubic-bezier(.22, 1, .36, 1); } /* 淡入：新内容渐显 */
body > .swup-progress-bar { top: 0; z-index: 200; background-color: var(--wp-accent); }

8. 局部样式修改速查

8.1 文章内标题左侧色条

markdown.css：

.post-content :is(h1,h2,h3,h4,h5,h6)::before {
  content: ""; position: absolute; left: 0; top: 50%; translate: 0 -50%;
  width: 4px;                                  /* ← 色条宽度 */
  border-radius: 2px;
  background: var(--wp-accent);                /* ← 色条颜色 */
  height: calc(100% - var(--i) * 14%);         /* ← 层级递减幅度 */
}

同时在 .post-content :is(h1..h6) 上设置了 padding-left: 0.9rem（给色条留位置）与 scroll-margin-top: calc(60px + 1rem)（锚点跳转避开吸顶头部，改头部高度时要同步这里）。

8.2 提示容器（:::info 等）

每类容器需要改两个位置：

容器共同样式：padding: 1em 1.25em、border-radius: var(--radius-wp)、border-left-width: 3px、background: var(--wp-surface)、font-size: 0.98rem。

8.3 圆角不统一的问题

--radius-wp: 8px 只在部分位置生效。实际引用 var(--radius-wp) 的文件（全仓 grep）：markdown.css（.md-container :443、.img-frame :373/:395、blockquote :101、.md-toc :532）、ScrollControls.css:8、music-player.css:76/:135、FriendsPage.css:9。

以下位置是写死的 px，想全局改圆角需要一并替换：

建议：若要做「全局圆角开关」，把上述硬编码替换为 var(--radius-wp) 或新增 --radius-card 变量统一管理。

8.4 背景网格

body {
  background-image: var(--wp-grid-image);
  background-size: 28px 28px;      /* ← 必须与 SVG 的 width/height 一致 */
  background-attachment: fixed;    /* ← 注释说明：限制背景跟随滚动 */
}

鼠标划过点亮（参考顶栏 hover 的实心主题色方块）：BaseLayout 在 <body> 首子节点挂载 #grid-trail（position: fixed; z-index: -1，压在网格背景之上、页面内容之下），pointermove 按 28px 网格换算指针所在格子生成 .grid-trail-cell（var(--wp-accent) 实心方块、无圆角，grid-trail-out 0.65s 淡出后自动移除节点）；快速划过时线性插值补齐跳过的格子形成连续轨迹。仅响应鼠标（pointerType === 'mouse'），prefers-reduced-motion 下不生成。关闭方法：删除 #grid-trail 节点与对应脚本及 main.css 的 .grid-trail-cell 样式。

卡片「另一套主题」预览方窗（ProfileCard 名片与 PostCard 文章卡共用机制）：每张卡片内嵌一层 .card-preview 覆盖层（position: absolute; inset: -1px、overflow: hidden、border-radius: 12px、pointer-events: none、inert），覆盖层基础样式（窗口裁切、--preview-size、is-on 开关、reduced-motion 兜底）定义在 main.css 的共享块中，两种卡片都调用 src/lib/pointerPreview.ts 的 attachPointerPreview(card, options)（共用同一份结构、节流与动画时序，差异只在 options：prepareClone 定制克隆、syncClone 增量同步、resetOnDetach、hover 悬停镜像、resyncEvents）。鼠标在卡内移动时用 clip-path: inset(...) 只留出指针处 56×56 的方窗，窗口里是卡片克隆件套上相反主题 token 后的真实渲染（亮色模式给克隆加 .dark、暗色模式加 .light），所以看到的就是「切到另一套主题时长什么样」。克隆在脚本加载期构建一次并常驻，状态变化只做就地同步、从不重建节点（重建换新 <img> 要等解码，空帧在方窗里会表现为头像闪烁）。名片刷漆切换时钟时克隆层会跟着本体跑同一套 clip-path 关键帧（否则克隆层只能在全显/全裁之间二选一，方窗会在整段动效里停在切换前的画面），落定瞬间再由 profile-card-clock-settle 事件同步到终态；时钟模式下方窗照常唤起，显示反色时钟（亮段 --wp-accent 随反主题翻转）。文章卡克隆额外剔除 .card-badge / .card-actions 角标与操作条（方窗内不骑边），且因覆盖层 pointer-events: none 克隆收不到 :hover，脚本把指针命中的 data-hover 链接（标题/系列/标签）按序号镜像到克隆节点加 .preview-hover 类，由 PostCard.css 用克隆自身的反主题变量复刻 hover 效果。.light 与 :root 同级（main.css 的 :root, .light）且声明同一套亮色 token，专供这种「在子树里翻转主题」的场景。想改窗口尺寸改 main.css 的 --preview-size（仅此一处，两处卡片共享）；关闭方法：删掉组件里的 .card-preview 节点与对应的 attachPointerPreview() 调用、main.css 的共享 .card-preview 样式块，以及 PostCard.css 的 .preview-hover 镜像规则（.light 可保留，它只是 token 作用域）。详见 02-组件说明.md#41-profilecardastro 与 02-组件说明.md#42-postcardastro。

8.5 滚动条

::-webkit-scrollbar { width: 0; height: 6px; }         /* 竖向滚动条隐藏（宽度 0） */
::-webkit-scrollbar-thumb { background: var(--wp-border); border-radius: 3px; }
::-webkit-scrollbar-track { background: transparent; }

项目刻意隐藏了竖向滚动条，只保留 6px 的横向细滚动条（用于代码块/表格横向滚动）。若想恢复竖向滚动条，把 width: 0 改成 width: 8px。

9. 样式改动自检清单

• 亮色与暗色都检查过（ScrollControls 的主题按钮切换）
• 硬编码颜色是否改为 var(--wp-*) 或语义类
• 新增颜色是否同时定义了 :root 与 .dark 两套值
• --wp-grid-image 里的 stroke='%23XXXXXX' 是否与新主色一致
• AboutPage.astro 的 16 处 #E86233 是否需要同步
• 移动端断点 768px / 640px / 400px 是否正常
• 新增动画是否补了 prefers-reduced-motion 降级
• 改头部高度后，是否同步了 markdown.css 的 scroll-margin-top
• pnpm check 与 pnpm build 通过