zriptic/roclicks-skills

Roblox UI 製作技能

授權優先。 圖示來自您（開發者）擁有的一個授權圖示包；此技能不附帶任何圖示與紋理。請閱讀您圖示包的授權合約：大多數付費圖示包允許在您自己的遊戲中使用，但禁止轉售、再散佈、資產包以及 AI 訓練（如果是這樣，切勿將圖示包的 PNG 檔案傳送給任何圖片模型）。在遊戲儲存庫中，請提交 icons.json 與複製腳本，而非圖示包本身（除非授權允許）。紋理由您自行從 https://ui-resources.com 下載（請參閱 UI_RESOURCES.md）；請標記其創作者。

Figma 匯入工具適用於已存在於 Figma 中的設計；此技能適用於設計新的 UI（或透過 HTML 重新製作截圖）。

工作循環： 參考 -> 標記 -> HTML（所有狀態）-> 開發者檢查 -> 學習 -> 匯入 -> 驗證。 在觸碰任何東西之前，請先閱讀 LESSONS.md（至今學到的所有規則及其背後的原因）。其優先級高於以下任何與之牴觸的內容。

此技能中的檔案

檔案	說明
LESSONS.md	所有規則 + 原因。優先閱讀；將開發者的回饋寫入此檔案 (REVIEW_LOOP.md)
STYLE.md	將參考轉換為標記；預設設定；CSS 標記 -> Roblox 表格
UI_RESOURCES.md	ui-resources.com：這是什麼、如何尋找/下載、Stud 紋理及其放置位置
PATTERNS.md	HUD、商店、抽獎轉盤 + 機率、提示、確認、載入、教學、對話框、目標藥丸、列表
PIPELINE.md	HTML -> JSON -> Roblox 詳細說明：rbx.json、匯出標記、映射表、分類帳、範本、副本
REVIEW_LOOP.md	如何展示畫面、收集回饋、獲得批准
VERIFY.md	模擬渲染、屬性掃描、編輯模式測試、實際遊玩點擊、檢查清單
ROBLOX_FACTS.md	實測引擎 + MCP 工具資訊 (inset, TextSize, 上傳, 截圖)
styles/	stud.css（預設設定）、glass.css（暗色模擬器設定）
templates/examples/	一個可運作的 UI 專案：build.py, kit.css, icons.json, rbx.json
templates/luau/	Builder, UIKit, NumberFormat, Theme, client/UI + Controller, Toasts, UpdateInPlace, PixelRows, ProgressiveReveal, NextGoal, CrateRoll, LoadingScreen, PropertySweep, WorldHitTest
scripts/	read_reference, copy_icons, cdp/export/dump, gen, ledger, assets, bundle, mock/mockshot/mockdiff, check_copies, luau_to_rbxmx; remake/ = 1:1 測量工具

下方使用 SK=<此技能的資料夾>（此 SKILL.md 所在的資料夾）。您需要的工具：python3（包含 PIL + numpy）、node 22+、Google Chrome（無頭渲染；環境變數 CHROME 可覆寫 macOS 路徑）、luau-analyze、一個用於檢視頁面的瀏覽器面板或瀏覽器自動化工具（在 Claude Code 桌面版中：mcp__Claude_Browser__*，使用 ToolSearch 載入）、一個可以執行 Luau 並匯入 .rbxmx 檔案的 Studio MCP 伺服器（此技能是針對社群 robloxstudio MCP 編寫的）以及用於 upload_image 的內建 Roblox_Studio MCP（請參閱 ROBLOX_FACTS.md）。

1. 簡介、參考、風格（必備：風格參考）

• 取得簡介：有哪些畫面、它們的功能、顯示哪些資料、PC 與手機版。列出每個畫面所需的所有狀態。
• 風格參考圖片是必需的。 使用開發者提供的圖片。如果沒有：詢問一次（「請提供您想要的風格截圖；否則我將使用 Stud 風格」）。如果他們說就照預設：使用 stud 預設設定。大多數遊戲都是 stud 風格。
• 首先執行步驟 4 的專案設定（會建立 ui/），然後將參考儲存為 ui/ref.png。佈局參考（另一款遊戲的商店）與 STYLE 參考是分開的。
• 在 ui/ 資料夾內讀取它（STYLE.md 第 2 節）：python3 $SK/scripts/read_reference.py ref.png -> 調色板、輪廓像素、紋理提示、文字樣式、密度 + ref_palette.png、ref_zoom.png（讀取它以查看 studs/光澤）以及一個草稿 style.css。肉眼確認每個數值，僅保留所選預設設定的覆寫。
• 「像遊戲 X」= 受其啟發，而非複製，除非開發者說「1:1 重製此畫面」（此時請參考 LESSONS 第 7 節和 scripts/remake/）。

