create-canvas

キャンバスを作成する

会話を通じて探索や反復を行うための自由形式のワークスペースを構築します。モデルはソースファイル内のコンテンツを変更します。キャンバスでは、そのコンテンツを実際に動作するものとして名前を付け、移動し、簡単に参照できるようにします。

プロジェクトから始める

• リポジトリのルール、ルート、コンポーネント API、テーマ、デザイントークン、テストを読みます。
• 新たに作成する前に、既存のキャンバスがないか確認します。
• プロジェクトのフレームワーク、コンポーネント、タイポグラフィ、デザイントークン、テーマ、アクセス制御を使用します。
• 編集、コマンド、ブラウザーアクセスに関する制限を守ります。
• スコープの変更、依存関係の追加、共有コードの変更、キャンバスの公開を行う前に確認します。
• 安全に分離できるか不明な場合は、作業を進める前に確認します。安全でないプレビューは決してマウントしないでください。
• その他の判断には妥当なデフォルトを選びます。明確な依頼をユーザーに繰り返させないでください。
• キャンバスのコードをまとめて管理します。カメラや配置のロジックをプレビュー、テストデータ、レジストリから分離します。フレームワークは構築しないでください。
• まず、安全なライブプレビューを1つ、読みやすいラベル、独立した移動ハンドルとともに用意します。マウントできることを確認します。
• 次に、レジストリと依頼されたコンテンツを追加します。その後、コピー機能、カメラ操作、既存のテーマ、保存済みレイアウトを追加します。

コンテンツはソースに保持する

レジストリは、型付けされたキャンバスアイテムのリストです。各エントリでは、安定した ID、一意で読みやすい名前、コンポーネント、安全なテストデータ、初期位置、寸法を定義します。

• レジストリを見つけやすく保ちます。アイテムの追加に、カメラやジェスチャーのコードの変更が必要にならないようにします。
• ソースの編集を通じて、アイテムの追加、複製、名前変更、削除を行います。実行時のエディター操作や削除用ショートカットは追加しないでください。
• アイテムの構成、名前、寸法、実装はソース内に保持します。ブラウザーストレージによってアイテムが作成されたり非表示になったりしないようにします。
• 保存された文字列やモデルの応答を、実行時にコードとして評価しないでください。
• 追加の依頼では既存のワークスペースを更新します。名前、ID、位置、無関係な実験内容を維持します。
• 参照先が曖昧な場合は、どのアイテムを指しているのかユーザーに確認します。
• 「別のバージョンを試して」では、元のアイテムを維持します。バリエーションごとに新しい ID、一意で読みやすい名前、独立した状態を割り当てます。
• 「このバージョンを変更して」では、そのアイテムをその場で更新します。依頼された場合にのみ名前を変更します。
• 削除の依頼では、指定されたレジストリエントリのみを削除します。共有コンポーネントや無関係な作業は維持します。
• 1つの機能を比較する場合は、その他のデータ、コンテンツ、寸法、全体テーマを同じに保ちます。
• より広範な代替案では、レイアウトの違いに名前を付けます。依頼がない限り、すべてのバリエーションを網羅する表は作成しないでください。
• 測定した境界を使って、近くの空きスペースに追加します。既存のアイテムを並べ替えたり、表示範囲をリセットしたりせず、カメラで追加項目が見えるようにします。
• コンテンツの拡張、サイズ変更、再読み込み後も位置を維持します。意図的な重なりを許可します。アイテムが重なっても、移動ハンドルを操作できる状態に保ちます。

ワークスペースをすっきり保つ

