# Unity UI 组件设计原则

> 本文档依据视觉基准图 `Doc/Design/ui_design.jpg` 提炼，定义本项目休闲卡通风格 UI 的统一设计语言与各类 UGUI 控件的设计规范。
> 配套规范见 `Client/Assets/Doc/Rule/UnityProject.md`（制作流程、JSON→Prefab 管线）与 `Doc/Design/UI_Pic_Set.md`（通用控件切图清单）。
> 通用控件切图位于 `Assets/Game/Art/UI/Texture/Common`。

---

## 1. 总体视觉风格

休闲、友好、明快的卡通糖果风（casual candy style），强调“圆润、厚实、有光泽、易读”：

- **圆角厚实**：所有容器、按钮、控件均为大圆角矩形或胶囊形，无尖角；体块饱满，像玩具/糖果。
- **描边收边**：控件外缘有一圈比主体更深的同色系描边（约 2–4px），让控件从背景中“跳”出来。
- **顶部高光**：主体上半部有一道柔和的白色玻璃高光，营造塑料/糖果的反光质感。
- **柔和投影**：控件下方有短距离、低透明度的柔和阴影（非硬黑边），增强层次。
- **暖色容器 + 亮色控件**：面板多为奶油米色/浅蓝底，功能控件用高饱和糖果色点亮。
- **图标拟物 + 描边**：业务图标为有体积感的拟物卡通图标，统一带深色描边与高光。

设计目标：在手机小屏上**一眼可辨、点击区域明确、状态反馈清晰**。

---

## 2. 配色系统

以下为基准图取色（十六进制为参考值，允许 ±5% 微调；实际以切图为准）。

### 2.1 背景与容器

| 用途 | 颜色 | 参考值 |
| --- | --- | --- |
| 全局背景 | 浅蓝白 | `#EAF3F8` |
| 主面板底（奶油米） | 暖米色 | `#F6EBCF` |
| 面板描边（暖棕） | 棕 | `#C89B5C` |
| 浅蓝面板底 | 浅蓝 | `#DCEBF5` |
| 内容卡片底 | 近白 | `#FBF6E9` |
| 半透明遮罩 | 深蓝黑 | `#0B1724` @ 70–80% |

### 2.2 功能色（按钮/状态）

| 语义 | 主色 | 描边/按下态 | 用途 |
| --- | --- | --- | --- |
| 主操作 Primary | 草绿 `#7ED321` | 深绿 `#4E9A12` | 确定、开始、匹配等主行为 |
| 次操作 Secondary | 天蓝 `#43B7F5` | 深蓝 `#1E84C8` | 取消、次要行为 |
| 强调 Emphasis | 橙黄 `#FFB13C` | 深橙 `#E07C18` | 需要吸引注意但非危险 |
| 危险 Danger | 珊瑚红 `#FF5B5B` | 深红 `#D63333` | 删除、退出、警告 |
| 禁用 Disabled | 灰 `#B9C0C8` | 深灰 `#8A929B` | 不可点击 |
| 选中高亮 | 亮绿 `#9EEB3B` | — | 选中态染色/描边 |

### 2.3 文本色

| 用途 | 颜色 | 参考值 |
| --- | --- | --- |
| 深色正文（浅底上） | 深棕/深蓝灰 | `#5A4632` / `#33405E` |
| 浅色文字（按钮/深底上） | 近白 | `#F6F8FF` |
| 次要说明文字 | 蓝灰 | `#B7C2D8` |
| 数值高亮（金币/比分） | 金黄 | `#FFE27A` |
| 文字描边（统一） | 深蓝/深灰 | `#102033` / `#0B1724`（**不使用纯黑**） |

### 2.4 图标点缀色

金币金 `#F5C033`、钻石蓝 `#46C8E6`、生命红 `#FF6B83`、能量绿 `#7ED321`、星黄 `#FFD54A`、防具蓝 `#5B8FE6`，整体保持高饱和、同族描边。

---

## 3. 形状语言（圆角 / 描边 / 高光 / 阴影）

