Naming System

Overview

Polaris uses a simple but robust Naming System called CMC*, that makes it easier to remember and work with, as well as avoid name conflicts with other open-source libraries.

* Component Modifier Child

Important Note!

If you understand Polaris Naming System, you will master the Polaris framework in no time.

Component

A component is a primary CSS class used for styling an HTML tag (or a set of HTML tags).

Syntax

component

The component could be a container for other components.

Here's an example:

<button class="btn">Submit</button>
<p class="text-center">This is a simple text!</p>

Both btn and text-center here are component classes.

Important Note!

In Polaris framework there are many components that are belong to a specific category, which sometimes referred to as a component class (a class of components).

For example, text-left, text-center, and text-right components are related to CSS text-align. Thus text-center is a multi-part component, and there is not a component named text.

Modifier

A modifier class is usually used to modify a component class.

Syntax

key-modifier

The key is either the component name or a shorthand of the component name.

The key and the modifier names are separated by single hyphen.

Here's an example:

<div class="row">                              	// Component (Container)
    <div class="col col-4">Column-1</div>	// Component & Modifier
    <div class="col col-8">Column-2</div>	// Component & Modifier
</div>

Child

A child class is used to style the component's child element.

Syntax

key--child

The key and the child names are separated by double hyphen.

Here's an example:

<div class="display-flex flex-row flex-wrap flex-fill">
    <header>Header</header>
    <main class="flex--grow-2 flex--basis-0 flex--order-2">Main</main>
    <nav class="flex--grow-1 flex--basis-0 flex--order-1">Nav</nav>
    <aside class="flex--grow-1 flex--basis-0 flex--order-3">Aside</aside>
    <footer>Footer</footer>
</div>

Notice that flex here is the key, which is a shorthand for display-flex component.

Templating

For templating you can extend CMC to control the component siblings, and parents.

Sibling

key_sibling

The key and the sibling are separated by single underscore.

Parent

key__parent

The key and the parent are separated by double underscore.

Here's an illustration for CMC templating:

<div class="key__parent">
    <div class="component key-modifier">
        <div class="key--child">
            ...
        </div>
    </div>
    <div class="key_sibling">
        ...
    </div>
</div>

Here's another illustration for CMC templating:

<div class="key__n">
    ...
    <div class="key__2">
        <div class="key__1">
            <div class="component key-1 key-2 ... key-n">
                <div class="key--1">
                    <div class="key--2">
                        ...
                        <div class="key--n">
                            ...
                        </div>
                        ...
                    </div>
                </div>
            </div>
        </div>
    </div>
    ...
</div>

You can use either numbers or meaningful names.

Variable and Optional

For categorizing Polaris classes in this document, we have used Variable and Optional syntaxes.

Variable

key-{var}

Here's an example:

text-{*}	// * {left, center, right}

text-{*} represents a component class consistent of: text-left, text-center, and text-right

Optional

key[-opt]

Here's an example:

color-{*}[-hover]	// * {Polaris Colors}

color-{*}[-hover] represents a component class of Polaris Colors with an optional hoverable modifier. For example: color-black and color-white-hover

Atomic & BEM

There are other naming systems used by some other frameworks.

Atomic

This naming system uses short names for all types of CSS classes.

Here's an illustration:

<div class="component modifier">
    <div class="child">
        ... 
    </div>
</div>

In Atomic system it is important to use unique names for each component.

As you may noticed this naming system looks so clean and brief.

To prevent name conflicts with other components, Atomic recommends nested CSS syntax:

.component-1 {...}
.component-1 .modifier {...}
.component-1 .child {...}
.component-2 {...}
.component-2 .modifier {...}
.component-2 .child {...}

This way different components can share same names for modifiers and children.

But what if we use something like this?

<div class="component-1 component-2 modifier">
    <div class="child">
        ... 
    </div>
</div>

Here's when name conflicts occur.

To prevent this, you have to always use unique names for all components, modifiers, and children classes, and you have to remember all your class names.

<div class="component-1 component-2 modifier-1">
    <div class="child-2">
        ... 
    </div>
