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 csswizardy-grids, and 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.



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.


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
  • 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

By Ryan Boudreaux

Ryan has performed in a broad range of technology support roles for electric-generation utilities, including nuclear power plants, and for the telecommunications industry. He has worked in web development for the restaurant industry and the Federal g...