Hello Digital Team,

I am sure everyone of us has faced this moment. You are building a CMS component library, you have a beautiful design file on one screen and the CMS admin on the other, and you are stuck on one small thing: what do we actually call this thing?

A week later the content author opens the CMS, scrolls a list of forty components, and cannot find the one they need. Small naming decisions become big authoring problems. A tiny card variation ends up as “Card Block” and “Card Block New”, and now nobody knows which to use. This is the practical playbook I have used on Optimizely, Sitecore, and headless builds over the last twelve years, written for the developers, designers, and PMs setting a library up or cleaning one up.

Why Naming Matters More Than People Think

A component name is read by three very different people, and it has to work for all three:

1. The content author who drags it onto a page and guesses what it does from the name alone.
2. The developer who finds it in the codebase, styles it, and maintains its variants for five years.
3. The designer who is adding a variation and needs to know if it already exists.

If the name only makes sense to one of them, the library drifts. Authors misuse components, developers create duplicates, and designers invent parallel versions in Figma that do not match the CMS.

💡 Golden Rule: Good naming is boring on purpose. It is clear, predictable, and hard to misinterpret. That is the whole job.

The Seven Golden Rules

1. Name by purpose, not appearance. “Blue Banner” is wrong the day the brand turns purple. “Promo Banner” survives the redesign.
2. Author-first language. The picker is used by marketers, not developers. “Two Column Text” beats “SplitContentBlockV2”. Keep the technical suffix (Block, Component) in the codebase, not the label.
3. Consistent suffix or none, but pick one. Do not mix “Hero Block”, “Testimonial Component”, and “FAQ Module”. I drop suffixes from author-facing names entirely.
4. Variants live inside the component. “Image Left” and “Image Right” are one component with a dropdown, not two. This rule alone halves a library.
5. Group logically. Use a category prefix only when the CMS has no folders or groups. If it has them, use them.
6. Test the name in the list, not on its own. A name is read in an alphabetical dropdown next to forty others. Write it into the full list and read it aloud before committing.
7. A name without a thumbnail is half a label. Authors scan the picker, they do not read it. More on that below.

Global Components: The Ones on Every Page

Keep the Top Navigation separate. It appears on every page by default, so it should never sit in the drag-and-drop component list. The same goes for the footer, cookie banner, and any announcement bar. These are site-wide fixtures, not authorable sections. Treat them as their own “Global” or “Site Settings” group, admin-only.

On the Optimizely build behind these screenshots, navigation and footer are edited inside a single Site Settings item, and the underlying data models are deliberately given no composition behaviour. That one setting keeps them out of the page picker, so an author can never drag a stray “menu item” onto a landing page.

Hero and Banner Components

Heroes are where naming goes wrong first, because they have the most variants. Do not build five heroes. Build one Hero with a Layout option (Image Left, Image Right, Full Width, Centered, Video Background), a Media Type option, and CTA options. If you genuinely need something different, for example a Campaign Hero with a countdown no other hero has, name it by purpose: Campaign Hero, not Hero 2.

Content Blocks: The Workhorses

These are the components authors use most, so the names matter most. This is the set I built on the Optimizely SaaS project behind this post, and the naming is deliberately flat and plain:

• Rich Text (single column of text, headings, links, lists)
• Two Column Text (two columns of rich text, no media)
• Text and Image (text and image, with a layout toggle for left or right)
• Text and Video (same, with video)
• Quote (large pull quote, optional attribution)
• Callout (short highlighted block, usually on a colored background)

Avoid “Content Block A” or “Layout Variant 3”: meaningless the moment you step away. Note that Text and Image and Text and Video are two components, because the field genuinely differs (an image versus a video), while left or right is a single dropdown inside each. That is the variant rule in practice.

Cards, Media, CTAs, and the Rest

Cards are the second place libraries explode. Resist a new card for every design. Build a Card Grid container (with Columns and Card Style dropdowns) holding a Card. Only name a card by its data source when it is genuinely tied to one: Product Card, Article Card, Event Card.

Keep the rest simple and predictable, and let options live inside each component rather than spawning siblings:

• Media: Image, Video, Image Gallery, Logo Strip. One Video with a size option, not “Hero Video” and “Content Video”.
• Call to action: CTA Banner, CTA Card. “CTA” is understood by every marketing team, so it is safe.
• Interactive: Accordion, Tabs, Timeline, Stats, Testimonial, Testimonial Carousel. The items inside (Accordion Item, Tab Item) are nested children, not standalone picker entries.
• Forms: Contact Form, Newsletter Signup, Event Registration Form, Gated Content Form. Name these by purpose even when the underlying form is the same.

Listing and Dynamic Components

These pull content from elsewhere in the CMS: Article Listing, Event Listing, Product Listing, Related Content. Put the filter and sort options inside the component. Do not create “Article Listing by Date” and “Article Listing by Category” as separate components.

Handling Variants Without Creating Chaos

Every project hits the “can we just add a small variation?” moment. My rule of thumb:

• Changes layout only (position, columns, alignment) is a variant. Add a dropdown.
• Changes content structure (new fields, new data source, new workflow) is probably a new component.
• Exists only for a temporary campaign? Build it behind a flag and remove it after. Do not leave campaign components lying around for years.

Here is that rule made concrete. Text and Image does not ship as “Text Image Left” and “Text Image Right”. It is one component with a single Layout dropdown, and Callout handles its colour the same way, through a Tone dropdown rather than four coloured copies. Two dropdowns standing in for six components.

Naming the New AI Components

