Digital Web Magazine

The web professional's online magazine of choice.

Architecting CSS : Comments

By Garrett Dimon

July 18, 2005


Paul Nattress

July 19, 2005 1:31 AM

Great article, and long overdue.

When I create my style sheets, I like to organise my styles in the order that the elements appear in the XHTML. This places the header styles at the top, the navigation next in line, then the content, then the footer etc.

This way, it’s quick and easy to navigate through the style sheet to find a particular style. I don’t need to know the name of the section it lives in, I just need to know where it is on the page.

Another thing we’ve started to play with, is to group our style sheets by the type of styles in them. We have a style sheet for layout, one for fonts, one for link styles etc. This allows other developers to know exactly which style sheet they need to work in. It also prevents someone from altering the layout when they only need to be changing a couple of font colours. This is particularly useful if you have several developers working on a large site as it makes asset management a little easier (only certain memebers of the web team could be given permission to edit the layout style sheet for example).

One last point (and this relates more to XHTML than CSS but is still relevant) – when we create a div with a class or ID, we always put a comment after the closing div to state which div it closes. It makes it easier for other developers to go through the code and add elements into the right place.

Adam Taylor

July 19, 2005 2:30 AM

I also tend to use Paul’s idea of organising by element order… But that eventually breaks down because styles will share similar properties.

Personally, I tend to organise properties within a declaration from inside-to-out – beginning with stuff like font-size and text-transform asnd ending with (in order) padding, border, margin and positioning.

What I haven’t tried (but must) is getting CSS parsed by server-side ASP/PHP, so that variables become possible. That way I wouldn’t have to keep retyping the same #rgb property over and over…

Garrett Dimon

July 19, 2005 5:01 AM

Paul – That’s a very good tip to put a closing comment after a div. That’s something I’ve been doing for a while. However, with the right code editor, collapsible code can be an amazing tool and make that comment unecessary.

Adam – I’d be a little hesitant to use variables in CSS. However, if you’re referring to constants, I think that could be a great bonus with regards to managing color and some other properties.

Jeff Sargent

July 19, 2005 5:39 AM

I (and the company I recently worked for) organize our styles in a similar way. We have a mainstyles.css file that imports 4 others: layout.css, design.css, incidentals.css, and ie5win.css. We separate out any styles for layout into layout.css, and all colors, borders, font-sizes, etc. into design.css. I edit the design.css and layout.css side by side when setting up a site. After that’s done, styles that pertain to one or two pages go into incidentals.css.

It took a little getting used to, but I really like it now.


July 19, 2005 6:55 AM

I basically do what Paul mentions. I’ll build a quick TOC in comments of the major layout elements(header, global nav, columns, footer, global links and other formatting) and I’ll continue to iterate over it as I go. I’ll also include comment seperators in the CSS file between each section, to work as headers for each section.

I also make sure, as someone mentioned, to include comments after major layout divs for better visual separation when I’m editing the code.

One article I’d like to see posted here, Garrett, is something along the subject of streamlining the effort of working with visual designers and css developers. I’ve never worked on a large site project that completely adhered to what I would call the “spirit” of CSS. It seems visual designers designate everything as a class, and don’t bother to use the inherent tags in XHTML/CSS to style their structure. It can be difficult, given strict timelines on these projects, to find time to work towards redefining the classes as proper elements.

Andy Matthews

July 19, 2005 10:46 AM


I build custom Content Management Systems for my company. They all use the same basic codebase so over time I’ve refined and honed it to where I can change every facet of the site from one file.

In ColdFusion, my language of choice, I have a file called Application.cfm which gets included on every page in my application. I define colors, shapes, fonts and more in this file all as variables. Then, in my header template (which also gets included on every page), I place all of my CSS and print out the corrsponding variables in their proper places.

It takes a little fiddling to get it working correctly but the flexibility it offers is unpararelled.


July 19, 2005 5:59 PM

Hey Garrett Dimon, what text editor do you use that allows you to collapse your code?

Eric Meyer

July 19, 2005 8:13 PM

They’re properties, not attributes.

As for alphabetizing, I’m not so sure that’s always appropriate— I guess is depends on how you alphabetize. That is, does ‘border-width’ come before ‘border’ or after? Yes, it can make sense to have both in the same rule, and their order will be critical to the final outcome.

Personally, I tend to group like properties together. For example, I might put all the box-model related proprties together, then all the font and text-related properties, then the colors and backgrounds, etc. Not necessarily the best approach for every situation or every person, of course, but it seems to work for me.

