anarchy.website Toggle Dark Mode

pheneco Naming Guide

By Una J. Ada, September 05, 2016

Purpose

This document is written to clearly describe consistent rules for naming CSS selectors across all Phene.co projects. Such consistency is necessary to allow any person working on one project to easily be able to pick up on another project without the requirement of learning new standards for selectors. This is merely a styleguide and not a rulebook, modifications can be made per project and should be noted within the appropriate documentation. Do not be afraid to break these rules if you truly believe it is necessary.

Inspiration and References

As with the CSS Guide, a lot of this section is inspired by 18F’s Front End Guide which describes a modified version of BEM for naming. The naming scheme here, however, is styled more similarly to SMACSS, but retains a structure much akin to BEM.

Methodology

The base concept and origin of the name in BEM is to format selectors in the order of Block Element Modifier, wherein a block is “a functionally independent page component that can be reused”, an element is “a composite part of a block that can’t be used separately from it”, and a modifier is “an entity that defines the appearance, state, or behavior of a block or element”. As an alternative to blocks, this guide will describe a Model-Implementation system. Where blocks would simply state that an element is a block of type .post, this system would go further and say that an element is a card that takes the form of a post, e.g. .card.post. This could be effectively described as a Model-Implementation Element Modifier (MIEM) naming scheme.

Models

The model is the most basic component of what defines an element. It is, in essence, the form that the element takes. This is in part inspired by Google’s Material Design in which there are a relatively few categories for a containing material to fall under:

To expand on this, there is also a list of models (which are referred to as components) starting with Bottom Navigation in said docs. Guidelines for models:

Implementations

An implementation of a model is an instance of a component that could be categorized as said model. Implementations are semantically close to the blocks defined in BEM. Guidelines for implementations:

Some good and bad examples of the Model-Implementation system written in Pug (fka Jade):

// Good
div.card.post
	h3.heading.post-header This is a header.
	p.post-text This is some copy.

// Bad, describes appearance
div.card.red-box

// Good, nesting
div.drawer.header
	div.heading.header-heading Welcome to my site!
	form.search-form

// Bad, uses ID to define implementation
div.drawer#heading
	div.heading.header-heading Welcome!