Paper to code

Paper-to-Code: Design to Production Website

You are converting a Paper design into a production-ready, animated, responsive website. Paper is a code-native design tool where the canvas IS real HTML/CSS — every element maps 1:1 to code. You have access to the Paper MCP server which lets you read the design programmatically.

Prerequisites Check

Before starting, verify:

1. Paper Desktop is running — the MCP server starts automatically on port 29979
2. The design file is open in Paper
3. Test MCP connection — call get_basic_info to confirm connectivity

If MCP fails, tell the user: "Please open Paper Desktop with your design file, then try again."

Phase 1: Design Reconnaissance

Step 1.1 — Get the Big Picture

Tools to call (in order):
1. get_basic_info → file name, page info, artboard count
2. get_tree_summary (depth: 2) → top-level section hierarchy
3. get_screenshot (root artboard, scale: 1) → full design visual

Step 1.2 — Map Sections

From the tree summary, identify each major section of the page. For a typical landing page:

• Navigation / Header
• Hero section
• Feature sections (may be multiple)
• Social proof / testimonials
• Pricing
• CTA / conversion section
• Footer

For each section identified:

1. get_screenshot (section node) → visual reference
2. get_jsx (section node, tailwind: true) → 1:1 code
3. get_computed_styles (key child nodes) → exact CSS values
4. get_children (section node) → component breakdown

Step 1.3 — Extract Design Tokens

From the collected data, document:

• Color palette — all unique colors (hex/oklch)
• Typography — font families, sizes, weights, line heights
• Spacing — padding, gaps, margins used
• Border radii — corner radius values
• Shadows — box-shadow definitions
• Gradients — any gradient fills

Create a design-tokens.ts or add to Tailwind config.

Step 1.4 — Catalog Assets

Identify all images, icons, illustrations, and decorative elements:

For each image node:
1. get_fill_image (node) → base64 image data
2. Save to /public/images/ with descriptive names

Phase 2: Architecture Plan

Step 2.1 — Section-by-Section Breakdown

Create a structured plan document (in memory, not a file) with:

Section: [Name]
├── Paper Node ID: [id]
├── Purpose: [what this section communicates]
├── Components needed: [list]
├── Scroll animation plan:
│   ├── Entry: [how it enters viewport]
│   ├── Internal: [any scroll-linked animations within]
│   └── Exit: [if applicable]
├── Responsive strategy:
│   ├── Desktop (1280px+): [from Paper design]
│   ├── Tablet (768-1279px): [adaptation plan]
│   └── Mobile (< 768px): [adaptation plan]
└── Interactive elements: [hover states, clicks, etc.]

Step 2.2 — Animation Design

For EVERY section, design animations following these principles:

Duration Rules (from Emil Kowalski):

Context	Duration
Micro-interactions	100-150ms
Tooltips, hover states	150-250ms
Section reveals, modals	200-300ms
Page transitions	300-500ms
Exit = 75-80% of entrance

Easing Rules:

• Element entering viewport → ease-out (fast start, smooth settle)
• Element moving on screen → ease-in-out
• Hover/color change → ease
• NEVER use ease-in alone (feels sluggish)

Spring Configs (preferred for organic feel):

// Apple-style (recommended default)
{ type: "spring", duration: 0.5, bounce: 0.2 }

// Snappy UI
{ type: "spring", stiffness: 300, damping: 30 }

// Gentle float
{ type: "spring", stiffness: 100, damping: 20 }

// Bouncy entrance (use sparingly)
{ type: "spring", stiffness: 200, damping: 15, bounce: 0.3 }

Common Section Animation Patterns:

1. Hero Section: No scroll trigger — animate on page load

   • Headline: fade up + slight scale (0.97 → 1), staggered words
   • Subtitle: fade up, 100ms delay after headline
   • CTA button: fade up + slight bounce, 200ms delay
   • Background: subtle gradient animation or shader

2. Feature Cards: Viewport entry triggered

   • Staggered fade-up with 80ms delay between cards
   • Slight y-offset (20-30px, not more)
   • Scale from 0.97 → 1 (NOT from 0 — elements should feel "inflated")

3. Card Stack on Scroll (special pattern):

   • See "Card Stack Animation" section below

4. Testimonials/Social Proof: Viewport entry

   • Fade in + subtle slide from sides
   • Stagger quotes

5. CTA Banner: Viewport entry

   • Scale from 0.95 → 1 with spring
   • Button pulse or glow animation after entry settles

6. Stats/Numbers: Viewport entry

   • Count-up animation (requestAnimationFrame, not re-renders)
   • Spring scale on the number

Performance Rules (MANDATORY):

• ONLY animate transform and opacity
• Never animate padding, margin, height, width
• Use will-change: transform only when animation is imminent
• Hardware-accelerate Framer Motion: use transform: "translateX(100px)" string form
• Pause off-screen animations with IntersectionObserver
• prefers-reduced-motion: disable ALL animations, show content instantly

Card Stack Scroll Animation

For the "See the product, not just the promise" section (or similar card carousel):

Pattern: Cards stacked with slight offset. As user scrolls, back card animates to front, front card moves to back. Like a deck being shuffled one card at a time, driven by scroll position.

Implementation approach (Framer Motion):

import { useScroll, useTransform, motion } from "framer-motion";

// Track scroll progress through the section
const { scrollYProgress } = useScroll({
  target: sectionRef,
  offset: ["start end", "end start"]
});

// Map scroll to card index
const activeIndex = useTransform(scrollYProgress, [0, 1], [0, cards.length - 1]);

// Each card gets:
// - z-index based on position relative to active
// - y offset (stacked behind)
// - scale (slightly smaller when behind)
// - opacity (dim when far back)
// - rotation (slight tilt for depth)

