Theme migrations
Goal
Let an agency offer clients multiple developer-owned themes without making a layout change silently lose customer content.
Matching rule
Content maps through stable semantic slotId values, never CSS selectors, display order, or raw HTML. A slot also declares its component type. Theme switching compares the current and target manifests before a change is applied.
| Result | Editor behavior |
|---|---|
| Preserved | Same slot ID and component type; retain its typed content. |
| Missing | Current slot does not exist in the target; require retain for later, export, map, or discard confirmation. |
| Added | Target slot is new; populate theme default content or ask the editor to configure it. |
| Incompatible | Slot ID matches but component type differs; require an explicit component migration. |
Appearance changes
Semantic colors, font families, the type scale, font weights, line heights, and shape treatment are appearance-only. They do not touch content documents and should preview immediately. Grid geometry, order, placement, responsive breakpoints, and content-bearing slots are layout. Component spacing is layout when changing it can affect structure or content fit.
Every conforming component consumes the same required appearance roles, so a theme does not need component-specific knowledge to choose a readable heading, card surface, form control, or primary action. See Theme appearance and component layout.
Approval flow
- Developer publishes a theme version with a versioned layout manifest and migrations.
- The client selects an agency-approved target theme.
- WiseWig generates a migration report and preview document.
- An authorized user resolves every missing or incompatible slot.
- The migration writes a new draft version; publish remains separate and reversible.