文档站暗了，Demo 还亮着#

有人切到暗色，截图发过来：四周已经是深底，中间 Demo 还是浅灰一块，像没贴牢的贴纸。第一反应是「样式没写到」，翻代码才发现更尴尬——根本不是漏写一行 CSS。

怎么绕进去的#

文档站（Rspress）的明暗，改的是页面壳：html 上挂 dark，正文和侧栏跟着走。
组件 Demo 走另一套：外面包着配置根节点，用组件库自己的主题算法决定背景和字色。多数示例写死了偏后台的浅色算法，跟文档站的 dark 完全不通信。

所以站点变暗时，Demo 理直气壮地继续亮。只有个别「主题演示」页自己在内部切换，才会变——那也不是跟着站点走。

同一周还踩了两个看起来像「样式问题」、其实是约定问题的坑：

• 侧栏想给未完成组件挂「敬请期待」徽章。框架的 tag 字段按图片 / SVG 解析，中文被当成图片地址，侧栏直接花掉。后来改成写进链接文案。
• 未完成项一度共用同一个占位链接，结果点开一个，侧栏里所有同链项一起高亮——不是多选逻辑坏了，是路由撞车。

怎么收的#

Demo 统一包一层「跟着文档站明暗走」的提供者：亮色用后台 / 品牌浅色算法，暗色切到组件库 dark。写进组件开发计划，避免后人再写死浅色。

代码块和 Demo 容器加了内边距，暗底下不再跟背景糊成一片。侧栏未完成项用文案标注，占位路由按项拆开，避免「点一个亮一串」。

修跟随后又冒出过主题开关失灵——说明文档壳、Demo 容器、全局样式三者只要有一处抢状态，体感就又断。这类问题适合回归清单里留一条：切一次明暗，看壳、Demo、代码块是否同向变化。

留下的纪律#

文档站可以有自己的皮肤，组件库也可以有自己的 token，但嵌在文档里的活示例必须认文档的昼夜。两套电可以并存，插排上不能各插各的而不标清楚谁听谁的。