移动端深色模式在iOS Safari失效主因是首屏渲染前未同步data-theme、缺失meta color-scheme声明、:root变量未全定义；需在head顶部内联JS立即设置data-theme，确保UA控件与Shadow DOM正确响应。
移动端深色模式在 iOS Safari 上失效，90% 是因为没同步初始化 data-theme、漏写 <meta name="color-scheme" content="light dark">，或变量没全定义在 :root 里。
为什么写了 @media (prefers-color-scheme: dark) 在手机上还是白屏闪动
iOS Safari 首次渲染发生在媒体查询生效前，:root 变量已按默认值计算完毕。等 JS 或媒体查询触发时，页面已经画了一次浅色，再重绘就“闪”。这不是 CSS 写错了，是渲染流水线卡在了 HTML 解析阶段。
- 必须在
最顶部内联极简 JS，用window.matchMedia('(prefers-color-scheme: dark)').matches立即读取并设置document.documentElement.setAttribute('data-theme', 'dark') - 这段脚本不能等
DOMContentLoaded，也不能打包进外部 JS —— 渲染阻塞前就得执行 - 只靠媒体查询不设
data-theme，html[data-theme="dark"]类型的选择器根本不会命中，所有覆盖规则都白写
:root 变量必须全部声明且顺序严格
CSS 自定义属性不继承、不监听、不重算，只在解析时取值。漏一个变量，比如 --border-color 没定义，组件里写 border: 1px solid var(--border-color, #e0e0e0)，深色下 fallback 就是浅灰边框，层级直接糊掉。
- 所有变量必须先在顶层
:root声明默认值：--bg-color: #ffffff;、--text-primary: #1a1a1a;、--border-color: #e0e0e0; - 深色覆盖必须后置，且只能用
:root[data-theme="dark"]或:root.dark，不能用.dark :root（作用域错） - 不要把
@media (prefers-color-scheme: dark)嵌套在@media (max-width: 768px)里 —— Safari 12.1 之前完全不识别
原生控件不随主题变色？缺了 <meta name="color-scheme"> 和 color-scheme 声明
<input>、<select></select>、滚动条 thumb、<progress></progress> 轨道这些 UA 控件，CSS 变量管不了。它们只响应系统语义色（Canvas、CanvasText），而语义色开关是 <meta> 标签和 color-scheme CSS 规则共同控制的。
立即学习“前端免费学习笔记（深入）”；
-
<meta name="color-scheme" content="light dark">必须硬写在最顶部，JS 动态插入无效 -
html { color-scheme: light dark; }必须存在，且需配合<meta>才能激活 UA 映射 - 变量中尽量用
Canvas、CanvasText这类系统语义色，而不是硬写#121212，否则高对比度模式或辅助技术会失效
Shadow DOM 组件内部样式不响应主题切换
自定义元素（如 <my-card></my-card>）若用了 Shadow DOM，它内部无法继承外部 :root 的变量。浏览器把它当独立样式上下文处理。
- 必须在
:host或::slotted里手动重声明变量：:host { --bg-color: var(--bg-color, #ffffff); } - 或者在组件内联
<style></style>中再次写:root覆盖块（不推荐，破坏复用） - 第三方 UI 库（如 Lit、Stencil 组件）同理，得查文档看是否支持主题令牌注入，否则要 wrapper 层手动透传
真正难的不是写几行 CSS，而是让变量在首屏渲染前就“到位”，让 UA 控件认出你在认真适配，让 Shadow DOM 不自闭，让 localStorage 的值不被 JS 加载时机吃掉 —— 这些点串起来，才是移动端深色模式不闪、不糊、不卡的底线。
