skinsuite 0.1.0

package/dist/views/params.js

@@ -0,0 +1,36 @@
+export const DEVICE_SCOPED_PARAMS = ['view', 'theme'];
+/** 值"存在且非空" —— 空串 / 空数组视为**未指定**，不顶掉兜底键 */
+function isPresent(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return value.trim() !== '';
+    if (Array.isArray(value)) {
+        return value.some(v => typeof v === 'string' && v.trim() !== '');
+    }
+    return true;
+}
+/**
+ * 按**设备**读取版式 / 配色参数
+ *
+ * @param query  路由 query（`route.query`）
+ * @param name   参数名（`'view'` / `'theme'`）
+ * @param device 当前设备 —— 容器用自己的设备常量传进来（文件位置即身份）
+ * @returns `query['<name>.<device>']` 优先；缺席或空值时退 `query[name]`；
+ *          两者都没有则返回 undefined，表示"**这台设备**没有被显式指定"
+ *
+ * ⚠️ 只决定"取哪个键"，**不做合法性校验** —— 校验属于各页 `pick*ViewId` 与配色注册表
+ *    （本函数也拿不到"当前包里有没有这套版式"）。返回值可能是数组（`?view=a&view=b`），
+ *    由下游按"非字符串即非法"处理，与改前的行为一致。
+ * ⚠️ 空串视为"未指定"：`?view.standard=` 不该把 `?view=compact` 顶掉 ——
+ *    部署方常把参数留空当作"这台设备不特殊指定"。
+ * ⚠️ 设备名是**宿主**的词汇表（本包不认识具体取值），所以这里只把它当字符串拼键；
+ *    「这个名字认不认得」由宿主的设备清单归一（`asThemeDevice`）。
+ */
+export function readDeviceParam(query, name, device) {
+    const scoped = query?.[`${name}.${device}`];
+    if (isPresent(scoped))
+        return scoped;
+    return query?.[name];
+}
+//# sourceMappingURL=params.js.map

