# Design System: PixelSmall / PixelTurn Utility Family

## 0. 这份文件的角色

`DESIGN.md` 是设计侧的 `AGENTS.md`。

它不是展示稿，也不是品牌宣传页，而是给人类和 agent 共用的产品家族设计契约。以后凡是这条产品线里的图片处理工具、PDF 处理工具、格式转换工具、批量导出工具，在开始生成页面、拆组件、写样式之前，都先读这份文件。

当出现冲突时，优先级如下：

| 场景 | 优先级 |
|---|---|
| 用户明确要求 1:1 对齐某个参考站 / 源码 / 截图 | 参考实现优先于本文件 |
| 没有明确参考，只是继续做同系列新工具 | 本文件优先 |
| 单个功能模块的业务差异 | 保持家族外壳不变，只替换模块内容 |

---

## 1. 家族目标

这套产品不是“花哨创意站”，而是**浏览器内直接处理文件的轻工具家族**。它要让用户一眼看到三件事：

| 目标 | 设计表达 |
|---|---|
| 本地处理，可信 | 浅底、克制、少炫技、信息清晰、不靠夸张动效获取注意力 |
| 同一家族，可连续使用 | 头部、语言切换、上传区、队列区、配置区、按钮体系高度一致 |
| 专业但不冷 | 中性浅色面、轻边框、柔和阴影、字重和字距控制精细，不做工程台式粗糙感 |

一句话定义：

> 这是一个“精准、克制、浏览器优先、同系稳定”的媒体处理工具家族。

---

## 2. 文章与资料提炼后的核心结论

结合掘金文章《DESIGN.md：让 AI agent 读懂你的设计语言》、Google Stitch 公开资料，以及 Stitch `design-md` skill，可以把 `DESIGN.md` 的价值总结成下面这几条：

| 结论 | 对这个项目的含义 |
|---|---|
| `DESIGN.md` 的本质是“让 agent 读得懂的设计系统” | 以后新工具不再只靠口头说“做得像 PixelTurn 一点” |
| Figma 对人类有效，但对 agent 不够直接 | 需要把颜色、字号、圆角、组件语义、禁忌项落成文本 |
| 它应该是活文档，不是一次性说明 | 家族视觉如果继续进化，这份文件要一起更新 |
| 它既要描述氛围，也要写清 token 和组件规则 | 只写“高级一点”没用，必须落到数值、层级和结构 |
| 它最适合当“多工具共用外壳”的总规范 | 头部、语言切换、drop、queue、settings、底部操作栏都应该固化成族谱 |

因此，这份 `DESIGN.md` 不只服务当前 `PixelSmall`，也服务未来的：

- 图片压缩
- PDF 压缩
- 图片格式转换
- 尺寸调整
- 批量重命名 / 导出
- 水印 / 裁剪 / 批处理等同系工具

---

## 3. 产品家族的稳定骨架

### 3.1 桌面结构

所有同系工具默认使用同一套三段式结构：

| 区域 | 角色 | 是否稳定复用 |
|---|---|---|
| Header | 主标题、工作区切换、语言切换 | 是 |
| Left Workspace | 上传、说明卡、队列 | 是 |
| Right Configuration | 配置标题、参数编辑、主操作、补充信息 | 是 |

桌面布局原则：

- 页面外层使用浅白背景和大留白
- 主内容采用居中容器
- 内部是 `12` 栏网格
- 左侧工作区占主宽度
- 右侧配置区较窄但固定清晰
- 配置区在桌面可以保持粘性阅读体验

### 3.2 移动端结构

移动端不是简单缩小，而是改成阅读优先顺序：

| 顺序 | 区域 |
|---|---|
| 1 | Header |
| 2 | Dropzone |
| 3 | 紧凑信息卡 |
| 4 | Queue |
| 5 | Configuration |
| 6 | 底部悬浮操作栏 |

移动端硬规则：

- 不允许横向滚动
- 上传后 drop 区自动压缩成紧凑态
- 设置与处理按钮固定在底部悬浮条
- 有 ZIP 下载时，底部悬浮条允许扩展为三按钮并排

---

## 4. 视觉氛围

### 4.1 Atmosphere

这套家族界面应当保持以下气质：

