# Paper To Code

> Convert Paper designs into production-ready websites with animations. Use when the user wants to build a website from a Paper design, convert Paper frames to code, implement a landing page from Paper, or says "build this from Paper", "convert my Paper design", "paper to code". Reads designs via Paper MCP, generates React + Tailwind + Framer Motion code with responsive breakpoints and polished scroll animations.

- Skill: `galangster/paper-to-code` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add galangster/paper-to-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/galangster/paper-to-code/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: galangster (https://skillmd.com/u/galangster)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/galangster/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):**
```typescript
// 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):**
```typescript
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:**
```typescript
// 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
```