2. 來自 ui-resources.com 的紋理

Stud 風格必須包含 stud 紋理。此技能不附帶一個：請自行從 https://ui-resources.com 下載「Stud texture」（標籤 Stud），如有需要，將其轉換為真正的 PNG，並在您的專案中儲存為 ui/stud.png（每個瓷磚 4x4 studs，以 112 px 平鋪，使用 overlay 混合模式）。對於其他任何東西（紙張、光芒、半色調、背景），首先在網站上搜尋，並將下載內容儲存在 ui/tex/ 中（UI_RESOURCES.md：過濾器、?tag=Stud、讀取延遲載入的 URL、針對命名為 PNG 的 WebP 使用 file + sips）。在 build.py 的開頭註明創作者。

3. 圖示：僅限您的圖示包

圖示僅來自開發者擁有的一個授權向量圖示包（每個專案一個向量包；切勿混合圖示包），絕不來自表情符號。透過瀏覽或搜尋圖示包自己的資料夾或目錄來尋找圖示（例如 find <pack> -iname '*coin*'）。在步驟 4 設定完成後，編輯 ui/icons.json（{"slug": "圖示檔案名稱或圖示包內的路徑"}；範例列表是一個起點），然後在 ui/ 資料夾中執行 python3 $SK/scripts/copy_icons.py icons.json --pack <您的圖示包>（可加上 --prefer " Outline" 或您圖示包的等效選項，以優先使用輪廓變體）。絕不使用表情符號，關閉按鈕使用文字 "X"。在宣稱任何圖示缺失之前，請先搜尋同義詞。

4. 以 HTML/CSS 建立每個畫面

在遊戲儲存庫中設定一次（在步驟 1-3 將任何內容寫入 ui/ 之前執行此操作；cp -n 絕不覆寫）：

mkdir -p ui && cp -rn $SK/templates/examples/. ui/ && cd ui
cp <您下載的 stud 紋理> stud.png && cp -r $SK/styles .     # stud 紋理來自 ui-resources.com
cp <參考> ref.png && python3 $SK/scripts/read_reference.py ref.png      # -> style.css (草稿)
python3 $SK/scripts/copy_icons.py icons.json --pack <您的圖示包> && python3 build.py   # -> *.html + index.html
python3 -m http.server 8870 --bind 127.0.0.1    # run_in_background；或使用下方的 launch.json 條目 + preview_start

遊戲儲存庫中的 .claude/launch.json（然後使用 mcp__Claude_Browser__preview_start {name: "ui"}）：

{ "version": "0.0.1", "configurations": [
  { "name": "ui", "runtimeExecutable": "python3",
    "runtimeArgs": ["-m", "http.server", "8870", "--bind", "127.0.0.1", "--directory", "ui"], "port": 8870 } ] }

編輯 build.py（它是唯一真相來源；切勿手動編輯產生的 .html 檔案）。最重要的規則：

• 1920x1080 舞台，絕對像素；共享元件（plate, panel, card, T, I），使同級元件共享一種處理方式；僅顏色變化。樣式來自標記：kit.css（結構）-> styles/<preset>.css（使用 UI_STYLE=glass python3 build.py 切換）-> style.css（此遊戲）。?style=glass 可即時預覽。
• 匯出標記：grp(name, html, anchor) = 一個錨定到螢幕邊緣的頂層 Roblox 框架；每個動態標籤/圖示/按鈕上使用 name=；sub(..., btn=True, opens='Shop')；使用 hid=True 表示已匯出但隱藏的狀態。PIPELINE.md 第 2 節有完整表格。
• 所有狀態在 states.html 上；手機佈局（hud_phone.html）；每個執行階段元素（提示、確認、獎勵、教學、公告板）在 templates.html 上；一旦有實際遊戲截圖，就在情境中展示這些片段。
• 行內 style="..." 中不能有雙引號；不能有名為 Active/Visible/Position... 的元素；對遊戲會切換的項目使用 hid（透明度 0），絕不使用 display:none。
• 自我檢查：在瀏覽器面板中使用 ?check 打開每個頁面（checkOverflow() 必須回傳無溢出且無損壞圖片）；渲染 2 張無頭截圖（REVIEW_LOOP.md）並檢查它們。

5. 停止：開發者檢查

