AI agent skills that build UI from Figma/screenshot/text and iterate until all tests pass.
Ralph takes a design input and automatically:
- Plans first — summarizes the request, identifies missing decisions, and asks follow-up questions when needed
- Extracts scene specs from Figma links, screenshots, text descriptions, or existing components
- Generates code with proper Tailwind classes and project conventions
- Runs verification — computed styles, layout bounding box on root + critical subgroups, AI vision comparison
- Auto-fixes failures — iterates until tests pass or the repair budget is exhausted
- Reports results — verification report + screenshots for PR
The core rule for this version is simple: exact mode must treat the original Figma as the final authority, not a lossy summary. If scene coverage is incomplete, if a Figma link is unmapped, or if verify cannot prove parity against the original reference, the run must not pass.
npm install -D ui-ralphThe postinstall script automatically copies skills to .claude/commands/ and e2e utilities to e2e/utils/.
It also adds a managed ui-ralph block to the project root AGENTS.md so Codex can trigger the same pipeline.
Ralph is not meant to jump straight into implementation on ambiguous requests. For complex work it should first enter a lightweight planning mode, point out missing decisions, show implementation options when there are multiple valid approaches, and keep asking until the request is detailed enough to execute safely.
In Claude Code:
# Full pipeline — auto-detects input from conversation context
/ui-ralph
# With Figma link
[paste Figma URL] + /ui-ralph
# With screenshot
[paste image] + /ui-ralph
# Individual stages
/ui-ralph:spec # Extract spec only → e2e/.ui-spec.json
/ui-ralph:gen # Generate code from spec
/ui-ralph:verify # Run verification only (always writes verification report)
/ui-ralph:clean # Remove all artifacts
In Codex:
ui-ralph로 진행해줘
ui-ralph:verify 실행해줘
Codex does not use Claude slash-command installation. Instead, the installer writes a managed block into the project root AGENTS.md so plain-text mentions of ui-ralph trigger the same workflow.
ui-ralph now includes a stateful harness that enforces stage order, commits stage receipts, and blocks completion unless the current run's verification passes.
ui-ralph harness init --quality exact --source figma --ref "https://figma.com/..."
ui-ralph harness begin spec
ui-ralph harness commit spec
ui-ralph harness gate spec
ui-ralph harness begin gen
ui-ralph harness commit gen
ui-ralph harness gate gen
ui-ralph harness begin verify
ui-ralph harness commit verify
ui-ralph harness approve --by "reviewer-name"
ui-ralph harness gate verify
ui-ralph harness statusui-ralph harness begin <stage> enters the stage's working state. ui-ralph harness commit <stage> writes a receipt under e2e/.ui-artifacts/receipts/<runId>/input-N/ with file hashes and environment metadata. The gate only trusts committed artifacts from the current run, so stale spec/report files from an older run cannot slip through.
In exact mode, the example above assumes e2e/.ui-spec.json already contains the deterministic verification contract: verification.authStrategy, verification.fixtureRefs, verification.externalDeps, and verification.browserProfile.
The authoritative state file is e2e/.ui-ralph-run.json. It is now organized around a run-level FSM plus per-input FSM states rather than a single currentStage field:
{
"runState": "running | blocked | completed",
"activeInputId": "input-1 | null",
"inputs": [
{
"id": "input-1",
"fsmState": "pending | spec.pending | spec.generating | spec.committed | gen.pending | gen.generating | gen.committed | verify.pending | verify.running | verify.reported | verify.awaiting_approval | blocked.awaiting_user | blocked.missing_prerequisite | repair.pending | repair.retry_exhausted | done",
"lastVerificationResult": "PASS | FAIL | ERROR | UNVERIFIED | null"
}
]
}In exact mode, ui-ralph harness gate verify will refuse to complete unless the verification report is PASS, verification completeness is complete, AI vision is PASS for visual references, and a human approval file exists.
For complex product work, especially multi-page or multi-state Figma requests, Ralph must not treat a single flattened spec as sufficient evidence of parity. The exact-mode happy path is:
- run a planning pass and collect missing decisions first
- split the request into scenes
- map every Figma reference into scene coverage
- generate scene-aware verification
- fail the run if any scene is unmapped, unverified, or visually different from the original Figma reference
This is the critical product requirement for the current version.
ui-ralph includes a replay harness for regression checking of the FSM contract.
npm run harness:replayIt replays at least 3 golden cases twice each, compares normalized terminal outcomes, and also verifies that status --events-file ... can rebuild state from events.ndjson without e2e/.ui-ralph-run.json.
exact: Figma, screenshot, 또는 승인된 text reference를 기준으로 완전 일치를 목표로 한다best-effort: 구조와 의도를 우선하는 빠른 구현 모드다
Exact is also auto-promoted when the user provides multiple Figma links or frames the task as a parity audit/fix, for example "피그마와 다르다", "비교해봐", or "이전 구현이 엉망".
Exact mode should not pass on color/button-only coverage. Scene specs are expected to carry placement/alignment context, and verification should cover at least 3 categories across placement, alignment, typography, and assets before a PASS candidate is considered.
Text-only exact work is not allowed to finish directly. It must first create and get approval for a reference artifact.
- Claude Code CLI
- Codex CLI or Codex desktop app
- Node.js >= 18
- A running dev server (
npm run dev) for verification
- Figma MCP server — for Figma link mode
- Playwright (
npm install -D @playwright/test) — for e2e verification
Input (Figma / text / image / component)
↓
/ui-ralph:spec → e2e/.ui-spec.json (design tokens, styles, layout)
+ verification route/data strategy + exact/best-effort reference contract
↓
/ui-ralph:gen → Component code + E2E test
↓
/ui-ralph:verify → 3-stage verification (mandatory; incomplete coverage becomes UNVERIFIED)
① Computed style check
② Placement/alignment + layout bounding box check
③ AI vision comparison + component crop review
↓
PASS? → Done
FAIL? → Auto-fix → Re-verify (max 3 attempts)
UNVERIFIED? → fix route/design source → Re-verify
Full PASS means the required checks actually ran. A skipped screenshot comparison or skipped Playwright coverage is not a PASS.
When the visual issue is about full-bleed margins, centered copy blocks, or icon/text subgroup alignment, e2e/.ui-spec.json should not stop at the scene root. Split those containers into separate elements, record parentContext, placement, alignment, and set sceneRequirements so exact mode cannot pass on color/button-only coverage.
| File | Purpose |
|---|---|
e2e/.ui-spec.json |
Design spec — source of truth for verification |
e2e/.ui-progress.json |
Legacy progress mirror for older integrations; e2e/.ui-ralph-run.json is the only authoritative state |
e2e/.ui-ralph-run.json |
Harness state for the current run |
e2e/.ui-artifacts/design-ref.png |
Reference screenshot from design |
e2e/.ui-artifacts/impl-screenshot.png |
Screenshot of implementation |
e2e/.ui-artifacts/component-crop.png |
Cropped screenshot of the primary component or subgroup under review |
e2e/.ui-artifacts/verification-report.md |
Detailed verification results |
e2e/.ui-artifacts/e2e-spec.ts |
Auto-generated E2E test |
e2e/.ui-artifacts/receipts/<runId>/input-N/*.json |
Stage receipts with artifact hashes and provenance |
e2e/.ui-artifacts/human-approval.json |
Exact-mode human approval record for the current input |
e2e/test-results/ |
Playwright output directory |
All artifacts are development-time only. Clean up with /ui-ralph:clean or:
rm -f e2e/.ui-spec.json e2e/.ui-progress.json e2e/.ui-ralph-run.json .ui-spec.json .ui-progress.json && rm -rf e2e/.ui-artifacts/ e2e/test-results/ .ui-artifacts/ test-results/npx ui-ralph uninstall
npm uninstall ui-ralphTo remove only one integration:
ui-ralph uninstall claude
ui-ralph uninstall codexMIT