在一个文件里改外观
全站的颜色、间距和字体都集中在一个 tokens 文件里。改完刷新即可。
想给站点换一套外观,从一个文件开始:
src/styles/tokens.css
核心颜色、间距阶梯和字体比例都在这里。组件和页面优先读取这些变量,而代码高亮等专用表面保留一小套本地色板。改核心变量,站点大部分会跟着变。
修改强调色#
在文件顶部附近找到 --color-blue。共有三处:
:root下的浅色模式prefers-color-scheme: dark媒体查询内的深色模式[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()。若想在宽屏上有不同的缩放曲线,在那里修改。
在深色模式下验证#
点击页头的主题切换。所有文字和表面颜色仍应满足对比度要求。
三处要检查:
- 自定义阴影。 浅色模式阴影用
rgba(0, 0, 0, …)。深色模式阴影需要更强,或接近黑色,才看得见。 - 硬编码颜色。 在
tokens.css、src/config/expressive-code.ts和src/styles/code.css之外,用 grep 搜索#和rgb(。代码块色板有意单独维护;其余通常应从 tokens 读取。 - 图片。 在白底上清晰的相片在近黑底上可能几乎消失。必要时给正文图片加细分割线或淡色背景。
修改字体栈#
默认栈以一小份 Pretendard 子集开头,回退到系统字体。
要加入品牌字体:
- 将
.woff2文件放入src/assets/fonts/。 - 在
tokens.css顶部附近添加@font-face块。 - 把该字体族放在
--font-sans的第一位。 - 仅当该字体对首屏至关重要时,在
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。若答案是「它说什么?」或「它去哪?」,那是配置。