| 要素 | 规范 |
| --- | --- |
| 圆角 | 按钮/卡片圆角半径约为短边的 25–40%；胶囊控件（开关、进度条、滑条）为全圆端。 |
| 描边 | 外描边宽度 2–4px，颜色为主体色加深约 20–30%；描边随控件等比，不随九宫格拉伸变形（见第 8 节）。 |
| 高光 | 主体上半部一道柔和白色高光（透明度 30–60%），覆盖上 40% 区域，向下渐隐。 |
| 阴影 | 投影偏移 `(0, -6 ~ -8)`，颜色 `#06101F` @ 70–80%，软边；用 UGUI `Shadow` 组件实现。 |
| 内凹 | 进度条/滑条/输入框的“槽”为内凹深色底，填充为带高光的亮色，形成凹凸对比。 |

---

## 4. 字体与可读性

- 统一使用 **TextMeshPro**（`TextMeshProUGUI` / `TMP_InputField` / `TMP_Dropdown`），默认字体思源黑体 CN Regular（`Assets/Game/Art/UI/Font/SourceHanSansCN-Regular.otf` 的 SDF 资源）。
- **字号层级**（2048×1024 设计分辨率参考）：界面标题 36–40；区块标题 28–32；按钮文字 24–30；正文/列表 20–24；说明/次要 18–20；大数值（比分等）64–80。
- **字重**：标题、按钮、状态、倒计时用 Bold；正文用 Regular。
- **可读性**（与 `UnityProject.md` 第 38–40 条一致）：
  - 浅色文字位于图片背景、高饱和按钮、半透明面板上时，**必须**加深蓝/深灰描边或阴影（`#102033` / `#0B1724`），描边宽度保持轻量，避免粗黑边弄脏画面。
  - 普通正文、列表、输入框文本优先靠背景对比度保证可读，不默认加描边。
  - 深底面板放浅色字、浅底面板放深色字；避免浅色字直接压在浅底上。

---

## 5. 各控件设计原则

### 5.1 面板 / 弹窗 (Panel)

- 结构：标题栏（深色木纹/蓝色横幅）+ 内容区（奶油米底）+ 操作区（底部按钮）。
- 弹窗右上角固定圆形关闭按钮（红色 `btn_close`）；模态弹窗下方铺半透明遮罩拦截点击。
- 切图：`ui_panel_main`（主窗）、`ui_panel_popup`（弹窗）、`ui_panel_content`（内容卡）、`ui_panel_header`（标题栏）、`ui_panel_tooltip`（提示），均为 **九宫格 Sliced**。
- 内容区四周留白≥24px；标题居中或左对齐配图标。

### 5.2 按钮 (Button)

- 四种语义色：主(绿)/次(蓝)/强调(橙)/危险(红)，外形一致仅配色不同。
- **必须实现完整状态**（`Button` + SpriteSwap，见第 7 节）：Normal / Highlighted(Hover) / Pressed / Disabled。
- 按下态：颜色加深 + 视觉下沉（高光减弱、整体下移 1–2px 的观感）。
- 文字白色 + 轻描边；带图标时图标在左、文字居中或图标在上文字在下。
- 尺寸：主按钮高度≥72（设计分辨率），点击热区不小于可视区；小按钮成组排列。
- 切图：`btn_primary_*`、`btn_secondary_*`、`btn_warning_*`、`btn_small_*`、圆形 `btn_close`/`btn_back`/`btn_home`。

### 5.3 输入框 (TMP_InputField)

- 浅蓝/白圆角底，内凹观感；左侧可选图标，右侧可选功能图标（编辑/搜索/清空）。
- 必须声明 `placeholder`、`characterLimit`、`contentType`（密码用 `Password`）。
- 占位符用次要蓝灰色 `#B7C2D8`；输入文本用深色，靠背景对比保证可读，不加描边。
- 切图：`input_bg_normal` / `input_bg_focus` / `input_bg_error`，光标 `input_caret`。

