Snapshot to Next.js

Convert saved HTML snapshots into grounded Next.js App Router builds. Treat the snapshot as source code, not inspiration: extract first, rebuild from extracted values, then prove the rebuilt page matches.

Use this skill when

• Input is a saved snapshot: .html + companion _files/ folders, SingleFile export, or an unpacked offline site capture.
• The user wants to rebuild, recreate, convert, clone, scaffold, or extract a saved site into Next.js.
• Fidelity matters more than speed or creative redesign.

Do not use this skill when

• The only source is a live URL, screenshot, PDF export, Figma design, or loose design idea.
• The task is general Next.js UI coding with no offline snapshot to parse.
• The goal is a redesign, simplification, or "same vibe" rewrite instead of faithful reconstruction.

Setup

Start with these decisions

Read references/input-output-spec.md for full input detection, output trees, and ambiguity handling.

Operating contract

1. Extract before build. No Wave N+1 starts until all Wave N signals exist. Read references/wave-pipeline.md.
2. Parse, don't guess. Every value must trace to snapshot CSS, HTML, or documented behavior. Read references/principles-and-rules.md.
3. Build from extracted values only. tokens.ts, tailwind.config.ts, globals.css, and components must trace to Wave 0/1 extraction; mark incomplete values UNVERIFIED instead of substituting Tailwind defaults.
4. Self-host everything. Fonts, images, icons, and other assets must end up local. No CDN fonts. No remote image URLs.
5. Write signals last. done.signal and foundation-ready.signal are written only after verification passes.
6. If something cannot be grounded, mark it UNVERIFIED. Honest gaps are allowed. Invented values are not.

Do this / not that

Required sequence

If the user only asked for extraction or documentation, stop after the appropriate wave instead of pushing to build.

Asset and style handling rules

• Extract CSS custom properties, @font-face, @media, @keyframes, and transition values before touching the build.
• Treat Wave 1 token-values.json as the source of truth for tokens; Wave 3 only re-expresses those exact values in tokens.ts, Tailwind config, and globals.css.
• Copy fonts to public/assets/fonts/, images to public/assets/images/..., and icons to public/assets/icons/ or inline them only when the source uses inline SVG.
• Preserve exact typography, spacing, gradients, shadows, radii, z-index, and breakpoint values.
• Preserve responsive behavior from real source media queries; do not substitute Tailwind defaults if the snapshot uses different breakpoints.
• Preserve extracted interaction behavior, but only if it can be grounded from CSS or documented JS behavior specs.
• For inline style="" attributes or JS-driven states, extract the base CSS and the trigger separately; do not freeze computed runtime values into guessed static styles.

Recovery rules

• Missing _files/ folder: treat as SingleFile mode if inline CSS exists; otherwise full reconstruction may be blocked.
• Missing assets or remote-only assets: download them during extraction and record original → local path mapping.
• Missing fonts: Check <link> tags for Google Fonts / Typekit URLs. Download font files to public/assets/fonts/ and create @font-face declarations. If URL is unreachable, substitute with a system font stack and add /* TODO: replace with original font */.
• External JS (analytics, chat widgets): Do NOT embed third-party scripts. Add a {/* TODO: re-add [service] script */} comment in layout.tsx.
• Missing CSS or JS evidence for a value or behavior: mark it UNVERIFIED and avoid inventing the implementation.
• Incomplete snapshot: continue extraction where possible, but do not claim a pixel-perfect rebuild if core layout, type, or asset data is missing.
• Shared headers, footers, or components across pages: deduplicate them intentionally; note page-specific overrides rather than re-documenting the whole component each time.

CLI-verifiable acceptance criteria

Every conversion must pass these checks before declaring success:

# Type-check passes
npx tsc --noEmit

# Production build succeeds
npm run build

# No UNVERIFIED comments remain
grep -r 'UNVERIFIED' app/ components/ lib/ styles/ && echo "FAIL: unverified values" || echo "PASS"

# No external URLs leak into components
grep -rE 'https?://' components/ | grep -v '// original:' && echo "FAIL: external URLs" || echo "PASS"

Verification before claiming completion

• After extraction (before Wave 3): run the grounding test and cross-reference checks from references/quality-checklist.md.
• Before foundation-ready.signal: verify extracted CSS custom properties and shared tokens are accounted for, allowed dependency set, self-hosted fonts/assets, traceability matrix, and clean TypeScript/build checks.
• Before final completion: compare source vs build at 1280px, 768px, and 375px; confirm zero external network requests; run clean install/build verification.
• If any verification fails, fix it before writing the completion signal or calling the build done.

Reference map

Read only the references needed for the current wave. Keep the top-level skill focused on decisions, sequencing, and guardrails; keep implementation detail in the reference files.