# Visual Ralph

> Visual frontend delivery loop — build or restyle UI from a generated reference, a static reference, or a live URL, iterating with measured visual-verdict scoring and pixel-diff evidence until the implementation matches and leaves a reproducible design system. Triggers: "visual ralph", "build UI from reference", "clone website from URL", "pixel-perfect UI", "visual implementation".

- Skill: `mrzhangguoguo/visual-ralph` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mrzhangguoguo/visual-ralph`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrzhangguoguo/visual-ralph/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: mrzhangguoguo (https://skillmd.com/u/mrzhangguoguo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mrzhangguoguo/visual-ralph

---


> Ported from oh-my-codex `visual-ralph`. OMX runtime conventions (`$macro` invocation,
> `omx` CLI, `.omx/` state directory) are replaced with WorkBuddy idioms
> (Skill tool, Agent tool, task list, `.workbuddy/memory`).

# Visual Ralph Skill

Use this skill when the user wants WorkBuddy 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; the `ralph` skill implements; and a 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` (it is deprecated); 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; invoke the `design` skill 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 the `ralph` skill 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. Use Read/Grep/Glob and Bash for read-only inspection.

### 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 deprecated — handle URL cloning here.

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 the **ImageGen** tool to produce the reference from the user's UI
description (this replaces OMX's `$imagegen`).

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.

For project-bound implementation, copy the approved reference into the workspace, for example
under `.omw/visual-ralph/<slug>/reference.png`. Never leave the implementation reference only in a
generated-images scratch location. Record the slug and baseline in
`.workbuddy/memory/YYYY-MM-DD.md`.

### 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 (use the
AskUserQuestion tool or a plain chat question).

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.

### 4. Hand off to `ralph` for implementation

Invoke the `ralph` skill and pass it:
- the approved reference image path or URL-derived baseline artifact,
- source URL, viewport(s), content state, and interaction parity notes for live URL tasks,
- the user description,
- the detected repo/frontend context,
- exact screenshot command/viewport requirements,
- the completion checklist below.

Ralph may iterate autonomously after approval. It should edit code, run the app, capture
screenshots, and keep improving until the approved reference is matched or a real blocker exists.

### 5. Use Visual Ralph verdict before every next edit

For each visual iteration:
1. Capture the current generated screenshot with recorded viewport/state.
2. Run the Visual Ralph verdict step comparing the approved reference and generated screenshot.
   Use the Read tool (WorkBuddy is multimodal) on both images for visual understanding; if a
   dedicated vision reviewer is available, delegate the comparison to an Agent.
3. Treat the JSON verdict as authoritative.
4. If `score < 90`, convert `differences[]` and `suggestions[]` into the next edit plan.
5. Rerun before the next edit.

Required verdict shape: `score`, `verdict`, `category_match`, `differences[]`, `suggestions[]`,
and `reasoning`.

### 6. Use pixel diff only as secondary debug evidence

When mismatch diagnosis is hard, generate a pixel diff or pixelmatch overlay to locate hotspots.
Pixel diff does not replace the Visual Ralph verdict; it only helps translate visual hotspots into
concrete edits.

Record final diff evidence with the reference/screenshot artifacts so the result can be audited
(under `.omw/visual-ralph/<slug>/`).

### 7. Build a reproducible design system

The implementation is incomplete unless the visual match is encoded in repo-native reusable
artifacts. Depending on the project, this may mean CSS variables, theme tokens, Tailwind config,
component variants, Storybook stories, updates that align with DESIGN.md, or existing equivalents.

Capture at least the applicable:
- colors,
- spacing scale,
- typography scale/weights,
- radii,
- shadows/elevation,
- important component variants and states.

Prefer existing token/component patterns. Do not introduce a new design-system layer if the repo
already has one that can be extended.

## Completion checklist

Do not declare done until all are true:
- Approved reference image or URL-derived reference artifact is saved in the workspace.
- Screenshot reproduction command, viewport, route, seed/state, and output paths are documented.
- Visual Ralph verdict final score is `>= 90` against the approved reference.
- Pixel diff or overlay evidence is recorded as secondary debug evidence.
- Design-system tokens/components are repo-native and reusable.
- Build/lint/test or the repo's equivalent verification passes.
- No unapproved major design pivot occurred after reference approval.
- Remaining visual differences, if any, are explicitly documented with rationale.

## Handoff template

```
Invoke the ralph skill: "Implement the approved frontend reference.
Reference: <workspace-reference-image-or-url-derived-artifact>
Source URL (if URL-derived): <url and permission/scope note>
Viewport/content state: <viewport, route/state, seed/login assumptions>
Interaction parity notes: <visible controls and known exclusions>
Route/surface: <route or component>
Screenshot command: <command and viewport>
Use the Visual Ralph verdict step before every next edit; pass threshold score >= 90.
Use pixel diff only as secondary debug evidence.
Extract reusable design tokens/components for colors, spacing, typography, radii, shadows, and key variants.
Run build/lint/test before completion.
Do not make major design pivots unless explicitly requested."
```