A contract between content and themes: how my CMS keeps a theme switch from breaking pages

I'm building Umono, an open-source CMS (Go, SQLite, MIT). Before it, I spent nearly four years maintaining a large WordPress site with more than 60 plugins, where a theme or plugin update could break things in places nobody expected. Umono is my attempt at a CMS where content, themes and plugins have hard boundaries. Version 0.9 adds the theme half of that, and I'd like feedback from people who think about how CMSs are put together.

The contract

A contract describes a kind of site: its layouts (a blog has `post`, `post-list` and `page`), the parameters each layout takes, and the components they share. Contracts are published on umono.dev, are never edited or removed once published, and are licensed MIT-0 so anyone can write a theme for them.

• The site owner binds each page to a layout and fills its parameters: the title, the menu, the content.
• A theme picks one contract and is only CSS, fonts and images. No templates, no scripts. It can change how a page looks, never what it says or does.
• A contract writes no text of its own, so a theme works in every language.
• Switching themes changes the look of every page bound to that contract and none of their content.

Frozen HTML

The HTML that the content language produces is part of what a theme relies on, and it doesn't change during 0.x, even where it deviates from the spec. Fixes to it are collected and land once, in v1. A theme built today keeps getting the same markup after Umono updates. Umono also doesn't trust the version a theme declares: it detects the features the theme uses again on install and activation, and refuses a theme that declares less than it uses.

What isn't there yet

Plugins. The plan is the same idea for behavior: plugins implement published schemas, run as separate services, and get only the access the site owner grants. That is still in design, and I'd rather say so than sell it. Content is written in Compono, Markdown with components, which today suits technical users more than editors. Only the official contracts exist so far, with one official theme each: Octavo for simple sites and Folio for blogs.

How it's built

Umono is developed document-first. I write every decision and spec before any code, and that is where most of my time goes. The code is then written by AI agents (Claude Code and opencode), and I review each change against the spec. It isn't vibe coding: the design is mine, and the behavior is pinned by about 700 golden tests for the content language and around 600 Go tests.

Questions for you

• Is a contract between content and theme the right boundary, or too rigid for real sites?
• In the CMSs you've maintained, what broke first when a theme or plugin changed?
• What would make you try a CMS like this on a small project?

Site: https://umono.io · Docs: https://docs.umono.dev · Code: https://github.com/umono-cms/umono · Feedback: https://github.com/umono-cms/umono/discussions