| 维度 | 定义 |
|---|---|
| 亮度 | 明亮、偏纸白，不做暗色主界面 |
| 对比 | 中高对比，但不是纯黑纯白硬碰硬 |
| 情绪 | 冷静、稳、专业、像同一个产品经理长期维护的工具组 |
| 密度 | 中密度；不是营销页，也不是后台报表墙 |
| 动效 | 少而准，只服务状态变化、拖拽感知、处理反馈 |

### 4.2 禁止变成下面这些风格

| 禁止项 | 原因 |
|---|---|
| 炫彩渐变主视觉 | 会破坏工具属性和可信度 |
| 暗黑 + 霓虹高光 | 偏离 PixelTurn 同系质感 |
| 大面积玻璃拟态 | 容易失去结构清晰度 |
| 卡片套卡片套卡片 | 信息噪音太大 |
| 到处都是 icon 外框 | 会显得模板味很重 |
| 过多 hover 特效 | 工具界面应优先功能稳定和低打扰 |

---

## 5. 色彩体系

当前家族采用浅中性灰白体系，强调色极少，主要靠层级和字距建立秩序。

| 名称 | 值 | 用途 |
|---|---|---|
| App Background | `#FDFDFD` | 页面总背景 |
| Panel Background | `rgba(255,255,255,0.96)` | 主卡片、配置卡、队列卡 |
| Muted Panel | `rgba(250,250,250,0.96)` | 次级区块、设置分组、说明块 |
| Border Default | `#E5E5E5` | 主边框 |
| Border Soft | `#F0F0F0` | 分割线、内部边框 |
| Text Primary | `#1D1D1F` | 主标题、主内容 |
| Text Secondary | `#525252` | 辅助正文 |
| Text Muted | `#8B8B8B` | 次级提示、空态说明 |
| Accent Ink | `#171717` | 激活态、主按钮、当前选中 |
| Success | `#238057` | 成功、压缩后体积、完成态 |
| Error | `#B9493E` | 错误 |
| Warning | `#B06D1B` | 警告和保留说明 |

色彩原则：

- 主界面不依赖品牌色；以近黑和浅灰建立秩序
- 绿色只用于真实成功信息，不滥用
- 红色和橙色只用于状态，不参与装饰
- 配置区与队列区的区分靠背景和边框，不靠强色差

---

## 6. 字体与文本层级

### 6.1 字体策略

当前家族优先使用系统无衬线方案，保证浏览器工具的稳定性与多语言兼容性：

| 场景 | 字体 |
|---|---|
| 英文 / 默认 | `system-ui, sans-serif` |
| 中文 | `Noto Sans SC`, `PingFang SC`, `Microsoft YaHei`, `system-ui`, `sans-serif` |

### 6.2 文本层级

| 层级 | 用法 | 典型特征 |
|---|---|---|
| H1 | 页面主标题 | 约 `1.22rem`，中高字重，轻微负字距 |
| H2 / Section Header | Queue 标题、配置标题 | 不大，但清楚，强调结构而非情绪 |
| Overline / Kicker | `CONFIGURATION`、`Queue List` 上的小标题体系 | `9px - 10px`，全大写，高字距 |
| Body Small | 队列细节、说明文案 | `10px - 12px` |
| Meta | hint、状态标签、计数 | 极小号、全大写、字距更大 |

硬规则：

- 小标题体系大量使用全大写 + 字距
- 中文字距要比英文收敛
- 不要出现营销型大口号字体
- 不要随意混入衬线字体

---

## 7. 圆角、边框、阴影

### 7.1 形状

| 类型 | 值 | 用途 |
|---|---|---|
| Major Card Radius | `30px` | 大面板基调 |
| Inner Radius | `22px` | 配置分组、内部容器 |
| Medium Radius | `16px` 左右 | header 胶囊、面板外框 |
| Small Radius | `12px` 左右 | 缩略图、按钮、小容器 |
| Pill Radius | `999px` | 标签、语言切换、状态标签 |

### 7.2 边框

- 默认是 `1px`
- 颜色永远偏浅，不抢文字
- 通过边框组织层级，而不是用厚重描边强调存在感

### 7.3 阴影

| 层级 | 阴影强度 |
|---|---|
| 主卡片 | 很轻，像纸面微浮起 |
| 激活按钮 | 可以略重，但仍克制 |
| tooltip | 比主卡片更明显，但不发光 |

阴影原则：

- 不允许蓝光、紫光、彩色 glow
- 不做厚重投影
- 阴影服务层级，不做装饰

---

## 8. 核心组件总表

