ThemeToggle

明暗档切换：一颗幽灵图标按钮，点一下按 modes 的顺序换下一档（缺省浅色 → 深色 → 跟随系统），modes 可裁成纯手动两档。读屏名报当前档（「外观：浅色」，文案取 useUiLocale().themeToggle），悬停提示是名字型 data-tip（页面要挂 XTooltip）。

不做分段器：三格加标签占一整块顶栏位，工作台与落地页都放不下。放进个人菜单的设置行时由宿主在左边配标签。

组件只是 useTheme() 的一个操作面——状态、持久化与 DOM 应用都在 composable 里，同页放几个都是同一份状态。

下面的 demo 会真的改掉文档站的明暗档并记住选择：组件写的是 html[data-theme] 与 color-scheme，和右上角调试面板作用于同一个元素（面板刷新即回默认，这里的选择会留下）。

基础

状态从哪来

状态、持久化与 DOM 应用都在 useTheme 里——组件本身不持有明暗档， modes 只决定这一处在哪几档间循环；存着的档不在 modes 里（只给两档而存的是 auto）时从第一档开始。

SSR / SSG 直出不用包 ClientOnly：服务端读不到已存档位，挂载前两端都按 auto 出图标，挂载后换成真实偏好。宿主自己把 preference / resolved 渲染成文字或属性时仍要自己做挂载门控——Vue 水合不纠正属性差异，服务端按 auto 出的值会残留。

API