This content originally appeared on Level Up Coding - Medium and was authored by Jon Dewitt
AIR — Naming CSS Color Variables
AIR is a naming convention to maximize theme-ability
“There are only two hard things in computer science: cache invalidation, and naming things.”
— Phil Karlton
Although this quote may be getting old and tired, it never gets any less relatable. This is especially true for CSS color variables, which may arguably be the most challenging kind of names to work out. It may not be immediately noticeable, but it does have a substantial impact on maintainability.
I’ve been experimenting, trying to nail down an appropriate pattern for years — and I’m not alone. I’ve read countless blogs on this subject, with very little consensus between them all. There are some arguments for role-based naming, some for actual color names, and some for a value scale. Yet, with each of these solutions, I’ve encountered some real-world problems that made it difficult for me to make updates.
To save you time and effort spent wrestling with these problems yourself, allow me to explain how I resolved each one.
Why Does It Matter?
Rebranding happens, requirements change, and sometimes additional themes are needed, most often dark mode. The initial build may be easy enough, but making updates will become a real thorn in everyone’s side. Of course, planning for different values can be frustratingly limiting, hence why it’s so tempting to give up and name things intuitively.
:root {
--merlot: #865f5f; /* red (merlot) */
--crimson: #dc143c; /* red (crimson) */
}Some shades of red might be labeled “merlot” or “crimson”, and that’s easy enough to conceive and remember. But, we have to be cognizant of the dangers that go along with that.
You’ve rebranded, and now you figure out all the variables aren’t really… variable. Merlot’s color has changed to navy, and crimson to cobalt, but the variable names haven’t changed at all. Due to the massive scope of impact, replacing all the uses across the project would never make it past the risk management team in one giant pull request. So, the only option is to keep the variable names the same for now, and just change the value.
:root {
--merlot: #000080; /* blue (navy) */
--crimson: #0047ab; /* blue (cobalt) */
}Oof, confusing. I’ve been there, and I don’t want to go back.
Thus, we should choose variable names that aren’t too opinionated of the value they contain; something which has the freedom to change and still make sense. This practice is not just based on my personal opinion, in fact it has existed in computer science since the beginning. It’s called information hiding. You could consider it a distinct part of encapsulation.
The Naming Convention
It’s been a maddening journey to design a sane naming convention that’s both flexible and terse. It should apply some meaning to the palette without locking itself into any particular color, nor any characteristic of color, like “dark” or “pastel” or similar visual descriptions.
Overall, my strategy can be narrowed down to three major parts.
- Affiliation: There’s pretty much always a way to divide colors into groups by how they’re affiliated, like “brand,” “site,” “error,” and so on.
- ID: “Primary” and “secondary” work pretty well, but how many people know what comes after “tertiary?” A number ID is sufficient and preserves equal semantic value, yet it’s certainly shorter and simpler.
- Relationship: Colors usually have specific and necessary relationships with other colors, such as background, foreground, and alternatives. In this convention, these relationships are described by another ID or “c” for “contrast.”
I call this approach AIR (affiliation-ID-relationship,) and it’s the naming convention I now use in all my projects to keep things orderly and future-proof.
affiliation-id-relationship
brand-1-1
error-1-c
A quick call-out before moving forward: CSS variables may of course include more than just colors. To differentiate color variables from the rest, I use the prefix --color- before applying this convention to the remainder of the variable name.
Affiliation
For a standard website, colors may be categorized by purpose; grouped together by what role they play in the design. Some common use cases are:
- Brand
- Site
- Accent
- Success
- Error
- Warning
- Info
The list may go on for infinity, but the above examples ought to adequately establish a pattern. Each affiliation could safely swap values, because there’s nothing that suggests particular colors, yet it remains useful enough as a memorable name.
Admittedly, it’s easier to remember specific color names. You may end up referring to the theme file frequently at first, but I’ll stress once again that you sacrifice theme-ability if you give in to temptation. Chris Coyier is very insightful and has a lot of great things to say — however, this is one topic on which we disagree, because the presumption of his argument is that variables are only useful for making colors readable, and he seems to assume they’ll never change.
I avoid such lock-in at all costs, because rebranding is seldom predictable. No one ever expects it to happen, so planning ahead might seem unnecessary, but such habits tend to hurt future developers. Anecdotally, I have led rebranding efforts on multiple occasions throughout my career, so that’s been enough to convince me not to become part of the problem.
ID
Of course, after you’ve named your affiliation, you need to start distinguishing each color it affiliates. Ordinal numerals (primary, secondary, etc.) have proven effective in a variety of applications in design, and continue to be useful today. I wouldn’t say there’s no place for it, just that it’s verbose and scarcely in our everyday vernacular.
Regular old numbers are just as useful, just as descriptive, and way shorter, not to mention easier to type and remember. Primary and secondary can be expressed as simply 1 and 2 without making any sacrifices, really.
At this point, we already have everything we need to name our first base color.
--color-brand-1: #0000ff;
Now only the direct relationships remain, which will compose upon the base color above to determine more specific colors from there.
Relationship (contrast)
You may be familiar with the requirement that colors must have a contrast ratio of 7:1 to pass WCAG level AAA conformance. With respect to that, you should always have a color available that sufficiently contrasts with the base color.
A suffix may be added to designate a color for this role, like “contrast.” Personally, that gets a little too wordy for my liking, so I abbreviate it with the letter “C,” like --color-brand-1-c.
Notice that I don’t choose labels like “foreground” or “background,” because they may be reversed occasionally. With buttons, for example:
.section {
background-color: var(--color-brand-1);
color: var(--color-brand-1-c); /* the contrast color is in the foreground */
}
.button {
background-color: var(--color-brand-1-c); /* the contrast color is now in the background */
color: var(--color-brand-1);
}Relationship (variation)
Another situation you’re likely to encounter in real-world projects is the event you need a set of similar colors for largely aesthetic purposes.
Although it can be argued that every single design decision is driven by some non-aesthetic motivation, sometimes the reasoning is too insignificant to justify breaking it down. That being said, we should be reasonably mindful of these trivial relationships; if there are seven different shades of green, and only five of them are related, we shouldn’t involve the other two in the same group.
To address these subtle color variations, I add another number for each variation.
--color-success-1: #55ab57;
--color-success-1-1: #3c8f4f;
--color-success-1-2: #4d7a64;
--color-success-1-3: #1ddb7c;
You might have a few cases to stack these suffixes for specific reasons. Of course, this must be practiced scarcely and modestly. Following this pattern to the nth extreme is surely bound to become unmaintainable.
--color-success-1-2-c: #c5dec6;
/* never name something like this if you want to give me credit! */
--color-success-1-2-1-c-5-4-c: #00ff00;
Must They be CSS Custom Properties?
I have my reasons for preferring custom properties, but none of them apply to this naming convention. Feel free to use this pattern with SCSS, LESS, or whatever preprocessor you like. The benefits come from flexibility and readability of names, not with the technology of choice.
In the case of custom properties, you can pierce shadow DOM and use the cascade to your advantage, nesting different themes down the tree. You could still achieve theme scoping with SCSS by simply importing a different _variables.scss file, but you’ll have to be aware of how that impacts shadow DOM.
Conclusion
This convention has served me well in my career so far, and I feel it’s my turn to pay it forward. I hope you find this as useful as I have.
Perhaps your project doesn’t require theme-ability, but I personally assume everything I do will eventually need updated. In my experience, themes are often an after-thought, and no one ever seems to predict they’ll scale to that point. On too many occasions, I’ve been tasked with reskinning a website that was not originally built with theme changes in mind. The experience has made me passionate about being more considerate of the future developer.
If you have any suggestions or questions, please feel free to respond! I may make some amendments. If you like the naming convention, please do share it with your friends and colleagues. I’d like to contribute something helpful and reduce bike-shedding in the industry, even if it is just a small amount.
AIR — Naming CSS Color Variables was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Jon Dewitt
Jon Dewitt | Sciencx (2022-05-06T03:59:18+00:00) AIR — Naming CSS Color Variables. Retrieved from https://www.scien.cx/2022/05/06/air-naming-css-color-variables/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.