# 画布节点可读性设计沉淀：节点与图片创作面板

> 范围：无限画布中的节点外壳、节点内容空态、节点标题、图片创作面板和节点间连接线。
> 目标：节点和连接在浅色、深色，以及点阵/线稿/空白画布背景上都能被快速识别和操作。
> 状态：已实现并完成常规桌面尺寸下的浅色、深色浏览器回归。

## 1. 问题定义

画布节点可能直接落在白色或黑色背景上。只依赖全局卡片表面会造成四个问题：

- 浅色画布与白色节点没有表面明度差，深色画布与节点的明度差也不足。
- 节点边界消失，空态内容看起来像画布的一部分。
- 图片创作面板的“将使用默认模型与参数”提示、输入区和操作控件缺少稳定的表面层级。
- 节点间普通连接线使用过低的透明度和线宽，在低缩放比例或点阵背景上难以追踪。

这不是生成逻辑或参考图尺寸逻辑的问题，因此本次只调整视觉契约，不改变节点数据、生成参数、定位和交互流程。

## 2. 设计决策

### 2.1 节点使用画布主题 token

`canvasThemes`（画布主题 token）中的 `canvas` 与 `node` 语义共同负责画布层级：

- `canvas.background`：创作空间的底层表面，与节点主体保持稳定明度差。

- `fill`：节点主体表面。
- `panel`：节点内部面板和空态子表面。
- `edge`：节点与画布之间的低对比边界。
- `shadow` / `hoverShadow`：静止与悬停时的空间层级。
- `text` / `muted` / `faint`：正文、辅助说明和占位内容。

浅色和深色主题必须成对提供这些 token。节点不能回退到全局 `--card-surface`，因为它不知道当前画布背景和节点层级。本轮调整固定的 `canvas.background`，并单独增强深色点阵与线稿网格；节点、浮层、边框、阴影和网格图层渲染透明度保持既有值。

深色画布底层使用比原节点和浮层更亮的中性灰，使原有深色工具表面作为更深一层自然显现，避免蓝灰背景与中性黑工具框的色温割裂；浅色画布底层使用比白色节点更沉的中性雾灰。该方案不通过整体提亮工具表面制造层级。自定义主题只调整画布底层和网格，允许设置背景色、明亮度、网格颜色与强度以及基础浅色/深色界面；节点、工具浮层、文字、边框和阴影继续使用原项目主题 token。

### 2.2 节点外壳与空态

`CanvasNode`（画布节点外壳）继续使用原项目的 `node.fill` 和主题阴影。普通状态保留透明的固定 1px 边界占位，不改变 Note 与其他节点的既有外观；选中状态继续沿用原有 active stroke。

`CanvasNodeContent`（节点内容渲染）的绘图空态在节点内部增加一个轻量子表面和图标边界，使“打开绘图”在白色和黑色背景下都能被识别；真实媒体内容不增加额外遮罩，不改变原始比例。

### 2.3 图片创作面板同步适配

`CanvasNodePromptPanel`（图片/视频/文本/音频创作面板）把面板变量绑定到同一组画布主题：

- 面板表面使用 `node.panel`，边界使用 `node.edge`，阴影使用 `node.shadow`。
- 模型选择器、参考素材、放大编辑和参数折叠按钮使用 `toolbar.itemHover` 与 `toolbar.activeBg`，不再依赖只适合深色背景的白色 hover。
- 展开编辑 Modal 使用相同的表面、边界和阴影，避免节点内面板与放大面板产生两套视觉语言。
- “将使用默认模型与参数”仍是状态说明，不改变模型解析或生成默认值。

### 2.4 连接线可读性

`ConnectionPath`（节点连接线）把交互命中层和视觉展示层分开：透明路径继续保留 16px 点击区域，视觉路径不承担点击事件。

- 普通状态使用“柔和外层 + 清晰内芯”两层路径，提高连接在画布背景上的连续性，但不使用高亮色制造噪音。
- 悬停或选中状态切换到 `accent.primary`（主题强调色），同时提高线宽、透明度和流动虚线强度。
- 起点和终点使用轻量圆点标识，让用户能快速判断连接的两端。
- 所有路径使用 `vectorEffect="non-scaling-stroke"`，保证缩放画布时线宽保持可读；动效继续服从 `prefers-reduced-motion`。

## 3. 状态与边界

| 状态 | 处理 | 目的 |
| --- | --- | --- |
| 默认 | `node.panel` + `node.edge` + `node.shadow` | 与点阵、线稿或空白背景分离 |
| 悬停 | `hoverShadow`，控件使用 `activeBg` | 提示可操作性，不改变布局 |
| 选中 | 沿用 active stroke | 与节点选中态保持一致 |
| 禁用/无内容 | 沿用 `faint` 和既有空态文案 | 不伪造生成成功或配置状态 |
| 展开编辑 | Modal 复用同一套主题 token | 保持放大编辑与节点内编辑一致 |
| 连接线默认 | 中性颜色的外层 + 清晰内芯 + 端点圆点 | 在低缩放和点阵背景下保持连贯可见 |
| 连接线悬停/选中 | 强调色、增强线宽、流动虚线 | 快速识别当前连接，不改变连接数据 |

本次不调整节点尺寸、面板定位、参考图尺寸选项、生成参数和资源同步逻辑。

## 4. 实现地图

- `web/src/lib/canvas-theme.ts`：维护浅色/深色节点边界和阴影 token。
- `web/src/components/canvas/canvas-node.tsx`：应用节点外壳和节点标题的主题表面。
- `web/src/components/canvas/canvas-node-content.tsx`：应用绘图空态子表面。
- `web/src/components/canvas/canvas-node-prompt-panel.tsx`：注入图片创作面板和放大编辑面板的主题变量。
- `web/src/components/canvas/canvas-connections.tsx`：渲染连接线的命中层、普通层级、选中流动线和端点标识。
- `web/src/styles/globals.css`：维护面板控件 hover 与尺寸调整手柄的唯一规则。

## 5. 验证与待回归

已完成：

- `git diff --check` 通过。
- `bun test test/canvas-starter.test.ts test/canvas-visual-contrast.test.ts` 通过（8 项）。
- `bun run build` 通过，包含 TypeScript 检查和 Vite 生产构建；只有既有的大分块体积提示。
- 本地前端与后端入口可用；已登录浏览器确认浅色背景 `#EDEEEE`、深色背景 `#262626` 正常生效，原节点与工具浮层颜色保持不变；自定义主题支持背景色与明亮度、网格颜色与强度以及基础浅色/深色界面，深色点阵和线稿网格使用 `rgba(205,205,205,0.28)`。

待确认：

- 在真实媒体节点中分别检查图片创作面板默认、悬停、选中和展开编辑状态。
- 在点阵、线稿和空白背景下检查节点边缘、空绘图态和“将使用默认模型与参数”的对比度。
- 在 25%、40% 和 100% 缩放下检查普通连接线、悬停/选中连接线及两个端点的可见度。
- 在窄屏和触屏尺寸补充检查节点、起始框与添加菜单的布局边界。