Skip to main content

Migrate a Non-Design System Project to a Design System Project

Overview​

This guide explains how to use the wm-design-system-migrator AI Skill to convert an existing non-Design System WaveMaker project into a Design System project. The skill automates platform compatibility updates, layout modernisation, and design token extraction — producing a Studio-importable package that is functionally identical to the original. After importing, you complete the migration by refining the visual layout of each page using WaveMaker AI.

Prerequisites​

Before you begin, make sure you have:

  • The source project zip — your existing non-Design System WaveMaker project exported from Studio.
  • An empty Design System project zip — downloaded from the target version of Studio where you intend to import the migrated project.
  • Access to the Design System Project Migrator skill from the WaveMaker Marketplace.

Stage 1 — Install the Migration Skill​

  1. Open the WaveMaker Marketplace and locate the Design System Project Migrator skill.
  2. Install the skill into your WaveMaker AI environment.

Stage 2 — Run the Migration​

  1. Launch the wm-design-system-migrator skill from WaveMaker AI.

  2. Upload your non-Design System project zip when prompted.

  3. The skill processes the migration automatically across three steps:

    • Design System Conversion — Updates project and runtime versions, converts metadata, migrates template configuration to PRISM, replaces legacy variable types with actions, updates package scopes, migrates theme artifacts to design tokens, and preserves migration history.
    • Auto Layout Conversion — Replaces unsupported grid and linear layout elements with auto layout-compatible containers: wm-layoutgrid → wm-container, wm-gridrow → wm-container, wm-gridcolumn → responsive containers, wm-linearlayout → flex-based containers, wm-linearlayoutitem → responsive container structures.
    • Studio-Ready Packaging — Bundles the migrated project into a Studio-importable package.

  4. Download the generated Studio-Package once the skill completes.

Stage 3 — Import into Studio​

  1. Open the target version of Studio where you want to run the migrated project.
  2. Create a new project by importing the empty Design System project zip (your prerequisite).
  3. Import the Studio-Package generated by the skill into this project.
note

After import, the application is functionally identical to the original — same backend, pages, and services. However, the visual layout will appear distorted and requires manual refinement before it is production-ready.

Stage 4 — Refine the UI​

This final stage is manual and must be completed page by page:

  1. Open a page in Studio.
  2. Capture a screenshot of the page as a visual reference for what to rebuild.
  3. Use WaveMaker AI's screenshot-to-code capability to recreate the page's UI layout.
  4. Apply layout adjustments and create the appropriate design variants using StyleWorkspace.
  5. Repeat for each page in the application.
tip

Take screenshots of the original application before migration and keep them alongside Studio. They give AI a precise target when recreating each page's layout.

Limitations and Constraints​

ConstraintDetails
UI distortion after importVisual layout will not match the original; manual page-by-page refinement is required
Legacy LESS themesMigration of LESS-based themes is not yet fully automated
Container spacing and alignmentAutomated handling of spacing and alignment within containers has limited coverage in the current version
Highly customised layoutsComplex or project-specific layout customisations may require additional manual work beyond Stage 4
Responsive behaviourAutomated responsive behaviour migration has limited coverage in the current version

See Also​