kvyatkovskys/swiftui-component-preview

SwiftUI 元件預覽

從一個小型、確定性的 SwiftUI 測試用程式建立元件渲染圖。需要 macOS 14 或更新版本以及 Xcode 15 或更新版本 (Swift 5.9+)；不需要 Swift 6。專案導入、HTML 圖庫以及即時建置器也需要 Python 3.8 或更新版本 (僅限標準函式庫)。選擇 PNG 進行靜態檢查，選擇圖庫進行圖片比較，或選擇原生視窗進行真實的測試用程式互動。這些輔助工具不提供 Xcode Canvas 或熱重載功能。

選擇輸出

在建立任何東西之前，依此順序決定輸出：

1. 明確的詞語。 如果請求或技能參數以「png」、「gallery」或「live」開頭或命名 (對於 PNG 也包含「screenshot」、「render」；對於 live 也包含「window」、「interactive」)，請使用該項。

2. 請求的意圖。

   使用者想要	輸出
   查看外觀、檢查佈局、間距、文字、狀態、語系	PNG
   比較淺色和深色，或包含/不含框架，並排或切換顯示	Gallery
   點擊、輸入、切換、導航、開啟工作表或提示框、檢查流程	Live window

   當一個請求符合多行時，互動優先：任何需要點擊或輸入後才會出現的內容都需要即時視窗。

3. 整個畫面或流程，無明確信號。 如果目標是整個畫面或多步驟流程，且上述規則均不適用，例如「預覽結帳畫面」，則提出一個問題，提供 PNG、gallery 和 live window 三種選項。

4. 預設。 對於單一元件且無明確信號，產生一個淺色 PNG，尺寸使用 fit。這是最快的輸出，也是唯一您可以自行檢查的輸出。然後添加一行提供其他兩種輸出選項。

規則 1、2 和 4 無需提問即可執行。當請求多個輸出時，從相同的配置產生所有輸出。請勿將選擇儲存在 .swiftui-preview/config.json 中：它屬於請求，而非專案。

在專案中首次使用

下方指令中的 <skill-directory> 是包含此 SKILL.md 的目錄；從已安裝的位置解析它。Claude Code 在技能載入時將其聲明為技能的基礎目錄 (${CLAUDE_SKILL_DIR})；在 Codex 和其他代理程式中，請使用讀取此檔案的路徑。不需要開發者特定的路徑或設定。使用使用者的當前專案根目錄並執行唯讀探索：

python3 "<skill-directory>/scripts/bootstrap.py" discover --root "<project-root>"

探索會報告 SwiftPM 清單、Xcode 專案/工作區、SwiftUI 原始碼、#Preview 的存在以及文字平台證據。它永遠不會評估清單、執行外掛程式、建置或修改專案。會跳過巢狀的依賴項/建置目錄和符號連結。缺少平台元資料表示未知，而非不支援。使用請求和發現的路徑來選擇預期的專案和元件。僅在選擇仍然真正模稜兩可時才提問；當請求的原始碼很明確時，僅憑多個標記並不需要強制提問。

在建立測試用程式之前，請讀取所選的實際原始碼、其現有的 #Preview 結構以及必要的區域定義。技能代理程式會在首次預覽請求時執行此改編；如果代理人可以安全地執行，請不要停留在指示使用者手動改編的說明上。保持元件的實際視圖層級、控制項、樣式和輸入。提取其值視圖並包含所需的區域定義，將服務依賴項替換為合成值和區域動作。請勿用相似的外觀畫面、通用示範或捆綁的範例來替代請求的元件。這些範例僅說明測試用程式的 API。

將改編後的測試用程式儲存在使用者的專案內，例如 .swiftui-preview/fixtures/StatusCard.swift。切勿將專案原始碼複製到共享的已安裝技能中。不要包含 @main、應用程式委派、生產組合根、#Preview 巨集或生產服務。configure、run 和 refresh 會將測試用程式掃描為文字，並在出現 @main、#Preview 或 import UIKit 時拒絕它 (包括註解內)；請將這些字串也排除在註解之外。錯誤訊息會指出符合的標記及其行號。在執行測試用程式之前檢查整個測試用程式：可執行的 Swift 程式碼以正常的呼叫者權限執行；此輔助工具不是沙箱。配置雜湊無法保證視覺保真度或沒有副作用。

如果明確的 UIKit 或僅 iOS 的 API 使元件與 macOS 不相容，請使用可用的 iOS 模擬器 / Xcode Canvas 工作流程，或報告確切的不支援依賴項。通用的 macOS 主機不會執行 UIKit。如果模組、資產或字串目錄無法安全地改編為單一檔案合約，請使用可用的專案特定工作流程或說明具體的限制。請勿默默地連結生產應用程式、執行其生命週期或變更其建置配置。

