harmonyos-design

name	harmonyos-design
description	审视、设计、从零启动或改进 HarmonyOS、OpenHarmony 与 ArkUI 产品界面。用于检查 ArkTS UI、建立新项目设计基线、区分永恒原则与当前平台视觉语言、规划跨手机/平板/折叠屏/PC 的导航和布局、多输入控件状态、animateTo、transition、geometryTransition、springMotion、手势跟手与可打断动效、异步状态真实性、视觉分层参数、无障碍或动画性能，或建立鸿蒙 Motion Token 时。不要用于签名、构建、网络、存储、权限、数据库等纯工程问题，也不要用于通用视频剪辑或其他移动平台的设计规范评审。
metadata	{"version":"1.0.0","status":"draft"}

HarmonyOS Design

把公开的 HarmonyOS / OpenHarmony 设计原则和 ArkUI 能力，转化为可执行、可验证、可追溯的产品判断。

核心命题：

一致而不相同，连续而不阻塞，反馈即时但状态真实；基础原则持久、平台表现版本化；系统优先且证据可追溯。

本 Skill 是独立、非官方工具。不要把项目建议说成华为官方规定。

1. 先确定入口与工作模式

先判断任务属于：

• 新项目启动：尚未形成稳定界面，需要先建立上下文、原则、平台版本、项目人格、原型和验收基线；
• 现有项目审视：已有代码、截图、录屏或设计稿，需要基于证据找问题并给出最小修复。

再根据用户意图选择一种主模式。不要同时输出三套重复内容。

设计模式

用于从需求或草图建立方案。新项目启动时输出：

1. Product Context Card；
2. Evergreen Principle Baseline；
3. Platform Version Profile；
4. Project Personality Overlay；
5. 任务、信息架构与导航；
6. 设备、窗口、输入与适配策略；
7. 控件状态、视觉与 Motion Token；
8. 异步状态与动效；
9. 无障碍和性能预算；
10. First Interactive Prototype Plan；
11. Acceptance Matrix。

实现模式

用于把明确方案翻译为 ArkTS / ArkUI。输出：

1. 文件和组件清单；
2. 系统能力与自定义边界；
3. Token / Modifier 方案；
4. ArkUI API 落点；
5. 改动顺序；
6. 构建、真机、性能和无障碍验证；
7. 回滚和未验证项。

默认先给计划。除非用户明确要求并提供工程，不要直接批量改代码。

审视模式

用于审查代码、截图、录屏、设计稿或现有产品。默认严格，只报告有证据的问题，不为“显得全面”制造发现。

输出必须符合“第 11 节”。

2. 建立上下文卡

先复用用户已提供的信息。只有缺失会实质改变结论时才提问；最多询问五项。无法确认时写入“假设”，不要静默套用手机端规则。

目标设备:
窗口形态:
主要输入:
API_Level:
主题与字号:
无障碍状态:
任务入口:
任务模式:
平台版本档案:
项目人格:
可用证据:
假设:

至少考虑：

• 设备：手机、折叠屏、平板、PC、穿戴、智慧屏、车机；
• 窗口：全屏、分屏、自由窗口、横竖屏；
• 输入：触摸、手写笔、鼠标、触控板、键盘、遥控器、旋钮、语音；
• 主题：浅色、深色、高对比；
• 字号：默认和放大；
• 语言方向和文本长度；
• 目标 SDK/API。

需要详细适配规则时读取 references/ADAPTATION.md。

3. 来源和措辞

对每条重要判断标注来源等级：

等级	含义	允许的措辞
H1	华为官方 HarmonyOS 文档	“华为官方文档要求/建议”，需注明版本
H2	OpenHarmony 官方 UX / ArkUI 文档	“OpenHarmony 官方文档要求/建议”
H3	官方样例、系统应用或演讲观察	“观察到的官方模式”
H4	跨平台经验或项目偏好	“项目建议 / House Style”

规则没有来源时标记“待验证”，不要用权威语气补全。

数值必须区分：

• 官方强制；
• 官方参考；
• ArkUI 默认；
• 观察值；
• House Style。

截图中的 0.97 按压缩放属于参考项目风格，不是已验证的 HarmonyOS 官方值。

完整来源见 references/SOURCES.md。

3.1 知识分层

每个结论都先判断属于哪一层：

层	内容	处理方式
Evergreen Foundation	反馈、因果、连续性、层级、可读性、无障碍、状态真实性	不因视觉趋势轻易修改
Versioned Platform Layer	当前 HarmonyOS/OpenHarmony/ArkUI 组件、视觉语言、API 和默认行为	标目标版本、设备和核验日期
Project Overlay	品牌、业务风险、产品性格与 House Style	不得伪装成官方

当前视觉语言可以改变材质、形态和组件表现，但不能自动覆盖方向感、可访问性、状态真实性和任务清晰度；旧原则也不能成为拒绝新平台能力的理由。

机器规则使用：

