CSS Tip #2: Structural Naming Convention in CSS

Structural naming convention – in essence – just means that you name (by assigning a class and/or id attribute to them) elements by describing what they are, and not where they are or how the look.  Its counterpart is called presentational naming which describes the location and/or appearance of web page elements.

Leading image

This CSS tip discusses the concept of structural naming conventions, the benefits of using this convention, and shares some guidelines on practical applications of structural naming conventions.

Let’s start with a presentational naming example

To illustrate by way of example, take a look at Example 1 which uses a presentational naming convention.

Example 1: A presentational layout.

Example 1 - screen shot.

What’s wrong about the layout?

There are two major fundamental flaws in using a naming convention such as shown in Example 1.

First, it makes it hard to move things around without affecting the accuracy of your markup.

Although the #top-div and #bottom-div will most likely stay in place, a design decision to put the secondary content (#right-col) to the right of the main content area (#left-col) completely invalidates the document’s model.

Secondly, the names don’t help describe what the elements are – what they’re for and what they do as part of the overall document.

For example, the link with the class .red-link in Example 1 describes the color of the link, but not what it’s for.

A realistic example

Let’s pretend I hired a new developer in my team – let’s call him Dave Newbie. I’ve given Dave the task of updating a website that uses a presentational naming convention instead of a structural naming convention.

The site’s CSS is much like Example 1, but instead of only 13 lines of declarations, it’s 500 lines (single-spaced, single-lined, shorthand notation).

I didn’t give Dave any other instructions besides updating the pages and assigning elements the appropriate class or id (I didn’t comment my code, because remember – I like to do things the hard way).

In a web page Dave was tasked to update, he encounters a special class of links with the name .red-link (as shown in Example 1).

.red-link example

Now he’s scratching his head wondering why these guys have a class of .red-link

What if instead of .red-link, I named it .external-link?

Dave would know instantly (and if he doesn’t – then I’d have to reconsider his employment) that any links that point to another website gets assigned a link of .red-link.

And that’s the practical reason for choosing a structural naming convention instead of a presentational naming convention – if not for semantics and best practices – then for helping Dave Newbie know what particular classes and ids mean, not what they look like or where they are (which he can already see anyways – granted that he doesn’t suffer from dyslexia or particular forms of color-blindness).

Let’s rework Example 1 to reflect a (sort of) structural naming convention.

Example 2: A structural naming convention.

Example 2 illustration

In Example 2, I’ve renamed the classes and ids to structurally-descriptive names.

#top-div has become #header, #left-col (short for left column) has been renamed to #main-content, and so on. That’s much better and more intuitive.

Wait a minute!

After looking at the example, some of you may be saying “Wait a minute Jacob, aren’t #header and #footer presentational descriptors?” –  some might even modify this question with an abbreviated explicitive and exclamation point like “…WTF!”, and some may go further with “WTF n00b!!”.

Yes, indeed you’re (mostly) right.

But now I ask you this: without any additional information – what does #header and #footer mean to you?

Some of the responses might be:

#header is for…

#footer is for…

Without telling you (or Dave Newbie for that matter), what they mean to me, you already know what they are for and what they probably mean.

That’s because names such as #header, #footer, and #sidebar are well-established.

In a survey of websites of some web professionals, Andy Clarke lists the naming convention used for the structure of these sites, check it out here.

You can see in Andy Clarke’s survey that #header and #footer are staples, and are used the majority of time. So they’re instantly recognizable.

We can follow a structural naming convention blindly by instead using #branding for #header and #siteinfo for #footer – but at the end of the day, I chose to bend the “rules” for the purpose of practicality.

#header and #footer still describe the purpose and the structure of those particular elements in the document, exactly like #branding and #siteinfo does.

In short, Dave Newbie won’t be knocking on my door at 3:00AM in the morning asking me what #branding means so that he can meet his deadline (and Dave, please call or text next time, don’t just show up in my front door steps).

But for those who are unwilling to compromise, let’s rework Example 2 to a strictly structurally-named example.

