| 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
Phase 1: Tool Setup & Connection
| Step | Action | Output |
|---|
| 1.1 | Download Pencil.dev desktop app | App installed |
| 1.2 | On launch, select Claude Code from AI platform options | Connection initiated |
| 1.3 | Verify MCP auto-configures — Pencil tools should appear in Claude Code | MCP tools visible |
| 1.4 | Select Opus 4.6 model in Claude Code | Model set |
| 1.5 | Confirm .pen file is in project root (JSON-based, Git-trackable) | File location verified |
Phase 2: Manual Sync Test
| Step | Action |
|---|
| 2.1 | Design a test element in Pencil.dev |
| 2.2 | Prompt Claude: "Sync the latest Pencil design to the Next.js project" |
| 2.3 | Verify rendered output matches Pencil canvas |
Key Discovery: Sync is not automatic. You must manually prompt every time — proceed to Phase 3 to automate.
Phase 3: Auto-Sync File Watcher
| Step | Action | Details |
|---|
| 3.1 | Pre-configure permissions | Edit ~/.claude/settings.json — add read, write, MCP tool permissions. Without this, Claude blocks indefinitely. |
| 3.2 | Create watch-pencil.js | Use chokidar to watch .pen file |
| 3.3 | Add Claude CLI trigger | On change, spawn child process: claude "Sync the updated Pencil design to Next.js" |
| 3.4 | Add debounce (1500-2000ms) | Prevent duplicate triggers on rapid saves |
| 3.5 | Add to package.json | "sync": "node watch-pencil.js" |
| 3.6 | Run npm run sync | Keep running in dedicated terminal tab |
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
| Step | Action |
|---|
| 4.1 | Ensure PRD + UI Guide are in project folder |
| 4.2 | List all pages: Home, About, Services, Portfolio, Contact |
| 4.3 | Prompt Claude: "Use multi-agent system. Assign one agent per page. Each agent designs its page in Pencil.dev using the UI Guide design system." |
| 4.4 | Let agents complete (5 agents work in parallel) |
| 4.5 | Save to trigger auto-sync → all pages implemented |
| 4.6 | Verify cross-page consistency in browser |
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
| Step | Action |
|---|
| 7.1 | Build UX Audit skill with: Context Gathering, 9-Point Checklist, Scoring |
| 7.2 | Run audit against site → get grade + issues list |
| 7.3 | Fix critical issues first (color contrast, etc.) |
| 7.4 | Prompt Claude: "Implement all fixes from this audit report" |
| 7.5 | Re-run audit → target grade B or above |
Exception Handling
| Problem | Solution |
|---|
| Claude blocks on permission prompt | Verify settings.json has read/write/MCP permissions |
| Auto-sync fires repeatedly | Increase debounce to 2000ms |
| Inconsistent fonts across pages | Run: "Audit all pages against UI Guide, standardize design tokens" |
| GSAP + Lenis jitter | Ensure Lenis uses ScrollTrigger.scrollerProxy() |
.pen file not detected | Check absolute path in watch script |
Quality Checklist
Open Questions
- Bidirectionality: Does code → design sync exist, or only design → code?
- UX Audit portability: Is the skill project-agnostic or needs per-project config?
- Session limits: Has the debounce period been tuned to your Claude plan's token cap?
