A Simple CSS custom properties naming convention

index.pug

h1 A simple CSS Custom properties naming convention
p.large Discussed in detail in my article on medium.com.
p
  a.button View on Medium
<script src="https://gist.github.com/vviikk/fde0fced50ee27780189dd7bc028e63d.js?file=style.css"></script>

style.css

/* Notice the specificity - this makes constants Immutable
   IMPORTANT:
   - Only use this during development to help you avoid mutating constants!
   - Use Webpack or any other means to add the 'development' class to
     your root HTML element
   - For a more targeted example: https://codepen.io/piggyslasher/pen/OaWpmQ?editors=1100
*/
:root, .development * {
  --COLOR-RED: palevioletred !important;
  --COLOR-GREEN: mediumseagreen !important;
  --COLOR-LIGHT: papayawhip !important;
  --COLOR-DARK: darkgray !important;
  
  --FONT-SIZE-MIN: 16;
  --FONT-SIZE-MAX: 26;
  
  --FONT-SIZE-MIN-PX: (var(--FONT-SIZE-MIN) * 1px);
  --FONT-SIZE-MAX-PX: (var(--FONT-SIZE-MAX) * 1px);
  
  --BROWSER-WIDTH-MIN: 300;
  --BROWSER-WIDTH-MAX: 1600;
  --BROWSER-WIDTH-MIN-PX: (var(--BROWSER-WIDTH-MIN) * 1px);
  --BROWSER-WIDTH-MAX-PX: (var(--BROWSER-WIDTH-MAX) * 1px);
  
  /* While the following isn't necessary, it's worthy to note that this
  // property is just being declared, and is an end result of two constants
  // i.e. it's a constant. This just makes for more readable code below. */
  --FONT-SIZE-DIFFERENCE: (var(--FONT-SIZE-MAX) - var(--FONT-SIZE-MIN));
  
  /* The property below is an interesting situation. 100vw is actually a variant because
     it depends on the screen size. But it's not yet computed using calc().
     It is, in effect a constant. Think of this as just text replacement */
  --FONT-SIZE-LOCK: ((100vw - var(--BROWSER-WIDTH-MIN-PX)) / (var(--BROWSER-WIDTH-MAX) - var(--BROWSER-WIDTH-MIN)));
  
  --WIDTH-THREE-QUARTER: (100vw * .75)
}

:root {
  /* ---THEME LAYER---
     Theme variables, for instance, can be overridden. That's what themes are for :)
     Hence, dynamic and lowercase */
  --theme-color-primary: var(--COLOR-RED);
  --theme-color-secondary: var(--COLOR-GREEN);
  --theme-color-background: var(--COLOR-LIGHT);
  --theme-color-foreground: var(--COLOR-DARK);
  
  /* BAD: Avoid referencing main color constants directly */
  --border-color: var(--COLOR-RED); /* You'll lose easy theme capability */
  /* GOOD: Always access the theme layer */
  --border-color: var(--theme-color-primary); /* Hard to debug where the value has changed */
  
  /* GOOD: Prefer getting value from constant */
  --border-color: var(--theme-color-primary);
  
  /* Calculate only properties that will be used across the page
  i.e. grid widths, font-sizes */
  --width-3-quarter: calc(var(--WIDTH-THREE-QUARTER));
}

html {
  --font-size: calc(var(--FONT-SIZE-MIN-PX));
  font-size: var(--font-size);
  border-top: calc(var(--font-size) * 0.25) solid var(--border-color);
}

body {
  width: var(--width-3-quarter);
  margin: var(--font-size) auto;
}

h1, h2, h3, h4, h5, h6 {
  --heading-color: var(--theme-color-primary);
  color: var(--heading-color);
}

  h1.muted {
    /* Change the color by changing custom proper value */
    --heading-color: var(--theme-color-foreground);
  }

button, .button  {
  /* Scope your variables. If it is used by only buttons,
     declare them at the TOP of the block
     and prefix the property with '--button'
  */
  --button-background: var(--theme-color-primary);
  --button-foreground: var(--theme-color-background);
  --button-padding: .5rem 1rem;
  
  /* BAD: Avoid magic numbers in values */
  padding: .5rem 1rem;
  /* GOOD: create locally scoped custom property and access that */
  padding: var(--button-padding);
  
  background-color: var(--button-background);
  color: var(--button-foreground);
}
  button:hover, .button:hover {
    /* BAD: Do no change regular properties */
    --button-background: var(--theme-color-secondary);
    
    /* GOOD: Mutate custom properties rather than actual CSS properties */
    --button-background: var(--theme-color-secondary);
  }

@media screen
and (min-width: 300px)
and (max-width: 1600px) {
  html {
    --font-size: calc(
      var(--FONT-SIZE-MIN-PX) + var(--FONT-SIZE-DIFFERENCE)
      * var(--FONT-SIZE-LOCK)
      );
  }
}

@media screen
and (min-width: 1600px) {
    html {
      --font-size: calc(var(--FONT-SIZE-MAX-PX));
    }
}