| 组件 | 角色 | 家族中是否固定 |
|---|---|---|
| `HeaderShell` | 标题、工作区切换、语言切换 | 固定 |
| `WorkspaceTabs` | 图片 / PDF / 未来更多工具切换 | 固定，可扩展 |
| `LocaleSwitch` | 语言切换 | 固定 |
| `Dropzone` | 上传入口 | 固定 |
| `WorkspaceCards` | drop 下方信息卡 | 固定结构，可换文案 |
| `QueueList` | 文件队列 | 固定 |
| `QueueRow` | 单文件行 | 固定骨架，可扩展 meta |
| `ConfigHeader` | 右栏标题行 | 固定 |
| `SettingsPanel` | 右栏参数编辑 | 固定容器，可换模块 |
| `SegmentedControl` | 输出格式 / 预设 / 模式切换 | 固定 |
| `RangeControl` | 质量 / DPI / 阈值 | 固定 |
| `ActionStack` | 主按钮、次按钮 | 固定 |
| `MobileFabBar` | 移动端底部悬浮操作 | 固定 |
| `CreditsPanel` | 致谢或状态补充信息 | 固定位置，可换内容 |
| `ToastRegion` | 轻提示 | 固定 |

---

## 9. 组件细则

### 9.1 HeaderShell

结构必须稳定：

| 左侧 | 右侧 |
|---|---|
| 主标题 | Tab 胶囊 + 语言切换胶囊 |

规则：

- 主标题永远左对齐
- Tab 胶囊和语言胶囊是两套独立外框，不合并
- 两组胶囊尺寸、圆角、边框语言一致
- `CONFIGURATION` 不放在 header，必须属于右栏自身

### 9.2 WorkspaceTabs

规则：

- 使用和语言切换同体系的胶囊外框
- 按钮较小，克制
- 激活态为深色底、白字
- 默认只承载“工作区切换”，不承载数字徽标和副文案

扩展方式：

- 可以从 `2` 项扩展到 `3-4` 项
- 超过 `4` 项时，优先改成滚动 tab，而不是把按钮做得极小

### 9.3 LocaleSwitch

规则：

- 必须是家族级固定组件
- 与 tab 同语法，不同语义
- 只放简短语言标识，如 `EN` / `中文`

### 9.4 Dropzone

Dropzone 是左栏第一视觉锚点，必须稳定。

结构固定为三层：

| 层级 | 内容 |
|---|---|
| Icon | 加号 / 上传 icon |
| Main Prompt | 一行主提示 |
| Hint | 更淡的格式提示 |

规则：

- 默认大态：中心对齐
- 上传后紧凑态：横向压缩，保留 icon + 主提示 + hint
- 不要在紧凑态塞第二行说明
- 拖拽激活态只做轻边框反馈和 icon 缩放
- icon 不做炫技动画

### 9.5 WorkspaceCards

Dropzone 下方信息卡用于告诉用户当前工作区的关键摘要，但要压成轻量。

固定语义顺序：

| 顺序 | 含义 |
|---|---|
| `label` | 小标题 / kicker |
| `body` | 当前配置摘要 |
| `meta` | 补充说明 |

规则：

- 卡片可以是 2~4 张
- 桌面版独立小卡，移动端压缩为紧凑条形卡
- 不做大段解释文

### 9.6 QueueList

Queue 是左栏的主信息密度区，必须高度稳定。

Header 固定包含：

| 元素 | 说明 |
|---|---|
| 标题 | `Queue List` |
| 数量 | `0 Items` 这种轻量计数 |
| 清空按钮 | `Clear Workspace` |

空态固定包含：

| 元素 | 说明 |
|---|---|
| 轻图标 | 不加圆形夸张包裹 |
| 一行说明 | `No images in queue` / 对应变体 |

### 9.7 QueueRow

单行文件结构固定为：

| 左 | 中 | 右 |
|---|---|---|
| 缩略图 | 文件名 + meta + 可选提示 | 状态 + 下载 / 删除 |

硬规则：

- 缩略图尺寸统一
- 文件名单行截断
- meta 使用超轻 overline 体系，不做彩色 badge 堆叠
- 压缩后大小用绿色强调，但仍属于 meta 体系
- `READY` 是右侧小标签，不是正文文案
- 冗长完成说明折叠到感叹号 tooltip 中
- hover 只提高按钮显隐，不改变整体排布

扩展方式：

- 新工具可以往 meta 里增加 1~3 个关键信息，如尺寸、页数、颜色数、输出格式
- 不允许把一行塞成信息墙

