docs: add English blog post on Figma-to-code visual validation

docs/blog/2026-03-07-figma-to-code-visual-validation.md

@@ -0,0 +1,166 @@
+---
+slug: figma-to-code-visual-validation
+title: "How ralph-starter Converts Figma Designs to Pixel-Perfect Code"
+authors: [ruben]
+tags: [ralph-starter, figma, visual-validation, design-to-code, tutorial]
+description: "Convert Figma designs to production-ready code with pixel-by-pixel visual validation. ralph-starter v0.4.0 introduces a three-layer comparison pipeline that catches layout, color, and typography mismatches automatically."
+image: /img/blog/figma-to-code.png
+keywords:
+  - figma to code
+  - visual validation
+  - AI coding tool
+  - design to code automation
+  - pixel comparison
+  - autonomous coding
+---
+
+I ran `ralph-starter figma`, pasted a Figma URL, picked my tech stack, and walked away. When I came back, the generated landing page matched the Figma design at 98.2% pixel accuracy. The AI agent had caught its own font-size mismatch, fixed it, and passed a strict visual comparison — all without me writing a single line of code.
+
+This is how Figma-to-code should work. Here is exactly how it does.
+
+<!-- truncate -->
+
+## The Figma-to-code gap
+
+Every developer has been here: you get a Figma design, spend hours eyeballing spacing values, manually extracting colors, guessing which font weight the designer used, and then the design review comes back with 30 comments about misaligned elements.
+
+Tools like the official Figma MCP and others try to solve this, but most of them break down when the designer did not use Auto Layout. Real-world Figma files are messy — absolute positioning, nested frames without constraints, text layers with overrides.
+
+ralph-starter takes a different approach. It reads the raw Figma node tree via the REST API and calculates positioning and z-index from the actual coordinates of each element. It does not depend on how the designer organized the layers.
+
+Messy Figma file? Works the same.
+
+## One command: `ralph-starter figma`
+
+The v0.4.0 release adds an interactive wizard that handles the full workflow:
+
+```bash
+$ ralph-starter figma
+  Figma to Code
+  Design to code in one command
+
+? Figma design URL: https://figma.com/design/ABC123/Dashboard
+? What would you like to build? responsive dashboard with sidebar nav
+? Tech stack? Next.js + TypeScript + Tailwind CSS (Detected)
+? Which model? Claude Opus 4.6 — maximum quality (Recommended)
+```
+
+Four steps:
+
+1. **Paste the Figma URL.** Any design file link works — no special setup or plugins needed.
+2. **Describe what to build.** A short natural-language description of the component or page.
+3. **Pick your tech stack.** Auto-detected from your `package.json`. Supports Next.js, React, Vue, Nuxt, Svelte, Astro, and plain HTML.
+4. **Choose a model.** ralph-starter detects which AI coding agents you have installed (Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, etc.) and shows the relevant models.
+
+Under the hood, it extracts a complete technical spec from the Figma API — typography, colors, spacing, images, icons, font detection — and passes it to the AI agent along with an implementation plan. The agent works in an autonomous loop: write code, validate with lint and build, commit, repeat.
+
+## Three-layer visual validation
+
+The real differentiator in v0.4.0 is the visual validation pipeline. After each coding iteration, ralph-starter doesn't just check if the code builds — it checks if it *looks right*.
+
+### Layer 1: Pixel comparison (pixelmatch)
+
+ralph-starter starts your dev server, captures a full-page screenshot with Playwright, and runs [pixelmatch](https://github.com/mapbox/pixelmatch) against a screenshot of the Figma design. If the pixel difference is under 2%, it passes immediately. Zero LLM cost.
+
+### Layer 2: LLM vision analysis
+
+When the pixel diff exceeds 2%, things get interesting. ralph-starter sends three images to an LLM vision API:
+
+- The original Figma design screenshot
+- The implementation screenshot
+- A diff overlay where red pixels highlight the mismatches
+
+The model returns actionable, numbered issues:
+
+```
+1. Header font should be 88px serif, currently 40px sans-serif
+2. Section gap should be ~80px, currently ~20px
+3. Button border-radius should be 8px, currently square
+```
+
+The agent then fixes each issue in the next loop iteration.
+
+### Layer 3: Strict gate
+
+After fixes are applied, the pipeline runs pixelmatch again with a strict 2% threshold. This catches anything the LLM missed — sub-pixel rendering differences are fine, but real layout or color mismatches get flagged for another round.
+
+Here is what a typical run looks like end-to-end:
+
+```bash
+→ Capturing implementation screenshot...
+→ Running pixel comparison...
+  Pixel diff: 8.3% (14,231 pixels differ) — analyzing...
+→ Sending to LLM vision for semantic analysis...
+  1. Header font should be 88px serif, currently 40px sans-serif
+  2. Section gap should be ~80px, currently ~20px
+→ Agent fixing 2 issues...
+→ Re-running strict pixel comparison...
+  Pixel diff: 1.1% — strict check passed
+✓ Visual validation passed
+```
+
+Playwright and sharp are auto-installed the first time visual validation runs. No manual setup needed.
+
+## What gets extracted from Figma
+
+ralph-starter does not just grab colors and text. The full extraction includes:
+
+- **Typography**: font family, size, weight, line height, letter spacing, text decoration
+- **Colors**: fills, strokes, gradients, opacity values
+- **Spacing**: padding, margins, gaps calculated from element coordinates
+- **Layout**: auto-layout properties, constraints, absolute positioning
+- **Images and icons**: downloaded at correct scale, optimized with sharp
+- **Fonts**: Google Fonts detected and configured in your project automatically
+- **Component variants**: component properties and variant metadata preserved
+- **Effects**: shadows, blurs, and other layer effects
+
+Five extraction modes are available: `spec` (default), `tokens`, `components`, `assets`, and `content`.
+
+## Works with any AI coding agent
+
+ralph-starter is agent-agnostic. The Figma wizard works with:
+
+- **Claude Code** (Claude Opus 4.6, Sonnet 4.5)
+- **Cursor** (any model)
+- **OpenAI Codex** (o3, o4-mini)
+- **Gemini CLI** (Gemini models)
+- **GitHub Copilot**
+- **OpenCode**
+- **Amp**
+
+Skills (Tailwind v4, React best practices, design systems) are auto-injected into the agent's context, so it generates code that follows current best practices regardless of which agent you choose.
+
+## Try it
+
+```bash
+npm install -g ralph-starter@latest
+ralph-starter figma
+```
+
+Or without installing:
+
+```bash
+npx ralph-starter figma
+```
+
+The tool is free and open source. Costs come from the AI agent you choose — typically $0.10 to $1.00 per page depending on complexity and model.
+
+## Beyond Figma
+
+ralph-starter is not just for Figma. The same autonomous loop works with specs from GitHub issues, Linear tickets, Notion pages, URLs, PDFs, and plain text files. Point it at a spec, pick an agent, and let it build.
+
+```bash
+ralph-starter run --from github --issue 42 --commit
+ralph-starter run --from linear --label ready --commit
+ralph-starter run --from notion --project "API Spec" --commit
+```
+
+## References
+
+- [Figma wizard CLI docs](/docs/sources/figma)
+- [Figma integration guide](/docs/sources/figma)
+- [Visual validation docs](/docs/advanced/validation)
+- [Supported agents](/docs/intro)
+- [Cost tracking guide](/docs/guides/cost-tracking)
+- [Full v0.4.0 changelog](/docs/community/changelog)
+- [GitHub repository](https://github.com/multivmlabs/ralph-starter)