Structured custom properties

The way people use custom properties is often similar to the use of design tokens, where we have different "types" of them.

What we have so far is what people will usually call primitives.

They are useful, but it can often be hard to remember which is which between brown-400 and brown-300.

Made even worse is when you're working on several projects at once, where you have different color schemes.

To make it easier, it's common to have a semantic "layer" of custom properties as well, which describe what they are being used for instead.

For example, for our orange text, instead of having to remember if we used the 400 or 500 version of our brand color, we just need to remember --text-accent, or for a dark background, if we just need to remember --background-dark.

:root {
  /* primitives here */
  --text-main: var(--clr-gray-100);
  --text-high-contrast: var(--clr-white);
  --text-brand: var(--clr-brand-500);
  --text-brand-light: var(--clr-brand-400);

  --background-accent-light: var(--clr-green-400);
  --background-accent-main: var(--clr-green-500);
  --background-accent-dark: var(--clr-green-600);

  --background-extra-light: var(--clr-brown-500);
  --background-light: var(--clr-brown-600);
  --background-main: var(--clr-brown-700);
  --background-dark: var(--clr-brown-800);
  --background-extra-dark: var(--clr-brown-900);
}

And of course, we can do this for more than only our colors:

:root {
  --font-size-heading-sm: var(--fs-700);
  --font-size-heading-regular: var(--fs-800);
  --font-size-heading-lg: var(--fs-900);
  --font-size-heading-xl: var(--fs-1000);

  --font-size-sm: var(--fs-300);
  --font-size-regular: var(--fs-400);
  --font-size-md: var(--fs-500);
  --font-size-lg: var(--fs-600);
}

Other variables

Before diving in, I always like to look over a project and look for things that could be handy custom properties.

These are things we don't really need primitives for, and can jump right to the "semantic" names for.

I'm looking for things that:

• Repeat themselves throughout the project in different places.
• I wouldn't want to have to remember a specific value for each time.

For the most part, this tends to be "effects" like shadows and glows, border radius values, and sometimes spacing values as well.

I'd encourage you to explore the design files and see if you can find anything that you think would be worth creating custom properties for.

The only thing that jumps out at me is the different border-radius that are used, but if you find other things feel free to include them (margin & padding values are common values people like to use as well).

:root {
  --border-radius-1: 0.25rem;
  --border-radius-2: 0.5rem;
  --border-radius-3: 0.75rem;
}