Jens Meiert

July 20, 2005 1:56 AM

Nice article, though I use another way to organize style sheets [...].

For rule sorting, I once defined for my company to “sort them by inverted specificity, where combined selectors have to be placed where their first selector (“div” in the case of “div p”) should be placed. At same specificity, rules with block-level element selectors precede inline element selectors. “More semantic” elements also precede, i.e., “h1” comes before “div”.”

Since just hacked in, I’m not absolutely sure if it’s really adequate (quite compressed form, hein), but I will write a more comprehensive article soon, dealing with CSS organization and sorting. It’s non-trivial and important matter, so I can only give kudos to you again – nice article.

Garrett Dimon

July 20, 2005 5:44 AM

Michael – TextMate. It’s Mac only, but it’s great.

Eric – Agreed. I don’t like to separate height and width and other similar concepts. I’d say this just depends on personal preference and experience. I’ve just run into too many problems in both my CSS and other’s where the “properties” were inconsistently organized, and the result was not being able to immediately see errors.

At the end of the day, these are still only meant as guidelines. Even I don’t follow them 100%.

I could definitely see a followup with examples and additional suggestions. Thanks for the feedback everyone.


July 27, 2005 2:24 PM

I’ve used a couple of Windows editors which collapse code.

Macromedia Homesite has lots of great tools. It doesn’t collapse code by tags automatically, but can find matching tags and you can collapse sections you select.

MS Visual Studio is expensive, but if you work with .NET it’s worth it, and it makes a great HTML and CSS editor (so long as you avoid Design mode). It even has intellisense for CSS, and with a little web research you can make it validate XHTML as you type.

On the CSS variables front, I’d be wary for one reason only: if you’re not careful a dynamically generated CSS file will take away one of CSS’s big advantages, because it will no longer be cached by the browser. You’d need to make sure you send the right HTTP header along with it.

Mike Stenhouse

August 1, 2005 6:26 AM

I wrote a couple of articles on a similar subject a little while back. I tend to split my CSS files into functional groups of tags that I can reuse across sites (same as Paul #1). Having this framework to start with means I can get up and running on new projects super-quick and the familiar organisation of the files allows me, and anyone else working with me, to get oriented very quickly.

If you’re interested:
Modular CSS
A CSS Framework

Douglas Clifton

August 2, 2005 9:30 AM

Caching is a big advantage for all documents that do not vary. I wish people would stop spreading the misinformation that dynamic CSS is somehow difficult to configure or use so that the browsers do take advantage of caching. It is, in fact, quite trivial to do so.


August 5, 2005 9:33 AM

Hello to everyone. Just thought you’d want to know that I have translated to French this article and posted it on my website, alongside the translation of the article of Stuart Rosenberg on ALA (Dynamic Text Replacement). I believe I haven’t forgotten to properly credit anyone, but if such was the case or there is a mandatory sentence to include that I didn’t, or I just shouldn’t have translated/posted it (though I’d fail to see why), etc, please tell me !
Have a great day and above all thanks for the great article ! :)

George Papadakis

August 11, 2005 4:01 AM

A rather small, but quite useful tip my experience as designer has taught me is about creating an image repository (folder) within the css folder.

Something like /css/img is what I am talking about.

That means : do not store the background images in the global image folder on your site, instead store them in a specific css related folder.

The advantages:

1. You will know where your css related images are store when composing your css file(s).
2. I am pretty sure url( “img/background.gif” ) is much better and usable than url( “../../images/background.gif” )
3. You can easily transfer all the css related files (.css, images ) by just copying one single folder.
4. You wont have to worry if an image is being used for (just) css purposes or not.

Christopher Fahey

August 14, 2005 1:43 PM

Thought I’d throw a project management monkey wrench into this.

There are lots of ways of organizing CSS logically based on what the styles are supposed to do and where in the site they fit in, but sometimes you may need to thwart that nice logical system to support the needs of a waterfall production cycle.

An important thing to consider for exceptionally large projects is the time difference between the day you start coding HTML/CSS and the day you’re done. Sometimes this can be months, during which time a significant amount of back-end code (integration with applications, content management systems, etc) will almost certainly be occurring. And during this time, the HTML/CSS developer may need to “hand off” their code in chunks to the back end team.

In other words, it might be necessary to break up your CSS files into groups chronologically according to the project schedule, which might not map so nicely with all of the UI-based organizational techniques discussed herein. So maybe you’d have a set of HTML & CSS files that need to be handed off during Week 3, even though the pages they pertain to may not have anything in common from a UI perspective (but lots in common on the back end, such as sharing code).

