{
  "slug": "themeswitcher",
  "end": "html",
  "curated": true,
  "summary": "原生主题切换：模式存 localStorage，品牌色写 CSS 变量，深浅靠根节点类。",
  "usage": [
    "三个模式选项 .kole-themesw-opt 各带 data-mode（light / dark / auto），点击写入 localStorage 的 kole-mode 后重渲染。",
    "实际深浅判定在 effective()：auto 时读 matchMedia(\"(prefers-color-scheme: dark)\") 的 matches，否则直接用 mode。",
    "深浅落地方式是给根节点加类：document.documentElement.classList.toggle(\"kole-dark\", actual === \"dark\")。",
    "品牌色是一组动态创建的 .kole-themesw-color（带 role=\"radio\"、aria-checked、tabindex），选中时写 document.documentElement.style.setProperty(\"--kole-color-brand\", brand)。",
    "读写 localStorage 都用 try / catch 包住，模式非法时回退 auto（frameworks/ThemeSwitcher.html:37）。",
    "系统主题变化有监听：media 的 change 事件里只在 mode === \"auto\" 时重渲染。"
  ],
  "bestPractices": [
    "模式与品牌色是两个独立状态（mode 与 brand），品牌色没有持久化，刷新后回到默认色。",
    "localStorage 的 try / catch 不要删，隐私模式下访问会抛异常导致整段脚本中断。",
    "选项与色点是运行时创建的，色点的 role / aria-checked / tabindex 都在 JS 里设置，改结构时注意这些属性也要跟着改。"
  ],
  "a11y": [
    "容器声明 role=\"radiogroup\" 与 aria-label，选项声明 role=\"radio\" 且脚本维护 aria-checked，这一组语义完整。",
    "色点与选项都补了 Enter / Space 键盘处理（e.key === \"Enter\" || e.key === \" \"），是本端无障碍做得最完整的一处。",
    "radiogroup 内缺少方向键在选项间移动的约定行为，只能用 Tab 逐个走。"
  ],
  "apiCarrier": {
    "kind": "attrs",
    "note": "H5 端的状态有三处落点：模式选项的 data-mode、根节点上的 kole-dark 类、以及 --kole-color-brand 这个内联 CSS 变量；localStorage 存模式，选项与色点由脚本创建并维护 role=\"radio\" 与 aria-checked。",
    "table": [
      {
        "name": "auto",
        "type": "类名",
        "desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:19）。"
      },
      {
        "name": "dark",
        "type": "类名",
        "desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:18）。"
      },
      {
        "name": "kole-btn",
        "type": "类名",
        "desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:25）。"
      },
      {
        "name": "kole-btn--primary",
        "type": "类名",
        "desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:25）。"
      },
      {
        "name": "kole-card",
        "type": "类名",
        "desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:23）。"
      },
      {
        "name": "kole-card__body",
        "type": "类名",
        "desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:24）。"
      },
      {
        "name": "kole-demo",
        "type": "类名",
        "desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:15）。"
      },
      {
        "name": "kole-desc",
        "type": "类名",
        "desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:13）。"
      },
      {
        "name": "kole-h2",
        "type": "类名",
        "desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:12）。"
      },
      {
        "name": "kole-page",
        "type": "类名",
        "desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:11）。"
      }
    ]
  },
  "resources": [
    {
      "file": "frameworks/ThemeSwitcher.html",
      "kind": "H5 原生",
      "desc": "该端实现（本页 API 与用法的唯一权威来源）。"
    },
    {
      "file": "frameworks/ThemeSwitcher.css",
      "kind": "样式",
      "desc": "该组件的样式文件，类名口径以它为准。"
    }
  ],
  "exampleIds": [
    "themeswitcher-ex-1"
  ],
  "notes": [
    "选项与 data-mode 见（frameworks/ThemeSwitcher.html:17-19），容器 role=\"radiogroup\" 见（frameworks/ThemeSwitcher.html:16）。",
    "色点创建与键盘处理见（frameworks/ThemeSwitcher.html:41-43），选项键盘处理见（frameworks/ThemeSwitcher.html:48）。",
    "深浅判定见（frameworks/ThemeSwitcher.html:50），根类切换与品牌色变量见（frameworks/ThemeSwitcher.html:53）与（frameworks/ThemeSwitcher.html:56）。",
    "系统主题监听见（frameworks/ThemeSwitcher.html:60-63）。"
  ]
}