Pixerate キャンバス
キャンバスは xyflow（React Flow / SvelteFlow）グラフです。ノードとエッジの配列で構成されます。
ノードは { id, type, position: { x, y }, width?, height?, parentId?, zIndex?, data }、エッジは
{ id, source, target, label? } です。デザインフィーチャーが保持するすべての情報は node.data に格納されるため、コピー、ペースト、JSON でも維持されます。
data.label/data.name：テキストコンテンツとレイヤー名。data.shape：シェイプノード （{ kind: rect | ellipse | polygon | star | path, fill, stroke, strokeWidth, ... }）。data.layout：オートレイアウトフレーム（modehorizontal / vertical / grid、gap、padding、alignMain、alignCross、sizing）。その子ノードは、ノード配列の順序でparentIdがフレームであるノードです。data.childLayout：子のサイジング（fixed / hug / fill）と制約。data.component（メインコンポーネント）、data.componentSet（バリアントセット）、data.instance（{ componentId, properties }）およびdata.componentOverrides。data.locked、data.animation（キーフレームトラック）、data.tokenBindings（デザイントークン）。
位置はキャンバス（フロー）単位です。子の位置は親からの相対位置です。ノードIDは get_editor_state から、コンポーネントIDとセットIDは list_components から取得します。ids または id を受け取るツールは、省略すると現在の選択範囲をデフォルトとします。そのため、canvas_select で選択した直後でない限り、IDを明示的に渡してください。名前空間、run_commands によるバッチ処理、エラーコードについては pixerate-agent-tools を参照してください。
ワークフロースキル
以下のジョブでは、ワークフロースキルもロードしてください。これにはメソッド、ステップ間のチェック、落とし穴が含まれ、以下のツールを使用します。
pixerate-canvas-design-system-components：コンポーネント、インスタンス、バリアントセット、オーバーライドpixerate-canvas-layout：整列、分布、順序、ロック
作業方法
- 読み取り。
includeDocument: falseを指定したget_editor_stateはcanvas.nodesとcanvas.edgesを返します。デザインシステムの場合はlist_componentsも呼び出し、インスタンスを変更する前にinspect_instanceを呼び出します。 - まず構造を計画します。 どのフレーム、どの再利用可能なコンポーネントとバリアント、どの間隔スケールを使用するかを決めます。メインコンポーネントを一度作成してから、インスタンスを配置します。ノードを手動でコピーしないでください。
- 書き込み。 グラフ編集専用のツール（
canvas_add_node、canvas_connect、canvas_update_node）とコンポーネント用ツール（create_component、create_instance、...）を使用します。整列、シェイプ、アニメーションコマンドにはatomic: trueを指定したrun_commandsを使用します。また、複数のステップを1つのアンドゥステップにする場合（パラメータ"$0.ids[0]"は以前のステップが返したIDを使用します）にもこれを使用します。 - 整理。 グラフには
canvas_layout、デザインにはcanvas.align*/canvas.distribute*、レイヤー順序にはcanvas.bringToFrontとその関連コマンド、完成した背景のロックにはcanvas.lockを使用します。 - 確認。 バッチ処理が完了したら
view_editor（デフォルトのビューポート、JPEG、1024 px）を使用します。描画全体を確認するにはscope: "canvas"を使用します。重なり、位置ずれ、テキストのクリッピングを修正し、canvas_selectまたはcanvas_highlightを使用してユーザーに表示します。
ユーザーと一緒に作業する場合（ユーザーが構築中で、あなたが依頼なしに追加する場合）：編集ではなく提案します。propose_nodes はユーザーが承認または却下するゴーストを表示し、それまではキャンバスやその履歴には何も影響しません。各提案は小さく、1つのアイデア（キャプション、シリーズ内の次のカード、不足しているコネクタ）に絞り、title と 1文の rationale を付け、nearNodeId で補完するノードにアンカーします。ユーザーから依頼がない限り、自分の提案を承認しないでください。古くなった提案は reject_proposal で取り下げます。ユーザーが提案の基盤を変更した場合、list_proposals はそれを missing の下に表示します。
ベストプラクティス
-
デザインシステム思考。 2回以上出現するものはコンポーネントにします。メインを1つ構築し、
combine_as_variantsで状態とサイズ（State=Default、State=Hover、Size=Small）をバリアント化し、create_instanceですべての場所に配置します。メインを変更するとすべてのインスタンスが変更されます。オーバーライドは使用ごとのコンテンツ（ラベルテキスト、アイコンの差し替え）にのみ使用します。バリアントのプロパティ名と値は一貫性を持たせ（プロパティはタイトルケース、値は短く）、組み合わせは一意に保ちます。 -
バリアント切り替え後も存続させる必要があるレイヤーには、安定した
data.nameを付けます。 一致のフォールバックはdata.labelです。テキストの場合、data.labelはその内容であり、バリアント間で異なります。 -
コンポーネントプロパティを使用し、デタッチしないでください。
set_instance_propertiesでバリアントを切り替え、テキストやブール値のプロパティを設定します。別のコンポーネントに切り替えるにはswap_instanceを使用します。インスタンスがメインの追跡を停止する必要がある場合にのみ、デタッチします。 -
間隔スケール。 基本単位（4または8）を選び、その倍数をギャップとパディングに使用します。行やスタックは、子を手動で配置する代わりにオートレイアウトフレーム（
data.layout）に配置し、コンテンツが変更されたときに自動で再フローするようにします。 -
整列と分布。 共通の端または中央に整列し、等間隔で分布します。端が揃っていると、デザインは整然として見えます。アンカーにしたいノードはロックします。ロックされたノードは決して移動しませんが、選択範囲の境界にはカウントされます。
-
レイヤリング。 背景は後ろ、コンテンツはその上、オーバーレイは最前面に配置します。再スタックコマンドを使用します。これらは兄弟グループごとに
zIndexを設定し、配列の順序を変更することはありません。 -
グラフレイアウト。 フローは一方向（パイプラインは
LR、階層はTB）にレイアウトし、エッジは短く保ちます。関係が明らかでない場合にのみエッジにラベルを付けます。 -
モーション。 出現するものにはイーズアウト（または多少のオーバーシュートには
ease-out-back）、消えるものにはイーズイン、2つの静止位置間の移動にはイーズインアウト、回転などの連続的な動きにはlinearのみを使用します。UIトランジションは約150〜400ミリ秒、エントランスは約600ミリ秒未満に保ちます。関連する要素は、すべてを同時に動かすのではなく、delayを使用して30〜80ミリ秒ずつずらします。opacity、x、y、scale、rotationをアニメーション化します。色のトゥイーンは OKLab で補間します。 -
ブラッシュストローク。 ユーザーが手描きの外観（スケッチ、インク、鉛筆、マーカー）を希望する場合はブラシを使用します。ダイアグラムやUIにはプレーンなストロークを使用します。曲線に沿って2〜8キャンバス単位ごとにポイントを送信し、短い
pressureプロファイル（テーパー状の端：[0.2, 0.9, 1, 0.9, 0.2]）で線を整形します。幅の異なる多数のポイントを使用するのではなく、このプロファイルを使用します。widthを省略すると、プリセットのサイズ（canvas.listBrushesで取得可能）が使用されます。widthは、マークを細くまたは太くする場合にのみ渡します。 -
ブラシの特性。 各プリセットは独自の特性で描画します。木炭とパステルは幅広でざらつきがあり（紙の表面を捉えます）、クレヨンとチョークも同様です。鉛筆は細く、わずかにざらつきがあります。インク、マーカー、ブラシペン、ボールペン、ゲルペン、ファインライナーはクリーンです（ファインライナーは1つの太さを維持します）。エアブラシはソフトなスプレーです。ざらつきとジッターはストロークごとにシードされるため、ストロークは常に同じように見え、隣接するストロークは1枚の紙を共有します。外観に合わせてブラシを選び、次に色を選びます。スケッチには、すべてのブラシを使うのではなく、1つまたは2つのブラシを使用します。デフォルトの色（ボールペンブルー、ハイライターイエロー、チョーク）を持つブラシは、
colorを渡さないとその色で描画します。colorを渡すと別の色を使用します。明/暗のデフォルト（チョーク）は、キャンバスのカラースキームに応じて解決されます（canvas.setColorScheme；ホストは通常、テーマに一致させます）。 -
描画ではなく、ユーザーのためにペンを設定します。
canvas.selectBrushは、ブラシピッカーと同様に、ユーザーが手で描画するブラシを選択します。これにより、ユーザーが色をロックしていない限り（canvas.setColorLocked、「色をキープ」）、またはkeepColourを渡さない限り、ブラシのデフォルト色が取得されます。このように取得されたデフォルトは、別の色が設定されるまでスキームに従います。ユーザーが設定したロックは尊重し、色を変更するためにロックを解除しないでください。これらはエディターの状態であり、アンドゥステップではなく、独自のbrushとcolorを取るcanvas.drawFreehandには影響しません。 -
ポイントではなく、ジェスチャーで注釈を付けます。 デザイナーが印刷物にマークアップするように作業にマークアップするには、ジェスチャーコマンド（
canvas.circle、canvas.underline、canvas.arrow、canvas.bracket、canvas.strike、canvas.cross、canvas.check）をノードID（{ "nodeId": "..." }）またはボックスとともに使用します。canvas.drawFreehandのポイントを計算する代わりにこれらを使用します。1回の呼び出しで1つの手描きマークが描画されます。注釈は、キャンバス上の何かを指しながら話すときに役立ちます。ピックを丸で囲み、重要な線に下線を引き、スウォッチからそれが使用されている場所へ矢印を描き、説明しているグループを括弧で囲み、却下されたオプションに取り消し線またはバツを付け、承認されたオプションにチェックを入れます。キャンバス上の何も参照されていない場合はスキップし、ポイントごとに数個のマークに留めます。マークで覆われたページは何も語りません。 -
ジェスチャースタイル。 1回のレビューパスには1色を使用します（赤または強い青のペンは、ほとんどのデザインの上でマークアップとして読み取れます）。ハイライターは円と下線にのみ使用します。手描きに見せたい場合は、同じパスのすべてのマークに同じ
brush（markerまたはink-pen）を使用します。マークはリクエストによってシードされるため、再度要求すると同じマークが描画されます。別のテイクを得るには別のseedを渡します。マークに言葉が必要な場合は、括弧の横または矢印の尾部にマージンノート（テキストノード）を配置します。
ツールリファレンス
読み取り
| ツール | 使用目的 |
|---|---|
get_editor_state | キャンバスグラフ（canvas.nodes、canvas.edges）と、デフォルトではプロンプトドキュメントも読み取ります。キャンバスのみのタスクでは includeDocument: false を渡して結果を小さく保ち、プロンプトのみの場合は includeCanvas: false を渡します。最初に、そしてユーザーによる編集後に再度呼び出します。 |
view_editor | エディターの画像を取得します。scope viewport（デフォルト）または canvas（描画全体の境界）、format jpeg（デフォルト）または png、maxEdge ピクセル単位（デフォルト1024）。バッチ処理後に重なり、バランス、可読性を判断するために使用します。エージェントカーソルは除外されます。 |
capture_view | キャンバスの一部をスクリーンショットして結果を確認します。region viewport（デフォルト、画面通り）、content（すべてのノード）、selection、nodes（get_editor_state からの ids を使用）、または rect（キャンバス単位）。padding（デフォルト16）、maxEdge（デフォルト1024）、format png（デフォルト）または jpeg。結果はキャプチャされた rect と scale を提供するため、画像ピクセル (px, py) はキャンバスポイント (rect.x + px / scale, rect.y + py / scale) です。追加したばかりのノードを詳細に検査するには nodes を推奨します。選択ボックスとエージェントカーソルは、includeOverlays を指定しない限り除外されます。 |
list_components | メインコンポーネント（id、名前、バリアント値、インスタンス数）と、そのバリアントオプションを持つコンポーネントセットを一覧表示します。create_instance、swap_instance、または任意のバリアントツールの前に呼び出して、IDと正確なプロパティ名と値を取得します。 |
inspect_instance | 1つのインスタンス（またはその内部のレイヤー、デフォルトは最初に選択されたノード）を記述します。そのメイン、バリアント、タイプ付きのコンポーネントプロパティ値、およびレイヤーごとのオーバーライドを表示します。set_instance_properties または reset_overrides の前に呼び出して、正しいプロパティ名とオーバーライドグループを使用します。 |
書き込み：グラフ
| ツール | 使用目的 |
|---|---|
canvas_add_node | ノードを追加します。node（id はオプションで未使用である必要あり、type はホストによって登録、data、position、width、height、フレームの場合は parentId）。position を省略すると、nearNodeId の隣の side（デフォルト right）に、重なりなく自動配置され、そのノードからのエッジも接続されます。または最後のノードの隣に配置されます。新しいノードIDとエッジIDを返します。 |
canvas_connect | source から target（2つの異なる既存ノード）へのエッジを追加します。オプションの label を指定できます。エッジIDを返します。 |
canvas_update_node | ノードの data にフィールドをマージします（例：{ "label": "Checkout" }）。マージは浅いものとして扱います。shape や layout などのネストされたオブジェクトは全体を渡します。ノードの移動やサイズ変更は行いません。 |
canvas_remove_nodes | ノードとそのエッジを削除します。すべてのIDが存在している必要があります。破壊的です。ユーザーが作成したコンテンツを削除する前に、ユーザーに確認してください。 |
canvas_layout | グラフを自動的に配置します。direction LR（デフォルト）、TB、RL、BT。incremental（デフォルト true）は既に位置を持つノードを保持します。すべてを再レイアウトするには false を渡します。正確に (0, 0) にあるノードは未配置と見なされます。 |
canvas_select | 選択範囲を置き換えます（空のリストは選択をクリアします）。結果をユーザーに表示したり、選択範囲に対して動作するコマンドをターゲットにするために使用します。 |
canvas_highlight | ノードをフラッシュしてユーザーに示します。color（デフォルト #3b82f6）、durationMs（デフォルト2000、最大60000）。何も変更しません。 |
展開と折りたたみ
展開可能なノード（サブタスクに展開するタスクや、そのステップに展開するガントバーなど）を持つホストは、これらを追加します。展開はノードの子ノードを表示し、周囲のノードを移動してスペースを作ります。折りたたみは子を削除し、移動したノードを元の位置に戻します。これはビューの変更であり、編集ではありません。アンドゥステップではなく、ドキュメントとともに保存されません。子が何であるかはホストが決定します。
| ツール | 使用目的 |
|---|---|
list_explodable_nodes | 展開可能なノード（id、label、exploded、collapsing）を一覧表示します。現在 exploded および collapsing のID、複数を同時に開くことができるか（multiple）、展開が無効になっている場合の readOnly 理由も表示します。最初にこれを呼び出します。これが展開可能なIDの唯一のソースです。 |
explode_node | node（list_explodable_nodes からのID）を展開します。multiple でない限り、以前に展開されたノードは折りたたまれます（collapsed で戻ります）。既に展開されているノードを展開しても何も変わりません（changed: false）。現在 exploded のIDを返します。その後、get_editor_state または capture_view を使用して子を読み取るか表示します。 |
collapse_node | 展開された node を折りたたみます。まだ exploded のIDと、まだ collapsing のID（折りたたみアニメーションが終了すると子が離れます）を返します。ノードが展開されていない場合は失敗します。 |
提案（編集ではなく提案）
エージェントが追加を提案できるようにするホストは、これらを追加します。提案はゴーストとして表示される新しいノードとエッジです（ドラッグ不可、選択不可、保存不可）。承認すると1つのアンドゥステップとして追加され、提案者（agent:<id>）が作成したものとして記録されます。拒否すると、キャンバスとその履歴は変更されません。
|
...（翻訳のため省略）