# 插件图标设计说明

本插件的图标是 `icon.svg`（`package.json` 的 `icon` 字段指向它）。这份文档记录
**为什么画成这样**，以免日后有人"顺手改改"又改回踩坑的版本。

渲染效果见 [`icon-rendering.png`](images/icon-rendering.png)：与 DSH 官方插件图标并排、
按宿主真实规格（卡片 48px 框内绘 36px、行内 40px 框内绘 30px）在浅色与深色主题下的样子。

---

## 一、宿主怎么渲染图标（这决定了画法）

以下结论来自阅读 DSH 应用内的实际代码，不是推测：

1. **宿主读取 `package.json` 的 `icon` 字段**，把它读成
   `data:image/svg+xml;base64,…` 交给界面。
2. **界面用图片标签渲染它**，也就是说：**SVG 是独立文档**。因此
   - `currentColor` **不生效**；
   - `var(--dsw-*)` 这类主题变量**不生效**；
   - 必须写死色值、并把渐变放进自己的 `<defs>` 里。
3. **圆角方框是宿主自己画的**，48px（插件卡片）/ 40px（插件行内），
   **背景透明**，只有 0.5px 描边；图片在其中按 36px / 30px 绘制。
4. 解析门禁：`icon` 必须是**相对路径**、位于包目录内、扩展名为
   svg/png/jpg/jpeg/webp、**不超过 256 KiB**。任一条不满足，或图标无法解析，
   宿主会**静默回退**成它自己的默认图形（不会显示破图）。

### 由此推出的三条硬性结论

| 约束 | 原因 |
|---|---|
| **不能画实心底板** | 宿主已经画了框，再画一层就是"双重相框"。旧版图标（96×96 蓝色实心圆角方块）正是这个问题。 |
| **必须 36×36 画布、透明底** | 与官方插件图标一致，才能在同一栅格里对齐。 |
| **必须有 `xmlns` 且 XML 合法** | 作为独立文档解析，任何语法错误都会导致静默回退。 |

---

## 二、尺寸：字形占画布多大

官方四个插件图标的字形视觉高度**实测**（光栅化后量墨迹包围盒）为
**50.3% – 61.1%**（均值 54.6%）。本图标取 **61.9%**，与官方最大的
`Auto Review`（61.1%）基本一致——视觉分量足够，又不越界。

早先的草稿达到 82.8%，明显比官方图标"胖"一圈，放在一起会显得抢眼，已修正。

> 改尺寸时请连带改 `stroke-width`：视觉高度 ≈ `2 × 半高 + 描边宽`，两者按比例走。

---

## 三、配色

全部取自 DSH 官方插件图标自身的色板：

| 用途 | 色值 |
|---|---|
| 主渐变（左上 → 右下） | `#7CB7FF` → `#145AF3` |
| 内芯点缀 | `#45D9E7` |

注：DeepSeek 官方品牌蓝是 `#4D6BFE`（旧版图标用的 `#4C6EF5` 其实是 Mantine 的靛蓝，
并不属于 DeepSeek 色系）。本图标采用上面这套**官方插件图标实际在用的渐变**，
因此与它周围的人更协调。

---

## 四、两个易踩的坑（都实际踩过）

### 1. 遮罩与渐变的 id 不能相同

```xml
<!-- 错误：同文档内 id 冲突，图形会消失，只剩一个点 -->
<mask id="a">…</mask>
<path fill="url(#a)" mask="url(#a)"/>
```

本图标统一加 `smp` 前缀且彼此不同（`smpCore` / `smpBlue`）。即使宿主日后改成
内联渲染，也不会与其它插件的 `id="a"` 互相覆盖——官方插件图标用的正是 `id="a"`。

### 2. XML 注释里不能出现双连字符和小于号

```xml
<!-- 错误：注释里的 var(--dsw-*) 含双连字符，XML 不合法 -->
<!-- 错误：注释里写 <img> 标签含小于号，XML 不合法 -->
```

两者都会让**整个图标被静默丢弃**并回退成默认图形——不报错，只是"看起来没生效"。
所以 `icon.svg` 里只保留最小注释，设计说明放在这份文档里。

---

## 五、备选方案

[`icon-alternatives/gem-facet.svg`](icon-alternatives/gem-facet.svg)：圆角菱形 + 斜向切面
（两半用不同渐变）。规格与正式稿完全相同，字形高度 57.8%，同样落在官方区间内。
若要换用，把它的内容整体覆盖到 `icon.svg` 即可，无需改动 `package.json`。

---

## 六、改完怎么自查

1. **XML 合法**：`python -c "import xml.etree.ElementTree as ET; ET.parse('icon.svg')"`
   —— 报错就说明图标会被静默丢弃。
2. **画法合规**：36×36 画布、无实心底板、渐变自包含、无 `currentColor`、无 `var(--…)`。
3. **尺寸协调**：字形视觉高度落在 50%–61%；可把 SVG 放大到 720px 截图，
   用 Pillow 量 alpha 通道的包围盒。
4. **看实际效果**：务必在**浅色和深色两种主题**、以及 **48px 卡片框与 40px 行内框**
   两种规格下都看一眼——宿主有两种尺寸，只调一种容易顾此失彼。