深色模式

Birdpaper UI 通过 CSS 变量实现深色模式，所有组件自动适配，业务侧无需额外处理。只需在根元素切换类名，整套色彩体系即可平滑过渡。

---

实现原理

深色模式通过在根元素添加 .dark 类名切换。所有组件使用 CSS 变量引用颜色，变量值在浅色/深色模式下自动映射，组件代码无需任何修改。

/* 浅色模式 */
:root {
  --bp-primary-6: #165dff;
  --bp-gray-0: #ffffff;
}

/* 深色模式：.dark 下会将语义变量映射到深色色板 */
.dark {
  --bp-primary-6: var(--bp-primary-dark-6); /* #3c7eff */
  --bp-gray-0: var(--bp-gray-dark-0); /* #141414 */
}

原理：.dark 类下的变量会覆盖 :root 的默认值，组件通过 var(--bp-primary-6) 引用时，实际取值由当前模式决定。

---

色阶方向

深色模式下色阶方向反转，1 为最深，10 为最浅。这意味着相同的变量名在不同模式下指向不同的实际色值。

1	最浅底色	最深底色
6	主色	主色（亮度提升）
10	最深文本	最浅文本

品牌色示例

以品牌色（Primary）为例，展示色阶在两种模式下的实际色值：

1	#e8f3ff	极浅蓝	#000d4d	极深蓝
6	#165dff	主色蓝	#3c7eff	亮蓝
10	#000d4d	极深蓝	#eaf4ff	极浅蓝

提示：功能色在深色模式下亮度提升约 20%，确保在深色背景上保持足够的视觉冲击力。

---

中性色映射

中性色（Gray）在深色模式下完全反转，浅色模式的最浅色对应深色模式的最深色，反之亦然：

0	白色背景	#ffffff	深色背景	#141414
1	次级背景	#fafafa	次级背景	#1f1f1f
2	边框	#f0f0f0	边框	#262626
8	正文文本	#262626	正文文本	#f0f0f0
10	最深文本	#141414	最浅文本	#ffffff

指南：业务侧直接使用 var(--bp-gray-0) ~ var(--bp-gray-10) 即可，无需关心当前模式——变量值会自动切换。切勿在业务代码中硬编码具体色值。

---

使用方式

切换深色模式

通过在根元素添加 / 移除 .dark 类名即可切换：

// 添加深色类名
document.documentElement.classList.add("dark");

// 移除深色类名（切回浅色）
document.documentElement.classList.remove("dark");

切换状态持久化

建议将用户偏好保存到 localStorage，页面加载时恢复：

// 切换时保存
const toggleDark = () => {
  const isDark = document.documentElement.classList.toggle("dark");
  localStorage.setItem("theme", isDark ? "dark" : "light");
};

// 页面加载时恢复
const saved = localStorage.getItem("theme");
if (saved === "dark") {
  document.documentElement.classList.add("dark");
}

跟随系统偏好

也可以根据操作系统的偏好自动切换：

const prefersDark = window.matchMedia("(prefers-color-scheme: dark)");

// 初始化时跟随系统
if (prefersDark.matches) {
  document.documentElement.classList.add("dark");
}

// 监听系统偏好变化
prefersDark.addEventListener("change", (e) => {
  document.documentElement.classList.toggle("dark", e.matches);
});

在 CSS 中使用

组件内部已通过 CSS 变量自动适配，业务侧如需自定义样式，直接引用变量即可：

/* 直接使用变量，会根据当前模式自动切换 */
.my-element {
  color: var(--bp-gray-10);
  background: var(--bp-gray-0);
  border: 1px solid var(--bp-gray-2);
}

/* 需要透明度时使用 RGB 变量 */
.my-overlay {
  background: rgba(var(--bp-gray-0-rgb), 0.8);
}

提示：所有颜色变量均提供 -rgb 后缀的 RGB 版本，用于 rgba() 场景。详见 色彩 文档。

---

适配规范

组件在深色模式下的适配遵循以下规则，确保可读性和视觉舒适度：

文字颜色	使用高色阶值（8 - 10）	保证在深色背景上的对比度
背景色	使用低色阶值（0 - 2）	降低视觉疲劳，营造沉浸感
边框色	使用中低色阶值（2 - 3）	保持可见但不突兀
功能色	主色（6）亮度适当提升	保证在深色背景上的可辨识度
阴影	降低不透明度	避免在深色背景上过于生硬

指南：业务侧自定义组件时，遵循以上规则可保证与 Birdpaper UI 组件库在深色模式下的视觉一致性。核心原则是——永远使用语义化 CSS 变量，不要硬编码色值。