This is the newest and messiest shelf in the library, so it is worth a rule before it fills up. Most “AI” features are one of two things, and teams mislabel both. The mode switch you now see next to All and Images, the toggle between a keyword list and a generated answer, is a variant: another tab in a row of tabs, sharing the structure of its neighbours, so it belongs as an option inside your existing search or filter component, not as a standalone “AI Mode Toggle”. The generated answer itself is a real new component, because it carries fields nothing else has: streamed body, citations, a source list, follow-up prompts, a disclosure line, and a generating state. Its parts are nested children, the way an Accordion Item lives inside an Accordion.

Name the component for what the reader receives, not the technology behind it. Keep the word “AI” only where the reader genuinely needs to know the text was machine-generated.

Component Thumbnails: The Part Everyone Skips

This is where naming stops being a wording exercise and becomes a usability one. Authors do not read the picker, they scan it, flicking down forty entries looking for a shape. A thumbnail skips the translate-word-back-into-shape step entirely. Every serious CMS supports one, and almost nobody fills it in, because it falls in the gap between design and development. So ask for it: make the thumbnail a named design deliverable.

Use a plain wireframe, not the polished design. It survives the rebrand and answers the author’s real question (“where does my stuff go”).

The mechanism differs on every platform, which is half the reason it gets dropped:

A note from a live Optimizely SaaS build. I tried to do exactly this on the SaaS product while writing the post, and it is worth reporting honestly. There is no built-in way to assign a preview image to a component today. I added a thumbnail field to a block in code and pushed it, and the Content Management API rejected it outright: the field does not exist on the content type. Optimizely confirmed the same, that custom component thumbnails would currently need a feature request or a custom solution, and the Add Section dialog shows a generic icon for every component in the meantime. This is exactly the kind of gap that tends to close quickly on an actively developed SaaS platform, so I hope and expect it will arrive before long. Until it does, on Optimizely SaaS your names are carrying the whole load, which is all the more reason to get them right.

The reason thumbnails get skipped is process, not effort. Make the component deliverable design + states + thumbnail (three files, not two), give the component register a thumbnail column, and include “renders correctly in the picker” in ticket acceptance. The CMS Component Index Drawing Set gives you 162 generic plates to start from.

A Worked Example: Two Real Components

Here are two components from a live build. Both keep their names, and the reasoning for keeping them is as useful as any rename.

“Curated Content” takes a content type and three fill modes (Latest, By tag, Hand-picked). It is a good, author-first name, with one honesty wrinkle: only one of its three modes is literally “curated”, so on a brand new build I might reach for Content Collection. But that is a day-one preference, not a reason to migrate a shipped component and re-point every reference for a marginal gain. The real win is the shape: one component with a content-type dropdown replaces the eight listing components many teams build.

“Highlight Card” is image, eyebrow, title, body, one CTA, as a wide feature panel. There is a general lesson attached: on a big library, watch the word Card, because Card usually already means the item inside a Card Grid, and AEM would call this a Teaser, Sitecore a Promo. On this build it does not collide (there is no Card or Card Grid beside it), it reads clearly for the daily authors, and it is shipped. So the guidance is layered: reach for Teaser or Promo Panel on a new build, and do not migrate a shipped name that is already clear.

Two things travel out of this. Get the shape right before you fuss over the word, and treat a naming rule as a design-time tool, not a license to churn shipped content. Before you commit a name, write it into the full alphabetical list and read it aloud. Collisions are invisible in a design file and obvious in a dropdown.

Who Owns Naming, and a Short Checklist

Both designer and developer, but not equally. The designer proposes the name and the thumbnail at design time, because they know the visual family it belongs to. The developer validates it against the codebase and the CMS, and wires the thumbnail in. The content lead has final sign-off, because they are the daily user. I run a fifteen-minute naming review at the end of each component sprint, and every name goes into a shared register (name, category, thumbnail, screenshot, one-line “when to use”). If it is not in the register, it does not exist yet.

Before you finalize any name, run the list:

1. Describes purpose, not appearance?
2. An author understands it without training?
3. Consistent with the pattern, and no collision when read in the alphabetical list?
4. Variants handled inside the component, not as separate entries?
5. Has a thumbnail, same ratio and style as the rest, rendering in the picker?
6. In the shared register with a screenshot and description?
7. Content lead signed off?

Yes to all seven, ship it.

Frequently Asked Questions

Should designers or developers name CMS components?

Both, with clear roles. The designer proposes the functional name based on intent, the developer validates it against codebase constraints, and the content lead gives final sign-off based on authoring usability.

What content blocks should a CMS component library include?

Start with a small, author-first set and grow only when a genuinely new structure appears. A reliable baseline is Rich Text, Two Column Text, Text and Image, Text and Video, Quote, and Callout. Keep left-or-right and colour choices as dropdowns inside those blocks rather than as separate components.

What is the difference between a CMS component and a variant?

A component defines the underlying content structure (e.g., Hero Banner). A variant alters layout or styling within that same structure (e.g., Image Left vs. Image Right), and should be a dropdown rather than a duplicate component.

Should you rename a CMS component that is already live?

Usually not. Renaming a shipped component means re-pointing every instance and reference in the CMS, a breaking change for a marginal wording gain. Get the name right on day one and keep it unless it is actively causing authoring errors.

Final Thoughts

Naming feels trivial until it costs you a week of rework. A tidy, author-first library makes content teams faster and developers happier. If you are starting a build, open the naming register on day one. If you are inheriting a messy one, do a two-hour naming audit with the whole team. Unglamorous work, real payoff.

If you have your own naming rules that have saved you from chaos, I would love to hear them, leave a comment below.