Halo 設計技能
Halo 是一種設計方式,不是一個可供複製的主題。它修正了文法(設計代碼、版式、動態效果、無障礙性、雙語佈局、品質驗證),並將產品的個性留給您:其標誌性視覺、重點顏色含義、插圖、文案和音效。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 tokens)。不要讀取所有內容;根據任務來導航:
| 任務 | 閱讀 | 從哪裡開始 |
|---|---|---|
| 任何新產品或頁面 | 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 tokens)。應改為搜尋特定模式(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)。 - 品質驗證,透過 http 提供服務:
加入產品本身的互動檢查和 axe-core。在兩種主題下,審查 390 與 1440 寬度的螢幕截圖。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。 - 設計代碼之外無色值字面量;無使用者未提供的商標。
- 筆電:欄位平衡、頁尾對齊、圖表填滿卡片。手機:≤ 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)。僅供參考。 |