Menu Search
Jump to the content X X
Smashing Conf New York

We use ad-blockers as well, you know. We gotta keep those servers running though. Did you know that we publish useful books and run friendly conferences — crafted for pros like yourself? E.g. upcoming SmashingConf New York, dedicated to smart front-end techniques and design patterns.

Improving Code Readability With CSS Styleguides


Once your latest project is finished, you are very likely to forget the structure of the project’s layout, with all its numerous classes, color schemes and type setting. To understand your code years after you’ve written it you need to make use of sensible code structuring. The latter can dramatically reduce complexity, improve code management and consequently simplify maintainability. However, how can you achieve sensible structuring? Well, there are a number of options. For instance, you can make use of comments — after all, there is always some area for useful hints, notes and, well, comments you can use afterwards, after the project has been deployed.

Indeed, developers came up with quite creative ways to use comments and text formatting to improve the maintainability of CSS-code. Such creative ways are usually combined into CSS styleguides — pieces of CSS-code which are supposed to provide developers with useful insights into the structure of the code and background information related to it.

This article presents 5 coding techniques which can dramatically improve management and simplify maintainability of your code. You can apply them to CSS, but also to any other stylesheet or programming language you are using. You can browse through the references listed under the article — they containt further information about how you can achieve a well-organized and well-structured code.

You may also be interested in the articles

1. Divide and conquer your code Link

First consider the structure of your layout and identify the most important modules in your CSS-code. In most cases it’s useful to choose the order of CSS-selectors according to the order of divisors (div’s) and classes in your layout. Before starting coding, group common elements in separate sections and title each group. For instance, you can select Global Styles (body, paragraphs, lists, etc), Layout, Headings, Text Styles, Navigation, Forms, Comments and Extras.

To clearly separate fragments of code, select appropriate flags or striking comments (the more *-symbols you have in your code, the more striking a heading is). In the stylesheet they will serve as a heading for each group. Before applying a preferred flag to your code, make sure you can immediately recognize single blocks when scanning through the code.

However, this approach might not be enough for large projects where a single module is too big. If it is the case, you might need to divide your code in multiple files to maintain overview of single groups of code fragments. In such situations master stylesheet is used to import groups. Using master-stylesheet you generate some unnecessary server requests, but the approach produces a clean and elegant code which is easy to reuse, easy to understand and also easy to maintain. And you also need to include only the master-file in your documents.

[Master Stylesheet]

Project:	Smashing Magazine
Version:	1.1
Last change:	05/02/08 [fixed Float bug, vf]
Assigned to:	Vitaly Friedman (vf), Sven Lennartz (sl)
Primary use:	Magazine 
@import "reset.css";
@import "layout.css";
@import "colors.css";
@import "typography.css";
@import "flash.css";
/* @import "debugging.css"; */

For large projects or large development team it is also useful to have a brief update log and some additional information about the project — e.g. you can put the information about who is this CSS-file assigned to and what is its primary use (e.g. Smashing Magazine, Smashing Jobs etc.).

Additionally, you can include a debugging CSS-code to take care of diagnostic styling in case you run in some problems. Consider using Eric Meyer’s Diagnostic Styling4 as a debugging stylesheet to test your CSS-code and fix problems.

2. Define a table of contents Link

To keep an overview of the structure of your code, you might want to consider defining a table of contents in the beginning of your CSS-files. One possibility of integrating a table of contents is to display a tree overview of your layout with IDs and classes used in each branch of the tree. You may want to use some keywords such as header-section or content-group to be able to jump to specific code immediately.

You may also select some important elements you are likely to change frequently — after the project is released. These classes and IDs may also appear in your table of contents, so once you’ll need to find them you’ll find them immediately — without scanning your whole code or remembering what class or ID you once used.

[Layout] * body + Header / #header + Content / #content - Left column / #leftcolumn - Right column / #rightcolumn - Sidebar / #sidebar - RSS / #rss - Search / #search - Boxes / .box - Sideblog / #sideblog + Footer / #footer Navigation #navbar Advertisements .ads Content header h2 -------------------------------------------------------------------*/

…or like this:

[Table of contents]

1. Body
	2. Header / #header
		2.1. Navigation / #navbar
	3. Content / #content
		3.1. Left column / #leftcolumn
		3.2. Right column / #rightcolumn
		3.3. Sidebar / #sidebar
			3.3.1. RSS / #rss
			3.3.2. Search / #search
			3.3.3. Boxes / .box
			3.3.4. Sideblog / #sideblog
			3.3.5. Advertisements / .ads
	4. Footer / #footer

Another approach is to use simple enumeration without indentation. In the exampe below, once you need to jump to the RSS-section you simply use a search tool to find 8. RSS in your code. That’s easy, quick and effective.

