diff --git a/docs/theme-shiroko-assets-spec.md b/docs/theme-shiroko-assets-spec.md
new file mode 100644
index 0000000..3eb02c7
--- /dev/null
+++ b/docs/theme-shiroko-assets-spec.md
@@ -0,0 +1,117 @@
+# 主题素材规格（shiroko）
+
+给外部生成工具用的参数表。照着填尺寸/比例/雾度，导出后按「换图清单」替换即可。
+所有尺寸都按 **2× 出图、1× 显示** 写，避免高分屏发虚。
+
+## 一、总表
+
+| 文件 | 用途 | 画布（生成） | 画布（导出） | 显示尺寸 | 透明 | 体积上限 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `chibi/window.webp` | 人物 | 270 × 920 | 135 × 460 | 高 400px（宽 ≈117） | ✅ 需要 | 40 KB |
+| `props/bike.webp` | 自行车 + 步枪 | 794 × 518 | 397 × 259 | 高 259px（宽 ≈397） | ✅ 需要 | 40 KB |
+| `scene-desktop.webp` | 教室背景（桌面） | 3840 × 2160 | 1920 × 1080 | `cover` 铺满 | ❌ 不需要 | 40 KB |
+| `scene-mobile.webp` | 教室背景（≤900px） | 1440 × 2006 | 720 × 1003 | `cover` 铺满 | ❌ 不需要 | 30 KB |
+| `pattern-dark.svg` | 深色模式平铺纹样 | 240 × 240 | 240 × 240 | 平铺 | ❌ | 2 KB |
+
+比例（认准这个，比像素更重要）：
+
+- 人物 **1 : 3.41**（宽 : 高 ≈ 0.293）
+- 道具 **1.53 : 1**（397 : 259）
+- 桌面背景 **16 : 9**
+- 移动背景 **0.718 : 1**（≈ 9 : 12.5）
+
+## 二、人物 `chibi/window.webp`
+
+| 项 | 值 |
+| --- | --- |
+| 画布 | 270 × 920 px，透明背景 |
+| 姿势 | 侧后方 3/4 视角、双手背在身后、头略向右（**不要正面直视**） |
+| 脚底 | **贴画布底边**（误差 ±4px），不要留空白 |
+| 头顶 | 贴画布上沿；若画光环，环心必须透明 |
+| 左右余量 | 各留 10~20px，别让手臂被画布裁掉 |
+| 雾度 | RGB 压白 **16%**：`v' = v×(1-0.16) + 255×0.16` |
+| 色彩 | 下表是**压白 16% 之后**的显示值，生成时按 `原色 = (显示值 − 40.8) / 0.84` 反算 |
+
+| 部位 | 显示值 | 生成时用 |
+| --- | --- | --- |
+| 头发 | `#c4c3c6` | `#b9b8bb` |
+| 围巾 | `#8abbc6`（青绿，别用纯蓝） | `#8fc1c9` |
+| 西装 / 上衣 | `#565e72` | `#3a4256` |
+| 鞋 | `#4f4f4f` | `#3f3f3f` |
+| 袜 | `#ffffff` | **用 `#ededed`**（纯白会和背景粘在一起，抠图会吃穿） |
+| 光环 | `#8abbc6` 细环 | `#7fd3dc` |
+
+要点：
+
+- **不能有描边**。平涂色块、无 line art、无渐变。
+- 抠图后检查三处必须透明：**手与背之间**、**两腿之间**、**光环环心**。
+  这三处是闭合区域，只从四角抹白是抹不掉的（我们踩过）。
+- 白袜子是 `#ededed` 左右，背景是 `#fdfdfd`，两者只差 16 级——抠图时**不要把阈值开大**，否则袜子会被吃穿。
+
+## 三、道具 `props/bike.webp`
+
+| 项 | 值 |
+| --- | --- |
+| 画布 | 794 × 518 px，透明背景 |
+| 内容 | 银色／白色城市自行车 + 一把细长步枪斜靠车架 |
+| 朝向 | **车头朝右**（和人物同向） |
+| 地面 | 轮子底线贴画布底部，下方留 12~16px 给接触阴影 |
+| 阴影 | 可以在图内自带一层椭圆软影（不透明度 15~20%，模糊 8~12px） |
+| 雾度 | RGB 压白 **26%**（比人物淡一档，它在人身后） |
+
+要点：
+
+- 侧视图即可，但不要画成“图标”——轮辐、脚踏、链条这些细节保留，否则缩到 259px 会变成一个圈。
+- 枪要细长、冷色（灰蓝），**不要木色**（会像双管猎枪）。
+
+## 四、场景 `scene-desktop.webp`
+
+| 项 | 值 |
+| --- | --- |
+| 画布 | 3840 × 2160（16:9），不透明 |
+| 导出 | 1920 × 1080，WebP q82 |
+| 色调 | 灰蓝／暖白，均值亮度 **235~245**，标准差 6~9（几乎是白雾） |
+| 处理 | 整体压白 30~38%，高斯模糊 1.2~1.4px |
+
+**构图硬约束（这条最容易翻车）：**
+
+1. **左侧 0~22% 的前景必须是空地（地板）**，不能有课桌、椅子、书包。
+   人物是贴在最上层的独立图层，脚下必须有地面，否则会读成“站在课桌上”。
+2. 课桌、椅子、黑板放在**中部偏右**，因为中间会被卡片完全盖住。
+3. **不要有必须完整露出的元素**（`background-size: cover` 会按视口裁两侧，1080 高的屏裁掉约 5%）。
+4. 不要出现人、文字、水印。自行车也不要画进背景——它要跟着人物一起移动。
+5. 玻璃／窗框这类高频细节会干扰卡片可读性，右侧留白区尽量干净。
+
+## 五、换图清单
+
+1. 覆盖同名文件（格式 `WebP`，有透明的存 `q88`，场景存 `q82`）。
+2. `static/css/themes/shiroko.css`：
+   - 若**显示尺寸不变**：只改三处 URL 的 `?v=`（图片不走 `StaticVersion`，缓存 1 天）。
+   - 若显示尺寸变了：改 `--tb-deco-size` 的 `auto 400px`（人） / `auto 259px`（车）。
+3. `internal/conf/static.go` 的 `StaticVersion` +1（CSS 改了必须）。
+4. 重新编译部署（静态资源是编译期 embed，只重启不重编不会变）。
+
+### 定位公式（改比例时才需要算）
+
+`background-position` 的百分比是相对 **(定位区宽 − 图片宽)**，不是视口宽：
+
+```
+实际 left = (视口宽 - 显示宽) × (pos%） + 偏移量
+```
+
+当前值（视口 1512 时：人物左沿 173px、车左沿 -55px，两者重叠区由人物遮住）：
+
+```css
+/* 人物：显示高 400，显示宽 = 400 × 0.293 ≈ 117 */
+left: max(10px, calc(50% - 524px)) bottom 36px;
+/* 车：显示高 259，显示宽 ≈ 397 */
+left: calc(50% - 612px) bottom 20px;
+```
+
+## 六、验收（不看代码也能查）
+
+1. **白边**：放大 300% 看轮廓，出现 1px 白色描边就是没抠干净。
+2. **闭合区域**：手内侧、腿间、环心应能透出背景色。
+3. **接地**：脚底／轮底离画布底边 ≤ 4px；有阴影时阴影在轮子内侧。
+4. **体积**：人 ≤40KB、车 ≤40KB、场景 ≤40KB（现在分别是 16 / 23 / 19 KB）。
+5. **深色模式**：所有图片在深色下都不显示，不用管。
diff --git a/docs/theme-shiroko.md b/docs/theme-shiroko.md
index 15fdcc1..9984ca4 100644
--- a/docs/theme-shiroko.md
+++ b/docs/theme-shiroko.md
@@ -63,6 +63,8 @@ available = default,sakura,shiroko
 - 所有槽位必须是单张图，**不能在一个槽位里塞逗号列表**（会让层数与 size/position 错位）。
 - 8bit 渐变要检查阶梯：横向扫描线的相邻像素差应 ≤2~3；本次实测 max 4，无可见色阶。
 
+> 尺寸 / 比例 / 雾度等可直接拿去外部工具复用的参数，见 [theme-shiroko-assets-spec.md](theme-shiroko-assets-spec.md)。
+
 ## 素材清单
 
 位于 `static/images/themes/shiroko/`，已随二进制嵌入（`static/fs.go` 的 `images/themes`）。