harmony-design

HarmonyOS Design 是华为为 HarmonyOS / OpenHarmony 应用定义的官方设计语言，覆盖设计理念、视觉风格（色彩/字体/排版/图标/光感/圆角/间隔）、布局（栅格/断点/响应式）、动效、控件、人机交互、系统特性、多设备适配、UX 体验标准与设计资源。Agent 凭 Material Design 或 iOS Human Interface Guidelines 经验直接生成的 ArkUI 代码，虽能编译但通常偏离鸿蒙视觉与交互范式：常见反模式包括硬编码字号而非鸿蒙字号阶梯、用 Material 风格 elevation 阴影而非「沉浸光感」、忽略 8vp 网格与断点系统、不适配深色模式色彩 token。

本 skill 提供离线参考文档集（13 份文档，覆盖 design-guides catalog 全部 9 个顶级分类约 60 份叶子文档 + 设计资源页），作为 Agent 给出鸿蒙设计语言指导的权威参考。

When to Use This Skill

Follow this skill's workflow whenever any of the following conditions is met:

• The user requests 鸿蒙设计语言 / HarmonyOS Design 设计理念 / 设计哲学 概念类指导
• The user requests 视觉风格 指导：色彩 token / 鸿蒙黑体 / 字号阶梯 / 文本排版 / 应用图标 / HarmonyOS Symbol / 沉浸光感 / 圆角参数 / 间隔参数
• The user requests 布局 指导：8vp 网格 / 断点系统 / 栅格 / 响应式布局 / 安全区 / 侧边 Tab / 分栏 / 自适应拉伸/缩放/延伸/折行
• The user requests 动效 指导：动效时长 / 曲线 / 转场动效 / 手势动效 / springMotion / 贝塞尔曲线
• The user requests 控件选型与规范：底部页签 / 子页签 / 标题栏 / 按钮 / 菜单 / 工具栏 / 列表 / 弹出框 / 半模态面板 / 选择器 / 滑动条 / 文本框 / 搜索框 等任意 ArkUI 控件
• The user requests 人机交互 指导：手势 / 焦点导航 / 鼠标 / 键盘 / 触控板 / 拖拽 / 框选
• The user requests 系统特性或能力 设计：导航条 / 通知 / 实况窗 / 服务卡片 / 画中画 / 深色模式 / 状态栏 / 分享 / 华为账号 / 华为支付 / 启动页 / 碰一碰 / 靠近发现 / 平行视界
• The user requests 多设备适配 设计：折叠屏（双/三/阔）/ 平板 / 电脑 / 智能座舱 / 智能穿戴 / 智慧屏
• The user requests UX 体验标准或最佳实践：通用应用/大屏/折叠屏/电脑/智慧屏/穿戴 UX 标准，或某垂类（影音娱乐/社交通讯/电商购物/金融理财等）最佳实践
• The user requests 元服务设计 指导
• The user requests 设计资源：Sketch/PIX 组件库 / HarmonyOS Sans 字体 / 应用图标 / 产品机框 / 品牌资源

Do not force this skill onto "ArkTS 语法/类型/编码风格"、"ArkTS 编译错误修复"、"命令行构建/签名/部署"、"在线抓取最新文档" 场景 — 使用对应 skill（见下表）。

Boundary with Other Skills

This skill covers 「鸿蒙设计语言要求什么」，不覆盖 「ArkTS 代码怎么写」、「编译错误怎么修」、「怎么构建部署」、「怎么在线抓取最新文档」。当 UI 设计任务涉及以下问题时，交叉引用对应 skill：

Workflow (Follow Strictly)

1. 读 INDEX，定位必读文档

任何 UI 设计任务前，必须先读 references/INDEX.md。INDEX 提供「任务类型 → 必读文档」映射表与大文件检索策略。不要凭文件名猜测，不要一次性加载全部 13 份文档。

2. 按任务加载 1-2 份文档

根据 INDEX 映射加载必读文档。对于 ⚠️ 标记的大文件（行数 > 1500，如 07/08/09/10/11），禁止整文件读入：

• 先用 Grep 搜索控件/特性名称（如 Grep "^## " references/09-system-features-capabilities.md 列出全部章节）
• 再用 Read with offset/limit 读取目标章节（200-400 行窗口）

3. 套用鸿蒙设计语言红线

写或改 ArkUI 代码前，自检以下高频红线（详细值见对应文档；最常被违反的已标注速查值）：

视觉风格红线（详见 references/02-visual-style.md）：

• 色彩：MUST 使用鸿蒙色彩 Token（系统基础 Token + 语义 Token），不要硬编码 #FFFFFF/#000000；MUST 同时适配深色模式（详见 references/09-system-features-capabilities.md 深色模式一节）
• 字号：MUST 使用鸿蒙字号阶梯（fp 单位），不要硬编码 fontSize: 14；1 fp = 1 vp × scale（用户字体设置）
• 圆角：MUST 使用鸿蒙圆角参数（同层统一、层级正相关），不要随意用 borderRadius: 8
• 间隔：MUST 使用鸿蒙间隔参数（8vp 网格倍数），不要随意用 margin: 12
• 阴影：MUST 用「沉浸光感」规范（层级与色彩区分），禁止用 Material 风格 elevation: 8 硬阴影
• 图标：MUST 优先使用 HarmonyOS Symbol（具备字体属性 + 多层颜色 + 分层动效），而非静态 PNG

