Each page had its own layout logic, its own spacing decisions, its own way of handling full-bleed sections versus contained text. Some used inline styles. Some used one-off SCSS files. None of them agreed on what “default spacing” meant. Adding a new case study meant copying an old one, deleting most of it and hoping the parts you kept still worked together.
We needed a system where content authors write markdown and the layout stays consistent without anyone thinking about it.
The contract
The fix started with a single SCSS file: the contract. It defines every spacing and layout value the site is allowed to use, from page max-width and gutters to three tiers of vertical spacing and text measure widths. All fluid, all using CSS clamp() so they scale smoothly between mobile and desktop.
No component gets to invent its own spacing. Every module reads from these tokens. If a value isn’t in the contract, it doesn’t exist. One file changed, every page updates.
Inside the wrapper
We built 24 components (Hero, TextColumns, Cards, ImageText, Slider, ClientQuote and 18 others) that all sit inside a single wrapper. The wrapper accepts a small set of layout attributes, each with a few named values that control width, spacing and proportion. CSS custom properties handle the rest.
The content author never writes layout code. They write container directives in MDX:
:::text-columns{layout="double" spacing="compact"}
The case study template maps each directive name (hero, text-columns, image-text, client-quote) to the matching component. The author picks which modules they want and in what order. The system enforces how those modules look.
What modules don’t need to know
Twenty-two case studies and five landing pages now run through the same template. Before, each page was a standalone Astro file with its own layout logic.
The surprise was how little the modules need to know about each other. A Hero doesn’t care what follows it. A TextColumns block doesn’t know if it’s inside a case study or a landing page. The contract handles the shared rules, ModuleSection handles the shared structure and each module only worries about its own content.
What actually ships
A content author opens an .mdx file, writes directives, saves it and the page is done. No custom template, no per-page SCSS. A new case study that used to take a developer half a day now takes about twenty minutes. Client work gets published faster, and nobody has to ask a developer to adjust spacing.
