CSS Coding Guidelines, annotated version - ΩJr. Coding Guidelines

This information lives on a webpage hosted at the following web address: 'https://www.omegajunior.net/code/guidelines/'.

CSS Coding Guidelines are intended to make it easier to read our work, both for colleagues when we are away, and for ourselves in a year's time. The Guidelines also answer newbie questions and provide best practices, in order to reduce the learning curve.

You are reading the annotated version. It contains explanations. For a rule and example overview, see the summary instead.

Suggestions are welcome.

A word from a sponsor:


Know your CSS
CSS basics, from the Web Standards Curriculum.


Avoid depending on CSS for critical functionality
Hackers can easily change or turn off or change your CSS. You should not allow that to lead to a corruption of critical data. If something critical should be invisible, then keep it out of the data you send to the client. When data comes back from the user, or when the user starts up instructions that lead to critical changes, the software developer should always double-check it by a secondary, tamper-resistant method.


Get along with clients on all kinds of devices


Like so:
/* Samples taken from Zjramble5, used with permission */
body {
max-width: 600pt;
margin-left: auto;
margin-right: auto;
}
button {
font-size: 14pt;
height: 28pt;
font-weight: bold;
margin: 0;
padding: 0pt 4pt;
width: auto;
min-width: 49pt;
text-align: center;
cursor: pointer;
-webkit-tap-highlight-color: rgba(4,96,179,0.3);
-webkit-appearance: none;
color: #fff;
background-color: #000;
background-image: url(myBadlyShapedLowResButtonImage.png);
background-image: -ms-linear-gradient( rgb(255,255,255),
rgba(255,255,255,0));
background-image: -moz-linear-gradient( rgb(255,255,255),
rgba(255,255,255,0));
background-image: -o-linear-gradient( rgb(255,255,255),
rgba(255,255,255,0));
background-image: -webkit-gradient(linear, 0% 0%, 0% 100%,
from(rgb(255,255,255)),
to(rgba(255,255,255,0)));
background-image: linear-gradient( rgb(255,255,255),
rgba(255,255,255,0));
-moz-text-shadow: 0pt -1pt 1pt #111;
-ms-text-shadow: 0pt -1pt 1pt #111;
-o-text-shadow: 0pt -1pt 1pt #111;
-webkit-text-shadow: 0pt -1pt 1pt #111;
text-shadow: 0pt -1pt 1pt #111;
}



Get along with CMS implementors



Adding CSS to your web pages
Preferably, you put CSS rules in their own file, using the .css extension: "myStyle.css?versionNumber". Combine various CSS files into a single one and minify the result. You can then add a reference to that file to your web page using the HtmlLinkElement. Put that tag in the page's HtmlHeadElement unless you have compelling reasons not to (and if so, do document those). Like so:
<link rel="stylesheet" title="myStyle" media="all" type="text/css" href="myStyle.css?20111020T1616" />

If you find yourself needing to add CSS material into the web page directly, be nice to the HTML parser and let it know that it can skip the contents of your HtmlStyleElement. We do that, compliant to the W3C-recommendation, by enclosing the CSS in a CDATA section. Like so:
<style type="text/css" id="myStyle">/* <![CDATA[ */
body{
background-color: #fff;
color: #000;
}
/* ]]> */</style>


Why a CDATA section?
It tells the HTML parser to skip its contents.

Why the multiline instead of single-line comments?
The comments are needed because the CSS parser breaks on the CDATA tags. Single-line comments do not work in CSS. Besides, multiline comments work in Javascript as well, meaning you have to remember fewer guidelines.


On version numbers in file names
For download speed, web masters tend to cache as much as possible, as long as possible. If your file name doesn't change, some systems fail to recognise that the file's content changed. The easiest way to fix that? Add a version number. You can use a native timestamp from your programming language, and for hand-coding you can use a universal date-time format, like so:
my-style.css?20111017T1530


Start big, end small
Blatantly copied from WNAS CSS Coding Conventions: start defining the largest elements, and work your way towards more specificity. At the top of your CSS we should find html and body, and as we read our way down, the elements and selectors should become smaller and more specific. This puts your CSS in the same cascade order as the HTML document.

Wrong:
a{}
li{}
ul{}
p{}
body{}
html{}


Better:
html{}
body{}
div{}
p{}
ul{}
li{}
a{}



On tables
Quite a bit of discussion has been going on about the use of tables in HTML, and whether or not tables can (and should) be displayed using CSS alone. Here's our rule of thumb: use tables for tabular data.

It is likely the HTML developer will wind up using non-tabular elements for non-tabular formatting. We prefer the use of semantically relevant elements, like article, aside, header, footer, hgroup, menu, and structurally relevant CSS properties like column-width, but we have to consider that some browser versions may never support those.


Avoid procedural rules where declared rules work
Sometimes we want to use Javascript (libraries) to set CSS or create animations. From experience we fathom that javascripted procedures take more time than native ones. Thus if you can use a CSS rule declaration instead of a scripted procedure, do so. (Do take ease of development into consideration, and talk to the Javascript developers.)

In the same line of thinking: if you must use Javascript to set CSS, do so by adding or removing a CSS class, rather than each property individually (or the whole CSS rule for that element at once). That allows the browser to prepare its rendering, and thus provide a snappier visual response.


