Table of contents
Why
Every AI coding tool previews at laptop width. The site looks finished, ships, and then breaks on the phone every customer actually uses: horizontal scroll, 24px buttons, hover menus that never open, a hero that is empty for a whole screen, a Three.js scene rendering seven times more pixels than the phone can show.
phonefix gives the agent what it was missing: real phone viewports, thirty concrete checks, an ordered fix list that goes after root causes, and a verify step that it cannot skip.
Set up in sixty seconds
- Get Playwright once per machine. It renders the phone viewports.
npx playwright install chromium webkit
- Add phonefix to your project with the one-liner for your agent below. Nothing global changes; the skill lands in
.phonefix/ (or .claude/skills/) and a 14-line pointer goes into your agent's rules file.
- Run your app (
npm run dev) or have a static build folder ready.
- Tell your agent: "make this mobile-perfect". It captures a baseline, fixes in order, captures again and opens
phonefix-report/report.html.
- Read the report, spot-check the worst device on a real phone, ship.
Prefer to download instead of a CLI? Grab the latest zip, copy skills/phonefix/ into your project, and paste the block from adapters/pointer.md.tmpl into your agent's rules file (replace {{SKILL_PATH}} with where you put it).
Install
Any agent
npx skills add kp6801-ai/phonefix
The skills CLI installs into whichever agents it finds in the project.
Claude Code
npx skills add kp6801-ai/phonefix -a claude-code
Or without the CLI, as a global skill:
git clone https://github.com/kp6801-ai/phonefix ~/.claude/skills/phonefix
Cursor
curl -fsSL https://raw.githubusercontent.com/kp6801-ai/phonefix/main/skills/phonefix/scripts/install.sh -o phonefix-install.sh && sh phonefix-install.sh --agent cursor
Writes .cursor/rules/phonefix.mdc and copies the skill into .phonefix/.
Codex
curl -fsSL https://raw.githubusercontent.com/kp6801-ai/phonefix/main/skills/phonefix/scripts/install.sh -o phonefix-install.sh && sh phonefix-install.sh --agent codex
Appends a 14-line block to AGENTS.md between <!-- phonefix:start --> and <!-- phonefix:end -->. Your existing rules stay.
Windsurf
curl -fsSL https://raw.githubusercontent.com/kp6801-ai/phonefix/main/skills/phonefix/scripts/install.sh -o phonefix-install.sh && sh phonefix-install.sh --agent windsurf
GitHub Copilot
curl -fsSL https://raw.githubusercontent.com/kp6801-ai/phonefix/main/skills/phonefix/scripts/install.sh -o phonefix-install.sh && sh phonefix-install.sh --agent copilot
Gemini CLI
curl -fsSL https://raw.githubusercontent.com/kp6801-ai/phonefix/main/skills/phonefix/scripts/install.sh -o phonefix-install.sh && sh phonefix-install.sh --agent gemini
--agent all covers every agent in one run. Re-running is safe: the installer refreshes the skill copy and rewrites only its own block. Read the installer before you run it; it is 50 lines.
How it works
| Phase | What happens |
|---|
| 1. Discover | detect.mjs reads the project offline: framework (static, Vite, Next, Nuxt, SvelteKit, Astro), Tailwind, GSAP, ScrollTrigger, Lenis, Three.js, R3F, Spline, dev command and port, where the viewport meta lives. |
| 2. Baseline | Git checkpoint, then capture.mjs renders every route on iPhone SE 375, iPhone 15 393, iPhone 15 Pro Max 430, Pixel 7 412, Galaxy S23 360, iPad 768, iPhone 15 landscape, plus a 1440 desktop guard. Five scroll positions per device so scroll-driven animation runs. |
| 3. Audit | Nine categories scored 0 to 4. The agent also opens the two smallest-device screenshots. Eyes catch what the DOM cannot prove. |
| 4. Fix | Thirteen ordered rules, root cause first. Never hides overflow, never disables zoom, never deletes an animation, never changes the desktop design. |
| 5. Verify | Captures again and builds phonefix-report/report.html: verdict, score deltas, before/after grid per device, remaining issues with reasons, desktop drift. Passes only with zero severity-4 issues. |
The skill itself is skills/phonefix/SKILL.md. Deep rules load only when a category fails.
What it checks
| Category | Checks |
|---|
| Viewport | meta missing, no width=device-width, zoom disabled, no viewport-fit=cover |
| Layout | horizontal overflow with the widest offenders named, fixed px widths over 430, no breakpoints, 100vh, fixed bars without safe-area, oversized fixed headers, overflow:hidden on body |
| Touch | tap targets under 44px, :hover-only reveals outside (hover:hover), JS mouseenter-only handlers |
| Forms | inputs under 16px (iOS zooms on focus) |
| Type | body under 16px, text under 12px |
| Media | large images without srcset, missing dimensions, video without muted / playsinline / poster |
| Motion | no prefers-reduced-motion handling, pinned section taller than the viewport, ScrollTrigger without mobile config, desktop-pixel tweens |
| 3D | canvas DPR over 2, stretched canvas, over 4 megapixels of canvas, too many WebGL contexts |
| Runtime | console errors and uncaught exceptions on load |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
