SuperAPI AI 工具集

light-dark-mode

通用与其它

查看项目

更新于 10-16 00:29

技能介绍

用途:在支持浅色/深色模式、颜色主题切换、高对比度模式或响应 prefers-color-scheme 的项目中,实现或审查无障碍的颜色主题支持。仅在项目确实支持主题切换时加载。

主要能力与规则:

  • 关键规则:焦点是导航而非选择。键盘焦点或指针悬停经过主题选项时不得预览、选择或应用主题;只有用户按 Enter 或 Space 显式激活后才切换,避免键盘导航时颜色闪烁。
  • 必须使用可见的三选项选择器(System、Light、Dark),用带标签的 role="group" 包裹三个原生 <button type="button">,选中项用 aria-pressed="true",其余为 false。禁止单按钮循环、两态开关、隐藏选项的菜单、自定义 role="radio"、方向键即切换的 radiogroup、悬停/聚焦预览。
  • 键盘:支持 Tab、Shift+Tab、Enter、Space 及鼠标/触摸/语音等激活;焦点移动不改变主题。
  • 默认与存储:未显式选择时默认 system,且不得把系统偏好转存为 light/dark;存储键如 theme-mode,仅允许 system、light、dark,读写包 try/catch,存储不可用时当前页仍可用。
  • 应用模型:区分 selectedMode 与 resolvedTheme,根元素用 data-theme-mode 与 data-theme 属性;system 时监听 matchMedia("(prefers-color-scheme: dark)") 变化并更新渲染主题,但不覆盖已存模式。
  • 防闪烁:在 <head> 早期执行初始化脚本,安全读取并校验存储、默认 system、解析系统偏好、首次绘制前设置根属性与 color-scheme,并加入 <meta name="color-scheme" content="light dark">。
  • CSS:用语义化 CSS 自定义属性(如 --color-text、--color-background 等)配合 prefers-color-scheme 与 light-dark(),组件不得硬编码颜色。
  • 状态样式:选中态不能仅靠颜色,需结合 aria-pressed、图标、边框、字重、文本标签;焦点与选中态须可区分,使用 :focus-visible 真实 outline。
  • 强制颜色:在 forced-colors: active 下用系统颜色保证按钮边界、选中与焦点可辨识,图标用 currentColor。
  • 命名与状态:使用可见文本标签 System、Light、Dark,装饰图标加 aria-hidden="true" focusable="false";不要动态替换按钮标签;可用 aria-live="polite" 状态消息但避免冗长重复。
  • 减少动效:默认不做颜色过渡动画;如示例包含过渡须细微、尊重 prefers-reduced-motion、不延迟状态变化、不产生中间低对比状态。
  • 对比度:所有状态须满足 WCAG 2.2 AA,测试系统解析浅色/深色、显式浅色/深色、强制颜色、键盘焦点、选中、悬停、禁用控件、链接、表单字段、边框与图形对象。

限制:资料未提供安装命令、价格、平台或效果数据;示例代码较长,此处不完整抄录。规范以 mgifford/ACCESSIBILITY.md 中 examples/LIGHT_DARK_MODE_ACCESSIBILITY_BEST_PRACTICES.md 为准。