Check out CSS Wizardry for guidelines to write clear, maintainable CSS

CSS Wizardry offers guidelines for developers to write standardized, easy-to-maintain CSS code. Here are some of the highlights.

CSS Wizardry is a collection maintained by Harry Roberts, and located on the GitHub software development collaborative. It includes a compilation of CSS contributions, repositories, and public activity. Several popular CSS repositories include inuit.css, CSS-Guidelines, csswizardy-grids, and csswizardry.github.com, which is Harry�s website. And speaking of his website, CSS Wizardry includes the blog behind the code so to speak, where Harry writes about the topics of CSS and its scalability, architecture, maintenance and more. This piece will review the CSS-Guidelines repository, which is touted as a high-level guideline for writing manageable, maintainable CSS.

CSS-Guidelines

A set of notes, advice, and general guidelines, the CSS-Guidelines is a living document which as of this writing was updated 9 days previous, and is a �Star� favorite of some 2,483 GitHub users. The guidelines which are native English language are also translated into Russian, Chinese, and French. The guidelines are intended for large projects with long running timelines that also may include a large team of developers and is meant to assist groups with working in a unified fashion -- keeping stylesheets and code maintainable, transparent, readable, and scalable. The document covers syntax, formatting, documentation, CSS anatomy, approach, mindset, and manner to writing and architecting CSS code.

Contents

The guidelines are well documented throughout and include a table of contents, of sorts, starting with the Anatomy of a CSS Document, which covers the general statement then gets into the issue of One file versus many files, which I am sure has sparked many a debate among developers. It goes on to explain having a Table of contents for your CSS in addition to Section titles. Some of the other content sections within the guideline are:

• Source order
• Anatomy of rule sets
• Naming conventions
• Comments
• Writing CSS
• Building new components
• OOCSS
• Layout
• And more!

Highlights from the guidelines

• Harry recommends limiting stylesheets to a maximum of an 80 character width when possible; exceptions include gradient syntax, URLs, and comments. I am sure there could be some other exceptions depending on individual projects. The Table of contents at the top of stylesheets is one that I do not see often, but it would help especially with respect to large CSS files, and Section titles makes sense, I know most CSS will have some form of section titles such as: /*---- Parallax Scrolling Container Styles ----*/
• Source order is a good rule of thumb. Harry recommends a well ordered stylesheet where each section builds upon and inherits a sensible organization as each section cascades down the file. Naming conventions for the most part are recommended to use hyphen-delimited classes, e.g., .class-one, .class_one, or .classOne, but in some instances, it is necessary to use the BEM (Block, Element, and Modifier) notation. Comments should use a docBlock style; limit the character width to 80; document your code as much as possible to maintain explanations and transparency.
• Magic numbers are used because they just work for a specific scenario or situation, but in reality only fix a symptom and not the problem. It is better to use percentages; i.e., instead of .rightBox { margin-left: 40px; }for a right side bar that sits next to a top navigation, you might use .rightBox {margin-left: 10%; } so that no matter how wide the navigation is, it will always sit 10% to the right of the navigation.

The CSS Guidelines by Harry Roberts is a great starting point for getting your styles code into a standardized and well documented, manageable, and maintainable CSS.