wireframe-to-hifi

A Claude Code skill that converts Excalidraw wireframes into production-quality HiFi UI mockups using Pencil MCP.

What It Does

• Reads Excalidraw JSON wireframes and extracts layout structure, text, and annotations
• Plans a composition strategy (layout type, component selection, visual hierarchy, persona-aware density)
• Builds pixel-perfect HiFi designs in Pencil using batch_design operations with shadcn design system components

Key Features

• Step-file architecture (7 steps + 1 conditional) for disciplined, reproducible execution
• Auto-improving design playbook — lessons from each screen feed into the next
• Composition-first methodology — plan before design, validate after
• 6 proven layout templates (sidebar+content, modal, mobile, kanban, split-view, tabbed)
• Full Tailwind CSS to Pencil property mapping (286 lines of conversion tables)
• shadcn/ui component integration with proper Card/Form/Button/Overlay patterns
• Built-in validation loop with screenshot checking and property auditing
• Battle-tested on 94 screens across 17 batches

Prerequisites

• Claude Code CLI (or IDE extension)
• Pencil MCP server installed and configured
• Excalidraw wireframes (.excalidraw files)
• A shadcn-based design system (optional but recommended)

Quick Start

1. Copy the skill to your project:

   cp -r skill/ your-project/.claude/skills/wireframe-to-hifi/
   

2. Copy the starter config to your project root:

   cp examples/starter/config.yaml your-project/wireframe-to-hifi.config.yaml
   

3. Edit the config with your design system values (colors, fonts, paths):

   project_name: "My App"
   design_system:
     preset_code: "your-preset"
     primary_color_light: "#3b82f6"
     font_family: "Inter"
   paths:
     wireframes_dir: "{project-root}/wireframes"
     pen_file: "{project-root}/designs/app.pen"

4. Place your Excalidraw wireframes in the configured wireframes_dir

5. In Claude Code, say:

   convert wireframe SCR-001
   

   or

   wireframe to hifi SCR-001
   

How It Works

Init → [Setup*] → Analyze → [Build Components*] → Design → Validate → Export → Learn
                                                                                  ↓
                                                                            Playbook
                                                                                  ↓
                                                                          Next Screen →
                                                                              Init...

* = runs only when needed (first run / missing components)

Step	File	Purpose
1	step-01-init.md	Load config, playbook, resolve screen
2*	step-02-setup.md	First-run design system setup in Pencil
3	step-03-analyze.md	Wireframe analysis, composition plan, component check
3b*	step-03b-build-components.md	Build missing shadcn components in .pen
4	step-04-design.md	Execute batch_design operations
5	step-05-validate.md	Screenshot validation, polish loop
6	step-06-export.md	PNG export, screen log update
7	step-07-learn.md	Reflect and append to design playbook

Configuration

See docs/customization.md for the full configuration reference.

Architecture

See docs/architecture.md for the step-file architecture explanation, state flow diagram, and design decisions.

Pencil MCP Operations

See docs/pencil-mcp-cheatsheet.md for all Pencil MCP operations used in this skill with examples.

Examples

• examples/bridgesync/ — The original BridgeSync configuration that was used to convert 94 screens. Includes the real config, sample playbook entries, and the full shadcn rules digest with all anti-patterns.
• examples/starter/ — Minimal starter templates for new projects. Copy these as your starting point.

Battle-Tested Stats (from BridgeSync)

Metric	Value
Screens converted	94
Batches	17 (auth, dashboards, modals, settings, mobile PWA, admin, billing, graphs)
Average polish rounds	0-1 per screen
Design playbook	1,500+ lines of accumulated lessons
Layout templates proven	6 (sidebar+content, modal, mobile, kanban, split-view, tabbed)

Contributing

Contributions are welcome! Here's how to help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Areas for contribution

• Additional layout templates (e.g., wizard/stepper, timeline, gallery)
• Support for design systems beyond shadcn
• More Pencil MCP anti-patterns and proven patterns
• Translations of documentation
• Integration with additional wireframe tools (Figma, Balsamiq)

License

MIT -- Copyright (c) 2026 NDilanka

Credits

• Pencil MCP — The design tool that makes this possible
• shadcn/ui — The component system this skill is optimized for
• Excalidraw — The wireframing tool for input
• Claude Code — The AI coding assistant that executes this skill