• ビューポートを無地の背景、目立たないプレビュー境界、最小限の固定コントロールで満たします。
• 各プレビューは本来の寸法を使用します。コンテンツを過度に大きなフレームへ引き伸ばさないでください。
• 装飾的なカード、バナー、背景パターンは追加しないでください。
• 各プレビューの上に、Pricing card · compact のような名前を表示します。曖昧な名前や不透明な ID をラベルとして使用しないでください。
• 名前のボタンは、ボタンらしいスタイルや別個のコピーボタンを使わずに、ボタンとして機能するようにします。
• クリック、Enter、Space、またはタッチで正確な名前をコピーします。ID、コード、URLはコピーしないでください。
• ホバー時とキーボードフォーカス時にコピー方法を説明します。ホバーだけではコピーしないでください。タッチ操作では、ホバーを必要としないでください。
• 利用可能な場合はクリップボード API を使用します。コピー成功後にのみ、「コピーしました」という簡潔なフィードバックを通知します。フィードバック表示中も名前を見える状態に保ちます。
• クリップボードにアクセスできない、または利用できない場合は、選択可能なテキストを提示します。クラッシュしたり、成功したと偽ったりしないでください。
• ラベルの横に、見える移動ハンドルを配置します。ラベルのコピーではドラッグを開始しません。ハンドルで項目を移動し、本文では移動しないようにします。
• ポインターの移動量を、現在のズームに応じたキャンバス座標に変換します。
• フォーカス中のハンドルでキーボードによる移動をサポートします。視認できるフォーカス表示と、アクセシブルな操作手順を用意します。
• ジェスチャー中も含め、キャンバスのナビゲーション領域とハンドルでは cursor: default を使用します。
• プレビュー内では、テキスト、リンク、入力欄、サイズ変更のネイティブカーソルを維持します。すべての子孫要素にカーソルルールを適用しないでください。
• パン、ズーム、全体表示、カメラのリセット、グローバルなテーマセレクター 1 つ、保存済みレイアウトを含めます。
• 既存のテーマ API を使用して、ライト、ダーク、名前付きテーマを適用します。キャンバスのコントロール、プレビュー、メニュー、ダイアログに同じテーマを適用します。
• 独自のテーマを追加したり、プレビューごとのテーマを追加したりしないでください。テーマがサポートされていない場合は、セレクターを省略し、その理由を説明します。
• ポータルのテーマを公開 API 経由で適用できない場合は、その制限を報告します。
• 要望がない限り、サイズ変更、幅のプリセット、比較配置、描画、コネクター、カタログ、プロパティエディター、複数選択、スナップ、取り消し／やり直しは省略します。
• モバイルまたはデスクトップのプレビューが求められた場合は、レジストリでその寸法を定義します。

ライブコンテンツを維持する

• 公開 API を通じて本番コンポーネントを再利用します。キャンバスに対応するために、ソース、エクスポート、フック、スタイルを変更しないでください。
• 本番コンポーネントをキャンバスコードから独立させておきます。
• 実験はキャンバス内に留めます。求められた場合にのみ本番環境へ移します。
• マウント前に、合成データ、モックサービス、安全なプロバイダー、既存のコールバックを使用して、実際のリクエストや書き込みを防ぎます。
• 個人データや本番環境の認証情報は使用しないでください。
• 安全に分離できない場合は、プレビューを省略し、その理由を説明します。iframe や別ドキュメントだけでは分離できません。
• クリック、入力、テキスト選択、ショートカット、フォーカス、入れ子になったスクロール、タッチ入力を維持します。
• 無効化および読み取り専用の例が本来持つ動作を維持します。
• 項目の移動、名前のコピー、テーマの変更、カメラの操作時に、プレビューを再マウントしたり入力内容を消去したりしないでください。
• プレビューの下書きは、再読み込み後まで保持する必要はありません。
• ポータルはネイティブのルートに配置し、画面座標上のサイズを維持します。位置調整とモーダルのフォーカス管理はライブラリに任せます。
• 必要な場合に限り、公開コンテナー API を使用します。ズームレベルが異なっても、ポータルの位置合わせとクリック可能領域が正しく機能することを確認します。
• 変換によってポータルが正常に機能しなくなる場合は、その制限を報告するか、別のプレビュードキュメントを提案します。
• ライブラリ、ブラウザー API、プレビュー DOM、ポータルルートにはパッチを適用しないでください。
• ポータル内のリンクを含め、ナビゲーションはキャンバスホストで定義します。コンポーネントのリンクやルーターの内部実装は変更しないでください。
• キャンバス項目のリンクは、ページをスクロールするのではなく、リンク先を表示します。
• それ以外のナビゲーションでは、実際のプロジェクト操作を実行したり、ワークスペースを黙って失ったりしないようにします。

ジェスチャーとプレビュー入力を分離する

