If Photos was about finding a contribution that matched something I already loved, this week was about finding one that actually challenged me. I picked up the Playground Blueprints contribution properly, and I can say without exaggeration: this was the toughest thing I’ve done in the course so far.
What I did this week
I followed the official guide, Build a WordPress Playground Blueprint, step by step. First, I browsed the existing Blueprint Gallery to see how other contributors structured their projects, then worked through the “Build your first blueprint” tutorial to understand how a blueprint.json actually works — which steps it runs, how it installs themes and plugins, and how it can inject custom content automatically.
Once I understood the mechanics, I had to decide what to actually build. I settled on a Design System / UI Kit environment: a blueprint called canvas-ui-lab. It installs and activates Twenty Twenty-Four as a clean, neutral canvas, then loads a custom mu-plugin (design-lab.php) that removes the default Sample Page, injects custom styling — Plus Jakarta Sans typography, a dark-mode color palette, and smooth animations — and generates an interactive homepage: a Component Gallery built from clickable cards. I also loaded six optimized WebP images into the media library, each representing a pillar of UI development: Design Tokens, Micro-Interactions, Responsive Layout, Component Motion, Accessibility Patterns, and Theme Architecture. Each card links out to real documentation — MDN, W3C WCAG, WordPress Developer Resources — so the demo doubles as a small resource hub for frontend developers, not just a visual showcase.
I chose this direction for a few reasons: it shows WordPress as a serious tool for prototyping design systems, not just blogs or stores; it stays fast and clean by avoiding heavy builders or placeholder filler text, so it loads instantly in Playground; and it’s genuinely useful — every element points somewhere real.
What was hard — and how it went
I went in a little overconfident, honestly. My first year in DAM gave me a solid base in JSON, so I assumed the technical part would be straightforward. It wasn’t — not because JSON itself was hard, but because a Blueprint isn’t just data; it’s a sequence of steps with its own API, its own conventions, and real constraints on what runs where. Just deciding what to build took longer than I expected; I went through the Blueprint Gallery source files several times before landing on something that felt both original and genuinely useful rather than a copy of an existing idea.
Getting the mu-plugin logic right inside the Blueprint’s structure was the second wall I hit — making sure the PHP executed correctly as a Must-Use Plugin, that the CSS injection didn’t conflict with the theme, and that everything still loaded cleanly and quickly in the browser-based Playground environment. Testing constantly in the Playground Builder became essential; small mistakes that looked fine in the JSON file would break silently once actually run.
Preparing the submission was its own separate challenge. The CONTRIBUTING.md guidelines are specific about folder structure, required metadata (title and author), and how referenced files need to be organized alongside blueprint.json. I had to research proper pull request conventions for the WordPress/blueprints repository — how to name my branch, how to structure the folder under blueprints/canvas-ui-lab/, and what a clean, reviewable PR actually looks like in an open-source project. None of this was covered by “knowing JSON.”
Challenges & what I learned
This week taught me that technical familiarity and contribution-readiness are two different things. I knew JSON, but I didn’t know Blueprints — and the gap between those two was most of the difficulty. I also learned that open-source contribution has its own etiquette around pull requests that’s just as important as the code itself: clear structure, following the contributing guide to the letter, and writing a PR description that makes review easy rather than assuming the reviewer will figure it out.
Leave a Reply