# Fun Toolkit · 工具页面框架规范

适用范围：新增图片、文件与素材生产工具。配合现有 UI 规范使用，先搭结构与状态，再接真实处理逻辑。

当前团队交付为 [fun-toolkit-ui v1.0.1](downloads/fun-toolkit-ui-1.0.1.zip)：自包含 Skill、最新页面模板、8 个空态 / 占位 SVG、反馈与动效资源、接入说明和验收清单。下载不等于安装；按所用 Agent 的方式添加并确认识别 `SKILL.md` 后，使用 `$fun-toolkit-ui` 发起任务。在线规范与团队包是当前交付，PDF v1.2 为历史快照。

## 1. 从一张工作台开始

统一顺序：**选择素材 → 预览与调整 → 生成 → 下载**。无需手动生成的工具，可以在上传后自动处理，但要明确显示处理状态。

```text
全站页头：Logo / 工具导航 / 中英切换 / 联系作者
工具标题 + 使用说明
┌────────────────────────────┬──────────────┐
│ 预览与输入                  │ 输出结果     │
│ 上传 / 文件信息 / 素材预览   │ 结果预览     │
│ 参数与动作（按需）           │ 尺寸 / 文件  │
│ 播放 / 裁切 / 生成 / 状态    │ 导出 / 下载  │
└────────────────────────────┴──────────────┘
全站页脚：版权 / 使用统计 / 设计规范 / 作者
```

| 区域 | 必选内容 | 按需模块 |
| --- | --- | --- |
| ① 全站页头 | Logo 回首页；当前工具导航；语言；作者入口 | 工具增多时采用清晰的更多工具入口 |
| ② 标题与帮助 | 一个左对齐 H1，简短工具名 | 灰色“使用说明 / 案例图片”按钮；复杂规则放弹窗 |
| ③ 预览与输入 | 上传入口、文件约束、空态、载入后预览、替换入口 | 拖放、批量队列、透明底、预览背景切换 |
| ④ 参数与动作 | 当前任务状态；需要用户决定时才出现参数 | 裁切、尺寸、质量、时间轴、生成、进度、重试 |
| ⑤ 输出结果 | 首次空态、可下载结果、真实尺寸、下载动作 | 结果缩略图、文件体积、多规格列表、ZIP |
| ⑥ 全站页脚 | 版权、规范、统计、作者入口 | 其他经过确认的资源链接 |

“六区”是六种职责，不是六张卡。最小工具只需要**左侧工作卡 + 右侧输出卡**。参数靠近相关预览或放在输出卡内；不要为一两个字段另开侧栏。仅当复杂参数确实需要持续操作时，才增加折叠分组。

## 2. 尺寸与响应式

| 场景 | 统一规则 |
| --- | --- |
| 桌面 > 900 px | 页面最大 1440 px，包含左右各 42 px 内边距；901–1100 px 紧凑桌面改为左右 24 px；超宽屏居中。工作区目标 7:3，右栏不小于 300 px，栏间距 16 px。最小宽度优先于精确比例。 |
| 1440 px 示例 | 实际内容宽 1356 px；扣除 16 px 栏间距，约为左 938 / 右 402 px。 |
| 541–900 px | 切为单列，左右 24 px；先预览与参数，后结果。不用压窄双栏来容纳。 |
| 320–540 px | 左右 16 px；工作台卡片间距 14 px、内边距 16 px。页头两行：品牌与全站操作在上，工具导航在下。 |
| 卡片与标题 | 外卡桌面圆角 22 px、内边距 24 px；手机圆角 18 px。H1 桌面 26/32 px、手机 22/28 px；标题到工作台桌面 16 / 手机 14 px。 |
| 预览 | 新通用模板桌面空预览默认 440 px，541–900 px 为 400 px；手机空态可用 clamp(280px, 48svh, 360px)。上传后按内容自适应，不把输出比例当作整张工作卡的固定高度。 |
| 内容与操作 | 手机操作命中区至少 44×44 px；输入内容至少 16 px。长文件名可换行或展开；按钮英文不截掉关键动词。 |