• 空白領域からマウスドラッグしてパンできるようにします。
• 空白領域やプレビュー上で、Ctrl／Meta＋ホイールおよびトラックパッドのピンチによるズームに対応します。
• ホイールやピンチでズームしている間、ポインター直下のキャンバス上の点を固定します。
• ズームイン／ズームアウトボタンとキーボード操作を用意します。ズームの中心はビューポートにします。
• どちらの方向にも、ジャンプやずれのないスムーズなズームに対応します。アイテムの位置とプレビューの状態を維持します。
• ブラウザーが対応している場合は、タッチによるパンとピンチに対応します。
• キャンバスのシェルにフォーカスがあるとき、キーボードによるカメラ操作に対応します。
• すべてのキャンバスコントロールで、キーボードフォーカスを視覚的に示します。
• アイテムが画面外にある場合でも、アクセス可能な「すべてに合わせる」コントロールとカメラリセットコントロールを固定表示し、常に操作できるようにします。
• レイアウトが落ち着いた後に「すべてに合わせる」を実行します。各タイトル、ハンドル、境界を含む実際の範囲に合わせます。アイテムを並べ替えないでください。
• カメラのみをリセットします。アイテムの所属、位置、テーマ、下書きは維持します。
• キャンバス上のどこでも、プレビュー上を含め、Space＋主ボタンのドラッグと中ボタンのドラッグでパンできるようにします。
• 明示的なパン操作を、アイテムの移動や名前のコピーより優先します。
• パンした後は、コントロールを作動させたり、ラベルをコピーしたり、リンクを開いたり、中クリックによる自動スクロールを起動したりしないでください。
• インタラクティブなコントロールまたは編集可能な領域にフォーカスがある場合は、Space によるパンを開始しないでください。
• ボタンとラベルの Space による作動を維持します。プレビューの矢印キー、Escape、取り消しも維持します。
• モーダルのポータルをキャンバスのジェスチャー処理の対象外にします。フォーカス、背景の動作、ネイティブコントロールを維持します。
• 空白領域やプレビュー上で、トラックパッドの2本指パンに対応します。
• ネストされたスクロール領域がジェスチャーの方向にスクロールできる場合は、そのスクロールを許可します。できない場合は、キャンバスをパンします。
• 修飾キー付きのホイール操作とピンチによるズームを、スクロールの振り分けより優先します。その他のポータル内スクロールはネイティブの動作を維持します。
• イベントのキャンセルとタッチ操作の制限は、所有するジェスチャーに限定します。プレビューコンテンツ全体でネイティブ入力を無効にしないでください。
• ハンドルを使った1本指でのアイテム移動に対応します。通常の1本指によるプレビュー操作も維持します。
• プレビューのネイティブなジェスチャーを妨げずに、2本指でのキャンバスパンとピンチに対応します。プレビューのタッチ操作を無効にするのではなく、ブラウザーの制限を報告します。
• 各操作をどのジェスチャーが所有しているかを追跡します。キャンセル時、ウィンドウがフォーカスを失ったとき、タブが非表示になったときに、押されたままのキーを解除します。
• ポインター数の変化、ポインターのキャンセル、ポインターキャプチャの喪失に対応します。
• 破棄時にキャプチャを解放し、リスナー、オブザーバー、タイマー、アニメーションフレームをクリーンアップします。
• ルートがアクティブな間は、ドキュメントのビューポートとキャンバスのスクロール境界に overscroll-behavior-x: none を適用します。
• Chrome の横方向の履歴スワイプをブロックします。内側のラッパーだけでは防止できません。
• 破棄時にドキュメントのスタイルを元に戻します。ネストされた横スクロール、戻る／進むコントロール、ナビゲーションショートカットを維持します。
• pushState で履歴をトラップしたり、ブラウザー API を書き換えたり、グローバルハンドラーを恒久的に残したりしないでください。
• ネイティブのページスクロールでキャンバスが移動しないようにします。画面外のキーボードフォーカスは、カメラを動かして表示します。
• カメラ座標、アイテムの位置、ズームの値には、有限かつ上限のある値を必須とします。
• ポインターとホイールによる更新は、1アニメーションフレームあたり最大1回の変換書き込みにまとめます。
• ジェスチャー中の値は、コンポーネント全体の React state の外部に保持します。カメラの移動によってプレビューを再レンダリングしないでください。
• キャンバスが所有するラッパーのみを更新します。ジェスチャー中にプレビューの DOM やレイアウトに影響する位置を変更しないでください。
• 計測した境界をキャッシュします。コンテンツ、寸法、レイアウトが変化したときは、まとめて更新します。
• コンテンツの境界を計測する際は、一時的なレンダリング用プレースホルダーを無視します。
• 毎フレームすべてのプレビューを計測したり、レイアウトの読み取りと書き込みを交互に繰り返したりしないでください。
• ジェスチャー後、または上限のあるデバウンスを使って保存します。ポインターイベントごとにストレージへ書き込まないでください。
• 破棄時は、可能であれば保留中の保存を安全にフラッシュします。
• 高コストなエフェクト、プレビューごとの恒久的なコンポジット用ヒント、単一アイテムの移動に伴うキャンバス全体の処理を避けます。
• 仮想化やメモ化を追加するのは、プロファイリングで効果が確認された場合に限ります。画面外でのアンマウントは入力状態を失わせ、フォーカスやポータルを壊す可能性があります。

