Convert Url To Nextjs

Convert URL or HTML Snapshot to Next.js — AS-IS Pixel-Faithful Rebuild

The scenario this skill is built for

A company lost the GitHub repo behind its frontend. The only thing left is the production build at example.com. The team wants the same-looking site back in their own stack — as a real, editable Next.js codebase — pixel-faithful to the deployed build, AS IS. The skill's job is to recover what is already in the world, not to redesign it. Throughout this workflow, when a judgment call surfaces between visual fidelity to the live deployed build and a more idiomatic Next.js choice, fidelity wins until the user explicitly opts out.

The output is one Next.js template per unique page type the source actually uses, plus a route map saying which live URLs are instances of which type. The user's expected next step after this skill finishes is usually to wire dynamic content (TinaCMS, MDX, or any CMS of their choice) onto those templates.

When to use this skill

• "Rebuild this URL as a Next.js site" (live URL, with or without scope filtering).
• "I lost my frontend repo and only have the build — recover the deployed site" (the canonical lost-frontend scenario).
• "Recover this page — the original repo is gone but the prod URL still works" (production-only recovery).
• "Convert this .html snapshot / SingleFile export into Next.js" (offline .html + _files/, adjacent local CSS, or inline `` only).
• "Clone / recreate / pixel-perfect / faithful rebuild" of an existing public page in Next.js.
• "Mirror this site offline as a Next.js app" with self-hosted fonts, images, and icons.

Do NOT use this skill when

• The only source is a screenshot, PDF, Figma, or "vibe" reference — there is no parseable HTML/CSS or live route. This skill needs inspectable implementation to rebuild; with no HTML to crawl, use a generic UI-build path instead.
• The user wants a redesign, simplification, or "same vibe" rewrite rather than faithful reconstruction.
• The user wants generic Next.js UI work with no source URL or snapshot grounding.
• The user wants a TinaCMS-backed editorial site from scratch — use build-tinacms-nextjs.

Sibling routing

| Need | Route to | |---|---| | Browser capture and the back-to-back verification loop in this pipeline | run-agent-browser is the helper this skill drives. | | Design-doc-only output for SaaS/dashboard/admin | a generic design-documentation path. Use this skill only when the deliverable is a buildable Next.js page. | | New CMS-backed Next.js site | build-tinacms-nextjs. This skill is for URL/snapshot reconstruction, not CMS scaffolding. The user typically uses build-tinacms-nextjs after this skill, to wire content onto the recovered templates. |

Setup contract

| Key | Value | |---|---| | Output location | nextjs-project/ plus .design-soul/ beside the capture or snapshot working root. | | Naming | Routes, capture IDs, manifests, asset folders, CSS classes, and tokens use kebab-case. React component files and exported component symbols use PascalCase. | | Minified-CSS warning | Captured/saved CSS is often minified (no trailing ; before }). Reference grep patterns use [^;}]+ — do not simplify to [^;]+, or extraction will silently miss values. | | Allowed deps | Limited to the scaffold rules in references/system-template.md. No icon, animation, or font packages added for convenience. |

Scripts

| Phase | Helper | Use | |---|---|---| | Capture | scripts/capture-url.sh (read scripts/capture-url.md) | Build the route capture skeleton, record expected artifacts, run the supplied browser-capture command. Never write a success signal on failure. | | Wave 0 | scripts/extract-styles.sh (read scripts/extract-styles.md) | Detect the page CSS corpus and emit manifests plus custom-property, font, media-query, and keyframe summaries before manual extraction. | | Verification | scripts/diff-screenshots.sh (read scripts/diff-screenshots.md) | Compare source vs build screenshots / paired directories and emit .design-soul/visual/{route}/summary.json. Do not fabricate diff metrics when tooling is missing. |

Decide first: which input mode are you in?

| Situation | First action | |---|---| | Live URL only — the lost-frontend default | Run the Capture Wave on L0, then crawl L1 from the homepage, then run type extraction. See references/type-extraction.md. | | Live URL + narrow scope request | Capture only in-scope L0+L1 routes, but still produce the route manifest and per-type cluster before implementing. | | .html + _files/ folders present | Skip live capture. Treat the snapshot as Wave 0 input directly; if multiple snapshots are present, still run type extraction on them. | | .html + adjacent local .css files, no _files/ | Use adjacent-asset snapshot mode. The local CSS and assets are the Wave 0 corpus. | | .html with inline ` only | Use **SingleFile fallback mode**. Extract from inline styles and document reduced confidence. | | package.json` + source repo, no live site, no snapshot | Source-fallback mode: read source directly. Same grounding/verification rules apply. | | Request says extract, document, design system, or tokens | Stop after the Capture Wave or Waves 0–2 unless the user explicitly asks to build. | | Request says rebuild, recreate, convert, clone, recover, or pixel-perfect | Run the full pipeline: Capture → Type Extraction → Waves 0–4 → Back-to-back verification → Report back to user. | | Source spans many routes / templates | The type-extraction phase handles this — cluster L1 URLs into unique types first, finish one type completely, then fan out. | | Request is ambiguous | Default to grounded extraction first. Do not assume a full rebuild. |

