修复： 回到顶部按钮和进度条不显示的bug

README.md

@@ -48,6 +48,7 @@ pnpm dev
 | `pnpm build` | 构建到 `dist/`，并跑 Pagefind 建立搜索索引 |
 | `pnpm preview` | 本地预览构建产物 |
 | `pnpm check` | Astro 的类型与内容校验（本项目没有单元测试框架，这就是唯一的自动检查） |
+| `pnpm verify:css` | 单独跑构建产物 CSS 自检（`pnpm build` 和 `deploy.sh` 里都会自动跑） |
 | `pnpm new-thought "..."` | 快速创建一条「偶得」（见下） |
 
 ## 项目结构
@@ -97,6 +98,27 @@ onPage("my-widget", () => {
 页面级的小交互如果**不需要 JS** 就别写 JS：阅读进度条和回到顶部按钮的显隐都由
 CSS 滚动驱动动画（`animation-timeline: scroll()`）负责，脚本只管点击与老浏览器降级。
 
+### ⚠️ 滚动驱动动画的两条硬规矩
+
+2026-09-21 踩过一次：线上按钮不显示、本地 dev 一切正常。原因是 Lightning CSS
+（Tailwind v4 的压缩器）把 `animation-timeline` 并进了 `animation` 简写，产出
+`animation: linear both back-to-top-reveal scroll(root)` —— 而 WebKit 不认简写里的
+timeline 分量（[webkit#293276](https://wiki.webkit.org/show_bug.cgi?id=293276)），
+**整条声明被判无效丢弃**，元素永远停在初始的隐藏样式；更坑的是
+`CSS.supports("animation-timeline: scroll()")` 照样返回 true，运行时特性检测看不出问题
+（[lightningcss#815](https://github.com/parcel-bundler/lightningcss/issues/815)）。因此：
+
+1. **写 CSS 时**：`animation-timeline` / `animation-range` 那条规则的选择器要和
+   `animation` 简写那条**不同**（现有代码用 `.reading-progress > .reading-progress-bar`
+   和 `.back-to-top[data-back-to-top]`），否则压缩器会把两条相邻的同选择器规则合并。
+   刻意用后代 / 属性选择器而不是 `:where()`，是为了让特异性不低于简写那条 ——
+   `animation` 简写会把 `animation-timeline` 重置回 `auto`。
+2. **写 JS 时**：不要用 `CSS.supports()` 判断滚动动画是否可用，直接读
+   `getComputedStyle(el).animationName` —— 只有这个才能反映「规则到底有没有活下来」。
+   `src/scripts/back-to-top.ts` 就是这么做的，CSS 那边一旦失效它会自动接管。
+
+`pnpm build` 和 `deploy.sh` 都会跑 `scripts/verify-build-css.mjs` 拦截这类回退。
+
 ## 写作
 
 内容集合定义在 `src/content/config.ts`，共三个：