Migration Guide#

This guide walks you through applying Theme Editor integration to an existing custom theme or a fork of Shadows that predates 26.01.00. Follow the phases in order — working through global components first, then high-traffic pages, then the long tail — to minimize the risk of missing updates or breaking layouts.

Reference Version

The template file paths, component names, and page listings in this guide are based on Shadows 10.13.04 → 26.01.00. If your theme was forked from an earlier version of Shadows, some of the listed templates may not exist, may have different names, or may not have all of the sections shown. Use these lists as a checklist and skip any entries that don’t apply to your build.

Before You Start#

Prerequisites#

Before making any template changes, confirm:

The mm-theme-styles CSS Resource is being emitted on every storefront page. You can verify this by viewing page source on any page and searching for mm-theme-styles. If it’s missing from non-Page-Builder pages, the Theme Editor classes won’t have any rules to apply — typography and buttons will render with browser defaults.
You are on Miva 10.12.00 or later, which is the minimum version that ships the Theme Editor.
You have a development branch of your store’s templates. Work the conversion there, not on the live branch.

Understanding the Three Patterns#

Templates contain three patterns of element that need updating:

Replacement pattern. A legacy Shadows class like c-heading-delta is swapped out entirely for the Theme Editor equivalent.

-<h1 class="c-heading-delta">&mvt:page:name;</h1>
+<h1 class="mm-theme-typography-title-two">&mvt:page:name;</h1>

Additive pattern. The existing class is a structural class (c-menu__title, t-basket__product-name, c-navigation__link) that stays. The Theme Editor class is appended.

-<div class="c-menu__title">Customer Service</div>
+<div class="c-menu__title mm-theme-typography-subheading-small">Customer Service</div>

Compound pattern. The element has a legacy heading or button class combined with one or more structural classes. The heading/button portion is replaced; the structural portions are retained.

-<div class="c-form-list__item c-form-list__item--full c-heading-foxtrot">Log In Information</div>
+<div class="c-form-list__item c-form-list__item--full mm-theme-typography-title-four">Log In Information</div>

-<input class="c-button c-button--full c-button--secondary" type="submit" value="Create My Account">
+<input class="mm-theme-button-secondary mm-theme-button-secondary__small c-button--full" type="submit" value="Create My Account">

For the full catalog of replacement rules, see the Class Mapping Tables.

Migration Phases#

Phase 1 — Global Components#

Update these first. They appear on every page, so getting them right gives you the widest visible impact for the least effort.

Template	Priority elements
`components/hdft.htm`	Site header basket link, account toggle, menu titles, collapsible toggles
`components/readytheme.htm`	All navigation links, category tree, menu labels, dialog titles, newsletter block, mobile nav
`components/global_minibasket.htm`	Cart summary heading, item name links, total, discount text, checkout button
`components/searchfield.htm`	Search preview item names
`components/breadcrumbs.htm`	Breadcrumb links
`components/html_profile.htm`	Root `<html>` paragraph-small class (affects site-wide default body text)

Phase 2 — Shared Content Components#

These appear on multiple pages and should be updated before the individual pages that include them.

Template	Priority elements
`components/buttons.htm`	Centralized button templates (AddToBasket, Save, Login, Continue, etc.) — updating this one file updates buttons across every page that uses `<mvt:item name="buttons" param="..." />`
`components/customer.htm`	Account create / edit form, dialog titles, subheading labels
`components/affiliate.htm`	Affiliate account pages
`components/addressbook.htm`	Address book entries, add/edit/delete actions
`components/addressfields.htm`	Address field form layout (used on CADA, CADE)
`components/basket.htm`	Cart title, product names, discount prices, remove/edit actions, continue-shopping button
`components/order_customer.htm`	Order summary addresses, shipping/billing/payment method labels
`components/order_contents.htm`	Order line items, product names, discount prices
`components/view_order.htm`	View-order product names, discount prices
`components/orderhistory_list.htm`	Order history page title, customer service button
`components/subscriptions.htm`	Subscription page title, manage buttons, pagination
`components/subscriptionfields.htm`	Subscription edit form, dialog titles, product-charge amounts
`components/wishlist.htm`	Wish list page title
`components/wishlistitems.htm`	Wish list item names, add-to-cart buttons, pagination, prices
`components/wishlists.htm`	Pagination
`components/affiliatelink.htm`	Affiliate menu links
`components/customerlink.htm`	Account toggle
`components/paymentcards.htm`	Edit payment card link
`components/shipestimate.htm`	Shipping estimate dialog
`components/sitemap.htm`	Sitemap section headings
`components/category_tree.htm`	Category tree heading and links
`components/datepicker.htm`	Date picker cancel button
`components/content.htm`	Content dialog

