Customer Theme Matching Guide

Reusable process for configuring the Marqo storefront search widget to visually match a customer's existing Shopify theme. Follow these steps for every new customer onboarding.

Prerequisites

Screenshot of the customer's current search/collection page (desktop)
Theme export — download from Shopify admin: Online Store > Themes > Actions > Download theme file
Access to Marqo admin UI for the customer's dev store

Step 1: Extract Theme Export

mkdir -p /tmp/{customer}-theme
cd /tmp/{customer}-theme
unzip ~/Downloads/theme_export__*.zip

Step 2: Analyze Theme Styling

Use the following prompt with an Explore agent to extract all visual values from the theme:

Theme Analysis Prompt

Analyze the Shopify theme at /tmp/{customer}-theme/ to extract all visual styling
details needed to make our Marqo search widget match their current design.

Read these files:
- snippets/card-product.liquid (or similar product card snippet)
- assets/base.css, assets/component-card.css, assets/section-collection*.css
- config/settings_data.json (color schemes, typography, spacing)
- sections/main-search.liquid or sections/main-collection-product-grid.liquid
- snippets/facets.liquid (filter styling)
- snippets/price.liquid (price display)

Extract exact values for each category below. Use actual hex codes, pixel
values, and font names from the CSS/config — do not guess.

### Product Cards
- Card background color
- Card border (radius, width, color)
- Card shadow (none, subtle, medium, strong)
- Card hover effect
- Image aspect ratio (1:1, 3:4, 9:16)
- Content spacing/padding
- Text alignment (left, center, right)

### Text Styles (for each: font family, size, weight, color)
- Product title
- Vendor name (or if hidden)
- Sale price
- Compare-at price (strikethrough)
- Variant title

### Sale Badge
- Position (top-left, top-right)
- Background color
- Text color
- Border radius
- Font size/weight
- Text format (e.g., "SAVE {percent}%", "-{percent}%", "{percent}% OFF")

### CTA Button
- Button text (e.g., "SHOP NOW", "Add to Cart", "Quick View")
- Background color
- Text color
- Border (width, color, radius)
- Full width (yes/no)
- Font size/weight
- Text transform (uppercase, none)

### Reviews / Star Ratings
- Provider (Okendo, Trustpilot, Judge.me, Stamped, Yotpo, etc.)
- Star color (filled)
- Star size
- Review count text color
- Show count (yes/no)

### Filters
- Filter mode (sidebar, drawer, horizontal)
- Background color
- Text color/size
- Separator color
- Accordion icon style (plus/minus, chevron)
- Show product count per option

### Sorting
- Available sort options
- Dropdown styling

### Layout / Grid
- Grid columns: desktop, tablet, mobile
- Column spacing (gap)
- Page title template
- Items per page
- Pagination style (paging, load more, infinite scroll)

### Global Colors
- Primary background
- Secondary/card background
- Primary text color
- Accent/sale color
- Button color

For each value found, provide:
1. The exact value (hex color, pixel size, etc.)
2. The source file and line/selector where you found it
3. Which Marqo UI setting it maps to

Step 3: Map to Marqo UI Settings

Use this reference table to translate theme values to our settings. Fill in the "Customer Value" column from the analysis.

Product Display Settings

Marqo Setting	CSS Variable	Default
`productDisplay.imageRatio`	`--marqo-card-image-ratio`	`1:1`
`productDisplay.cardBorderRadius`	`--marqo-card-border-radius`	`8`
`productDisplay.cardBorderWidth`	`--marqo-card-border-width`	`1`
`productDisplay.cardBorderColor`	`--marqo-card-border-color`	`#e2e8f0`
`productDisplay.cardBackgroundColor`	`--marqo-card-bg`	`#ffffff`
`productDisplay.cardShadow`	`--marqo-card-shadow`	`none`
`productDisplay.cardHoverEffect`	`--marqo-card-hover-*`	`none`
`productDisplay.columnSpacing`	`--marqo-column-spacing`	`16`
`productDisplay.cardContentSpacing`	`--marqo-card-content-gap`	`6`
`productDisplay.columns.desktop`	responsive rule	`4`
`productDisplay.columns.tablet`	responsive rule	`3`
`productDisplay.columns.mobile`	responsive rule	`2`
`productDisplay.alignment`	`data-align`	`left`

Text Styles