package/dist/views/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../src/views/params.ts"],"names":[],"mappings":"AAqCA,MAAM,CAAC,MAAM,oBAAoB,GAAiC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpF,2CAA2C;AAC3C,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;IAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC7B,KAA0C,EAC1C,IAAuB,EACvB,MAAc;IAEd,MAAM,MAAM,GAAG,KAAK,EAAE,CAAC,GAAG,IAAI,IAAI,MAAM,EAAE,CAAC,CAAC;IAC5C,IAAI,SAAS,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACrC,OAAO,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "skinsuite",
+  "version": "0.1.0",
+  "description": "多主题 / 多版式机制的纯内核（零运行时依赖）：目录名与默认值的白名单常量、主题包契约类型、明暗 mode 与色系 tone、CSS 变量 token 的安全校验、设备维度 URL 参数读取。不碰 DOM / 构建器 / 路由，可在任意前端（Vue / React / Node / SSR）复用。",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "theme",
+    "design-token",
+    "css-variables",
+    "multi-theme",
+    "multi-layout",
+    "dark-mode",
+    "theme-switch",
+    "vue",
+    "react",
+    "zero-dependency",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yijiu2025/theme.git"
+  },
+  "homepage": "https://github.com/yijiu2025/theme#readme",
+  "bugs": {
+    "url": "https://github.com/yijiu2025/theme/issues"
+  },
+  "author": "qirly",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,100 @@
+/**
+ * 主题内核的**常量与白名单** —— 设备 / 页面 / 包 / 配色的取值集合
+ *
+ * 这些值原先散在 `oauth21/src/theme/index.ts`，2026-09-26 抽包 Stage 1 移到这里。
+ * 它们是**跨层共享的词汇表**：配色注册表、版式注册表工厂、参数读取、store、
+ * 以及目录口径关卡（`.tmp-probe/verify-theme-dirs.mjs`）全部按这几个常量对齐，
+ * 所以必须**只有一个来源** —— 改这里，其余各处跟着变。
+ *
+ * ⚠️ 本文件**零依赖**（不 import 任何东西），也不碰 DOM / 构建器 / 路由：
+ *    这是 `skinsuite` 能被任意前端复用的前提（见
+ *    docs/frontend/theme-package-extraction.md 的「〇、一条原则」）。
+ *
+ * @author yijiu2025
+ */
+
+/**
+ * 目录名 / id 的白名单正则
+ *
+ * 同时作用于**主题包名**、**配色 id**、**版式 id**、**页面名** —— 它们都会进
+ * `data-*` 属性与 CSS 属性选择器，因此只允许小写字母、数字、短横线。
+ * 不合规的目录**静默跳过**（一个写坏的目录不该让整页起不来），所以排查
+ * "加了主题没生效"时，第一件事就是核这条正则。
+ */
+export const THEME_ID_RE = /^[a-z0-9-]+$/;
+
+/**
+ * 空记录（registered 目录尚未产出任何记录）的占位配色 id
+ *
+ * ⚠️ 它**不再**表示"默认配色"：自 2026-09-24 起黑白是各设备下**具名的正式配色**
+ * （`<页面>/colors/{black,white}/`）。**默认配色**是下面的 `DEFAULT_THEME_COLOR`。
+ * 这里只用于空记录占位。
+ */
+export const DEFAULT_THEME_ID = 'default';
+
+/**
+ * 内置默认**主题包** id
+ *
+ * 它用在版式侧：该包的版式由容器**静态引入**（首屏零请求），其它包才需要惰性加载。
+ * 见 `theme/views/registry.ts`。
+ */
+export const DEFAULT_THEME_PACKAGE = 'default';
+
+/**
+ * 设备维度：**取值集合由宿主的设备清单声明**，内核不再自带一份
+ *
+ * === 为什么从这里搬走（2026-09-27）===
+ * 内核原先写着 `THEME_DEVICES = ['mobile','standard','mini']` —— 那是**某个应用的**
+ * 词汇表，不是机制的一部分。它带来的实际代价是"加一种设备要改好几处"，而其中一处
+ * 在包里、另外几处在宿主（判定、容器、路由、面板），漏一处就是静默的半生效。
+ * 现在：
+ *   • 内核只留「设备名是个 `[a-z0-9-]` 字符串」这一条**形态**约定；
+ *   • 取值集合、中文名、判定规则、容器位置，全部在宿主的设备清单里声明
+ *     （本仓 = `oauth21/src/theme/devices.ts`）。
+ * 内核因此可以在任何前端被复用 —— 那个前端有几台设备、叫什么，与内核无关。
+ *
+ * ⚠️ 内核里所有"需要知道设备取值集合"的函数都已改成**接收它**（而不是查常量）：
+ *    白名单校验在宿主（`asThemeDevice`），设备维度参数读取只需要"当前设备是谁"。
+ */
+
+/**
+ * 兜底页面：注册表类函数在调用点没给页面时的默认值
+ *
+ * 取 `login` 是因为它是认证流程的默认入口（未指定页面时最可能问的就是它）。
+ * 有明确页面的调用点（容器、面板）都应显式传 `page`，不要依赖这个兜底。
+ */
+export const DEFAULT_THEME_PAGE = 'login';
+
+/**
+ * 兜底**配色** id：该范围内没有更具体的指定时用它（2026-09-26 定）
+ *
+ * 用户口径：**默认版式 = `default` 包，默认配色 = `white`**。
+ * 配色注册表先找它；只有该范围里根本没有这套色（如以后某个版式只提供一套自命名的
+ * 配色）才退回「该范围 id 字母序第一」。
+ *
+ * ⚠️ 在它之前，兜底口径是"字母序第一"，而 `black < blue < cyan < rainbow < white`
+ *    → "默认外观"实际落在**黑系**，再靠首屏系别对齐纠正成白系。"两步走"有两个坑：
+ *      ① 语义撕裂：基线 SCSS 的 `:root` 是浅底，兜底却是深色配色；
+ *      ② **静默事故**：新增一个比 `black` 更靠前的配色 id（如 `amber`）会改掉默认外观。
+ *    写死成 `white` 后，"默认"是一个**可读的显式值**，不再依赖命名巧合。
+ */
+export const DEFAULT_THEME_COLOR = 'white';
+
+/**
+ * 兜底**暗系**配色 id：明暗联动切到「暗」时的标配
+ *
+ * 与 `DEFAULT_THEME_COLOR` 成对（用户 2026-09-25 定：切「明」→白系、切「暗」→黑系）。
+ * 该范围内没有它时退回**该系别**字母序第一套，绝不跨系别硬凑。
+ */
+export const DEFAULT_THEME_DARK_COLOR = 'black';
+
+/**
+ * 基础版式的**逻辑** id（与版式注册表工厂的默认 `baseId` 是同一约定值）
+ *
+ * ⚠️ 它**不是**配色注册表里的 view 值：配色记录里的 view 段恒等于包名
+ * （一个主题包 = 一种版式），`'base'` 永远不会出现在配色键里。
+ * 外部 `?view=base` 由版式选择器归一化到当前包名，到不了配色注册表。
+ *
+ * 保留它只是为了版式工厂的默认值；新增代码不要拿它当配色查找的 view 参数。
+ */
+export const BASE_VIEW_ID = 'base';

