niklas-westman/penpair

Design together. Build together.
Penpair helps people and AI coding assistants work on the same Penpot design, then carry that design into frontend code. Your assistant can inspect a real file, build a page in reviewed steps and check the result. You stay in control of what changes and what gets approved.
Design in Penpot → build in your app → compare the result.
Install · First task · Companions · Contribute · Documentation
## What it does
Penpot holds the design. Penpair adds project configuration, reusable operations and skills: written instructions that teach your assistant how to work with that design.
| From an idea to a checked page | What Penpair helps with |
| Understand the design | Read pages, inspect components and tokens, audit spacing and export frames. |
| Work on it together | Pin the intended file, inspect before writing, take snapshots and independently read changes back. |
| Build the frontend | Hand design references and component mappings to the coding assistant. |
| Check the implementation | Add Reflection Check to compare approved references with real browser captures. |
Use your existing frontend stack. Library-specific knowledge lives in optional adapters; the core stays independent of any component library.
## Install
Choose how you want to get started. Both routes set up the same project and agent skills.
| Route | Best for | Start here |
| Set it up with your assistant — recommended | You want guidance, help with browser steps and checks along the way. | Guided installation |
| Install it yourself | You prefer to run each command and review the configuration yourself. | Manual installation |
For the recommended route, open your application's project in your coding assistant and paste:
text
Read https://raw.githubusercontent.com/niklas-westman/penpair/main/packages/core/skills/penpair-setup/SKILL.md
and follow its recommended assisted route to set up Penpair in this project.
Keep my MCP key out of chat and check with me before changing a design file.
You need Node.js 22 or newer, a project folder and a Penpot account. Your assistant helps check the prerequisites; you handle your personal key and browser. No clone of this repository is needed. Prefer a terminal wizard? The installation guide covers that too.
## Try your first task
Start with a read-only request to your assistant:
> Read the installed penpair-design skill. Inspect the pinned design file, summarize its pages and tokens, and suggest one small improvement. Do not change the file yet.
Then choose a scratch page and agree on a small design task. The workflow is: inspect, snapshot, write once, independently read back, export and look at the result. The design workflow explains the review points and recovery steps.
The installed skills cover setup → design → recipes → handoff → verification, with design-judgment for visual hierarchy. Ask the assistant to name the skill it uses. For frontend work, penpair-handoff carries design evidence into implementation; penpair-verify guides browser comparison, image review, fixes and recapture. Check skill discovery and behavior.
## Where the command and tools live
Install one command package in your application project. Both expose the same