dsh-theme-gallery 0.3.0 → 0.4.0

package/README.md

@@ -11,8 +11,10 @@
 | 自己做皮肤（或让 AI 做） | 在 `lib/themes/` 加 JSON 后重跑 `npm run embed-themes`，或装 `dsh-theme-skin-author` 技能让 AI 生成 |
 | 贡献一个皮肤给所有人 | 在 `lib/themes/` 放一个 JSON，提 PR |
 
-已随 **0.3.0** 发布 **6 套**皮肤：四套复刻自电商新零售系统管理后台（`admin-modular/src/utils/themes.js`），
-两套是本插件**原创**的宠物主题（同一套造色方法，色相取自中国传统色库）。
+已随 **0.4.0** 发布 **7 套**皮肤：四套复刻自**蜂链商城**电商新零售系统管理后台
+（[`renjie2026/fenglianshop-open`](https://github.com/renjie2026/fenglianshop-open) 的
+`admin-modular/src/utils/themes.js`），两套是本插件**原创**的宠物主题（同一套造色方法，色相取自中国传统色库），
+另有一套是**「纯色/拼色」配色选择器**卡片（15 个可点色值，见下）。
 
 | id | 名称 | 主色 | 强调色 |
 |---|---|---|---|
@@ -22,15 +24,17 @@
 | `pei-an-jie-xin` | **佩安杰心** | `#7A5C3E` 暖檀褐 | `#B4653A` 赭陶 |
 | `hu-po-mao-mi` | **琥珀猫咪**（原创） | `#9C5F24` 琥珀深焙（按钮/边框族） | `#CA6924` 琥珀（中国传统色） |
 | `hu-zi-a-huang` | **虎子阿黄**（原创） | `#896C39` 秋色（按钮/边框族） | `#F0C239` 缃色（中国传统色） |
+| `shi-liu-jin` | **纯色/拼色**（配色选择器） | `#F20C00` 石榴红（默认那套「石榴金」） | `#9D2933` 胭脂（按钮族） |
 
 面板里另有**两张内置外观卡**（`浅色` / `深色`）：它们**不是皮肤**，作用是把配色切回官方的浅色 / 深色
-（与「设置 → 通用 → 外观」同一套），所以**不计入上面这 6 套**。我们在官方浅色/深色上加了一点**小惊喜**
+（与「设置 → 通用 → 外观」同一套），所以**不计入上面这 7 套**。我们在官方浅色/深色上加了一点**小惊喜**
 —— 见 [效果预览](#效果预览) 最后一行。官方外观里的「跟随系统」**不出卡**：它就是浅色/深色二选一，
 再占一张卡只是重复。
 
 工作区里另有三套复刻皮肤仍在打磨，**尚未发布**：江畔冬云 `jiang-pan-dong-yun`、
-徐山军月 `xu-shan-jun-yue`、光彩凤晨 `guang-cai-feng-chen`。（发布前自检会核对这份清单：
-README 里的每个 id 都要真实存在，`lib/themes` 里的每套皮肤也必须在这里被提到。）
+徐山军月 `xu-shan-jun-yue`、光彩凤晨 `guang-cai-feng-chen`。
+（发布前自检会核对这份清单：README 里的每个 id 都要真实存在，
+`lib/themes` 里的每套皮肤也必须在这里被提到。）
 
 每个皮肤 67 个 token，覆盖整屏。
 
@@ -54,6 +58,12 @@ README 里的每个 id 都要真实存在，`lib/themes` 里的每套皮肤也
 |---|---|
 | ![内置浅色外观：调色回到官方浅色，而侧栏仍留着山青婷彩的山峦、水塘与蜻蜓](https://raw.githubusercontent.com/renjie2026/dsh-theme-gallery/main/screenshots/builtin-light-with-shan-qing-ting-cai.png) | ![内置深色外观：调色回到官方深色，而侧栏仍留着营慕彩云的彩云与热气球](https://raw.githubusercontent.com/renjie2026/dsh-theme-gallery/main/screenshots/builtin-dark-with-ying-mu-cai-yun.png) |
 
+**「纯色/拼色」卡片 —— 同一张卡、两套配色**（点色格即时换色；卡片名旁边的「已应用」标出当前那套）
+
+| 石榴金配色（默认） | 换点「松柏绿」那一格之后 |
+|---|---|
+| ![纯色/拼色卡片 + 石榴金配色：侧栏与主区都是石榴红/赤金/翡翠那套暖调](https://raw.githubusercontent.com/renjie2026/dsh-theme-gallery/main/screenshots/shi-liu-jin.png) | ![同一张卡片换成松柏绿配色：整屏转为松柏叶的墨绿调](https://raw.githubusercontent.com/renjie2026/dsh-theme-gallery/main/screenshots/shi-liu-jin-song-bai-lu.png) |
+
 玩法：**先点一套皮肤，再点「浅色」或「深色」** —— 调色回到官方外观，而侧栏素材**留在原处**
 （切到**另一套皮肤**时素材会正常替换；重启应用后不会有残留，因为那时的页面上本来就没有"上一套"可留）。
 
@@ -426,6 +436,105 @@ if (active === void 0) throw new Error(`theme registry lost "${resolvedId}"`)
 | **空对话态** | 会话里还没有消息 | 整屏铺满主题：左侧栏渐变 + Windows 顶部标题栏渐变 + 中间留白也是主题色 |
 | **有对话态** | 出现消息后 | 正文套一层**提亮卡片**（默认 62% 不透明度 / 3px 模糊 / 640px 限宽），四周仍透出主题渐变；左侧栏与顶部**保持主题强度**，一眼可辨是哪个皮肤 |
 
+### 配色选择器 `card`（纯色/拼色 一类）
+
+到 0.3.0 为止，每张卡片都是**一条 6px 色带**，取色由代码从皮肤的 3 个 token 里挑
+（`brand-primary` / `label-secondary` / `state-business-primary`），所以任何皮肤都不用额外写卡片信息。
+一条色带只能表达"一套配色长什么样"，而这一类卡片要表达的是**"这里有多少套配色，点哪个换哪个"**。
+
+所以新增了可选字段 `card.rows`（不写它就还是那条色带，九套场景皮肤一个字都没改）：
+卡片上排 **15 个可点的色值按钮**，**5 + 5 + 5**：上两排是 **10 个纯色**方案，最后一排是 **5 个拼色**方案。
+
+```jsonc
+"card": {
+  "rows": [
+    { "kind": "solid", "schemes": ["p-xiang-se", "p-ju-huang", "p-tao-hong", "p-hai-tang-hong", "p-jiang-zi"] },
+    { "kind": "solid", "schemes": ["p-song-bai-lu", "p-zhu-qing", "p-cang-qing", "p-dai-zi", "p-xuan-qing"] },
+    { "kind": "clash", "schemes": ["p-shi-liu-jin", "p-bao-lan-jin", "p-qing-lian-jin", "p-song-hua-tao", "p-wu-jin"] }
+  ]
+}
+```
+
+**15 套配色不是 15 个主题。** 它们住在 [`lib/palette-schemes.json`](lib/palette-schemes.json)，由建期
+内联进包里，但**不注册进主题服务**：所以官方「设置 → 通用 → 外观」的主题列表里不会多出 15 项，
+面板头部的"N 款皮肤"也仍然是皮肤数。点一个按钮 = 把该方案的 token 层叠到整屏上，
+所选方案记在 `localStorage`（`theme-gallery:palette`），**绝不**写进 `ui-theme.preference`。
+
+| 规则 | 为什么 |
+|---|---|
+| 2 或 3 排，**最后一排必须是拼色** | 拼色排在最下方才读得出层级；放别处只会像画错了 |
+| 一排 1–5 个按钮，等宽 | 5 个是卡片最小宽度（200px）下仍能读出 5 种颜色的上限，第 6 个只剩约 28px，会读成条纹 |
+| 每个按钮**按宽度分带**：纯色格一条带占满；拼色格主色占 **2 份**、每个次色各占 **1 份** | 一眼看出"这一套谁占大头、旁边配了哪些色"。比值由数据算出来（一主一次 = 2/1、一主两次 = 2/1/1、一主四次 = 2/1/1/1/1），不是写死的；画法和点下去的效果取自**同一张表**，不可能对不上 |
+| 每个次色相对主色的对比度 **≥ 2.5:1** | 次色带在最窄的卡片上只有几像素宽，明度接近时整条糊进主色里，**没有异常也没有日志**。实测反面样本：`碧色 #1BD1A5` 上的红点 1.14:1、`海棠红 #DB5A6B` 上的竹青 1.07:1 |
+| 深色正文压在方案底色上 **≥ 7:1** | 15 套方案只写三四个色，其余 60 多个 token 由 `schemeTokens()` 派生；底色与正文的对比度是整屏的阅读下限 |
+| 按钮填充色按对比度选（本色 + 深色字 / 本色 + 白字 / 压深后用白字） | 缃色、橘黄、桃红这类**亮色**做填充时白字只有 1.7–3.7:1，读不清。规则逐个候选试，尽量让按钮留在色库那个**名字色**上；石榴金显式指定用「胭脂」`#9D2933`（白字 7.50:1） |
+| 15 套全部出自**中国传统色库** | `zerosoul/chinese-colors` 的 `src/assets/colors.json`，每套都写明「组 + id」出处（见 `source` 字段） |
+
+**15 套色值一览**（`主色` = 纯色格那一整条带 / 拼色格的第 1 条带；`次色` = 拼色格其余各条带。
+表由 `lib/palette-schemes.json` 直接生成，不手抄）：
+
+| 位置 | 方案 | 主色 | 次色 | 色库出处 |
+|---|---|---|---|---|
+| 纯色 1 | 缃色 | `#F0C239` | — | 黄 1-9 缃色（浅黄色） |
+| 纯色 2 | 橘黄 | `#FF8936` | — | 黄 1-5 橘黄（柑橘的黄色） |
+| 纯色 3 | 桃红 | `#F47983` | — | 红 0-3 桃红（桃花的颜色） |
+| 纯色 4 | 海棠红 | `#DB5A6B` | — | 红 0-4 海棠红（淡紫红色、较桃红色深一些） |
+| 纯色 5 | 绛紫 | `#8C4356` | — | 红 0-9 绛紫（紫中略带红的颜色） |
+| 纯色 6 | 松柏绿 | `#057748` | — | 绿 2-30 松花绿（松柏叶的墨绿） |
+| 纯色 7 | 竹青 | `#789262` | — | 绿 2-3 竹青（竹子的绿色） |
+| 纯色 8 | 苍青 | `#7397AB` | — | 苍 4-3 苍青 |
+| 纯色 9 | 黛紫 | `#574266` | — | 蓝 3-12 黛紫（深紫色） |
+| 纯色 10 | 玄青 | `#3D3B4F` | — | 黑 7-1 玄青（深黑色） |
+| 拼色 1 | 石榴金 | `#F20C00` | `#FFFFFF` `#D6ECF0` `#EACD76` `#3DE1AD` | 红 0-5 石榴红 + 金银 8-0 赤金 + 绿 2-14 翡翠色；按钮族用红 0-11 胭脂（白字 7.50:1，而压在石榴红上只有 4.35:1） |
+| 拼色 2 | 宝蓝·赤金 | `#4B5CC4` | `#F2BE45` `#EACD76` `#D9B611` `#FFFFFF` | 蓝 3-5 宝蓝（多和小面积纯黄色（金色）配合使用）+ 金银 8-0 赤金 |
+| 拼色 3 | 青莲·金玉 | `#801DAE` | `#F2BE45` `#FFF143` `#3DE1AD` `#FFFFFF` | 蓝 3-19 青莲（偏蓝的紫色）+ 黄 1-0 鹅黄 + 绿 2-14 翡翠色 |
+| 拼色 4 | 松花·桃粉 | `#BCE672` | `#C93756` `#057748` | 绿 2-31 松花色（嫩黄绿）+ 红 0-1 樱桃色 + 绿 2-30 松花绿 |
+| 拼色 5 | 藏青·鹅黄 | `#2E4E7E` | `#F2BE45` `#FFFFFF` `#FFB3A7` `#3DE1AD` | 蓝 8-2 藏青（深蓝）+ 金银 8-0 赤金 + 精白 + 红 0-0 粉红 + 绿 2-14 翡翠色 |
+
+> **两处按用户反馈改过色**（2026-09-26）：① 原「松花·桃粉」的主色是**松花绿 `#057748`**，
+> 与纯色「松柏绿」撞脸（两张卡看着是同一个绿），于是那个墨绿**归给松柏绿**这一格，
+> 「松花·桃粉」改用**松花色 `#BCE672`** 当主色、只配两个次色（画出来正是 2/1/1）；
+> ② 原「乌金·翡翠」是拿玄色 `#622A1D` 当"乌"用，观感发闷，整条换成「**藏青·鹅黄**」。
+> 色库里的「乌金」其实是 `#A78E44` 这个金褐色 —— 名字与用途对不上也是换掉它的原因之一。
+
+### 出处与致谢
+
+- **纯色/拼色卡片上的 15 个色值，全部取自「中国传统色库」项目（chinese-colors）**：
+  <https://github.com/zerosoul/chinese-colors>
+  —— 作者 **tristan**（GitHub [@zerosoul](https://github.com/zerosoul)），
+  在线手册 <https://colors.ichuantong.cn>，许可 ISC。
+  该项目把 170 个中国传统色的名字与色值整理成 `src/assets/colors.json`，
+  **本插件只做取色与派生**（每套方案只挑三四个名字色，其余 token 由同一条造色规则算出来）；
+  取色数据在 [`lib/palette-schemes.json`](lib/palette-schemes.json)，每套都带 `source`
+  记着它在色库里的「组 + id」。色名与色值是作者整理的开源成果，
+  **在此感谢作者 tristan 的整理与开源。**
+- 七套**复刻**皮肤的场景与配色复刻自**蜂链商城**电商新零售系统管理后台的主题：
+  <https://github.com/renjie2026/fenglianshop-open>（该项目的开发者就是本插件的作者）。
+- 两套宠物主题（琥珀猫咪、虎子阿黄）与内置浅色/深色的卡片文案是本插件原创。
+
+如果你是要**转载或再分发**本插件：色值本身请按上面那条一并保留出处与致谢；
+复刻皮肤的场景素材请遵循蜂链商城仓库的许可。
+
+**这一类卡片不印 `description`**：15 个按钮已经占满卡面，文字会把卡片挤爆。`description` 仍然必须非空 ——
+它照 Schema 的定义只作 **tooltip**（`title`），也就是说这一类反而用回了字段本来的契约。
+这条"不印正文"是**渲染分支的属性**，不是另一个开关（多一个 `text:false` 只会多一个能自相矛盾的状态），
+由 `tests/check-card-order.mjs` 的源码断言与 `tests/check-boot-path.mjs` 的行为断言（含反证）共同钉住。
+
+样本卡是 **`shi-liu-jin`**（序号 97，尚在打磨）：它是这 15 套里「石榴金」那一套的**锚主题** ——
+卡片本体、`accent`（激活标记）与拼色按钮都由它承载。
+
+**点「石榴金」那一格（拼色排第 1 格）与点其它 14 格走的是两条不同的路**，这不是疏漏而是刻意的：
+它是锚主题**自己那套手工写好的 67 个 token**（`lib/themes/shi-liu-jin.json`，侧栏渐变、两层底、
+正文、按钮族都在里面）—— 也就是最初那版"两排纯色 + 一排拼色"合起来的整套配色。所以点它**不叠**
+配色层，屏幕上是皮肤自己的调色；其余 14 格才用 `main/ground/ink` + 次色派生出一整套 token 叠上去。
+（早先没有区分：点石榴金也会派生一层，得到"相似但不等"的另一套颜色 —— 实机一眼就能看出
+不是原版，已修，并由行为断言 + 反证 10 钉住。）
+
+**它不配 `ambient`** —— 侧栏仍有自己的渐变，
+只是上面不画任何素材；因此从一套**有素材**的皮肤切过来时，上一套的侧栏素材会**留在原处**
+（与内置浅色/深色卡同样的"惊喜"行为，已确认**有意保留**：装饰不会因为换皮肤就消失，
+只有切到另一套有素材的皮肤才会被替换）。
+
 ### 原理：整屏覆盖靠 token，不靠注入 CSS
 
 看起来渐变必须注入样式表，其实不用。官方布局**本来就用主题 token 画这些面**：
@@ -586,6 +695,7 @@ dsh-theme-gallery/
 │   ├── publish-check.mjs         # 发布前自检（含 README 与 lib/themes 一致性）
 │   ├── build-ambient-preview.mjs # 生成侧栏素材预览页（CSS 读自 client.js）
 │   ├── build-panel-preview.mjs   # 生成面板卡片顺序/文案预览页
+│   ├── lib/card-rows.mjs         # 卡片色块（card.rows）的校验（建期与测试共用）
 │   └── serve-bench.mjs           # 启动调参台
 ├── tests/                # 20 组校验（一个 *.mjs 文件一组；lib/ 是共用解析器）
 ├── types/                # 契约校验源（不参与运行）
@@ -615,7 +725,7 @@ pnpm run bench     # 调参台
 2. **契约与桩**：`check-schema`（真实 schemastery 解析 + **10 个反向用例**，含缺 `label`、缺 `description`、`reading.alpha` 越界）、`smoke-host`（**真机加载** `lib/index.js` 跑 `apply`，并守住 `inject` 清单与插槽门控）、`check-store-contract`（`handle.create()` 每次返回新实例）、`check-client-module`（bundle 形状、挂载失败必须可见）。
 3. **启动安全与端到端引导**：`check-boot-safety`（`inject` 清单、无 `modifies` 环）、`check-boot-timing`、`check-boot-path`（桩里跑完整引导：上色确认、默认皮肤、点内置卡不被弹回、切内置主题后素材保留 —— 每条都带**反证**）。
 4. **静态审计（含自检与变异反证）**：`check-declaration-order`、`check-tdz-order` + `check-tdz-logic`、`check-scope-reach` + `check-scope-reach-logic`、`check-undefined-calls`、`check-bounded-work`（有界工作量：指纹守卫、单一路径渲染、循环有截止）、`check-self-emit-guard` + `check-self-emit-guard-logic`（数出**全部**主题服务写入点）。
-5. **主题与皮肤**：`check-theme-contribution`（贡献逻辑与幂等，并断言**注册的 token 必须是字符串**——成对对象会变成 `[object Object]`）、`check-card-order`（卡片顺序、内置卡文案、默认皮肤，含 7 处变异反证）、`check-ambient-render`（场景标记与关键帧）。
+5. **主题与皮肤**：`check-theme-contribution`（贡献逻辑与幂等，并断言**注册的 token 必须是字符串**——成对对象会变成 `[object Object]`）、`check-card-order`（卡片顺序、内置卡文案、默认皮肤、色块排版 `card.rows`，含 **17 处变异反证**）、`check-ambient-render`（场景标记与关键帧）。
 6. **介绍文字不落后于实际**：`check-copy-consistency-logic` —— 核对 README 的皮肤清单 / 数量 / 版本 / 入口说法、面板与预览页的计数口径、README 里写的校验组数，与 `lib/themes`、`package.json`、`lib/client.js` 一致（**10 处变异反证 + 1 个"正式发布一套皮肤必须全过"的对照组**）。发布自检 `npm run publish:check` 用同一份实现，所以"改了皮肤忘了改文案"会在发布前被拦住。
 
 `scripts/embed-themes.mjs` 校验每套皮肤（形状 / id 唯一 / 双配色 / 12 必需 token / `reading`）后内联进 `lib/client.js`，幂等；两个预览页随后重建。