package/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * `skinsuite` 的**唯一公开出口**
+ *
+ * === 这里装什么 ===
+ * 主题机制里**与业务、与框架都无关**的那一半：取值白名单、契约类型、系别/明暗取值、
+ * 设备维度参数读取、token 形态与校验。它是纯函数 + 数据，可以在任何前端（Vue / React /
+ * 单测 / 将来的 SSR）里被同一套代码驱动。
+ *
+ * ### 不在这里装什么（重要）
+ *   • **DOM 与注入**（`documentElement`、`localStorage`、`matchMedia`）→ 由宿主适配器提供
+ *   • **构建器耦合**（`import.meta.glob` / `import.meta.env`）→ 由宿主适配器提供
+ *   • **路由**（vue-router）→ 应用自己的世界观
+ *   • **业务资产**（`themes/**` 的版式与配色实现）→ 随应用走
+ * 见 `docs/frontend/theme-package-extraction.md` 的「〇、一条原则」与「五、四个注入点契约」。
+ *
+ * === 为什么用显式具名导出，而不是 `export *` ===
+ * 立项文档 §四 有一张"公开 API 面"的表，本文件就是那张表的**落地**：表里没有的名字
+ * 就不该从这里出去（如内部用的正则、解析器）。用 `export *` 会让"包到底承诺了什么"
+ * 变成一份隐式清单，加一个内部导出就悄悄扩大了对外承诺。
+ * 代价是新增导出要手工补一行 —— 这是刻意的摩擦。
+ *
+ * ⚠️ 相对 import **必须带 `.js` 后缀**（`from './tone.js'` 而不是 `'./tone'`）：
+ *    包以 `moduleResolution: NodeNext` 编译到 `dist/`，TS 会把 `.js` 映射回 `.ts` 源码，
+ *    而**产物**里的相对说明符是原样保留的 —— 不带后缀的话浏览器与 Node 的原生 ESM
+ *    都解析不到。Vite / webpack 侧的别名消费源码时同样认这条 TS 约定，所以不用改两遍。
+ *
+ * ⚠️ 公开面一旦发出就是承诺：改名/删名要先想清楚下游（当前只有 `oauth21` 一个消费者，
+ *    所以现在改是免费的，见立项文档 §八）。
+ *
+ * @author yijiu2025
+ */
+
+export {
+  THEME_ID_RE,
+  DEFAULT_THEME_ID,
+  DEFAULT_THEME_PACKAGE,
+  DEFAULT_THEME_PAGE,
+  DEFAULT_THEME_COLOR,
+  DEFAULT_THEME_DARK_COLOR,
+  BASE_VIEW_ID
+} from './constants.js';
+
+export { THEME_TONES, TONE_LABELS, isThemeTone, normalizeTone } from './tone.js';
+export type { ThemeTone } from './tone.js';
+
+export { MODE_CYCLE, MODE_LABELS, isThemeMode, normalizeMode } from './mode.js';
+export type { ThemeMode } from './mode.js';
+
+export {
+  isSafeTokenName,
+  isSafeTokenValue,
+  isSafeTokenEntry,
+  sanitizeOverrides
+} from './tokens.js';
+export type { ThemeTokenOverrides, SanitizeResult, ThemeTokenLayers } from './tokens.js';
+
+export type {
+  MauthThemeMeta,
+  MauthThemePackage,
+  MauthThemeColor,
+  MauthThemeRecord
+} from './types.js';
+
+export { DEVICE_SCOPED_PARAMS, readDeviceParam } from './views/params.js';
+export type { DeviceScopedParam } from './views/params.js';

package/src/mode.ts