Key details:

• Make the section taller than viewport (e.g., 200-300vh) to give scroll room
• Use position: sticky on the card container so cards stay visible while scrolling
• Transition between cards should use springs for organic feel
• Cards behind should be slightly scaled down (0.95) and offset (y: -20px per level)
• Subtle shadow increase on the front card
• Use useMotionValueEvent to snap to nearest card

Overlapping Cards on Scroll

For the "Built to Keep You Consistent" section:

Pattern: Cards that compress/overlap as user scrolls past them. Each card has a different scroll speed creating a parallax stack effect.

Implementation:

// Each card gets its own scroll transform
const y1 = useTransform(scrollYProgress, [0, 1], [0, -50]);
const y2 = useTransform(scrollYProgress, [0, 1], [0, -100]);
const y3 = useTransform(scrollYProgress, [0, 1], [0, -150]);

// Cards use position: sticky with increasing top values
// As you scroll, they stack on top of each other

Phase 3: Code Generation

Step 3.1 — Project Setup

If starting fresh or rebuilding:

- Next.js 14+ (App Router)
- Tailwind CSS 3.4+
- Motion (motion/react) 12+ or Framer Motion 11+
- TypeScript

Preserve existing functionality:

• API routes (e.g., waitlist endpoints)
• SEO metadata and schema.org
• Legal pages
• Any backend integrations (Vercel KV, etc.)

Step 3.2 — Generate Components

For each section from the plan:

1. Read the JSX from Paper — get_jsx with tailwind mode
2. Clean the JSX — Paper outputs valid JSX but may need:
   • Extracting hardcoded values into props/constants
   • Adding semantic HTML elements (section, nav, article, etc.)
   • Replacing absolute positioning with flex/grid where appropriate
   • Adding responsive classes (Paper only has the desktop version)
3. Add animations — Wrap elements in motion.div with planned animations
4. Add responsiveness — Design mobile-first breakpoints:
   • Stack horizontal layouts vertically on mobile
   • Reduce font sizes proportionally
   • Adjust spacing (typically 60-70% of desktop)
   • Hide decorative elements that don't work on small screens
   • Convert multi-column grids to single column
5. Add interactions — Hover states, click handlers, scroll triggers

Step 3.3 — Responsive Breakpoints Strategy

Since Paper designs are desktop-only, derive mobile/tablet layouts:

Mobile (< 640px):
- Single column layouts
- Hamburger nav
- Full-width cards
- Reduced padding (px-4 to px-6)
- Font sizes: ~85% of desktop
- Stack side-by-side elements
- Hide complex decorative animations

Tablet (640px - 1024px):
- 2-column where desktop has 3+
- Condensed nav
- Font sizes: ~92% of desktop
- Moderate padding

Desktop (1024px+):
- Match Paper design exactly
- Full animations
- All decorative elements visible

Large Desktop (1280px+):
- Max-width container (1200-1400px)
- Centered content
- Paper design at full fidelity

Step 3.4 — Visual Verification

After generating each section:

1. Run npm run dev or next dev
2. Open in browser
3. Take a screenshot or ask the user to verify
4. Compare against Paper design (get_screenshot of the same section)
5. Iterate until pixel-perfect on desktop

Phase 4: Polish & Ship

Step 4.1 — Animation Audit

Review all animations using the /animate skill principles:

• Do animations serve the content's purpose?
• Is timing consistent across similar elements?
• Do paired elements share easing/duration?
• Is prefers-reduced-motion handled everywhere?
• Are scroll animations smooth (no jank)?

Step 4.2 — Performance Check

• Lighthouse score (aim for 90+ on all metrics)
• No layout shift from animations
• Images optimized (WebP, proper sizing, lazy loading)
• Fonts preloaded
• No unnecessary JavaScript

Step 4.3 — Accessibility Check

• Semantic HTML throughout
• Proper heading hierarchy
• Alt text on images
• Keyboard navigation works
• Focus states visible
• Color contrast meets WCAG AA
• prefers-reduced-motion respected

Step 4.4 — Cross-Browser Basics

• Test in Chrome, Safari, Firefox
• Verify animations work in Safari (known Framer Motion quirks)
• Check mobile Safari viewport handling

Skill Orchestration

This skill may invoke other skills during the process:

Phase	Skill	Purpose
Animation design	/animate	Add purposeful motion to sections
Animation details	/web-animation-design	Spring configs, easing decisions
Code quality	/emil-design-engineering	Design engineering best practices
UI polish	/polish	Final detail pass (alignment, spacing)
Frontend code	/frontend-design	Production-grade component code
Design review	/critique	Evaluate design effectiveness
Responsive	/adapt	Adapt for different screen sizes
Accessibility	/audit	Comprehensive accessibility audit

Important Notes

• Paper's JSX is your source of truth — the design IS code. Trust it.
• Don't over-animate — every animation must serve the content. When in doubt, less is more.
• Mobile first in code, desktop first in design — Paper gives you desktop; build mobile breakpoints up from there.
• Sticky sections for scroll animations — use position: sticky + scroll progress for parallax/stacking effects.
• Test with real content — Paper designs may have placeholder text. Replace with real copy early.
• Ship incrementally — deploy each section as it's ready, don't wait for perfection.

Quick Start (TL;DR)

1. Open Paper Desktop with design → MCP auto-connects on :29979
2. /paper-to-code [file-url or just "the open file"]
3. Phase 1: Read design via MCP (screenshots + JSX + styles)
4. Phase 2: Plan sections, animations, responsive strategy
5. Phase 3: Generate Next.js + Tailwind + Framer Motion code
6. Phase 4: Polish, verify, ship