Skip to content

Token name structure

Jump to bottom
Garth Braithwaite edited this page Jul 31, 2024 · 4 revisions

Token names are made up of parts. We have some documentation of the basic categorization of these parts on the Spectrum website.

Chart showing the 3-part structure for how Spectrum names design tokens. The first part is the context, which is the most broad idea in what needs to be communicated in the name. Examples of this are a component, a system constant like a border or a background, or a color. The second part is the common unit, which is the most consistent idea. Examples of this are sizing, spacing, styling, or text. The third part is clarification, which is the most specific or detailed idea. Examples of this are a t-shirt size, and index or value, or a user-initiated state.

As I have been auditing these name parts, I have found repeating trends that could be broken into more granular categories.

Group or component

  • These are either globally shared or generic component parts or specific components.
  • Examples:
    • field-edge-to-text-quiet: field refers to the group. In this case, it's a pseudo component that isn't a real component but refers to a classification or type of component.
    • side-label-character-count-to-field: side-label refers to a general element in a component.
    • gray-50: gray is a group of colors.
    • slider-handle-size-small: slider is a component.

Sub-element or component part

  • A term that describes a part of a component or sub-element.
  • Examples:
    • checkbox-control-size-large: control refers to the square part of a checkbox, with or without the indicator nested inside.

Space between

  • This is a from-to notation that describes the space between component parts. This should be informed by a component's anatomy.
  • Examples:
    • text-to-visual: this whole token name is a space-between description; it describes the space between text and visual.
    • breadcrumbs-start-edge-to-text: start-edge-to-text describes the space from the start-edge (left in ltr and right in rtl) in the breadcrumbs component.
    • table-row-top-to-text-small-compact: top-to-text describes the space from the component top to the text sub-element.

Property

  • The attribute of an element being defined by the token. These shouldn't be confused with component options.
  • Examples:
    • color-loupe-drop-shadow-color: color is a property, but a bit too generic. text-color, background-color, and drop-shadow-color would all be more specific. In this case, drop-shadow-color would be
    • alert-banner-minimum-height: minimum-height is a property of the alert-banner component.
    • accent-background-color-default: background-color is a property that could be used by any component with a accent component option.

Component options

  • Should be defined in the "table of options" on the Spectrum design system website. Properties of a component that can be changed for specific use cases. Unlike component states, they shouldn't change based on user interactions or system status.
  • Examples:
    • checkbox-control-size-large: large refers to the size property with the small, medium, large, extra-large options in checkbox table of options.
    • tab-item-compact-height-medium:
      • compact refers to the density property with regular and compact options.
      • medium is an option of the size property for the tab-item component.

States

  • This is the interactive state of a component that changes based on user interaction (mouse, keyboard, or touch interactions). It could also be something that changes based on system status.
  • Examples:
    • table-selected-row-background-opacity-hover: hover refers to the hover mouse interaction on the table component.

Index

  • A numeric representation of a relationship between values in a set of tokens. The index is usually 100 level increments to provide flexibility to add values between like 150 without breaking the existing values. The index does not perfectly reflect the ratio between values (i.e., if spacing-100 is set to 8px, that does not mean that spacing-200 is double 8px).
  • Examples:
    • corner-radius-100: corner-radius has a set of potential values. 100 implies corner-radius-100 is larger than corner-radius-75 and smaller than corner-radius-200.
    • gray-50: 50 describes the proximity to the base color for a color-set (e.g., white #FFFFFF for the light color theme and black #000000 for the dark color theme.
---
title: Spectrum Tokens Workflow
config:
  theme: base
  themeVariables:
    primaryColor: "#F8F8F8"
    primaryTextColor: "#222222"
    primaryBorderColor: "#B1B1B1"
    lineColor: "#B1B1B1"
---

flowchart LR
    group(Group or Component)
    subElement(Sub-element or component part)
    space(Space between)
    property(Property)
    options(Component options)
    states(States)
    index(Index)

    subgraph context [Context]
        group
        subElement
    end
    subgraph commonUnit [Common Unit]
        space
        property
    end
    subgraph clarification [Clarification]
        options
        states
        index
    end
    group ~~~ subElement ~~~ space ---|or| property ~~~ options ~~~ states ~~~ index

linkStyle default stroke-width:1px
classDef containerStyle rx:7,ry:7,stroke-width:0;
classDef contextStyle fill:#68dea8;
classDef commonUnitStyle fill:#ffbb62;
classDef clarificationStyle fill:#dbbbfe;
class context,commonUnit,clarification containerStyle
class context contextStyle
class commonUnit commonUnitStyle
class clarification clarificationStyle
Loading
Clone this wiki locally