The way semantic tokens can be defined is too restrictive.

[sanstream]

Description

When I try to add semantic tokens based on my core/primitive tokens I am forced to group them based on color, gradient etc.

But the consensus these days in the design system community seems to be that semantic tokens should be describe based how they are used. So a grouping based on their type (like color) makes them harder to manage.

Problem Statement/Justification

For example, The way we use semantic tokens, is as way to translate the theme of a brand or product (defined as core/primitive tokens) into tokens that describe how they are used within the UI design.

Our semantic tokens are divided into two sets: General tokens and component specific tokens.

A general token is set up like: {part of the layout}.{property of layout}.{light/dark mode} and might look like `paFor example, The way we use semantic tokens, is as way to translate the theme of a brand or product (defined as core/primitive tokens) into tokens that describe how they are used within the UI design.

Our semantic tokens are divided into two sets: General tokens and component specific tokens.

A general toge.sideMargin.onLight` .

A component specific token is set up like:
{component name}.{variant}.{style element}.{state (optional)}.{light/dark mode}} and might look like: button.cta.borderColor.focused.onLight , button.cta.borderColor.hovered.onDark or button-cta-borderColor.active.onLight .

Right now the sematicTokens property witihn theme prevents me from defining those, because it only allows grouping based on token type.

Perhaps (for now) there is a way arround this, but to me the current implementation is too strict.

Proposed Solution or API

Allow this:

    theme: {
      semanticTokens: {
        page: {
          backgroundColor: {
            value: {
              _dark: coreTokens.colors.neutral[700],
              _light: coreTokens.colors.neutral[100],
            },
          } as ColorToken,
        }
      }
    },

Note: my TS syntax might be wrong, please forgive me ;-).

Alternatives

No response

Additional Information

I am aware that currently the grouping by value type allows for syntax like this:

  <div
    className={css({
      color: 'green.400',
      background: 'gray.200'
    })}
  />

In which the fact that green.400 can automatically be found in the colors group, and my proposed solution could maybe ruin this.

What could be an option is to allow something like this:

  <div
   className={css({
     color: 'pageBody.textColor',
     background: 'pageBody.backgroundColor'
   }, true)}
 />

Where the true enforces the use of fully qualified (spelled out) token names.

[astahmer]

What about making using defineSemanticTokens twice in your side, 1 for your general tokens and 1 for your component semantic tokens, and then merge the result in config.semanticTokens ?

[sanstream]

I did some further digging into my assertion that the current implementation of the semanticTokens property is too strict. And maybe it is, but I've discussed this with other people in the design system community (design systems slack) and most of them define their semantic tokens initially by grouping them by category/type (font, color, size) as opposed to pattern/property (page, button,mainBackground). This produces tokens like color.button.callToAction.background.focus and font.bodyText.fontFamily, and those fit nicely into the current sematicTokens scheme.

So it is actually fine the way it is. With that in mind I am closing this discussion.