[Table of contents]

1. Body
2. Header / #header
3. Navigation / #navbar
4. Content / #content
5. Left column / #leftcolumn
6. Right column / #rightcolumn
7. Sidebar / #sidebar
8. RSS / #rss
9. Search / #search
10. Boxes / .box
11. Sideblog / #sideblog
12. Advertisements / .ads
13. Footer / #footer
<!-- some CSS-code -->
[8. RSS / #rss]
#rss { ... }
#rss img { ... }

Defining a table of contents you make it particularly easier for other people to read and understand your code. For large projects you may also print it out and have it in front of you when reading the code. When working in team, this advantage shouldn’t be underestimated. It can save a lot of time — for you and your colleagues.

3. Define your colors and typography Link

Since we don’t have CSS constants yet, we need to figure out some way to get a quick reference of “variables” we are using. In web development colors and typography can often be considered as “constants” — fixed values that are used throughout the code multiple times.

As Rachel Andrew states5, “one way to get round the lack of constants in CSS is to create some definitions at the top of your CSS file in comments, to define constants. A common use for this is to create a color glossary. This means that you have a quick reference to the colors used in the site to avoid using alternates by mistake and, if you need to change the colors, you have a quick list to go down and do a search and replace.”

# [Color codes]

# Dark grey (text): #333333
# Dark Blue (headings, links) #000066
# Mid Blue (header) #333399
# Light blue (top navigation) #CCCCFF
# Mid grey: #666666
# */

Alternatively, you can also describe color codes used in your layout. For a given color, you can display sections of your site which are using this color. Or vice versa — for a given design element you can describe the colors which are used there.

[Color codes]

Background:	#ffffff (white)
Content:	#1e1e1e (light black)
Header h1:	#9caa3b (green)
Header h2:	#ee4117 (red)
Footer:		#b5cede (dark black)

a (standard):	#0040b6 (dark blue)
a (visited):	#5999de (light blue)
a (active):	#cc0000 (pink)

The same holds for typography. You can also add some important notes to understand the “system” behind your definitions.


Body copy:		1.2em/1.6em Verdana, Helvetica, Arial, Geneva, sans-serif;
Headers:		2.7em/1.3em Helvetica, Arial, "Lucida Sans Unicode", Verdana, sans-serif;
Input, textarea:	1.1em Helvetica, Verdana, Geneva, Arial, sans-serif;
Sidebar heading:	1.5em Helvetica, Trebuchet MS, Arial, sans-serif;

Notes:	decreasing heading by 0.4em with every subsequent heading level

4. Order CSS properties Link

When writing the code often it’s useful to apply some special formatting to order CSS properties — to make the code more readable, more structured and therefore more intuitive. There is a variety of grouping schemes developers use in their projects. Some developers tend to put colors and fonts first; other developers prefer to put “more important” assignments such as those related to positioning and floats first. Similarly, elements are also often sorted according to the topology of the site and the structure of the layout. This approach can be applied to CSS selectors as well:

	h1, h2, h3,
	p, ul, li,
	form {
		border: 0;
		margin: 0;
		padding: 0;

Some developers use a more interesting approach — they group properties in an alphabetical order. Here it’s important to mention that alphabetizing CSS properties may lead to some problems in some browsers. You may need to make sure that no changes are produced as a result of your ordering manipulations.

body {
background: #fdfdfd;
color: #333;
font-size: 1em;
line-height: 1.4;
margin: 0;
padding: 0;

Whatever grouping format you are using, make sure you clearly define the format and the objective you want to achieve. Your colleagues will thank you for your efforts. And you’ll thank them for sticking to your format.

5. Indentation is your friend! Link

For better overview of your code you might consider using one-liners for brief fragments of code. This style might produce messy results if you define more than 3 attributes for a given selector. However, used moderately, you can highlight dependencies between all elements of the same class. This technique will dramatically increase code readability when you have to find some specific element in your stylesheet.

#main-column { display: inline; float: left; width: 30em; }
	#main-column h1 { font-family: Georgia, "Times New Roman", Times, serif; margin-bottom: 20px; }
	#main-column p { color: #333; }

You remember exactly what you did and can jump back in there and fix it. But what if you made a lot of changes that day, or you just simply can’t remember? Chris Coyier suggests6 an interesting solution for highlighting recent changes in your CSS-code. Simply indenting new or changed lines in your CSS you can make recent changes in your code more visible. You can as well use some comments keywords (e.g. @new) — you’ll be able to jump to the occurrences of the keyword and undo changes once you’ve found some problems.

#sidebar ul li a {
     display: block;
     background-color: #ccc;
          border-bottom: 1px solid #999; /* @new */
     margin: 3px 0 3px 0;
          padding: 3px; /* @new */

Conclusion Link

CSS styleguides are helpful if and only if they are used properly. Keep in mind that you should remove every styleguide which doesn’t effectively help you to get a better understanding of the code or achieve a well-structured code. Avoid too many styleguides for too many elements bundled in too many groups. Your goal is to achieve a readable and maintainable code. Stick to it and you’ll save yourself a lot of trouble.

Sources and Resources Link

Footnotes Link

  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
SmashingConf New York

Hold on, Tiger! Thank you for reading the article. Did you know that we also publish printed books and run friendly conferences – crafted for pros like you? Like SmashingConf New York, on June 14–15, with smart design patterns and front-end techniques.

↑ Back to top Tweet itShare on Facebook

Vitaly Friedman loves beautiful content and doesn’t like to give in easily. Vitaly is writer, speaker, author and editor-in-chief of Smashing Magazine. He runs responsive Web design workshops, online workshops and loves solving complex UX, front-end and performance problems in large companies. Get in touch.

  1. 1


    May 2, 2008 6:45 am


  2. 2

    Great work as always, some really helpful tips! Thanks Smashing!

  3. 3

    Arthur Lawry

    May 2, 2008 6:49 am

    All well and good if you have a script to remove those contents prior to serving it to a visitor. Otherwise your maintainable CSS has a good chance at slowing down your visitors’ experiences with excessive file-sizes comprised of primarily comments and whitespace.

    I’m not advocating a lack of comments, but pointing out that this solution only works well if you can dynamically strip comments and spaces. Only then do you get the benefit of readable, maintainable, and tiny code.

    Same thing goes for external javascript.

  4. 4

    I’m all for keeping notes, but like Arthur Lawry said these css comments can add size if you’re not careful. I think for smaller websites it’s not an issue though and come to think of it, I’d rather loose 1/2 a second of load time than loosing my brain trying to figure out what I did two years ago. :)

  5. 5

    Paul Armstrong

    May 2, 2008 7:11 am

    Using the @import rule is likely to give your new visitors the “FOUC” bug (Flash Of Unstyled Content), where your html page renders without any CSS styles because the @import stylesheets get loaded after the page.

    I wouldn’t recommend using that method.

  6. 6

    Jeff MacCharles

    May 2, 2008 4:15 pm

    I agree, comments are nice; but can get out of control quickly and are timely. Sometimes what i do is i will create a text file that uses the commenting guidelines and aplly it for each stylesheet. This way i can keep my .css file small but still have a detailed reference for the future.

  7. 7

    Brad Baumann

    May 2, 2008 7:25 am

    I agree with Paul Armstrong. @import isn’t always the best of ideas.

  8. 8

    Great suggestion!

  9. 9

    The table of contents is a good approach to index what’s on a CSS page. I’m curious how this could be used to manage several CSS files?

    One thing to consider is the file size. I’ve been trying to optimize by reducing lines, leaving out comments and such but putting them in where it’s really needed.

    These are good practices though to consider if you have developers and designers working on a CSS page.

  10. 10

    Michael Thompson

    May 2, 2008 7:49 am

    “Some developers use a more interesting approach and group properties in an alphabetical order. In this context it’s important to mention that alphabetizing CSS properties may lead to some problems in some browsers.

    Wrong — alphabetizing your attributes won’t cause any problems.

  11. 11

    Acctually it could, if your CSS inherit on one another without using “!important”.

    As for the file size, you shouldn’t bother with that, the version that you are sending to the client should be minified with something like YUI Compressor. The commented version is for your development, and for tweaking stuff unitll you are ready to let the new style sheet to the clients.

  12. 12

    There’s another reason to go easy on the comments, at least for CSS that’s in the head of an (x)html doc inside style tags. Long visual dividers like the ones above, made of hyphens (minus signs) will choke the W3C validator (using plus signs, underscores, periods etc. won’t).

  13. 13

    Ahhh, adding an extra indent to a line that has been recently changed sounds like a wonderful and easy way of simplifying later troublehsooting… sw-ee-ee-ee-ttt…

  14. 14

    Utilizing these methods makes re-creating a stylesheet much more efficient.

    Not only does it allow for quicker production but also means you don’t leave anything out. I have a blank stylesheet with the second styled TOC, including all typography etc. I’ve gone from days of coding to hours to create the basics. Thanks Smashing!

  15. 15

    The biggest issue with using @import is that it causes extra http requests to the server and slows down site performance. Best practice is to house all your css in 1 file, it takes less time to load 1 large file than 8 small ones (file size + request time)

  16. 16

    wow, will make use of it in my next project…

  17. 17

    Sean Hannan

    May 2, 2008 10:20 am

    I use Sass to organize my stylesheets. Best of all, it allows for variables so I only have to define my colors once.

  18. 18

    Instead of using @imports, I use php to include groups into a master stylesheet. This prevents extra http-requests (and FOUC).

  19. 19

    I don’t agree with everything – but there are some good tips here. I will add some to my own

  20. 20

    Phil Thompson

    May 2, 2008 10:56 am

    There are some great tips here – almost all of which I follow.

    Sadly, in my experience, these kinds of things are just not kept upwhen other people in the team edit the CSS file.

  21. 21

    This article is amazing. This is what I will be using from here on out!

  22. 22

    Sandeep Sharma

    May 2, 2008 9:42 pm

    Great suggestion! Thank you.

  23. 23


    May 2, 2008 1:01 pm




  24. 24

    Simple but effective and powerful when it comes to cleaning up a rat’s nest of CSS. Thanks!

  25. 25

    I love this post,

  26. 26

    Excellent tips. Thank you!

  27. 27

    Andy Gongea

    May 2, 2008 3:44 pm

    Most of this tips are not OK in a production process. These tips are used in the development process, because on the final release you will want to reduce the file size.

  28. 28

    Fabulous timing of this post! I was just thinking this morning that I needed a more consistent way of writing my css. I am not a fan of the css libraries, so doing it myself is my favorite option.

    Thanks for this post!

  29. 29

    Jacob Grady

    May 2, 2008 7:46 pm

    I hand code everything so I tend to comment a lot in my PHP scripts. For CSS I tend to write a small .txt file that houses the layouts and other general notes. Basically a ‘read_me’ file in my CSS directory. That way the browser doesn’t have to load it but it’s there for development and maintenance.

    Also, I tend to order my CSS in the same fashion I program it. First I do positioning/float styles, followed by dimensions/margin/padding styles, then text styles. A kind of ‘work from the outside – in’ approach.

    Works for me anyway and that’s the most important thing for organizing anything you do!

  30. 30

    Mithun Sreedharan

    May 2, 2008 8:52 pm

    Good stuff here, good comments also. First time I feel comments are better than the post, aw! sorry, better than the code!
    Well, I’m a fan of alphabetizing CSS properties.

  31. 31

    Good ideas!
    You should share your ideas with the guys from the project CSSDoc:
    It’s an approach to comment CSS-documents the same way like you use for Java- or PHPdoc.

    In times of Web >= 2 CSS becomes more and more powerful and it seems that coding-wise it is still a real mess.
    Therefore I plead for a css-nationally coding guide/concept :-)

  32. 32

    Nout van Deijck - Blog

    May 3, 2008 1:10 am

    Thanks very much!
    I’m going to manage my stylesheets better now!

  33. 33

    Good article and comments,

    these thoughts are really needed, even an averagely maintained C++ project is more readable than a professional (x)html site’s html, css, php and javascript mash-up.

    good points, QT. i think that the whole html concept itself is the wrong way. all its incompatible extensions, confusing styling techniques and complex workarounds are a big mess IMO.

    all this could be much easier and less error-prone…

  34. 34

    1. It’s always good do divide the code, and import other css, this results in speed eventually
    2. It’s bad to define table of contents and to define colors withing the /* */ in CSS you end up with a css that will load TOMORROW (enourmous size) … Last time i cheeked the smashingmagazine css it had more then 50 kb and this is not good. You guys wrote a novel withing /* */ it’s always nice to keep it simple and perfect. Not everybody has super internet connections like we do.

    You guys should correct the article. If you are going to make a table of contents do it on paper but keep the css as tiny as simple as possible.

  35. 35


    May 3, 2008 7:29 am

    Thank you for this great article to improve my own css – style.


  36. 36

    Some tips are fine but mostly bad.

    1. Document your CSS structures/color schemes on a separate CSS file.
    2. Don’t use nested @import “” inside a CSS file. Slows down your loading speed.
    3. In Article it said uses one liner moderately? I don’t get it… many times you’ll have more than 3 attributes….your css file is going to be so hard to read

  37. 37

    If you are working in a team have a lot of comments is very helpful in development phase. Just make sure to remove them when in production. ;-)

  38. 38

    I’m a brand new Web Designer for a fairly big company and I’ve been giving the task to managing the whole design and css building. These article is great. Thank you so much.

  39. 39

    Isaac Castillo

    May 3, 2008 7:52 pm

    Great post guys!

  40. 40

    Fouad Masoud

    May 3, 2008 9:27 pm

    thx for the tips guys.


↑ Back to top