Reusable content blocks need names users recognize
You built a nice modular content system. Users can assemble pages from pre-built blocks: hero sections, text columns, testimonial carousels, call-to-action panels. Then someone opens the CMS and sees a dropdown full of options like ContentModule_HeroVariantA or Block::Feature::TwoColumn. They guess wrong, preview the page, delete it, guess again.
The problem isn't the user. It's that you named your blocks for your codebase, not for the moment someone needs to choose one.
Name blocks for the choosing moment
Your block labels should answer the question "What will this look like on the page?" in under three seconds. A content editor assembling a landing page doesn't think in component taxonomy. They think in outcomes: "I need the thing with the big image and the headline" or "the part where we show three features side by side."
Bad: TextImageComboReverse_v2
Better: Text beside image (image on right)
Bad: CTAModulePrimary
Better: Call-to-action button with background color
Bad: FeatureHighlight_Trio
Better: Three features in a row
You can keep your technical component names in the code. But the label users see in the CMS should describe what the block does or looks like, using words they'd use when talking about the page.
Avoid jargon that only developers recognize
Terms like "hero," "card," or "accordion" might feel universal if you work in web design, but they're not as obvious as you think. Someone updating a product page may not know what a "card" means, and they definitely don't know the difference between CardStyleA and CardStyleB.
If your organization uses those terms consistently and everyone understands them, fine. But test it. Show three people the list of block names and ask them to describe what they think each one will produce. If they hesitate or guess wrong, rewrite the labels.
Descriptions help, but names come first
Some CMS tools let you add helper text under each block option. Use it—but don't rely on it to fix a bad name. People scan the list of names first. If the name is confusing, they won't read the description. They'll just pick something and hope.
Write the name so it works on its own. Use the description to add details: image ratio, character limits, whether it works well at the top of a page or only in the middle.
Group blocks if the list gets long
Once you have more than about eight blocks, a flat list gets hard to scan. Group them by purpose or page area:
- Page headers: blocks that go at the top
- Content sections: blocks for the main body
- Calls to action: blocks that prompt a user action
- Media: blocks focused on images or video
Within each group, keep names short and concrete. The group label already provides context, so you don't need to repeat it in every block name.
Decide on names before you build the blocks
This is a structure decision, not a late-stage polish task. If you name your blocks clearly from the start, you'll also catch duplicates and unnecessary variants early. Do you really need both "Text with image on left" and "Image beside text (left-aligned)"? Probably not.
Write the list of block names the same way you'd define your content types: before anyone starts building or writing. Show it to the people who'll actually use the CMS. Adjust based on what confuses them. Then build.
Your modular content system only works if people can confidently choose the right block without a guide, a preview, or a developer standing next to them. Name your blocks like you're writing instructions for someone who's never seen them before—because eventually, that's exactly who'll be using them.