Design Files That Actually Live in Your Code Repo

For most of the past decade, "design" and "code" have lived in two separate systems that sync manually, if they sync at all. A designer ships a Figma file, an engineer eyeballs the spacing, and the two drift apart the moment either side changes something without telling the other.

Pencil, an AI-native vector design tool, closes that gap in a fairly literal way: its .pen files are plain JSON. Over MCP — the Model Context Protocol, a standard that lets an agent call a tool's functions directly instead of a human clicking through a UI — Claude Code can read and write them directly, no exporting, no manual measurement of colors and spacing. That's what its creator means by "a canvas that lives directly in your code repo and IDE": the design file becomes something that can be version-controlled, diffed, and edited by an agent, the same way source code is.

The core toolset

The MCP surface splits into three groups: reading state (get_editor_state, get_guidelines), batch editing (batch_design, capped at 25 operations per call), and verification (get_screenshot, snapshot_layout for catching overlaps and clipping, export_nodes for final output). A separate pair of tools, get_variables/set_variables, manages design tokens — colors, fonts, spacing.

One thing worth knowing up front: .pen files are encrypted, so they're only readable and writable through this MCP toolset — a plain file read or grep won't get you anywhere, unlike a normal Markdown or code file.

A five-stage system, borrowed from TobyScr's design-system skill

Idea discovery. Nail down the problem space, target users, and core flows through conversation, and land on a list of 5-7 key screens.
Style direction. Pull every available style tag with get_style_guide_tags(), pick 5-10, and feed them into get_style_guide() to generate a visual direction.
Brand direction boards. Build 2-3 candidate directions in Pencil — safe, bold, experimental — each with a palette, typography, and component samples. A human picks one.
Component library. Import tokens first, then build reusable components (Button, Input, Card, Nav) one at a time with batch_design(), checking each with get_screenshot() as you go.
Key screens. Assemble pages from the stage-4 components, run snapshot_layout(problemsOnly=true) to catch layout issues specifically, and export with export_nodes().

My Pencil workflow — five stages plus the feedback loop

What this sequence really does is make the old advice — "build the design system before you build pages" — concrete and enforceable through tooling. Lock in tokens and components first, and you avoid the alternative: adjusting spacing page by page and ending up with a UI that's internally inconsistent.

Extracting tokens from competitors

This part relies on Dembrandt, an open-source CLI that renders a real website through Playwright and extracts its design tokens in the W3C DTCG format — colors, type scale, spacing, shadows, corner radii, all of it. The full loop: extract a competitor's tokens, screenshot their key screens, have Claude Code compare palette, typography, and spacing against your own system, produce a diff report, and write the approved changes back into Pencil.

Closing the loop between design and code

This is the part of the workflow I think is worth paying the most attention to. The idea, shared by @tikeda on X, is to have Claude Code read a project's existing design-tokens.css/design-tokens.ts, rebuild the full token set and component library inside Pencil, generate UI from those components, and convert it back into code. Design and code stop being a one-way handoff — sketch first, hand to engineering — and become something that can sync in either direction.

For pixel-accurate implementation specifically, Saqoosha's approach (shared on Zenn) runs four parallel agents implementing the same screen, then compares the resulting screenshots with a PIL-generated heatmap — reporting a match rate above 94.8%. The number itself isn't the interesting part; the principle is: screenshot comparison is the final arbiter, not someone's subjective sense that it "looks about right." You measure the actual pixel difference instead of eyeballing it.

The responsive-design guidance in the source material is fairly plain: a 390px mobile frame (standard iPhone 14 width), a 1440px desktop frame, and a three-stage sequence — set up the canvas and tokens, generate components and pages, then adapt across both frames.

Where I land on this

The most valuable part of this workflow isn't "AI can generate a design" — plenty of tools already do that. What's actually worth paying attention to is .pen files landing inside the code repository: for the first time, a design file sits in the same version-control system as the code, diffable and directly editable by an agent, instead of a static asset parked in Figma's cloud, physically separate from the codebase it's meant to describe.

That also means "design to code" stops being a one-time handoff and becomes a loop you can iterate on — change a token in code and, in principle, it can sync back to the design file; change the design file and generate a fresh version of the component code. Whether that loop actually holds up smoothly on a real project is a separate question from how complete the tooling is. And however complete the toolchain gets, what ultimately decides the match rate is still the same rule: screenshot comparison, not subjective judgment.