Read references/input-output-spec.md for input detection, working-root rules, route normalization, output trees, and ambiguity handling. Read references/capture-workflow.md when starting from a live URL.

Operating contract (load-bearing rules)

1. Fidelity to the deployed build is the goal. When a judgment call surfaces between visual fidelity and an "improvement," fidelity wins. Ask the user before deviating.
2. Capture before extract when the source is live. Build the L0+L1 route inventory, layout fingerprints, screenshots, runtime metadata, mirrored asset roots, and grounded DOM artifacts before Wave 0. See references/capture-workflow.md and references/type-extraction.md.
3. One template per unique page type, not one template per URL. See references/type-extraction.md.
4. Preserve the strongest offline artifact set. _files/ folders, adjacent local CSS, and inline styles are all valid snapshot evidence. Do not discard a snapshot because it does not match one filename convention.
5. Parse, don't guess. Every value must trace to captured CSS, HTML, runtime metadata, or documented behavior. See references/principles-and-rules.md.
6. Screenshots are for verification, not invention. Use full-page and scroll-slice screenshots to detect missed structure and to measure fidelity — not to derive token values when CSS/HTML evidence exists.
7. Build from extracted values only. tokens.ts, tailwind.config.ts, globals.css, components, and route data must trace to Capture/Wave 0/Wave 1 artifacts. Mark unverifiable values UNVERIFIED rather than substituting defaults.
8. Self-host everything. Fonts, images, icons, and other assets must end up local. No CDN fonts. No remote image URLs.
9. Preserve asset provenance. Record original source URLs and asset origins. Self-host captured images, fonts, and icons only when the user owns or has permission to use them; otherwise mark replacements UNVERIFIED or user-supplied. Workflow guardrail, not legal advice.
10. Verify back-to-back against the original before claiming a type is done. See references/back-to-back-verification.md.
11. If something cannot be grounded, mark it UNVERIFIED. Honest gaps are allowed. Invented values are not.

Do this / not that

| Do this | Not that | |---|---| | Treat the live deployed page as ground truth; recover AS IS | "Improve," modernize, or redesign while rebuilding | | Capture L0 + every L1 link; cluster L1 by layout fingerprint into unique page types | Generate one Next.js route per URL | | Produce one Next.js template per unique page type | Duplicate similar layouts as bespoke per-route JSX | | Use CSS Module prefixes, semantic tags, heading outlines, and screenshot coverage together to identify sections | Infer structure from generic ` nesting or above-the-fold screenshots alone | | Search across the full discovered CSS corpus per page, then deduplicate shared files | Read minified CSS by eye or treat each hashed CSS file as an isolated system | | Carry exact source values through Capture / Wave 0 → Wave 4 | Round, normalize, or replace values because they look "close enough" | | Run the back-to-back verification loop at 1440/768/375 per type before declaring done | Declare success from build success or spot-checking only the top viewport | | Keep deps to the scaffold rules in references/system-template.md` | Add UI, icon, animation, or font packages for convenience |

The phased workflow at a glance

| Phase | Goal | Required reference | Primary outputs | Gate | |---|---|---|---|---| | 1. Capture (L0 + L1) | Crawl homepage and every same-origin link from it; capture hydrated DOM, screenshots, runtime metadata, and mirrored assets per URL | references/capture-workflow.md + references/input-output-spec.md | .design-soul/capture/{route}/dom.html, mirror/, screenshots, runtime-metadata.json | per-route capture artifacts present | | 2. Type extraction (NEW NAMED PHASE) | Cluster L1 URLs into unique page types by layout fingerprint; choose a canonical exemplar per type; emit route-map.json | references/type-extraction.md | .design-soul/types/route-map.json, page-types.md, per-URL fingerprints | route-map.json complete, one exemplar per type | | 3. Per-type rebuild | For each type, extract tokens (Wave 0), unify family (Wave 1), brief the build (Wave 2), scaffold (Wave 3), render (Wave 4) into one Next.js template per type | references/foundations-agent.md, references/sections-agent.md, references/section-template.md, references/system-template.md, references/wave-pipeline.md, references/website-patterns.md | nextjs-project/app/... (one template per type) | wave3/foundation-ready.signal + per-type Wave 4 build passes | | 4. Back-to-back verification (NEW NAMED PHASE) | Per type, drive run-agent-browser to load the original exemplar URL and the candidate Next.js URL at the same viewport; compare; pass/iterate/escalate | references/back-to-back-verification.md + scripts/diff-screenshots.md | .design-soul/verify/{type}/iterations.json, screenshots, summary.md, verification-report.md | all types pass at desktop/tablet/mobile, or user-approved residual drift | | 5. Report back to the user (NEW NAMED PHASE) | Surface every type found, the L1 URLs it covers, the template path, the verification evidence, the residual drift, and the recommended next step | This SKILL.md — "Report back to the user" section below | RECOVERY-REPORT.md at the working root | user has the complete map of what was rebuilt and what is optional from here |

