SCUM: CSS naming for Design Systems.

This document describes an approach to naming css elements for a design system. It is similar to BEM, but more concise and readable. It works well for Design Systems and Pattern Libraries that are component driven (for example based on Atomic or Predix standards). It is also pretty interoperable in mixed environments, where you may be migrating from one pattern to another, or heaven forbid, need to have two at once.

The naming system is used for classNames that are applied to DOM elements, and also applies to a logical groupings of variables and mixins that are defined in the system.

tl;dr

.sysContent-unit.modifier

System

This is your personal namespace. Choose a few letters that uniquely identify your company or project. 1, 2, 3, 4 characters is all you need. ui is a bad choice. If you are developing a company wide design system, name it after the company. g or goog would be a good choice for Google. If your design system is specific to a project and internal to a company, name it after the project. You’ll be typing this a lot, so short is sweet.

Content

This is your basic building block. It might be a component that is applied to DOM nodes as class names (like a button or dialog) or it might be a set of less variables or mixins like a color palette or typographical set.

Each content group is given a unique name in the system. We prefix the content with the system name and use camelCase for the whole thing. This is the content identifier. If it’s a component, the root DOM element of the component gets this identifer as a class.

@prePalette
.preDialog

Unit

Units are subsections of content. They are semantically tied to the content and can not be separated.

To name them, take the content identifer as a prefix and separate with a hyphen. Units are camelCased if they contain multiple words and sub-sub sections are joined with more hyphens.

@prePalette-red-500
.preText-large()
.preDialog-title
.preLeftPanelLayout-leftPanel-title

Sometimes you’ll need to target pseudo elements in css. Just use the standard :: syntax, that’s fine.

preInput-field::placeholder

Modifier

Modifiers are flags on content or units that change the behaviour or appearance. They are always given a single simple name with no capital letters. They are usually defined on content, but may be applied to units also. Modifiers do not need to be unique, since they must be joined to content or units and must not be given any styling outside of the parent context. Multiple modifiers are allowed.

preButton.disabled
preButton.primary.disabled
preInput.readonly.required

.disabled { opacity: 0.7; } // bad - must be associated .preButton.disabled { opacity: 0.7; } // good

Modifiers only really make sense in the context of classNames since they require the css class combining behaviour. If you want modifier behaviour on content that is not a component, use a unit naming style instead.

.prePalette-lighten(color) { ... }