Example 3: Really using structural naming conventions.

Example 3 is fully-structural in naming convention. It describes what the div’s and other elements are for, instead of where they are or how they look. I’ve used Andy Clarke’s suggestions in an article he wrote a ways back.

A few guidelines

Here are a few guidelines to help you name your elements structurally, and these are just thatguidelines. In the end, you have to use what’s best for you and the project at hand.

1. When assigning a class or id, ask yourself “What is this element for?”

For example, if you have a span class that’s meant for captions, you might call it .caption or .figure-caption instead of .smaller-text.

If a particular group of images are banner advertisements, you might want to call the class .banner or .ad-banner instead of .sidebar-images (since they may change locations).

2. Avoid using names that rely on locational or visual aspects of the particular element

In Example 1, we used .red-link for links that are red, and #left-col for the column on the left.

Later on, in Example 2 and Example 3, we changed them to .external-link and .main-content.

The practical reason for doing this is that it keeps your HTML markup accurate even if – say – you change the style of the .red-link class to green or brown.

Of course you can always do a batch find-and-replace if you have a static site, hunting down .red-link and replacing them with .blue-link in all of your affected HTML documents, but why rely on that when you can avoid it in the first place with a little forethought.

It also keeps your code (code is used literally here, not to imply that CSS or HTML is programming – which they aren’t) semantic.

You don’t have to change .red-link in the markup even when you’ve changed the value of the color attribute in the stylesheet, but it would be semantically inaccurate in describing that particular element.

For example, even if it’s called .red-link and you changed your style declaration to: { color:  blue;  }

a elements with the class .red-link will be rendered as blue despite of their class name (at least in most browsers).

But wouldn’t that be irritating? I know I wouldn’t be able to sleep at night knowing that my .red-link‘s are being rendered as blue.

And wouldn’t that be confusing to Dave Newbie, the new member of my development team?

If instead of .red-link or .blue-link, I used .external-link, then it wouldn’t matter if it’s red, green, blue, or black – it’ll be accurate as long as I do indeed use them for external links.

3. Use names that are intuitive to you

Earlier, in Example 2, I used #header instead of #branding. The reason is because I feel that #header is more recognizable than #branding. Notice that even though it can be interpreted as a locational description – I still used it.

I decided to do what’s best for me and what I think is best for the people that might be working on the same project. I bent the “rules” (notice that rules are in quotes because these are more like guidelines, not the law of the land) – so to speak – for the purpose of practicality and general intuitiveness.

Here’s a good guideline for naming classes and id’s intuitively.

Ask yourself, “If I asked Dave Newbie what this class (or id) is for, would he automatically know?

That’s programming 101, naming variables intuitively so that other programmers will know what the variable holds ($total instead of $t) – and that lesson is applicable to CSS naming conventions.

Further reading

The concept of structural naming isn’t new, and there have been wide discussions about the concept. Here, I’d like to share a few resources on the topic to help you further explore the concept.

Structural Naming

In a short post, Eric Meyer discusses his viewpoints on class and id naming conventions, mentioning Andy Clarke’s viewpoint on the matter.

Standardizing CSS class and id names

Michael Meadhra discusses presentational naming conventions and structural naming conventions.

Build for the Future: Bend, Don’t Break

Garret Dimon discusses the foundations of creating a flexible and adaptable website that’s always prepared for changes in the future. He also mentions how HTML markup is the foundation of a website, citing names like left_bar can quickly be outdated in a design change.

About the CSS Tips series

The CSS Tips series is a group of articles on Six Revisions that focus on a particular CSS tip, concept, or best practice. In each article, I’ll deconstruct a particular tip/standard/best practice and provide the context, benefits, and disadvantages of each.

I believe in learning both theory and practice, as well as striking a balance between strict, uncompromising standards and practicality, so you’ll get a chance to learn the way people generally do it, and why you shouldn’t necessarily follow them blindly.