### 5.4 下拉框 (TMP_Dropdown)

- 暖黄/白圆角底，右侧朝下三角箭头 `dropdown_arrow`。
- 展开列表复用列表项样式（见 5.8）。切图 `dropdown_bg`。

### 5.5 数值步进器 (Stepper)

- 形式：`[ − ]  数值  [ + ]`，减号红圆按钮、加号绿圆按钮，中间数值居中。
- 复用 `ico_minus`/`ico_plus` 圆形按钮 + 输入/显示框。

### 5.6 进度条 (Progress)

- 内凹深色底槽 + 高光亮色填充（绿/蓝/橙），全圆端胶囊形。
- 左端可挂圆形图标徽章，填充上叠加数值文本（如 `350/500`、`80%`），文本白色加轻描边。
- 切图：`progress_bg` + `progress_fill_*`，填充用 **Filled 或 Sliced**；脚本驱动时按 `sizeDelta.x` 或 `fillAmount` 改变。

### 5.7 滑动条 (Slider)

- 内凹轨道 + 亮色已填充段 + 圆形拖拽手柄（白/蓝带高光）。
- 左侧图标说明（音量/音乐/亮度），右侧显示百分比。
- 切图：`slider_track` / `slider_fill` / `slider_handle`。

### 5.8 滚动列表与滚动条 (ScrollView / Scrollbar)

- 列表项：奶油米圆角卡片，左图标 + 主标题 + 次要描述 + 右侧 chevron 箭头。
- 列表项状态：普通 `ui_list_item_normal`、选中 `ui_list_item_selected`、禁用 `ui_list_item_disabled`（均九宫格）。
- 滚动条：内凹轨道 `scrollbar_track_*` + 亮蓝滑块 `scrollbar_thumb_*`，全圆端。
- 内容用 `VerticalLayoutGroup` + `ContentSizeFitter`，视口用 `RectMask2D` 裁剪。

### 5.9 开关 / 勾选 / 单选 (Toggle / Checkbox / Radio)

- 开关：胶囊轨道（开=绿 `toggle_bg_on` / 关=灰 `toggle_bg_off`）+ 白色圆形滑块 `toggle_knob`，配 开/关 文案。
- 复选框：`checkbox_off` / `checkbox_on`（圆角方形 + 对勾）；单选：`radio_off` / `radio_on`（圆形 + 实心点）。

### 5.10 页签 (Tab)

- 选中态高亮（蓝）凸起 `tab_active`，未选中态浅色下沉 `tab_inactive`；选中页签与内容区无缝相连。
- 分段控件用 `seg_left` / `seg_mid` / `seg_right` 拼接。

### 5.11 角标 / 徽章 (Badge)

- 图标按钮右上角红色圆形数字角标（未读/数量），切图 `ui_badge_alert`（红点/提醒）、`ui_badge_base`（普通）。
- 角标数字白色加粗；红点用于“有更新”无数字场景。

### 5.12 业务图标 (Icon)

- 拟物卡通 + 统一深色描边 + 高光；尺寸基准 64×64，重要图标可放大。
- 常用：货币 `ico_coin`、钻石 `ico_diamond`、生命 `ico_heart`、能量、星级 `ico_star`、防具 `ico_shield`、武器 `ico_sword`、背包 `ico_bag`、地图 `ico_map`、钥匙 `ico_key`、设置 `ico_settings` 等。
- 图标槽/道具格用 `slot_empty` / `slot_selected` / `slot_locked`（九宫格）。

### 5.13 资源/货币条 (Currency)

- 形式：圆形货币图标 + 数值（金黄高亮）+ 末尾绿色加号按钮（前往充值/获取）。
- 数值用千分位，居中垂直对齐图标。

### 5.14 头像 / 玩家卡 (Avatar)

- 圆形头像框 `avatar_frame` + 等级角标 + 昵称 + 经验进度条（如 `870/1500`）。

### 5.15 底部导航 (Bottom Nav)

