Skip to content

Behavioural Tokens

The behavioural token encodes through data structure (rather than naming convention) the relationship between tokens used in default, hover and active states.

Many design systems will have, somewhere in the semantic layer, tokens that look something like this:

Semantic Tokens
Name
Light
Dark
Semantics
Primary
Background
Default
Primitives/Primary/300
Primitives/Primary/1100
Hover
Primitives/Primary/400
Primitives/Primary/1000
Active
Primitives/Primary/500
Primitives/Primary/900
Semantics
Secondary
Background
Default
Primitives/Secondary/300
Primitives/Secondary/1100
Hover
Primitives/Secondary/400
Primitives/Secondary/1000
Active
Primitives/Secondary/500
Primitives/Secondary/900

There's a clear intent here, expressed through the naming, that a component using a background color of Semantics/Primary/Background/Default should also use a background color of Semantics/Primary/Background/Hover when in hover state (if applicable) and likewise for active state.

However, there's no easy way to apply this to a component that doesn't require the designer to manually select each one.

The behavioural token exists to fill this void:

Behavioural Tokens
Name
Default
Hover
Active
Semantics
Primary
Background
Semantics/Primary/Background/Default
Semantics/Primary/Background/Hover
Semantics/Primary/Background/Active
Foreground
Semantics/Primary/Foreground/Default
Semantics/Primary/Foreground/Hover
Semantics/Primary/Foreground/Active
Border
Semantics/Primary/Border/Default
Semantics/Primary/Border/Hover
Semantics/Primary/Border/Active
Semantics
Secondary
Background
Semantics/Secondary/Background/Default
Semantics/Secondary/Background/Hover
Semantics/Secondary/Background/Active
Foreground
Semantics/Secondary/Foreground/Default
Semantics/Secondary/Foreground/Hover
Semantics/Secondary/Foreground/Active
Border
Semantics/Secondary/Border/Default
Semantics/Secondary/Border/Hover
Semantics/Secondary/Border/Active

Now, consumers can reference Semantics/Primary/Background, and have a mode to switch between states.