visual-ralph

Visual Ralph スキル

$visual-ralph は、承認済みの生成リファレンス、静的画像、またはライブ URL のベースラインに対して、計測に基づくフロントエンド実装を行うために使用します。ループは次のとおりです。

説明 / URL -> 承認済みリファレンス -> $ultragoal による実装 -> Visual Ralph の判定 + ピクセル差分 -> 再利用可能なデザインシステム

URL のクローンについては、このスキルが移行済みの $web-clone のユースケースを担当します。URL、ビューポート、再現度、インタラクションに関するメモはここで保持してください。スタンドアロンの $web-clone は呼び出さないでください。

共通の運用、委任、状態、フック、チーム、キャンセル、検証に関する不変条件は templates/AGENTS.md にあります。ここで規則を重複させず、そのソースに従ってください。

使用する場面

• ユーザーが、ビジュアルターゲットに合わせて Web/アプリの UI を構築またはスタイル変更したい場合。
• ライブ URL または生成されたラスター形式のモックアップについて、計測に基づく実装とピクセルレベルの反復が必要な場合。
• 結果として、一致するスクリーンショットだけでなく、リポジトリにネイティブな再利用可能なトークン/コンポーネントを残す必要がある場合。

永続的な DESIGN.md の仕様（$design）、非ビジュアルなバックエンド作業、直接実行できる比較のみの修正、または決定論的な SVG/コードネイティブのアセットには使用しないでください。

ワークフロー

1. リポジトリを把握する

パッケージマネージャー/スクリプト、フロントエンドのフレームワークとルート、スタイリング/トークンの規約、スクリーンショットツール、再利用可能なコンポーネントを確認します。スタック固有のコマンドは、リポジトリの根拠によって裏付けられる場合にのみ選択してください。

2. リファレンスを確立する

ライブ URL の場合、次を含むアーティファクトを作成または文書化します：ソース URL と許可/適用範囲、ビューポート、ルート/状態、シード/ログインの前提、ベースラインのスクリーンショットのパスまたはキャプチャコマンド、表示されているコントロールの一致に関するメモ、および除外事項（バックエンド/API/認証、個人化されたデータ、クローリング、サードパーティのウィジェット）。

生成されたコンセプトの場合は、$imagegen を分類 ui-mockup で使用し、ビューポート/アスペクト比、サーフェス、レイアウトの階層、タイポグラフィ、カラームード、正確なテキスト、ロゴ/透かし/要求されていない印なしの指定、そして読みやすく実現可能な UI の詳細を指定します。OMX ランタイムでは、組み込みの画像ツールを呼び出す前に、継続チェックポイントをキューに入れてください：

omx imagegen continuation <session-id> --artifact <slug-or-filename> --generated-dir "$CODEX_HOME/generated_images/<session>" --work-dir ".omx/artifacts/visual-ralph/<slug>"

承認済みのリファレンスを .omx/artifacts/visual-ralph/<slug>/reference.png にコピーしてください。$CODEX_HOME/generated_images の下だけに残さないでください。

3. 承認ゲート

生成または URL のキャプチャの後で停止し、1 つのリファレンス画像/状態（または対象を絞った再生成/キャプチャの調整）の承認を得てください。承認を得るまでは、実装も $ultragoal の呼び出しも行わないでください。承認後は、その画像/ベースラインが視覚的な唯一の正となり、大きな方向転換には明示的なユーザーの要求が必要です。

4. $ultragoal に引き継ぐ

承認済みのリファレンス/ベースライン、該当する場合の URL と許可に関するメモ、ビューポート/コンテンツの状態、インタラクションの一致と除外事項、ユーザーの説明、検出されたフロントエンドのコンテキスト、スクリーンショットのコマンド/ビューポート、そして完了チェックリストを渡します。承認後は、アクティブな Ultragoal の実行レーンが、一致またはブロックされるまで、編集、実行、キャプチャ、反復を行います。

5. 編集の前に毎回判定する

各反復で、ビューポート/状態を含む現在のスクリーンショットをキャプチャし、Visual Ralph の判定を実行し（必要に応じて vision を使用）、その JSON を正として扱います。score < 90 の場合は、differences[] と suggestions[] を次の編集計画に変換し、編集の前に再実行してください。必須の判定キーは score、verdict、category_match、differences[]、suggestions[]、reasoning です。

6. 補助的な差分の証拠

ピクセル差分/pixelmatch のオーバーレイは、ホットスポットを特定して編集に変換するためにのみ使用します。判定の代わりにはなりません。監査可能性のために、最終的なリファレンス、スクリーンショット、差分のアーティファクトを記録してください。

7. 再利用可能なデザインシステム

一致の内容を、既存のリポジトリにネイティブな CSS 変数、テーマトークン、設定、コンポーネントのバリアント、ストーリー、または DESIGN.md の更新としてエンコードします。該当する色、余白、タイポグラフィ/ウェイト、角丸、影/エレベーション、および重要なバリアントや状態を記録します。並行するレイヤーを追加するのではなく、既存のパターンを拡張してください。

完了の根拠と停止条件

承認済みの参照/ベースラインと再現コマンド（ビューポート、ルート、状態、出力パス）が保存されるまで、完了と宣言しないでください。最終判定は >= 90 であること、副次的な差分の根拠が記録されていること、再利用可能なトークンとコンポーネントが存在すること、同等のビルド/リント/テストの検証が通過していること、未承認の方針転換が発生していないこと、そして残存する差分が文書化されていることが条件です。根拠がこれらの条件を満たせない場合は、承認ゲートで停止するか、具体的な阻害要因を報告してください。

ハンドオフテンプレート

$ultragoal "Implement the approved frontend reference.
Reference: <workspace reference or URL-derived artifact>
Source URL and permission/scope: <when applicable>
Viewport/content state: <viewport, route/state, seed/login assumptions>
Interaction parity and exclusions: <visible controls and known limits>
Route/surface: <route or component>
Screenshot command: <command and viewport>
Run Visual Ralph verdict before every next edit; pass threshold >= 90.
Use pixel diff only as secondary evidence.
Extract reusable tokens/components for colors, spacing, typography, radii, shadows, and variants.
Run the repository's equivalent verification before completion.
Do not make major design pivots unless explicitly requested."

Task: {{ARGUMENTS}}