# Subnautica2Maps — Design Handoff

状态：**DESIGN_GO after t_fce73c42 resource-silver repair / 可交给前端实现**
日期：2026-05-20
任务：t_b2675914
修复任务：t_fce73c42（resource-silver content contamination repair）
Tenant：site-rerun-subnautica2maps-20260520-stitch-sdk-clean

## 1. 视觉真源

设计目录：`/root/.hermes/kanban/boards/site-factory/workspaces/t_c3810340/reports/site-pipeline/site-rerun-subnautica2maps-20260520-stitch-sdk-clean/subnautica2maps/design`

前端实现以这些文件为准：

### Stitch 元信息
- `stitch/screen-index.json`
- `verification.json`

### HTML/CSS 参考
- `html/home-desktop.html`
- `html/home-mobile.html`
- `html/map-normal-desktop.html`
- `html/map-search-filter-desktop.html`
- `html/map-marker-popup-desktop.html`
- `html/map-route-desktop.html`
- `html/map-mobile-bottom-sheet.html`
- `html/resource-silver-desktop.html`
- `html/resource-silver-mobile.html`
- `html/guide-coordinates-mobile.html`
- `html/legal-footer-state.html`
- `html/guide-coordinates-desktop.html`

### 截图
- `screens/home-desktop.png`
- `screens/home-mobile.png`
- `screens/map-normal-desktop.png`
- `screens/map-search-filter-desktop.png`
- `screens/map-marker-popup-desktop.png`
- `screens/map-route-desktop.png`
- `screens/map-mobile-bottom-sheet.png`
- `screens/resource-silver-desktop.png`
- `screens/resource-silver-mobile.png`
- `screens/guide-coordinates-mobile.png`
- `screens/legal-footer-state.png`
- `screens/guide-coordinates-desktop.png`

### 内容契约
- `content-fit-matrix.md`

## 2. Stitch Project / Screen ID

| Screen | Viewport | Project ID | Screen ID | HTML | Screenshot | Gate |
|---|---|---|---|---|---|---|
| home-desktop | DESKTOP | `15241094415756415186` | `4a3e8a6f00e94ddd8d4e43bcd97291e3` | `html/home-desktop.html` | `screens/home-desktop.png` | PASS |
| home-mobile | MOBILE | `15241094415756415186` | `af2d4659174c4fe8be7ddc58b9d05469` | `html/home-mobile.html` | `screens/home-mobile.png` | PASS |
| map-normal-desktop | DESKTOP | `15241094415756415186` | `1bd57ffbbdbd4779b5e5c8b69dee90f2` | `html/map-normal-desktop.html` | `screens/map-normal-desktop.png` | PASS |
| map-search-filter-desktop | DESKTOP | `15241094415756415186` | `e0c497b91bb746bda135bcb64ff3ee87` | `html/map-search-filter-desktop.html` | `screens/map-search-filter-desktop.png` | PASS |
| map-marker-popup-desktop | DESKTOP | `15241094415756415186` | `bb5cd918f27443eca5dcfd625eb050ee` | `html/map-marker-popup-desktop.html` | `screens/map-marker-popup-desktop.png` | PASS |
| map-route-desktop | DESKTOP | `15241094415756415186` | `0b6962e8d92e4699bfe06d26ab0d068b` | `html/map-route-desktop.html` | `screens/map-route-desktop.png` | PASS |
| map-mobile-bottom-sheet | MOBILE | `15241094415756415186` | `9dcf4b6117104e5b9a4bc08f37d0d2a7` | `html/map-mobile-bottom-sheet.html` | `screens/map-mobile-bottom-sheet.png` | PASS |
| resource-silver-desktop | DESKTOP | `15241094415756415186` | `e3af7f1334f04f429dc3d5fdea25cbf6` | `html/resource-silver-desktop.html` | `screens/resource-silver-desktop.png` | PASS / repaired t_fce73c42 |
| resource-silver-mobile | MOBILE | `15241094415756415186` | `cab7304783e54c2fa15e258a2dc60e76` | `html/resource-silver-mobile.html` | `screens/resource-silver-mobile.png` | PASS / repaired t_fce73c42 |
| guide-coordinates-mobile | MOBILE | `2288259298607184394` | `f9496e945ea34214a642d7520ec90656` | `html/guide-coordinates-mobile.html` | `screens/guide-coordinates-mobile.png` | PASS |
| legal-footer-state | DESKTOP | `2288259298607184394` | `5f921bf0701549b4903dc088dcc1de32` | `html/legal-footer-state.html` | `screens/legal-footer-state.png` | PASS |
| guide-coordinates-desktop | DESKTOP | `4998469226023875117` | `91187f78b8f843aa9efd2e48a0213ba9` | `html/guide-coordinates-desktop.html` | `screens/guide-coordinates-desktop.png` | PASS |

主项目 ID：`15241094415756415186`
补充修复项目 ID：`2288259298607184394`, `4998469226023875117`

说明：`resource-silver-desktop` 与 `resource-silver-mobile` 已在 t_fce73c42 通过官方 `@google/stitch-sdk` 的 `screen.edit` 重新导出，替换原 Subnautica 1 / non-PRD 内容污染。当前有效 screenId 分别为 `e3af7f1334f04f429dc3d5fdea25cbf6` 与 `cab7304783e54c2fa15e258a2dc60e76`。

说明：`guide-coordinates-desktop` 已用新 prompt 修复，当前有效记录为 projectId=`4998469226023875117`, screenId=`91187f78b8f843aa9efd2e48a0213ba9`。历史上空 `htmlCode.downloadUrl` 或 `htmlCode.mimeType=image/svg+xml` 的尝试只视为失败记录，不纳入交付。

