Architecting the CSS in a Tridion Implementation (How to keep the hippies from winning)

In a previous post that I wrote, I talked about living the web developer’s fantasy of being told, “be as cutting edge as you want”, and how Joe Shirley (a fellow Tahzooligan) and I decided to use all the nice things we could 1. Before I get in to how we used a CSS preprocessor to crank our BEM methods up to 11, I need to take a step back and explain how we architected the CSS.

I’m not a Java monkey or a .NET hacker. I’m a front-end guy who works with Tridion. So first…

A Message from Your Stylesheet

The complexity of a language — or lack thereof — should have no bearing on the decision to write it with a disciplined and thoughtful architecture.

We don’t want to just write some stylesheet like some same carefree, free-wheeling, tie-dye wearing hippie from Woodstock. We want to make plans, classifications, and naming conventions like the guys that planned Woodstock.

Users and the Principles of CSS Architecture

The User Experience is our Guiding Principle

A user experiences a website as a sum of increasingly complex interactions. If a good design acknowledges that there are layers of complexity, then you could generally divide those layers into brand, layout (information architecture),and the actual content which is consumed by the user. So at Tahzoo, whenever possible, this sets the foundation for how we architect the CSS:

  • We never write a whole stylesheet
  • At minimum, a stylesheet is split into four files:
    • CSS reset
    • Brand
    • Page Layout
    • Components
  • Preferably one CSS file per component template
  • Internet Explorer stylesheets may also be divided along the same principles
  • Responsive stylesheets are also cut along the same rules— on a per-breakpoint basis

Slicing your CSS is Good for the Soul

Whether writing the stylesheet, or being given a stylesheet, we work more efficiently when its split along the layers of the design. A team can work on various pieces of the CSS without stepping on each other’s toes. Not only that, we get just as much flexibility in producing a new layout with the old branding as creating a new branding with the old layout. There’s the added bonus that if you have a good methodology for your HTML (BEM, cough cough), new projects never start from scratch; you already have some element of the design to work from.

Syndicated Design™ is our goal

Writing the Main CSS File

In our static development phase (where we’re just working with HTML, CSS, and JavaScript), our CSS file starts as /assets/css/ But, that main file doesn’t actually contain any styles. Instead, it’s full of @import rules1:

@import ('assets/css/core/000-reset.css')
@import ('assets/css/001-brand.css')
@import ('assets/css/002-tables.css')
@import ('assets/css/003-forms.css')
@import ('assets/css/004-sprites.css')

@import ('assets/css/010-page.css')
@import ('assets/css/011-homepage.css')
@import ('assets/css/012-contentpage.css')

@import ('assets/css/020-bodycopy.css')
@import ('assets/css/030-imageslider.css')
@import ('assets/css/040-articlelist.css')

@import ('assets/css/090-ie8.css')

@import ('assets/css/100-tablet.css')

Naming Your CSS Files for Fun and Profit

Sure, we have a CSS file loaded with @imports, but we don’t go naming those files with the samewreckless abandon that flower children get named in drum circles. Not only do we number the files for the order in which they appear, we have pretty strict rules for how to number them. Otherwise, the hippies win:

  • Three digits as the start of the name
  • Separate the integers from an arbitrary name with a single hyphen
  • The ones, tens, and hundreds place each represent a level of complexity
  • The 0 is a core style
  • 000 - 009 are for the core and the brand
  • 010 - 019 are for page templates
  • 020 - 089 are for component templates; it’s still up for debate whether we increment by one or ten
  • 090-099 are for Internet Explorer or other browser hacks
  • 100-999 are for responsive styles; we increment by 100 per breakpoint; a responsive version of this stylesheet would be identical but with every filename starting with a 1

Using this numbering system in our naming convention helps us in a few ways. For one, we know the order in which they must appear in the main CSS file. For another, we’ve abstracted our styles to different layers without creating new folders. We also have a system that helps us organize responsive and even print versions of our stylesheets in an identical fashion to each other. Even better, we know what a CSS file is doing without having to open it up and look through the code.

If I had gotten my way, we actually would have used five digits — we’d go to the thousands for responsive and ten-thousands for print. And each place would have represented a whole layer of the design. I was outvoted…something about “out-nerding Melvil Dewey”.

A good number-based naming convention leads the way in innovative conformity™

Moving your CSS to Tridion

Pre-Tridion, having a lot of CSS @imports is fine. In a production website, this is a bad idea. The fewer HTTP requests there are, the better is is for the end user. We want to keep the discrete organization of our files, but have just one request for a stylesheet come out of the other side.

The CSS Components

Depending on the client, our CSS files become either multimedia components (of the mime type text/css) or code components (a schema with the plain text field code. Regardless of the type, a super basic component template is created to render the code.

As a code component, you’ll write the smallest Razor TBB in history:


I prefer code components because I like being able to jump into Tridion to edit CSS (a CodeMirror extension makes this pleasantly unpainful).This really isn’t optimal in an agile workflow because you’re migrating changes with copy and paste; many clients let the CSS go in as a multimedia component (a binary with the mime text/css) because it’s easier to synchronize things through WebDav.

The CSS Page Template

After we’ve created a basic Component Template that outputs our CSS, we build a CSS Page Template. There’s no need in sharing that code because its no more complex than your Component Template. We just need to put CSS components on a page that has the file extension .css and publish it. Tridion will automatically concatenate all of our code components into a single CSS file.

Now, the numbering system we’ve adopted matters quite a bit at this point, because as we build our CSS page in Tridion, we need to know the order in which the components should be arranged. Having the number as part of the name of the CSS component makes it very easy to make sure that we’ve assembled our stylesheet in in the proper order.

The Big Idea

The design of a website is layered and we should let that be the guiding principle in how we architect our CSS. We want our CSS to be composed of brand, layout, and content files because this extends a healthy amount of flexibility— enough that you should have syndicatable design. Dividing our styles even more discretely makes it easier for large teams to work together without killing each other’s grooves. Even better, a thoughtful number-based naming convention helps us understand the purposes of files without even opening them, and makes it easy to replicate the organization within Tridion.

Sources and Whatnots

1 Joey decided to do all the nice things that we could. I nodded my head in agreement and looked at cat videos.

2 My good buddy Joey Shirley pointed out that @imports are not awesome for performance, and gave me an authoritative resource to prove it. I do not advocate using the @import rules in a production site. Especially after looking at the numbers, it may even hurt that project on your local environment


  1. //

    Fascinating post! Coming from the functional design side with a mix of other backgrounds (basic markup/css, ASP.NET, etc), I’ve been trying to find way to connect the semantic meanings I’d _like_ the content model to have to the front-end markup and styles for the designers.

    Do you have preferences for classes, ids, and actual nodes as they come from the CMS?

    I’ve read a little on object-oriented CSS and recognize principles like separating structure from content, but wonder if that could mean a mostly automatic approach at outputting markup with classes that include maybe schema, field names, position (e.g. “first” and “last”), and/or component template names.

    Is this the “BEM” you’re referring too?

  2. //

    Hi Alvin,

    I probably should’ve linked to my earlier BEM post on how we did classes, semantics, and the like:

    BEM is a pretty solid methodology that can be aligned easily with schemas and field names. It also produces highly semantic class names. I’ve found that, as a principle, using IDs in CSS is not a good idea.

    The real trick is separating things that are Brand from things that are layout or component-template focused.

Comments are closed.