# Hello UI

> 已进入显式 UI 工作流、宿主全局模式下的 UI 任务、已初始化项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 基线之上补充项目契约执行、设计系统映射与视觉验证。

- Skill: `hellowind777/hello-ui` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hellowind777/hello-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hellowind777/hello-ui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: hellowind777 (https://skillmd.com/u/hellowind777)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hellowind777/hello-ui

---


本 skill 不是 UI 质量的唯一来源。当前已加载的 HelloAGENTS UI 质量基线负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流、宿主全局模式和复杂 UI 任务中，补充更明确的契约执行、实现映射与视觉验收。
`.helloagents/` 在本 skill 中统一按项目级存储路径理解：会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录解析。

## 适用边界
已进入显式 UI 规划/实现/验证路径、宿主全局模式下的 UI 任务，或当前已初始化项目且任务涉及整页新建、跨多个组件的视觉重做、设计系统改造、需要截图验收的界面任务时，读取本 skill。
标准模式、且项目未初始化时的普通 UI 请求，仍只受当前已加载的 HelloAGENTS UI 质量基线约束；修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不读取本 skill。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。

## 设计契约优先级
进入 UI 相关的规划、实现、验证时，按以下顺序做设计决策：
1. 当前活跃方案包 `plan.md` 或 PRD 中已确认的 UI 决策
2. `.helloagents/DESIGN.md`（按当前项目存储模式解析）
3. 已读取的本 skill 具体 UI 审美与实现规则
所有 UI 任务都必须满足 UI 质量基线；缺少上层产物时，才直接依赖下层规则；不得用通用审美覆盖已确认的项目契约。

## 核心职责
- 遵循上游契约：把 `plan.md` / PRD / `DESIGN.md` 中已确认的 UI 决策视为强约束，而不是建议
- 处理可选 UI 契约：若 `contract.json` 启用 `ui.styleAdvisor`，复用当前会话 `artifacts/advisor.json` 记录设计方向复查证据；若启用 `ui.visualValidation`，用当前会话 `artifacts/visual.json` 记录视觉验收证据
- 映射到代码结构：明确 token 放在哪里、组件边界如何划分、状态组件如何组织、动效与主题如何实现
- 做视觉验收闭环：优先使用截图/浏览器工具做桌面与移动端检查；没有工具时也要完成结构化视觉自检
- 回写稳定决策：只把跨 feature 稳定成立的设计系统规则同步回 `.helloagents/DESIGN.md`（按当前项目存储模式解析），不要把一次性页面细节全部写成项目级契约

## 设计简报（编码前必须明确）

先理解上下文，再做出大胆且有意图的设计决策：

1. 目的：这个界面解决什么问题？谁在用？什么场景？什么平台？
2. 美学方向：选择一个鲜明的方向并坚持到底。不套用固定风格标签，而是根据项目的受众、场景和情感目标，创造一个忠于上下文的独特风格。先问清楚：这个产品的用户期待什么情绪？什么视觉语言能传达这种情绪？
3. 记忆点：用户看到这个设计会记住的一个特征是什么？
4. 差异化：当任务明确要求探索，或缺少现成设计约束时，主动避免滑入常见默认风格；差异化必须服务产品语义、品牌边界与可用性，不为变化而变化。
5. 设计 token：尽早建立变量/token 体系——背景色/表面色/主色/弱化色/强调色 + 展示/标题/正文/说明文字的字体角色。Web 用 CSS 变量，桌面/移动端用平台对应的主题系统。
6. 约束定义：为当前项目定义具体约束（如最多几个区块、几种字体、几个强调色、首屏的 CTA 数量），用约束帮助释放创意。
7. 真实内容：使用真实文案、产品信息、项目上下文，不使用 Lorem ipsum 或泛化占位符。真实内容更容易帮助做出更贴合上下文的设计决策。

执行顺序要求：
- 当前项目已有本地项目存储且存在 `.helloagents/DESIGN.md`（按当前项目存储模式解析）时，进入真实 UI 任务先读取它，再展开方案或实现
- 已通过方案包或 PRD 确认设计方向的，按确认方向执行，并以 `plan.md` / PRD 中的 UI 决策为最高优先级
- 当前项目已有本地项目存储，且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但 `.helloagents/DESIGN.md`（按当前项目存储模式解析）不存在时，先按 `templates/DESIGN.md` 创建最小设计契约（至少覆盖产品表面、设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项），再继续大规模实现
- 未经方案包且无 `DESIGN.md` 的任务，基于以上规则，结合任务需求和项目上下文做出设计决策并执行

## 实现映射（进入编码前必须明确）
- token 落点：颜色、字体、间距、圆角、阴影、动效参数分别落在哪个 token / theme 文件
- 组件边界：哪些能力做成复用组件，哪些只保留在当前页面；避免把一次性布局抽成错误的“通用组件”
- 状态矩阵：当前界面涉及的加载、空、错误、成功、禁用、危险态分别如何呈现
- 主题与适配：深浅色、响应式断点或平台尺寸、安全区、最小窗口/最小视口如何处理
- 验收证据：本次需要检查的关键视口、关键状态和关键截图点是什么

## 结构性规则

以下规则关于构图和信息架构，按页面类型适用。

### 展示型页面（着陆页、营销页、产品展示页）

第一屏构图：
- 第一屏必须是一个完整构图，品牌/产品名必须是最明显的识别点
- 品牌测试：如果去掉导航栏后第一屏可以属于任何品牌，说明品牌感太弱

Hero 区域：
- Hero 图必须是边到边的主视觉平面或背景
- Hero 预算：第一屏通常只放品牌、一个标题、一句支撑文案、一组 CTA、一张主图
- 不在 hero 区域放次要内容，不在 hero 媒体上叠加浮动元素

页面叙事：
- Hero — 建立身份和承诺
- 支撑图像 — 展示上下文或环境
- 产品细节 — 解释产品/服务
- 社会证明 — 建立可信度
- 最终 CTA — 将兴趣转化为行动

### 应用型页面（Dashboard、管理后台、工具型应用）

- 信息密度优先：高效展示数据，合理利用空间
- 清晰的导航层级：主导航/侧边栏/面包屑让用户始终知道自己在哪
- 操作可发现性：关键操作显眼可达，次要操作收入菜单
- 状态一目了然：用颜色/图标/徽章传达状态，减少用户认知负担

### 通用规则（所有页面类型）

- 卡片克制：默认不用卡片，卡片仅在作为交互容器时使用。去掉边框/阴影/背景/圆角后不影响理解的就不应该是卡片
- 区块纪律：每个区块只做一件事，避免堆砌标签集群、统计条、图标行、多个竞争文本块
- 真实视觉重点：图像应展示产品、场所、氛围或上下文，装饰性渐变和抽象背景不算主视觉

## 视觉执行

### 字体
选择有表现力、有目的的字体。展示字体与正文字体配对要有对比（衬线+无衬线，或粗+细）。避免默认字体栈。优先考虑可变字体（减少请求数、支持精细调节）和当前流行的高质量字体。

### 配色
选择清晰的视觉方向，用 token 体系建立一致性。大胆的主色 + 锐利的强调色，优于胆怯的均匀分配。暗色主题使用降低饱和度的色调变体，不是简单反转。优先使用感知均匀的色彩空间（如 OKLCH）生成和谐的色阶。

### 布局
有意识的空间运用。非对称、重叠、对角线流动、破格元素都是好工具。建立一致的间距系统，保持全局节奏。优先使用目标平台当前最新的布局能力实现响应式设计。

### 动效
用动效创造存在感和层次，不是噪音。一个精心编排的入场动画（带交错延迟）优于散落的微交互。时长参考：即时反馈 < 100ms，微交互 150-300ms，复杂过渡 ≤400ms。至少 2-3 个有意图的动效。动画必须可中断，不阻塞用户输入。支持减弱动效偏好设置。优先使用平台原生动画能力，复杂场景再引入动画库。

### 氛围与纹理
不依赖纯色背景。渐变网格、噪点纹理、几何图案、透明叠层、戏剧性阴影、颗粒覆盖——选择匹配整体美学的手法营造纵深感。

## 实现标准

### 可访问性（最高优先级，所有平台）
- 颜色对比度 ≥ 4.5:1（正文），≥ 3:1（大文本）
- 所有交互元素支持键盘/辅助技术操作
- 不仅靠颜色传达信息（加图标或文字）
- 支持系统级减弱动效设置
- Web：语义化 HTML、aria-label、可见焦点环
- 桌面/移动端：使用平台原生无障碍 API（VoiceOver/TalkBack/Narrator）

### 响应与适配
- Web：根据产品的主要使用场景确定首要目标视口（桌面端产品以桌面为主设计，移动端产品以移动为主设计），然后适配其他视口。优先使用组件级响应式而非仅依赖视口断点，确保所有目标视口都能正常使用
- 桌面应用：支持窗口自由缩放，合理的最小窗口尺寸，内容自适应
- 移动应用：适配不同屏幕尺寸，尊重安全区域（刘海/手势条），支持横竖屏
- 通用：正文最小 16px/pt，触摸/点击目标 ≥ 44px/pt

### 交互反馈
- 加载状态：骨架屏 > spinner > 空白等待
- 空状态、加载态、错误态都要有对应 UI
- 移动端：合理使用触觉反馈（确认操作、重要动作）
- 桌面端：支持常用键盘快捷键

### 平台惯例
- Web：优先平台原生动画能力（CSS 动画、原生过渡 API），复杂场景再引入动画库
- iOS：遵循 HIG（底部 Tab Bar、滑动返回、Dynamic Type）
- Android：遵循 Material Design（顶部 App Bar、涟漪反馈、预测性返回）
- 桌面：遵循平台原生控件风格，除非品牌需要自定义
- 游戏 UI：优先可读性和操作效率，HUD 不遮挡核心内容
- 通用：查阅目标平台当前最新的设计指南和 API，不依赖旧版本知识

### 表单
- 每个输入框必须有可见 label
- 错误信息紧挨字段显示
- 失焦时验证
- 提交时：按钮禁用 + 加载指示 + 成功/失败反馈
- 长表单自动保存草稿，多步表单显示进度指示器
- 破坏性操作使用语义危险色并与常规操作视觉分离

### 图表与数据可视化
- 图表类型匹配数据类型（趋势→折线、对比→柱状、占比→饼图/环形图）
- 提供图例和交互 tooltip
- 使用无障碍配色（不仅靠颜色区分数据，辅以图案或标签）
- 大数据集使用虚拟滚动或聚合展示

## 交互逻辑

### 状态完整性
每个异步操作必须覆盖四种状态：加载中、成功、错误、空数据。缺少任何一种都是交互缺陷。错误信息必须具体且可操作（说明原因 + 如何修复），不接受"出错了"这类泛化提示。

### 焦点管理
- 焦点永远不能消失或被意外困住
- Tab/Shift+Tab 在控件间移动，方向键在复合控件内部导航
- 模态框打开时焦点困在内部，关闭后焦点回到触发元素
- 页面/路由切换后焦点移到主内容区域
- 提交出错后焦点自动移到第一个错误字段

### 模态框与对话框
- 仅在需要中断用户流程时使用，不用于展示非关键信息
- 必须支持 Escape 关闭，有明确的关闭/取消入口
- 不嵌套模态框
- 有未保存内容时关闭前确认

### 导航
- 用户始终知道自己在哪（高亮当前位置、面包屑、标题）
- 返回行为可预测且一致，保留滚动位置和筛选状态
- 主导航在深层页面仍可达
- 破坏性操作（删除账号、登出）与常规导航项视觉和空间分离

### 列表与数据
- 分页适合比较/定位场景，无限滚动适合发现/浏览场景
- 搜索框在内容密集型应用中必须显眼可达
- 筛选器随查询上下文动态调整（禁用零结果的选项）
- 可排序表格标注当前排序状态

### 渐进式披露
- 复杂功能分步展示，不一次性呈现所有选项
- 高级设置折叠或收入二级入口
- 引导新用户逐步发现功能，而非一次性展示全部

## 复杂度匹配

实现复杂度必须匹配设计目标。需要强表现力的界面，可以用更丰富的实现；需要克制的界面，就保持简洁和精确。不要为了效果堆效果，也不要为了求稳把设计做平，而是根据上下文做出意外但合理的选择——展现真正的创造力。

## 交付检查

### 清单
- [ ] 字体：有表现力，配对有对比
- [ ] 配色：有凝聚力的色彩体系，token 一致
- [ ] 构图：首屏完整，品牌感强（展示型页面）/ 信息层级清晰（应用型页面）
- [ ] 结构：区块职责单一，整体有节奏
- [ ] 动效：至少 2-3 个有意图的动效，可中断，尊重减弱动效设置
- [ ] 氛围：背景有纵深感
- [ ] 记忆点：有一个让人记住的设计特征
- [ ] 契约一致性：已确认的 `plan.md` / PRD / `DESIGN.md` 决策与实现一致；新增稳定设计决策已同步回 `DESIGN.md`
- [ ] 状态覆盖：每个异步操作都有加载/成功/错误/空状态
- [ ] 焦点管理：Tab 顺序合理，模态框焦点困住，关闭后焦点回到触发元素
- [ ] 可访问性：对比度达标，辅助技术可用
- [ ] 适配：目标平台上正常使用
- [ ] 技术现代性：使用的技术方案符合 HelloAGENTS 技术选型原则与工程质量下限；若当前模式未加载实现要求中的工程质量下限，则至少满足技术选型原则且无过时依赖
- [ ] 未使用当前已加载的 HelloAGENTS 规则明确禁止的过时模式；若当前模式未加载该章节，则至少避免紫色渐变默认配色、白底卡片堆砌、默认字体栈、emoji 图标等已列出的过时模式

### 设计自评
对以下维度各打 1-10 分，低于 8 分的维度必须迭代改进：
- 字体表现力与配对质量
- 配色凝聚力与品牌感
- 构图与视觉层次
- 动效意图性与流畅度
- 整体氛围与记忆点
- 技术现代性与性能表现

3-5 轮迭代后仍低于 8 分的维度，记录原因并与用户讨论。

### 视觉自检
如果有浏览器工具可用（Playwright MCP 等）：
1. 截图渲染结果（桌面 + 移动端视口）
2. 对照设计原则审查截图：构图是否完整？品牌感是否到位？配色是否一致？
3. 发现问题 → 修复 → 再截图验证
4. 若当前契约要求 `ui.visualValidation.required=true`，调用 `scripts/visual-state.mjs write` 写当前会话 `artifacts/visual.json`，记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status` 与 `summary`
5. 确认截图与设计意图一致后才能报告完成

无浏览器工具时，仔细审查生成的代码，确认样式、布局、动效的实现与设计意图一致。
若当前契约要求 `ui.visualValidation.required=true`，仍需用结构化结论调用 `scripts/visual-state.mjs write` 写当前会话 `artifacts/visual.json`，并明确标记所用 tooling 与已检查的 screens / states。