レイアウトを保存し、コンテンツは保存しない

• カメラ、サポート対象のテーマ設定、安定したレジストリ ID をキーとする位置のみを保存します。
• プロジェクト固有かつキャンバス固有のキーの下に、小さなバージョン管理されたドキュメントを保存します。
• 既存のアプリ設定や、無関係なテーマ設定を尊重します。競合するテーマ設定は作成しないでください。
• 保存するレイアウトにも同じ数値制限を適用します。プロジェクトの規約に従って、ID、サポート対象のテーマ、ドキュメントのサイズ、位置の数を検証します。
• 現在のレジストリエントリをすべて描画します。有効な保存済み位置を適用し、古い ID は無視します。
• 新しいエントリは常に表示します。現在のソース名と寸法をすぐに使用します。
• 不正なデータ、ストレージを利用できない状況、容量超過エラーが発生しても、キャンバスが壊れないようにします。
• 既知の旧形式については、有効なカメラ値、テーマ、現在の ID に対応する位置のみを保持します。
• 保存済みのメンバー情報、名前、寸法、重複、非表示または削除済みの状態は破棄します。不明なバージョンの場合は、安全なデフォルトを使用します。
• 実行可能なコンポーネント、シークレット、トークン、アカウントデータ、フォームの内容は決して保存またはデシリアライズしないでください。
• 明示的に依頼されていない限り、プレビューの下書きや操作履歴は保存しないでください。

テストを実施し、正直に報告する

リポジトリで必須とされているチェックを実行します。ルートがマウントされ、インポートが解決され、コンソールにエラーが表示されないことを確認します。意図しない本番環境向けの変更がないか、差分を確認します。

新しいキャンバスやコントローラーの変更では、上記のすべての動作をテストします。コンテンツのみの変更では、コントローラーを再構築せず、影響を受ける動作をテストします。複数のズームレベルとビューポートサイズを試し、既存の保存済みレイアウトがある状態で再読み込みします。

タッチテストには、サポート対象のデバイスを使用します。Chrome の履歴スワイプテストでは、実際のトラックパッド入力と実際の履歴エントリを使用します。

空白領域とプレビューの両方を対象に、ズームインとズームアウトをテストします。ジャンプやずれがなく、ズームのアンカーが固定されていることを確認します。ビューポートの中心を基準に、ボタンとキーボードでのズームをテストします。プレビューの内容上やネストされたスクロール領域上で、スクロール範囲の端も含めて、トラックパッドによるパンをテストします。

実際に実行したテストのみを合格と報告します。コンパイルやソースコードの確認だけでは、ブラウザー上の動作を証明できません。実施できなかったデバイスのテストやブラウザーの制限を報告します。

スムーズなパフォーマンスを主張する前に、空のキャンバスだけでなく、代表的な数のプレビューを含むキャンバスでプロファイリングします。プレビュー数、ブラウザー、デバイス、パン、ズーム、移動時の測定値を記録します。長時間のタスク、レイアウトの繰り返し、同期的なストレージ書き込み、プレビューの再描画を調査します。観測された停止や未テストのケースを報告します。変更されていないコントローラーは、プレビューのみの編集で再構築やプロファイリングを行う必要はありません。

次の詳細を含む短いレポートで締めくくります。

• 変更点：パス、目的、ローカルでの実験、共有コンポーネントの変更、新しいプレビューの正確な名前。
• 実施したチェック：実行したテストとその結果。
• 未動作または未テスト：制限、未実施項目、その理由。
• 判断した内容：確認せずに選択したデフォルト設定。