布局红线（详见 references/03-layout.md）：

• 单位：MUST 使用 vp/fp，禁止用 px 硬编码
• 网格：MUST 对齐 8vp 网格（小图标可对齐 4vp）
• 栅格列数：<600vp → 4 列；600-840vp → 8 列；>=840vp → 12 列
• 断点：MUST 使用横向断点（窗口宽度）+ 纵向断点（宽高比）双维度判断布局
• 安全区：MUST 处理系统安全区（状态栏/导航条/侧边防误触区），用 avoidArea 而非硬编码 padding

动效红线（详见 references/04-animation.md）：

• 时长：简单动画 ~100ms；小范围运动 ~150ms；局部运动 ~200ms；复杂动画 ~300ms；全屏运动 ~350ms
• 曲线：MUST 用鸿蒙贝塞尔曲线（标准/减速/加速）或弹性曲线（springMotion/responsiveSpringMotion/interpolatingSpring），禁止用 linear 直线
• 帧率：默认 60 FPS（1 帧 = 16.67ms）

控件选型红线（详见 references/06/07）：

• 导航：底部页签（手机）/ 子页签（内容分类）/ 标题栏（顶部）按场景选型，不要自创导航
• 列表：MUST 用 List 控件 + LazyForEach，不要用 Column + ForEach 模拟
• 弹出：模态用 Dialog，半模态用 bindSheet，轻提示用 toast/snackbar，气泡用 popup，按场景选型

4. 引用来源

回答中 MUST 标注引用的文档章节，例如：

Per references/02-visual-style.md 「色彩」一节，鸿蒙色彩 Token 分为系统基础 Token 与语义 Token，禁止硬编码颜色值。

5. 必要时用 harmony-fetch 在线补全

若离线文档无法回答（如 HarmonyOS 新版本新增控件、最新设计资源下载链接失效、未覆盖的文档），按以下流程：

1. 用 harmony-fetch skill 的 getDocumentById API（catalogName=design-guides）在线抓取对应 objectId
2. 或用 WebSearch with site:developer.huawei.com/consumer/cn/doc/design-guides/ <keywords> 找到上游 URL
3. 回答中标注「在线补全：来源 developer.huawei.com，抓取时间 YYYY-MM-DD」

鸿蒙设计语言红线快速参考

以下为高频反模式的速查表，详细规则以 references/ 对应文档为准。

Directory Structure

harmony-design/
├── SKILL.md                                                  # This file
├── references/
│   ├── INDEX.md                                              # 唯一入口，必读
│   ├── 01-design-concepts.md                                 # 设计理念
│   ├── 02-visual-style.md                                    # 视觉风格（色彩/字体/排版/图标/Symbol/光感/圆角/间隔）
│   ├── 03-layout.md                                          # 布局（基础/响应式架构/响应式方法）
│   ├── 04-animation.md                                       # 动效（概述/原则/属性/转场/手势）
│   ├── 05-foundations-misc.md                                # 界面用语/全球化/隐私
│   ├── 06-components-navigation-action.md                    # 控件·概览/导航/操作
│   ├── 07-components-display-input-selection-container.md    # 控件·展示/输入/选择/容器（大文件，按章节检索）
│   ├── 08-hmi.md                                             # 人机交互（大文件，按章节检索）
│   ├── 09-system-features-capabilities.md                    # 系统特性 & 能力（大文件，按章节检索）
│   ├── 10-multi-device.md                                    # 多设备适配（大文件，按章节检索）
│   ├── 11-ux-standards-and-practices.md                      # UX 标准/最佳实践/元服务（大文件，按章节检索）
│   └── 12-design-resources.md                                # 设计资源索引
└── assets/
    ├── typography-scale.ets                                  # BAD vs GOOD：字号阶梯
    ├── elevation-and-shadow.ets                              # BAD vs GOOD：沉浸光感 vs Material 阴影
    ├── safe-area-and-grid.ets                                # BAD vs GOOD：安全区 + 响应式栅格
    └── dark-mode-color.ets                                   # BAD vs GOOD：深色模式色彩 token

Documentation Source & Maintenance

• 上游：华为开发者官网设计子站
  • 设计概览：https://developer.huawei.com/consumer/cn/design/
  • 设计指南：https://developer.huawei.com/consumer/cn/doc/design-guides/design-concepts-0000001795698445（catalogName=design-guides，9 个顶级分类约 60 份叶子文档）
  • 设计资源：https://developer.huawei.com/consumer/cn/design/resource/
• 抓取方式：design-guides 叶子文档通过 harmony-fetch 的 getDocumentById API 抓取（objectId 取自 catalog tree 的 relateDocument 字段）；设计资源页用 WebFetch 抓取 SPA 渲染后文本
• 抓取时间：2026-07-05（所有 references/*.md 顶部标注）
• 更新策略：鸿蒙设计语言随 HarmonyOS 版本迭代；若需更新，使用 harmony-fetch skill 重新抓取对应 objectId 覆盖文件，或访问上游 URL 获取最新资源链接
• 图片链接：文档中的图片为华为 CDN 带签名链接，24 小时后过期；若需查看图片，访问上游 URL 或重新抓取