## 3. 设计方向

Abyssal Tactical Console — 深海战术控制台。

关键词：dark underwater ambience、sonar HUD、scanner panels、coordinate/depth readouts、bioluminescent teal/green accents。

核心判断：玩家地图任务优先，合规/fan-made 声明可见但不压过核心工具体验。

## 4. Design Tokens

| Token | Value |
|---|---|
| Background | `#031014` |
| Surface | `#071C22` |
| Panel | `#0B2730` |
| Text Primary | `#D8FFF8` |
| Text Secondary | `#8BB8B0` |
| Accent Primary | `#27E7C5` |
| Accent Secondary | `#B8FF5C` |
| Warning | `#FFD166` |
| Font Display | Oxanium |
| Font Body | IBM Plex Sans |
| Font Mono / Coordinates | JetBrains Mono |

## 5. 覆盖页面 / 状态

1. Homepage desktop/mobile：首屏地图搜索控制台、quick chips、route teaser、trust strip。
2. Map normal desktop：完整地图 app shell，左筛选、中地图、右抽屉。
3. Map search/filter desktop：搜索/筛选激活态，显示结果数、marker clusters、filter pills。
4. Map marker popup desktop：marker 详情、坐标、深度、source/confidence/index policy。
5. Map route desktop：当前位置输入、目标 marker、bearing/distance/depth delta。
6. Map mobile bottom sheet：390px 单列地图 + bottom sheet，44px touch target 基线。
7. Resource silver desktop/mobile：answer-first 资源详情、坐标表、相关 markers、source cards。
8. Guide coordinates desktop/mobile：坐标教程、步骤卡、地图 CTA、自制图解。
9. Legal/footer state：fan-made/legal/DMCA/support footer shell。

## 6. 验证结果

- `screen-index.json` 行数：12
- HTML 校验：12/12 通过；全部以 `<!DOCTYPE html>` 或 `<html` 开头；无 SVG 根文档。
- 截图校验：12/12 通过；全部为非空 PNG/JPEG；当前检测均为 PNG。
- `verification.json` 已更新，包含每个 screen 的 bytes、sha256、HTML start、startsSvg、image signature、detectedType。
- 缺失/无效项：0

## 7. 前端实现注意事项

- 不要把这些 HTML 当成最终生产代码直接上线；它们是视觉真源。前端应迁移视觉系统、布局、状态和内容层级。
- 地图必须保留 app-like 结构：left sidebar / map canvas / right drawer；移动端必须保留 bottom sheet 模式。
- 地图表面、biome、marker、route 视觉必须使用自制/程序化素材或公共引用数据，不得复制官方地图瓦片、官方截图、logo、key art。
- Route helper 用 approximate language，不要暗示精确导航。
- Standalone marker pages 默认 noindex；资源/指南页按上游 index policy 执行。
- YouTube 只做 click-to-load `youtube-nocookie`，且放在主要数据之后；不能占据首屏核心价值。
- Legal/fan-made disclaimer 要出现在 footer/legal shell，但保持低优先级，不替代地图工具价值。

## 8. 需替换 / 接入的内容

- HTML 中的地图/biome/marker 为 Stitch 视觉表达，前端需接入 `data-assets-carry-forward.json` 中的 63 marker 公共引用合同。
- source cards / citation / confidence labels 必须接入真实 public-reference provenance。
- 视频区域需接入安全的 click-to-load YouTube metadata；无视频时显示明确 fallback。
- 所有 Stitch 下载 URL 可能过期；本地 `html/` 和 `screens/` 文件才是交付真源。

## 9. 残余风险

- Stitch 输出是高保真静态状态，不包含真实交互逻辑；前端需实现搜索、筛选、marker popup、route helper、bottom sheet 状态机。
- 游戏站视觉不能使用官方素材兜底；如果前端缺少程序化地图/marker layer，会回落成空框，属于实现风险。
- 当前交付不重跑策略/文案/素材研究；只完成 t_c3810340 后续收尾和证据门槛。

## 10. 下一棒输入

给前端：
- 本文件 `HANDOFF.md`
- `stitch/screen-index.json`
- `verification.json`
- `content-fit-matrix.md`
- `html/*.html`
- `screens/*.png`
- 上游 `data-assets-carry-forward.json`

验收入口：前端实现后，用 12 个状态逐项对齐，不要只看 homepage。


## 11. t_fce73c42 Resource Silver Repair Evidence

- Repaired files: `html/resource-silver-desktop.html`, `html/resource-silver-mobile.html`
- Re-exported screenshots: `screens/resource-silver-desktop.png`, `screens/resource-silver-mobile.png`
- SDK method: official `@google/stitch-sdk` `screen.edit`, no local-html-fallback success claim
- Desktop screen: projectId `15241094415756415186`, screenId `e3af7f1334f04f429dc3d5fdea25cbf6`
- Mobile screen: projectId `15241094415756415186`, screenId `cab7304783e54c2fa15e258a2dc60e76`
- Required field labels present in both repaired HTML files: `marker_id`, `coordinates`, `depth`, `region`, `biome`, `source`, `confidence`, `index_policy`, `retrieved_at`
- Media placement: `youtube-nocookie` appears after primary data as click-to-load guide card design
- Grep guard: PASS, zero hits for legacy contamination term set from t_fce73c42 acceptance brief
- Repair note: `repair-note-resource-silver.md`