Using design tokens
In design
Using design tokens as Figma variables is moving to open-beta following a successful invite-only pilot.
It's easy to opt in to the beta.
- Add Beta: Design tokens library to your files. (How do I add a library to my file?)
- Use colors as Figma variables instead of styles from 📙 Component library. (How do I apply a Figma variable?)
- Let us know how you get on in the feedback issue. No problem too big, no feedback too small.
In the future, color styles will be removed from the component library and these Figma variables will be updated to support dark mode.
We've scoped these Figma variables by limiting the properties they can be applied to. This helps cut out the guess work when designing and supports recommended usage. For example, text.color.default can only be applied as a fill to a text element and not to a stroke or shape layer.
In code
NOTE: A pilot for design tokens in code has been completed as part of this issue , and we're currently doing more exploration with a small subset of components as part of this issue . More details about officially using design tokens will be coming soon, but in the meantime carry on with your typical development process.Concepts
Our design tokens are organized into conceptual categories that reflect their purpose and usage within the user interface. These categories help create consistent, accessible, and meaningful user experiences across the product. Consider the context, user needs, and overall design consistency when designing custom elements that use design tokens. Use sufficient color contrast and provide text alternatives for all visual indicators.
Actions
Actions are interactive elements that trigger or represent user actions. action.* design tokens give a common visual style for interactive elements across the GitLab UI.
To create bespoke interactive elements, combine background, foreground, and border color tokens. Note that in some modes, borders might not be visible by default. This is intentional to provide accessible boundaries in modes like Windows High Contrast Mode.
Action tokens support three contexts:
neutral: Default for most actions.confirm: For positive outcome actions.danger: For potentially destructive actions.
Interactivity can be communicated through implementing states such as hover, focus, and active.
Consider using existing GitLab components (such as button, pagination, or tabs) that already implement action tokens. These provide consistent styling and behavior without custom implementation. For more information on available components, see the components overview.
Controls
Feedback
feedback.* design tokens are used to communicate dynamic information about the result of an action, event, or opportunity. Feedback often requires a user's attention or action.
Use feedback design tokens when:
- Notifying a user about a system event (for example, an error or successful action).
- Promoting a new feature or important information.
- Providing guidance or additional context.
Examples of custom feedback elements:
- A notice that alerts about unusual performance patterns, or an available dependancy update.
- An inline update providing compliance check feedback, or discovery of a new vulnerability.
- An addition to a collaboration activity stream.
Status
status.* design tokens represent the current state or condition of an element or system. A status item provides static information that doesn't typically require immediate action.
Use status design tokens when:
- Indicating the current state of an item (for example, in progress or completed).
- Showing a priority or importance level.
- Representing system health or connection status.
Examples of custom status elements:
- A color-coded indicator showing task urgency, or the current state of a CI pipline.
- A small icon representing the confidentiality level of a document, or the visibility of a repository.
- Text communicating code test coverage as a percentage.
Considerations
Choosing between feedback and status
Use these factors to decide between using feedback and status design tokens:
| Characteristic | Feedback | Status |
|---|---|---|
| Purpose | Communicates changes or opportunities | Informs about current state |
| Timing | Triggered by events or changes | Always present |
| User attention | Often requires immediate action | Doesn't require immediate action |
| Persistence | Often temporary | Persistent until state changes |
| Scope | Can relate to entire system | Specific to particular element |
| Interactivity | May include interactive elements | Typically non-interactive |
| Examples |
|
|
Additional considerations:
- Dynamic vs. static: Feedback is often dynamic and changing, while status tends to be more static, changing only when the underlying state changes.
- Context: Consider the broader context of the user interface. Status is often used within components or alongside specific elements, while feedback might appear separately or overlay other content.
- Combination use: In some cases, you might use both status and feedback design tokens together. For example, status design tokens to show the current state of a CI/CD pipeline, with feedback design tokens to communicate that a merged result pipeline has failed.
- Active processes: For ongoing processes (like 'in progress' or 'syncing'), consider using status, as these represent the current state even though they're dynamic.
When in doubt, consider whether the information represents the current state of something (status) or is communicating a change or the result of an event (feedback). Remember that the primary goal is to provide clear, consistent, and meaningful information to the user in the context of GitLab.
Patterns and matching
Accessibility considerations
Last updated at: