migrate-from-BUI-to-WDS.md

BUI → WDS Migration Playbook

Context

Migration of panels from Wix Base UI (wix-base-ui) to Wix Design System (@wix/design-system) in bookings-calendar-catalog-viewer. This is a prerequisite for Dark Mode in Studio 2.0. The plan defines the repeatable process for migrating each panel.

Execution Model

Steps are assigned to either the main conversation (for user interaction) or subagents (for autonomous work):

Step	Executor	Type
1. Audit	Subagent	Explore
2. Rename as Deprecated (separate PR)	Subagent	general-purpose
3. Feature Toggle Setup	Subagent	general-purpose
4. Migrate using /migrate-bui-to-wds	Subagent	general-purpose
5. CSS Cleanup + Global CSS Import	Subagent	general-purpose
6. Build & Test	Subagent	general-purpose
7. Punch List & Fix Loop	Subagent	general-purpose

Per-Panel Migration Steps

These steps should generally follow the way migration was done in https://github.com/wix-private/bookings-calendar-catalog-viewer/pull/5635

Step 1: Audit ⚡ Subagent (Explore)

• Identify all BUI imports in the target panel (Composites.*, TextLabel, Divider, etc.)
• Identify BUI-specific SCSS (imports from wix-base-ui, className overrides)
• Flag any known migration gaps (TODO(wds-migration): @WDS_MIGRATION_GAP)

Step 2: Rename Old Code as Deprecated ⚡ Subagent (separate PR)

• Rename Settings → DeprecatedSettings (and update all existing references accordingly)
• If and only if SharedSettings exists:
  1. rename SharedSettings to DeprecatedSharedSettings (and update all existing references accordingly)
  2. rename Settings.mobile to DeprecatedSettings.mobile (and update all existing references accordingly)
• This change should be done in a separate PR, to make it clear that the renamed files are only renamed and not changed. Later, we will migrate the renamed components back into Settings and Settings.mobile and SharedSettings.
• In order for the artifact to remain working in production after the rename, add a Settings/index.tsx file the default-exports the DeprecatedSettings/index.tsx, and if Settings.mobile is renamed, do the same there.
• Ask for approval before pushing and creating this PR.
• SharedSettings partial deprecation: If Settings only imports specific components from SharedSettings/ (not the whole folder), deprecate only those components (e.g. SharedSettings/ComponentX/ → DeprecatedSharedSettings/ComponentX/), not the entire SharedSettings/ directory. This keeps non-deprecated components available for the new WDS path.

Step 3: Feature Toggle Setup 🧑 Main (user input)

• Decide on a FT name. in the format specs.bookings.<artifactName>MigrateFromBUIToWDS
• Wire experiment in entry point gate: experiments.enabled(EXPERIMENT) → WDS path, else → Deprecated path
• Create entry point Settings/index.tsx with experiment gate:
  1. It should render WDS settings when FT is enabled and the Deprecated BUI settings when the FT is disabled
  2. Both settings should be loaded lazily (using React.lazy), to avoid loading both UI libraries
• If SharedSettings exists, create Settings.mobile/index.tsx with same pattern of lazy load with FT

Step 4: Migrate using /migrate-bui-to-wds ⚡ Subagent

• Create new WDS versions of all settings components in Settings/ and SharedSettings/ using the /migrate-bui-to-wds skill.
• Tell the skill the source deprecated directory, and instruct it not to change the source, but migrate into the target directory.
• If a component has test files (spec or driver), copy them as well to the target directory and update them to use WDS.
• Important The @wix/bookings-editor-ui artifact is using BUI. @wix/bookings-breakpoint-indication is a clone that uses WDS. In migrate code, use @wix/bookings-breakpoint-indication instead of @wix/bookings-editor-ui
• Create *.stories.tsx for each migrated component as part of the migration (CSF3 format, 290px settings panel decorator)
• If needed, create a StorybookProviders component to wrap all the providers needed for stories.
• Add these scripts in artifacts package.json:

    "storybook:start": "yoshi-flow-editor storybook start",
    "storybook:build": "yoshi-flow-editor storybook build",

Step 5: CSS Cleanup + Global CSS Import ⚡ Subagent

• Don't migrate BUI-specific SCSS imports
• Replace custom padding/margin with WDS spacing tokens (SP1, SP2, etc.)
• Use Box layout props (direction, align, verticalAlign) instead of custom CSS where possible
• Ensure root component imports @wix/design-system/styles.global.css

Step 6: Build & Test ⚡ Subagent

• Run yarn && yarn build to confirm everything compiles
• Run unit tests (yarn test)
• Run the storybook:start script in the background, and keep track of the storybook local URL.
• Open the storybook URL in a browser, then open every story and check that it opens without an error and that it and look good. Check spacing, alignment, and interactive states
• Log each error you encounter.

Step 7: Punch List & Fix Loop ⚡ Subagent

• Review migrated files: no remaining BUI imports in WDS path, using spacing tokens instead of pixels
• Create a punch list of remaining problems
• Fix issues from the punch list
• Re-build and re-test until clean