Pixel HUD UI 是做什麼的？
這是一套 UI 框架，而不僅僅是色彩主題。它包含三個層次，好的成果需要三者並用：
- 基礎：4px 網格、針對 12px 像素字體調整的字級、色彩角色（每種顏色代表一個意義）、以 1px 線條取代陰影、階梯式動畫。
- 控制項：面板與標題列、按鈕（含意圖）、圖示按鈕、分頁、分段控制、列表行、表單欄位、輸入框、選擇器、方形核取方塊與選項按鈕、指示燈開關、儀表滑桿、進度儀表、指示燈、標籤、徽章、按鍵提示、選單、工具提示、對話框、提示訊息、表格、程式碼區塊、文章、載入器、空白狀態。每個都有固定尺寸和統一的狀態模型（hover, pressed, focus, selected, disabled, loading, error）。
- 色板：
--hud-*Token，讓框架能搭配任何色彩，包括應用程式自身的品牌色。
檔案
| 檔案 | 說明 |
|---|---|
references/design-system.md | 設計規範。 原則、基礎，以及每個控制項的結構、尺寸、狀態、使用時機和無障礙設計。在開始設計前請先閱讀。 |
assets/pixel-hud.css | 實作：Token、[data-skin="pixel"] 下的淺色全域變數，以及 hud-* 控制項類別 |
assets/palettes.css | starward（深空、暗色）、terminal（灰綠、暗色）、paper（暖沙色、淺色） |
assets/fonts.css | Fusion Pixel 12px（OFL 授權），託管於 jsDelivr；或透過 @fontsource 自行託管 |
assets/pixel-caret.js | 選擇性的 3px 區塊游標，用於文字欄位 (data-pixel-caret) |
assets/demo.html | 每個控制項的所有狀態，附色板切換器：可視化參考 |
references/integration.md | 各技術棧的整合指南：對應應用程式色彩、Tailwind、shadcn/ui、React/Next、Vue、範圍限定、無閃爍切換、自行託管字型 |
scripts/check-contrast.mjs | 任何色板的 WCAG 對比度檢查：node scripts/check-contrast.mjs my.css |
工作流程
1. 閱讀設計規範與展示頁
閱讀 references/design-system.md（至少包括原則、基礎，以及任務所需的控制項），並查看 assets/demo.html。設計規範說明每個控制項為什麼長這樣；遵循它才能讓畫面呈現出這個框架的風格，而不只是「一個深色主題加上像素字型」。
2. 了解專案
在複製任何東西之前，先確認：
- 使用的技術棧，以及全域 CSS 的載入位置（佈局檔、
main.ts、index.html、Tailwind 入口）； - 目前色彩的定義方式（CSS 自訂屬性、Tailwind 主題、shadcn 的 HSL 變數、元件中的十六進位色碼）；
- 這是全新 UI 還是重新造型、應用程式只有一種外觀還是可切換的主題、影響整個頁面還是特定區域。
這些決定色彩對應方式（步驟 4），並避免與應用程式現有樣式衝突。
3. 加入套件
將 pixel-hud.css、fonts.css、palettes.css（如果使用內建色板）以及 pixel-caret.js（如果應用程式有文字輸入框）複製到專案中。載入順序：字型 → 色板 → pixel-hud.css，放在應用程式自身基礎樣式之後。
4. 選擇色彩
- 使用內建色板：
data-hud-palette="starward" | "terminal" | "paper"。 - 使用應用程式自身色彩：撰寫一個區塊將其變數對應到
--hud-*（參見references/integration.md› Mapping an app's colors）。保留品牌色，加上框架。 - 建立新色板：依照設計規範中的「新建一套配色」步驟。
然後對任何你撰寫或對應的色板執行 node scripts/check-contrast.mjs <file>，並修正所有 FAIL 項目：控制項依賴橫條、文字和綠色在每個表面上都要可讀。
5. 啟用框架
<html data-skin="pixel" data-hud-palette="starward">
如果是可切換的主題，需在首次繪製前設定這些屬性（references/integration.md › No-flash toggle）。若要僅對特定區域套用風格，將兩個屬性放在其容器上即可。
6. 使用控制項建構
全域樣式已處理好字型、方形角落、原生輸入框、選取器、範圍滑桿、核取方塊、捲軸、焦點環、選取範圍和掃描線。為每個元素透過類別指定角色，並遵循設計規範中的尺寸與狀態：
| 需求 | 控制項（類別） |
|---|---|
| 群組相關資訊 | .hud-panel + .hud-titlebar (+ .hud-titlebar__actions)，內容區 .hud-panel__body，區段標題 .hud-subhead |
| 主要動作 | .hud-btn.is-solid（意圖：accent, go, warn, info, danger） |
| 次要動作 | .hud-btn |
| 僅圖示動作 | .hud-icon-btn + aria-label |
| 切換檢視 | .hud-tabs > .hud-tab[aria-selected] |
| 從 2-5 個值中選一個 | .hud-segmented > button[aria-pressed] |
| 可導覽列表 | .hud-row[aria-current] |
| 有標籤的輸入框 | .hud-field > .hud-label + input/select + .hud-help / .hud-error |
| 下拉選單 | .hud-select > select |
| 是/否，單選 | .hud-check, .hud-radio（方形標記） |
| 即時開關 | button.hud-switch[role=switch][aria-checked] > .hud-switch__knob |
| 等級/進度 | .hud-gauge + --value（data-state warn/alert） |
| 狀態 | .hud-lamp[data-state] |
| 數值、ID、參數 | .hud-tag；計數 .hud-badge；按鍵 kbd |
| 選單、提示、模態、反饋 | .hud-menu, .hud-tooltip, .hud-backdrop > .hud-dialog, .hud-toasts > .hud-toast |
| 資料、程式碼、文章 | table.hud-table, .hud-code, .hud-prose |
| 指令/聊天輸入 | .hud-input + data-pixel-caret |
| 等待中、無資料 | .hud-loader、按鍵上的 aria-busy、.hud-empty |
將類別放在元件原始碼中（JSX、模板），透過元件庫的 className/class 屬性傳遞，而不是針對框架內部寫選擇器：這樣能經得起重構，且閱讀清晰。
若要重新造型現有應用程式，先將每個現有元件對應到上表（在回覆中提供簡短列表有助於使用者跟進），然後套用。
7. 檢查結果
- 擷取頁面畫面（或開啟頁面）並與
assets/demo.html比較。 - 確認像素字型已載入（
document.fonts、Network 分頁）；CSP 可能封鎖 jsDelivr，此時需自行託管。 - 使用 Tab 鍵逐項瀏覽：每個控制項都可到達，1px 綠色焦點環可見。
- 對主要控制項檢查狀態模型：hover, pressed, disabled, loading, error。
- 對使用中的色板執行對比度檢查腳本並通過。
最重要的規則
設計規範中有完整說明，以下是常被違反的幾點：
- 方形且扁平。 無圓角、無模糊陰影、無漸層（掃描線除外）。只有疊加層可以使用硬邊偏移陰影。
- 色彩堅守其角色。 橫條色 = 結構和選取；綠色 = 開啟、強調、焦點；黃色 = 數值；橙色 = 筆記和警告；紅色 = 危險。將綠色用作裝飾會使其失去「開啟」的意義。
- 選取 = 反白。 橫條色填滿加上深色文字；列表行額外加上 3px 綠色邊緣。在橫條色背景上，hover 會反向反白。
- 每個區域一個實心主要動作；並排的動作各自擁有自己的意圖色，且在停用時保持該顏色（淡化，不轉為外框）。
- 標題列僅用於面板。 表格和程式碼標題使用較柔和的
--hud-bar-soft。 - 尺寸遵循比例：控制項 24/28/32px，間距基於 4px 網格，文字 12/14/16/24/36px。
常見陷阱
- 框架會在其範圍內強制設定
border-radius: 0 !important。若要保留圓形（例如大頭貼），請將皮膚限定在排除該元素的容器中。 color-mix()需要 Chrome/Edge 111、Safari 16.2、Firefox 113；對較舊的瀏覽器，請將--hud-bar-soft/--hud-bar-line設定為純色。- 設定
display的類別可能會顯示hidden元素；框架會在其範圍內重新隱藏[hidden]，因此建議使用hidden屬性來切換顯示。 - 從程式碼設定欄位值的框架不會觸發
input事件；在這種變更後需呼叫field.__pixelCaret.update()以立即移動游標。 - 掃描線位於非常高的 z-index 且設有
pointer-events: none；若掃描線造成干擾（截圖、Canvas 應用程式），可使用data-hud-scanlines="off"將其關閉。