A Simple CSS Color Naming Convention
  • Context

  • Generally I recommend using Tailwind utility classes for almost all of your css, because it removes collisions and the thousands of decisions around naming which will starts when you build you own CSS conventions.

  • There is, however, one place where I think it makes sense to have a (very lightweight) layer of custom css alongside Tailwind. And that is for colors.

  • Why Colors Specifically?

    • They're unique to each app, and thus won't be covered by Tailwind. Yes, you can of course use Tailwind config, but we use a build-less version of Tailwind.

    • Many of the places colors appear are interactive, meaning you will need to add a lot of classes making the markup very verbose - active, hover, focus, dark mode etc.

  • Color Groups

  • Another common use case for colors is within menus and navigation lists, where colors are used to signal active states. My first rule still applies here - Tailwind should be used for layout - paddings, margins etc. But there are a small number of attributes that don't fit within that framework - background color, text color, border color, and transitions.

  • Thinking through naming conventions

  • Ultimately these conventions are very subjective. These are what I've landed on after years of writing CSS on teams.

    • I've found explicitly including the color name in the variable name (e.g. --color-orange) to get confusing when another similar color gets introduced later on.

    • I've found having completely non-specific numbered colors (e.g. --color-1, --color-2) to be difficult for recall - I always have to go back and check what color-1 refers to.

    • I've found suffixing color names with a number (e.g. --color-1 ) to create the incorrect assumption that there is some level of primacy (one is more important than two etc).

  • My (Current) Guidelines

    • Use the greek alphabet for (this gives us 24 colors to work with across the codebase)

    • Prefix variables related to colors with color-*

    • Use the --text suffix to pair font color to a background color.

    • Create .bg-* utility classes for each of your color variables.

    • Create color groups for common navigation lists, using an .active class to designate the currently active state.

  • What this looks Like

  • Here is a tiny, real world example of a CSS file that follows these conventions

    :root {
      --color-alpha: rgba(26, 31, 42,100);  /* Black */
      --color-beta: #5046e5 ; /* Purple */
      --color-gamma: #1e293b; /* Dark Navy Purple */
      --color-gamma-text: #fff; 
      --color-zeta: #cbd5e1; /* Light Gray */
      --color-delta: #f471b5; /* Pink */
      --color-epsilon: #7dd3fc; /* Baby Blue */
      --gray-1: #f2f2f2;
      --gray-2: #e6e6e6;
    .bg-beta {
      background-color: var(--color-beta);
    .bg-gamma {
      background-color: var(--color-gamma);
    .color-group-zeus > .active,
    .color-group-zeus > *:hover {
      background: var(--color-gamma);
      color: var(--color-gamma-text);
      transition: background-color 0.3s ease;
    .color-group-odin {
      & > * {
        color: rgba(0, 0, 0, 0.4);
      & > *:hover,
      & > *.active {
        color: var(--color-gamma);
  • Questions

  • Why not use rgba values? They're more modifiable & you can easily create opacity variants.

  • In practice, I found the benefits (outlined above) were minimal, and I personally preferred the aesthetics and ease-of-readabilty without them.

  • Website Page