Overview
Data Tokens are UI elements created to present structured, and repeatable information in grouped lists. Tokens are specifically designed for interaction and drag-and-drop behavior. Typically tokens are placed in side panels and their content depicts metadata about a selected object.
Look and Feel
Legacy Guideline Available
This guideline pertains to the most recent version of the SAP Design System. Previous iterations of this guideline remain applicable for tools that have not yet adopted the latest design vision.
Legacy Guidelines:
When to Use
Data Tokens reside within SAP product areas, such as builder panels, control panels, data wranglers, and modelers. They are found in dialog boxes like linked dimensions, facet sorting, target scoping, and toolbars like story filters. These use cases are mostly reserved for administrators and editors of the documents – not viewers.
Recommended
- Use to organize data points.
- Use to show hierarchical data.
- Use to add interactivity to simple UI elements.
Not Recommended
- Avoid using them for non-interactive scenarios.
- Avoid using them outside panels.
- Avoid using them as decorations.
Token Types
Anatomy
The anatomy of the Data Tokens is divided into three areas: Icons, Content, and Actions. Icons are placed at the beginning of the token and contain various icon indicators such as data type, expand and collapse, value state, color, avatar, primary key, etc. The content area in the middle contains vertically stacked text such as the token title, byline, line, etc. The actions area at the end is reserved for actions like buttons and switches.
Icons Area
The icons area is a container that hosts various types of heroes, each with its unique purpose. The icon area can display icons for the following:
- Expand / Collapse Indicator - shows whether the token is expanded or collapsed.
- Token Type - an icon representation of the token type
- Semantic Status - predefined icon for the semantic value state of the token
- Avatar - displays the avatar component to show a user
- Color - displays a rectangle that contains the color that the token represents
- Marker - a unique identifier that provides an additional highlight to the token (ex., primary key)
Icons or UI Elements associated with each token type
Content Area
The content area is a container that hosts the token title and bylines. The title is represented in textual form and is highlighted (semibold font weight) when a marker or a value state is displayed. Sometimes, a byline can provide additional information about the token. The byline can also be replaced by a link that can serve as navigation or a button. You can have either a byline or a link, not both.
Actions Area
The actions area is a container that hosts interactive components (mostly buttons). See actions later in the article for full details.
Constructing a Data Token
When creating a data token make precise considerations of the information it needs to show and the interaction use it has. Keep in mind that Data Tokens are typically placed in panels and their width rarely exceeds 300 pixels.
- Show just the information needed, not more
- Show the appropriate icon type
- Keep the token title concise and clear
- Consider the internationalization of the token content
- Use semi-bold fonts for tokens with an additional indication (ex. primary key, value state)
- Don't use more than two icons. A type and addictional indication is enough in most cases.
- Don't provide lengthy token names or bylines. The texts will truncate and meaning will be lost.
- Don't provide more than two actions. If you need more decide on a primary action and overflow the rest.
- Don't make data token too wide. They are designed to be used in small spaces.
Behavior
General
Data Tokens are interactive components designed to provide various interaction possibilities such as selection, dragging and dropping, expanding and collapsing, etc. The interactions work together multiplicatively, which results in a vast array of combinations.
Visual States
As an interactive component, the Data Token supports all required visual states for both mouse and keyboard interaction. The token also supports visual variants with and without borders.
Data Token Visual States
- Prefer the bordered visual variant.
- Prefer non-selectable tokens.
- Use the borderless variant for hierarchical lists.
- Don't use data tokes with no interaction.
- Don't use checkboxes to do token selection.
Value States
Sometimes the Data Token needs to display a semantic value state (ex. error, warning, etc.). In such cases the an additional semantic icon indication is displayed and the token text becomes semibold.
Data Token Value States
- Use value states to indicate validation issues
- Use value states to show data point status
- Provide error message on click or focus
- Put AI-generated tokens in a warning state
- Do not modify value state icons or colors
See also
Core Visual Design - Message and Status Icons
Drag and DropDrag
When the Data Token is enabled for drag and drop interaction, hovering or focusing changes the token type identifier icon to a grip indicator. In addition, the cursor changes from pointer to move. The drop area interaction behavior and visuals follow the SAP Design System's established rules.
Data Token Drag and Drop
- Replace token type icon with drag indicator on hover and focused visual states
- Keep the token in the normal visual state for displaying the ghost element.
- Follow the official visual design concept for dragging multiple tokens.
- Follow the official visual design concept for designing drop areas.
See also
Core visual Design - Drag and Drop Visual Concept
Expanding and Collapsing
Some Data Token use cases require placing multiple components or other tokens inside the token content area. In such cases the token uses its expand/collapse functionality. When expanded, the token contents remain at the top portion of the token, and a newly expanded content area is presented to host whatever the use case requires.
Data Token Expand and Collapse
- Expand and collapse happen on token click.
- Actions in expanded tokens affect all content.
- Don't make expandable token selectable.
- Don't use expandable tokens for hierarchies.
- Don't nest expandable tokens in each other.
Selection
Some tokens are selectable, while others are not. The selectable ones act as toggle buttons or checkboxes. Clicking on a token selects it, and clicking it again deselects it. Multi-selection occurs when clicking on tokens in succession. In that sense, the tokens behave as list items.
Data Token Selection
Actions
Many of the Data Tokens require additional actions that is associated with them. Actions are placed on the end of the tokens. Actions are shown on :hover and :focused states.
Data Token Actions
- Place not more than two actions.
- More actions overflow in a menu.
- Place only buttons in the actions area.
- Use BTP Nested Buttons
- Don't place disabled action in the data token
- Don't place edit fields for actions.
In special cases external enabling and disabling of the data token is required. In such cases use the switch component to toggle between enabled and disabled state.
See also
Keyboard Handling
Data Token Keyboard Handling
Screen Reader
Data Token Screen Reader
Responsiveness
Form Factor
As with any component, the Data Token is available in desktop and touch-optimized sizes. This allows proper interactive behavior on all screens and minimum sizes that SAP supports. Displaying the Cozy (mobile) form factor is recommended on mobile devices only. On touch-enabled desktops, the option to switch to a Cozy form factor should be presented to the user but not forced.
Data Token Form Factors
Truncation
A design goal for the tokens is to keep the component's height stable. Therefore for lower widths, it is not uncommon the token title, byline, or both is not uncommon to get truncated. Truncation can occur earlier in the Cozy form factor.
- Overflow the actions first.
- Truncate the content area last.
- Provide a tooltip when the text truncates.
- Don't overflow or hide any icon identifiers.
Data Token Truncation