This all started with a small problem and a timely conversation in the Grav CMS Discord.

I needed to change "Version" to "Course" in the navigation switcher for the brand new Grav premium Helios theme, as I saw its potential as a successor to my original Open Course Hub. Andy Miller, the creator of Grav CMS, kindly pointed me in a direction I hadn't considered: handle everything in a dedicated plugin and leave the theme files completely untouched. "That one plugin is their entire customization. Keeps everything else stock." He also suggested Claude Code as a way to extend my existing basic Grav development capabilities. That combo – the right architecture and the right tool to help get that job done – reframed the entire project for me.

The Grav Helios Course Hub is my third generation open course companion. The previous version eventually split into two separate projects, single-course and multi-course, and naturally maintaining both resulted in more effort. That friction turned out to be a signal: multi-course wasn't a variant of the design, it was the default use case that could handle both. This approach resolves that with one installation, one plugin, and one licensed Grav Premium theme doing the heavy lifting. And using a premium theme made sense on multiple levels – revenue from Helios licenses directly funds continued development of the open-source Grav CMS itself.

What follows are nine design principles that emerged from this experience, each circling back to the same question: where does this complexity actually belong?

Each principle is explored from two angles, a developer perspective and a UX design perspective, because the same insight often looks different depending on where you're standing.

Here are the nine principles, followed by a detailed look at each:

The Nine Principles at a Glance

1. In open source, the people who are most familiar with the platform's seams are often just a conversation away.
2. The question is never just "can I build this?" – it's "what does it cost to own this instead of the platform?"
3. A feature designed for one domain can map directly onto another – if you're looking at structure rather than labels.
4. A boundary you cannot cross reveals the right seam rather than the convenient one.
5. When a concept is central from the start, everything else gravitates to it. When it's added later, it orients around everything else.
6. Every configuration option is a decision the system has transferred to the user.
7. What the system offers should depend on where the user is, not just what they ask for.
8. Persistent maintenance friction is diagnostic – it points at a structural problem, not just an implementation one.
9. Content and the tools that hold it have fundamentally different lifespans – treating them the same is a mistake that compounds over time.

The Design Principles

1. In open source, the people who are most familiar with the platform's seams are often just a conversation away.