# Retrofit > Entry point for existing Next.js sites that ultraweb did not build — inventory the codebase and routes, sweep for banned-list patterns, boot the site, screenshot every page at 375/768/1440, score it against the taste constitution via the design-judge rubric, and write design/RETROFIT.md — scored gaps each mapped to the one ultraweb skill that fixes it, phased into quick wins → system fixes → direction change, each phase then executed via ultraweb:iterate. Invoke when the user points at an existing site and asks to "improve", "audit the design", "modernize", "redesign", or "bring it up to standard", or asks "how bad is my site". For building from scratch use the root ultraweb skill; for a scoped change to a site that already has design/* artifacts use ultraweb:iterate directly. - Skill: `blyatiful1/retrofit` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add blyatiful1/retrofit` - Raw SKILL.md: https://api.skillmd.com/api/skills/blyatiful1/retrofit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: blyatiful1 (https://skillmd.com/u/blyatiful1) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/blyatiful1/retrofit --- # retrofit — diagnose before redesigning **Stage:** Entry point — before any pipeline phase, for sites ultraweb did not build - **Reads:** existing codebase, running site, taste - **Writes:** design/RETROFIT.md, design/screenshots/retrofit/*, qa/visual/round-1/VERDICT.md, reconstructed design/BRIEF.md + DIRECTION.md ## Standard A diagnosis a studio would charge for: every gap carries evidence (a screenshot path or a file:line grep hit), a score against the taste rubric, the ONE ultraweb skill that fixes it, and a phase. Scores come from looking at rendered pages — never from reading code alone. Retrofit is a **mutating audit** and says so up front: it writes the design record into the repo (design/RETROFIT.md, screenshots, a reconstructed BRIEF.md + DIRECTION.md) and touches app code only where required to boot the site — each boot fix named in RETROFIT.md. All treatment happens afterward, through ultraweb:iterate, one approved phase at a time. ## Process 1. **Qualify the patient.** First: if `design/DIRECTION.md` already exists, STOP — this is an ultraweb site, and retrofit against it would overwrite real recorded decisions with reconstructed guesses. A complete record is `ultraweb:iterate`'s case; a partial one is the root skill's §Resuming ladder. Then read package.json and the tree. Next.js App Router → proceed. Pages Router, CRA, or another framework → say so and stop; retrofit audits, it doesn't port. Offer a fresh `ultraweb` build as the alternative. 2. **Inventory.** Routes (every `app/**/page.tsx`), components, styling entry (`@theme` in app/globals.css vs `tailwind.config.js` — the config file marks Tailwind v3), and deps of record: next major, `framer-motion` vs `motion`, zod major, `middleware.ts` (pre-Next-16 signal) vs `proxy.ts`. Collect any written direction statement too (style guide, brand page, README §design) — step 6 needs it. 3. **Static anti-slop sweep** — grep the banned list before rendering anything: - `lorem`, `href="#"`, `Feature 1`, `placeholder.com` - `from-purple-|from-violet-|to-blue-` and headline `bg-clip-text` gradient text - `✨|🚀|🎉` and emoji-as-icons in TSX - counts of `rounded-xl` and `shadow-lg` — near-universal usage = depth without hierarchy - `Elevate|Unlock the power|Seamlessly|Empower|Welcome to` Every hit is a pre-scored gap with file:line evidence. 4. **Boot it.** `npm install`, `npm run dev`. Won't start → hand the verbatim error to stack-doctor and apply the minimal fix that gets pixels on screen. No other code changes during the audit. 5. **Screenshot everything.** pixel-qa drives Playwright MCP, `outputDir: design/screenshots/retrofit/`: viewport frames per route at 375/768/1440, light + dark when a toggle exists, plus 1440 sectionals. No full-page captures — the judge refuses frames >2500px. Console errors are recorded as gaps. 6. **Score.** `mkdir -p qa`, then dispatch design-judge as round 1, pointed at `design/screenshots/retrofit/` as the round directory (frames + sectionals), the project and plugin roots. No `design/DIRECTION.md` exists — step 1 refused the site if it did — so hand it the step-2 direction statement as the stand-in and tell it to score against the taste constitution and the award-canon invariants alone. It scores its own fixed six axes, writes the full review to `qa/visual/round-1/VERDICT.md`, returns ≤700 tokens: scores, ranked defects, verdict, plus round-1's antislop/responsive lines — fold every violation into the gap table. Compute the mean and the worst axis yourself from that table — the judge returns neither. 7. **Map every gap to one skill** (table below). A gap without a named fixing skill isn't finished — "improve the design" ships nothing. 8. **Phase the plan** into design/RETROFIT.md: A quick wins → B system fixes → C direction change (only when triggered). 9. **Bootstrap the artifacts iterate needs.** Reverse-engineer design/BRIEF.md from the evident site (audience, purpose, pages, backend surface) — including the machine-read fields every consumer expects: `Deployment mode: production` (an existing live site is production; never guess demo) and, when the site serves a named market, §Compliance facts reconstructed from the Impressum and shop surface (flag each entry `counsel-needed` — reconstructed facts are assumptions, not knowledge). Write design/DIRECTION.md as the TARGET direction — the existing aesthetic sharpened, or, when Phase C triggers, a fresh pick via ultraweb:direction. 10. **Hand off.** Present RETROFIT.md. Each approved phase executes via `ultraweb:iterate` with this file as the change request. Phase C is the burn-it-down case: get explicit user confirmation of scope before starting it. ## Scoring rubric design-judge's six fixed axes, 1–10 per page — Motion folded into Craft (its contract has no Motion axis): | Axis | 8–10 looks like | ≤4 means | |---|---|---| | Hierarchy | the eye lands where the page intends | everything shouts equally | | Typography | real pairing, hero ≥3.5× body | default Inter at timid sizes | | Spacing | compression and release on a base unit | uniform py-24 wallpaper | | Color | one accent doing real work, AA verified | slate + purple gradient, or gray soup | | Distinctiveness | a point of view and a signature move | interchangeable template | | Craft | focus rings, favicon, optical alignment; purposeful motion, one easing family, reduced-motion path | defaults in the last 2%; everything fades up, or nothing moves | Report the WORST axis alongside the mean — a 7.0 average hiding a 2/10 distinctiveness IS a distinctiveness problem. Triggers: any axis ≤4 → its system fix goes to Phase B. Distinctiveness ≤4, or no identifiable direction at all → Phase C candidate. ## Gap → skill map (canonical examples) | Gap found | Fixing skill | Phase | |---|---|---| | Dead startup copy, lorem, "Feature 1" | copywriting | A | | Emoji as icons | icons | A | | Missing metadata / OG image / favicon | seo | A | | No focus-visible, contrast failures | micro-interactions + color (verify via gate-accessibility) | A | | Untouched shadcn look (Inter, slate, default radius) | tokens + color + typography | B | | Uniform section rhythm, everything centered | layout-grid | B | | Three identical icon-cards as "features" | feature-sections | B | | Dark mode absent, or an inversion filter | color + tokens | B | | Motion on everything, or none at all | motion-language + scroll-motion | B | | Tailwind v3 config / framer-motion / middleware.ts | stack migration first — prerequisite to all Phase B token work; verify steps against current migration docs | B-0 | | No point of view; template look | direction, then Phase 3 of the root pipeline | C | ## RETROFIT.md format ```markdown # Retrofit — () Verdict: . Mean /10, worst axis: /10. ## Scorecard | axis | score | evidence (screenshot / file:line) | ## Gaps | # | gap | evidence | severity P0–P3 | skill | phase | ## Plan - Phase A — quick wins (hours, local, reversible): #3, #7, #9… - Phase B — system fixes (globals.css tokens + foundation skills): #1, #2… [B-0 stack migration first if flagged] - Phase C — direction change (only if triggered; confirm scope with the user): … Execute each phase via ultraweb:iterate, pointing it at this file and the phase id. ``` ## Anti-patterns - Fixing while auditing — the only permitted edit is whatever boots the dev server - Scores produced without screenshots — code reading is inventory, not judgment - "Improve visual hierarchy" with no skill, no evidence, no phase — that's a shrug, not a gap - Every gap mapped to "rebuild it" — Phase C is the exception; most sites need B - Reporting only the mean score — the worst axis is the headline - Treating `tailwind.config.js` as cosmetic — it blocks the entire token strategy; migration is B-0 - Skipping the artifact bootstrap — iterate refuses sites without design/BRIEF.md and DIRECTION.md ## Worked example — Ledger & Lane, auditing the firm's inherited site Moved to `references/example.md` — read only when this build's case is genuinely ambiguous; the sections above are the decision material. ## Composes with Moved to `references/composes.md` — the handoff map; load it when orchestrating this skill against its neighbors.