Phase 3 — Account Pages#

Page	Page Code
Customer Login	`logn.mvt`
Create Account	(covered by customer.htm)
Account Landing	`acln.mvt`
Affiliate Login	`afcl.mvt`
Affiliate Create	`afrt.mvt`
Affiliate Password Reset	`afpw.mvt`
Affiliate Forgot Password	`affr.mvt`
Customer Password Change	`cpwd.mvt`
Change Password Compromised	`cpcd.mvt`
Change Email	`ceml.mvt`
Account Cart Transfer	`acrt.mvt`
Customer Credit Balance	`abal.mvt`
Forgot Password	`fpwd.mvt`
Custom Page Customer Address	`cpca.mvt`
Custom Page Customer Edit	`cpce.mvt`
Custom Page Subscriptions	`csbe.mvt`
Customer Store Receipt	`cstr.mvt`

Phase 4 — Checkout Pages#

Page	Page Code
Order Customer	(covered by order_customer.htm)
Order Selection	`osel.mvt`
Order Payment	`opay.mvt`
Invoice	`invc.mvt`
Order Upsell	`ous1.mvt`, `ousm.mvt`
Upsell Required Attributes	`uatr.mvt`, `uatm.mvt`
Basket Edit	`bske.mvt`
Order Product Charges	`oprc.mvt`
Order Detail List	`ordl.mvt`
Order Status	`ords.mvt`
Order History List	`orhl.mvt`

Phase 5 — Content and Misc#

Page	Page Code
About Us	`abus.mvt`
FAQs	`faqs.mvt`
Contact Us	`ctus.mvt`
Sitemap	`smap.mvt`
Store Returns	`sarp.mvt`
Purchase Order	`prpo.mvt`
Gift Certificate List	`gftl.mvt`
Gift Certificate Redemption	`rgft.mvt`
Store Receipt	`sert.mvt`
Welcome Page (new customer)	`wpck.mvt`
Group Product Charges	`group_productcharges.mvt`
Product Display Product Charges	`product_display_productcharges.mvt`

Phase 6 — Wish List#

Page	Page Code
Wish List	`wish.mvt`
Wish List Store	`wlst.mvt`
Wish List Guest Login	`wlgn.mvt`

Updating theme.css#

Template changes alone are not enough. theme.css contains hardcoded typography and color values that were applied directly in CSS before the Theme Editor integration existed. Once Theme Editor classes own those values, the corresponding legacy CSS declarations must be removed — otherwise they override Theme Editor customizations regardless of what the merchant sets.

Work through theme.css using the diffs below after completing each template phase, or apply all CSS changes in a single pass at the end.

Remove the hardcoded typography from .t-site-footer .c-menu__title — mm-theme-typography-subheading-small now owns font-size and font-weight. Also remove .c-collapsible-menu__label from the selector; the collapsible toggle receives its typography separately via Theme Editor classes on the template element.

-.t-site-footer .c-menu__title,
-.t-site-footer .c-collapsible-menu__label {
-    font-size: var(--subheading-small);
-    font-weight: var(--font-medium);
-    margin-bottom: calc(var(--default-spacing-unit/2));
-}
+.t-site-footer .c-menu__title {
+    margin-bottom: calc(var(--default-spacing-unit/2));
+}

Remove hardcoded color, text-decoration, and the hover rule — mm-theme-button-secondary-navigation now owns these:

 .t-site-footer__content .c-menu__link:not([class*=" u-icon-"]),
 .t-site-footer__content .c-menu__text:not([class*=" u-icon-"]) {
-    color: var(--gray-600);
     line-height: 3;
-    text-decoration: none;
 }

-.t-site-footer__content .c-menu__link:hover {
-    text-decoration: underline;
-}

