How to Name Design Tokens for Easier Maintenance

A design-token name should explain why a value exists, not merely describe how it looks today. blue-500 may be easy to create, but it becomes misleading when the brand color changes. button-primary-background communicates more intent, yet it can also create unnecessary coupling if the same role belongs to links, menus, and other actions.

The maintenance-first rule is simple: name tokens by stable intent first, then add only the scope, state, or component context needed to distinguish valid uses. Every extra word creates a promise that the system must keep true. Every missing qualifier can leave consumers guessing.

Start by deciding what the token represents

Before choosing a naming pattern, identify the token’s layer and responsibility. A primitive token records a reusable value such as a color, spacing unit, font size, or border radius. A semantic token records a role such as a default surface, muted text color, or primary action background.

These layers answer different questions. A primitive asks, “What value is available?” A semantic token asks, “What should this value do here?” Keeping that distinction visible helps prevent a raw value from becoming an accidental interface contract. For more context on this separation, see primitive and semantic tokens.

A practical naming review begins with four questions:

• Is this token a raw value, a reusable role, or a component-specific contract?
• What design meaning should remain true if the value changes?
• Which consumers are allowed to use it?
• What information would a future maintainer need to choose it correctly?

If the answer is only a color, size, or number, the token may be primitive. If the answer describes a purpose in the interface, a semantic name is more appropriate. That does not make semantic naming mandatory everywhere. It makes the layer and intended reuse explicit.

Remove volatile details from semantic names

A value-based name exposes a visual decision that may not remain stable. Names such as blue-500, large-radius, or dark-gray-text describe the current implementation. They do not explain whether the value represents a brand accent, a warning state, a surface, or secondary content.

Suppose a hypothetical system starts with blue-500. The team considers three alternatives:

• blue-500
• button-primary-background
• action-primary-background

The first preserves the current value but not its role. The second preserves a component relationship but may be too narrow if other primary actions use the same treatment. The third communicates a broader role, provided “primary action” has a stable definition in that system.

The right choice depends on the allowed scope. If the value is intentionally available only to a button contract, a component qualifier may be useful. If the role applies across buttons, links, and menus, action-primary-background better preserves the underlying meaning. If the team cannot agree what “primary” means, the name is not ready merely because it sounds semantic.

A practitioner discussion of token naming proposes describing a color through its component, interaction state, and attribute rather than its current value (the contextual naming approach). Treat that as a useful design proposal, not proof that one naming structure works universally.

Add context only when it prevents ambiguity

Component and state qualifiers are useful when they define a real contract. They are costly when they simply reproduce the current file structure.

A name such as card-header-background may be justified when the header has a distinct role that should not be reused elsewhere. It is less useful when the token only exists because the value was first encountered inside a card. The component name should express ownership or intended restriction, not historical placement.

State information deserves the same test. button-primary-background-hover is more specific than action-primary-background, but that specificity is worthwhile only if hover behavior differs from the broader action role and the token is governed by the button contract. Disabled, pressed, selected, focus, and error states should be named when they change the meaning or usage conditions—not because every component happens to have a state folder.

Use a qualifier when removing it would create one of these problems:

• Two tokens would appear interchangeable even though they have different contracts.
• A consumer could choose a token without knowing an important state condition.
• A theme or product scope would override the wrong role.
• Ownership, review responsibility, or allowed reuse would become unclear.

Otherwise, prefer the shallower name. Naming guidance commonly connects scalability with descriptive purpose and hierarchical structure, but a hierarchy should support decisions rather than imitate the implementation tree (one practitioner guide’s naming criteria).

Test the name against likely changes

A name is not maintainable because it looks tidy in the current interface. Test it against changes that would expose hidden assumptions.

If the value changes

Would the name still be accurate if the brand replaced blue with green, or if a spacing scale changed? If not, the name probably leaks an implementation value.

If the theme changes

Would the name still describe the role in light and dark themes, or across brands? A semantic name should identify what the token does even when each theme assigns a different primitive value.

If reuse expands

Would the name still make sense outside the first component that used it? If a token may serve several action components, avoid encoding a single component without a deliberate ownership reason.

If the component changes

Would the name survive a component split, merger, or ownership change? A name tied to an unstable component structure can turn a refactor into a token migration.

If the state changes

Does the token describe a genuine interaction state, or did the team add a state suffix because the file happened to contain a hover variation? Keep the qualifier when it governs a distinct visual or behavioral contract.

This test distinguishes a stable role from a convenient label. It also exposes names that are technically consistent but semantically ambiguous. A specialist naming guide recommends that names clearly distinguish one token from another; that is a practical ambiguity test, not measured evidence that a particular syntax reduces maintenance work (the ambiguity guidance).

Treat scope as a contract, not decoration

Scope can refer to a product, brand, theme, component, state, or ownership boundary. It belongs in the name only when it changes how the token may be selected or overridden.

For example, a global semantic role may be appropriate when every product shares the same meaning. A product-specific token may be necessary when two products use the same phrase for different interface decisions. A component token may be warranted when the component must control the value independently of the broader role.

Do not encode every possible dimension by default. A name such as brand-a-product-b-button-primary-background-hover-dark may appear precise while becoming difficult to scan, document, and migrate. Some of that information may belong in theme modes, token metadata, ownership records, or documentation rather than the identifier itself.

The name should help a consumer select the token. Supporting records should explain who owns it, where it applies, what it aliases, and what changes require review. A design token contract can carry those details without turning every identifier into a compressed policy document.

Allow exceptions without losing consistency

Strict naming rules do not eliminate judgment. They make judgment easier to review. An exception is reasonable when a role is intentionally local, a component needs an independent contract, a state cannot safely inherit a broader role, or a product has a meaningful scope boundary.

Record the reason for the exception. Include the intended consumers, owner, replacement path if the token is temporary, and the condition that would justify consolidation or retirement. Without that context, an exception looks like inconsistency to the next contributor and may be copied into unrelated work.

Avoid aliases that exist only to make names look semantic. If action-primary-background always points to button-primary-background, ask whether both names represent genuinely different contracts. An alias can preserve compatibility during migration, but it should not conceal uncertainty about which role is authoritative.

Review names before they spread

A proposed token name is ready when a reviewer can answer five questions without opening the component implementation:

1. What stable design role does the token represent?
2. Which volatile details has the name intentionally omitted?
3. What scope, component, or state limits its use?
4. Would the name remain accurate after a value, theme, or structural change?
5. What would happen if the role were split, reused, deprecated, or replaced?

If the answers are unclear, change the meaning before changing the punctuation. A naming convention is not just a string pattern. It is a small governance system for deciding what the organization promises to preserve.

The most maintainable name is therefore not the shortest or most descriptive in isolation. It is the name that communicates stable intent, prevents meaningful ambiguity, and leaves implementation details out unless they are part of the contract.