OMFG, naming things is so hard. I've come to the conclusion that the perfect naming convention for design tokens may actually exist — I'm just not smart enough to figure it out, and certainly not with these deadlines.
Why can't we just call it this and be done with it?
It seems like everyone is having a hard time coming up with a good naming convention for their design system. While going through this exercise at Atolls, I really got bogged down naming design tokens. I was thisclose to the perfect convention — but some new use case kept breaking things. I even had a lovely spreadsheet with column definitions: populate the columns you needed, ignore the ones you didn't, and it spat out a dot-separated token name. I mean, who doesn't love a spreadsheet?
Anyway, it didn't take off. Funnily enough, not everyone shared my passion for a perfectly-named token that fit just so within our ecosystem. So it got relegated to the dustheap of non-critical projects we'll get back to someday.
I considered sharing the spreadsheet here, but honestly it's a little embarrassing. It's over-engineered. It's over-complicated. It's naïve. And wrong — wrong in so many ways.
So when the deadline loomed, a simpler solution came to light.
More guidelines than actual code
What I settled on was hard-and-fast rules for what lived inside the design system — but if product designers wanted to create their own tokens, they only had to follow the first two parts of the name. The first part designates a token for use with components only; the second is the unique name of the component it belongs to. With those two parts unique, you're guaranteed no clashes with any other token in the system.
The rest follows something like this:
Align on token property groups
To make things easier to read and understand, alignment on property groups is encouraged. The groups include:
- Animation
- Color
- Font
- Shape
- Spacing
- Typography
I like to keep the groups alphabetised for findability.
No interdependency between patterns
Tokens created to support custom patterns should only be used in those patterns. You shouldn't end up in a situation where a token you've been using gets deleted or renamed without you knowing. It also frees you up to add and remove tokens as needed, without worrying about breaking changes outside your control.
When creating tokens for your own patterns, remember to scope them properly to avoid name clashes. That relies on good communication across teams to land on good, understandable, unique pattern names.
People can offer what worked for them — but in the end, you'll have to decide what works best for your current situation.
Right so, as it stands…
As with most things, it's a work in progress — but it all looks workable. Which brings me back to my original goal: a unifying token naming convention. Well, I didn't find the one… but I did find one that works for us.
As infuriating as that sounds, that's kinda how most things go.
