CSS Classes

Classes and related CSS should be identifiable in a theme when exploring the structure. To aid in that, we are using a namespaced BEM (Block, Element, Modifier) style of designating classes.

Class Names

Classes used on the forum will follow a defined structure.

.[namespace]-[component]__[element]--[modifier]

Block __ Element -- Modifier

.block {} // represents the higher level of an abstraction or component
.block__element {} // represents a descendent of .block that helps form .block as a whole
.block--modifier {} // represents a different state or version of .block

Analogy

In case you are having trouble figuring out whether something is an element or a modifier, here is a handy analogy using the same syntax (and also an example of how you can compose the two):

.person {}
.person__hand {}
.person--female {}
.person--female__hand {}
.person__hand--left {}

Namespacing

Note

Namespacing of elements allows us to assign classes to specific purposes - and providing clear meanings to their use.

o-: Signify that something is an Object, and that it may be used in any number of unrelated contexts to the one you can currently see it in. Making modifications to these types of class could potentially have knock-on effects in a lot of other unrelated places. Tread carefully.

c-: Signify that something is a Component. This is a concrete, implementation-specific piece of UI. All of the changes you make to its styles should be detectable in the context you are currently looking at. Modifying these styles should be safe and have no side effects.

u-: Signify that this class is a Utility class. It has a very specific role (often providing only one declaration) and should not be bound onto or changed. It can be reused and is not tied to any specific piece of UI. You will probably recognise this namespace from libraries and methodologies like SUIT.

t-: Signify that a class is responsible for adding a Theme to a view. It lets us know that UI Components’ current cosmetic appearance may be due to the presence of a component theme. A common example would be a light and dark mode themes.

s-: Signify that a class creates a new styling context or Scope. Similar to a Theme, but not necessarily cosmetic, these should be used sparingly—they can be open to abuse and lead to poor CSS if not used wisely.

is-, has-: Signify that the piece of UI in question is currently styled a certain way because of a state or condition. This stateful namespace tells us that the DOM currently has a temporary, optional, or short-lived style applied to it due to a certain state being invoked.

Important

Do not assign custom styles to the classes as namespaced below - they are intended for non-CSS use.

_: Signify that this class is the worst of the worst—a shortcut! Sometimes, although incredibly rarely, we need to add a class in our markup in order to force something to work. If we do this, we need to let others know that this class is less than ideal, and hopefully temporary (i.e. do not bind onto this).

js-: Signify that this piece of the DOM has some behaviour acting upon it, and that JavaScript binds onto it to provide that behaviour. If you are not a developer working with JavaScript, leave these well alone.

qa-: Signify that a QA or Test Engineering team is running an automated UI test which needs to find or bind onto these parts of the DOM. Like the JavaScript namespace, this basically just reserves hooks in the DOM for non-CSS purposes.

Code Standards

We try to follow a set guideline for writing our CSS. You can read more about our standards on our GitHub.