Component Token Naming

[gfellerph]

In the component token layer (currently exported as one sass file with two maps), components are not consistently named. Notifications and Buttons are two components, but Button tokens are nested in a list mixed with other interactive components while Notification tokens live in their own list.

/** Content of the maps is shortened for demo purposes */
$post-interactives: (
  'post-comp-interactive-color-primary-bg-enabled': var(--post-sem-color-interactive-primary-enabled-bg),
  'post-comp-interactive-button-primary-color-fg-enabled': var(--post-sem-color-interactive-button-primary-enabled-fg),
);

$post-notifications: (
  'post-comp-notification-color-bg-badge': var(--post-sem-color-notification-badge-bg)
);

Potential issues

This approach makes it hard for developers looking at the exported sass files to determine what components the tokens should be used for (are Tabs "interactive"?). While it's possible to look up tokens used in Figma Dev Mode, it's not a guarantee to catch all tokens, especially in deeply nested components. There's no overview of what tokens are used for this component when the outer layer is selected. With the Figma approach, it's easy to miss tokens.

The danger of component tokens that need renaming is also higher when we use shared component names. A renamed component token will most likely be a breaking change for development because they will be documented in Storybook (adding more component tokens would be features, removing component tokens would be a breaking change also).

Proposed solution

Component tokens are the most important interfacing point between Figma and Code. Therefore naming and consistency are most important in this area.

Consistent naming

The naming schema should be consistent across the whole token system.

// Component layer: [namespace] [layer] [group] [component] [variant] [property group] [property] [state]
// Semantic layer:  [namespace] [layer] [property group] [group] [component] [variant] [state] [property]
'post-comp-interactive-button-primary-color-fg-enabled': var(--post-sem-color-interactive-button-primary-enabled-fg),

Naming schema

For component tokens, especially the development will profit from short, memorable token names. Unnecessary categorization should be omitted. The layer naming (-comp-) is good to have an overview in the token system, but is irrelevant to end users of tokens because the only thing they should interact with are the component tokens. As for the grouping of component tokens, it does not provide any benefit if every component has it's own collection of tokens.

/* Comp interactive could be left out */
--post-comp-interactive-button-primary-color-fg-enabled

--post-button-primary-color-fg-enabled

Sass output

Ideally, each component will generate a list of tokens available for this component. This makes it possible to iterate over existing tokens not only in the Styles, but also in the documentation. If lists with tokens for multiple components are used, it's not possible to assign the tokens used to a specific component.

$post-textfield: (
  'post-comp-interactive-textfield-primary-color-bg-enabled': var(--post-sem-color-interactive-primary-enabled-bg),
);

$post-button: (
  'post-comp-interactive-button-primary-color-fg-enabled': var(--post-sem-color-interactive-button-primary-enabled-fg),
);

$post-notifications: (
  'post-comp-notification-color-bg-badge': var(--post-sem-color-notification-badge-bg)
);

[gfellerph]

Proposal accepted, need dev support for renaming.

[gfellerph]

Added new state on the production board and moved affected tickets to this column. Moving to discussions for documentation purposes.