</div>

Important Note!

Using Atomic system in real world projects, it is impossible to prevent name conflicts, especially when a team works together on a project. Therefore, it is not recommended to use it in such projects.

BEM

It is one of the best naming systems for CSS classes.

This system has divided every CSS class in three categories:

Block - Acts like a Polaris component.
Element - Acts like a Polaris child.
Modifier - Acts like a Polaris modifier.

Block

component

For simplicity, we have used the name component for block.

Element

component__child

For simplicity, we have used the name child for element.

In BEM element (child) and block (component) names are separated by double underscore.

Modifier

component--modifier

In BEM modifier and block (component) names are separated by double hyphen.

Here's an illustration:

<div class="component component--modifier">
    <div class="component__child">
        ... 
    </div>
</div>

BEM is a great way for naming CSS classes, with almost zero possibility for name conflicts, which makes it ideal for teams.

CMC vs Atomic & BEM

Each of the naming systems we mentioned, have their cons and pros. Depend on the project you use, each one of them can be an option.

It is recommended to use Atomic rarely, and only in very simple projects and demos.

For a real-world project, you need to use a more dynamic naming system like BEM or CMC. CMC is more dynamic. However, you should be a little careful to prevent name conflicts.

The possibility for name conflicts in CMC is very low, you only need to use unique component and keys names. But if you are using this system in a team, it is recommended to use the full component name for all the keys, this way there will be almost zero possibility for name conflicts.

Here's a comparison between CMC, BEM, and Atomic:

Name Conflicts: (BEM is the best, but CMC is also a great option)
- BEM: Absolutely zero. (With unique component names)
- CMC: Almost zero. (With unique component names and keys)
- Atomic: May be zero. (All component, modifier, and child classes must be unique)
Templating: (CMC is the best)
- CMC: Is ideal for templating.
- BEM: Is not specifically designed for templating. (Can be somehow extended)
- Atomic: Doesn't support templating.
Memorizing: (Both CMC and BEM are great)
- CMC: Is easy to memorize.
- BEM: Is easy to memorize.
- Atomic: For simple projects is easy to memorize.
Briefness: (Atomic is the briefest)
- Atomic: Uses the briefest syntax
- CMC: Uses name keys for make names cleaner.
- BEM: Uses full names.

Polaris & BEM

It is also possible to use BEM system in Polaris framework.

CSS Library

First open up the following configuration module:

src/scss/variables/config.scss

Then, modify the following variables as the following:

$mod: "--" !default;	// Modifier Separator
$chi: "__" !default;	// Child Separator

Finally, you need to somehow modify the following variables. Here's an example:

$sib: "_" !default; 	// Sibling Separator
$par: "---" !default;	// Parent Separator

JavaScript Library

First open up the configuration class:

src/ts/modules/Config.ts

Then, modify the following properties as the following:

public modSep: string = "--";	// Modifier Separator
public chiSep: string = "__";	// Child Separator

Finally, you need to somehow modify the following properties. Here's an example:

public sibSep: string = "_";	// Sibling Separator
public parSep: string = "---"; 	// Parent Separator

Custom Names

Polaris framework is 100% customizable. All the names can be modified easily.

CSS library:

First open up the following configuration modules:

src/scss/variables/config.scss
src/scss/variables/naming.scss

Then change the names to whatever you want.

JavaScript library:

First open up the configuration class:

src/ts/modules/Config.ts

Then change the names to whatever you want.

Notice! Use the same names for both CSS and JavaScript libraries.

Note!

It is not the best way to modify the Polaris framework. One reason can be the upcomming new releases which will override your changes, and you need to do it over again.

A much better way to modify the Polaris framework is explained in Polaris Layouts.

Datasets

In Polaris datasets refer to CSS data-... property. A special property which is used by the CSS & JavaScript libraries to perform specific tasks on some components.

For example, Polaris Animations use datasets:

<div class="animation" data-animation="fadeOut" data-duration="500ms" data-delay="500ms">
    ...
</div>

Note! Values in datasets follow JavaScript standard naming rules.