主内容至少覆盖 320 px；页面不得横向滚动。表格、时间轴等确需横向查看的内容只在自身区域滚动，并标明可滑动。默认采用自然页面滚动；不要给左右两栏都设置固定满屏高度。新模板默认不吸附输出栏，避免手机键盘、弹窗和短视口互相遮挡。

当前实现差异：头像框与 Banner 的桌面空预览为 440 px，房间背景保留 590 px 的长画布例外；旧卡片内边距有 23 / 19 / 18 px，24 px 是新增模板统一目标。旧隐藏的 `.sources` 来源侧栏不复制。页头和主体在部分历史断点的留白不同，新模板以内容对齐为目标。

## 3. 五个必交付状态

| 状态 | 输入与预览 | 输出与动作 | 推荐文案 |
| --- | --- | --- | --- |
| 上传前 idle | 图标、短标题、支持格式、上传按钮；拖放只是补充入口 | 空结果；导出不可用，附近说明条件 | “点击或拖入图片” / “上传素材后可生成文件” |
| 已载入 ready | 展示素材、文件名、替换；参数可用 | 手动流程显示“生成 WebP”；自动流程进入处理中 | “已载入，可以调整后生成” |
| 处理中 processing | 保留当前素材；锁定会改变本次任务的操作；显示真实阶段 | 主动作保宽、禁止重复；有真实进度才显示百分比 | “正在读取…” / “正在生成…” / “正在打包…” |
| 成功 success | 预览与参数仍可检查 | 展示可用结果，明确单个下载与全部下载；不只弹 Toast | “已生成 2 个文件” / “下载全部 · ZIP” |
| 错误 error | 保留输入；在失败位置写清原因与恢复入口 | 不把失败显示为 0 个成功；保留已有有效结果的能力需真实实现 | “文件读取失败，请替换文件或重试” |

空态、处理中、成功、错误占用同一稳定区域，减少高度跳动。提示使用文字与图标，不只改变颜色。读取失败、参数不合法、编码失败和下载发起失败应分别反馈；“已发起下载”不能写成“已保存成功”。

实际任务可拆分读取、解码、渲染、编码、打包；五态是统一对外表现。新工具要定义状态转换与取消后去向，不能只给按钮替换一句文案。批量部分成功、单项重试、取消处理属于按需能力，未实现时不显示可用入口。

## 4. 三种工具变体

| 变体 | 页面组织 | 当前工具映射 |
| --- | --- | --- |
| 单文件 → 多规格 | 一处上传；同一工作卡内展示多个预览；右侧按规格列结果；支持单个下载与 ZIP | **Banner**：上传后自动生成；房间 772×200，游戏 684×240，内图 645×201；游戏预览黑色/透明仅影响查看，导出仍透明。 |
| 多文件 → 批量结果 | 左侧批量预览；每个源文件有稳定标识；裁切与错误定位到具体文件；右侧按文件与规格组织 | **房间背景**：720×1560 与 300×480；独立裁切位置；预览 UI 图层不混入实际背景导出。 |
| 动画 → 选帧导出 | 动态预览下放播放/暂停、前后帧、时间轴；右侧显示选定帧、锁定尺寸与导出 | **头像框**：SVGA 默认停在第 1 帧；点击播放才播放；默认 240×240、1:1 锁定，整数范围 16–2048；导出静态透明 WebP。 |

工具差异只改变所需模块，不改变全站页头、标题、卡片、反馈和结果的视觉语言。单文件不硬塞批量操作；动画不自动播放；没有可调质量的业务，不展示无效“质量”滑杆。

未来文字 / 表单工具可沿用同一双栏：左输入、右结果，移除上传与画布槽；没有媒体预览时，不造空画布填位置。

## 5. 状态持有与结果有效性

