Visual Ralph

Visual Ralph Skill

Use this skill when the user wants Codex to build or restyle frontend UI through a Visual Ralph loop: an approved generated reference, static reference, or live URL-derived baseline becomes the target, Ralph implements, and Visual Verdict drives measured iteration rather than subjective description alone.

Purpose

Create a measured frontend delivery loop from either a generated reference, a static reference, or a live URL:

user description / live URL -> approved visual reference -> $ralph implementation -> Visual Ralph verdict + pixel diff -> reproducible design system.

For live URL cloning requests, Visual Ralph owns the migrated $web-clone use case. Do not route new URL-driven website cloning work to $web-clone; preserve the URL, viewport, fidelity requirements, and interaction notes inside the Visual Ralph loop.

This is an orchestration skill. It composes existing skills and must not add runtime commands, dependencies, or app-specific assumptions by itself.

Use when

• The user describes a desired web/app UI and wants implementation, not just design advice.
• The user provides a live URL and wants a visual implementation or clone through measured Visual Verdict iteration.
• A generated raster mockup/reference image would make the target clearer.
• The task needs pixel-level visual iteration with a pass/fail threshold.
• The final result should leave reusable design tokens/components, not only a one-off screenshot match.

Do not use when

• The user only wants repo-wide design guidance, product/design context, or a DESIGN.md source of truth; use $design or a designer lane.
• The task is a non-visual backend/API implementation with no UI reference target.
• The user already supplied a final static reference image and only needs comparison/fixes; hand directly to $ralph with Visual Ralph verdict guidance.
• The requested output is a deterministic SVG/vector/code-native asset rather than a raster reference.

Workflow

1. Ground the target repo

Before stack-specific choices, inspect local evidence:

• package manager and scripts,
• frontend framework and routing structure,
• styling system and design-token conventions,
• screenshot/test tooling,
• existing components that should be reused.

Do not hardcode React, Vue, Tailwind, Playwright, or any other stack unless the repository evidence supports it.

2. Establish the visual reference

For live URL requests, capture or document the URL-derived reference inside the Visual Ralph artifacts and carry forward viewport, content-state, and interaction constraints. Do not invoke $web-clone; that standalone skill is hard-deprecated.

Live URL reference artifacts must include:

• source URL and permission/scope note,
• viewport(s), route/state, and any seed/login assumptions,
• captured baseline screenshot path or documented capture command/tool,
• interaction parity notes for visible controls,
• known exclusions such as backend/API/auth, personalized data, multi-page crawling, and third-party widget parity.

For generated UI concepts, use $imagegen to produce the reference from the user's UI description.

Prompt requirements:

• classify as ui-mockup, unless another imagegen taxonomy is clearly better,
• include viewport/aspect ratio and intended surface,
• specify layout, hierarchy, typography direction, color mood, and any exact text,
• forbid logos/watermarks/unrequested brand marks,
• ask imagegen to avoid impossible UI details or unreadable text.

When running under OMX CLI/runtime and a generated reference is part of an active Ralph-style loop, queue a continuation checkpoint before invoking the built-in image tool:

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

This helper records .omx/state/sessions/<session>/imagegen-pending.json and uses the existing Stop-hook follow-up queue. It exists because built-in image generation may have to end the assistant turn immediately; the next Stop checkpoint should resume artifact recovery, copy the generated image into the workspace, and run the required visual QA/verdict gate instead of relying on a manual $ralph re-prompt.

For project-bound implementation, copy the approved reference into the workspace, for example under .omx/artifacts/visual-ralph/<slug>/reference.png. Never leave the implementation reference only in $CODEX_HOME/generated_images/....

3. Require explicit user approval

Stop after reference generation or URL-derived reference capture and ask the user to approve one reference image/state or request a targeted regeneration/capture adjustment.

Before approval:

• do not start frontend implementation,
• do not invoke $ralph,
• do not treat a rough image as final.

After approval, the confirmed image or URL-derived baseline becomes the visual source of truth. Major design pivots, replacing the reference, or changing the design direction require an explicit user request.