If the user only asked for extraction or documentation, stop after Phase 2 or Wave 1 instead of pushing to build.

Phase 1: Capture L0 and L1

The crawl is the homepage (L0) plus every same-origin link reachable from it (L1). The capture contract per URL is unchanged from the existing capture workflow.

• Open L0 with run-agent-browser. Wait for the page to settle. Capture hydrated dom.html, headings, runtime metadata, screenshots at 1440/768/375, and mirror the route's CSS/JS/fonts/images.
• Extract every same-origin in-DOM link from L0 (skip mailto:, tel:, javascript:, # anchors, external hosts, and obvious tracking/locale duplicates).
• Repeat the capture contract for each L1 URL. Treat sticky headers, lazy content, and modals as default-state captures unless the user asks otherwise.
• Crawl deeper than L1 only when the user explicitly opts in.

See references/capture-workflow.md for the full per-route capture contract, working-root selection, route normalization, and failure recovery. Use scripts/capture-url.sh to scaffold the per-route artifact skeleton; the script delegates to the browser command and verifies artifacts before returning success.

Phase 2: Type extraction — one template per unique page type

This is the discrete named phase that converts the L1 URL set into the small number of unique page types the site actually uses. It runs before any rebuild work. Read references/type-extraction.md for the full procedure.

What this phase produces

• .design-soul/types/fingerprints/{slug}.json — one layout fingerprint per L1 URL
• .design-soul/types/route-map.json — { typeId → { exemplarUrl, instances, nextjsTemplate, captureRoots } }
• .design-soul/types/page-types.md — human-readable rationale per cluster (signal evidence, exemplar choice, notable instance differences)

What goes into a layout fingerprint

Compute these for each L1 URL from the hydrated DOM:

• pathname pattern with slug/numeric segments replaced by :slug
• ` and ` class set (sorted, deduplicated)
• top-level section sequence — ordered CSS Module prefixes or semantic tags of the direct children of ``
• direct-child section count
• recognizable widget set — hero, pricing table, FAQ accordion, logo wall, testimonial cards, blog metadata, contact form, legal heading rhythm, etc.
• header/footer shell hash (hashed class names normalized)
• top-N CSS class prefixes across the body

How clusters form

Two L1 URLs join the same type cluster when all three hold:

1. pathname template matches
2. section-sequence overlap ≥ ~70%
3. header/footer shell hash matches OR top class-prefix overlap ≥ ~60%

Homepage is always its own type. A cluster of size 1 is valid. A cluster of 20+ visually diverse instances is a signal to ask the user before continuing.

Output to the rebuild phase

One Next.js template per type:

• single-instance type → app/{type-route}/page.tsx
• multi-instance type → app/{type-route}/[slug]/page.tsx

The rebuild phase reads route-map.json as its plan. Do not write any Next.js code until this phase has finished and route-map.json is on disk.

Phase 3: Per-type rebuild

For each type in route-map.json, run the existing waves against the type's canonical exemplar (and any instance-specific overrides that surfaced in Phase 2):

• Wave 0 — per-page exploration and deobfuscation. See references/foundations-agent.md. Use scripts/extract-styles.sh first to inventory the CSS corpus before manual extraction.
• Wave 1 — unified design soul for the type's family. See references/sections-agent.md. Anatomy heuristics live in references/website-patterns.md.
• Wave 2 — self-contained build brief per type. See references/section-template.md.
• Wave 3 — Next.js scaffold and shared design-system foundation. See references/system-template.md. Allowed deps and foundation-ready.signal gate are defined there.
• Wave 4 — render the type's template under app/. Full orchestration and quality gates live in references/wave-pipeline.md.

Think first:

• Capture: Which browser helper produces the complete evidence contract for this source? (Use run-agent-browser.)
• Type extraction: Are any clusters borderline? If yes, ask before committing.
• Wave 0: Which CSS corpus is strongest for this type — mirrored live capture, _files/, adjacent CSS, inline CSS, or source fallback?
• Wave 3: Which types stay static, and which exact interactions justify Client Components?
• Wave 4: Ha

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yigitkonur
• Source: yigitkonur/skills-by-yigitkonur
• License: MIT

Install and usage instructions live in the source repository linked above.