<aside> <img src="/icons/home_blue.svg" alt="/icons/home_blue.svg" width="40px" /> Home | Foundations | Components | Addons | Patterns

</aside>

Design Tokens are the foundational building blocks of the Aqua Design System. They are key values that define visual properties like color, typography, spacing, and more. Their purpose is to ensure consistency, scalability, and easy implementation across different platforms (web, mobile, etc.).

🔗 Connection of Design Tokens to Components

Application of the color palette brings a unified and recognizable consistency to Masiv vast array of digital products and interfaces. This consistency is grounded by a set of well-defined rules on how to work with the Aqua component library.

Aqua establishes a clear and intuitive relationship between Design Tokens and components, enabling UX and UI designers to build cohesive and consistent interfaces.

When applying styles to components, many properties are derived directly from Design Tokens. For example, a button’s background might be defined using the --primary token, ensuring consistency across the entire design system.

<aside> 💡

Design Tokens must always be applied through their intended level of abstraction. Components should never reference raw values directly, but instead consume usage Tokens that inherit from Semantic Tokens, which in turn inherit from Primitive Tokens.

</aside>

Aqua organizes its Design Tokens into three main collections:

🧩 Primitive Collection

This collection contains the raw foundational values used across the system. These values are not directly tied to specific components but serve as the building blocks for all design decisions.

• Colors – Base color values that include primitives like Primary, Accent, Neutral, Base, Danger, Success, Warning, and Information.
• Radius – Corner radii used for components like buttons, cards, and inputs.
• Spacing – Values used for paddings and margins across components.
• Stroke – Thickness values for borders or outlines.
• Shadow – Currently in progress; this will define shadow and depth levels for components.
• Typography – Font sizing, line height, and font families. (Pending full implementation due to platform limitations.)
• Icons – Tokenized icon sizes used across the UI

What they are

Primitive tokens are raw, foundational values (colors, spacing, radius, etc.) with no UI meaning.

Examples

color.blue.600
color.gray.900
color.green.300
radius.4
spacing.8

Rules

• ❌ Must NOT be used directly in components
• ✅ Can only be referenced by theme or semantic tokens
• ✅ Serve as the base for theming and brand customization

Why

Using primitives directly in components couples UI to raw values and breaks theming.

🧬 Figma Colour Tokens Structure

🧩 Token Types

Aqua design tokens are grouped by function and usage:

Untitled

🎨 Theming

Aqua supports custom themes using token layering and nesting:

• Tokens are grouped into themes (e.g., Light, Dark, Brand A)
• Tokens inherit from Primitives Collection or Theme Collection
• Themes can be switched dynamically in product UI

Theme & Semantic Tokens

What they are

Semantic tokens describe intent, not appearance.

They translate primitives into meaningful roles in the UI.

Examples

color.primary.base
color.background.surface
color.text.primary
color.feedback.success

References

color.primary.base → color.blue.600
color.background.surface → color.gray.0

Rules

• ✅ Used across layout, text, and general UI
• ✅ Change per theme (Light / Dark / Brand)
• ❌ Must not reference components directly