Accent switch

在运行时切换 zzzUI 的强调色。12 种预设上的墨黑文字均清晰可读，通过一排色块选取，再次访问时沿用上次的选择。

安装

terminal

# once per project: where @zzzui items come frompnpm dlx shadcn@latest registry add @zzzui=https://zzzui.catforest.dev/r/{name}.jsonpnpm dlx shadcn@latest add @zzzui/accent-switch

示例

五种预设，为页面局部换色

accent-switch-preview.tsx

import { useRef } from "react";import { AccentSwitch } from "@/components/zero/accent-switch";import { Badge } from "@/components/zero/badge";import { Button } from "@/components/zero/button";import { Progress } from "@/components/zero/progress";import { Switch } from "@/components/zero/switch";import { Tabs, TabsList, TabsTab } from "@/components/zero/tabs";export default function AccentSwitchPreview() {  // this demo recolours only the box below; without `target` it recolours the page  const box = useRef<HTMLDivElement>(null);  return (    <div className="grid w-full max-w-md gap-4">      {/* five of the twelve: the ones clear of every rarity tier's hue */}      <AccentSwitch        accents={["lime", "cyan", "magenta", "leaf", "mono"]}        target={() => box.current}        storageKey={null}        aria-label="Accent of the preview"      />      <div        ref={box}        data-zero-accent="lime"        className="grid gap-5 border-(length:--zero-stroke) border-zero-ink bg-zero-surface p-5"      >        <div className="flex flex-wrap items-center gap-3">          <Button>Take the job</Button>          <Badge>Rush</Badge>          <Switch defaultChecked aria-label="Night routes" />        </div>        <Tabs defaultValue="open" size="sm">          <TabsList>            <TabsTab value="open">Open</TabsTab>            <TabsTab value="taken">Taken</TabsTab>          </TabsList>        </Tabs>        <Progress value={62} aria-label="Route done" />      </div>    </div>  );}

行为

预设定义在地基中：在 <html> 上将 data-zero-accent 设为 lime（默认）、cyan、magenta、amber、mint、sky、violet、mono、yellow、leaf、iris 或 orchid，作用于整个页面；设在任意元素上，则只作用于该元素内部。每种预设上的墨黑文字对比度都不低于 7 : 1（最暗的 magenta 恰为 7 : 1）。红色不在其中，因为它表示危险。yellow 与 lime 都接近焦点框的黄色；焦点框内侧留有一道墨黑间隙，因此在强调色填充上依然可见。另有几种预设与某个稀有度档位的色相相近：在显示稀有度的界面上，宜选用 lime、cyan、magenta、leaf 或 mono，以免把档位误认为强调色。

AccentSwitch 负责写入这个属性（写在 <html> 上，或 target 指定的元素上），并以 storageKey 为键把选择保存在 localStorage 中；storageKey 传入 null 时，选择仅在本次页面浏览中生效。它是一个单选组：可用方向键在色块之间切换，每个色块都有可访问名称。accents 决定这一排提供哪些预设。将 AccentScript 置于 <head> 中，已保存的强调色即可在页面绘制之前生效。空间不足以容纳全部 12 种预设，或需要自定义颜色时，请改用 Accent picker；两者保存强调色的方式相同。

圆角不可切换：zzzUI 只用斜切，不用圆角。最接近的调节项是斜切角度 --zero-slant；设为 0deg 时，所有切角都变为直角（参见用设计 token 为 zzzUI 定制主题）。

属性

AccentSwitch

属性	类型	默认值	说明
value / defaultValue / onValueChange	AccentPreset \| "#rrggbb"	"lime"	强调色，受控或非受控均可：预设名称，或自定义颜色（此时不选中任何色块）。
accents	AccentPreset[]	全部 12 种	这一排提供哪些预设。
target	() => HTMLElement \| null	<html>	写入 data-zero-accent 的元素。
storageKey	string \| null	"zero-accent"	保存选择所用的键；设为 null 则不保存。
aria-label	string	"Accent colour"	单选组的可访问名称。
labels	AccentLabelsInput	accentLabels	预设的名称换成其他语言（labels.names）；未提供的部分保持英文。

AccentScript

属性	类型	默认值	说明
storageKey	string	"zero-accent"	与 AccentSwitch 使用同一个键。