Skip to main content

Design Token Architecture

This section explains how design tokens are structured and related inside WaveMaker. It helps you understand where tokens live, what each type of token does, and how they connect from global definitions to component-level overrides to make your app look consistent, scalable, and theme-ready.

Token Hierarchy​

Design tokens in WaveMaker are organized across three levels:

LevelDescriptionFolder path
1. Global tokensFoundational, brand-wide styles such as colors, typography, spacing, and shadows.global/{category}/{file}.json
2. Component tokensStyles for specific widgets (buttons, lists, inputs, etc.) that use global values.components/{widget}/{widget}.json
3. OverridesEdits from Style Workspace, including theme and variant adjustments.overrides/global/{category}/{file}.json, overrides/components/{widget}/{widget}.json

These layers cascade from Global → Component → Overrides → App UI.

1. Global Tokens: the Foundation Design​

These are the master style values that define your brand’s look and feel. They are not tied to any single component; they apply everywhere.

For example:

  • Color: brand colors like #E8925C (primary) or #6C757D (secondary)
  • Text: default font family ('Inter', sans-serif)
  • Size / Spacing: 8px, 16px, 24px etc.
  • Style: border radius or shadow depth

Think of Global Tokens as the DNA of your app’s visual design. When you change one here (like your primary color), that change automatically affects every component that uses it.

Global tokens live under global/, for example:

global/colors/color.json
global/font/font.json
global/space/space.json

2. Component Tokens: the Applied Layer​

Component Tokens use the global tokens and apply them to actual UI elements like buttons, cards, or text fields.

They define how each component should look — for example, what color a button uses for its background, text, or border.

Example:

  • Button Primary → background color = {color.brand.primary}
  • Button Text → text color = {color.text.inverse}
  • Card Header → background color = {color.surface.container}
  • This means if your global color changes, these component styles automatically update too.

Component tokens live under components/, for example:

components/button/button.json
components/cards/cards.json
components/form-controls/form-controls.json
note

Components in WaveMaker can have variants, which define different visual styles of the same component.
Component Tokens exist at two levels:

  • Component Level: Define common properties shared by all variants (for example, typography, padding, or default color).
  • Variant Level: Define more specific visual treatments for each style variation of the component.

For example, the Button component includes multiple variants such as:

  • Filled Button: Uses a solid background for high emphasis actions.
  • Outlined Button: Displays a border with a transparent background for medium emphasis.
  • Text-only Button: Removes the fill and border for minimal emphasis actions.

Each variant inherits core values from the component tokens while applying unique styling for background, border, and text color.
This structure allows you to maintain consistency across all button types while enabling clear visual hierarchy within your design system.

3. Overrides: the Flexible Layer​

Overrides are edits or theme variations that you make in Style Workspace (for example light or dark mode, or custom variants for your app).

When you change something visually, WaveMaker does not overwrite your global or component token files. Instead, it saves those changes as overrides, for example:

overrides/global/colors/color.light.json
overrides/components/button/button.json

Your base design system stays intact, and your app applies override values on top of it. For Studio editing steps, see Working with Style Workspace. For paths, build flow, and compiled output, see Customising your application.

How they connect​

  • Define your brand foundation in global tokens.
  • Widgets such as buttons, lists, and inputs use those values through component tokens.
  • Visual changes and theme updates from Style Workspace are stored as overrides.
  • The running app uses the combined token system.

A single change at the top—for example updating the global primary color—flows through dependent components and keeps the app visually consistent.