hello-ui

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

适用边界

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

设计契约优先级

进入 UI 相关的规划、实现、验证时，按以下顺序做设计决策：

当前活跃方案包 plan.md 或 PRD 中已确认的 UI 决策
.helloagents/DESIGN.md（按当前项目存储模式解析）
已读取的本 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（按当前项目存储模式解析），不要把一次性页面细节全部写成项目级契约

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

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

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

列表与数据

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

渐进式披露

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

复杂度匹配

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

交付检查

清单

设计自评

对以下维度各打 1-10 分，低于 8 分的维度必须迭代改进：

字体表现力与配对质量
配色凝聚力与品牌感
构图与视觉层次
动效意图性与流畅度
整体氛围与记忆点
技术现代性与性能表现

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

视觉自检

如果有浏览器工具可用（Playwright MCP 等）：

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

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