name: pencil-dev-workflow description: Use when building websites with Pencil.dev and Claude Code, setting up design-to-code sync, automating file watching for .pen files, running parallel agents for multi-page design, or adding GSAP/Lenis animations

AI Design-to-Code Workflow — Pencil.dev + Claude Code

Overview

Build multi-page, WCAG-compliant, animated Next.js websites by connecting Pencil.dev to Claude Code with automated design-to-code sync, parallel agents, and programmatic UX audits.

Estimated Time: 4–8 hours for a full 5-page site

Prerequisites

• Pencil.dev desktop app installed (free at pencil.dev)
• Claude Code CLI authenticated
• Next.js project scaffolded and running
• PRD and UI Guide docs stored in project folder
• Design system defined: fonts, colors, component tokens

Phase 1: Tool Setup & Connection

Phase 2: Manual Sync Test

Key Discovery: Sync is not automatic. You must manually prompt every time — proceed to Phase 3 to automate.

Phase 3: Auto-Sync File Watcher

Test: Modify element in Pencil → Cmd+S → Claude should fire automatically.

⚠️ Security: Limit write permissions to project directory only — never grant global filesystem access.

Phase 4: Multi-Agent Parallel Pages

Phase 5: GSAP Scroll Animations

Use XML-structured prompts — Claude parses XML more reliably than prose.

<task>Add GSAP scroll animations</task>
<dependencies>gsap, @gsap/react</dependencies>
<elements>
  <section id="hero">fade-in on load</section>
  <section id="features">stagger children on scroll</section>
</elements>
<behavior>ScrollTrigger, start: "top 80%"</behavior>
<notes>Install GSAP if not present</notes>

Pass to Claude → GSAP installed, animations added across all pages.

Phase 6: Lenis Smooth Scrolling

<task>Add Lenis smooth scrolling</task>
<dependencies>lenis</dependencies>
<setup>Initialize in _app.tsx with requestAnimationFrame loop</setup>
<integration>Connect to GSAP ScrollTrigger via scrollerProxy</integration>
<behavior>smooth: 0.1, lerp: 0.1</behavior>

Note: GSAP controls what animates on scroll; Lenis controls how scroll feels. They're complementary.

Phase 7: UX Audit & WCAG Compliance

Exception Handling

Quality Checklist

• Pencil MCP tools visible in Claude Code
• npm run sync triggers on every .pen save
• No duplicate triggers (debounce working)
• All pages render without console errors
• Fonts/colors uniform across pages
• GSAP animations trigger at correct scroll positions
• Lenis scroll is smooth, no jitter
• UX Audit grade B or above
• npm run build passes

Open Questions

1. Bidirectionality: Does code → design sync exist, or only design → code?
2. UX Audit portability: Is the skill project-agnostic or needs per-project config?
3. Session limits: Has the debounce period been tuned to your Claude plan's token cap?