Marqo Setting	CSS Variable	Default
`textStyles.vendor.fontFamily`	`--marqo-vendor-font`	`inherit`
`textStyles.vendor.fontSize`	`--marqo-vendor-size`	`12`
`textStyles.vendor.fontWeight`	`--marqo-vendor-weight`	`500`
`textStyles.vendor.color`	`--marqo-vendor-color`	`#64748b`
`textStyles.title.fontFamily`	`--marqo-title-font`	`inherit`
`textStyles.title.fontSize`	`--marqo-title-size`	`14`
`textStyles.title.fontWeight`	`--marqo-title-weight`	`600`
`textStyles.title.color`	`--marqo-title-color`	`#1e293b`
`textStyles.price.fontFamily`	`--marqo-price-font`	`inherit`
`textStyles.price.fontSize`	`--marqo-price-size`	`16`
`textStyles.price.fontWeight`	`--marqo-price-weight`	`700`
`textStyles.price.color`	`--marqo-price-regular-color`	`#059669`
`textStyles.variant.fontFamily`	`--marqo-variant-font`	`inherit`
`textStyles.variant.fontSize`	`--marqo-variant-size`	`12`
`textStyles.variant.fontWeight`	`--marqo-variant-weight`	`400`
`textStyles.variant.color`	`--marqo-variant-color`	`#9ca3af`
`textStyles.collections.fontFamily`	`--marqo-collections-font`	`inherit`
`textStyles.collections.fontSize`	`--marqo-collections-size`	`11`
`textStyles.collections.fontWeight`	`--marqo-collections-weight`	`400`
`textStyles.collections.color`	`--marqo-collections-color`	`#b0b8c4`

Price Display

Marqo Setting	CSS Variable	Default
`priceDisplay.salePriceColor`	`--marqo-price-sale-color`	`#dc2626`
`priceDisplay.compareAtPriceColor`	`--marqo-price-compare-color`	`#9ca3af`
`priceDisplay.showCompareAtPrice`	—	`true`

Sale Badge

Marqo Setting	CSS Variable	Default
`saleBadge.enabled`	—	`true`
`saleBadge.position`	`data-position`	`top-left`
`saleBadge.backgroundColor`	`--marqo-sale-badge-bg`	`#dc2626`
`saleBadge.textColor`	`--marqo-sale-badge-text`	`#ffffff`
`saleBadge.borderRadius`	`--marqo-sale-badge-radius`	`4`
`saleBadge.textFormat`	—	`SAVE {percent}%`

CTA Button

Marqo Setting	CSS Variable	Default
`cta.enabled`	—	`false`
`cta.buttonText`	—	`Shop Now`
`cta.backgroundColor`	`--marqo-cta-bg`	`#000000`
`cta.textColor`	`--marqo-cta-text`	`#ffffff`
`cta.borderColor`	`--marqo-cta-border-color`	`#000000`
`cta.borderWidth`	`--marqo-cta-border-width`	`0`
`cta.borderRadius`	`--marqo-cta-border-radius`	`0`
`cta.fullWidth`	`--marqo-cta-width`	`true`

Reviews

Marqo Setting	CSS Variable	Default
`productReviews.enabled`	—	`false`
`productReviews.provider`	—	`okendo`
`productReviews.starColor`	`--marqo-star-color`	`#f59e0b`
`productReviews.starSize`	`--marqo-star-size`	`16`
`productReviews.textColor`	`--marqo-review-text-color`	`#6b7280`
`productReviews.showCount`	—	`true`

Filter Styling

Marqo Setting	CSS Variable	Default
`filters.filterMode`	—	`sidebar`
`filters.iconStyle`	—	`chevron`
`filters.showProductCount`	—	`true`
`filters.styling.backgroundColor`	`--marqo-filter-bg`	`#ffffff`
`filters.styling.textColor`	`--marqo-filter-text-color`	`#1e293b`
`filters.styling.textFontSize`	`--marqo-filter-text-size`	`14`
`filters.styling.separatorColor`	`--marqo-filter-separator`	`#e2e8f0`
`filters.styling.activeIndicatorColor`	`--marqo-filter-active-indicator`	`#3b82f6`

Sort / Pagination Dropdown Styling

