Design Tokens for Links

A pragmatic exploration of token architecture choices for hyperlinks in design systems

Links are everywhere in digital interfaces—from navigation menus to call-to-action buttons embedded in content. Yet when it comes to organizing them within our design token architecture, they present a unique challenge that many teams struggle with.

Unlike clearly defined components such as buttons or cards, links occupy an interesting middle ground: they're atomic elements that can exist independently or be integrated into more complex components. This versatility makes their classification in design token systems particularly nuanced.

The architectural dilemma

In the three-level model of design tokens (global, semantic, specific), links find themselves in a gray area.

Links are not specific interface elements, but they can feature different styles depending on whether they are placed within a paragraph of text, in a menu, or in a card.

The naming convention that follows the structure {element}.{category}.{property}.{modifier} would suggest placement in the specific tokens group.

However, the cross-cutting nature of links in the interface might justify a semantic treatment.

Links as Semantic Tokens

In the semantic approach, we don't use the word link in the token name, but instead reuse the group of semantic tokens dedicated to the "text" category:

// TEXT SEMANTIC TOKENS

color.text.primary
color.text.primary.hover
color.text.secondary
color.text.secondary.hover
color.text.accent
color.text.accent.hover

In a CSS stylesheets we could use them as follows:

.navigation-link {
  color: var(--color-text-primary);
  &:hover {
    color: var(--color-text-primary-hover);
  }
}

.footer-link {
  color: var(--color-text-secondary);
  &:hover {
    color: var(--color-text-secondary-hover);
  }
}

.cta-link {
  color: var(--color-text-accent);
  &:hover {
    color: var(--color-text-accent-hover);
  }
}

Pros

• Flexibility: Facilitates adaptation to different contexts

• Reusability: Tokens can be used across multiple components

• Abstraction: Enables global changes without impacting individual components

Cons

• Clarity: Lacks easily identifiable design tokens specific to links

• Roles: Using text-dedicated tokens creates confusion about which ones apply to links

When to use

Opt for the semantic approach when:

• The system needs to support multiple variants or themes

• Links share common logic in different contexts

• It's important to maintain consistency with other semantic elements

• Significant system growth is expected

---

---

Links as Specific Tokens

This approach treats links as discrete interface elements with their own dedicated token namespace, recognizing their unique role and behavior within the user interface.

This methodology acknowledges that links, despite their ubiquity, deserve special consideration in the token architecture due to their distinct interactive properties and visual signifiers:

// LINKS SPECIFIC TOKENS

link.color.primary
link.color.primary.hover
link.color.secondary
link.color.secondary.hover
link.color.accent
link.color.accent.hover

By establishing a specific token structure for links, designers and developers can more easily identify and apply consistent styling across different contexts while maintaining a clear separation from other interface elements.

.navigation-link {
  color: var(--link-color-primary);
  &:hover {
    color: var(--link-navigation-color-hover);
  }
}

.content-link {
  color: var(--link-color-secondary);
  &:hover {
    color: var(--link-color-secondary-hover);
  }
}

.cta-link {
  color: var(--link-color-accent);
  &:hover {
    color: var(--link-color-accent-hover);
  }
}

Pros

• Clarity of intent: Focuses on the purpose of the link rather than its technical classification

• Consistency: Maintains coherence with other semantic elements in the system

• Reduced redundancy: Leverages existing semantic tokens rather than creating parallel structures

Cons

• Redundancy: Potentially duplicates the tokens already defined for the text

• Overengineering: Risk of creating excessive abstractions for simple cases

• Limited scalability: Managing complex systems with many variants

When to use

Opt for the specific approach when:

• The design system is relatively simple

• Links have very specific and differentiated behaviors

• The team prefers a more explicit and less abstract structure

• Frequent changes to link values are not anticipated