stability: evergreen | versioned | experimental
design_layer: foundation | platform | project

4. 审视顺序

始终按以下顺序。上游问题未解决时，不优先美化下游动画。

1. 用户任务是否清晰；
2. 信息架构与导航是否可理解；
3. 设备、窗口和输入是否适配；
4. 控件状态和反馈是否完整；
5. 视觉 Token、字体和信息层级；
6. 动效是否有目的、连续并表达关系；
7. 无障碍；
8. 性能；
9. 品牌效果是否克制。

核心原则详见 references/PRINCIPLES.md。

5. 不可妥协的检查

5.0 不用最新视觉趋势推翻稳定原则

• 先识别变化属于材质、组件、API 还是基础交互。
• 新视觉语言必须经过对比度、焦点、动态字体、状态真实性和性能检查。
• 不因“最新”“高级”“像系统”统一覆盖所有产品。
• 不因资料年份较早就否定仍可被真实交互验证的原则。

5.1 系统能力优先

• 先检查系统控件是否已经提供所需状态、动效和无障碍。
• 自定义不能削弱按压、焦点、悬停、禁用、选中和读屏语义。
• 不要为了“统一”覆盖所有系统默认动画。
• 不要发明 ArkUI API。

5.2 导航必须可解释

用户应知道：

• 身处何处；
• 可以去哪里；
• 操作后会到哪里；
• 如何返回。

检查同层、上下层和跨应用关系。平板/PC 可把手机父子页面改成分栏；不要只放大手机页面。

5.3 布局必须适配，而非等比缩放

明确选择一种或多种策略：

• 拉伸、均分、占比、缩放；
• 延伸、隐藏、折行；
• 缩进、挪移、重复、分栏；
• 导航形态转换。

阻断明显截断、变形、过多空白、过度拥挤和大字体错乱。

5.4 输入与状态完整

在适用设备检查：

• 正常；
• 禁用；
• 按下；
• 焦点；
• 激活；
• 悬停。

长按发现性差，不承载没有替代入口的高频核心功能。键鼠、遥控器和旋钮需要相应焦点和快捷路径。

5.5 反馈立即且连续

• 点击在按下时给出反馈，不等待抬起后才变化。
• 拖拽、滑动、捏合在跟手阶段持续响应。
• 离手动画从当前显示状态继续，不从逻辑目标或零速度重启。
• 新意图出现时允许动画被打断和重定向。
• 快速连续操作不得锁住输入。

5.6 动效必须表达任务

每个动效回答：

1. 它反馈了什么？
2. 它说明了什么层级或空间关系？
3. 去掉后是否损害理解？
4. 触发频率多高？
5. 是否手势驱动？
6. 是否有低运动替代？

没有明确目的时，优先删除。

5.7 可访问是默认要求

检查：

• 非文本交互元素有简洁语义；
• 角色、选中/勾选状态准确；
• 分组和焦点顺序符合任务；
• 大字体不破坏布局；
• 颜色不是唯一状态信号；
• 动效有温和替代；
• 自绘组件提供必要虚拟无障碍节点。

详见 references/ACCESSIBILITY.md。

5.8 性能属于设计质量

• 优先系统动画 API。
• 出现/消失优先考虑 transition。
• 高频位置或大小变化优先图形变换，避免持续重新布局。
• 相同参数的状态变化尽量合并。
• 真机验证帧率、长帧和快速连续操作。
• 构建成功不等于体验通过。

6. 动效决策

需要完整细节时读取 references/MOTION.md。

6.1 是否使用弹性曲线

使用弹性曲线：

• 手势跟手；
• 拖拽释放；
• 需要速度继承；
• 目标会连续变化；
• 明确的物理回稳。

优先非弹性曲线：

• 简单颜色变化；
• 非手势的小型状态淡入淡出；
• 不需要弹性、速度和打断的短过渡。

不要仅因“更活泼”加入弹跳。大面积、多次振荡容易干扰。

6.2 公开参考时长

以下是 OpenHarmony 公开设计参考，不是所有场景的绝对规则：

场景	参考
简单颜色变化	约 100ms
很短动作	约 150ms 内
局部列表变化	约 200ms
短距离运动	约 250ms 内
复杂旋转	约 300ms
长距离或全屏	约 350ms 内

若偏离，解释复杂度、距离、频率、设备和用户任务。

6.3 公开曲线语义

• 标准：前后都在视线内的状态变化；
• 减速：元素进入视线并在终点稳定；
• 加速：元素离开视线；
• 弹性：跟手、速度或物理回稳。

不要机械地给所有进入、退出使用同一曲线。

7. ArkUI 快速映射

详细映射和注意事项见 references/ARKUI-MAPPING.md。