Inside the @media (max-width: 47.999em) block, remove the toggle’s font-size and font-weight rules — Theme Editor typography classes on the toggle element now own them. Also remove font-weight from the icon child rule:

 @media (max-width: 47.999em) {
-    .t-site-footer .x-collapsible-content__toggle {
-        font-size: var(--paragraph-large);
-        font-weight: var(--font-medium);
-    }
     .t-site-footer .x-collapsible-content .c-menu__title {
         display: none;
     }
     .t-site-footer .x-collapsible-content__toggle [class^=u-icon-] {
         font-size: 0.66em;
-        font-weight: var(--font-medium);
     }

Basket: Subtotal and Table Head Colors#

Remove hardcoded color: var(--gray-600) from the basket subtotal and table head — Theme Editor typography classes now provide the color:

 .t-basket__alt-heading-subtotal {
-    color: var(--gray-600);
     display: flex;
     font-size: var(--default-input-font-size);
     justify-content: space-between;
     margin-bottom: 0;
 }

 .t-basket__table-head {
     border-bottom: var(--default-border-width) solid var(--gray-300);
-    color: var(--gray-600);
     display: grid;
     ...
 }

Basket: Action Link Typography#

Remove the font-size and line-height rule for inline basket action links — Theme Editor link-button classes now own those values:

-.x-edit-basket-item,
-.t-basket__product-remove,
-.t-basket__product-save,
-.t-basket__additional-product-actions {
-    font-size: var(--default-input-font-size);
-    line-height: var(--default-line-height);
-}

Basket: Coupon Form Disabled State#

Update the invalid-input selector to target the Theme Editor button class and update the disabled visual to use opacity instead of hardcoded color:

-.t-basket_coupon-form input:invalid + .c-button {
-    background-color: var(--gray-400);
-    color: var(--black);
-}
+.t-basket_coupon-form input:invalid + .mm-theme-button-primary {
+    opacity: 0.25;
+}

Checkout Steps#

Remove hardcoded color and font-weight from .t-checkout-steps and color from .t-checkout-step--complete — Theme Editor typography classes now supply these:

 .t-checkout-steps {
-    color: var(--gray-600);
     display: grid;
     font-size: 0.625rem;
-    font-weight: var(--font-medium);
     grid-template-columns: repeat(3, 1fr);
     line-height: 2;
     margin-bottom: calc(2 * var(--default-spacing-unit));
     text-transform: uppercase;
 }

 .t-checkout-step--complete {
     border-bottom-color: currentColor;
-    color: var(--black);
     font-weight: var(--font-bold);
 }

Checkout: Customer Summary and Address Toggle#

Remove entire rules for .t-checkout-customer-summary and the color/text-decoration styles on the address/instructions summary elements — Theme Editor classes now own the color and link styling:

-.t-checkout-customer-summary {
-    color: var(--gray-600);
-}

-.t-customer-address-2 summary,
-.t-order-instructions-toggle summary {
-    color: var(--gray-600);
-}

-.t-customer-address-2 summary span,
-.t-order-instructions-toggle summary span {
-    text-decoration: underline;
-    text-decoration-thickness: from-font;
-    transition: text-decoration ease-in-out 0.3s;
-}

Product Charge Amounts#

Remove the standalone typography rules for product charge amounts — mm-theme-typography-price-extra-small and mm-theme-typography-additional-price-extra-small now own these. Also remove color from .t-product-charge__list:

-.t-product-charge__amount-total {
-    font-weight: bold;
-}

-.t-product-charge__amount-original {
-    color: var(--gray-500);
-}

 .t-product-charge__list {
-    color: var(--gray-600);
     display: grid;
     gap: 0 0.5rem;
     grid-template-columns: repeat(2, auto);
     margin-top: 0.25rem;
 }

Category Name (mobile)#

Remove the mobile typography override for .t-category-name — Theme Editor typography classes now own font-size and line-height:

-@media (max-width: 59.999em) {
-    .t-category-name {
-        font-size: var(--title-three);
-        line-height: calc(var(--title-three) * 1.33);
-        margin-bottom: 0;
-    }
-}

Remove hardcoded background-color and color from .t-site-header__basket-link — Theme Editor navigation classes now own these:

 .t-site-header__basket-link {
     align-items: center;
-    background-color: var(--white);
     border: 0 none;
-    color: var(--black);
     cursor: pointer;
     display: inline-flex;
     padding: 0;
-    text-decoration: none;
 }

Working Through a Template#

For each template, use this sequence:

Scan for c-heading-* classes. Replace each one using the Headings → Typography table. Retain any adjacent utility classes (u-text-center, u-color-red, u-block, etc.).
Scan for c-heading--subheading--* classes. Replace each using the Subheadings table.
Scan for c-button classes. Match the full class combination against the Primary and Secondary Buttons table. Keep structural modifiers (c-button--full, c-button--full-small).
Leave c-button--as-link and c-button--as-text untouched. These classes are not converted — skip every occurrence.
Scan for c-dialog__title. Check for attached heading classes and replace them.
Scan for utility classes acting as typography (u-font-small, u-text-medium, u-text-regular, u-color-gray-600, u-color-red on price/discount elements). Use the Utility-Styled Text tables.
Scan for structural navigation classes (c-menu__link, c-menu__text, c-menu__title, c-navigation__link, c-navigation__text, t-basket__product-name, t-global-account-toggle, t-site-header__basket-link, x-category-tree__*, x-mini-basket__*, x-fasten-header__*, x-transfigure-navigation__*). Append the appropriate Theme Editor navigation class.
Scan for product charge and discount markers. Update per the Price and Discount Markers table.

Search-and-Replace Strategies#

Template Search and Replace#

The Template Search and Replace module lets you make bulk class substitutions directly inside the Miva admin — no local checkout or command-line access required. This is the recommended approach for merchants or developers working entirely through the admin UI.

Warning

Template Search and Replace operates on the working branch. Confirm you are on a development branch before running any replacements.

Install the Module#

Go to Settings > Modules.
Search for Template Search And Replace and click Install.

Using the Module#

Navigate to Settings > Utilities > Template Search and Replace.
Enter the legacy class in the Search field.
Enter the Theme Editor replacement in the Replace field.
Review the list of matching templates and select the ones you want to update.
Add a note describing the change, then click Replace.

Warning

Always review every match before confirming. Compound-pattern elements (where a legacy class is mixed with structural classes on the same element) may need manual adjustment after the bulk replace — see Understanding the Three Patterns.

Heading Class Replacements#

Run one pass per class pair. These are pure swaps (replacement pattern) and are safe to apply in bulk:

Search	Replace
`c-heading-alpha`	`mm-theme-typography-display-two`
`c-heading-bravo`	`mm-theme-typography-display-three`
`c-heading-charlie`	`mm-theme-typography-title-one`
`c-heading-delta`	`mm-theme-typography-title-two`
`c-heading-echo`	`mm-theme-typography-title-three`
`c-heading-foxtrot`	`mm-theme-typography-title-four`

Subheading Class Replacements#

Search	Replace
`c-heading--subheading--x-small`	`mm-theme-typography-subheading-extra-small`
`c-heading--subheading--small`	`mm-theme-typography-subheading-small`
`c-heading--subheading--large`	`mm-theme-typography-subheading-large`

Button Class Replacements#

Button replacements are more complex because the Theme Editor requires two classes (a base class and a size class) where Shadows used one. Bulk replace works for the common defaults; compound elements (c-button--full, c-button--full-small) need a manual review pass afterward to confirm the structural modifier was retained.

Search	Replace
`c-button c-button--secondary`	`mm-theme-button-secondary mm-theme-button-secondary__small`

For remaining c-button instances (primary buttons), use the Class Mapping Tables to determine the correct size class before running a replace.

c-button--as-link and c-button--as-text are not converted

Do not replace or modify these classes. Every occurrence of c-button--as-link and c-button--as-text is left exactly as-is during the migration.

Command Line#

If you have the templates checked out locally via mmt checkout, run these commands from the root of that checkout directory. MMT places page templates under templates/ and ReadyTheme content sections (global components) under properties/readytheme_contentsection/.

# Count legacy classes remaining across the full checkout
grep -rnE 'c-heading-(alpha|bravo|charlie|delta|echo|foxtrot)' templates/ properties/readytheme_contentsection/ | wc -l
grep -rnE 'c-heading--subheading--' templates/ properties/readytheme_contentsection/ | wc -l
grep -rnE '\bc-button\b' templates/ properties/readytheme_contentsection/ | grep -v mm-theme-button | wc -l

# Find every file that still contains legacy heading classes
grep -rlE 'c-heading-(delta|echo|foxtrot)' templates/ properties/readytheme_contentsection/

# Find every c-button that doesn't already have a Theme Editor class on the same line
grep -rnE 'class="[^"]*\bc-button\b[^"]*"' templates/ properties/readytheme_contentsection/ | grep -v 'mm-theme-button'

Progress Verification#

After each phase, run the verification commands again to see your remaining work. A fully migrated template file should have:

Zero c-heading-(alpha|bravo|charlie|delta|echo|foxtrot) matches — except in print templates.
Zero c-heading--subheading--(x-small|small|large) matches — except in print templates.
All c-button instances paired with either a Theme Editor button class on the same element, or intentionally excluded (see Classes Deliberately Left Unchanged).

Common Pitfalls#

Replacing the Wrong Half of a Compound Class#

When you see something like c-dialog__title c-heading-foxtrot, only c-heading-foxtrot gets replaced. c-dialog__title is a structural class that stays.

-<h2 class="c-dialog__title c-heading-foxtrot">Shipping Method</h2>
+<h2 class="c-dialog__title mm-theme-typography-title-four">Shipping Method</h2>

Forgetting Structural Button Modifiers#

c-button--full and c-button--full-small control button width and stay on the element, even after c-button and c-button--secondary are replaced.

-<input type="submit" class="c-button c-button--full c-button--secondary" value="Create My Account">
+<input type="submit" class="mm-theme-button-secondary mm-theme-button-secondary__small c-button--full" value="Create My Account">

Missing Utility-Styled Typography#

A <div class="c-menu__title"> renders correctly because its CSS uses font-size: var(--subheading-small).

The Shadows CSS variables that correspond to Theme Editor typography:

CSS Variable	Theme Editor Class to Apply
`--display-two`	`mm-theme-typography-display-two`
`--display-three`	`mm-theme-typography-display-three`
`--title-one`	`mm-theme-typography-title-one`
`--title-two`	`mm-theme-typography-title-two`
`--title-three`	`mm-theme-typography-title-three`
`--title-four`	`mm-theme-typography-title-four`
`--subheading-x-small`	`mm-theme-typography-subheading-extra-small`
`--subheading-small`	`mm-theme-typography-subheading-small`
`--subheading-large`	`mm-theme-typography-subheading-large`
`--paragraph-large`	`mm-theme-typography-paragraph-large`
`--paragraph-small`	`mm-theme-typography-paragraph-small`

Adding the Size Class Without the Base Class#

Theme Editor button classes come in pairs. Both must be present.

- <!-- WRONG - size class alone has no base styling -->
- <input type="submit" class="mm-theme-button-primary__small">
+ <!-- RIGHT - base class and size class together -->
+ <input type="submit" class="mm-theme-button-primary mm-theme-button-primary__small">

Using `__large` for Shadows `--large` Buttons#

The Shadows size scale is offset by one step from the Theme Editor’s scale. Use __medium, not __large, when converting Shadows c-button--large:

-<a class="c-button c-button--large" href="...">Continue</a>
+<a class="mm-theme-button-primary mm-theme-button-primary__medium" href="...">Continue</a>

Over-Applying the Conversion to Icon-Only Buttons#

c-button--as-link and c-button--as-text are not converted at all — leave every occurrence untouched. More broadly, utility buttons with no visible chrome (hamburger triggers, search icon buttons, form control group buttons) are also left as-is. See Classes Deliberately Left Unchanged for the full list.

Forgetting to Update `buttons.htm`#

The components/buttons.htm component defines the Button_Update templates for every named button code used by <mvt:item name="buttons" param="..." />. A single update to this file propagates to every page that uses the buttons item — dozens of pages. Don’t skip it.

After the Migration#

Once you’ve worked through all six phases:

Run the verification commands from Progress Verification to confirm no legacy classes remain outside the intentional exceptions.
Walk through the pages in your Testing Your Integration checklist with a customized Theme Editor configuration to confirm every element picks up the customization.
Commit the changes as a single focused commit (or series of commits, one per phase) so future developers can audit the conversion.
Update your theme’s changelog to note that Theme Editor integration has been enabled.