The Need of CSS Style Guides

October 15, 2019 • ☕️ 5 min read

Any programming languages lacking built-in namespaces will desperately need coding style guides and CSS is obviously one of them. CSS codes are extremely opinionated across teams and individuals, most companies maintain their own CSS style guides generated manually based on popular style guides with some modification.



A CSS style guide is a set of standards and rules on how to use and write CSS code in a consistent and maintainable way.

The Motivation

There isn’t much we can do to change how CSS works, but we can make changes to the way we author and structure it. The problem with CSS conventions is that they rely on developers to manually maintain them with a high degree of accuracy to be effective.

This problem is compounded as styles grow. Each developer needs to know more context in order to effectively style UI. That’s why you should just write good CSS is an insufficient response to how do we keep styles maintainable.

Even developers who write great CSS are challenged with an ever-growing problem; the problem with CSS isn’t CSS, it’s humans. We can only keep so much in our heads, and sharing that knowledge across teams, even teams who really care about consistent styling is really hard.

Every project needs some organization. Throwing every new style you create onto the end of a single file would make finding things more difficult and would be very confusing for anybody else working on the project.

How do you decide which elements should get the styling magic you wish to bestow upon it? How do you make it easy to understand how your site and your styles are organized?

You don’t need to maintain a custom CSS style guide on your own but you need to find one to follow, failing to do so will put you in a position of maintaining an ugly unmaintainable codebase sooner or later.

The Benefits

Following a CSS style guide can create a beautiful code base which will make any developer love working on a project. They enable a codebase to be flexible, easily scalable and very well documented for anyone to jump in and work on with other developers.

  • Keep stylesheets maintainable and scalable
  • Keep code transparent, sane, and readable
  • Set the standard for code quality in team
  • Give developer feeling of familiarity
  • Promote consistency across projects
  • Increase developer productivity

The Recipes

Ordering properties is just one choice you have to make that makes up a complete styling strategy. Naming is a part of it. Sectioning is a part of it. Commenting, indentation, overall file structure, etc. It all makes up a complete CSS style guide.

  • Coding format — spacing, characters width, indenting, whitespace, alignment
  • Commenting convention — what to be documented and removal in production using minification
  • Naming convention — following a CSS methodology like BEM or not
  • Coding rules — decisions about defining global styles, variables, mixins, functions, typography, unit usage
  • Reusable components — consideration of putting some common components to be used across products

The Options

Following style guides are opinionated, but they have been repeatedly tried, tested, stressed, refined, broken, reworked, and revisited over a number of years on projects of all sizes:

Design system is something bigger which includes CSS style guide inside, following design systems are well developed and maintained by companies: GitHub Design System, Carbon Design System, Lightning Design System

Other resources might help you build good custom style guide on CSS or Sass automatically or manually: Style Guide Boilerplate, Website Style Guide Resources, BigCommerce Sass Guidelines, Sass Guidelines, SMACSS

Anyone who has attempted to maintain a CSS style guide over a long period of time will attest that it is a very difficult process. This is bad because once your style guide falls out of sync with your applications it has entirely lost its purpose.

It’s best to have a living CSS style guide auto generated from codebase or just follow the one that is being well developed and maintained by community.

The Takeaways

CSS style guide aims at improving collaboration, code quality, and enabling supporting infrastructure. It contains methodologies, techniques, and tips that you and your team should follow.

You could generate a style guide automatically — kss, mdcss, stylemark, nucleus — or manually. Any method would work, as long as it does not take too much time.

Using style guide along with formating tools like Prettier or editorconfig that could help your team produce well-formatted code.

Each style guide has or should have the same goals — to improve consistency and usability. By standardizing your code, and by applying uniform design principles, you could create a unique cookbook that could help your team build the product more efficiently and consistently.