Why your CMS should not know what a hero section is
Page-shaped content models feel productive for about six weeks. Here is what to model instead, and how to tell when a field is describing meaning rather than layout.
Most content models start honestly and drift. The first few types describe things the business actually has — a product, an author, a case study. Then a designer needs a two-column band with a tinted background, and a field called backgroundVariant appears. Six months later the model is a catalogue of visual arrangements, and nobody can answer the question the CMS exists to answer: what do we publish?
Model meaning, not arrangement
The test is portability. If you had to publish the same content to a newsletter, an app, and a voice assistant, which fields would survive? Title, excerpt, author, body and category survive. A field named paddingTop does not. That is not a rule about tidiness — it is the difference between content you can reuse and content that only renders once.
This does not mean layout has no home. It means layout belongs in a layout object, quarantined from the fields that carry meaning, so a redesign touches one part of the document and leaves the rest untouched.
References beat duplication
An author typed as a plain string is the single most common modelling shortcut, and the most expensive one to undo. The moment you want a bio, a photo, a role, or structured data authorship, that string has to become a document — and every post referencing it by name has to be migrated. Reach for a reference the first time you notice the same value being typed twice.
The cost of a reference is one extra click for an editor. The cost of not having one is a migration, and migrations against live content are never as clean as they look in a planning document.
Let the query do the derivation
Reading time is a good example. It can live as an editable number, be computed in the template, or be projected by the query. Only the last option guarantees that a card in a listing and the post page itself agree, because there is exactly one implementation and the listing does not have to fetch the entire body to use it.
Every value you derive in a component is a value some other component will derive slightly differently. Push derivation toward the data and the inconsistency has nowhere to live.
Written by
Avery Lin
Content Architect
Avery designs content models for teams moving off page-builder CMSes, and writes about keeping structured content structured.
