How we stopped using color names and moved to purpose naming

How we stopped using color names and moved to purpose naming

Orr Gottlieb and Dor Yehoda

Recently we’ve started to build our components library (open source is coming soon), as a first step we started to design our foundations – Typography, General design (shadows, rounded corners …) and Colors (we have a lot of them). We’ve had a small break-through in how we work and we thought about sharing.

Color naming.

Our colors have awesome names. We have Egg Yolk (#FFCB00), Lipstick (#F279F2), Snow White (#FFFFFF), Mud Black (#323338) and many more. Although it is cool to write color: $explosive; in your code, it is hard to keep track what is their purpose.

What led us to change

Once we started to develop we started to see a lot of back and forth between dev and design – mostly about which color should have which purpose.

“What color should I use when the component is in this state?”

Getting different answers to that question was what made it pretty clear for us that we need to change how we communicate over colors and their purposes.

border-color: $explosive;
border-color: $riverstone;

Creating a common language

We started thinking about what we״re trying to achieve. A unified, easy-to-understand and predicted behavior across our product.
We can not achieve that when we talk about colors and behavior separately.

We decided that each behavior (or a state) is representing a color. It is more important that the behavior will always present itself with the same color than the color value itself.

For example – Our CTAs are using our primary color. That color can be a button background color or a selected text. The fact that our primary-color is a shade of blue doesn’t matter. If we replace the color, the purpose of the CTA will stay the same.
We wanted to shift the way we talk in that direction – talk about the purpose of the color we use, and not its value. No one will ask “What color should I use when the component is disabled?” when we have a “disabled-color” declaration, right?

Keys Keys Keys

Keys are the key (sorry for this pun).
We have declared color-keys that are bound to specific behaviors (or states) that will be self-explanatory and easy to use.

Our 3 golden rules for adding keys

  1. Adding a key must be acceptable by a predefined key committee (or the person who brings the best chocolate chip cookies). Adding a key means we either add a state or adding a behaviour to the system, we want everyone to understand the meaning of it.
  2. The key must not contain a component or part of the system name in it. A key should describe a behavior, a component is a use case.
  3. The name of the key must imply what role is. So it would be obvious when and where to use it.

Our implementation

We decided to go with css variables, in this approach we define each potential color with a css var --color-primary: #0085ff and each role is mapped to the relevant color var – --primary-color: var(--color-basic_blue);

We also have to support IE11 (as of now) so we created a simple SASS mixin @include theme-prop(color, primary-color); which inserts both the css variable and the default IE11 color which we support (once we drop support – change the mixin and all our CSS is smaller ???? )

@mixin theme-prop($property: color, $color-variable: primary-text-color, $important: false) {
  @if $important {
    #{$property}: theme-value-default($color-variable) !important;
    #{$property}: theme-value-var($color-variable) !important;
  } @else {
    #{$property}: theme-value-default($color-variable);
    #{$property}: theme-value-var($color-variable);

@function theme-value-default($color-variable: primary-text-color) {
  @return map-get($theme-defaults, $color-variable);

@function theme-value-var($color-variable: primary-text-color) {
  @return map-get($theme-vars, $color-variable);

Cool Side Effect – We’ve added themes support in a single day!

The fact that we chose CSS variables has given us the chance to create themes. It is as simple as creating a class with different values for each css-variable (our functional color keys).

All we needed to do is to use those keys around the system – That’s where our Darkathon came in.
We have gathered six developers from different teams and started our Darkathon (dark-theme hackathon). At the end of that day we had most of our system already adjusted to dark colors!. A huge bonus – those areas are now consistent in the way components look and behave between states as they all use the same color keys instead of explicit colors like before!

Minor Cool Side Effect.

By using CSS Vars the design team can change the CSS var color via the developer tools and see the entire system changes its appearance (in production)

Keeping our system aligned

We’ve added a CI rule that warns the developer if they entered an explicit color and or used an explicit saved color (by its name and not value). This way we are keeping our SCSS files colors role and state based.