Communitygithub.com

Halo 设计技能

Halo 设计系统,适用于任何 Web 应用、仪表盘、工具、着陆页或矢量 PDF,支持英文 + 库尔德语(索拉尼语)或任何 RTL 脚本的双语设计。当用户要求 Halo 风格、需要精致的深色/浅色界面(发光卡片、安静动效、可选轻柔音效)、需要同时支持库尔德语/阿拉伯语/波斯语和英语,或需要可直接打印的矢量 PDF 时使用。

Halo 设计技能 是什么?

Halo 设计技能是一个全面的设计系统,旨在帮助 AI 代理(如 Claude Code、Cursor 等)为各种 Web 项目创建具有一致性、双语支持(英文 + RTL 语言)和精致动效的界面。其核心理念是“为每个产品设计”,代理首先编写设计简报,然后根据产品特性选择独特的“签名视觉元素”(signature visual),而非简单复制模板。系统通过严格的 token 管理确保设计规范(色彩、曲线、半径均由 `tokens.css` 控制),并强制要求同时设计浅色和深色主题、从左到右(LTR)和从右到左(RTL)布局,以及响应所有断点。内置 QA 工具(qa_layout.py 和 qa_touch.py)能自动测试 9 种宽度 × 2 种主题 × 2 种语言,确保高质量的交付。Halo 强调“数字优先”的表达(灰色标签 + 大号数值 + 简洁句子),并推荐使用标准组件库(如 Google Sans 字体、IBM Plex Sans Arabic、以及 Lucide 图标)来避免重复发明机制。支持生成矢量 PDF(通过 HTML → print_pdf.py → qpdf),适合需要打印或导出的场景。该技能还包含详细的文档(docs 目录)、模板(starter.html、dashboard.html、print-a4.html)和一个完整的示例(workout-plan)供参考。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SawabS/halo-design-skill/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Halo 设计技能 是做什么的?

Halo 是一种设计方式,而不是一个可以复制的主题。它定义了语法(令牌、字体、动效、无障碍、双语排版、QA),而产品的个性——签名视觉、强调色含义、插图、文案和音效——由你来决定。examples/ 中的锻炼计划示例和两个模板只是机制演示,不是可重复使用的内容。

基本规则

  1. 为每个产品独立设计。 先写设计简报(templates/brief.md),然后选择一个适合这个产品的签名视觉元素(docs/00-creative-direction.md)。除非产品是关于完成每日目标,否则环、运动象形图和锻炼文案都是错误的。
  2. 平台 → Halo → 经过验证的库。永远不要发明机制(docs/16-libraries.md)。
  3. 令牌是颜色、曲线和圆角的唯一来源。 tokens/tokens.css 之外不允许出现颜色字面量;scripts/check_skill.py 会对 Halo 的 CSS 强制执行此规则。
  4. 两种主题、两种方向、每个断点都需要设计和测试。
  5. 数字优先: 灰色标签 → 大号强调数值 → 简洁句子。视觉元素重复数字,但绝不取代数字。
  6. 动效要轻: 一条曲线,一次揭示,没有循环,对减少动效模式友好。实时更新数据就地变化,从不重新播放动效。
  7. 没有标志。 品牌位置写产品名称的文本。只有当用户提供时才使用图形标记。
  8. 完成意味着 QA 通过(docs/13-qa.md)。

只阅读任务所需的内容

文档都很短(每个约 1,500 token)。不要阅读所有内容;根据任务选择路径:

任务阅读起始模板
任何新产品或页面docs/00、docs/02、docs/03、docs/05templates/starter.html(个人应用)或 templates/dashboard.html(数据/运维)
数据密集型页面docs/10、docs/04templates/dashboard.html
库尔德语 / 阿拉伯语 / 波斯语docs/08、docs/03任一模板,设置 lang=ckb
手机端打磨docs/07—
动效、边缘光、滚动docs/06—
音效docs/14js/halo-sound.js
图标或插画icons/README.md、docs/09icons/
打印文档或 PDFdocs/11templates/print-a4.html
React / Next / Tailwind / Vuedocs/17—
选择库docs/16—
Figma 或其他工具的设计令牌docs/15、tokens/*.tokens.json—
无障碍docs/12—
测试docs/13qa/

绝对不要整体阅读 examples/workout-plan/index.html(约 42k token)。相反,通过搜索特定模式来查找内容(例如 grep -n "restTimer" …)。

工作流程

  1. 简报。 填写 templates/brief.md:目标用户是谁、他们回来检查什么、1–3 个核心数字、签名视觉元素、强调色含义、插画语言、动效和音效强度、表面、语言和章节。如果需求不明确,显示简报并问一个问题;否则用短段落陈述需求并开始构建。
  2. 基础设置。 链接 tokens/tokens.css、css/halo.css、js/halo.js(以及仅在简报包含音效时才链接的 js/halo-sound.js),并调用 Halo.init({dict})。字体:Google Sans + IBM Plex Sans Arabic(docs/03)。
  3. 组装章节,使用 docs/05 中的组件:
    • 用现有块构建签名视觉元素:Halo.rings、Halo.spark、带 .target 标记的 .meter、.bars、.timeline、状态网格或排版英雄。或者发明一个符合 docs/00 规则的新元素。
    • 替换所有模板内容。如果你的页面出现了“关闭圆环”或“GPU 健康”,但产品与此无关,那就是你复制了内容。
  4. 平衡手机和笔记本的布局(docs/04、docs/07)。
  5. 双语: 每个字符串都放入字典,并应用 docs/08 中的 RTL 规则。如果你自己编写库尔德语,告知用户并建议请母语者审查。
  6. 动效和音效 按照简报选择的强度实现(docs/06、docs/14)。
  7. QA,通过 http 服务运行:
    python3 qa/qa_layout.py http://localhost:8000/page.html    # 9 种宽度 × 2 种主题 × 2 种语言
    python3 qa/qa_touch.py  http://localhost:8000/page.html    # 手机触摸测试套件
    
    添加产品自身的交互检查和 axe-core 无障碍检查。在 390px 和 1440px 两种主题下检查截图。
  8. 打印(如果需要):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)。仅作参考。

相关技能