pixel-perfect
A Claude Code plugin that skips the mockup abstraction entirely. Instead of generating designs that get "lost in translation," it builds the real components in your target framework during design ideation — browsable in a native sandbox it generates from scratch (Storybook optional).
Why Skip the Abstraction?
Your Figma mock is not your product. And AI just made that abstraction obsolete.
AI reads code better than it reads pixels. That insight flipped everything. Why mock when you can just… make the thing?
The unlock was the sandbox — a tiny component browser. Storybook is one web version of it; but the AI can generate one from scratch in any framework. Turns out when the sandbox builds itself, every stack gets one.
pixel-perfect follows the organic design process:
- Define theme tokens
- Build atomic components
- Scaffold entire views
All in a sandbox — native to your framework (or Storybook, if you prefer). All production-ready from the start. No more pointing at the moon — you just go there.
The 7-Phase Process
| Phase | What Happens | Gate Checks |
|---|
| DISCOVER | Define goal + vibe from PRD | Goal statement exists, vibe captured |
| TARGET | Select platforms + framework | Platform/framework declared |
| EQUIP | Select style + component libraries | Adapters validated |
| SCAFFOLD | Install tools, create theme, generate token stories | Theme renders, sandbox runs |
| ATOMS | Build individual components | Each component has story + controls |
| MOLECULES | Build functional atom compositions (optional) | Each molecule has story + state scenarios |
| ORGANISMS | Build complex stateful compositions (optional) | Each organism has story + state scenarios |
| COMPOSE | Assemble screens from organisms, molecules, atoms | Screens render with real data shapes |
| INTEGRATE | Wire navigation + state | App navigates, state persists |
Each phase has a gate that must pass before you proceed. The plugin tracks state in design/manifest.json and blocks forward progress until gates clear.
Quick Start
Installation
/plugin marketplace add https://github.com/hackerpug-ai/pixel-perfect
/plugin install pixel-perfect@pixel-perfect
First Project
# 0. (Optional) Start from an existing design instead of a blank PRD
/pixel-perfect:design-deconstruct https://example.com # or a screenshot, repo, or concept
# 1. Set up your project (phases 1-3)
/pixel-perfect:init
# 2. Scaffold tools, theme, token stories (phase 4)
/pixel-perfect:scaffold
# 3. Build components and screens (phases 5-7)
/pixel-perfect:build
# Check progress anytime
/pixel-perfect:status
Init walks you through:
- Where are your requirements? (auto-detects PRD.md)
- What's the goal? (one sentence)
- What's the design vibe? (clean, bold, playful, etc.)
- What platforms? (web-desktop, web-mobile, mobile-ios, mobile-android)
- What framework? (React, Next.js, Vite, SvelteKit, React Native, Expo, or provide docs URL)
- What style system? (Tailwind, NativeWind, CSS Modules, or provide docs URL)
- What component library? (shadcn, shadcn-svelte, Bits UI, Skeleton, Paper, Mantine, none, or provide docs URL)
The UI library is completely flexible — use whatever you want or build from scratch. pixel-perfect uses AskUserQuestion to follow your lead.
The Sandbox — a spec, not a tool
A sandbox is just a component browser: it catalogs your components by layer and renders each one in isolation, themed. Storybook is one implementation of that idea (for the web) — not the idea. So pixel-perfect treats the sandbox as a spec (docs/sandbox-spec.md) and, by default, builds one from scratch in your target framework — rendering the real components, nothing extra to install. An off-the-shelf tool is used only if you ask.
The spec is ~7 small pieces (a layer-keyed story registry · isolated render · a two-pane navigator · token codegen from theme.*.json · a run command · pixel-target refs). It's derived from two real, running sandboxes built from scratch in Rust — a GPUI desktop one and a Ratatui TUI one — the same concept in totally different paradigms.
Why custom (v6 default)
Storybook is great — for web projects that want Storybook. But pixel-perfect builds UI in any framework: React, SvelteKit, React Native, Expo, GPUI, Ratatui, SwiftUI. Shoehorning all of those into Storybook means fighting Storybook — native-web shimming, addon incompatibilities, version conflicts, and an entire toolchain that doesn't apply outside a browser.