### 9.8 ConfigHeader

右栏顶部固定是：

| 元素 | 说明 |
|---|---|
| icon | 与标题同色 |
| `CONFIGURATION` | 高字距全大写标题 |

规则：

- 位置独立于 header
- 永远是右栏自己的第一行
- 图片工作区和 PDF 工作区切换时，这一行不跳样

### 9.9 SettingsPanel

右栏是“固定容器 + 动态模块”。

固定骨架：

| 顺序 | 区块 |
|---|---|
| 1 | 配置标题 / 顶部切换项 |
| 2 | 各种参数模块 |
| 3 | 主操作按钮 |
| 4 | 次级补充块，如致谢 |

模块类型只允许以下几种：

- 分段按钮组
- 单值滑杆
- 可展开高级设置
- 单行说明
- 轻量状态标签

不建议：

- 大面积表单
- 复杂两列表单
- 深层嵌套折叠

### 9.10 SegmentedControl

适用于：

- 输出格式
- JPEG preset
- PNG mode
- Compression preset
- Result policy

规则：

- 外层是浅灰底容器
- 内层激活项是白底 + 轻阴影
- 默认 2~3 列
- 需要时可以单行 3 选项，不要无理由折到两行

### 9.11 RangeControl

适用于：

- Quality
- Raster DPI
- PNG threshold
- OxiPNG level
- Max dimension

结构固定为：

| 上 | 下 |
|---|---|
| label + value | track + fill + thumb |

规则：

- 所有滑杆必须同一套轨道语言
- value 永远右对齐
- 同类控制在图片和 PDF 工作区必须对齐

### 9.12 ActionStack

规则：

- 主按钮使用深色实体
- 次按钮使用浅底边框
- 文字全大写、小号、高字距
- 桌面端是竖排堆叠，移动端进入底部悬浮栏

### 9.13 MobileFabBar

规则：

- 只有移动端出现
- 默认两个按钮：设置 / 开始处理
- 有下载结果时变为三个按钮：设置 / 下载 ZIP / 开始处理
- 允许悬浮模糊背景，但不能盖住主要内容过多

### 9.14 CreditsPanel

这个区域是右栏尾部的独立补充卡，不属于主配置卡本身。

可承载：

- 致谢
- 编码器说明
- backend / local-only 状态
- 风险提醒

规则：

- 视觉比主配置卡更轻
- 标题仍走 overline 体系
- 内容可使用小胶囊

---

## 10. 交互与状态

### 10.1 状态语言

| 状态 | 表达方式 |
|---|---|
| Pending | `READY` 小标签 |
| Compressing | 转圈 icon |
| Completed | 成功 icon + 下载按钮 |
| Warning | 感叹号 tooltip |
| Error | 错误 icon + 短错误提示 |
| Cancelled | 警告态 icon |

规则：

- 状态优先靠位置和图标识别，不靠大段文字
- 成功说明尽量收起，避免队列变高
- 处理动画必须丝滑，不允许默认低质 spinner 破坏整体质感

### 10.2 动效规则

允许：

- icon 轻微 scale
- tooltip 淡入
- 激活态按钮轻微位移 / 阴影变化
- 列表 hover 透明度变化

禁止：

- 弹跳
- 果冻缩放
- 大幅度位移动画
- 长时间、与任务无关的装饰动效

---

## 11. 多语言规则

| 规则 | 说明 |
|---|---|
| 中文优先防炸版 | 英文一般更短，布局先按中文校验 |
| 英文 overline 可以更大字距 | 中文 overline 需要略收 |
| 中文标签优先简短 | 例如 `高级设置`，避免解释型长句进入主控件 |
| 文案分层不变 | 标题、提示、meta 三层语义不能因翻译打乱 |

---

## 12. 面向未来工具的扩展规则

### 12.1 什么必须复用

下面这些是家族级稳定资产：

| 模块 | 必须复用 |
|---|---|
| 页面外层、网格、左右区关系 | 是 |
| Header 标题 / tab / 语言切换 | 是 |
| Dropzone 基本骨架 | 是 |
| QueueList 骨架 | 是 |
| ConfigHeader | 是 |
| 分段按钮、滑杆、主次按钮 | 是 |
| 移动端底部悬浮栏 | 是 |
| Toast / tooltip / 状态标签体系 | 是 |

### 12.2 什么允许变化

