Skip to main content

Naming Conventions

Particle provides two types of CSS classes: utility classes and component classes.

Utility Classes​

Utility classes use a double hyphen to separate the property or styling concern from the value or the enum the utility class applies. The left side references the property/concern and the right side references the value/enum. Some examples:

.shadow--xl {
  box-shadow: var(--shadow--xl);
}

.margin-t--4: {
  margin-top: 4em;
}

.rounded-right--small {
  border-top-right-radius: var(--radius--small);
  border-bottom-right-radius: var(--radius--small);
}

.overflow--hidden {
  overflow: hidden;
}

CSS Variables​

CSS variables for global style properties follow the same convention. Some examples:

--color--dscout: ...;
--font-size--l: ...;
--radius--m: ...;

Component Classes​

Component classes follow the BEM convention of defining blocks, elements, and modifiers and using standardized punctuation to separate them. Particle's convention adds capitalization to more clearly distinguish component classes from utility classes.

In BEM lingo, the component is the "block", elements rendered by the component that have special styling concerns are "elements," and states/variants are "modifiers." Modifiers are always lowercase, while blocks and elements are uppercase. Some examples

.Container { ... }
.Container__Inner { ... }
.Container--editing { ... }
.Container__Header--editing { ... }

Multi-word names should use a single hypen:

.Speech-Bubble__Tail: { ... }

CSS Variables​

CSS variables for themeable components follow the same pattern but append the property/styling concern after ____ (four underscores) to clearly separate it from the blocks/elements/modifiers. Some examples:

--Radio____radius: ...;
--Radio--unchecked____bg-color: ...;

--Toggle__Switch____height: ...;
--Toggle--checked__Switch____shadow: ...;