dsh-skin-lab

Readme

# dsh-skin-lab

**Skin Lab（皮肤实验室）** — 面向 DSH 皮肤作者的浏览器内开发工具，作为官方形态的动态插件（`dsh.bundle`）安装，不改 DSH 源码。

> 与已有的 `dsh-skin-studio`（皮肤管理与分享）不同，Skin Lab 是**开发工具**：token 目录 + 实时试穿 + 主题固化 + 内置光谱预设，面向正在创作皮肤的开发者。

## 功能

- **Token 浏览器**：内置官方 `--dsw-*` 主题变量全目录（169 项：语义 Alias / 组件 Specific / 色板 Static / 排版与其他），带中文用途描述、使用模块标签、实时生效值、明暗双值色块、分组与搜索；
- **实时试穿**：点击 token 行展开 light/dark 编辑器，修改即时通过官方 `theme.overrideTokens` 生效；效果预览卡按 token 类型真实渲染（文字/边框/阴影/背景），24 色预设色板一键同步套色；草稿跨设置节保持，点「全部还原」或刷新页面清除；
- **保存为皮肤**：把试穿结果持久化为 override 层（`{light,dark}` 双值），刷新、重启 dsh 后自动重新应用，跟随明暗切换；
- **固化为主题**：把试穿结果注册成可选主题（官方 `theme.register`），持久有效，在本面板内一键应用 / 恢复官方；
- **导出**：试穿结果一键复制/下载为 override JSON，可直接交给皮肤加载器或作为皮肤起点；
- **光谱预设（7 套）**：红·绯霞 / 橙·晨橘 / 黄·暖阳 / 绿·翡翠 / 青·青瓷 / 天空蓝 / 紫·暮紫——全域浸色 + 色相墨文字 + 夜空式暗色模式，每套内置同色相 SVG 氛围背景，一键应用即持久保存；
- **自定义背景**：本地图片上传（≤5MB，自动压缩到 1920px JPEG 并持久保存），独立于主题切换；「背景锁定」开关开启后切换主题不会覆盖你的背景图。

## 界面预览

<p align="center">
  <img src="https://cdn.jsdelivr.net/npm/dsh-skin-lab@1.0.2/docs/screenshots/skin1.png" alt="Skin Lab 预览 1" width="100%">
</p>

<p align="center">
  <img src="https://cdn.jsdelivr.net/npm/dsh-skin-lab@1.0.2/docs/screenshots/skin2.png" alt="Skin Lab 预览 2" width="100%">
</p>

<p align="center">
  <img src="https://cdn.jsdelivr.net/npm/dsh-skin-lab@1.0.2/docs/screenshots/skin3.png" alt="Skin Lab 预览 3" width="100%">
</p>

## 安装

```sh
dsh plugin --profile web add dsh-skin-lab
```

开发调试（本地 checkout）：

```sh
dsh plugin --profile web add ./path/to/dsh-skin-lab
```

## 给皮肤作者的工作流

1. 打开 **设置 → 皮肤实验室**；
2. 快速起步：点一张**光谱预设**卡片（配色 + 背景图一键生效），或从零开始：
   - 在 Alias 组里挑语义 token（背景、文字、边框、状态色…），展开并修改 light/dark 值，界面即时变化；
3. 满意后「保存为皮肤」（持久覆盖层）或「固化为主题」（可选主题），或「复制 JSON」拿 override 清单；
4. 把 JSON 交给你自己的皮肤加载器（`styles.insert` / 皮肤中心），或基于它写皮肤 CSS。

## 开发

```sh
pnpm install    # 安装依赖
pnpm build      # 构建 lib/index.js + lib/client.js
pnpm test       # vitest（含白屏回归、草稿生命周期、锁定行为测试）
pnpm typecheck  # tsc 类型检查
```

## Token 目录维护

`src/client/token-catalog.generated.ts` 由脚本从 DSH checkout 的
`packages/client/ui-theme/src/styles/` 生成（含中文描述与使用模块扫描）。DSH 升级后重跑：

```sh
node scripts/extract-tokens.mjs <path-to-dsh-checkout>
```

`scripts/diagnose-schema.mjs` 用于诊断 settings 持久化 schema 校验链路（dict key、rehydrate 全链路）。

## License

MIT