| 模块 | 可变化内容 |
|---|---|
| 主标题 | 工具名 |
| tab | 工具分组或工作区数量 |
| Dropzone | 接受文件类型、提示文案、icon 语义 |
| WorkspaceCards | 摘要内容 |
| Queue meta | 文件格式、尺寸、页数、目标格式、耗时等 |
| SettingsPanel | 配置模块组合 |
| 主按钮文案 | `Compress` / `Convert` / `Export` / `Resize` 等 |
| 致谢区 | 当前工具依赖或提示信息 |

### 12.3 推荐的工具装配方式

未来新增工具时，优先按这套装配：

| 层 | 说明 |
|---|---|
| `FamilyShell` | 外层网格、头部、移动端框架 |
| `WorkspaceModule` | 左侧 drop + cards + queue |
| `ConfigModule` | 右侧参数组 |
| `ToolAdapter` | 当前工具自己的文案、accept、queue meta、处理逻辑 |

推荐抽象的配置对象：

| 字段 | 作用 |
|---|---|
| `toolId` | 工具唯一标识 |
| `title` | 页面主标题 |
| `tabs` | 工作区切换定义 |
| `dropzone` | 上传文案、accept、icon |
| `queueMeta` | 队列每行要显示什么 |
| `settingsSections` | 右栏模块列表 |
| `actions` | 主按钮、次按钮、下载按钮 |
| `credits` | 致谢区内容 |

---

## 13. 组件设计的禁止项

以下内容默认禁止：

| 禁止项 | 说明 |
|---|---|
| 新工具私自换一套 header 风格 | 会破坏家族统一 |
| 右栏重新做成营销式大卡片 | 偏离工具属性 |
| drop 和 queue 风格不一致 | 左栏必须像一个完整工作区 |
| 把所有状态写成长文 | 队列会变得很脏 |
| 小控件风格各自为政 | segmented、range、button 必须统一语法 |
| 移动端直接缩放桌面版 | 必须针对手机重排 |
| 横向溢出 | 属于严重失败 |
| 颜色过度装饰 | 这个家族不是用来秀视觉技巧的 |

---

## 14. Agent 执行规则

以后无论是 Stitch、Claude Code、Codex 还是别的 agent，在生成这条产品线的新页面时，都遵守下面这几条：

| 规则 | 说明 |
|---|---|
| 先保骨架，再换业务 | 先复用家族外壳，再填工具差异 |
| 优先复用已有组件，而不是新造视觉语言 | 保持同系识别度 |
| 视觉决策必须落到 token 和组件层 | 不接受只写“更高级、更精致” |
| 对齐参考站任务时，优先追源代码和截图 | 家族规则不能替代 1:1 还原任务 |
| 移动端必须单独检查 | 不允许桌面正确、手机爆版 |
| 中英双语必须同时成立 | 任何新增组件都要过双语检查 |

---

## 15. 维护方式

这份文件以后按下面方式维护：

| 场景 | 操作 |
|---|---|
| 家族视觉基线变化 | 直接更新本文件 |
| 新工具复用现有外壳 | 不改本文件，只按本文件执行 |
| 新工具出现稳定新组件 | 先在项目里验证，再补进本文件 |
| 用户要求 1:1 对齐具体参考站 | 在任务里记录“参考优先”，必要时回写本文件的共性部分 |

---

## 16. 当前 PixelSmall 的落地映射

这份文件当前已经映射到以下区域：

| 区域 | 当前文件 |
|---|---|
| 页面骨架与右栏结构 | `src/App.tsx` |
| 全局视觉令牌与组件样式 | `src/index.css` |
| Dropzone | `src/components/FileDropzone.tsx` |
| Queue | `src/components/QueueList.tsx` |
| Tabs | `src/components/WorkspaceTabs.tsx` |
| Toast | `src/components/ToastRegion.tsx` |
| 多语言文案 | `src/lib/copy.ts` |

如果未来要把这套家族真正组件化，优先拆的顺序是：

1. `HeaderShell`
2. `LocaleSwitch`
3. `SegmentedControl`
4. `RangeControl`
5. `SettingsPanel`
6. `ActionStack`
7. `MobileFabBar`

---

## 17. 最终定义

这条产品线不是“每次重新设计一个工具”，而是：

> 用同一套可信、克制、浏览器优先的设计语言，持续生成一组彼此像兄弟产品的文件处理工具。

以后任何新工具，只要还属于这条产品线，就默认先继承这份 `DESIGN.md`。