I’ll present each CSS tip as comprehensively as I can, but I depend on you to correct me if I’m wrong, expound on things I skimmed over, clarify things that may be confusing to our fellow beginning developers, and provide your own input on the subject – so I highly encourage you to contribute in the comments.

To see all the CSS Tips articles thus far, you can go to the CSS category.

Related content

This was published on Dec 4, 2008


Henry Brito Dec 04 2008

Nice, good nice

Nice article!

insic Dec 04 2008

nice tips, Structural naming convention helps me to have clean, better and more organized css. But sometimes I mess up when my css becomes really big. lol

Thanks for the nice article.

Andrew Odri Dec 04 2008

Hey Jacob, really nice write up :) I liked your rhetorical questions actually:

When assigning a class or id, ask yourself “What is this element for?”
If I asked Dave Newbie what this class (or id) is for, would he automatically know?

Those alone should weed out 99% of poor structural names.

Vladimir Carrer Dec 04 2008

First, Great Post! I’m thing a lot lately about naming convention, considering that all my CSS Frameworks are “not” so semantic. I’m trying to give meaning to all my classes. And not always is easy task. I think that ultimate goal should be universal naming convention that every CSS developer shout be able to understand. Maybe it is wrong to call it #Header or #Footer but it is becoming a standard. I hope you will write more beautiful post about CSS. Thanks!

Rishi Luchun Dec 04 2008

Nice tips, thanks

Good read. People always seem to forget, “Always consider the context.”

Jim Gaudet Dec 04 2008

Excellent, I don’t think enough people care about what their “code” looks like, or if it even validates.

I like to create ID’s for all my structure, ie header, footer and sidebar. Then I use classes inside of the content of the divs. This allows me to have a structured design with divs and my minor updates with classes.

Susie Dec 04 2008

I found this tip really useful, and will endeavour to keep it in mind when building style sheets in the future.

You’re right, its so easy just to name a style after what it looks like or where its located, but in order to make it easy on ourselves or the next person to work on the site, we need to spend that extra half a second to name it structurally, thus saving a bundle of time in the future.

Chris Eppstein Dec 04 2008

I couldn’t agree more. Unfortunately the trend with CSS Frameworks these days is to move away from semantic ids and class names and mix presentation with markup again. I address this problem with a new stylesheet framework named Compass. Read about it here:

Michael Dec 04 2008

Great article full of great tips. I especially like: “(I didn’t comment my code, because remember – I like to do things the hard way)” that’s one of my biggest pet peeves.

Far too often I see posts that say not to comment your code to save space, that’s when I say ‘WTF? n00b’.

Between commenting your code and using structural naming, you’ve saved not just Dave Newbie time but yourself as well when you come back to a project months or years later.

Again, great post, keep up the good work.

Simon Dec 04 2008

Great tips – i’ve been able to teach myself basic css, but every new bit of info helps

Jacob Gube Dec 05 2008

I’m so happy many of you found this piece informative and humorous, I’m trying to vary the types of articles you see here on Six Revisions, so expect more of these types of stories!

@Andrew Odri: Yeah that’s true! See I do get to work with a lot of new developers, not just for CSS strictly, but server-side code. So in anything I do, whether it’s naming a selector, or writing a code block in PHP – I ask myself, “if so and so reads this, will he/she understand it right away?” and that’s when I reconsider if I chose the right class or id name, or the right variable name, or if I should provide comments in the code block.

@Vladimir Carrer: standardizing classes and id names can be a good or bad thing depending on who you ask. It does limit your ability to go out of the norm. Additionally, HTML 5 will help a lot in not only standardizing naming conventions, but also keeping the code semantic. For example, they have a <header> element which is a replacement for <div id="#header"> (or whatever you call your header div).

@Susie: I like your perspective on naming conventions, spend half a second now, save a lot of time in the future! Kind of like the old saying, “An ounce of prevention is a pound of cure”.

@Chris Eppstein: We’ll get to the topic of CSS frameworks in another CSS Tip series, so I’ll hold my tongue about my opinions on CSS Frameworks. :) But great article, and let’s just say I agree with you.

