← 全部文章

在一个文件里改外观

全站的颜色、间距和字体都集中在一个 tokens 文件里。改完刷新即可。

想给站点换一套外观,从一个文件开始:

src/styles/tokens.css

核心颜色、间距阶梯和字体比例都在这里。组件和页面优先读取这些变量,而代码高亮等专用表面保留一小套本地色板。改核心变量,站点大部分会跟着变。

修改强调色#

在文件顶部附近找到 --color-blue。共有三处:

  1. :root 下的浅色模式
  2. prefers-color-scheme: dark 媒体查询内的深色模式
  3. [data-theme='dark'] 强制深色

三处都要改。入门模板在各模式中使用同一变量名,组件无需关心当前是哪种模式。

:root {
--color-blue: #197ca8; /* light mode */
}
[data-theme='dark'] {
--color-blue: #74c7dc; /* dark mode */
}

经验法则:浅色模式用较深色调(在白底上对比度足够),深色模式用较浅色调(在近黑底上对比度足够)。入门模板中的配色是好的起点;可以调整色相,但保持这种对比关系。

Scroll dark turns on here#

滚动深色默认关闭。本示例仅为演示而开启。在任意文章 frontmatter 中添加 focusEffect: 'scroll-dark' 即可为该文启用。

---
title: 'Your post'
focusEffect: 'scroll-dark'
---

修改间距#

比例采用 4 点网格:

--space-1: 0.25rem; /* 4pt */
--space-2: 0.5rem;
--space-3: 0.75rem;
--space-4: 1rem;
--space-6: 1.5rem;
--space-8: 2rem;

组件引用 var(--space-4),而不是裸写 1rem。把 --space-4 翻倍会让全站每个「一格」间距都翻倍,这通常不是你想要的。改一两个具体阶梯更合适。

常见调整:

  • 更紧凑的正文:降低 --space-6 和 --space-8。
  • 更宽松的标题:提高 --space-10 和 --space-12。

修改字体比例#

Tone 以 16px 为基准,采用克制的字体阶梯:

--text-large-title: 2.125rem; /* page hero */
--text-title-1: 1.75rem; /* featured */
--text-title-2: 1.375rem; /* section heading */
--text-headline: 1.0625rem; /* list titles */
--text-body: 1.0625rem; /* body */
--text-callout: 1rem; /* descriptions */
--text-footnote: 0.8125rem; /* dates, captions */

想要更紧凑的主题,可将每级约缩小 10%:

--text-large-title: 1.875rem;
--text-title-1: 1.5rem;
--text-title-2: 1.25rem;

文章标题大小在 src/styles/layouts/post.css 中直接用 clamp()。若想在宽屏上有不同的缩放曲线,在那里修改。

在深色模式下验证#

点击页头的主题切换。所有文字和表面颜色仍应满足对比度要求。

三处要检查:

  1. 自定义阴影。 浅色模式阴影用 rgba(0, 0, 0, …)。深色模式阴影需要更强,或接近黑色,才看得见。
  2. 硬编码颜色。 在 tokens.css、src/config/expressive-code.ts 和 src/styles/code.css 之外,用 grep 搜索 # 和 rgb(。代码块色板有意单独维护;其余通常应从 tokens 读取。
  3. 图片。 在白底上清晰的相片在近黑底上可能几乎消失。必要时给正文图片加细分割线或淡色背景。

修改字体栈#

默认栈以一小份 Pretendard 子集开头,回退到系统字体。

要加入品牌字体:

  1. 将 .woff2 文件放入 src/assets/fonts/。
  2. 在 tokens.css 顶部附近添加 @font-face 块。
  3. 把该字体族放在 --font-sans 的第一位。
  4. 仅当该字体对首屏至关重要时,在 src/components/BaseHead.astro 中添加 preload。

若新字体是可变字体,保留 font-weight: 100 900 或其支持的范围。若是静态字体,只列出实际使用的字重。

当 token 不够用时#

有时单个组件需要系统里没有的值。两种做法:

  • 局部 CSS 变量。 在组件的作用域样式块内定义 --feed-date-column。PostFeed 已用它做布局列宽。
  • 新 token。 若多个组件都会用到,在 tokens.css 添加新 token 并在各处使用。

一次性布局值优先用局部变量。涉及颜色、间距、字体或动效时,优先用新 token。

什么不该放进 tokens#

token 文件用于视觉原语。不要放:

  • 文案字符串 — 它们在 src/ui.ts 和 astro-theme-config.ts。
  • 路由路径。
  • 功能开关。

若答案是「它长什么样?」,那是 token。若答案是「它说什么?」或「它去哪?」,那是配置。