How to Name CSS Variables

After using CSS custom properties (in short: CSS variables) for some years and being confronted with many different naming systems, I’ve found the following structure to work quite well for me:

--(prefix)-someLabel-cssProperty-variant

Name Components

Position 0: Prefix

A prefix is required in third party components like plugins or third party themes (use plugin or theme prefix), but usually not in custom projects, even if it uses third party components. In addition, I use a general developer prefix, whenever I add my own variables to a third party project, e.g. through a WordPress child theme.

When it comes to separated modules within a project, I try to make use of the cascade to scope my variables accordingly, instead of introducing a bunch of prefixes. This also makes it easier to move variables to the root level, if appropriate.

Position 1: Label

Apart from naming objects, I use ‚theme1‘, ‚theme2‘, ‚theme3‘ etc. for theme colors and the like, and I may replace the ‚theme‘-part with something else (e.g. the module name) in case I have different styles for different scopes. In addition, I will name client or brand specific colors ‚brand1‘, ‚brand2‘ etc.

Be pragmatic and chose your labels according to your project needs.

Abstract labels:

'theme1', 'theme2', 'theme3'
'brand1', 'brand2'

Rather concrete labels:

'red', 'blue', 'green'

Abstract groups of elements:

'contentBox', 'textBox', 'mediaBox'
'basicModal', 'fullWidthModal'

More (or less) HTML related elements:

'basicTable', 'shopTable', priceTable'
'basicButton', 'mainButton', 'smallButton'

Easily readable labels (no abbreviations), everything camel case.

Position 2: Property

Full CSS property name in camel case.

'background', 'backgroundColor'
'boxShadow'
'font', 'fontStyle', 'fontSize'
'lineHeight'
'filter'
'opacity'

Position 3: Variant

Can be described by an abstract three letter abbreviation:

'def' (default)
'acc' or 'ac1' (accentuated), 'ac2' (more accentuated) 'ac3' (very accentuated), 'ac0' (less accentuated)
'lt1' (light), 'lt2' (lighter)
'dk1' (dark), 'dk2' (darker)
'sh1' (shady), 'sh2' (shadier)
'lg1' (large), 'lg2' (larger), 'sm1' (small), 'sm2' (smaller)

Or something more concrete:

'odd', 'even'
'first', 'last'
'hover', 'focus', 'clicked'

For the default variant, I always use 'def' rather than omitting the variant part. I find it helps with clarity and quick search/replace-operations.

Examples

--body-background-def
--body-color-def
--contentBox-background-def
--contentBox-color-def
--contentBox-color-acc
--theme1-color-def
--theme2-color-def
--basicButton-borderRadius-def
--listItem-backgroundColor-odd
--textBox-opacity-ac2
--basicTable-boxShadow-def
--contentBox-marginBottom-last
--mainButton-backgroundImage-focus
--smallButton-backgroundSize-acc

Deprecating Variable Names

Changing variable names via search/replace-operations helps keeping the project clean, but it takes some time to do it carefully and check for possible errors. In order to maintain my flow, I like to have a place to deprecate variable names quickly.

Let’s say we have a file called setup.css to declare our currently used variables, and another file called deprecated.css for old variable names that should be replaced:

x) Add deprecated.css right after(!) setup.css to the project and copy your deprecated variables declarations over. Everything should still work as before.

x) In setup.css, replace the deprecated variable names with new ones, keeping the values.

x) In deprecated.css, map the old variable names to the new ones by replacing the values with the new variable names.

body {
--bc-table-def: var(--shopTable-backgroundColor-def);
--cl-table-def: var(--shopTable-color-def);
}

That’s all.