入门

Dark mode 暗黑模式

在 <html> 写 data-pvs-theme 切换同一组 --pvs-* 令牌；自定义样式必须用变量，不要写死色值。

核心用法（记住两件事）

开关在 <html>：data-pvs-theme="light" / "dark"（或按钮 data-pvs-theme-toggle 由 JS 改写该属性）
颜色走令牌：页面与组件用 var(--pvs-body-bg)、var(--pvs-surface)、pvs-bg-* 等；暗色只覆盖 [data-pvs-theme="dark"] 下同一组 --pvs-*，类名不变

点击切换作用于整页（含本侧栏与顶栏），不只是下方演示框。

最小 HTML

引 CSS + JS；按钮切换；自定义区块用令牌变量：

html

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="/assets/pivcss.css" />
    <style>
      /* 对：跟主题走 */
      .my-panel {
        background: var(--pvs-surface);
        color: var(--pvs-body-color);
        border: 1px solid var(--pvs-border-color);
      }
      /* 错：写死 #fff — 暗色下不会变 */
    </style>
  </head>
  <body class="pvs-bg-body">
    <button type="button" class="pvs-btn pvs-btn--outline" data-pvs-theme-toggle>明亮 / 暗黑</button>
    <div class="my-panel pvs-p-4">令牌驱动的面板</div>
    <script src="/assets/pivcss.min.js" defer></script>
  </body>
</html>

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="/assets/pivcss.css" />
    <style>
      /* 对：跟主题走 */
      .my-panel {
        background: var(--pvs-surface);
        color: var(--pvs-body-color);
        border: 1px solid var(--pvs-border-color);
      }
      /* 错：写死 #fff — 暗色下不会变 */
    </style>
  </head>
  <body class="pvs-bg-body">
    <button type="button" class="pvs-btn pvs-btn--outline" data-pvs-theme-toggle>明亮 / 暗黑</button>
    <div class="my-panel pvs-p-4">令牌驱动的面板</div>
    <script src="/assets/pivcss.min.js" defer></script>
  </body>
</html>

实时看切换

点顶栏或下面按钮；观察色块与状态行。当前 <html data-pvs-theme>：

<html data-pvs-theme="…">

pvs-bg-body

pvs-bg-surface

pvs-bg-primary

<div class="pvs-stack pvs-gap-3">
  <p class="pvs-m-0 pvs-text-sm">
    <code>&lt;html data-pvs-theme="<span data-pvs-theme-status>…</span>"&gt;</code>
  </p>
  <div class="pvs-docs__swatch-tray pvs-p-3 pvs-rounded-md">
    <div class="pvs-docs__swatch-grid">
      <div class="pvs-docs__swatch pvs-bg-body">
        <span class="pvs-docs__swatch-label">pvs-bg-body</span>
      </div>
      <div class="pvs-docs__swatch pvs-bg-surface pvs-border">
        <span class="pvs-docs__swatch-label">pvs-bg-surface</span>
      </div>
      <div class="pvs-docs__swatch pvs-bg-primary">
        <span class="pvs-docs__swatch-label pvs-docs__swatch-label--light">pvs-bg-primary</span>
      </div>
    </div>
  </div>
  <button type="button" class="pvs-btn pvs-btn--primary pvs-btn--sm" data-pvs-theme-toggle>切换明亮 / 暗黑</button>
</div>

1 · 引入运行时

仅引 CSS 时暗色令牌已在样式表里，但不会自动写 html 属性。要按钮切换或记住用户偏好，必须引 JS：

html

<link rel="stylesheet" href="/assets/pivcss.css" />
<script src="/assets/pivcss.min.js" defer></script>

<link rel="stylesheet" href="/assets/pivcss.css" />
<script src="/assets/pivcss.min.js" defer></script>

2 · 切换按钮

任意元素加 data-pvs-theme-toggle。JS 在 light / dark 间切换 document.documentElement 的 data-pvs-theme，并写入 localStorage 键 pvs-theme。

3 · 无 JS：写死暗色

不需要切换时，直接在根节点写属性（适合纯静态暗色站）：

html

<html lang="zh-CN" data-pvs-theme="dark">

<html lang="zh-CN" data-pvs-theme="dark">

明亮站可写 data-pvs-theme="light"，用于显式覆盖系统暗色偏好。

4 · 会随主题变的令牌

暗色段在 [data-pvs-theme="dark"]（及无偏好时的 prefers-color-scheme: dark）覆盖下列变量；组件类 pvs-card、pvs-btn 已内置引用。

类名	说明
`--pvs-body-bg` / `--pvs-body-color`	页面底与正文色
`--pvs-surface` / `--pvs-surface-muted`	卡片、面板底
`--pvs-border-color` / `--pvs-muted-color`	边框与次要字
`--pvs-primary`	主色（暗色段略提亮）
`--pvs-success-muted` 等	Alert/Badge/描边按钮的语义浅底 · 暗色段同步变深

自定义 CSS 请用 var(--pvs-surface)，不要写 #ffffff。完整令牌见基础 · 设计令牌。

css

/* 站点覆盖暗色 palette */
[data-pvs-theme="dark"] {
  --pvs-primary: #818cf8;
  --pvs-body-bg: #0c1222;
  --pvs-surface: #1a2332;
}

/* 站点覆盖暗色 palette */
[data-pvs-theme="dark"] {
  --pvs-primary: #818cf8;
  --pvs-body-bg: #0c1222;
  --pvs-surface: #1a2332;
}

5 · 跟随系统

未写入 localStorage.pvs-theme 且 <html> 未写 data-pvs-theme 时，pivcss.css 用 @media (prefers-color-scheme: dark) 自动套暗色令牌。仍建议引 JS，以便用户手动覆盖系统偏好。

类名速查

类名	说明
`<html data-pvs-theme="dark">`	根节点属性 · 激活暗色令牌
`data-pvs-theme="light"`	显式明亮 · 覆盖系统暗色
`data-pvs-theme-toggle`	按钮 · JS 切换并持久化
`localStorage pvs-theme`	用户偏好 · light / dark
`var(--pvs-*)` 自定义样式	跟主题走 · 禁止写死 hex 背景
`[data-pvs-theme="dark"] { --pvs-* }`	暗色换肤覆盖点
`prefers-color-scheme: dark`	无属性无偏好时的系统默认