Is naming ‘blocks’ the hardest part of building a CMS?

If you’ve ever built a custom block system (whether with ACF, Gutenberg, Umbraco, or any other CMS) you’ve probably faced the weirdly difficult challenge of naming your blocks. It sounds simple, but the minute you go beyond “Hero”, “Related Content”, and “Image & Text,” things can get a bit tricky (and even those come with their own problems).

Just to clarify what I’m talking about when I say ‘Blocks’, I mean a re-usable / modular element that can be inserted into a template or page editor. You can then edit the content of that block, and move it up/down in the order of the page. Here’s an example of some blocks in WordPress’ Gutenberg editor:

And here is an example of some re-usable blocks in the format of ACF Flexible Content:

I’m calling them Blocks for the purpose of this article, but you may also see them referred to as:

• Modules
• Tiers
• Components
• Sections
• Elements
• Panels
• Widgets

As you can see, there’s multiple ways to describe these re-usable blocks and that’s before we’ve even gotten into the naming of them! That’s why I would say that this is probably one of the hardest things I encounter when building a content management system (CMS). Let’s delve deeper into why.

Why naming blocks is surprisingly tricky

Block names serve multiple audiences:

• You, the developer: you want consistency and sanity in your codebase.
• Content editors: they need to understand what the block does at a glance.
• Designers: they often name things based on visual layout or style, which may or may not align with function.
• Clients: they often interpret names differently to how designs and developers do, which can lead to confusion.

You’re balancing semantics, usability, and design. And the stakes are higher than you’d think – because naming impacts how intuitive (or not) the entire CMS becomes.

You’re balancing semantics, usability, and design.

Common challenges

• Too generic: “Content Block” tells you nothing.
• Too specific: “Feature Box With Left Image And Right Text” is a lot of text to ingest every time, and it also means if you want to expand on that block in the future you may have to rename it.
• Inconsistent naming conventions: is it “Call to Action” or “CTA”? Is that “Two Column” or “Split Content”?
• Overlap: How do you differentiate between two blocks that look similar but serve slightly different purposes?
• What happens when the design changes? Now your “Team Grid” block is being used for Testimonials and no one wants to rename it.
• Different industries or departments use different lingo: A graphic designer could use different terminology to a copywriter or a marketing exec, for example. A prime example of this is the many different terms people simply use for the first page on a website. I’ve heard it referred to as ‘Home’, ‘Web Page’, ‘Portal’, ‘Landing page’, ‘Dashboard’… and that’s just a few. Even across different web development agencies the language can vary.
  

My go-to tips

• Try to start with purpose, not layout – Where possible, name the block based on what it’s used for, not how it looks. “Image background & text and button on top” should be “Contact Call to Action”. Or “Quote & Image” should be “Client Testimonial”. This can help the editor use the blocks for purpose, rather than re-purposing them for something else. This comes with a caveat in that this doesn’t apply to everything, some blocks like ‘Image & Text’ are used for multiple purposes.
• Avoid developer lingo – Use plain English that makes sense to the person editing the site.
• Group similar blocks – Prefix related ones (e.g., “Content – Image Left”, “Content – Image Right”) so they’re easier to scan in the editor, or even better use one block “Image & Text Block” but give them options to flip the content so the image can be on the left or right. This keeps your CMS much cleaner in the backend.
• Document it – Include a cheatsheet in your CMS guide with screenshots and example uses. If using something like ACF Flexible Content, then bonus points if you include those preview images.

Can two/three blocks actually become one?

If I’m building another designer’s work, this is one of the reasons I like to have the full design before I start the build. It’s so I can assess the design and purpose of each block, and then map out whether multiple blocks are needed, or whether they can be combined into one.

Here’s an example of a Hero block that looks like 2 different blocks, but actually worked well as one. They serve the same purpose, but just have different layouts. By using conditional fields you can really help out your clients by presenting less blocks, but having more flexibility within the blocks you have built.

For this I just created a True/False ACF field that when checked, switches between Full Width image, and Half Width Image.

What’s the solution?

Honestly, it’s one of those problems that seems to be ongoing, you can’t predict how every person uses a site, and there’s no ‘standard’ that everyone across the world adheres to. Some of the terminology such as ‘Hero’ (often used to describe the first big area of content on a web page) is well known amongst agencies and web folk, but may still be a new reference for someone building their first website. 

The web often assumes a lot of its users, which is where accessibility can really fall down.

If a user gets frustrated with an experience, my stance is it’s never the user’s fault.

If a user gets frustrated with an experience, my stance is it’s never the user’s fault. People simply just use things in different ways. You can’t get frustrated with pedestrians walking on the grass to get to a destination instead of the path that was built for them, users will always try and take the easiest and quickest route to get to where they’re going.

It’s our job as UX designers and developers to anticipate their needs, and then continually test and adapt to make their experience on your site as pain free as possible.