Use this checklist when integrating SmartSize with a custom or heavily modified Shopify theme. Complete each step in order to verify that SmartSize loads, displays, and functions correctly on your storefront.

Before you start

You need:

a live Shopify store with a custom or modified theme
access to the Shopify theme editor
a published product to test with
SmartSize installed and at least one size chart or fit quiz created

Architecture notes

SmartSize is built with Preact, styled-components, and Nanostores, bundled as an IIFE widget that renders inside a Shadow DOM. It communicates with the Shopify storefront through app embeds and app blocks.

Breakpoints: Mobile = max-width: 768px
Coordinate system: The mannequin visualization uses a 600×615 coordinate space with CSS transform: scale()
Font loading: The widget loads its own fonts to avoid theme dependencies

Step 1: Verify theme supports app embeds

Most standard Shopify themes (Dawn, Refresh, Craft, etc.) support app embeds. Custom and headless themes may not.

[ ] Open the Shopify theme editor for your live theme.
[ ] Go to App embeds in the left sidebar.
[ ] Confirm that the SmartSize app embed appears in the list.
[ ] If SmartSize does not appear, your theme may bypass standard Shopify theme architecture. You may need a custom integration using the JavaScript API or manually placed script tags.

If app embeds are not supported: See SmartSize app embeds for custom themes and JavaScript API overview for alternative integration paths.

Step 2: Add required theme hooks

SmartSize needs specific DOM hooks to anchor the popup and inject scripts correctly.

[ ] Confirm the product page template includes a <head> section where app embed scripts can load.
[ ] Confirm the product form or product information section has a stable container element for button placement.
[ ] If using automatic placement, verify the product form has a standard Shopify structure (form with action="/cart/add").
[ ] If automatic placement fails, switch to floating button or app block placement in SmartSize Global settings.

Test: Save the theme and load a product page. Check the browser DevTools Elements panel for a <smartrecom-host> or Shadow DOM container.

Step 3: Turn on app embeds and save

[ ] In the Shopify theme editor, find SmartSize in App embeds.
[ ] Turn on the Size chart app embed (if using size charts).
[ ] Turn on the Fit quiz app embed (if using fit quizzes).
[ ] Click Save.
[ ] Wait for Shopify to confirm Changes saved.

Step 4: Verify SmartSize loads on the storefront

[ ] Open a live product page (not the theme editor preview).
[ ] Open browser DevTools → Console.
[ ] Type window.SmartRecom and press Enter.
[ ] Confirm the output is an object (not undefined).
[ ] Type window.SmartRecom.isReady() and confirm it returns true.
[ ] If isReady() returns false after 5 seconds, check the Network tab for blocked scripts or CORS errors.

Step 5: Test the SmartSize button

[ ] Look for the Size Chart or Find my size button on the product page.
[ ] If the button is missing:
Check that a size chart or fit quiz is Active in SmartSize
Check that the product matches the product display rules
Try floating button placement in Global settings
See SmartSize button is missing from my product page
[ ] Click the button and confirm the popup opens.
[ ] If the popup does not open, check the Console for JavaScript errors.

Step 6: Test the quiz flow (if using fit quizzes)

[ ] Open the fit quiz popup.
[ ] Complete each step (measurements, multiple choice, bra size if applicable).
[ ] Confirm the size recommendation appears on the winner screen.
[ ] Verify the recommended size is displayed prominently.
[ ] Check that the size chart opens correctly from the recommendation screen.

Step 7: Test the size chart (if using size charts)

[ ] Open the size chart popup.
[ ] Confirm the table displays correctly with no cut-off columns.
[ ] Verify measurements are readable.
[ ] Check that images load and are not broken.

Step 8: Test on mobile

[ ] Open a product page on a mobile device or use browser DevTools device emulation.
[ ] Tap the Size Chart or Find my size button.
[ ] Confirm the popup fits within the screen.
[ ] Verify text is readable without zooming.
[ ] Check that the close button is easy to tap (minimum 44×44px).
[ ] Scroll through quiz steps and confirm no content is clipped.
[ ] Complete the quiz and confirm the recommendation screen displays correctly.

Common mobile issues:

Fit labels clipped on the right edge → increase mannequin container padding
Slider initial values too low → verify default values in theme settings
Step dots too small → SmartSize uses a progress bar on mobile by default

Step 9: Verify CSS resilience

[ ] Install a browser extension that modifies page styles (dark mode, font changer).
[ ] Reload the product page and open the SmartSize popup.
[ ] Confirm the popup appearance is unchanged by the extension.
[ ] Check that fonts, colors, and spacing inside the popup match SmartSize's intended design.

If styles are affected: See Styling resilience and conflict prevention.

Step 10: Validate accessibility

[ ] Navigate the quiz using only the Tab key.
[ ] Confirm all interactive elements (buttons, inputs, options) are focusable.
[ ] Verify focus indicators are visible.
[ ] Confirm the Escape key closes the modal.
[ ] Check color contrast with a browser extension or DevTools.
[ ] Verify screen reader announcements for the recommendation result.

Step 11: Test after theme updates

After any theme code update, repeat steps 4–8:

[ ] SmartSize loads (window.SmartRecom.isReady()).
[ ] Button appears.
[ ] Popup opens.
[ ] Quiz completes.
[ ] Mobile experience is correct.

If SmartSize stops working after a theme update: See SmartSize stopped working after a theme change.

Check the result

After completing this checklist, you should have:

SmartSize app embeds active on your live theme
The SmartSize button visible on product pages
The popup opening and closing correctly
The quiz or size chart rendering without layout issues
A clean mobile experience
No visual interference from browser extensions or theme CSS
Accessible keyboard navigation

Next steps

Customize the popup appearance with your brand colors and fonts.
Trigger the modal programmatically from custom buttons.
Listen to quiz events for analytics or UI updates.

SmartSize app embeds for custom themes — Reference for embed block IDs and hooks
CSS customization reference — Complete class list for styling
Styling resilience and conflict prevention — How SmartSize prevents theme conflicts
SmartSize button is missing from my product page — Troubleshooting visibility issues

Custom theme integration checklist