这类问题看似集中在一个 API 或参数上，真正决定可用性的却是状态归属、资源上限和失败后的恢复方式。 把白变黑、黑变白会破坏品牌色、状态色和层级。令牌应表达 surface、text、border、accent、danger 等用途，每个主题分别给值，组件不直接选择具体色号。
前端架构的核心不是目录层级，而是状态由谁拥有、事件能否重复执行、旧异步结果如何失效，以及卸载后监听器和资源是否真正归零。
先把实现决策说清楚
先从数据和协议能保证的事实出发，再决定界面承诺。下面的规则都应有明确所有者、边界值和兼容策略，不能只存在于某次代码评审的口头共识里。
- 基础色阶与语义令牌分层，组件只消费语义令牌和少量组件令牌。
- 主题在首屏脚本读取系统与本地偏好，挂载应用前设置属性避免闪烁。
- 交互、禁用、焦点和图表系列在每个主题单独验证对比度。
主题系统的价值是让视觉决策集中且可验证。语义令牌稳定后，深色、品牌变化和可访问性修复都不再依赖逐组件打补丁。
最容易漏掉的失败路径
边界条件会把隐藏假设变成真实事故。弱网、刷新、并发和容量上限必须组合测试，因为单独出现时它们往往都能被重试掩盖。
- 深色主题复用浅色阴影，黑背景上层级完全消失或产生脏光。
- 硬编码颜色散落组件，新增主题后需要全仓库搜索替换。
- 服务端或静态页面不知道偏好，首屏白闪后才切深色。
上线前怎样验证
验证需要先写预期状态轨迹，再执行故障注入。每个阶段同时核对用户可见结果、两端协议状态、持久记录和资源计数，才能证明闭环成立。
- 自动扫描令牌引用，禁止组件新增未批准的裸色值。
- 对主要页面运行对比度、键盘焦点、系统主题切换和首屏无闪烁测试。
- 在 OLED、低亮度和高对比系统模式下检查状态可辨识度而非只看截图。
当实现能够安全降级、重复执行不产生额外副作用、故障指标早于投诉出现时，这项能力才算具备长期维护价值。