需求	优先考虑
组件出现/消失	transition
同参数多属性变化	一个 animateTo
连续位置/缩放	图形变换属性
跟手弹性	curves.responsiveSpringMotion()
离手回稳与速度衔接	curves.springMotion()
自定义物理参数	curves.interpolatingSpring()
页面共享关系	geometryTransition()
页面导航	Navigation 默认或自定义转场
可点击图片语义	accessibilityText 等无障碍属性
复杂自绘语义	虚拟无障碍节点
性能检查	Inspector、Profiler、SmartPerf、长帧分析

注意：

• 物理曲线的实际时长由参数和速度决定，不要把 duration 当业务定时器。
• 使用 geometryTransition 时检查是否需要关闭默认转场，避免叠加。
• API 和行为必须以目标 SDK 文档及本地编译为准。

8. Motion Token 原则

建立语义层，不建立“好看参数集合”。

建议层级：

MotionTokens
├── duration: instant / short / local / full
├── curve: standard / decelerate / accelerate / follow / settle
├── distance
├── scale
├── stagger
└── policy

每个 Token 记录：

• 语义；
• 适用场景；
• 来源类型；
• 设备/API 范围；
• 低运动替代；
• 最后核验日期。

优先封装行为：

• PressFeedback；
• RowFeedback；
• StaggeredEntrance；
• StateMorph；
• SharedContainerTransition；
• FollowGestureMotion；
• VelocitySettleMotion；
• MotionPolicy。

不要使用 animation1、niceEase、fastSpring 等无语义名称。

9. Coding Agent 改造流程

当用户要求修改项目时：

1. 先列 Product / Motion / Interaction Inventory；
2. 标记 Evergreen、Versioned Platform 与 Project Overlay；
3. 标记系统默认与自定义；
4. 找重复常量和不一致行为；
5. 提议 Token 和语义 Modifier；
6. 对高风险手势或新视觉语言先做最小可交互原型；
7. 先改高频基础控件；
8. 再改导航、列表、状态和手势；
9. 品牌与装饰动效最后；
10. 每一批都构建；
11. 真机快速连续操作、反向打断和慢放；
12. 输出覆盖范围、删除项、平台版本、House Style 和未解决风险。

没有用户确认时，不批量重写全部页面。

10. 证据和置信度

证据优先级：

1. 源码与文件行；
2. 截图区域；
3. 录屏时间点；
4. 真机和性能数据；
5. 明确可复现的观察。

没有证据时，不输出 Blocker。推断必须标明“推断”。

置信度：

• high：直接证据且规则适用；
• medium：证据充分但上下文部分缺失；
• low：需要真机、设备或版本确认。

11. 审视输出格式

上下文卡

先列已知和假设。

Findings

优先级	规则 ID	证据	问题	用户影响	建议	ArkUI 落点	来源等级	置信度

优先级：

• BLOCKER：关键任务、方向、适配、可访问或性能严重失败；
• MAJOR：发布前应修复；
• MINOR：一致性和精致度；
• NOTE：可选或待验证。

最小修复方案

按依赖和收益排序。优先：

1. 删除不必要行为；
2. 恢复系统默认；
3. 修复架构和状态；
4. 修复手势连续性；
5. 统一 Token；
6. 最后调整品牌细节。

验证矩阵

至少包含：

• 最小可交互原型或真实实现；
• 构建；
• 目标设备；
• 目标输入；
• 浅/深主题；
• 默认/大字体；
• 快速连续操作；
• 反向打断；
• 慢放；
• 无障碍；
• 帧率或长帧。

结论

只能使用：

• 通过；
• 有条件通过；
• 不通过。

假设与待验证项

明确列出没有获得的证据。

12. 通过门槛

不通过

存在任一：

• 关键路径方向或返回关系错误；
• 主要交互无即时反馈；
• 手势与内容明显脱节；
• 重要功能不可被辅助工具理解；
• 目标设备严重截断、变形或不可操作；
• 自定义动画造成明显长帧；
• 把 House Style 冒充官方要求。

有条件通过

无 Blocker，但有未关闭的 Major。

通过

• 无 Blocker 和未关闭 Major；
• 关键设备、输入、字号和主题已验证；
• 自定义数值来源明确；
• 无障碍和性能证据充分。

13. 跨媒介边界

• 本 Skill 的强适用范围是 HarmonyOS 产品 UI。
• ArkUI、Canvas、RenderNode 或其他代码生成的产品动效，可以复用时间、几何、连续性和排版原则。
• 非交互视频不能套用按下反馈、焦点、可打断等交互规则。
• 传统视频剪辑、镜头叙事和生成式视频不属于当前主 Skill。
• 对缺少已核验官方资料的第三方工具，不假定其具体能力。

14. 参考文件加载

• 设计总原则：references/PRINCIPLES.md
• 动效与手势：references/MOTION.md
• 跨设备适配：references/ADAPTATION.md
• 无障碍：references/ACCESSIBILITY.md
• ArkUI 映射：references/ARKUI-MAPPING.md
• 来源登记：references/SOURCES.md

只读取当前任务所需文件，不要一次性复述全部参考内容。