- **UI 状态与输出状态分开**：预览背景、语言和视口宽度不应改变导出内容；处理参数、源文件和选定帧会改变输出版本。
- **参数变化即失效**：新工具应将旧结果标为“设置已更改，请重新生成”，防止下载旧内容；成功提交新结果后再释放旧资源。此为接入目标，不能假定既有三工具已全部具备同一套版本管理。
- **保留当前会话**：切换语言、预览背景和窗口宽度保留素材、设置与帧位置。是否在切工具或刷新后恢复，必须在需求里写明；不要承诺浏览器刷新可恢复内存文件。
- **任务有边界**：用任务版本识别过期回调，快速替换文件后，旧任务不得覆盖新文件。离开页或替换结果时停止无用播放器、释放 Object URL 和图像内存。
- **统计单独接入**：生成成功的输出文件数和有效发起的下载动作分别记录；失败不计数、打包不重复计生成。现有统计服务只登记 room/avatar/banner，新增工具需同时补充前后端登记。

## 6. 命名与接入契约

保持“显示名称、路由、工具标识、DOM 名称”各自稳定，避免把中文标题当内部 ID。

| 对象 | 当前约定 / 新工具要求 |
| --- | --- |
| 工具标识 | 当前 data-tool 为 room / avatar / banner；新增使用短英文小写标识，同一值贯穿页面、任务和统计登记。 |
| 路由 | 现有 #room-backgrounds / #avatar-frames / #banners；新增采用可读的英文短横线地址，直接访问能选中对应导航。 |
| 页面结构 | 旧页沿用 .workspace / .preview / .exports；新增模板自行隔离样式，按插槽职责接入，不要求重命名旧三工具。 |
| DOM 与字段 | ID 带工具前缀，例如 cover-file / cover-width；label for 必须指向唯一字段 ID；不靠 placeholder 充当标签。 |
| 状态 | 模板建议 data-state="idle|ready|processing|success|error"；JS 状态应是来源，CSS 只呈现状态。 |
| 输出记录 | 至少持有 sourceId、规格标识、width、height、format、size、fileName、有效下载地址和任务版本；新增字段按真实流程需要加入。 |
| 双语文案 | 按工具归组，例如 cover.title / cover.upload / cover.generating / cover.error；标题、标签、错误、空态、ARIA 名称一并翻译。不要散落硬编码文案。 |

新增工具的最少业务定义：**输入类型与上限、是否自动处理、可调参数与默认值、输出规格与压缩策略、文件命名、失败恢复、统计时点**。素材限制必须真实校验；不能把 Banner 的 30 MiB / 4000 万像素限制直接描述为全站既有能力。

当前网站没有自动注册新工具的通用 API；新增首页入口、hash 路由、词条、导航选中和统计登记需逐处接入。独立 Starter 只用于复制页面骨架，不是第 4 个生产工具；状态控制器属于示例。

## 7. 统一交互的底线

- 主操作蓝底白字；普通 hover 保持蓝色调。替换文件沿用绿色语义；删除用危险色。每个工作区域只突出当前阶段最重要的一个动作。
- 鼠标输入焦点为 1 px 蓝边与极淡光晕；键盘保留 2 px 焦点外环。错误描边优先，不能被 hover 覆盖。
- 主按钮可复用现有轻扫光；禁用和处理中不扫光。仅精确指针 hover 触发，触屏不给残留 hover，也不持续循环。
- 帮助使用统一弹窗：轻弹性入场、玻璃模糊遮罩、明确关闭按钮、Escape 关闭、焦点进入与返回。尊重 prefers-reduced-motion。
- 语义元素优先：导航用 a、操作用 button、字段有 label；状态用 role=status / aria-live=polite。不要把同一个上传区和内部上传按钮做成两个互相触发的嵌套点击陷阱。
- 手机保留正常纵向滚动；滑杆操作区足够大；长结果不会被固定底栏压住；200% 缩放仍能操作。

颜色、表单细节和动效参数沿用主规范，不在每个工具里复制另一套。页面框架只规定位置与职责，不替代组件规范。

