Best Practices for Naming
Our naming convention is designed to create a universal language that bridges the gap between designers and developers. Instead of relying on arbitrary colour names or direct design references, our approach focuses on the meaning and intention behind design elements. This ensures:
- Clarity & Consistency – Tokens are self-explanatory and easy to understand.
- Scalability & Maintainability – The structure prevents technical debt by avoiding hardcoded values.
- Flexibility Across Themes & Modes – Names reflect intent rather than specific values, making adaptation seamless.
Naming Structure
Tokens follow a structured format
- Domain – Defines the scope (e.g., intentional tokens for semantic use).
- Group – Categorizes the type (e.g., colour, spacing, typography).
- Concept – Describes the general purpose (e.g., feedback, interaction).
- Modifier – Adds specificity (e.g., error.high, container.neutral).
- Property – Specifies the design property (e.g., background, border).
- State (optional) – Defines interaction states (e.g., hover, active).
Examples
|
Domain |
Group |
Concept |
Modifier |
Property |
State |
|---|---|---|---|---|---|
|
intentional |
colour |
feedback |
error.high |
background |
— |
|
intentional |
colour |
interaction |
container.neutral |
border |
hover |
|
intentional |
colour |
level |
00 |
background |
— |
|
intentional |
colour |
interaction |
container.branded.high |
border |
hover |
By structuring tokens in this way, we ensure a future-proof, context-agnostic, and developer-friendly design system that adapts effortlessly across products and platforms.
Types of Tokens
Primitive Tokens
The foundational values of the system (e.g., raw colours, spacing, typography scales). These are abstract and context-agnostic, serving as the building blocks for all other tokens.
- Colour
- Spacing
- Typography
- Radius
Intentional Tokens
Tokens that convey semantic meaning and design intent (e.g., feedback.error.high). They abstract primitives into meaningful categories, ensuring consistency across themes and modes
- Content: Body content (text, icons, borders)
- Level: Defines the background and surface colours of layouts.
- Interaction: Interactive elements (buttons, links, navigation items)
- Feedback: Status indicators (error, warning, success)
- Accent: Highlights (used to emphasize elements)
Example - Feedback tokens structure :
Component-Specific Tokens
Tokens applied directly to components, defining their styling while inheriting from intentional tokens. They ensure a consistent look and feel while allowing flexibility within the system.
- Tokens specific to UI components (e.g., buttons, forms, modals).
- we use 2 main types of tokens to build a component: spacings and colours
Colours
Spacings
