Style Guide & Coding Standards for CSS
last revised March 19, 2011
effective starting March 19, 2011
Contents
Introduction
Overview
File Naming Conventions
Blocks
Comments
Classes
Images
Sample File
Introduction
This document describes coding standards for cascading style sheets (CSS) files developed at Cliffson Solutions, LLC. Unless superseded by client requirements, these standards apply to all CSS files developed by employees and subcontractors of this company for both internal use and client projects.
The purpose of these standards is to bring consistency to the structure of CSS definitions, including formatting and naming conventions. CSS, like HTML, allows a fair amount of flexibility in its formatting. This flexibility means only a relatively few, simple grammar rules are required, but if some guidelines and layout conventions are not applied as the files are constructed, the code can become very difficult to read and maintain.
Some would argue that using Web page design and management tools eliminates the need for interaction with raw CSS code. However, our experience is that these tools will inevitably reach their limits in desired effects or introduce odd behaviors that must be remedied by hand-editing. The unfortunate truth is that most of these tools also generate very poorly structured code, which make working with the raw CSS even more difficult than it needs to be.
Historically, browsers are remarkably lax and wildly inconsistent in their interpretation of HTML tags, HTML and CSS standards, even adding support for their own unique codes and capabilities. This situation has improved in recent years, but many modern browsers still support old conventions and quirks for the sake of backwards compatibility — at the cost of rendering speeds and inconsistencies in displayed pages.
Our goal is to use tag conventions known to work with the widest variety of modern browsers following W3 standards. We do not spend a great deal of time accommodating the quirks of browsers that insist on flouting established standards.
Many clients only care if the pages appear in their favorite browswer correctly, not how consistently the pages are rendered by other browsers or how the underlying code is formatted. However, the practical consideration is that well-formatted and well-organized code is considerably easier to maintain and enhance, saving both the client and developers time and money in the long run.
Overview
We readily acknowledge that many of the conventions described here are strictly preferences and that such conventions can incite passions on par with the wildest religious and political debates. However, these guidelines have been developed based on years of building HTML pages and noting what works well and what does not. In some cases these may result in a bit more typing, but any programmer worth his/her salt will 1) already be a decent typist, and 2) realizes clear coding can save at least an order of magnitude in time quickly locating and tweaking class blocks.
We use curly brackets and block-level indenting of two spaces for all class definitions. Indenting tag blocks by two spaces is sufficient to make the blocks readily visible without using an inordinate amount of horizontal real estate. All code is written assuming a 80-column display. See the section Blocks below for more details.
We also use specific naming conventions for classes, based on their intended purpose. Any reasonably large Web site will include a large number of classes, and some rules in naming those classes inherently helps organize the CSS file.
All styles are associated with classes, not IDs. We use IDs strictly for DOM manipulation (as in Javascript functions), never for style definitions. This convention derives from the fact that IDs must be unique within the page, but classes may be referenced by as many page elements as is appropriate. Defining a style in terms of an ID that can only be used once is not particularly flexible or efficient. See the sections Classes below for more details.
This document must be considered in conjunction with Style Guide and Coding Standards for HTML. In particular, that document discusses how styles are defined as local in-line code when the use of separate CSS files is not justified (which is rarely).
Use of &nbps; tags to control page layout should be extremely limited. Frames are never used. Instead, layouts should be controlled by using <div> blocks and adjusting margin and padding settings in the corresponding CSS classes.
Careful attention should be paid to background and text color choices. All pages should be reviewed on multiple computers using several browsers (Firefox, IE 8 or later, and Safari at minimum) to make sure color selections and page layouts are working as expected. Blinking text is not allowed, and the use of automatically running animations and flash slideshows should be minimized to avoid overwhelming visitors with pages that are unnecessarily busy.
Note that some styles may be defined as subclasses, particularly for fonts used in content boxes — this allows for limited scope of visibility while using shorter class names. Unfortunately, some properties (such as background colors) are not inherited into subclasses consistently among different browsers, so the usefulness of multi-level subclasses may be limited. Redundancy in defined style properties may be necessary to ensure that all browsers render pages as intended.
File Naming Conventions
In general, the names of Web page files, including CSS files, are all lowercase. This differentiates them from directories, which always start with capital letters. Underscores may be used to make names more readable. Spaces and dashes are not used in either file or directory names.
CSS files are named according to the site or application they support, with .css extensions. Site-wide CSS files are typically located under the directory /Styles in the site's document root (home directory). Application-specific CSS files are typically located in the directory containing the application and share the same base file names which uniquely identifies the applications.
Examples:
/Styles/cliffson.css [site-wide CSS for Cliffson Solutions, LLC]
/Utils/regis.css [application-specific CSS for application
comprised of script files named regis_*.php
or static files named regis_*.html]
Note that application-specific script and HTML files typically reference the site-wide CSS to ensure a common look-and-feel, with the application's local CSS file extending and overriding site class definitions as appropriate.
Blocks
All CSS blocks are indented by two spaces per level. Blocks are defined as one or more lines of text which comprise a class definition. All such blocks are further delimeted by a pair of curly brackets, both of which are placed on lines by themselves.
Example:
.box_logo
{
color: #cc00ff;
text-weight: bold;
}
This indenting style is consistent with those used at Cliffson Solutions for source code (e.g., Javascript, PHP). It also makes finding discrete class definitions much easier. Style attributes are placed on individual lines, rather than the common and lamentable practice of running everything together on a single line.
Tabs are never used for indenting, as they do not always render consistently across different terminal software. Editors which handle indents as an optimal mix of tabs (assuming tabs are equivalent to eight characters) and spaces must have this feature configured to use spaces only or this feature must be disabled.
Comments
We define three types of comments: headers at the top of all CSS files, headers that separate major types of classes, and comments contained in individual class definitions.
File Headers:
Every CSS file must contain a header that specifies the name of the file, its intended use, assumptions regarding screen resolutions and target browsers, and revision documentation. The file header is delimited by normal comment characters /* ... */. A solid line of asterisks is used to clearly set the header apart from the rest of the file.
Example:
/*****************************************************************************/
/* Cliffson/Style/cliffson.css */
/* */
/* main CSS definitions for all Cliffson Solutions Web pages */
/* */
/* note that display resolutions are assumed to be 1024 horizontal or more; */
/* max width in many elements are set here 1020px to avoid triggering a */
/* horizontal scrollbar when a vertical scrollbar is displayed; lower */
/* resolutions will work but will always invoke a horizontal scrollbar */
/* */
/* these settings have been verified to work in Firefox 3.x, Safari, and */
/* IE >= 7; absolutely no attempt is made to support IE 6, which even */
/* Microsoft has declared dead */
/* */
/* Written 12/6/2010, L.Pritchett */
/* Revised 3/17/2011, L.Pritchett */
/*****************************************************************************/
All statements which are longer than 80 characters after indenting must be manually wrapped to fit in an 80-column display. Breaks in such lines should be made where convenient (e.g., at commas and spaces between words or between tag components). Continuation lines should always be indented two spaces until the entire logical line is complete.
Section Headers:
Section headers are used to delineate related blocks of information. For example, classes for content containers should be grouped together and separated from font classes by section headers. To make these easily visible, two lines of dashes are used between /* ... */ comment markers to extend across the page, with a description of the block contained between the two.
Example:
/*---------------------------------------------------------------------------*/
/* content boxes */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* navigation tabs */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* fonts */
/*---------------------------------------------------------------------------*/
Class Comments:
In most cases, a short description of each class and how it is to be used is included immediately after the opening curly bracket of the class definition. Any dependencies or unusual behavior, particularly accommodations for specific browser peculiarities, should be noted here as well.
Example:
.box_seal_ssl
{
/* container for SSL cert seal; assume is enclosed in box_seals */
/* this is floated right so it still looks okay if the other */
/* seals are not displayed */
padding: 8px 0px 0px 0px;
width: 95px;
float: right;
align: center;
}
Classes
In additional to global (body) style settings, individual classes should be defined and named by their intended purpose. Note that this is different than naming them by their attributes. For example, rather than defining a class called font_red, we instead create a class called font_alert. This allows much more flexibility if the background color were to change in the future and red is no longer an appropriate color to stand out well.
Similarly, classes that define content boxes are not normally defined by their location on the screen. For example, box_nav to contain navigation buttons or tabs is position-agnostic. Compare this to box_top_nav, which although is descriptive, requires major editing should the navigation box be moved to the left side.
However, some classes, particularly those that define auto-sized border images, must by necessity specify their specific orientations to have meaningful and usable names. A class named border_line_top is inherently more self-descriptive than border3.
Class names are named using lowercase letters and underscores as needed for readability. Related classes are grouped by their functions, as designated by common class name prefixes. Some common prefixes are:
.box_ [content boxes or containers]
.tab_ [navigation tabs, such as small floated divs]
.border_ [graphical border elements]
.bttn_ [button input elements]
.font_ [font styles]
Examples:
.box_banner
.box_copyright
.box_content
.box_footer
.box_search
.tab_normal
.tab_selected
.tab_disabled
.border_corner_upper_left
.border_line_upper
.border_corner_upper_right
.font_error
.font_alert
All attribute lines consist of an attribute name, followed by a colon and one space, followed by the value or values, and ending with a semicolon. Only one attribute is defined per line.
Example:
.font_norm
{
font-family: Arial, Helvetica, sans-serif;
font-size: 16px;
line-height: 1.2em;
color: #000000;
background-color: #edeff3;
}
Images
Classes that define content boxes or containers may include background graphics using the background-image attribute. This is commonly used for images that comprise borders or other page decorations. However, some browsers do not print background images, so they should be used only where the image is not an important component of the page. For example, business logos should be included as standard in-line images (using <img ... /> tags), not as CSS background images.
Where background images are used, the graphic files should be in PNG or JPEG formats (with file name extensions of .png and .jpeg/.jpg, respectively). Generally file sizes should be no larger than 40KB for reasonable download performance, and resolutions should be adjusted to 75 dpi. Tiling should be used where appropriate for repeatable background patterns to reduce the size of the base graphics file.
Example:
.border_line_top
{
background-image: url(/Graphics/cliffson_border_top_side.png);
background-repeat: repeat-x;
height: 16px;
width: 922px;
float: left;
}
If the page is delivered over a secure (https://) connection, all included graphics also must be delivered from https sources. Mixed references to to secure and non-secure resources will cause most modern browsers to complain. The lock icon on the browser must be completely closed to indicate all elements of the page are fully secured.
Sample File
The following is an example of a typical CSS file demonstrating all major expected conventions for CSS files developed at Cliffson Solutions, LLC.
/*****************************************************************************/
/* Cliffson/Style/cliffson.css */
/* */
/* main CSS definitions for all Cliffson Solutions Web pages */
/* */
/* note that display resolutions are assumed to be 1024 horizontal or more; */
/* max width in many elements are set here 1020px to avoid triggering a */
/* horizontal scrollbar when a vertical scrollbar is displayed; lower */
/* resolutions will work but will always invoke a horizontal scrollbar */
/* */
/* these settings have been verified to work in Firefox 3.x, Safari, and */
/* IE >= 7; absolutely no attempt is made to support IE 6, which even */
/* Microsoft has declared dead */
/* */
/* Written 12/6/2010, L.Pritchett */
/* Revised 3/19/2011, L.Pritchett */
/*****************************************************************************/
/*---------------------------------------------------------------------------*/
/* global and body settings */
/*---------------------------------------------------------------------------*/
body
{
/* force default margins on page */
margin: 10px 0px 0px 0px;
/* force into scrollbar mode at resolutions less than 1020 horiz px */
/* most of the time this isn't necessary, but it also doesn't hurt */
min-width: 1020px;
font-family: Arial, Helvetica, sans-serif;
font-size: 16px;
line-height: 1.2em;
color: #000000;
background-color: #edeff3;
}
a
{
color: 003366;
text-decoration: none;
}
a:hover
{
color: #008800;
text-decoration: none;
}
img
{
/* hide display of border around linked graphics */
border-style: none;
}
/*---------------------------------------------------------------------------*/
/* main body boxes */
/*---------------------------------------------------------------------------*/
.box_page
{
/* define box for entire page; this sets the minimum width and on higher */
/* resolutions, automatically centers the page on the screen */
width: 1020px;
margin: auto;
}
.box_body
{
/* container for banner, nav, and content */
width: 100%;
height: 750px;
}
/*---------------------------------------------------------------------------*/
/* content boxes */
/*---------------------------------------------------------------------------*/
.box_content_wrapper
{
/* wrapper for banner, main content, and footer */
float: left;
width: 988px;
height: auto;
vertical-align: top;
}
.box_banner
{
/* box for banner information */
/* use a negative top margin to move the box into the space */
/* otherwise reserved by the left upper corner graphic */
margin: -35px 0px 0px 0px;
background-image: url('/Graphics/cliffson_banner_bg.jpg');
background-repeat: no-repeat;
width: 988px;
height: 148px;
/* this is required to accommodate floating sub-boxes; if this is */
/* not in place, this container will not encompass its children, */
/* even if the div's are correctly nested in the Web page */
overflow: hidden;
}
.box_banner_logo
{
margin: 15px 0px 0px 20px;
width: 300px;
float: left;
}
.box_content
{
/* box for the main content of the page */
padding: 20px 10px 0px 20px;
width: 800px;
height: 585px;
float: left;
line-height: 1.4em;
}
.box_footer
{
/* the footer is displayed as a negative offset relative to the lower */
/* border, rather than just stuck on the end of box_content; this */
/* guarantees the footer will be at the bottom of the page, */
/* regardless of the size of box_content; overall height is driven */
/* by credit card and ssl cert seals */
margin: -100px 0px 0px 15px;
float: left;
width: 985px;
}
/*---------------------------------------------------------------------------*/
/* navigation tabs */
/*---------------------------------------------------------------------------*/
.tab_normal
{
margin: 0px 0px 0px -2px;
padding: 6px 0px 0px 0px;
width: 130px;
height: 16px;
float: left;
border: 2px solid #579ff5;
font-family: Arial, Helvetica, sans-serif;
font-size: 12px;
line-height: 1em;
text-align: center;
}
.tab_normal a
{
color: #ffffff;
text-decoration: none;
}
.tab_normal a:hover
{
color: #00ff00;
text-decoration: none;
}
.tab_selected
{
margin: 0px 0px 0px -2px;
padding: 3px 0px 0px 0px;
width: 130px;
height: 16px;
float: left;
border: 4px ridge #357ee3;
font-family: Arial, Helvetica, sans-serif;
font-size: 12px;
color: #ffffff;
font-weight: bold;
background-color: #357ee3;
line-height: 1em;
text-align: center;
}
/*---------------------------------------------------------------------------*/
/* fonts */
/*---------------------------------------------------------------------------*/
.font_reqd
{
color: #cc0000;
}
© 2010 - 2024,
Cliffson Solutions, LLC