It was a casual morning scroll through BlueSky when a post by Sam Gordashko caught my eye—a nuanced discussion about the semantic intricacies of "Heading" versus "Title" in design systems. What seemed like a minor terminology debate quickly unfolded into a fascinating exploration of how seemingly small naming choices can profoundly impact design, development, and accessibility.

Intrigued by Sam's insights, I dove deeper, using AI-powered analysis to unpack the pros and cons of these design token approaches. The result is this comprehensive exploration of a topic that's more complex than it first appears.

Why the Debate?

The term "Heading" carries semantic weight in web development, being closely tied to HTML elements `<h1>` through `<h6>` and the hierarchical structure they provide. On the other hand, "Title" is less prescriptive and allows for more flexibility in design systems.

The choice between these terms affects:

1. Clarity in token purpose

2. Implementation in HTML and CSS

3. Accessibility and SEO

The Case for "Heading"

Using "Heading" aligns directly with HTML semantics, which is particularly useful when building a design system that needs to stay consistent with web standards.

Benefits

• Semantic clarity: Developers immediately associate "Heading" tokens with `<h1>`, `<h2>`, etc., preserving proper document structure.

• SEO alignment: Search engines use headings to understand page hierarchy, so "Heading" tokens align naturally with these practices.

• WCAG compliance: Headings are a critical part of accessibility, as screen readers rely on the correct use of `<h*>` tags.

Example

A token system using "Heading" might look like this:

JSON

{

  "typography": {

    "heading": {

      "large": {

        "fontSize": "32px",

        "fontWeight": "bold",

        "lineHeight": "40px"

      },

      "medium": {

        "fontSize": "24px",

        "fontWeight": "bold",

        "lineHeight": "32px"

      },

      "small": {

        "fontSize": "18px",

        "fontWeight": "semibold",

        "lineHeight": "24px"

      }

    }

  }

}

CSS

.heading-large {

  font-size: 32px;

  font-weight: bold;

  line-height: 40px;

}

.heading-medium {

  font-size: 24px;

  font-weight: bold;

  line-height: 32px;

}

.heading-small {

  font-size: 18px;

  font-weight: 600;

  line-height: 24px;

}

HTML

<h1 class="heading-large">Main Heading</h1>

<h2 class="heading-medium">Section Heading</h2>

<h3 class="heading-small">Subsection Heading</h3>

The Case for "Title"

"Title" provides a more flexible approach, decoupling the design system from strict HTML semantics. It focuses on visual styling rather than the structural role, which can be especially helpful in multi-platform design systems.

Benefits

• Flexibility across contexts: Tokens named "Title" can be applied to various HTML elements (`<h1>`, `<h2>`, `<div>`) without implying a specific semantic role.

• Reduced confusion: Developers and designers avoid the assumption that these tokens must always map to HTML heading tags.

• Versatility for non-web use cases: "Title" can be used for app headers, section dividers, or banners in non-HTML environments.

Example

A token system using "Title" might look like this:

JSON

{

  "typography": {

    "title": {

      "primary": {

        "fontSize": "32px",

        "fontWeight": "bold",

        "lineHeight": "40px"

      },

      "secondary": {

        "fontSize": "24px",

        "fontWeight": "bold",

        "lineHeight": "32px"

      },

      "tertiary": {

        "fontSize": "18px",

        "fontWeight": "semibold",

        "lineHeight": "24px"

      }

    }

  }

}

CSS

.title-primary {

  font-size: 32px;

  font-weight: bold;

  line-height: 40px;

}

.title-secondary {

  font-size: 24px;

  font-weight: bold;

  line-height: 32px;

}

.title-tertiary {

  font-size: 18px;

  font-weight: 600;

  line-height: 24px;

}

HTML

<h1 class="title-primary">Main Title</h1>

<div class="title-secondary">Section Title</div>

<span class="title-tertiary">Subsection Title</span>

Accessibility and SEO Implications**

Using "Heading"

• Pros: Guarantees alignment with WCAG and semantic best practices if implemented with proper HTML structure (`<h1>` to `<h6>`).

• Cons: Risks over-prescription; developers might feel constrained to use headings in a specific way even when the design intent doesn't require semantic structure.

Using "Title"

• Pros: Allows for flexibility in design and non-web contexts while maintaining a consistent style across platforms.

• Cons: Requires additional effort to ensure accessibility, as semantic roles (`role="heading"`, `aria-level`) may need to be added manually.

ARIA Example with "Title"

HTML

<div role="heading" aria-level="1" class="title-primary">Main Title</div>

<div role="heading" aria-level="2" class="title-secondary">Section Title</div>

Making the Right Choice

Inspired by Sam Gordashko's BlueSky post, the decision to use "Heading" or "Title" depends on your design system's priorities:

1. Choose "Heading" if:

• Your design system primarily supports web projects

• Semantic HTML and SEO are critical

• Accessibility compliance is a key focus

2. Choose "Title" if:

• Your design system spans multiple platforms

• You want to decouple design tokens from HTML semantics

• Flexibility in usage is more important than strict alignment with HTML

Conclusion

What began as a casual BlueSky post by Sam Gordashko transformed into a deep dive into the nuanced world of design system terminology. The choice between "Heading" and "Title" comes down to how you want your design system to balance semantic clarity, styling flexibility, and accessibility.

For web-specific systems, "Heading" aligns naturally with HTML and accessibility standards. For broader use cases, "Title" offers the flexibility to adapt to diverse platforms.

By considering your system's goals and user needs, you can confidently pick the terminology that best suits your design system—a decision that's about much more than just semantics.