@Michael: For CSS I don’t comment a lot, but I do comment on things that may throw people off. For example, if I was using an image replacement technique (I usually use the text-indent method because the text doesn’t get hidden in screen readers), then it might look something like this:

h2 a.image-replace { 
  text-indent:-9999px; /* text-indent to push text out of the screen */

Other than that, I bank on intuitive naming of classes and id’s, section comments for easier findability, and that the person working on my code uses a browser tool like Firebug or Web Developer. I do agree that not commenting your code at all is wrong, but in terms of commenting CSS, I stand in the middle – not “don’t comment at all” but not “comment a lot” either.

Farid Hadi Dec 07 2008

Hey Jacob,

This is a great topic to bring up. I’m looking forward to more CSS Tips articles.

Michael Dec 08 2008

@Jacob I agree, with CSS I don’t do a whole lot of commenting, except for 1) Like you I comment things that may throw others off, and 2) I break my CSS files up into 3 sections (Standard Selectors, IDs and Classes) and use comments to differentiate the sections. Personal preference, but for me it makes it much easier to find what I’m looking for.

Again, great article, I’m looking forward to more.

Jacob Gube Dec 09 2008

@Michael: Yeah, exactly. I think for CSS, it’s so simple that if you need to comment a lot, you may have to think about your code. For PHP, I do comment like there’s no tomorrow though (I use the PEAR coding standards for my projects) – not only for people working on my stuff later on, but especially for my sake.

I’m curious to hear more about how you break up your CSS files into the 3 sections you mentioned.

ivan acosta-rubio Dec 10 2008

Love the article!

Yay for self-documenting code!

nice post. i always try to use structural naming.i think its more logical.

sivas Mar 21 2009

great, thank you

Ronald Apr 05 2009

this is really great post. I’ll apply this when writing CSS such impart new knowledge on me…thanks for the share

Dylan Bauer Jul 21 2009

Excellent read, I didn’t even realize I was making some of these trivial mistakes!

Irene Dec 15 2009

Thx,This is really useful for us.

Sidra Blue Mar 03 2010

Good read, although personally, I hate long names that take up valuable filesize. With the way most websites are, you would want to reduce as much as possible, your filesizes that are being downloaded for a view.

There are the standard class names which would be common for all sites like #header, #footer, #content, but everything else is normally different these days.

Coming up with shorter but easily understandable names, (eg using ll in place of left, or rr in place of right, etc) and have an accompanying document on how these class names are so, would hopefully help Dave Newbie easily understand and help them “immediately start work without having to constantly scratch their heads”

Most would probably disagree though, but that’s just our way =)

Kimball Le Apr 13 2010

how do you feel about css frameworks such as 960 gs and the naming of classes?

The one thing I hate about design is how all of the different browsers are different and need to be accounted for.

I use resets a bit but probably not enough and many designs therefore are flawed in so many browsers because of this (Why can’t everyone just use FireFox?)

this is really great post. I’ll apply this when writing CSS such impart new knowledge on me…thanks for the share

cooljaz124 Oct 11 2010

Yes, Point taken. Very nice one.

Derek Jun 17 2011

This is just like HTML5.

Skaman Sam Jun 28 2011

I really liked this article and sent it to my rails dev team. In my professional life, I prefer to think of #header and #footer and general areas, then get more specific, with hyphen-levelling, such as:

#header, #header-logo, #header-logo-text, #header-motto,#header-motto-emphasis, #header-funnyPerson-head-rightEye-eyebrow-hairFolicle

This just makes sense to me. It can make the selectors a bit long, but is perfect for parsing with regex.

As a bonus, Rails like to create name with underscores to separate objects, so I will name them #header-name in my code, and Rails with turn it into something like #header-name_person_name. I can then find the objects by splitting the id at each underscore. Nifty!

Archana Nov 25 2011

Nice Article about naming conventions. Thanks for the info

This comment section is closed. Please contact us if you have important new information about this post.