What is Romanesco?

Romanesco is a collection of tools for prototyping and building websites. It integrates a front-end pattern library directly into a CMS (MODX Revolution). It aims to combine various best practices like code reusability, iterative development, a content-first approach and responsive content editing into one coherent ecosystem.

To explore what that means, let's slice a Romanesco into two halves. The first half consists of a preconfigured MODX installation, a list of preinstalled extras, and styling assets for displaying the website in your browser. This half serves as the starting point of the website. It is a one-time setup, which can be modified after installation (sometimes called a boilerplate). For Romanesco, this repository is called Romanesco Soil. As in: the foundation from which the project can grow.

The second half includes a pattern library with a set of templates, layouts and common website elements, which can be forged together into content with a drag&drop block editor (ContentBlocks). There's also a central styling theme, a Backyard area with examples, and some tools working in the background to improve performance. What all these areas have in common, is that they can be updated inside each project.

This means that bug fixes, improvements and new features are portable between Romanesco projects.

The underlying philosophy here is to provide a set of essentials that is centrally maintained, while still being flexible enough to adapt to your specific needs. Many websites are remarkably similar nowadays from a technical perspective, but in the end each project is still unique. With Romanesco, I tried to find a balance between not reinventing the wheel all the time and creating exactly what is needed.

This would not have been possible without the CMS that lies at the heart of Romanesco: MODX.

Time to look inside a Romanesco


If you have experience with other CMSes, then you might be familiar with the struggle of rendering your content exactly how you want it to appear.

Things you've seen working elsewhere, or have even designed and marked up already in HTML/CSS, turn out to be nearly impossible to integrate in the CMS. You either need to obey their rigid templating rules, or hack your way through tons of theming and framework layers. The process is ridden with frustration and the result is often not what you had in mind.

In other words: you should be telling the CMS what to do, not the other way around. This has always been the prime directive of MODX. Designers and developers should never be forced to follow any framework dogmas. You should be able to use any tool, technique or library you want.

MODX calls this Creative Freedom. It is characterized by:

  • A blank template to start from (you build your own theme)
  • No mandatory file structure (you can place your assets anywhere)
  • A clear separation of frontend and backend code
  • A fully customizable content manager (bring your own RTE)
  • X stands for: extend with anything you want

