主题 · Elements

整个库的观感由根元素（<html>）上的五个属性决定：data-theme、data-accent、data-scene、data-density、data-contrast。@bysages/core 的主题引擎负责写入和保存，静态页面也可以直接手写这些属性。

import { applyTheme } from "@bysages/core";

applyTheme({
  mode: "dark",        // "light" | "dark" | "system"，默认 "system"
  accent: "zhusha",    // "auto" | "ink" | "qinghua" | "celadon" | "zhusha" | "feicui" | "jilan" | "qingjin"，默认 "auto"
  scene: "civic",      // "auto" | civic | enterprise | studio | tech | cupertino | expressive | fluent | material | sketch | missive | dispatch | metric | new-york
  density: "spacious", // "compact" | "default" | "comfortable" | "spacious"，默认 "default"
  contrast: "high",    // "auto" | "normal" | "high"，默认 "auto"
});

调用后它与当前主题合并、写入属性，并返回完整的 Theme。主题保存到 localStorage 的 bs-theme 键，传 persist: false 可以不保存；initTheme() 负责恢复，getTheme() 读取当前主题。

#明暗

data-theme="light" 是宣纸，data-theme="dark" 是暖调的漆黑——不用纯 #000，同样的色相关系提到更亮的层级。"system" 跟随系统的 prefers-color-scheme。

#主题色

data-accent 决定主要操作块和焦点光晕的颜色。语义色（成功、警告、危险、信息）是固定的，不随主题色变。

`accent`	颜色	说明
`ink`（或不设）	单色墨	默认，庄重
`qinghua`	钴蓝	青花
`celadon`	水绿	天水碧
`zhusha`	朱砂红	印泥红，常用于政务
`feicui`	翡翠绿	翡翠，家书场景的颜料
`jilan`	霁蓝	霁蓝，公牍场景的颜料
`qingjin`	青金	青金石蓝，格律场景的颜料
`auto`	场景的默认搭配	见下表

#场景

data-scene 调整整站的形状、密度、动效和光的方向，不分叉组件。十三个场景分两类，每个场景有一组默认的主题色和对比度：

`scene`	名称	面向	默认主题色	默认对比度
`civic`	典章	政务和大龄用户：直角、48px 大目标	`zhusha`	`high`
`enterprise`	信笺	安静的商用界面，适合长时间使用	`qinghua`	normal
`studio`	雅集	设计和编辑类产品，留白多	`celadon`	normal
`tech`	司南	现代工具类，精密高效	`ink`	normal
`cupertino`	圆融	移动端，柔和轻盈	`qinghua`	normal
`expressive`	飞白	活泼，动效优先	`zhusha`	normal
`fluent`	流水	克制的生产力套件	`qinghua`	normal
`material`	格物	靠投影分层的立体风格	`celadon`	normal
`sketch`	写意	手绘趣味	`zhusha`	normal
`missive`	家书	熟悉的手持端风格	`feicui`	normal
`dispatch`	公牍	办公场景的手持端风格	`jilan`	normal
`metric`	格律	讲究章法的生产力套件	`qingjin`	normal
`new-york`	玄素	单色开发者工具风	`ink`	normal

各场景的出处。 受众场景——典章、信笺、雅集、司南——是我们自己的案头；风格场景各自致敬一种设计语言，key 换成通用词让 API 保持我们自己的，但谱系正是意义所在，明说无妨：

`scene`	参考的气质来源
`cupertino` 圆融	iOS 的设计语言——柔和轻盈的手持端
`expressive` 飞白	弹簧动效驱动的移动端设计
`fluent` 流水	Fluent，克制的生产力套件
`material` 格物	Material，靠投影分层的立体风格
`missive` 家书	开源移动端样式规范（WeUI）的熟悉手感
`dispatch` 公牍	WeUI for Work，同一套手感换上办公的案头
`metric` 格律	TDesign，讲究章法的企业级设计系统
sketch 写意	手绘速写本与漫画
`new-york` 玄素	shadcn/ui，黑白单色的开发者工具气质（沿用其官方 style 名）

applyTheme({ scene }) 自动带上这对默认值；手动指定的 accent 或 contrast 优先。比如 applyTheme({ scene: "civic", accent: "qinghua" }) 保留典章的直角和大目标，主题色换成钴蓝。默认值也导出为 SCENE_DEFAULT_ACCENT / SCENE_DEFAULT_CONTRAST，代码里可以直接用。

#密度和对比度

data-density 只调整留白（间距、内边距、控件间隙），不动字号和对比度。data-contrast="high" 把次级文字和边线提到与主级相同的强度，并加深焦点光晕。

#覆盖令牌

主题负责选值，你的 CSS 可以改值。令牌都在 @layer bs.tokens 里，所以一条不加 layer 的覆盖规则就能生效：

css

:root {
  --bs-radius-sm: 4px;   /* 控件更方 */
  --bs-color-primary: var(--bs-color-ink);
}

属性也可以不挂在 <html> 上，挂在任意容器上——属性会级联下去，所以一块 data-scene="studio" 的面板可以嵌在 civic 页面里。