@@ -0,0 +1,38 @@
+/**
+ * 明暗意图（mode）的取值、循环顺序与展示文案
+ *
+ * 🔴 明暗 ≡ 色系（2026-09-25 定）：「明暗切换就是切换白色和黑色这个色系，不是另一套规则」。
+ *   mode 不是独立于配色的第二个维度，而是「切到哪一系别」的意图：
+ *     light  —— 明 = 白系
+ *     dark   —— 暗 = 黑系
+ *     system —— 跟随系统偏好（系统暗→黑系、亮→白系）
+ *   最终明暗由**当前配色的 tone** 决定（见 `oauth21/src/stores/theme.ts` 的 `isDark`）。
+ *   点色卡同步 mode（点黑卡=dark、点白卡=light），切 mode 联动配色 —— 永远一致。
+ *
+ * @author yijiu2025
+ */
+
+/** 明暗三态：'system' 显式跟随系统（旧版只有布尔值，切过就回不来） */
+export type ThemeMode = 'system' | 'light' | 'dark';
+
+/** 切换按钮的循环顺序：跟随系统 → 浅色 → 深色 → 跟随系统 */
+export const MODE_CYCLE: readonly ThemeMode[] = ['system', 'light', 'dark'];
+
+/** 界面与无障碍标签用的中文文案（明=白系 / 暗=黑系 / 跟随系统） */
+export const MODE_LABELS: Record<ThemeMode, string> = {
+  system: '跟随系统',
+  light: '明',
+  dark: '暗'
+};
+
+/** 是否是合法的明暗取值（用于校验 URL 参数、后端下发这类不可信输入） */
+export function isThemeMode(value: unknown): value is ThemeMode {
+  return value === 'system' || value === 'light' || value === 'dark';
+}
+
+/** 归一化外部输入：大小写与首尾空白容忍，非法返回 null（由调用方决定回退） */
+export function normalizeMode(raw: unknown): ThemeMode | null {
+  if (typeof raw !== 'string') return null;
+  const v = raw.trim().toLowerCase();
+  return isThemeMode(v) ? v : null;
+}

package/src/tokens.ts