在第一輪中展示 style.html 與第一個畫面，然後展示其餘部分（REVIEW_LOOP.md）。等待明確的「是」。每次修正：找出通用規則，將其寫入 LESSONS.md（規則，然後原因），全局套用，用一句話告訴開發者您修正了什麼。在獲得批准之前，不要進行任何 Roblox 工作。

6. 匯入 Roblox（獲得批准後）

完整細節：PIPELINE.md。從 ui/ 資料夾（伺服器正在執行）開始：

# 僅首次匯入：Luau 執行階段 + 建構器（然後將 "<Gui>" 替換為 ../roblox/ui/client/UI.luau 中的 rbx.json "gui"）
mkdir -p ../roblox/ui/client && cp -n $SK/templates/luau/*.luau ../roblox/ui/ && cp -n $SK/templates/luau/client/*.luau ../roblox/ui/client/
rm -f ../roblox/ui/LoadingScreen.client.luau ../roblox/ui/CrateRoll.luau   # 這些檔案位於 ReplicatedFirst / ReplicatedStorage
node $SK/scripts/export.mjs              # 佈局 JSON + 每個點陣圖元件的 2x 透明 PNG -> rbx/out/
python3 $SK/scripts/gen.py               # Data_<Screen>.luau, Data_Templates, Data_Manifest -> luau_out; 美術 -> rbx/out/upload
python3 $SK/scripts/mock.py && node $SK/scripts/mockshot.mjs   # 離線 Roblox 語義渲染：每個畫面平均差異 1-3
python3 $SK/scripts/ledger.py 20         # 接下來要上傳的 URL；使用 mcp__Roblox_Studio__upload_image(+studio_id) 上傳，
                                         # 然後：echo '<result json>' | python3 $SK/scripts/ledger.py 20；重複直到剩餘 0 個
python3 $SK/scripts/assets.py            # AssetIds.luau
python3 $SK/scripts/bundle.py            # rbx/out/<Gui>Build.rbxmx

上傳規則：每次最多 20 個，當遊戲是群組擁有時，打開該群組的場所，絕不重新上傳分類帳中已有的檔案，偵測外部 ID。然後在 Studio 中透過 robloxstudio： 刪除舊的 ServerStorage.<Gui>Build -> 使用 import_rbxm 將 .rbxmx 匯入 ServerStorage -> require(game.ServerStorage.<Gui>Build.Builder).build() -> 啟用 gui，Builder.fit() 兩次，停用。 切勿使用 set_script_source（會搞亂 \n）；始終使用 .rbxmx + import_rbxm。 連接遊戲程式碼（Controller 啟動 UI + UIKit；僅在使用 gui 屬性 PreviewMode 時使用示範數字）： client/UI.luau（開啟/關閉/返回，使用具有 Button/Opens 屬性的生動按鈕、Escape、遮罩、彈出佇列、計數） + UIKit.luau（範本合約：複製、使用陰影雙胞胎進行 set、圖示、長條、複數/冠詞、worldLabel） + NumberFormat.luau。遊戲程式碼複製範本；絕不使用 Instance.new 建立外觀。記錄對已匯入畫面所做的每次執行階段變更（PIPELINE.md 第 8 節）。

7. 在 Studio 中驗證

請參閱 VERIFY.md，依序執行：無空白圖片；適應比例；在 1920x1080 / 1366x768 / 844x390 解析度下執行 PropertySweep.atSizes；編輯模式測試（複製 gui，要求複製的 UI，驅動，UI.destroy()，Archivable=false）；僅在需要時進行遊玩測試（檢查沒有其他人的遊玩測試正在執行）：洋紅色截圖不代表 UI 損毀；在 AbsolutePosition + size/2 +58 px 處進行實際點擊；手機裝置設定檔；快速點擊測試；列表原地更新。對每個客戶端檔案執行 luau-analyze --mode=nonstrict；執行 check_copies.py 以確保 Studio 中的副本與磁碟上的副本相符。

8. 疊代

新的回饋 -> LESSONS.md -> HTML -> 批准 -> 僅匯出已變更的頁面 -> gen -> 分類帳僅上傳新美術 -> bundle -> Builder.buildScreen("<Screen>")（一個面板在原位）或 build() -> fit -> 驗證。

絕不

使用表情符號或第二個圖示包；AI 生成的圖示；在授權禁止 AI 使用時將圖示包檔案傳送給任何模型；將文字嵌入圖片；在獲得批准前匯入；手動編輯 Data_*.luau；使用 set_script_source；在真實遊戲客戶端執行時寫入示範值；自動領取獎勵；在獎品上繪製線條或標記；在此技能資料夾內包含遊戲特定的 ID 或名稱。