Romanesco builds upon these liberties (in fact, it couldn't exist without them) and respects them by keeping the door open for MODifications and eXtensions as much as possible. So for insiders: this is still the MODX you know and love!

Discover MODX

Start with content

Content is arguably the most important part of your website. Yet, many web projects only deal with it at the very end. Not Romanesco!

Romanesco originally started as a prototyping tool. We were trying to flip the development stage on its head by moving the design phase to the end, and starting with content. We'd have a kickoff meeting with our client where we would gather as much info and data as we could (I still highly recommend doing that).

We then had to structure and visualize that content somehow, so we needed a place where we could quickly dump these assets and play around with them. Heavily inspired by the PatternLab project, a base installation was born (still using Bootstrap at the time).

We quickly realized that putting it directly in our CMS of choice (MODX) had a lot of benefits (compared to the wireframing tools we used before). It didn't take long before the first client said: "wow, that looks great!". After which we replied: "ehmm well, this is just the prototype (in default Bootstrap styling). We still have to start with the design." See! It's all about the content.

Fast forward to today: we have a CMS, a brilliant block editor, a more flexible UI system and a growing set of common website elements at our disposal, so we can start adding content right away.

Structure Prototype Design Publish Content A Romanesco site
Create and edit pages
Set up a navigation structure
Add text, images and other media
Publish content when ready

Status Grid

Status ID Page Improvements Issues Owner Due date


An Overview in Romanesco is a collection of related pieces of information, displayed in a list or grid (or slider, or selector...). It is an introduction to content that is located elsewhere on the site.

A good example of an Overview is a list of blog articles. You can display the latest articles on your homepage, which link to the Detail page in your blog.

What can you do with an Overview?

  • Use templates to display different variations (i.e. with images)
  • Set the amount of columns (with additional responsive controls)
  • Control heading level for SEO
  • Sort options and limit number of items
  • Show pagination after X number of items

And many other things. Overviews are the information desks inside your website. Where the main navigation is meant to quickly get you to a specific location, Overviews provide a little more insight into what your website is about while you are browsing.

Responsive design

It's probably impossible to create anything on the web nowadays without considering responsive design. As web builders, we are responsible to make the site work across a range of devices.

Romanesco helps you to choreograph your content a little, so it comes out nicely on any screen size. It also takes care of a few things automatically, following responsive design best practices.

  • Compact / touch friendly navigation on mobile
  • Start stacking content as the screen gets smaller
  • Simplify layout elements on mobile (like turning tabbed content into accordions)
  • Keep font sizes and white space balanced across breakpoints
  • Load smaller images when screen is smaller or has lower pixel density

Benefits of using a central library

Anyway, you know this stuff already. The thing with responsive design is: it can take a long time to get it right. Endless fiddling with CSS, build tools, testing in different browsers / devices, etc. etc. And when you discover a bug in your approach, you sometimes find yourself fixing it over and over again in various places.

Maintaining a central repository with responsive design elements still requires a lot of work. But ultimately, the benefits are well worth the effort (if you ask me). Just think of all the work (and frustration) you save when everyone is using components that have been tweaked and tested over an extended period of time. Because bugfixes and improvements can be applied to all your projects, the quality and usefulness of your responsive design elements will continuously increase.

Example of a responsive image gallery. Change the width of your browser window (or visit this page on another device) to see how this component adjusts.

Follow Romanesco

Receive information about the project in your mailbox.

The mailing list is called Fractal Forest and sent by Fractal Farming.


Romanesco doesn't offer a ton of different themes. Instead, you get 1 theme with a ton of customization options.

You can control some of these options yourself (from inside MODX), like color scheme, fonts and logo. And you can ask any webdesigner to help you with tweaking the theme to further fit your identity, or dive into the mechanics yourself if you feel adventurous.

The theming framework relies on FomanticUI and allows you to apply customizations per component, and on different levels in your design. That sounds a bit fuzzy and in fact: it probably is a bit intimidating at first. But essentially, what you end up with is a fully customizable design system.

Theming structure Fomantic UI

Primary color (Dark)

Secondary color (Dark)

Primary color (Light)

Secondary color (Light)






Together with bandwith and possibilities, the complexity of the internet has grown immensely over the past 20 years. The same cannot be said for the average human attention span.

Fast loading times and snappy interactions are therefore crucially important for online survival. Romanesco has a few (optional) mechanisms built in for improving site performance. Some of these measures (like critical CSS) are only intended for medium to large web projects, where competition is fierce and every milisecond counts.

I admit, mobile pagespeed was much lower ;)

Custom caching

By default, MODX clears the site cache every time you save a page (even something small like a fixed typo). After that, a lot of content needs to be regenerated from the database, resulting in slower page loads. Thats why some parts of the cache have been moved to their own partition, so they won't be cleared on every save action.

Cache busting

When you intentionally cache static assets in the visitors' browser, changes to these files won't be visible on return visits, unless the filename is different. The cache buster takes care of this. When static assets like CSS or Javascript are updated, they receive a new suffix so the client browser will treat it as a new file and download it again.

Critical CSS

When enabled, a CSS file will be generated for each resource, containing only the styles needed to display content above the fold. This file is usually much smaller than the main stylesheet and loaded as early as possible. The main CSS file can then be loaded asynchronously, resulting in a substantial performance gain.

That wasn't exactly quick, was it?

By now I hope you have a general idea of what Romanesco is. Romanseco is a system, and a system is more than just the sum of its parts. It's a way of doing things. A series of rules and guidelines, from which certain properties can emerge.