Handling CSS naming conventions in SPFX

The new SharePoint Framework has a smart way to avoid conflicting CSS definitions. Therefore all style sheet classes will be post-fixed with a unique random string and converted to a JSON object. In your web part code, you can use the same class name as you used in your style sheets and the variable will be automatically replaced with the random class name string. So far the good parts of the SharePoint Framework.

In practice, this has some limitations and challenges.

CSS naming conventions

From a professional web development perspective, you don’t class names as you like. A significant benefit is when you use clear defined guidelines how you name your elements in the style sheets. The most common naming conventions are:

All those naming conventions have one thing in common. Those naming conventions make use of hyphens in class names. Office UI Fabric makes use of the SuitCSS naming convention which also defines hyphens for their class names.
Those naming conventions are widely used in web development but cause some challenges with the SharePoint Framework.

The problem

After the SharePoint Framework compiles your SASS style definition into CSS files, all class names will be post-fixed with and additional random string. The idea behind attaching a random string is that you get a set of unique class definitions scoped for your project. It makes sure that each class definition is only used once on a page and makes your web part safe of breaking and interfering with other web parts.

SASS to CSS compilation

In addition to the SASS to CSS compilation, the framework creates a javascript style object too. Instead of using the class names directly you can use this object, which replaces during compilation your property with the appropriate class name.

Style TypeScript Object

While the first property of this object is simply named card the 'card-headline' property is wrapped in single quotes. The problem here is that the second definition contains a hyphen.
This character is not allowed in variable names by the JavaScript language definition, but it can use when single quotes wrap the property.
The downside is that you cannot access this second property directly in the form of styles.card-headline.

The solution

The simple dot notation is not suitable to access the property, but JavaScript has an alternative way to access this property. A bracket notation allows access to the property.
So instead of style.card-headline the property needs to be accessed through style['card-headline'].
The problem now is that your web part is not type safe anymore because it is very challenging to evaluate all the bracket notations used in your web part. Also, you won’t get any warning in the editor if you rename a class or have properties that don’t exist anymore.

Type-Safe warning in SharePoint Framework console

The SharePoint Framework issues a simple warning in the console that gives the hint that camel-cased class names might be a better option for specific class names.
Renaming all the classes is a valid option but not a practical. If you already have a well-proven web development guidance in your company that uses one of the previously mentioned naming conventions you don’t like to set up exclusive guide for CSS naming conventions for web parts.

Practical Guide

In theory, you can mix the dot notation with the bracket notation when you add the style definitions to your web part code. From my point of view, you should be consistent what to use and mix both notations is not a good option. If the class names might contain hyphens, always use the bracket notation, but you will loose some of the type-safe benefits.
If you just use simple names always use the dot notation, because otherwise, your code becomes hard to read. If none of these options does work that well you can disable all this auto-postfixing SASS compilation.
In this case, you need to make sure that your style definitions are unique. The easiest way to accomplish this is to define a base class on the web part container.

Unique Class Definitions added to web part class

Then you can simply wrap all your CSS code with this class name.

Uniques Class names in SharePoint Framework CSS

The last option is not to use any CSS-specific code in the SharePoint framework at all. In my project, I always have a style guide that already has its clear styling rules, and naming conventions included. This style guide then acts as an external custom tailored framework for my clients. It is easy to deploy the style sheet used to the CDN and reference as an external resource.

The SharePoint framework web part then only contains the business logic and the components used for rendering. The style definition, in this case, will be utilised like a global design asset.
I like to know what your thoughts on this are so, please feel free to give me feedback.