Imagine your .pen design files whispering their structural secrets directly into your AI coding assistant's ear. That is precisely what the Pencil Design Intelligence Hub accomplishes. This isn't merely a plugin; it is a synaptic translator that converts visual design intent into machine-readable context for AI code generators.
In the ecosystem of design-driven development, most tools treat design files as static images. This project inverts that paradigm. By leveraging the Pencil MCP (Model Context Protocol) server, we establish a real-time neural pathway between your design canvas and AI agents like Claude Code, Cursor, Codex, and Gemini CLI. The result? Code that breathes the same aesthetic soul as your original design, without the manual transcription overhead.
Designers and developers often inhabit parallel universes. The designer sees pixel-perfect spacing, subtle gradients, and harmonious typography. The developer sees divs, CSS flexbox, and React props. This gap creates what we call the Design Fidelity Paradox: the closer a developer tries to match the design, the more time they spend on non-functional aesthetics.
This repository solves that by embedding design intelligence directly into the coding loop. Think of it as a bilingual interpreter for your UI components. Your .pen file doesn't just get exported as an image; it gets distilled into structured, AI-actionable metadata that your coding agents can consume enthusiastically.
graph TD
A[Pencil .pen Design File] --> B[Pencil MCP Server]
B --> C{Design Intelligence Engine}
C --> D[Component Hierarchy Parser]
C --> E[Style Token Extractor]
C --> F[Layout Grid Analyzer]
D --> G[AI Context Builder]
E --> G
F --> G
G --> H[Claude Code]
G --> I[Cursor IDE]
G --> J[Codex API]
G --> K[Gemini CLI]
H --> L[Generated UI Codebase]
I --> L
J --> L
K --> L
L --> M[React/Vue/Svelte Components]
L --> N[CSS/SCSS/Tailwind Styles]
L --> O[Responsive Breakpoint Rules]
The system doesn't just see rectangles; it recognizes UI patterns. A bordered box with a heading and button becomes a Card component. A list of items with icons becomes a Navigation Menu. This is pattern recognition elevated to architectural understanding.
Unlike single-vendor solutions, this plugin speaks the language of multiple AI coding companions. Whether you prefer:
- Claude Code for nuanced architectural decisions
- Cursor for real-time inline suggestions
- Codex for rapid prototyping
- Gemini CLI for terminal-centric workflows
Each receives optimized context from the same .pen source, ensuring design consistency across all outputs.
Modern applications live on screens of every dimension. The design intelligence automatically extracts responsive breakpoints from your Pencil layouts and injects them as media query recommendations. Your AI generates mobile-first code by default, based on how you arranged elements at different viewport sizes.
Design tokens are language-agnostic. The plugin attaches I18n metadata derived from your design labels and text elements. The generated code includes placeholder structures for translations, ready for integration with localization frameworks like react-i18next or vue-i18n.
The MCP server acts as a persistent design oracle. Even when you are sleeping, your CI/CD pipeline can query the server for the latest design specs. This enables continuous deployment scenarios where design changes automatically trigger code regeneration overnight.
Under the hood, the design intelligence engine offers a plugin interface for:
- OpenAI API: For broad pattern recognition and natural language design descriptions
- Claude API: For nuanced component reasoning and complex layout logic
You can configure which API handles specific tasks, or let the system auto-select based on the complexity of each design element.
Configure your design-agent.json to personalize how the AI interprets your design files:
{
"project": {
"name": "saas-dashboard-v3",
"framework": "react",
"styling": "tailwind",
"i18n": true
},
"aiAgents": {
"claudeCode": {
"enabled": true,
"preference": "architectural",
"tokenLimit": 4096
},
"openai": {
"model": "gpt-4-turbo",
"endpoint": "https://api.openai.com/v1",
"fallback": true
},
"gemini": {
"enabled": false,
"task": "responsive-breakpoints"
}
},
"design": {
"sourceDir": "./designs",
"autoWatch": true,
"outputDir": "./generated",
"componentStyle": "functional-components",
"typescript": true,
"responsiveBreakpoints": {
"mobile": 375,
"tablet": 768,
"desktop": 1280
}
},
"extraction": {
"colors": "generate-design-tokens",
"typography": "clamp-values",
"spacing": "tailwind-scale"
}
}Run the design-to-code pipeline directly from your terminal. No GUI. No friction. Just pure productivity:
# Parse a .pen design file and generate React components with Tailwind
pencil-skill parse ./designs/login-screen.pen --framework=react --styling=tailwind --output=./src/components
# Watch a directory for changes and auto-generate on save
pencil-skill watch ./designs --client=claude-code --ts
# Preview all design tokens extracted from a complex layout
pencil-skill analyze ./designs/dashboard.pen --extract-tokens --format=json
# Generate with specific AI client preference
pencil-skill generate --source=./designs/onboarding.pen --client=gemini --framework=vueThe console interface treats every .pen file as a design blueprint that your chosen AI agent can read, understand, and transmute into production-ready code.
| OS | Version Support | Compatibility Status | Notes |
|---|---|---|---|
| 🪟 Windows | 10, 11, Server 2022 | ✅ Native | Full MCP server support via WSL2 |
| 🍏 macOS | Ventura, Sonoma, Sequoia | ✅ Native | M-series optimized binary |
| 🐧 Linux | Ubuntu 22.04+, Fedora 38+, Debian 12+ | ✅ Full | Requires Node.js 18+ |
| 💻 ChromeOS | 2024+ (Linux container) | No hardware GPU acceleration | |
| 🔷 FreeBSD | 13.2+ | 🧪 Experimental | Community-maintained port |
This repository naturally incorporates high-value search terms for design-to-code automation:
- AI design-to-code conversion - Transform visual interfaces into working code
- Pencil MCP server plugin - Extend design tool connectivity with MCP protocol
- Automatic UI code generation - Reduce manual coding through AI-powered parsing
- Claude Code design integration - Connect Anthropic's AI to your design workflows
- React component generator - Produce component trees from design hierarchies
- Responsive layout extraction - Automatically determine breakpoints from design files
- Design token pipeline - Extract colors, typography, and spacing as structured data
- Multi-AI development workflow - Switch between AI agents without changing design source
- Headless design-to-code - Run conversion entirely via CLI with no interface overhead
- ✅ Parse
.penfiles with full hierarchy preservation - ✅ Extract component nesting, z-index layers, and visibility states
- ✅ Identify reusable design patterns and suggest component abstraction
- ✅ Detect animation timelines and easing curves for micro-interactions
- ✅ Export to intermediate representation (JSON/YAML) for custom pipelines
- ✅ Build structured prompts optimized for Claude Code's extended context window
- ✅ Generate role-specific instructions (frontend, backend, fullstack)
- ✅ Include design rationale and user intent behind layout decisions
- ✅ Add accessibility hints (contrast ratios, focus order, ARIA roles)
- ✅ Annotate complex interactions (drag-and-drop, multi-step forms, modals)
- ✅ Output frameworks: React, Vue 3, Svelte, Angular, Astro
- ✅ Styling systems: Tailwind CSS, Styled Components, CSS Modules, Vanilla CSS
- ✅ TypeScript-first with strict type generation
- ✅ Storybook stories auto-created for each component
- ✅ Test templates (Jest, Vitest) based on component interaction areas
- ✅ CI/CD integration via GitHub Actions, GitLab CI, Jenkins
- ✅ Webhook triggers when
.penfiles change in connected repositories - ✅ Slack/Teams notifications when design drift is detected
- ✅ Version tracking between design iterations and generated code
- ✅ Diff reporting showing what changed between design versions
Important Legal and Operational Notice
The Pencil Design Intelligence Hub is provided as an open-source tool under the MIT License. While it aims to significantly reduce manual coding effort, it does not guarantee production-ready code without human review. Generated code should always be audited for:
- Security vulnerabilities - AI-generated code may contain overlooked injection points or misconfigured authentication flows
- Performance bottlenecks - Component structures optimized for design fidelity may not be optimal for runtime performance
- Accessibility compliance - While we annotate for accessibility, final WCAG compliance requires manual verification
- Legal ownership - The designs you parse remain your intellectual property; however, generated code patterns may resemble existing open-source components
The developers assume no liability for production incidents arising from unmodified AI-generated code. Use this tool as a productivity accelerator, not as a replacement for professional software engineering judgment.
This project is licensed under the MIT License - a permissive open-source license that allows for commercial use, modification, distribution, and private use. You are free to incorporate this plugin into your design-to-code pipelines, whether for personal projects, enterprise systems, or commercial products.
The full text of the license is available in the LICENSE file. In summary: you can do whatever you want with this code, but we provide no warranty and accept no liability. Build something remarkable.
Version 2.0.0 | Released 2026 | Maintained by the community
Turn every design file into a conversation with your AI. The future of design-to-development is not about exporting images—it is about exporting understanding.