Characteristics

A design token stores design decisions in a single place, enabling teams to use them to create consistent experiences.

The Salt Design System uses three tiers of tokens. From most generalized to most specific, they are:

1. Foundational tokens
2. Characteristic design tokens (characteristics)
3. Component-specific tokens

Characteristics form sets of Cascading Style Sheet (CSS) variables that define a visual attribute, such as text or colors denoting status. Components can then reuse them, allowing for design consistency and logical patterns. They help to define the rules that style each component and aid the cohesiveness of the overall user interface.

Characteristics offer the following benefits:

• Ability to theme Salt in line with third parties or sub-brand guidelines
• Increased consistency across all components, improving the overall user experience, e.g., reduced cognitive load
• Simplified design of new components and patterns e.g., drag-and-drop behavior
• Single reference points for commonly used values
• Streamlined design changes, e.g., a characteristic tweak automatically applying to all related components
• Shared language enabling smooth handovers from design to development

You can look at the Salt components' CSS files to see how they are styled.

When defining characteristic design tokens, they should generally be in the format --salt-<characteristic name>-<variant>-<attribute>-<state>

1. Always begin with --salt-.
2. Follow with the foundation name, e.g., --salt-actionable-, --salt-text-, --salt-focused-.
3. Append the variant if applicable, e.g., --salt-actionable-cta-, --salt-text-h2-.
4. Append the attribute, e.g., --salt-actionable-cta-background, --salt-text-h2-fontSize, --salt-focused-outlineColor.
5. Append the state if applicable, e.g., --salt-actionable-cta-background-hover.

Remember to wrap the characteristic you wish to use inside a var() function.

For example, a Button is a component on which a user can perform an action, so you can use the following characteristics to style the component:

Characteristics are both light/dark and density scoped, meaning that the value the characteristic points to will change according to the values given in the nearest SaltProvider.

In the above example, --salt-actionable-primary-background resolves to var(--salt-palette-interact-primary-background). In the light theme, this is var(--salt-color-gray-60); in the dark theme, this is var(--salt-color-gray-300). Foundation tokens then resolve to their respective RGBA values.

Generally, the characteristics appropriate for the component should be given by the design team. To decide which characteristics to use when styling a new component, it may be useful to ask questions like:

• What can the user do with this component? Can they click it, drag it, etc.
• What state can this component be in? Can it be focused, disabled, etc.
• What is the purpose of this component? Will it contain other elements, lead the user to a new page, etc.
• Should this component give feedback? Can it be submitted, does it have a success state, etc.

Just because you have assigned a characteristic to a component does not mean it consumes all of those characteristics. You can specify which characteristics you want to apply.

A good example of this is the focused characteristic, which offers both border and outline styles. You would use the outline token if setting the outline attribute, and the border token if setting the border attribute.

Think carefully when deciding which characteristics are most appropriate. For example, should your component background come from container because that's its general purpose, or should it come from the selectable, since it can be selected? Many characteristics define the same attribute (e.g., background color), and deciding which characteristic your component should use is important. This will ensure consistent styling across your user interface, especially when different themes are applied.