Design as Code

With Pencil, your designs are no longer opaque binary blobs locked inside a proprietary cloud. Every .pen file is a plain-text, JSON-based artifact that sits right next to your source code — meaning you can commit it, diff it, branch it, and merge it exactly the way you already work with code.

Commit .pen Files Like Code

Because .pen files are plain JSON, Git treats them as first-class text files. Stage and commit them exactly the way you would any other source file:

# Stage a design file
git add src/designs/sidebar-nav.pen

# Commit with a descriptive message
git commit -m "feat(design): add sidebar navigation layout"

View Diffs in Git

Every property change, layer reorder, or style tweak shows up as a readable diff. No more guessing what changed between two versions of a design:

git diff src/designs/sidebar-nav.pen

Because the JSON is structured and deterministic, diffs are clean and easy to review in pull requests, making design changes as transparent as code changes.

Branch & Merge Designs

Work on a design experiment without affecting the main branch. When you are happy with the result, merge it back — just like code:

# Create a feature branch
git checkout -b design/new-header

# ... make design changes in Pencil ...

# Merge back into main
git checkout main
git merge design/new-header

Collaboration with Version Control

When every team member commits their design work to the same repository, collaboration happens naturally. Designers and developers share a single source of truth: the Git history. Pull requests become the review surface for both visual and functional changes, and merge conflicts — when they arise — are resolved with the same familiar tooling you already use for code.

# Pull the latest designs from your team
git pull origin main

# Push your design changes for review
git push origin design/new-header

Best Practices

  • Commit frequently — small, incremental commits make it easy to pinpoint when a specific change was introduced and to roll back if needed.
  • Write descriptive commit messages — a message like feat(design): widen sidebar to 280px tells the whole story at a glance.
  • Review design diffs in pull requests — encourage your team to inspect .pen diffs alongside code diffs for a complete picture of every change.
  • Use feature branches for experiments — keep the main branch stable by developing new design ideas on dedicated branches.

Last updated: February 22, 2026