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」、ライブの場合は「window」「interactive」も含む）、その出力を使用します。

2. リクエストの意図。

   ユーザーがしたいこと	出力
   見た目を確認する、レイアウト、間隔、テキスト、状態、ロケールをチェックする	PNG
   ライトとダーク、フレームありとなしを並べて比較する、またはトグルで切り替える	ギャラリー
   クリック、タイプ、トグル、ナビゲート、シートやアラートを開く、フローを確認する	ライブウィンドウ

   リクエストが複数の行に一致する場合、インタラクションが優先されます。クリックや入力後にのみ表示されるものは、ライブウィンドウが必要です。

3. 画面全体またはフロー、明確なシグナルがない場合。 対象が画面全体や複数ステップのフローであり、上記のルールが適用されない場合（例：「チェックアウト画面をプレビュー」）、PNG、ギャラリー、ライブウィンドウのいずれかを尋ねる質問を1つ行います。

4. デフォルト。 明確なシグナルがない単一のコンポーネントの場合、fit サイズのライトPNGを1つ生成します。これは最も高速な出力であり、自分で検査できる唯一の出力です。その後、他の2つの出力を提供する行を1行追加します。

ルール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を実行しません。モジュール、アセット、またはStringカタログを単一ファイル契約に安全に適応できない場合は、利用可能なプロジェクト固有のワークフローを使用するか、具体的な制限を述べてください。プロダクションアプリを静かにリンクしたり、そのライフサイクルを実行したり、ビルド設定を変更したりしないでください。

本物のフィクスチャを準備して確認した後、選択したパスを（プロジェクトルートからの相対パスで）保存します：

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 はレンダリングにのみ適用されます。ギャラリーはすべてのバリアントを含み、ライブプレビューにはネイティブコントロールがあります。出力親ディレクトリは存在している必要があります。bootstrapは直接の render.sh や gallery.sh ヘルパーとは異なり、既存の出力を置き換えるのではなく拒否します。再レンダリングするには、新しいファイル名を選択するか、以前のタスク所有のアーティファクトを先に削除してください。相対的な出力パスはプロジェクトルートから解決されます。--mode live はビルドのみ行います。起動と検査のルールは references/live.md にあります。

変更されたソースまたはフィクスチャのハッシュにより実行が停止します。実際のコンポーネントを再検査し、フィクスチャを更新してから、選択したパスで configure --replace を実行するか、ライブウィンドウを反復処理している場合は refresh を実行します。サポートする定義/リソースの変更も検査してください。ハッシュはプライマリソースと自己完結型フィクスチャをカバーし、依存関係グラフ全体はカバーしません。コンポーネントの切り替えは、設定を置き換える前に初回使用の適応ワークフローに従います。既存のフィクスチャへのユーザー編集は保持してください。

フィクスチャ契約と直接ヘルパー

レンダラーは、1つの自己完結型Swiftファイルをそのヘルパーとともにコンパイルします。そのエントリポイントは：

import SwiftUI

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

ヘルパーは、コンパイラがサポートする場合はSwift 6言語モードで厳密な並行性を有効にしてコンパイルし、それ以外の場合はSwift 5モードでコンパイルします。Swift 5プロジェクトから適応したフィクスチャが並行性診断（Sendable、アクター分離）だけで失敗する場合、コンポーネントを書き換えてそれらを満たす必要はありません。run または refresh に --swift-version 5 を渡すか、直接ヘルパー用に PREVIEW_SWIFT_VERSION=5 を設定し、プレビューがSwift 5モードでビルドされたことを伝えます。

合成データと固定された初期状態を使用します。静的レンダリングには不活性なアクションを使用します。ライブフィクスチャは、ビューローカルな状態変更、検証、ナビゲーションを実装できます。フィクスチャにコンポーネントの必要なローカルビュータイプを含めます。実際のSwiftUIコントロール（Form、TextField、SecureField、Toggle など）は保持します。認証情報ストア、ネットワークコール、永続化、ビューより長く存続する処理はフィクスチャから除外します。ライブフィクスチャは、短いインメモリ遅延でサービスをシミュレートしても構いません。

プロジェクトに既に #Preview フィクスチャがある場合、そのビュー構築と入力を再利用します。このスタンドアロンフィクスチャで #Preview マクロや @main App をコンパイルしないでください。コンポーネントをレンダリングするためだけにプロジェクト設定を書き換えないでください。

同じフィクスチャ契約は、macOS用にコンパイルされるSwiftUIコンポーネントであればプロジェクト間で機能します。UIKit専用コンポーネントにはiOSシミュレーターワークフローが必要です。ヘルパーは任意のプロジェクトモジュールを自動的にリンクしたり、アセットやStringカタログをコンパイル/コピーしたりしません。可能な場合は自己完結型の値ビューを抽出します。コンポーネントがプロジェクトモジュールやバンドルを必要とする場合、このスタンドアロンコマンドには明示的に適応されたビルドが必要であることを説明してください。ロケール注入が欠落した翻訳やリソースを提供するとは主張しないでください。

レンダリングと検査

現在のタスクに適したパスを使用します。このスキルの場所からスキルディレクトリを解決し、すべてのパスを引用符で囲み、最初に出力親ディレクトリを作成します。次を呼び出します：

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の整数で、1ポイントあたり1ピクセルでレンダリングされるか、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 x 高さ+88になります。その信号機は描画された形状です。実際のウィンドウを作成したり、ネイティブウィンドウのクロームを検証したりしません。

利用可能なローカル画像ビューアで生成された画像を検査してから、視覚的な結果を報告します。コンテンツがない、またはクリップされている場合は、最初にフィクスチャのレイアウトとビューポートを確認します。プロダクションアプリを静かに起動するのではなく、ウィンドウ、アプリのライフサイクル、利用できないリソースが必要なコンポーネントについては停止して説明します。

ギャラリーとライブウィンドウ

さらに2つの出力が同じフィクスチャ契約を使用します。それぞれを生成する前に、リンクされたリファレンス全体を読んでください。それぞれに出力パス、起動、検証とみなされるものに関するルールがあります。

• 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 が指定されていない限り、アプリ自体を開きます。インタラクティブな要素を操作して検証してください（クリック、入力、フォーカス変更）。そのようなツールがない場合は、コントロールが操作されなかったことを伝えてください。

その他のエージェント（Cursor、Codexなど）。 プラットフォームがPNG、HTML、アプリの起動を処理する方法に従ってください。通常、画像を表示したりブラウザで開いたりするための専用のツールがあります。

さらなる情報

• references/ ディレクトリには、ギャラリー、ライブプレビュー、トラブルシューティングに関する詳細なドキュメントが含まれています。
• フィクスチャの適応に関するベストプラクティスについては references/fixtures.md を参照してください。
• 一般的な問題と解決策については references/troubleshooting.md を参照してください。