Use short-hand notation where possible
Short-hand notation diminishes the chance of scattered rules. Bonus: short-hand is easier to understand, because the brain can take all that information at once. (Note that this guideline doesn't discuss variable and method naming.)

Example of full notation:
.myBlock { background-color: transparent; background-image: url(myImage.png); background-attachment: scroll; background-repeat: no-repeat; background-position: center center; }

Example of short-hand notation:
.myBlock { background: transparent url(myImage.png) scroll no-repeat center center; }

However, when setting just one property, using short-hand is wrong, because it will overrule the other implied properties.


Remember a background colour
Browsers like Microsoft Internet Explorer do not necessarily take white as the page's background colour. Instead, they take whatever background colour the computer's user has set. That could be black, for people with hindered eye-sight. They could have set a white text colour. Thus, your CSS must always define both a background colour and a foreground colour for texts. The background colour is one of the most-forgotten settings, leading to black text (developer choice) on black backgrounds (visitor choice), making a web site utterly unusable. What a visitor can't see, doesn't exist. Help the visitor: provide a background colour.

Wrong:
body{
font-size: medium;
padding: 8pt;
}
p{
padding: 8pt;
margin: 8pt 0pt 16pt;
color: #000;
}
a{ color: blue; }


Better:
body{
font-size: medium;
padding: 8pt;
background-color: white;
}
p{
padding: 8pt;
margin: 8pt 0pt 16pt;
color: #000;
}
a{
color: blue;
background-color: white;
}


Even better:
body{
font-size: medium;
padding: 8pt;
color: #000;
background-color: white;
}
p{
padding: 8pt;
margin: 8pt 0pt 16pt;
}
a{
color: blue;
background-color: white;
}



Remember contrast
You may think: the visual designer defined the contrast levels, so why should I have to look out for this? Well, that's because the visual designer may have forgotten, or the visual's gamma changed during the transfer from one OS to the next, leading to less contrast than intended. Since you are the one who changes the visual design into reality, it is your job to make sure that your creation can be seen and read. Too low a contrast on texts will lead to visitors leaving. If you spot this flaw, contact the designer and get it corrected.
Colour Contrast Check


Put rule properties together that make sense together
Some guidelines impose an alphabetical sorting order, adding an exception for groups of things that make sense to be grouped (like dimensions). We seek to remove that exception by making it the rule: group stuff together as it makes sense to do so, and be consistent about it. Whether some selectors and properties make sense together, depends on the web page, so it will differ per project.

Wrong:
p.error{
color: #111;
border: none;
text-decoration: underline;
padding: 8pt;
background-color: #ecc;
font-style: italic;
}


Better:
p.error{
color: #111;
background-color: #ecc;
font-style: italic;
text-decoration: underline;
padding: 8pt;
border: none;
}



On whitespace and block style for selectors and properties


/* no comparison needed */
fieldset {
background-color: #ddd;
color: #000;
border: 1pt solid black;
border-radius: 5pt;
margin: 8pt;
padding: 8pt;
}


Table-like whitespace and alphabetical arrangements are said to provide a cleaner look. Unfortunately, alphabetical arrangements only make a logical sense, not a semantical one. And CSS properties aren't tabular data: you aren't going to be doing much subtraction and addition, apart from maybe sizes, paddings, and margins. If the data isn't tabular in comprehension, don't make it look tabular either, otherwise you confuse your coworkers.

If you must make your CSS properties easy to compare, you can use whitespace to make your code look like a spreadsheet. Like this:

/* comparison needed */
fieldset#gameStart { background-color: #ffc; }
fieldset#gameActive { background-color: #9d9; }
fieldset#gameOver { background-color: #600; color: #fff; }



Provide semantically relevant class names and element IDs
Name classes and elements after what they are used for in the web page. Be as specific as needed. "#box15 .blue2" provides little semantic information (even if the page shows differently-coloured Tupperware...). What proves semantically relevant, depends on the type of page.


Use camel casing for class names and element IDs
Normally we would add a space to signify the start of new words. Since CSS class names and element IDs must not contain spaces, we advise camel-casing: concatenate all the words in a class name and start each word with a capital letter, except for the very first one, which must start with a lower case letter. Avoid underscores, hyphens, and other marks. These are camel-cased, and on some pages also semantically relevant class names:
leftSidebarBlock
footerServiceLink
newsArticleButton

Why camel casing?
Because we advise the same in our guidelines for Javascript, XSLT, C#, and PHP. Fewer exceptions leads to fewer mistakes.


Use consistent colour value casing
Some guidelines will tell you to use upper case for hexadecimal colour values. Since all browsers we tested don't care, this guideline also doesn't care, as long as you stick with the choice you made.


Prepend your CSS files with a JavaDoc-like comment block
Preferably one that holds useful information, e.g.:
/**
* myStyle.css
* @use For template: thisPageType
* @author Our company <us@here.now>
*/

The information you include should be relevant and helpful for your coworkers. It should identify how and where this file is used, and who to contact in case of questions. We can imagine that some stylesheets are used across multiple templates in a site, whereas others apply to only a single page, regardless of template.


Use a CSS validator
It will find grammatical and some usability errors. It will not find functional errors. Use common sense and browser-comparison services for functional testing.

Need problem solving?

Talk to me. Let's meet for coffee or over lunch. Mail me at “code at omegajunior dot net”.

Clicky Analytics