Another chronological dilemma with CSS is the inevitable changes that occur along the way. For example, you’re 75% of the way through coding a 200 page site, and you realize that the main navigation needs to change – but the back-end team has already built it. You may find yourself needing to change CSS files that you thought were 100% complete weeks or even months ago. If those files have already been integrated into a back-end system, this might be tough to manage.

So when planning your CSS grouping structures, sometimes it’s good to try to keep “files that are likely to change a lot” all in the same small set of CSS files, instead of leaving little bits of non-final CSS in every single file. So when you need to change that nav, the nav.css is separated from everything else.

Frequently, when planning the integration of the work of front- and back-end developers, it’s possible to have the code & page groups synch up nicely, especially if the site is portal- (or include-) based and the pages are built as lots of smaller modules instead of as whole pages. It’s not hard to imagine a single page pulling in ten different CSS files.

I’d be interested to hear how others handle these sorts of dilemmas. Is there such a thing as dynamic CSS files, where the CSS resides in a database or a CMS and is retrieved by passing URL parameters?

Richard Conyard

August 21, 2005 5:57 AM

Nice article – although we tend to split somewhat differently. One global CSS that covers CSS positioning and one WYSIWYG css that ties in the the CMS to bring in the styles for content.

Mike Mertsock

August 23, 2005 9:41 PM

This is a great introduction to CSS planning. All of us web developers need to spend more time thinking about the maintainability of our CSS code. My blog discusses my strategy in more depth and describes a successful example of CSS organization.

Adam van den Hoven

August 24, 2005 1:10 PM

In general I follow a combination of these techniques. I’m still working on all the details but its pretty nice so far.

I write CSS for a webapp built on Java and JSPs. Becuase i want to have my CSS as granular as possible AND make the fewest number of http requests as possible (its a metric used to measure performance) I leverage JSPs get both.

Each type of page I’ll create a jsp (home.jsp, forms.jsp, content.jsp) each jsp consists of a number of static includes to normal CSS files:

<%@ include file=“homelayout.css” %>
<%@ include file=“colors.css” %>
<%@ include file=“common.css” %>
<%@ include file=“primarynav.css” %>

and so on. Now my CSS files are accessible as /Style/home.jsp.

Problem solved.

Kevin Cannon

August 26, 2005 2:46 AM

Gah! Architecting is not a word. Please stop the spread of this horrible term.

Designing, structuring, organising, are all suitable, and they’re actually reall words!

Isaac Z. Schlueter

October 14, 2005 8:25 PM


About 1,210,000 people would disagree with you. “Architecting” might not be in dictionaries yet, but it’s in common usage. The very fact that everyone knows what it means is proof enough, but here’s more:

Furthermore, the meaning is not precisely the same as “designing”, “structuring”, or “organising”.

“Reall” and “Gah” on the other hand, are not proper words. You know what they say about eyes, planks, and splinters.

I built a very big web application with several different sections. Each page has a “type”, and each also included “main.css” first.

If a page’s type is “”, and its ID is “123”, then it would include the following files, if they exist, in this order:


If a file doesn’t exist, it isn’t imported. This allows the developer to drop a CSS file into the folder to just affect one type of pages or a single page.

Most of the “override” CSS files were very small, so organization didn’t matter much, but the main file is about 2000 lines, so organization is crucial.

My policy on CSS organization is this, and it’s based on how I think about the page and go about writing the CSS, so it’s sort of a logical/chronological ordering:

1. Rules that set the defaults: primarily, set the font styling on the HTML/BODY elements.
2. Rules that put the outermost blocks where they belong. Put the sidebar where it belongs, make room by moving the content out of the way, set the footer as a clearer, etc.
3. Rules for the header, (more or less) sorted by tag.
4. Rules for the content, sorted by tag
5. Rules for the sidebar, sorted by tag.
6. Rules for the footer.
7. Rules that override what came before.

In all of this, comment like it’s going out of style.

The idea is that, if you were to watch the HTML as the CSS rules are applied, you’d see the page gradually get closer and closer to its final state in logical steps. Things lower down the CSS are less important, until the last section where any overrides appear, commented to show why they’re there.

Another key is to have a few outermost ID attributes in your XHTML, so that you can override things using specificity without using the !important modifier. If you need to override a rule later on for a specific situation, you can then use a selector like #outermost #page #content p { ... }
if necessary.

Sorry, comments are closed.

Media Temple

via Ad Packs