Communitygithub.com

halo-design

設計技能。Halo 是為任何網頁應用、儀表板、工具、登陸頁面或向量 PDF 所設計的冷靜、光滑且以數字為優先的設計系統,雙語設計(英文 + 庫爾德索拉尼語或任何 RTL 腳本)。當使用者要求 Halo 風格、想要看起來充滿活感的拋光暗/亮色界面(邊緣發光卡片、柔和動畫、可選的平靜音效)、需要與英文並列的庫爾德語、阿拉伯語或波斯語,或想要可直接印刷的向量 PDF 時,即可使用。代理人會撰寫一篇簡短的設計摘要,並為產品創造一個專屬的標誌性視覺。

halo-design 是什麼?

Halo 是一個完整的設計系統技巧,旨在為開發者與 AI 代理提供嚴謹、可測試且以產品為中心的設計方法論。不同於傳統的 UI 主題,Halo 提供一套工具與規則(包括設計代碼、版式、動態效果、無障礙性、雙語佈局及品質驗證),同時保留每個產品的獨特個性。此技巧支援廣泛的應用場景,從個人應用儀表板、數據密集的後台操作介面、到多語種(特別是庫爾德索拉尼語等 RTL 腳本)的印刷級向量 PDF。它的設計哲學以「數字優先」為核心,強調清晰的灰色標籤、突出的數值、以及清晰的文字說明,並搭配輕量的動畫效果(單一動畫曲線、僅顯示一次、無循環、支援減少動畫模式)。Halo 在各個主流平台(如 Claude Code、Cursor、Codex)上均可運行,其工作流程從撰寫產品專屬的設計摘要開始,選擇一個標誌性視覺元素(如光環、火花條、目標測量器、時間軸或狀態網格),然後基於 Halo 的組件庫進行組合,並在每個斷點分別平衡手機與筆電的佈局。此技巧強調「完成即代表通過 QA」,並提供自動化指令(如 `make setup`、`make check`)來安裝依賴、驗證技能本身,以及執行涵蓋 9 種寬度、2 種主題與 2 種語言的佈局測試與觸控測試。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Halo 設計技能

Halo 是一種設計方式,不是一個可供複製的主題。它修正了文法(設計代碼、版式、動態效果、無障礙性、雙語佈局、品質驗證),並將產品的個性留給您:其標誌性視覺、重點顏色含義、插圖、文案和音效。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 tokens)。不要讀取所有內容;根據任務來導航:

任務閱讀從哪裡開始
任何新產品或頁面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 tokens)。應改為搜尋特定模式(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. 品質驗證,透過 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。在兩種主題下,審查 390 與 1440 寬度的螢幕截圖。
  8. 如有需要則進行列印: HTML → scripts/print_pdf.py → qpdf 合併 → scripts/verify_pdf.sh(0 張圖片)。嵌入 .ttf 字型。

交付前檢查清單

  • 存在摘要,且標誌性視覺符合產品(非預設的光環,非複製的內容)。
  • 最多三個重點顏色含義,且使用一致;文字重點使用 --XT。
  • 設計代碼之外無色值字面量;無使用者未提供的商標。
  • 筆電:欄位平衡、頁尾對齊、圖表填滿卡片。手機:≤ 4 個導航控制項、44 px 觸控目標、320 寬度無水平滾動。
  • 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、圖示、數據視覺化、列印、無障礙性、品質驗證、音效、Figma、函式庫、框架
qa/ · scripts/測試套件 · 列印、驗證、設計代碼、資產、自我檢查
fonts/IBM Plex Sans Arabic + Inter(TTF, OFL),供離線、CI 與列印使用
examples/workout-plan/一個使用 Halo 製作的完整產品(網站 + 4 個向量 PDF)。僅供參考。

相關技能