Marqo Setting	CSS Variable	Default
`sorting.dropdownStyling.backgroundColor`	`--marqo-sort-dropdown-bg`	`#ffffff`
`sorting.dropdownStyling.borderColor`	`--marqo-sort-dropdown-border`	`#e2e8f0`
`sorting.dropdownStyling.textColor`	`--marqo-sort-dropdown-text`	`#1e293b`
`pagination.dropdownStyling.backgroundColor`	`--marqo-page-dropdown-bg`	`#ffffff`
`pagination.dropdownStyling.borderColor`	`--marqo-page-dropdown-border`	`#e2e8f0`
`pagination.dropdownStyling.textColor`	`--marqo-page-dropdown-text`	`#1e293b`

Layout

Marqo Setting	Default	Customer Value
`layout.showSearchBar`	`true`
`layout.searchBarText`	`Search for products`
`layout.pageTitleTemplate`	`{count} results found for "{term}"`
`layout.resultsCountStyle.color`	`#6b7280`
`pagination.mode`	`paging`
`pagination.itemsPerPage`	`24`

Step 4: Apply Settings

Two options:

Option A: Admin UI (preferred)

Open the Marqo admin UI and manually enter each value from the table. Use the live preview to verify changes.

Option B: DynamoDB Direct (for bulk setup)

If you have DDB access, update the UIComponentsSettings record for the shop directly. The settings map to UIComponent.value fields as documented in docs/storefront-widget-user-guide.md.

Step 5: Verify

Open the dev store search page
Compare side-by-side with the customer's current search page (screenshot)
Check:
- Card layout matches (columns, spacing, alignment)
- Card styling matches (background, borders, shadows)
- Image ratio matches
- Title font/size/weight/color matches
- Price styling matches (sale color, compare-at strikethrough)
- Sale badge matches (position, color, format)
- CTA button matches (colors, text, shape)
- Review stars match (color, size, count display)
- Filter sidebar matches (background, text, separators)
- Sort/pagination dropdowns match
- Mobile layout matches (drawer mode, column count)
Screenshot the result and compare with the original

Step 6: Document

Save the completed settings table in docs/plans/{customer}-theme-settings.md for reference. Include:

Customer name and website
Date of analysis
Theme name/version
Any custom CSS overrides needed beyond the standard settings
Notes on features that couldn't be matched exactly (and why)

Common Patterns by Theme

Theme	Typical Card Style	Badge Style	CTA Style
Dawn (default)	White bg, rounded corners, subtle shadow	Top-left, rounded pill	Full-width, rounded
Debut	No bg, flat, left-aligned	Top-left, square	Full-width, square
Brooklyn	Gray bg, no border, centered	Top-right, pill	Outlined, centered
Prestige	White bg, thin border, elegant	Minimal, top-left	Text link, no button
Custom/Agency	Varies widely	Varies	Varies

Troubleshooting

Colors don't match exactly:

Check if the theme uses CSS custom properties with RGB values (e.g., rgb(var(--color-foreground))) — extract the actual RGB values from settings_data.json.
Some themes apply opacity to colors — our settings use solid hex values.

Fonts don't match:

We use inherit by default which picks up the theme's font. Only override if the search widget renders in a container with a different font stack.
If the customer uses a premium web font (e.g., Brandon Grotesque), verify it's loaded on search/collection pages.
Adobe Typekit / premium fonts on dev stores: Typekit kits are domain-locked — font files are only served to whitelisted domains. On dev stores, load a close Google Fonts alternative via @import in Custom CSS (e.g., Raleway for Brandon Grotesque) and add a font-family override. Remove the @import and font-family override before deploying to the real store — with fontFamily: "inherit", the widget will pick up the customer's actual font from their theme.

Layout doesn't match:

Check if the theme uses a custom page width or container padding that differs from the search widget's container.
The widget inherits the embed container's width — if the theme constrains it differently, add Custom CSS.

CTA button text case:

Our button renders the text as-is. If the customer uses uppercase, set buttonText to "SHOP NOW" (already uppercase).
For CSS-driven uppercase, add to Custom CSS: .marqo-cta-button { text-transform: uppercase; }

Prerequisites​

Step 1: Extract Theme Export​

Step 2: Analyze Theme Styling​

Theme Analysis Prompt​

Step 3: Map to Marqo UI Settings​

Product Display Settings​

Text Styles​

Price Display​

Sale Badge​

CTA Button​

Reviews​

Filter Styling​

Sort / Pagination Dropdown Styling​

Layout​

Step 4: Apply Settings​

Option A: Admin UI (preferred)​

Option B: DynamoDB Direct (for bulk setup)​

Step 5: Verify​

Step 6: Document​

Common Patterns by Theme​

Troubleshooting​