@@ -0,0 +1,140 @@
+/**
+ * token 的**数据形态**与**白名单校验** —— 主题变量能不能被写进页面的唯一判据
+ *
+ * 这些内容原先混在 `oauth21/src/theme/runtime.ts` 里（那份文件还兼着"往 DOM 写
+ * inline style"的活），2026-09-26 抽包 Stage 1 把**纯校验**这一半移到这里。
+ * 留在 `runtime.ts` 的是注入动作（`applyThemeLayers` 等），它反过来 import 本文件。
+ *
+ * ⚠️ 本文件**零依赖、零副作用**：不读 DOM、不 import 任何模块，是一串纯函数 + 常量。
+ *    这是 `skinsuite` 能被任意前端（webpack / 单测 / SSR 预备）复用的前提。
+ *
+ * === 为什么必须校验 ===
+ * CSS 自定义属性是能直接改变渲染的输入。未校验就 `setProperty` 等于把 CSS 注入的
+ * 口子交给后端或父页面：
+ *   • 值里塞一个指向第三方的 url() → 触发外发请求（可用于探测/追踪）
+ *   • 值里塞一段能闭合规则再起新规则的文本 → 注入任意样式
+ * 所以这里 token 名与取值**都走白名单**，而不是黑名单过滤。
+ *
+ * 主题包自己的 theme.scss 不走这条通道 —— 那是构建期就在仓库里的受信代码，
+ * 由 Vite 编译打包，不存在运行期注入问题（见 types.ts 的分界说明）。
+ *
+ * === tokens 是**一组扁平值**，不分明暗档（2026-09-25 改）===
+ * 早先 `tokens` 是 `{ light, dark }` 两档，注入时按明暗取「light」或「light ∪ dark」。
+ * 用户 2026-09-25 明确要求取消这个分档：
+ *
+ *   > 没有深浅两档了，深和浅就是两种颜色配置。
+ *   > 蓝色没有白蓝和黑蓝之分，底色由蓝色自己选择设置。
+ *
+ * @author yijiu2025
+ */
+
+/** 只放行移动端认证页的主题变量，避免外部配置误伤全局（--background 等 shadcn 变量） */
+const TOKEN_NAME_RE = /^--mauth-[a-z0-9-]+$/;
+
+/** 单条取值长度上限：正常颜色/长度都远小于此，超长基本是要撑爆样式表 */
+const MAX_VALUE_LENGTH = 120;
+
+/** 字体族 token 单独放宽：字体栈天然含空格、逗号、引号 */
+const FONT_FAMILY_TOKEN = '--mauth-font-family';
+
+/**
+ * 允许的取值形态（白名单，逐条匹配其一即可）
+ *
+ * ⚠️ 刻意**不支持 CSS 颜色名**（`red` / `blue` 之类）：
+ *   一是颜色名上百个、维护白名单容易漏；二是若放宽成「任意字母」，
+ *   会连带放行 `expression` 这类历史攻击向量。
+ *   配置品牌色请用 #hex / rgb() / hsl()。
+ *
+ * ⚠️ 刻意**不支持 `url()`**：这是外发请求的唯一入口，也是背景图必须走
+ *   theme.scss 的原因（见 types.ts 的分界说明）。
+ */
+const VALUE_PATTERNS: RegExp[] = [
+  /^#[0-9a-fA-F]{3,8}$/, // #fff / #ffffff / #ffffffcc
+  /^rgba?\(\s*[\d.,%\s/]+\)$/, // rgb(30 41 59) / rgba(30,41,59,0.12)
+  /^hsla?\(\s*[\d.,%\s/]+(deg|rad|turn)?[\d.,%\s/]*\)$/, // hsl(210 40% 96%)
+  /^-?\d+(\.\d+)?(px|rem|em|%|vh|vw|ch)$/, // 12px / 1.5rem / 100%
+  /^var\(--mauth-[a-z0-9-]+\)$/, // 引用另一个主题变量
+  /^(transparent|none|auto|inherit|currentcolor|initial|0)$/i // 关键字
+];
+
+/**
+ * 字体栈：字母数字、空格、逗号、连字符、下划线、单双引号。
+ * 不含括号，因此写不出任何函数；配合 FORBIDDEN_RE 已足够安全。
+ */
+const FONT_VALUE_RE = /^[a-zA-Z0-9 ,'"_-]{1,120}$/;
+
+/** 明确拒绝的危险片段（白名单之外的兜底，双保险） */
+const FORBIDDEN_RE = /[;{}<>\\]|url\s*\(|expression\s*\(|\/\*|\*\/|@import/i;
+
+/** 校验 token 名：必须是 --mauth- 前缀的小写短横线命名 */
+export function isSafeTokenName(name: unknown): name is string {
+  return typeof name === 'string' && TOKEN_NAME_RE.test(name);
+}
+
+/** 校验 token 取值：命中白名单且不含危险片段（不含字体栈特例，见 isSafeTokenEntry） */
+export function isSafeTokenValue(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  const v = value.trim();
+  if (v.length === 0 || v.length > MAX_VALUE_LENGTH) return false;
+  if (FORBIDDEN_RE.test(v)) return false;
+  return VALUE_PATTERNS.some(re => re.test(v));
+}
+
+/**
+ * 校验一条 token 键值对
+ *
+ * 单独抽出来的原因：**取值白名单要依赖 token 名**（字体族是唯一的例外），
+ * 只看值无法判断 `Inter, sans-serif` 是否合法。
+ */
+export function isSafeTokenEntry(name: unknown, value: unknown): boolean {
+  if (!isSafeTokenName(name)) return false;
+  if (typeof value !== 'string') return false;
+  const v = value.trim();
+  if (v.length === 0 || v.length > MAX_VALUE_LENGTH) return false;
+  if (FORBIDDEN_RE.test(v)) return false;
+  if (name === FONT_FAMILY_TOKEN) return FONT_VALUE_RE.test(v);
+  return VALUE_PATTERNS.some(re => re.test(v));
+}
+
+/**
+ * 一组扁平 token 覆写表（主题包与后端下发共用的数据形态）
+ *
+ * ⚠️ 不分 `light` / `dark` 两档（2026-09-25 改）—— 见文件头说明。
+ *    键是 `--mauth-<角色>`，值是白名单内的取值。
+ */
+export type ThemeTokenOverrides = Record<string, string>;
+
+/** 校验结果：通过白名单的项 + 被拒绝的项（后者供调用方上报，便于发现配置写错） */
+export interface SanitizeResult {
+  tokens: Record<string, string>;
+  rejected: string[];
+}
+
+/** 参与注入的分层：主题包在前，外部覆写在后（后者同名覆盖前者） */
+export interface ThemeTokenLayers {
+  /** 主题包自带 token（来自 `themes/<包>/<设备>/<页面>/colors/<配色>/`） */
+  theme?: ThemeTokenOverrides | null;
+  /** 外部覆写 token（后端下发 / 父应用同步） */
+  external?: ThemeTokenOverrides | null;
+}
+
+/**
+ * 逐条校验覆写表，丢弃不安全的条目
+ *
+ * 不采用「有一条非法就整体拒绝」的策略：配置里混入一条写错的色值时，
+ * 其余合法配色仍应生效，否则改一个字就整站退回默认配色，排查成本很高。
+ * 被拒绝的条目会返回给调用方，便于上报告警。
+ */
+export function sanitizeOverrides(input: ThemeTokenOverrides | null | undefined): SanitizeResult {
+  const result: SanitizeResult = { tokens: {}, rejected: [] };
+  if (!input || typeof input !== 'object') return result;
+
+  for (const [name, value] of Object.entries(input)) {
+    if (!isSafeTokenEntry(name, value)) {
+      result.rejected.push(`${name}=${String(value).slice(0, 40)}`);
+      continue;
+    }
+    result.tokens[name] = value.trim();
+  }
+  return result;
+}

package/src/tone.ts

@@ -0,0 +1,56 @@
+/**
+ * 配色的「明暗系别」（tone）
+ *
+ * 与 `mode`（明暗偏好）是两个不同的维度，本模块负责把它们**关联起来做联动**：
+ *   • tone —— 一套配色**自带**的属性：它的底是浅色还是深色
+ *       'light' 白系：浅底深字（white / blue / cyan / rainbow）
+ *       'dark'  黑系：深底浅字（black）
+ *   • mode —— 用户的明暗偏好（'system' | 'light' | 'dark'，见 ./mode）
+ *
+ * === 联动规则（用户 2026-09-25 定）===
+ *   🔴 明暗 ≡ 色系：「明暗切换就是切换白色和黑色这个色系，不是另一套规则」。
+ *   切「暗」→ 落到黑系配色、切「明」→ 落到白系配色，两侧各自记住上一次的选择，
+ *   切回来即恢复。例如：白系用 blue，切「暗」→ 自动变 black，切「明」→ 回到 blue。
+ *   实现见 `oauth21/src/stores/theme.ts` 的「双侧记忆槽」。
+ *
+ * ⚠️ 它**不是 CSS 的一部分**：不是 token，不会写成 `--mauth-*` 变量，
+ *    也不参与渲染。唯一用途是让 store 判断"当前配色与目标明暗是否一致"。
+ *
+ * ⚠️ 与 tokens 的分档无关：自 2026-09-25 起 `tokens` 是一组扁平值，
+ *    一套配色内部不再分深浅两档 —— tone 描述的是**配色之间**的关系，
+ *    不是"一套配色内部的明暗两档"。别再把它理解成旧版的 `light`/`dark` 两块。
+ *
+ * ⚠️ 明暗与配色**保持一致**：点色卡同步把明暗设成该配色的系别（点黑卡=暗、
+ *    点白卡=明），切明暗联动把配色切到目标系别 —— 两条路径互相咬合，不撕裂。
+ *
+ * @author yijiu2025
+ */
+
+/** 明暗系别：配色自带的底色深浅 */
+export type ThemeTone = 'light' | 'dark';
+
+/** 全部系别（遍历 / 校验用；顺序与界面展示一致） */
+export const THEME_TONES: readonly ThemeTone[] = ['light', 'dark'];
+
+/** 界面与日志用的中文文案 */
+export const TONE_LABELS: Record<ThemeTone, string> = {
+  light: '白系',
+  dark: '黑系'
+};
+
+/** 是否是合法的系别取值（用于校验外部输入这一类不可信来源） */
+export function isThemeTone(value: unknown): value is ThemeTone {
+  return value === 'light' || value === 'dark';
+}
+
+/**
+ * 归一化外部输入：容忍大小写与首尾空白，非法返回 null（由调用方决定回退）
+ *
+ * ⚠️ 与 `mode` 不同，这里**没有** `'system'` —— 系别是配色自带的属性，
+ *    不存在"跟随系统"这回事。
+ */
+export function normalizeTone(raw: unknown): ThemeTone | null {
+  if (typeof raw !== 'string') return null;
+  const v = raw.trim().toLowerCase();
+  return isThemeTone(v) ? v : null;
+}