- 一排图标按钮（首页/背包/任务/商店/设置），当前页高亮（凸起蓝底 + 图标点亮），其余浅色。
- 当前项放大并加底色块区分。

---

## 6. 状态与反馈

每个可交互控件至少定义以下状态，保证“可点、已选、不可点”一目了然：

| 状态 | 表现 |
| --- | --- |
| Normal | 默认色 + 高光 + 描边 |
| Highlighted/Hover | 整体提亮（更亮/更饱和） |
| Pressed | 加深 + 下沉，高光减弱 |
| Disabled | 去饱和转灰 + 降透明，无高光 |
| Selected/Active | 选中色描边或染色（亮绿 `#9EEB3B`），或凸起 |

- 按钮优先用 **SpriteSwap**（不同状态用不同切图）；无专用切图时退化为 ColorTint。
- 选中反馈可叠加：背景换图 + 文字变色/加粗（如列表当前项）。
- 关键操作（确定/危险）给与即时视觉与（可选）音效反馈。

---

## 7. 与 Unity 实现的衔接

- 控件优先复用 `Assets/Game/Art/UI/Texture/Common` 通用切图；缺图时用 gptimage2 按本风格生成到该目录（见 `UnityProject.md` 第 6 条）。
- 新界面按 **JSON→Prefab 管线**：在 `Doc/UIPrefabCreater/` 写界面描述 JSON，Unity 自动生成 Prefab（`UnityProject.md` 第 26–46 条）。
- 文本控件统一 TextMeshPro；按钮 `transition` 优先 `SpriteSwap`；九宫格图片声明 `"imageType": "Sliced"`，进度填充可用 `"Filled"`。
- 按钮 SpriteSwap 状态对应切图：`*_normal`(Target) / `*_hover`(Highlighted) / `*_pressed`(Pressed) / `*_disabled`(Disabled)。

---

## 8. 九宫格与间距

- **九宫格 (Sliced)**：所有可拉伸容器（面板、按钮、输入框、进度条、列表项等）必须设置正确的 `Border`，保证圆角与描边在任意尺寸下不变形；`Border` 值参考 `Doc/UI_Pic_Set.md` 各切片。
- 导入设置：Texture Type = `Sprite (2D and UI)`，勾选 `Alpha Is Transparency`，Mesh Type = `Full Rect`，Filter = Bilinear。
- **间距节奏**：统一使用 8 的倍数（8 / 16 / 24 / 32）。控件内边距≥16，区块间距≥24，安全区四周≥24。
- 切图四周保留约 2px 透明边，避免双线性采样串色（项目切图已统一处理）。

---

## 9. 分辨率与适配

- 设计分辨率 **2048×1024**（`CanvasScaler` = ScaleWithScreenSize，referenceResolution `[2048,1024]`，Match = 0.5）。
- 布局以锚点为主：全屏元素用拉伸锚点；角标/悬浮按钮锚到对应屏幕角；主面板居中。
- 关键信息放安全区内，避免刘海/圆角遮挡；考虑长宽比从 4:3 到 20:9 的适配。
- 重要图标与文字用 `None`/`High Quality` 压缩，避免边缘与文字出现压缩噪点。

---

## 10. 设计检查清单（提交前自检）

- [ ] 配色取自第 2 节调色板，语义色使用正确（绿=主/蓝=次/橙=强调/红=危险）。
- [ ] 控件有圆角 + 描边 + 高光 + 柔和阴影，风格与 `ui_design.jpg` 一致。
- [ ] 可交互控件具备 Normal/Hover/Pressed/Disabled（必要时 Selected）状态。
- [ ] 文字用 TMP；浅色字在复杂/高饱和/深底上加了深蓝灰描边；深浅对比充足。
- [ ] 可拉伸控件设置了正确的九宫格 Border，任意尺寸不变形。
- [ ] 间距为 8 的倍数；点击热区足够大。
- [ ] referenceResolution = [2048,1024]，锚点适配多分辨率。
- [ ] 复用 Common 通用切图；新图按本风格用 gptimage2 生成到对应目录。