The naming scheme for your design tokens is important, this is what people will be using to communicate, guide, and write in both design tools and code. Try to keep it concise while still conveying meaning.
Also known as a 'token hierarchy'
Base levels as a token’s backbone that combine category (for example,
color), concept (action) and property (size). Modifier levels to refer to one or more of variant (primary), state (hover), scale (100), and mode (on-dark). Object levels to refer to a component (button), element within a component (left-icon), or component group (forms). Namespace levels combining any (or all, in extreme cases!) of system (esds), theme (oceanor subbrand), or domain (retail).
namespace-object-base-modifier
A single token doesn't need every level. Describe the intent [[20220523102023-design-tokens-as-intents]]
Avoid homonyms. Words such as type convey two different meanings: 'typography', and 'categorisation'.
Category + property pairs are very general and not useful. We need to add concepts and modifiers.
Adding a concept like action, feedback, or body makes tokens more useful. Consider how you divide your concepts to avoid overlap.
Variants may have different distinctions depending on the concept. Text may have primary, secondary, etc. But feedback offer success, error, etc.
Adding properties to your variants make them more specific, but less flexible. Consider color-success vs color-text-success.
Usually describes interactivity
Different scales are used for different things. Consider t-shirt sizes (S, M, etc), proportions (1x, 2x, etc.), numeric (100, 200, etc.), etc. [[20230803125044-t-shirt-size-scale]]
Usually for things like light and dark.
Consider if you need the default to be explicit or implicit, e.g. color-action-secondary-onl-light vs color-action-secondary.
Tokens are reusable across a component library. However tokens may also be reusable across a few components or within a single component. Consider if you're tokenising for a component, element, or component group (e.g forms).
When doing so, make sure to not globalise prematurely [[20211115112656-rule-of-three]]. Create component-level tokens within a component, and then extract higher if needed.
Having tokens for individual objects helps enable localised change [[20211029153348-semantic-design-tokens]]
Namespaces may not be necessary.
Useful for themes, brands, etc. Can even extend to a domain.
Also useful to avoid global styling problems with tools like SASS.
Some examples for colour:
Asana uses sentiment-usage-prominence-interaction, e.g. warning-text-default-hover
Salesforce uses component-category-property-attribute-relationship-state
![[[design-token-naming.png]]](/design-token-naming.png){kind=link}