该技能是前端深浅色主题的权威参考,核心围绕四个原语:color-scheme 声明页面支持的配色方案,light-dark() 按属性分支,@media (prefers-color-scheme) 按规则块分支,<picture><source media="(prefers-color-scheme: dark)"> 按图片分支。
主要能力与用法:
- 仅跟随系统的极简方案,无需 JS、无需开关:在 :root 声明 color-scheme: light dark,并用 light-dark() 为 --bg、--fg、--accent、--border 等令牌分支,同时需保留 <meta name="color-scheme" content="light dark">。
- 三态切换(system/light/dark):通过 <html> 上的 data-theme 属性,system 时移除属性、light/dark 时设属性,并用 localStorage 中 theme 键持久化,二者必须同步为唯一事实来源。
- 防 FOUC:若仅跟随系统则不会闪烁;若有用户覆盖,须在 <head> 中、样式表之前同步内联脚本读取 localStorage 并设置 data-theme,禁止在 useEffect/DOMContentLoaded 等绘制后才应用。服务端持久化时可直接在响应中输出 <html data-theme="...">。
- 图片深色变体优先用 <picture><source media="(prefers-color-scheme: dark)"> 切换。
- 切换按钮用 aria-pressed(开关式用 aria-checked)表达激活态;可用 transition 平滑过渡,但需在 prefers-reduced-motion: reduce 时取消。
硬性规则:调用 light-dark() 前必须声明 color-scheme,否则只返回浅色分支;深色页面不可省略 color-scheme,否则滚动条与原生表单控件仍为浅色;能用 light-dark() 覆盖时不要重复整块 @media 规则;强制模式规则中也要同时设置 color-scheme(如 :root[data-theme="dark"]);默认跟随系统,将覆盖作为用户选择;主题控件须具备 aria 状态。
限制:light-dark() 只接受颜色或图片值,非颜色/图片分支须用 @media;浏览器支持不足时可用 @supports 门控。设计令牌基础设施、OKLCH 调色板、对比度合规、组件级覆盖不在本技能范围内。系统变更监听仅在用户选择 system 时有意义。具体价格、平台等信息暂未提供。