迁移背景
在主题开发的早期阶段，很多颜色值以硬编码形式散布在 CSS 各处：#fff、#f1f5f9、#e2e8f0、#1a1a2e、#333 等。随着暗色模式的引入，这些硬编码值成为主题切换的最大障碍——暗色模式下它们不会自动变化，导致出现亮色背景上白色文字消失、暗色区域与相邻元素格格不入等问题。
统一迁移到 CSS 自定义属性（CSS 变量），可以实现在一处修改变量值，全局生效，同时暗色模式只需覆盖变量定义即可自动适配。
颜色映射表
梳理所有硬编码颜色并根据用途映射到对应的 CSS 变量：
| 硬编码值 | 用途 | 替换为 |
|---|---|---|
#fff / #ffffff | 卡片背景 | var(--bg-card) |
#f1f5f9 | 浅灰背景 / 表格条纹 | var(--bg-secondary) |
#e2e8f0 | 边框色 | var(--border-color) |
#cbd5e1 | 较深边框 | var(--border-light) |
#1a1a2e | 深色文字 / 标题 | var(--text-primary) |
#333333 | 正文文字 | var(--text-primary) |
#64748b | 辅助文字 / 元信息 | var(--text-secondary) |
#94a3b8 | 占位符 / 禁用文字 | var(--text-muted) |
关键选择器迁移
related-card 组件
1/* 迁移前 */
2.related-card {
3 background: #fff;
4 border: 1px solid #e2e8f0;
5}
6
7.related-card:hover {
8 border-color: #cbd5e1;
9 box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
10}
11
12/* 迁移后 */
13.related-card {
14 background: var(--bg-card);
15 border: 1px solid var(--border-color);
16}
17
18.related-card:hover {
19 border-color: var(--border-light);
20 box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
21}
阴影色 rgba(0, 0, 0, 0.08) 不需要替换——阴影在亮暗模式下均使用黑色，只是透明度不同，这已经通过暗色模式下的 box-shadow 微调来处理。
post-nav-item 组件
1/* 迁移前 */
2.post-nav-item {
3 background: #f8fafc;
4 border: 1px solid #e2e8f0;
5 color: #333;
6}
7
8/* 迁移后 */
9.post-nav-item {
10 background: var(--bg-secondary);
11 border: 1px solid var(--border-color);
12 color: var(--text-primary);
13}
post-content details 折叠块
1/* 迁移前 */
2.post-content details {
3 background: #f1f5f9;
4 border: 1px solid #e2e8f0;
5 border-radius: 8px;
6}
7
8/* 迁移后 */
9.post-content details {
10 background: var(--bg-secondary);
11 border: 1px solid var(--border-color);
12 border-radius: 8px;
13}
series-nav-item 系列导航
1/* 迁移前 */
2.series-nav-item {
3 background: #f8fafc;
4 border-left: 3px solid #e2e8f0;
5}
6
7.series-nav-item.current {
8 border-left-color: #3182ce;
9 background: #eff6ff;
10}
11
12/* 迁移后 */
13.series-nav-item {
14 background: var(--bg-secondary);
15 border-left: 3px solid var(--border-color);
16}
17
18.series-nav-item.current {
19 border-left-color: var(--color-primary);
20 background: var(--bg-primary-hover);
21}
迁移成果
本次迁移覆盖了 main.css 和 custom.css 中的以下选择器：
| 选择器区域 | 迁移点数 |
|---|---|
.related-card 相关推荐卡片 | 8 处 |
.post-nav-item 上下篇导航 | 6 处 |
.series-nav-item 系列导航 | 5 处 |
.post-content details 折叠块 | 4 处 |
.post-content blockquote 引用块 | 3 处 |
.post-content table 表格 | 7 处 |
.sidebar-widget 侧边栏组件 | 9 处 |
| 合计 | 42 处 |
后续维护
迁移完成后建议遵循以下规范：
- 新增样式一律使用 CSS 变量，禁止引入新的硬编码颜色
- 在 Stylelint 中配置
color-no-hex规则（排除变量定义文件） - 每新增一个颜色变量，同步在暗色模式
[data-theme="dark"]块中定义其暗色值 - 定期审查 CSS 文件，发现遗漏的硬编码颜色及时迁移
CSS 变量不仅解决了暗色模式切换的问题，也让整个主题的颜色体系变得清晰可维护——从「散落在各处的魔法数字」变成了「有名称、有层级、有文档的语义化设计令牌」。
留言评论
期待你的想法评论加载中