企业官网建设流程全解析

用 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-theme="dark"] { color-scheme: dark; }

color-scheme: light dark表示"两种配色都支持，由浏览器按系统偏好选择"；而[data-theme="dark"]上的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）环节的落地操作：

1. 检查规则影响到的断点（breakpoints）与交互状态下的渲染 UI；
2. 在 DevTools 中确认计算样式（computed styles）与预期修复一致；
3. 发布前至少在一个移动端视口 + 一个桌面端视口下测试；
4. 若规则影响动效（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 attribute="class" // 把主题写为 html 上的 class（即 .dark） defaultTheme="system" // 默认跟随系统 enableSystem // 启用 prefers-color-scheme 探测 disableTransitionOnChange >

这正是规则文档方案的框架封装：enableSystem对应prefers-color-scheme媒体查询跟随；attribute="class"对应.dark类覆盖；defaultTheme="system"对应"未保存偏好时交给系统"。next-themes内部在加载时会读取localStorage（默认 key 为theme）并注入内联脚本，在 React 水合前就把类挂到<html>上，规避闪烁问题。

3. 三态切换组件：light → dark → system

规则文档演示的是二态data-theme切换，仓库的主题开关则实现了业界更完整的三态循环，见 apps/web/components/navigation/theme-toggle.tsx：

const 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.），保证屏幕阅读器用户也能理解控件状态——这是暗色模式组件本身的无障碍要求。组件还通过useHasMounted（useSyncExternalStore）在客户端挂载前渲染占位按钮，避免服务端/客户端主题状态不一致导致的闪烁。

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），说明"媒体查询探测"在仓库中被作为一组统一的无障碍偏好工具来管理。

常见坑与规避建议

基于规则文档与仓库实现，汇总几个高频踩坑点：

小结

暗色模式的最优实现路径是清晰的：语义化颜色令牌 +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