在準備並審查真實的測試用程式後，儲存選定的路徑 (相對於專案根目錄)：

python3 "<skill-directory>/scripts/bootstrap.py" configure --root "<project-root>" \
  --project "Package.swift" --source "Sources/StatusCard.swift" \
  --fixture ".swiftui-preview/fixtures/StatusCard.swift" --component StatusCard

--project 也接受相對的 .xcodeproj 或 .xcworkspace 目錄；init 是 configure 的別名。添加 --live-fixture "<relative path>" 以註冊一個單獨的有狀態測試用程式，用於即時建置 (請參閱 references/live.md)。有版本的 .swiftui-preview/config.json 僅儲存相對路徑、元件名稱、平台 macos 以及所選原始碼和改編後測試用程式的 SHA-256 雜湊。它會隨專案一起移動，並且使用者可以提交它；除非被要求，否則不要執行任何 Git 操作。除非在檢查和改編後使用 configure --replace 明確取代，否則現有配置將保留下來。選定的路徑和配置必須存在於根目錄內，不能有符號連結或目錄遍歷。

在 configure 成功後，如下所述使用 run 產生第一個預覽。後續章節中的直接輔助工具適用於一次性且沒有儲存配置的測試用程式。

後續預覽

當配置存在時，檢查它並使用 run。它會驗證架構、路徑和雜湊，然後使用固定的引數位置分派已知的輔助工具：

python3 "<skill-directory>/scripts/bootstrap.py" run --root "<project-root>" \
  --mode render --output "/absolute/task-output/card.png" \
  --width 480 --height 320 --locale en_US --theme light --frame

使用 --mode gallery 搭配 .html 輸出，或使用 --mode live 搭配新的 .app 輸出。--theme 和 --frame 僅適用於渲染；圖庫包含所有變體，即時預覽則有原生控制項。輸出父目錄必須存在；與直接 render.sh 和 gallery.sh 輔助工具不同，bootstrap 會拒絕已存在的輸出而非取代它們；要重新渲染，請選擇一個新檔名或先刪除舊的任務擁有的工件。相對輸出路徑從專案根目錄解析。--mode live 僅建置；啟動和檢查規則在 references/live.md 中。

變更的原始檔或測試用程式雜湊會停止執行。重新檢查實際元件，更新測試用程式，然後使用選定的路徑執行 configure --replace，或者當即時視窗正在進行迭代時執行 refresh。同時檢查支援定義/資源的變更：雜湊涵蓋主要原始碼和自包含的測試用程式，而非整個依賴圖。在取代配置之前，切換元件需遵循首次使用改編工作流程。保留使用者對現有測試用程式的編輯。

測試用程式合約和直接輔助工具

渲染器會編譯一個自包含的 Swift 檔案及其輔助工具。其進入點為：

import SwiftUI

@MainActor
enum PreviewFixture {
    static func makeView() -> some View {
        Text("Example")
    }
}

當編譯器支援時，輔助工具會以 Swift 6 語言模式並啟用嚴格的並行性進行編譯，否則以 Swift 5 模式編譯。當從 Swift 5 專案改編的測試用程式僅因並行性診斷 (Sendable、actor 隔離) 而失敗時，請不要重寫元件以滿足它們：將 --swift-version 5 傳遞給 run 或 refresh，或為直接輔助工具設定 PREVIEW_SWIFT_VERSION=5，並說明預覽是以 Swift 5 模式建置的。

使用合成資料和固定的初始狀態。對於靜態渲染使用惰性動作；即時測試用程式可以實現視圖局部狀態變更、驗證和導航。在測試用程式中包含元件所需的區域視圖類型；保留真實的 SwiftUI 控制項，例如 Form、TextField、SecureField 和 Toggle。將憑證儲存、網路呼叫、持久化以及在視圖之外持續存在的工作排除在測試用程式之外；即時測試用程式可以使用短暫的記憶體內延遲來模擬服務。

當專案已經有 #Preview 測試用程式時，重用它們的視圖結構和輸入。請勿在此獨立測試用程式中編譯 #Preview 巨集或 @main App。請勿僅為了渲染元件而重寫專案配置。

相同的測試用程式合約適用於為 macOS 編譯的 SwiftUI 元件的不同專案。僅 UIKit 的元件需要 iOS 模擬器工作流程。輔助工具不會自動連結任意專案模組或編譯/複製資產和字串目錄。在可行的情況下提取自包含的值視圖。如果元件需要專案模組或套件，請說明此獨立命令需要一個明確改編的建置；不要聲明語言環境注入可以補充缺少的翻譯或資源。

