用 prefers-color-scheme 与 CSS 自定义属性实现暗色模式：Front-End-Checklist 规则实战指南

用 prefers-color-scheme 与 CSS 自定义属性实现暗色模式Front-End-Checklist 规则实战指南【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本文是 Front-End-Checklist 仓库中 dark-mode-css 规则文档 的深度解读与实战指南。文章围绕用prefers-color-scheme媒体查询 CSS 自定义属性实现暗色模式这一核心主题展开结合仓库 Web 应用Next.js Tailwind v4 shadcn 风格的真实实现讲解语义化颜色令牌设计、系统偏好跟随、手动切换、原生控件配色与图片处理等完整方案。读完本文你将掌握一套不依赖任何框架、且可平滑迁移到next-themes等主流方案的暗色模式实现方法并能用 DevTools 完成可验证的验收检查。规则速览它要求什么该规则在 skills/dark-mode-css/SKILL.md 中定义为优先级medium中难度intermediate中级预估耗时25 分钟核心诉求站点应自动适应用户的系统配色偏好浅色/深色无需用户寻找手动开关推荐做法用media (prefers-color-scheme: dark)应用暗色样式把明/暗两套颜色定义为:root上的 CSS 自定义属性变量实现一键切换如需手动开关则用localStorage保存偏好并设置data-theme属性同时确保暗色配色满足 WCAG 对比度要求规则文档给出了检查清单Check、修复思路Fix、讲解要点Explain与代码审查Code Review四个视角其中检查环节尤其值得注意检查样式表中是否存在硬编码颜色hard-coded colors因为这类颜色在暗色模式下必然出错是规则要消灭的主要问题。为什么值得做暗色模式不是装饰规则文档从用户体验角度给出了明确依据超过一半的用户偏好暗色模式用于在低光环境下减轻眼部疲劳对光敏感photosensitivity的用户而言暗色模式是刚需而不是偏好通过prefers-color-scheme跟随系统用户无需在网站内寻找开关体验成本为零借助 CSS 自定义属性暗色模式是一次干净、可维护的增量改造而不是破坏性的整体重构。第一步定义语义化颜色令牌不是dark-blue而是color-primary暗色模式的关键设计决策是颜色令牌必须按语义命名而非按字面颜色命名。规则文档强调不要定义--color-dark-blue这种绑定具体颜色的变量而要定义--color-primary这类语义变量——这样组件永远只关心主色是什么而不关心主色在暗色下长什么样。规则文档给出的完整范式如下/* ✅ 定义语义化颜色令牌——不是 dark-blue 而是 color-primary */ :root { /* 浅色模式取值默认 */ --color-surface: #ffffff; --color-surface-elevated: #f9fafb; --color-text: #111827; --color-text-muted: #6b7280; --color-border: #e5e7eb; --color-primary: #2563eb; --color-primary-foreground: #ffffff; --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.05); }第二步在媒体查询里只重定义变量不碰组件暗色模式的全部魔法在于在prefers-color-scheme: dark媒体查询里重定义同一组变量组件样式一行都不用改。/* 暗色模式只需重定义同一组变量 */ media (prefers-color-scheme: dark) { :root { --color-surface: #0f172a; --color-surface-elevated: #1e293b; --color-text: #f1f5f9; --color-text-muted: #94a3b8; --color-border: #334155; --color-primary: #3b82f6; --color-primary-foreground: #ffffff; --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.3); } } /* 组件使用变量——无需任何暗色模式专属的组件 CSS */ .card { background: var(--color-surface-elevated); border: 1px solid var(--color-border); color: var(--color-text); box-shadow: var(--shadow-sm); }这就是变量一层变、组件全局变的核心收益暗色模式不再是散落在各组件里的补丁而是收敛到一个集中定义颜色的位置可维护性大幅提升也符合规则文档without changing any component styles不改变任何组件样式的要求。第三步支持手动切换data-theme localStorage系统偏好跟随无法覆盖用户在系统浅色、但就是想看深色网站的场景因此规则文档给出了一致的手动覆盖方案用data-theme属性覆盖系统偏好用localStorage持久化用户选择。CSS 侧为data-theme属性分别定义两套取值/* 允许>// 手动切换 localStorage 持久化 function setTheme(theme) { document.documentElement.setAttribute(data-theme, theme) localStorage.setItem(theme-preference, theme) } // 页面加载时——优先尊重已保存的偏好否则交给媒体查询自动处理 const saved localStorage.getItem(theme-preference) if (saved) { document.documentElement.setAttribute(data-theme, saved) } // 若没有已保存的偏好媒体查询会自动处理注意这里的设计要点只有当用户主动做出选择时才写data-theme和localStorage。没有保存偏好时站点完全交给prefers-color-scheme跟随系统——这正是系统偏好优先、用户显式选择覆盖的经典层级。第四步用 color-scheme 同步原生控件prefers-color-scheme媒体查询只影响你自己的 CSS滚动条、表单控件、input、选择框等浏览器原生 UI默认仍是浅色。规则文档给出的解法是color-scheme属性:root { color-scheme: light dark; /* 浏览器根据系统偏好调整滚动条、表单控件等 */ } [data-themedark] { color-scheme: dark; }color-scheme: light dark表示两种配色都支持由浏览器按系统偏好选择而[data-themedark]上的color-scheme: dark则保证手动切换暗色时原生控件同步变暗避免深色页面 浅色滚动条的割裂感。第五步暗色模式下的图片处理截屏图、示意图、插画在深色背景下往往显得刺眼。规则文档给出了一个实用技巧在暗色媒体查询中统一降低图片亮度、轻微提升对比度。/* 暗色模式下降低图片亮度对截屏图和示意图很有效 */ media (prefers-color-scheme: dark) { img:not([src*.svg]) { filter: brightness(0.85) contrast(1.05); } }这里用img:not([src*.svg])排除 SVG是因为 SVG 通常是图标/线稿且常带有自身的主题色统一加滤镜可能破坏其设计。图片属于强相关素材之外的装饰性调整但直接影响暗色模式的观感质量值得纳入验收清单。第六步平滑过渡与页面加载闪烁在手动切换主题时直接跳变会显得生硬。规则文档提供了过渡方案/* 切换主题时添加平滑过渡 */ :root { transition: background-color 200ms ease, color 200ms ease, border-color 200ms ease; } /* 但页面加载时跳过过渡 */ .no-transition * { transition: none !important; }关键的工程细节是第二段页面首屏加载时不能有过渡动画。否则主题脚本尚未运行、暗色类尚未注入时页面会先以浅色或错误主题渲染再过渡到暗色造成肉眼可见的闪烁FOUC。no-transition类通常由内联脚本在document.documentElement上临时挂载、加载完成后移除。仓库 Web 应用也遵循同样思路在 apps/web/app/layout.tsx 中ThemeProvider显式设置了disableTransitionOnChange正是为了规避主题切换过程中的过渡闪烁。验收清单如何验证暗色模式Verification规则文档给出了 4 步验证流程这是可以检查Check环节的落地操作检查规则影响到的断点breakpoints与交互状态下的渲染 UI在 DevTools 中确认计算样式computed styles与预期修复一致发布前至少在一个移动端视口 一个桌面端视口下测试若规则影响动效motion、对比度contrast或布局稳定性layout stability直接验证这些面向用户的结果。实操提示在 DevTools 的 Rendering 面板中可强制模拟prefers-color-scheme: dark无需切换系统设置即可快速预览computed styles面板则可确认目标元素最终命中的变量值来自:root的哪一套定义。仓库实战Front-End-Checklist 的生产级暗色模式实现规则文档是纯 CSS 范式而本仓库的 Web 应用给出了同一范式在 Next.js 生态中的生产级落地可作为框架侧的最佳实践参照。1. class 策略.dark类 变量重定义仓库的全局样式 apps/web/app/globals.css 在:root中定义浅色主题变量随后在第 147 行通过.dark类选择器apps/web/app/globals.css整体重定义同一批变量——这正是规则文档只重定义变量思想的工程化用.dark类替代data-theme属性便于与 Tailwind v4 的dark:变体协作/* 浅色默认值节选来自仓库 globals.css */ :root { --background: oklch(1 0 0); --background-subtle: oklch(0.965 0 0); --foreground: oklch(0.205 0 0); --primary: oklch(0.567 0.159 275.208); --primary-foreground: oklch(1 0 0); /* ... */ } /* 暗色模式重定义同一组变量 */ .dark { --background: oklch(0.141 0.004 285.766); --background-subtle: oklch(0.21 0.006 285.82); --foreground: oklch(0.985 0 0); --primary: oklch(0.68 0.158 276.935); --primary-foreground: oklch(0 0 0); /* ... */ }注意仓库变量还同时承担了无障碍语义--priority-*与--category-*系列在深浅两套定义中均以AAA contrast为目标globals.css 中注释明确标注与规则文档暗色模式必须维持 WCAG 对比度的要求一一对应——暗色主题不能只是变暗还得保证文本可读性。2. next-themes开箱即用的系统偏好 持久化仓库在 apps/web/app/layout.tsx 中用next-themes的ThemeProvider包住整个应用配置为ThemeProvider attributeclass // 把主题写为 html 上的 class即 .dark defaultThemesystem // 默认跟随系统 enableSystem // 启用 prefers-color-scheme 探测 disableTransitionOnChange 这正是规则文档方案的框架封装enableSystem对应prefers-color-scheme媒体查询跟随attributeclass对应.dark类覆盖defaultThemesystem对应未保存偏好时交给系统。next-themes内部在加载时会读取localStorage默认 key 为theme并注入内联脚本在 React 水合前就把类挂到html上规避闪烁问题。3. 三态切换组件light → dark → system规则文档演示的是二态data-theme切换仓库的主题开关则实现了业界更完整的三态循环见 apps/web/components/navigation/theme-toggle.tsxconst cycleTheme () { if (theme light) { setTheme(dark) } else if (theme dark) { setTheme(system) } else { setTheme(light) } }三个状态分别渲染 Sun / Moon / Monitor 图标对应 light / dark / system按钮的aria-label会随当前主题动态更新如Current theme: dark. Click to change.保证屏幕阅读器用户也能理解控件状态——这是暗色模式组件本身的无障碍要求。组件还通过useHasMounteduseSyncExternalStore在客户端挂载前渲染占位按钮避免服务端/客户端主题状态不一致导致的闪烁。4. 浏览器主题色同步仓库在 apps/web/app/layout.tsx 中通过viewport.themeColor数组让浏览器地址栏/标签栏颜色也随系统偏好变化export const viewport: Viewport { width: device-width, initialScale: 1, maximumScale: 5, themeColor: [ { media: (prefers-color-scheme: light), color: #ffffff }, { media: (prefers-color-scheme: dark), color: #09090b } ] }这是prefers-color-scheme在非 CSS 场景的延伸应用通过media条件让同一份themeColor同时响应明/暗两套系统偏好保证 PWA/移动端浏览器的 UI 与页面主题一致。5. JS 侧的系统偏好探测工具仓库把prefers-color-scheme的 JS 探测封装为可复用工具函数见 apps/web/lib/accessibility/preferences.ts/** 返回用户偏好的配色方案light | dark | no-preference。 */ export function prefersColorScheme(): light | dark | no-preference { if (typeof window undefined) return no-preference if (window.matchMedia((prefers-color-scheme: dark)).matches) return dark if (window.matchMedia((prefers-color-scheme: light)).matches) return light return no-preference }这段实现有三个值得借鉴的细节一是服务端渲染安全typeof window undefined时返回no-preference避免在 SSR/SSG 阶段抛出 ReferenceError二是matchMedia是当前浏览器探测系统偏好的事实标准 API三是返回了no-preference这一中间态而非武断地二选一为不支持该媒体查询的旧浏览器保留了合理默认。同一文件中prefersReducedMotion()与prefersHighContrast()使用了完全相同的模式apps/web/lib/accessibility/preferences.ts说明媒体查询探测在仓库中被作为一组统一的无障碍偏好工具来管理。常见坑与规避建议基于规则文档与仓库实现汇总几个高频踩坑点问题现象规避方式硬编码颜色组件内直接写#fff/black暗色下无法覆盖全部抽成语义变量组件只引用var(--...)忽略原生控件深色页面配浅色滚动条/输入框:root声明color-scheme: light dark暗色容器内声明color-scheme: dark暗色对比度不足深底深字、链接不可辨明暗两套变量都以 WCAG AA/AAA 为目标设计用对比度工具逐一校验主题闪烁FOUC首屏先浅色后跳暗色内联脚本提前注入主题类next-themes等库用disableTransitionOnChange配合加载期禁用过渡深浅切换生硬手动切换瞬间跳变对background-color/color/border-color等加200ms左右过渡但页面加载期用.no-transition跳过忽略图片观感截图、示意图在暗色下过亮media (prefers-color-scheme: dark)中对非 SVG 图片施加brightness(0.85) contrast(1.05)滤镜三态缺失用户无法回到跟随系统提供 light / dark / system 三态循环参照仓库ThemeToggle组件小结暗色模式的最优实现路径是清晰的语义化颜色令牌 prefers-color-scheme媒体查询跟随系统 data-theme/.dark类支持手动覆盖 localStorage持久化 color-scheme同步原生控件。这套方案组件零改动、主题切换集中可控、天然满足无障碍对比度要求并且能够无缝映射到next-themes等主流框架方案——Front-End-Checklist 仓库本身就是规则文档references/rule.md 生产级实现layout.tsx、theme-toggle.tsx、globals.css相互印证的最佳教材。最后不要忘记规则文档的验收纪律发布前在 DevTools 中核对计算样式并至少在移动端与桌面端各测一个视口。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考