A design token name is a sentence

My button's hover background is called --quieto-component-button-primary-color-background-hover. It's long, and every word in it is there on purpose. The thinking behind it is borrowed. Nathan Curtis' Naming Tokens in Design Systems breaks a name into levels, and Brad Frost's Atomic Design builds interfaces up from small parts. I put the two together in quieto-tokens as three tiers.

Each tier adds words to the name. A primitive like --quieto-color-blue-400 only says what the value is. A semantic token like --quieto-semantic-color-background-default-hover says where it goes. And the button token above says who owns it. Read any of them left to right and the name narrows as it goes, from the system down to a single state.

A few rules keep the names from drifting. Semantic properties are only content, background or border, and anything else needs a conversation first. content always means text and icons, so text and foreground never show up as synonyms. Only semantic and component tokens carry a tier word, which makes a stray primitive in a component stylesheet easy to catch in review. And every token starts at the component tier, moving up only once a few components need the same decision.

It has costs. Component names get long, and autocomplete ends up doing a lot of the typing. The closed lists also slow people down the first time they hit an edge case, like a chart color that isn't really a background or a border. I'd still take a long name I can read over a short one I have to look up.