渲染與檢查

使用適合當前任務的路徑。從此技能的位置解析技能目錄，引用每個路徑，並先建立輸出父目錄。執行：

bash "<skill-directory>/scripts/render.sh" \
  "/absolute/path/Fixture.swift" "/absolute/path/component-light.png" \
  480 320 light en_US

引數分別是測試用程式、輸出 PNG、內容寬度、內容高度、外觀 (light 或 dark) 以及語言環境識別碼。寬度和高度是 1 到 4096 的整數，以每點一像素的方式渲染，或使用 fit。現有的輸出檔案會以原子方式取代；選擇任務擁有的路徑。當外觀比較有用時，使用 dark 和一個不同的檔名重複執行。語言環境僅設定 SwiftUI 的環境；如果這是測試的一部分，請在測試用程式中明確選擇 RTL 版面方向。

選擇視窗尺寸。 根據元件大小調整，而不是根據範例數字。對於全螢幕，使用目標視窗或裝置的點數尺寸。對於一行、卡片或控制項，傳遞其實際容器的寬度，高度使用 fit，例如 390 fit；渲染器會在每個適合的軸上測量測試用程式的理想大小，並將 render: fitted content size WxH 輸出到 stderr。fit fit 適用於本質上大小固定的控制項，但圍繞 Spacer、maxWidth: .infinity 或 ScrollView 建立的視圖在適合的軸上會縮小到其最小值，因此請為這些情況提供一個數字。run --mode render 接受 --width fit 和 --height fit；畫廊和即時預覽需要數字，因此在這些地方重用報告的大小。

僅在請求或對呈現有用時才附加 --frame。它會在固定內容視窗外部添加一個裝飾性的標題列和周圍的內邊距：輸出尺寸變為寬度 + 48 乘以高度 + 88。其交通號誌燈是繪製的形狀。它不會建立真實的視窗或驗證原生的視窗邊框。

在報告視覺結果之前，使用可用的本地圖片檢視器檢查產生的圖片。如果內容缺失或裁剪，首先檢查測試用程式的佈局和視窗尺寸。對於需要視窗、應用程式生命週期或不可用資源的元件，請停止並解釋，而不是默默地啟動生產應用程式。

畫廊和即時視窗

另外兩種輸出使用相同的測試用程式合約。在產生其中任何一個之前，請完整閱讀連結的參考文件；每個都有關於輸出路徑、啟動以及什麼算是已驗證的規則。

• HTML 主題畫廊，當使用者想要比較淺色/深色或切換裝飾性框架時：使用 run --mode gallery，或直接使用 scripts/gallery.sh。請參閱 references/gallery.md。
• 即時原生視窗，用於真實的按鈕、文字輸入、焦點和導航：使用 run --mode live，或直接使用 scripts/live.sh。它會建置一個 .app 但不會啟動它。一個具有惰性動作的靜態測試用程式在點擊時不會顯示任何內容；references/live.md 說明了何時使用 configure --live-fixture 添加一個單獨的有狀態測試用程式。一個開啟的視窗永遠不會擷取程式碼變更：更新測試用程式後，refresh 會在同一路徑重新建置應用程式，關閉舊視窗，然後重新開啟它 (同一份參考文件)。

呈現結果

在向使用者展示之前，先自行檢查每個工件，然後使用當前代理程式提供的任何方法進行呈現。使用會話中實際可用的工具；不要假設此列表中存在某一個。

輸出位置。 使用任務擁有的目錄。當客戶端只能顯示專案內的檔案時，寫入 <project-root>/.swiftui-preview/artifacts/ (先建立它)，除非被要求，否則不要對其執行任何 Git 操作。

Claude Code。

• PNG：使用「Read」工具讀取檔案以檢查圖片。要顯示它，如果存在，請使用會話的檔案呈現或預覽工具；否則，以連結形式給出絕對路徑，並在使用者要求查看時執行 open "/absolute/path/component-light.png"。內聯 Markdown 圖片在終端機中無法渲染。
• HTML 畫廊：使用可用的瀏覽器或預覽工具使用其 file:// URL 開啟它，或執行 open "/absolute/path/component-gallery.html"。在報告它們已驗證之前，請透過瀏覽器工具使用主題和框架控制項；如果沒有此類工具，請說明控制項未經測試。
• 即時應用程式：當啟動在請求範圍內時，執行 open "/absolute/path/SwiftUI Preview.app"；refresh 會自行開啟應用程式，除非給定了 --no-launch。在報告互動已驗證之前，驗證互動性