design

成果物を Subframe に保存する場合は、このワークフローを使用します。実装には develop を、既存のデザインシステムを Subframe に取り込むには import を使用します。

Subframe を使う理由とタイミング

Subframe を使う理由。 デザインをコードブランチの外に永続的に保存し、チームメイトが見つけて、レビューし、再確認できるようにします。キャンバス上で複数のバリエーションやマルチ画面のフローを並べて比較できます。コードを変更する前に、チームメイトからコメントを集められます。デザインのすぐそばにあるデザインドキュメントに、決定事項とその理由を記録できます。Subframe を信頼できる情報源として使う場合は、そのテーマとコンポーネントからコードを同期します。

使用するタイミング： 方向性を検討する、選択肢を比較する、レビューや共有可能な成果物を求める、複数の画面やデザインシステムを変更する場合です。

使用しないタイミング： 既存の UI に対する小さな修正や、コードのみの動作変更の場合は、ユーザーが Subframe を求めているか、プロジェクトでデザインを Subframe に保存している場合を除き、コードを直接編集します。

手順

1. 変更せずに残す部分と、変更する部分を特定します。既存のデザインの場合は、実際のコンテンツを読み、レンダリングされた外観を確認します。ウェブサイトやコードベースを参照する場合は、ホストのブラウジングツールやファイルツールを使って、関連するソースとスクリーンショットを収集します。既存の UI を再現するうえで、文章による説明だけでは根拠として不十分です。
2. 依頼を満たす最小限の操作を選びます。既存のページやスニペットはその場で編集し、完全なコピーを作成する場合は複製します。新しいデザインや大幅に異なる方向性には生成を使用します。再利用可能なコンポーネント、ページ構成、使用例、または文書によるガイダンスのどれが意図された成果物かを判断します。
3. 生成する前に、参照資料を準備します。実際のソース、画像、または Subframe のリソースを渡し、何を維持し、何を変更するかを説明する使用上のメモを添えます。ソースコードが関連する子コンポーネントやスタイルに依存している場合は、それらも含めます。これらの指示は生成ブリーフに記載します。ジェネレーターは会話や推論を参照できません。
4. 依存先を、それを利用する側より先に完成させます。ページに不足している再利用可能なプリミティブが必要な場合は、まず design_component で作成します。プリミティブを独立して完成させてから、それらを組み込むコンポーネントを作成し、その後にページを生成します。一度限りのページ構成はインラインにします。ページの再現を、依頼されていないコンポーネントライブラリの再構築に発展させないでください。
5. 依頼された画面と編集を完成させてから、反映された内容を確認します。下部のセクション、影響を受けるレスポンシブレイアウト、関連する状態も含め、スクリーンショットを参照資料および依頼された変更と比較します。報告する前に、コンテンツの欠落、クリッピング、間隔、タイポグラフィの不一致を修正します。

ページとフロー

各バリエーションのブリーフは、それだけで完結するようにします。レイアウトや強調点の具体的な違いを説明し、別のバリエーションをコピーするよう指示しないでください。ユーザーが1回の呼び出しで作成できる数を超えるバリエーションを求めた場合は、同じキャンバス上で複数回の呼び出しに分け、指定された数を作成します。

フローを作成する場合は、最初の画面で共通のシェルを確立します。wait_for_jobs が完了を報告したら、ページが実際に存在することを確認し、その ID を sourcePageId として次の画面にすぐ使用します。複数の候補が作成された場合は、一貫性のある出発点を自分で選び、どの方向性を引き継いだかを伝えます。ナビゲーションとレイアウトを維持しながら、次の画面の違いを指定します。ユーザーの選択を待たないでください。

既存のデザイン

スタイルの変更には update_node_styles を、コンテンツや構造の変更には edit_page または edit_snippet を使用します。既存のクラスとサブツリーを起点にすることで、無関係なレイアウト、子要素、コピーを維持します。置換する場合は、維持するノードの data-node-id を残し、新規または挿入するノードには ID を付けません。古い ID によるエラーが発生したら、対象のリソースを再読み込みし、古いマークアップを再試行するのではなく、編集内容を組み立て直します。

変更内容が共有コンポーネントに関わる場合は edit_component を使用します。影響を把握するため、代表的な使用箇所を確認します。ページ固有の調整は、そのページのインスタンスまたは構成に加えます。

コメントに基づいて編集する場合は、各スレッドを現在の要素と照合し、どのフィードバックに対応したかを記録します。要素がなくなっているスレッドは、以前の ID を使って編集するのではなく、内容を解釈する必要があります。

テーマとデザインのガイダンス

スタイルを変更する場合は、既存のトークンを更新し、現在のデザインに意図した見た目を反映させます。意味上の役割とエイリアスを維持し、似た見た目のトークンを別に作成しないでください。影響を受けるモードで、代表的なページとコンポーネントを確認します。削除や置換に必要な確認を求める前に、具体的なトークンの対応関係を準備します。外部のトークンソースを採用するには import を使用します。

将来のデザイナーが UI から推測できない判断事項、つまりパターンを使う場面、コンテンツ上の制約、製品固有の例外をデザインドキュメントに記載します。既存のガイダンスを更新し、埋め込み例を維持します。コンポーネント API が不要な再利用可能な例や構成には design_snippet を使用します。すべてのページに対して、ドキュメントや例を無理に作成しないでください。

レビューと復旧

ジョブの完了後、変更したページには screenshot_page を、変更したコンポーネントには screenshot_component を使用します。スニペットについては、既存ページでの使用箇所があればそこで確認します。確認だけのためにページを追加作成しないでください。視覚的な確認ができていない箇所があれば、その旨を明示します。

編集が成功したと判断する前に、パーサーの警告と適用結果を確認します。コンテンツが削除または正規化によって失われた場合は、意図する静的デザインをより直接的に表現します。「問題が発生しました」というマスクされたエラーが表示されても、変更がなかった証拠にはなりません。作成を再試行する前に、作成先とジョブの状態を確認します。不足している作業のみを再試行し、失敗が続く場合は、対象リソースと返されたジョブ ID を報告します。