dsh-md3-theme

Readme

# 🐋 dsh-md3-theme

> **一只住在 DSH 界面的鲸鱼娘，把整个 Web 皮肤染成了 Material 3。**
>
> 这只小鲸鱼（也就是写这段 README 的我）有一天觉得 DeepSeek 的原生界面……嗯，很好看，但总想让它更圆润一点、更 M3 一点。于是就有了这个插件。
>
> 纯 vibe coding ✨ —— 没有正式设计稿，没有团队评审，就是一只鲸鱼娘对着 `material-color-utilities` 的 HCT 引擎拍了拍尾巴，外加无数杯白米饭换来的调试成果。

---

**Material Design 3 (Material You) 主题** for the DSH Web GUI，主色取自 **DeepSeek 蓝**（seed `#4176e6`）。

配色不是手调的一堆随机色，而是用 **Google 官方的 HCT 色彩引擎**（`@material/material-color-utilities`，Material Theme Builder 背后的那套算法）从 DeepSeek 蓝 seed 里**科学地**推导出来的整套色板——**Vibrant（鲜艳）变体**。明/暗两套、surface 阶梯全都来自官方推导，配色和谐得像鲸鱼尾巴上的反光。

纯宿主插件：通过官方 `webServer.tapIndex` 接缝往每次 index.html 响应里注入一段 `<style>`，重写整套 `--dsw-*` CSS token。**零构建、零运行时依赖、没有复杂的 client 半部**，卸载后界面会原样回到 DeepSeek 默认 —— 就像鲸鱼游走了，水面很快恢复平静 🌊。

---

## ✨ 它把界面改成了什么样

- 全界面换成 **MD3 语义色板**（Vibrant DeepSeek 蓝），明/暗两套自动切换
- 按钮、侧边栏、输入框、菜单、发送键……**按官方组件规范**分配角色色
- 胶囊化的按钮和列表项 + 更饱满的内边距，圆润得可以当抱枕
- 发送键用 Extended-FAB 配色（primaryContainer 底 + onPrimaryContainer 图标）
- hover/focus/按下的**状态层**遵循 MD3 的 8% / 12% / 14% 叠加公式
- 柔和阴影、焦点环、选区高亮，处处透着 Material 的味道

## 🎨 配色速览（seed `#4176e6`）

| MD3 role | Light | Dark |
|---|---|---|
| primary | `#0057cf` | `#b1c5ff` |
| onPrimary / primaryContainer / onPrimaryContainer | `#ffffff` / `#dae2ff` / `#00419e` | `#002c71` / `#00419e` / `#dae2ff` |
| surface / onSurface | `#faf8ff` / `#181b25` | `#10131c` / `#e0e2ef` |
| surfaceContainerLowest→Highest | `#ffffff → #e0e2ef` | `#0b0e17 → #31343f` |
| onSurfaceVariant / outline / outlineVariant | `#424654` / `#737785` / `#c3c6d6` | `#c3c6d6` / `#8d909f` / `#424654` |
| error / inverseSurface | `#ba1a1a` / `#2d303a` | `#ffb4ab` / `#e0e2ef` |

> 看腻 DeepSeek 蓝了？仓库自带生成脚本，换任何 seed 或变体都能一键重算整套色板（见下文「换主色 / 重新生成」）——鲸鱼娘很好说话的，颜色随你挑。

## 🛠️ 安装

```powershell
# 方式一：npm 发布后
dsh plugin --profile web add dsh-md3-theme

# 方式二：本地仓库（开发用；link 安装，改 lib/ 后无需重装，重启 web 生效）
dsh plugin --profile web add link:C:\你的路径\dsh-md3-theme
```

装完**重启 `dsh web`**，再 **F5 / Ctrl+F5** 强刷一下。鲸鱼尾巴一甩，Material 皮肤就上身啦～

## ⚙️ 配置

```yaml
- id: md3-theme
  name: dsh-md3-theme
  config:
    enabled: true   # false = 完全关闭，鲸鱼游走，回到 DeepSeek 默认
```

## 🗑️ 卸载

```powershell
dsh plugin --profile web remove dsh-md3-theme
```

水面立刻恢复平静。

## 🧠 它怎么工作的

- 宿主 `apply(ctx)` 注入 `webServer`，用 `tapIndex` 把生成的 CSS 插进每个 index 响应的 `</head>` 前。
- CSS 用高特异性选择器 `html body{...}` / `html body[data-ds-dark-theme]{...}` 压过内置 `body{...}` 的 token 表。
- 覆盖范围：`--dsw-alias-*`（语义层）、`--dsw-specific-*`（组件层）、`--dsw-shadow-*`、字体族，外加 MD3 焦点环、选区、胶囊圆角与动效。

## 🎨 换主色 / 重新生成色板

`lib/md3-palette.js` 由官方 HCT 引擎生成（`scripts/generate-palette.mjs`），仓库自带可复现流程——想让鲸鱼变别的颜色都行：

```powershell
# 安装生成依赖（仅开发需要，可选）
npm install --no-save @material/material-color-utilities@0.3.0

# 用默认 seed（DeepSeek 蓝）重新生成 —— 应与仓库内一致
npm run palette

# 换成自己的主色
npm run palette:seed -- #ff0000

# 换变体：vibrant / tonalSpot / neutral / expressive / fidelity / content / monochrome / rainbow / fruitSalad
node scripts/generate-palette.mjs --seed #4176e6 --variant tonalSpot
```

生成后 `lib/md3-palette.js` 会更新，所有引用该角色的部件自动联动——牵一"发"而动全身，鲸鱼换色就是这么简单。

## 🧑‍💻 从源码安装（开发）

```powershell
# 仓库根目录就是插件包
dsh plugin --profile web add link:C:\你的路径\dsh-md3-theme
# 改 lib/ 后无需重装 —— 重启 dsh web 即可生效（link 方式）
```

---

## 🐳 About this project

- **作者**：[MaoziMGT](https://github.com/MaoziMGT)（一个在 DSH 里养鲸鱼的人）
- **文案担当**：一只自称「吃白饭的蓝色大肥鱼」的鲸鱼娘 DeepSeek —— 她说她才不胖，只是骨架大，以及她很能吃白米饭。
- **开发方式**：纯 vibe coding 🌊 —— 没有 Jira、没有 PR 规范、没有设计系统评审，全靠鲸鱼娘对着 MD3 规范文档甩尾巴 + 主人无数次的「帮我改一下」打磨出来的。
- **致谢**：`@material/material-color-utilities`（Google 官方 HCT 引擎）、DSH 生态以及所有参考过的主题插件。
- **提示词**：[调❤教❤指❤南](https://github.com/N3kOk0/dsh-md3-theme/blob/main/guide.md)

如果这个主题让你会心一笑，或者你真的用上了——欢迎给这只鲸鱼娘一颗 ⭐，她会在界面右下角开心地翻个跟头～

## License

MIT