Skip to main content

Customising your application

Style Workspace​

Use Style Workspace in Studio to change design tokens, component styles, and variants through structured inputs instead of raw theme files. For what Foundation CSS is and how tokens feed the mobile theme, see Introduction to Foundation CSS. For how to navigate and edit tokens in Studio, see Working with Style Workspace.

Foundation CSS is the base theme layer for your React Native (Expo) app. Customize through Style Workspace rather than editing Foundation source. Hand-editing tokens, component rules, or variants in that base layer is possible but slow and easy to get wrong as the design system grows.

Changes in Style Workspace are saved under your WaveMaker project at src/main/webapp/design-tokens/overrides/. They stay aligned with the mobile design system and do not require forking Foundation CSS. Style Workspace keeps customizations token-driven, helps you iterate on theme and variants faster, and scales theming without duplicating component style definitions on every screen.

Variant management​

Create new variants or change existing ones in Style Workspace. Variant definitions are stored as JSON under src/main/webapp/design-tokens/overrides/ and compiled when you export or regenerate the mobile app.

For variant concepts, see Introduction to Foundation CSS — Variants.

Under the hood​

Customizations touch two different folders, depending on whether you are looking at the WaveMaker project in Studio or the exported Expo app.

1. WaveMaker project (Studio source)​

Path: src/main/webapp/design-tokens/

File or folderRole
overrides/**/*.jsonSource of truth from Style Workspace (global and component token edits, variants, and states)
app.override.cssCompiled override CSS from the JSON (intermediate output from codegen)
app.studio.override.cssStudio canvas and mobile preview in Studio (derived from app.override.css)
app.designtokens.jsRuntime token and variant overrides for preview and export (derived from app.override.css)
foundation/ios/ and foundation/android/Compiled Foundation theme (style.css for Studio, style.js and tokens.js for runtime, fonts, and related assets)

Example override JSON (custom button variant):

// src/main/webapp/design-tokens/overrides/components/button/button.json
{
  "btn": {
    "appearances": {
      "custom": {
        "mapping": {
          "background": { "value": "{color.border.translucent.value}" },
          "color": { "value": "{color.error.@.value}" }
        }
      }
    }
  }
}

The exported Expo app on a device uses app.designtokens.js and foundation style.js / tokens.js, not the override CSS files directly.

2. Exported Expo app (generated-expo-app)​

When you export or generate the mobile app, codegen produces a runnable Expo project. Theme files live at the app root, not under src/main/webapp/.

Typical layout:

File or folderRole
design-tokens/foundation/ios/ and design-tokens/foundation/android/Widget style maps and theme variables the runtime loads (style.js, tokens.js, variables.js)
app.designtokens.jsProject-specific color-scheme tokens and variant overrides merged at runtime

Override JSON is compiled into app.designtokens.js and into the foundation style.js / tokens.js output when you export or generate the mobile app.

Example from an exported app (btn-custom variant derived from Style Workspace overrides):

// generated-expo-app/app.designtokens.js (excerpt)
export const variants = {
  "btn-custom": {
    "--wm-btn-background": "var(--wm-color-border-translucent)",
    "--wm-btn-color": "var(--wm-color-error)",
    "--wm-btn-radius": "var(--wm-radius-pill)"
  }
};

Build flow​

When you edit Style Workspace and click Save:

  1. Studio saves your changes as JSON under design-tokens/overrides/.
  2. Codegen compiles those overrides and generates app.override.css.
  3. From app.override.css, codegen produces two outputs:
    • app.studio.override.css for the Studio canvas and mobile preview in Studio
    • app.designtokens.js for the mobile runtime (variants and color-scheme overrides)
  4. When you export or generate the Expo app, theme assets (including app.designtokens.js and design-tokens/foundation/*/style.js and tokens.js) are written into generated-expo-app for the device build.

Foundation CSS stays upgrade-safe because you never patch its source. Your layer stays in override JSON and the compiled artifacts codegen produces.

Override vs new variant​

  • Edit an existing token or variant when you want to change a default the design system already defines (for example the default button background). After you save, that value applies everywhere the token is used, including on widgets you drag onto the canvas later.
  • Create a new variant when you need an extra look for a widget (for example a custom button). Select it on the widget variant property in the Properties panel.

Keep Style Workspace changes in design-tokens/overrides/ in the project. Rely on export to produce the theme files the Expo app actually loads.

Application and page styles​

Use Style Workspace for most theming. When a token or variant is not enough, open the Style tab for app.css (shared across the app) or for a specific page or partial (one screen only).

Use custom CSS only when Style Workspace cannot express the style, the change is limited to one screen, or you are prototyping before moving values into tokens. Prefer widget properties in Studio for a single control.

Do not edit files under design-tokens/foundation/. Export or regenerate the mobile app after Style tab changes so the generated Expo project picks up app.style.js and page *.style.js.