Halo 设计技能 是做什么的?
Halo 是一种设计方式,而不是一个可以复制的主题。它定义了语法(令牌、字体、动效、无障碍、双语排版、QA),而产品的个性——签名视觉、强调色含义、插图、文案和音效——由你来决定。examples/ 中的锻炼计划示例和两个模板只是机制演示,不是可重复使用的内容。
基本规则
- 为每个产品独立设计。 先写设计简报(
templates/brief.md),然后选择一个适合这个产品的签名视觉元素(docs/00-creative-direction.md)。除非产品是关于完成每日目标,否则环、运动象形图和锻炼文案都是错误的。 - 平台 → Halo → 经过验证的库。永远不要发明机制(
docs/16-libraries.md)。 - 令牌是颜色、曲线和圆角的唯一来源。
tokens/tokens.css之外不允许出现颜色字面量;scripts/check_skill.py会对 Halo 的 CSS 强制执行此规则。 - 两种主题、两种方向、每个断点都需要设计和测试。
- 数字优先: 灰色标签 → 大号强调数值 → 简洁句子。视觉元素重复数字,但绝不取代数字。
- 动效要轻: 一条曲线,一次揭示,没有循环,对减少动效模式友好。实时更新数据就地变化,从不重新播放动效。
- 没有标志。 品牌位置写产品名称的文本。只有当用户提供时才使用图形标记。
- 完成意味着 QA 通过(
docs/13-qa.md)。
只阅读任务所需的内容
文档都很短(每个约 1,500 token)。不要阅读所有内容;根据任务选择路径:
| 任务 | 阅读 | 起始模板 |
|---|---|---|
| 任何新产品或页面 | docs/00、docs/02、docs/03、docs/05 | templates/starter.html(个人应用)或 templates/dashboard.html(数据/运维) |
| 数据密集型页面 | docs/10、docs/04 | templates/dashboard.html |
| 库尔德语 / 阿拉伯语 / 波斯语 | docs/08、docs/03 | 任一模板,设置 lang=ckb |
| 手机端打磨 | docs/07 | — |
| 动效、边缘光、滚动 | docs/06 | — |
| 音效 | docs/14 | js/halo-sound.js |
| 图标或插画 | icons/README.md、docs/09 | icons/ |
| 打印文档或 PDF | docs/11 | templates/print-a4.html |
| React / Next / Tailwind / Vue | docs/17 | — |
| 选择库 | docs/16 | — |
| Figma 或其他工具的设计令牌 | docs/15、tokens/*.tokens.json | — |
| 无障碍 | docs/12 | — |
| 测试 | docs/13 | qa/ |
绝对不要整体阅读 examples/workout-plan/index.html(约 42k token)。相反,通过搜索特定模式来查找内容(例如 grep -n "restTimer" …)。
工作流程
- 简报。 填写
templates/brief.md:目标用户是谁、他们回来检查什么、1–3 个核心数字、签名视觉元素、强调色含义、插画语言、动效和音效强度、表面、语言和章节。如果需求不明确,显示简报并问一个问题;否则用短段落陈述需求并开始构建。 - 基础设置。 链接
tokens/tokens.css、css/halo.css、js/halo.js(以及仅在简报包含音效时才链接的js/halo-sound.js),并调用Halo.init({dict})。字体:Google Sans + IBM Plex Sans Arabic(docs/03)。 - 组装章节,使用
docs/05中的组件:- 用现有块构建签名视觉元素:
Halo.rings、Halo.spark、带.target标记的.meter、.bars、.timeline、状态网格或排版英雄。或者发明一个符合docs/00规则的新元素。 - 替换所有模板内容。如果你的页面出现了“关闭圆环”或“GPU 健康”,但产品与此无关,那就是你复制了内容。
- 用现有块构建签名视觉元素:
- 平衡手机和笔记本的布局(
docs/04、docs/07)。 - 双语: 每个字符串都放入字典,并应用
docs/08中的 RTL 规则。如果你自己编写库尔德语,告知用户并建议请母语者审查。 - 动效和音效 按照简报选择的强度实现(
docs/06、docs/14)。 - QA,通过 http 服务运行:
添加产品自身的交互检查和 axe-core 无障碍检查。在 390px 和 1440px 两种主题下检查截图。python3 qa/qa_layout.py http://localhost:8000/page.html # 9 种宽度 × 2 种主题 × 2 种语言 python3 qa/qa_touch.py http://localhost:8000/page.html # 手机触摸测试套件 - 打印(如果需要):HTML →
scripts/print_pdf.py→qpdf合并 →scripts/verify_pdf.sh(0 张图片)。嵌入.ttf字体。
交付前检查清单
- 存在简报,签名视觉元素适合产品(不是默认使用圆环,不是复制的内容)。
- 最多三个强调色含义,使用一致;文本强调色使用
--XT。 - Token 之外没有颜色字面量;没有用户未提供的标志。
- 笔记本:平衡的列、对齐的页脚、图表填满卡片。手机:≤ 4 个导航控件、44px 触控目标、320px 宽度下没有横向滚动。
- RTL:设置了
dir/lang、翻转的尖括号、镜像的图表、拉丁术语和拉丁单位用<bdi>包裹。 - 减少动效模式得到尊重;音效(如果有)提供切换开关并且绝不是唯一的信息传递方式。
- 事实性声明已链接来源;破坏性操作提供撤销功能。
-
qa_layout.py和qa_touch.py通过;控制台无错误;PDF 已验证为矢量。
可重现性
make setup安装固定版本的依赖(requirements.txt)和 Chromium。make check验证技能本身:链接、令牌同步、无多余颜色、无标志、JS 语法、frontmatter。make qa测试每个模板和示例;make assets重新渲染 README 图片;make tokens重新构建 DTCG JSON。- CI 在
.github/workflows/qa.yml中运行相同流程。
文件映射
| 路径 | 内容 |
|---|---|
docs/00-creative-direction.md | 首先阅读。 简报、签名视觉元素目录、强调色含义、插画语言、反模式 |
templates/brief.md | 需要填写的简报 |
templates/starter.html | 个人应用机制:分割英雄、圆环、任务、计时器、底部面板、音效 |
templates/dashboard.html | 数据/运维机制:状态网格、迷你走势图、带目标的仪表、实时更新、静止动效 |
templates/print-a4.html | 矢量打印页面 |
tokens/ | tokens.css(真实来源)+ DTCG 2025.10 JSON |
css/halo.css · js/halo.js · js/halo-sound.js | 组件 · 运行时 · 轻柔音效 |
icons/ | UI 图标(Lucide 网格)、字形、象形图语法 + 图库 |
docs/01–17 | 原则、颜色、字体、布局、组件、动效、手机、RTL、图标、数据可视化、打印、无障碍、QA、音效、Figma、库、框架 |
qa/ · scripts/ | 测试套件 · 打印、验证、令牌、资源、自检 |
fonts/ | IBM Plex Sans Arabic + Inter(TTF,OFL 许可证),用于离线、CI 和打印 |
examples/workout-plan/ | 一个使用 Halo 制作的完整产品(网站 + 4 个矢量 PDF)。仅作参考。 |