HC3 裝置圖示
以使用者語言回覆。使用 scripts/icon_kit.py（Python，需安裝 pip install cairosvg pillow）產生圖示：
它包含了樣式輔助工具（漸層、柔影、徽章、約 35 種徽章圖形）、一個範例裝置繪圖（附有 11 段位百葉窗的天窗）以及預覽產生器。
風格（讓這些圖示適合 HC3 使用者介面）
- 真實描繪實際裝置（形狀、顏色、材質、視角）。要求使用者提供確切型號的照片並加以複製；切勿描摹照片或複製製造商標誌/商標（這樣也能保持圖示可分享）。如果使用者明確要求僅供私人使用的品牌標誌，請將該圖示排除在任何公開內容之外。
- 透明背景，每個狀態一個檔案 — 無淺色/深色變體。為確保在兩種主題下都可讀，請為深色裝置加上淺色邊緣（
stroke="#FFFFFF"1–2 像素或較淺的斜角），且切勿繪製背景底板。 - 右下角的小圓形徽章（中心點 100,100，半徑約 22，白色外環）：顯示狀態（綠色：開啟、灰色：待機/關閉、紅色：警報、橘色：警告、藍色：開啟/等級、紫色：自動…）或測量數值（溫度計、水滴、CO₂、風速…）。裝置繪圖需空出該角落。
- 128 × 128 viewBox，繪圖範圍約在 10–118 像素內，落地式裝置下方加上柔和的橢圓形陰影。
- 在交付前檢查預覽（
preview.png：每個圖示在淺色/深色對角背景上各顯示一次）。
每個裝置需要多少張圖片（HC3 規則）
| 裝置類型 | 一個圖示組的圖片數量 | 上傳欄位 |
|---|---|---|
| 二進位（開關、binarySensor、門/窗、動作、煙霧…） | 2：待機/啟動 | icon0, icon100 |
| 多層級（調光器、百葉窗、閥門高度） | 11：0, 10 … 100 | icon0 … icon100 |
| deviceController、大多數 QuickApp 父裝置、multilevelSensor / 溫度… | 1 | icon0 |
單一圖片的類型無法自行改變畫面。對於狀態相關的 QA 圖示（正常/警告/警報，或一種模式），請為每個狀態上傳一組圖示，並透過 Lua 切換：self:updateProperty("deviceIcon", tonumber(self:optionalVariable("iconAlarm")))
（將 ID 貼在變數中；模式請參考 hc3-quickapp 技能的 references/patterns.md §5）。
為每個有用的狀態製作一個圖示，並為 QuickApp 建立的每個裝置（父裝置與子裝置）製作圖示。
工作流程
- 列出所有裝置（父裝置、每個子裝置、每個 Z-Wave 子裝置）及其確切的
type（api.get("/devices/<id>")，例如 Fibaro 百葉窗模組為com.fibaro.FGR224，QA 子裝置為com.fibaro.rollerShutter）。 - 要求提供真實型號的照片；協商狀態與徽章的含義。
- 複製
scripts/icon_kit.py，為每個裝置編寫一個繪圖函式（128 方框內的 SVG 片段，請參閱roof_window(pct)），在ICONS中加入(name, title, body)列 — 每個狀態一列 — 然後執行python3 icon_kit.py --out icons/。命名規則：<裝置名稱>-<狀態>（shutter-000…shutter-100、boiler-on、boiler-off），以便 README 表格能說明哪個圖示對應到哪個位置。 - 顯示
preview.png；根據使用者的意見反覆修改（形狀、顏色、如表情符號般的徽章清晰度）。 - 上傳：在 QA 的
qa.json中的icons區段列出各組圖示，然後讓build_fqa.py（技能hc3-packaging） 產生<qa>-icons.sh，或手動上傳：設定 → 裝置 → 裝置 → 圖示 → 新增。
上傳 API（在 5.2xx 版本中觀察到）
POST /api/icons，multipart/form-data：type=device、deviceTemplate=<精確的裝置類型>、每個狀態一個檔案
（icon0、icon100 或 icon0…icon100）、fileExtension=png（也接受 svg）。回傳 201
{"id": 1055, "iconSetName": "User1055", "fileExtension": "png"}。套用：PUT /api/devices/<id>
{"properties": {"deviceIcon": 1055}}（從外部執行 — 切勿從 QA 內部對 QA 自身的 ID 執行，這會導致重啟；請使用
self:updateProperty）。刪除：DELETE /api/icons?id=&type=device&name=&fileExtension=png。使用者圖示 ID 從
約 1000 開始。GET /api/icons 會列出它們（不同韌體中存在兩種回應格式：請都接受）。
房間和場景圖示也存在（type=room / type=scene 可能 [V]）。
references/badges.md 列出了該工具包中可用的徽章顏色和圖形。