## 8. 新工具接入清单

1. 选变体：单文件、批量、动画；删掉不需要的模块。
2. 写清输入、输出和默认值；先确认自动处理还是手动生成。
3. 复用全站壳和两个工作卡，补工具标题、帮助、导航选中与首页入口。
4. 接入真实读取、校验、处理、编码和下载；不要用计时器模拟成正式成功。
5. 补齐五态、字段校验、替换与失败恢复；定义旧结果失效和并发任务规则。
6. 补中英与可访问名称；检查 Tab 顺序、弹窗关闭返回、减少动画。
7. 验证 1440 / 1024 / 900 / 768 / 390 / 320 px、长英文、200% 缩放；确认页面无横向溢出。
8. 用真实素材验证尺寸、透明度、画质、命名、单个与批量下载；统计在真实成功事件后接入。

**完成标准**：可复制的页面壳、可理解的五态、可替换的业务接口。模板不自动提供图像编码、SVGA 解码、文件上传服务、取消任务、持久化或全站统计；这些必须单独实现并测试。

## 9. 可复制的搭建需求

> 使用 `$fun-toolkit-ui`，请按 Fun Toolkit 工具页面框架搭建「[工具名]」。复用现有全站导航、左对齐标题与帮助、7:3 双栏工作台和页脚。选择 [单文件 / 批量 / 动画] 变体；输入为 [格式与限制]，采用 [上传后自动处理 / 点击生成]，参数为 [字段、默认值、范围]，输出为 [尺寸、格式、压缩、文件名]。补齐上传前、已载入、处理中、成功、错误五态；新参数使旧结果失效，保留输入并提供真实恢复入口。统一蓝色 hover、精细焦点、轻扫光和玻璃弹窗；支持中英、键盘与减少动画。≤900 px 单列，手机边距 16 px、操作目标 44 px，验证至 320 px。真实处理与统计单独接入，未实现能力明确标为示例，不制造成功结果。

参考来源：当前 Fun Toolkit 三工具源码、在线 UI 设计规范 v1.4.1 与团队 Skill v1.0.1。PDF v1.2 为历史快照。本文是新增工具的统一接入标准，现有页面中的历史间距和状态差异按后续迭代逐步收敛。

## 下载模板的实际入口

模板以 `data-slot` 标记职责区，用 `ToolPageDemo.setState('empty'|'ready'|'processing'|'success'|'error')` 切换演示；其中 `empty` 对应本文的 `idle`（上传前）。`setLanguage('zh'|'en')` 切换文案，`getState()` 读取当前状态。正式接入应替换 `tool-page.js` 中的 `simulateGeneration()` 和 `previewFile()`，用真实处理结果驱动状态。

主要插槽：`site-header`、`page-heading`、`workspace`、`preview-card`、`preview-stage`、`source-meta`、`parameters`、`output-card`、`results`、`primary-action`、`site-footer`。先保留框架，按任务删掉不需要的模块。成功示例的下载按钮始终禁用，只有真实文件及下载地址就绪后才启用。


## 配套反馈与动效

新增工具的空状态、加载、图片与头像占位、元素出入场和装饰视差，参见同目录 `feedback-states.html` / `feedback-states.md`。团队 Skill v1.0.1 已合并最新模板、`feedback-motion.css` / `.js` 和 8 个 SVG，优先使用完整团队包；单独资源 ZIP 保留按需下载。

当前房间背景、头像框与 Banner 通过根目录 `tool-feedback.css` / `tool-feedback.js` 适配共享 `feedback-motion`，保留各自真实处理流程。模板已接入同一套空态 / 占位、800ms Spinner、1600ms Skeleton，以及离屏 / 后台 / 减少动画规则。普通内容入场 180ms、最多上移 6px；生产工具的 Canvas 区域采用 160ms、opacity .35→1 的轻淡入，不改变精确坐标，忙碌提示 120ms 淡出。不能把模板演示控制器当作生产适配层或业务处理器。