develop

アプリケーションに Subframe のデザインを実装します。同期に関する質問には、ファイルを変更せず、以下の境界について説明してください。

信頼できる情報源を選ぶ

コードを書く前に、アプリケーションのパッケージにある .subframe/sync.json、同期済みディレクトリ、コンポーネントのインポート、テーマファイル、ルート、package.json を確認します。証拠がどのモデルを支持するかを明示してください。

• Subframe がテーマとコンポーネントを管理します。 同期設定と、アプリで使用されている生成済みコンポーネントがあれば、このモデルが確立されます。これらのコンポーネントを使ってページを構築してください。見た目の変更は Subframe で行って再同期し、アプリケーションの動作はコードで管理してください。必要なコンポーネントやトークンが Subframe にない場合は、デザインで追加してからコードに取り込んでください。見た目だけを似せたものを独自に作成したり、生成済みのスタイルを修正したりしないでください。
• コードベースがテーマとコンポーネントを管理します。 MUI、shadcn、カスタムコンポーネントなどの確立されたライブラリがあり、Subframe の同期がない場合は、このモデルが確立されます。Subframe のページは視覚的な参考として扱ってください。アプリのコンポーネントとトークンを使って実装し、それらに相当するスタイルに置き換えてください。Tailwind クラスを貼り付けて、既存の仕組みを迂回しないでください。ユーザーが採用を選ばない限り、Subframe を初期化したり同期したりしないでください。コードのシステムを Subframe に取り込むよう求められた場合は、今後のデザインにそのシステムを忠実に反映できるよう、import を使用してください。
• 混在、または不明確です。 両方のモデルと、それぞれを裏付ける証拠を、プロジェクトとの不一致も含めて明示してください。対象画面には、確立されている境界に従ってください。未解決の選択によって使用するコンポーネント、テーマ、ファイルが変わる場合に限り、確認してください。

アプリに Subframe のセットアップがなく、ユーザーが Subframe のコンポーネントを使いたい場合、または init/sync が失敗した場合に限り、setup.md を読んでください。

最小限のトークンでコードを取得する

実装するページについて get_page_info を一度取得し、screenshot_page を確認してください。ページのソースとして files[].fileName と files[].contents を使用します。既定のクリーンなエクスポート設定を維持してください。実装にノード ID やエディターのメタデータは不要です。ページのインポート先はプロジェクトのエクスポート設定（通常は設定済みのインポートエイリアス）に従います。ローカルのセットアップ設定に照らして解決してください。

Subframe モデルでは、コードをコンテキストに通さずディスクに直接書き込むため、不足しているコンポーネントには CLI sync を、テーマファイルには init を使用してください。実装に必要なローカルコンポーネントの API だけを読み取ってください。sync ですでに利用できるコードを取得するために、すべてのコンポーネントについて get_component_info を呼び出さないでください。

不足しているコンポーネントは、たとえば npx @subframe/cli@latest sync Button Alert のように、名前を指定して同期してください。すでに存在するコンポーネントを自動で再同期しないでください。再取得するのは、デザイン更新を依頼された場合に限ります。通常の作業で sync --all や引数なしの sync を使うのは避けてください。これらはすべてを同期します。名前を指定した同期には依存関係も含まれるため、それらの変更も確認してください。

ページのコードをアプリのコードに反映する

実装はアプリのルートとレイアウト構造に配置します。アプリのシェル、ルーティング、サーバー／クライアントの規約を再利用してください。

• コンポーネントのバリアントと props の型を、意図する状態に合わせます。ローカルの型と既存の使用例を確認し、コードベースのモデルにおける同等の API に対応付けてください。
• 宣言済みの props または children を通じてスロットを埋め込み、複合コンポーネントの構造を維持します。ページの構成はコンポーネントの外側に配置し、コンテンツを挿入するために生成済みの内部実装を編集しないでください。
• ローカルのアイコンのインポート方法と props の型に従ってください。Subframe モデルでは、ページ専用のアップロード済みアイコンモジュールが不足している場合、get_icon_info から作成してください。そのアイコンのためにライブラリ全体を同期しないでください。コードベースモデルでは、アプリのアイコンライブラリとアセットの規約を使用してください。
• アプリのアセットパイプラインを通じて画像の URL とアセットを解決します。トリミング、アスペクト比、意味のある代替テキストを維持し、アセットが読み込まれることを確認してください。
• プレースホルダーの文言と繰り返しの JSX を実際のデータに置き換え、マッピングした項目には安定したキーを指定します。既存のデータ取得と書式設定の規約を使用し、利用できないデータはバックエンドをでっち上げずに明示してください。

Subframe モデルでは、生成されたコンポーネントファイルを変更しないでください。カスタムコンポーネントのロジックは index.tsx に配置し、そのラッパーに // @subframe/sync-disable を記述します。生成済みコンポーネントは、ビジュアル更新に使える状態にしておいてください。すでに無効化されているファイルには、変更を手動でマージしてください。

動作を実装する

ナビゲーション、フォーム、バリデーション、選択、ダイアログ、読み込み中、空、エラーの各状態を、アプリ既存のパターンを通じて接続してください。静的なページのエクスポートだけでは、実行時の動作は実装されません。

ユーザーが意図する動作の参考として Subframe のプロトタイプを指定した場合は、read_prototype_file を使って関連ファイルだけを読み、その動作を反映してください。プロトタイプはモックデータを含む別個のスキャフォールドであり、採用すべきコードとは限りません。

アニメーションやモーションを実装する場合は、ゼロから作る前に、モーションライブラリの search_motion_examples と get_motion_example ツールを使い、get_motion_guidance を読んでください。

アプリで検証する

ホストのシェルツールとブラウザツールを使ってアプリを実行します。同じビューポート、テーマ、コンテンツ、状態で screenshot_page と比較してください。初期画面だけでなく、下部のセクション、レスポンシブレイアウト、操作も確認します。差異を修正してから、関連するビルドまたはチェックを実行してください。実行した内容と、完了できなかったビジュアルまたは動作の検証を報告してください。

後からのデザイン変更を反映する

Subframe モデルで更新を依頼された場合は、影響を受けるコンポーネントを名前で再同期します。既存の設定を使用し、コンポーネントの同期を無効にした状態で init を実行して、変更されたテーマファイルを更新してください。sync だけではトークンは更新されません。デザイン変更が完了したら、ページを再取得してください。コードベースモデルでは、ビジュアル上の変更点をアプリのコンポーネントとトークンに反映します。

可能であれば更新後のエクスポートを以前のエクスポートと比較し、以前のものがなければ実装済みの JSX とスクリーンショットと比較してください。インポート、バリアント、スロット、レイアウトクラス、アセット、文言を確認し、ローカルのコンポーネントの差分を調べてください。

フック、ハンドラー、状態、データバインディング、ラッパーのカスタマイズを維持しながら、変更箇所を既存の実装にマージします。ルートを新しいエクスポートで置き換えないでください。ビジュアルと動作の検証を繰り返してください。

キャンバスとコードの同期について説明する

CLI は sync を通じて Subframe のコンポーネントをコードに取り込み、init を通じてテーマファイルを取り込みます。ページは別途実装またはコピーされるものであり、CLI sync では更新されません。ローカルでの編集はキャンバスに自動反映されず、キャンバスでの編集も実装済みのページには自動反映されません。ページの変更を依頼されたら、再取得してマージしてください。コードを Subframe に戻す作業は明示的なデザインまたはインポートのタスクであり、継続的な双方向同期ではありません。