Guild AI context

Documentation scope: Guild 0.1.x pre-release builds. The exact public release version will be confirmed in the changelog before Theme Store publication.

Public Markdown context for merchants who want to use ChatGPT, Claude, Gemini, or another AI assistant while configuring Guild. It is meant to keep AI guidance close to the actual theme editor instead of generic Shopify advice.

Last updated: 2026-09-30 Theme: Guild Theme version: 0.1.0 Audience: Shopify merchants and support assistants Primary use: Copy or upload this file to an AI assistant before asking for help with Guild setup.

Task-first public guides

Use the full context below when broad theme knowledge is needed. For focused merchant tasks, prefer these shorter guides:

• Navigation and page structure
• Commerce and product discovery
• Forms, popups, and advanced content
• Theme editor workflow
• Why content is missing
• Troubleshooting

How an AI assistant should use this file

You are helping a Shopify merchant configure the Guild theme.

Use this file as the source of truth for theme-specific guidance. Give practical setup advice that fits the merchant's page, product data, and content quality. When helping the merchant:

• Prefer Shopify Admin and theme editor settings before suggesting code edits.
• Ask which template or page the merchant is editing before giving detailed setup steps.
• Ask for store context only when it materially changes the recommendation.
• Use the section, block, template, and setting names listed here.
• Do not invent Guild sections, blocks, presets, settings, apps, metafields, or code APIs.
• Do not claim a feature exists unless it is listed here or visible in the merchant's theme editor.
• Do not recommend editing Liquid, CSS, JavaScript, or JSON templates unless the merchant clearly needs developer-level work.
• Do not ask the merchant to paste passwords, private keys, payment data, full customer records, full order exports, or broad admin access details into the chat.
• Do not claim that Guild, an app, an embed, or an AI answer makes the store legally compliant, privacy compliant, cookie compliant, accessibility certified, or Shopify-approved.
• When code is necessary, tell the merchant to duplicate the theme before editing code.
• Keep instructions practical, merchant-facing, and Shopify-native; avoid generic advice that could apply to any theme.
• Separate likely theme setup issues from Shopify data issues, app issues, and custom-code issues.
• Treat the AI context as optional. Do not tell a merchant that AI troubleshooting is required before they can contact Guild support.
• Explain that Guild support provides an initial human response within the published response window.

What Guild is

Guild is a Shopify theme for visually led product brands that sell through curated discovery, shoppable inspiration, and product confidence. The first public demo and listing direction targets the Shopify Home industry category, including decor, lifestyle, furniture, interior, and related curated stores. Home is an industry category and demo focus, not the theme name or a preset name. The normal setup path uses supplied templates and ready-made presets before advanced structural composition or custom code.

Guild is a Shopify Online Store 2.0 theme. It uses templates, sections, blocks, presets, theme settings, dynamic sources, and Shopify-native content such as products, collections, pages, blogs, articles, menus, localization, and customer/account data.

Recommended support style

When answering merchant questions about Guild, use this order:

1. Identify the page or template: home page, product page, collection page, cart, search, blog, article, page, password page, 404 page, or list collections.
2. Identify the relevant section or block.
3. Check whether the missing content is controlled by Shopify data, theme editor settings, a menu, a metafield, a product/collection field, or a third-party app.
4. If the source product, collection, menu, policy, page, metafield, or other Shopify data is missing or incorrect, fix that data in Shopify Admin first.
5. Then suggest the matching theme editor template, section, block, or setting steps.
6. Suggest app configuration only when the feature depends on an app.
7. Suggest code edits only when the task cannot be done through Shopify Admin or theme editor settings.

Good answer format:

This is probably controlled by [section/block/data source].
Check this first: [theme editor path or Shopify admin path].
If that is correct, check: [second likely cause].
Only use custom code if: [condition].

What AI should not do

Do not:

• Assume the merchant has custom metafields unless they mention them.
• Assume a third-party app is installed.
• Suggest copying random Liquid into theme files as the first solution.
• Suggest removing accessibility attributes, focus styles, labels, or semantic markup.
• Suggest editing minified assets or generated package files.
• Tell merchants that custom code is covered by standard Guild support.
• Expose or reference internal development files, audit scorecards, tool instructions, private readiness notes, or implementation task notes.
• Treat this file as a full developer API reference. It is a merchant-facing AI context file.

Important terminology

• Theme editor: Shopify's visual editor under Online Store > Themes > Customize.
• Template: A Shopify page type layout, such as product, collection, page, article, blog, search, cart, password, 404, gift card, or list collections.
• Section: A configurable page area that can be added, moved, hidden, or edited in the theme editor.
• Block: A repeatable content item inside a section.
• Industry category: A Shopify Theme Store classification and demo/merchant-fit direction, such as Home. It is not the theme name, a separate theme, or a theme preset.
• Theme preset: A starting configuration within Guild. It can change starter styling and default configuration, but it uses the same core theme feature library and is separate from the Theme Store industry category.
• Section or block preset: A ready-made structure merchants can add from the theme editor, such as Store highlights, Testimonials, Gallery, or a prepared card layout.
• Theme settings: Global settings for colors, typography, spacing, buttons, inputs, tags, brand assets, social media links, and utility behavior.
• Theme editor workflow: The decision order for whether a change belongs in Shopify Admin, Theme settings, templates, sections, blocks, apps, Custom HTML, Custom Liquid, or code.
• Dynamic source: Shopify content connected to a setting, such as a product field, collection field, page, metafield, or metaobject.
• Custom Liquid: Advanced Shopify Liquid entered by the merchant. Use carefully.
• Custom HTML: Merchant-entered HTML. Use carefully. Trusted social embed code for Instagram, TikTok, X/Twitter, and similar providers belongs here rather than in native Media blocks in the current MVP scope.
• Product media and media blocks: Product media can include images, videos, YouTube/Vimeo external videos, and 3D models where Shopify supports them. Guild media-style blocks can also be used for merchant-configured visual media such as Google map embeds. Social embeds are handled as merchant-controlled Custom HTML / Custom Liquid in the current MVP scope, not as native Media block types.
• Variant: A purchasable option combination such as size, color, material, or finish.
• Collection: A group of products, manual or automated.
• Menu: Shopify navigation content configured in Online Store > Navigation.

Theme structure overview

Guild includes core Shopify templates, global sections, storefront sections, ready-made section and block presets, reusable content blocks, product/collection/blog-specific blocks, advanced layout blocks, form blocks, utility blocks, and theme settings. Guide merchants toward templates and ready-made presets before advanced structural blocks.

Required Shopify templates

Guild includes these core templates or page sections:

• Home page / index template.
• Product page.
• Collection page.
• List collections page.
• Cart page.
• Search page.
• Blog page.
• Article page.
• Standard page.
• 404 page.
• Password page.
• Gift card layout/template.
• Customer account access through Shopify's current customer-account system, the Guild Account block, the required Shopify account component, its customer account menu, and Sign in with Shop. Shopify controls authentication and account pages; Guild does not provide legacy customer account templates. See Shopify's customer accounts and account component documentation for platform behavior.

Global and layout sections

• Header - main storefront header with static Logo, Main menu, optional automatic mega menus, capped/grouped mega menu columns, desktop-only mega menu panels and Custom mega menus with configurable surface padding/color-scheme/shadow behavior, Custom mega menu tabs that can host normal Product lists, Main search with configurable Shopify Predictive search result groups, composable Heading/Buttons/Row - search/Column - search child content, a dynamic Search results button action, a movable/removable Predictive results list with a restricted Product item composition, and Theme Editor preview state, Header controls that preserve merchant presentation on desktop while using compact icon-first controls on small mobile screens, optional Top bar utility content, native Shopify account support, a Shop link that can use Sign in with Shop or Follow on Shop, cart controls, and an automatically composed mobile menu.
• Footer - footer menu, Content list utility areas, social media links, payment methods, localization utilities, the configurable Shop link, support/policy links, and boxed-mode border controls. The Shop link block itself owns Sign in with Shop or Follow on Shop presence; there is no separate Footer visibility gate for Follow on Shop.
• Popup - popup/popup content in the popup group, including automatic popups, media popups, age-blocker-style presets, and configurable backdrop overlay color and opacity.
• Back-to-top button - page utility button.
• Breadcrumbs - breadcrumb navigation where useful.
• Spacer - simple spacing between sections.
• Custom HTML - advanced merchant-provided HTML.
• Custom Liquid - advanced merchant-provided Liquid.

Storefront content sections

Current public section catalog:

• Rich content - flexible all-purpose content layout for cards, text, media, logos, forms, trust bars, utility bars, and custom compositions.
• Hero slideshow - visual hero slides with media and content. Collection and Article Hero slides can use Advanced > Show slide to condition storefront output on the current resource image plus collection description or article excerpt; the Theme Editor still keeps the configured slide visible for editing.
• Image divider - image-led visual separator.
• Media with content - image/video plus text and call-to-action content.
• Google map - map-focused media-with-content section for store locations, showrooms, studios, pickup points, or appointment directions.
• Columns - side-by-side column layouts.
• Boxed content - framed content blocks.
• Featured collection - product merchandising section for a selected collection.
• Featured catalog - collection/category merchandising with Collection cards for all or selected collections.
• Shop the look - editorial shopping section for product discovery.
• Related products - product recommendations section.
• Complementary products - complementary product recommendations.
• Recently viewed - recently viewed product display.
• Related links and text - structured internal links and SEO/supporting text.
• Blog posts - editable article-card display with optional featured article, tags, details, buttons, and blog pagination on blog templates.
• FAQ accordion - collapsible FAQ content.
• Tabbed content - tabbed information layout.
• Countdown banner - campaign or launch countdown.
• Before and after - comparison image/content block.
• Contact form - merchant contact form section.
• Newsletter form - customer newsletter signup.

Global theme settings

Use Theme settings for the global brand and UI baseline before editing individual sections.

Available global setting groups:

• Colors - color schemes and color behavior.
• Typography - body and heading fonts plus their global weight, line-height, letter-spacing, width, style, and transform baselines. Component-level Typography can select the Body or Heading role, Text style independently controls Default/Muted/Italic/Muted italic presentation, and Font weight independently controls Default/Light/Regular/Medium/Semi bold/Bold/Extra bold. Default remains component-owned; there is no global Price font weight setting.
• Font sizes - desktop and mobile sizes for body text, headings, prices, and quotes.
• Layout - global layout behavior.
• Radius - border radius for elements, media, and tags.
• Spacing - body, heading, and section spacing.
• Buttons - global button height and border width.
• Inputs - input radius and border width.
• Shadows - shadow blur and opacity.
• Tags - tag padding and spacing.
• Brand assets - logo, favicon, and social media preview image.
• Social media - social media profile links.
• General utilities - boxed content padding, reduced opacity, and image overlay hover opacity.

Recommended setup order:

1. Configure brand assets: logo, favicon, and social media preview image.
2. Configure colors and typography.
3. Configure font sizes and spacing.
4. Configure buttons, inputs, radius, shadows, and tags.
5. Configure social media links and footer utilities.
6. Build page sections and templates.
7. Review mobile layouts and forms.

Fast setup sequence

When a merchant asks where to start, send them to /first-hour-setup before suggesting custom code. When they are unsure where a change belongs in the editor, send them to /theme-editor-workflow. The preferred first pass is:

1. Theme settings: brand assets, colors, typography, font sizes, spacing, buttons, inputs, radius, shadows, and tags.
2. Header and footer navigation.
3. One useful home page flow: opening visual, catalog route, trust/story content, and optional signup.
4. One real product and one real collection.
5. Cart, search, contact form, newsletter form, policies, and footer links.
6. Mobile preview and publish decision.

If Shopify product, collection, menu, policy, or app data is missing, recommend fixing Shopify Admin content before editing theme code. If a setting appears to do nothing, ask the merchant to check the preview state first: product, collection, cart, search, popup, menu, or dynamic source content may need matching Shopify data before the setting has visible output.

Page setup guidance

Home page

Use the home page to introduce the brand, feature key products or collections, show campaign content, and route customers to the main shopping paths.

Recommended structure for a home/decor/furniture store:

1. Header.
2. Hero slideshow or Media with content.
3. Featured collection or Featured catalog.
4. Shop the look or Rich content cards.
5. Media with content for brand story or materials.
6. Product list, collection list, or editorial cards.
7. FAQ accordion or Tabbed content for trust/support details.
8. Newsletter form.
9. Footer.

Use real product, collection, and brand images. Remove sample/demo content before publishing.

Product page

Use Product spotlight for product media, title, price, variants, quantity, buy buttons, description, trust content, product details, and optional trust and service content such as Product shipping and Back-in-stock request. On a product template it uses the current product; on another page the merchant selects the product in the section settings. Product gallery supports Slideshow/Grid, desktop highlighted-first-media Top/Start/End positioning, a 50-75% highlighted width for Start/End, a Liquid-only thumbnail display limit with a final +x remainder indicator, Grid gap/radius normalization, and full-screen PhotoSwipe. Slideshow-only Controls include arrow visibility, control size, icon style/scale/stroke, border radius, and Background opacity; Grid keeps its full-screen gallery controls on normalized defaults instead of inheriting hidden Slideshow appearance state. Full-screen mode provides one gallery-level magnifier. In Theme Editor previews, real Product gallery media remains authoritative: one real media item stays one item, and synthetic placeholders are added only when the product has no media. In the Variants block, Buttons and swatches creates one control group per product option, while Dropdowns creates one menu per option. Standard Swatches resolve each value through Shopify swatch color, Shopify swatch image, matching variant image, then text, so missing Shopify swatch metadata does not need to render as an empty visual control. If a merchant expects color chips but one product shows variant photography, check that product's Shopify category and connect its Color option to a compatible color category metafield with color entries before changing theme code; blanket and throw products can use Shopify's Blanket color attribute when the assigned category exposes it. Swatch size controls visual swatch geometry through Small, Medium, Large, or Custom values. With Swatch style set to Variant images, a group uses image tiles only when Shopify provides actual variant imagery; otherwise it remains a standard swatch group. Swatch style can also use Boxes for plain text radio boxes such as Size values. Image padding controls spacing only for active image tiles, and Aspect ratio supports Auto, preset, or Custom image proportions. For Swatches and Variant images groups with at least one real Shopify swatch or matching variant-image source, Show selected option value can append the active choice to the label, for example Color: Red; an all-text option named Color, Dropdowns, Boxes, hidden option labels, and text-box fallback groups suppress the duplicate value. Preview option value on hover can temporarily preview a fine-pointer-hovered or keyboard-focused visual value in that label and restores the canonical selected value on mouseout/focusout without changing Product selection state. Coarse-pointer/touch contexts do not receive mouse-hover preview listeners. Use muted selected value mutes only the selected value. Product cards do not show the full picker. In Custom blocks mode, Purchase controls owns Quick view/View options/Add to cart behavior; when its quantity input is enabled, the merchant can hide the visible quantity control on mobile while keeping quantity submission active. The built-in Default product card keeps its own media/title/price/swatch-link fallback and does not synthesize a legacy purchase-action footer. Product metafields is the shared repeatable definition list for Metafield rows, Disclosures rows, and Volume pricing rows, with Default as the initial Item appearance. Metafield children support product metafields, selected-variant metafields, native SKU and Barcode values, manual rows, and optional icon visuals; SKU and Barcode update with the selected variant. Any Shopify list.* metafield value is flattened to escaped comma-separated inline text instead of generating a nested list inside the definition row, while non-list metafields retain Shopify's native typed rendering. Disclosures and Volume pricing inherit the parent's list presentation settings. Build size-guide disclosures with Product Accordion item plus Text or Content source instead of a dedicated Size chart block.

Purchase controls renders no supplemental stock, cart-quantity, or quantity-rule hints. Keep merchant-facing availability in the separate Product inventory block. Native quantity constraints, cart validation, and visible actionable purchase errors remain; successful AJAX add-to-cart status uses a visually hidden live announcement instead of taking layout space. Back-in-stock request collects an email address and unavailable selected-variant context through Shopify's contact-form delivery to the merchant. Its visible content is composed with the same Heading, Text, Form field, Buttons, and Success message blocks as generic Form. The Success message appears after Shopify returns a successful contact-form submission; it is not an inventory notification. Recommend an app when automatic stock-triggered notifications are required. On full Product surfaces, Product price automatically emits Shopify's tax-inclusive disclosure when the active cart/market reports taxes included; product-card adapters remove that repeated disclosure. Product price uses independent Text style and Font weight controls. Font weight: Default follows the main body weight; Light, Regular, Medium, Semi bold, Bold, and Extra bold select explicit weights. There is no separate Product-price Price weight setting. Supporting details Font size can follow the adaptive Default size derived from Price size or explicitly use Main, Caption, or Small; sale tags keep their own typography. When Smaller decimals is enabled with Show from price, the translated From label uses the supporting text size while the primary price decimals remain governed by Price size. Add Disclosures inside Product metafields to read Shopify-native structured disclosure records; it owns only Show labels, renders text-only definition rows, and otherwise inherits the parent list contract. Add Volume pricing in the same parent when quantity-break rows should share that presentation. Product shipping reads the configured product metafield by default and can optionally update from a selected-variant metafield. In variant-aware mode, the selected-variant value has priority, the product metafield is the fallback, and the visible copy updates after variant selection. Empty data hides the storefront component; Theme Editor preview copy is not storefront data. Product shipping does not infer dates from inventory or incoming stock. Product pickup instead reads native selected-variant local-pickup data and renders every returned location through the shared Cards/Card presentation contract; Shopify controls locations, availability, pickup-ready text, addresses, and phone numbers, while the block controls list/card presentation and whether address and phone details appear. Product gallery keeps main-media boxed styling independent from thumbnail boxed styling; thumbnail boxed controls are Slideshow-only and require thumbnails to be enabled. Product visibility group is one generic conditional wrapper with Volume pricing, Product disclosures, Product pickup, Related products, Complementary products, Recently viewed products, Shipping info, Product description, or Product metafield has a value conditions. Product-specific Accordion item and Tab item blocks expose the same ordered Show content when contract. Product metafield has a value uses the configured product metafield namespace and key; Shipping info remains a separate specialized condition for Product shipping, including its variant-aware state. Related, Complementary, and Recently viewed conditions follow the resolved Product-list availability state after asynchronous loading, while variant-aware Product shipping follows the actual dynamic child visibility; legacy shipping groups without that child retain the configured product-metafield check. Unavailable conditional items are omitted, and an Accordion/Tabs parent is omitted if no item remains visible. Shopify XR is available through Buttons > Button > Show advanced options > Action behavior. It uses the standard Button label, icon, and appearance, requires a Shopify 3D model plus Product gallery in the same Product surface, always renders a visual setup preview in the Theme Editor, and appears on the storefront only when Shopify confirms device support. Recommend View in your space with the 3D model icon and place the Button near the gallery. Accordion item keeps a rich-text Dynamic content setting so compatible rich-text metafields can connect, and the entire item is omitted on the storefront when both dynamic and nested content are empty.

Check products with:

• one variant;
• multiple variants;
• sold-out variants;
• long descriptions;
• image, video, and 3D media;
• discount pricing;
• unit pricing, where applicable;
• selling plans, where applicable;
• gift card products, where applicable;
• products with disclosures, size guidance, shipping details, restock prompt links, SKU, or barcode values where applicable.

Useful supporting sections around product content:

• Breadcrumbs.
• FAQ accordion.
• Tabbed content.
• Media with content.
• Related products.
• Complementary products.
• Recently viewed.
• Rich content trust bars or care information.

Collection page

Use collection pages to show collection title, image, description, sorting, storefront filters, product grid, pagination, empty states, and merchandising content. The main Collection section uses a focused picker for collection controls, Collection Hero, product and collection merchandising, compact content, custom code, and app blocks; place unrelated editorial modules in separate sections.

Check:

• collection title;
• collection image;
• collection description;
• product cards and Quick view from collection results;
• empty collection state;
• sorting, including optional mobile border removal and sticky sorting that stays below a sticky Header or Main menu;
• storefront filters, active filter removal, and clear-all behavior;
• filter presentations such as price, list, boolean, swatch, and image filters when Shopify provides them;
• pagination mode: Paginated, Load more, or Infinite scroll;
• JavaScript-enabled AJAX updates and native no-JS fallbacks;
• product images and prices;
• mobile filter drawer and grid readability.

If collection filters are not visible, check Shopify Search & Discovery setup, product data, tags/options/metafields used for filters, and whether the current collection has products matching the filter configuration.

If a Collection Hero is visible in the Theme Editor but not on the storefront, check Slide - collection > Advanced > Show slide and whether the current collection has the image/description required by that choice. The shipped default collection composition uses When collection has an image or description.

List collections page

The shipped list collections page separates curated discovery from the complete catalog: Featured collections uses a small selected set, Shop by room uses selected room collections, and the final All collections section owns the complete paginated or progressively loaded catalog.

Recommended use:

• Keep the curated lists intentional rather than using the first global collections by accident.
• Keep collection titles clear and short.
• Use Shopify collection featured images; Guild uses Shopify's featured-image fallback behavior when an explicit collection image is missing.
• Review mobile spacing, slider behavior, image cropping, and the complete-list pagination or Infinite scroll path.

Cart page

Use the cart page to review line items, quantities, discounts, cart notes, optional cart attributes, totals, and checkout-adjacent actions. The default cart template is assembled from cart-specific layout blocks so cart-only blocks stay in the Cart section rather than normal page sections. The full Cart picker is focused on cart controls, compact trust/navigation content, recommendations, payment methods, custom code, and app blocks; use separate sections for unrelated editorial modules. Guild also provides an optional Slide-out cart in the Popups group. Section visibility controls whether supported AJAX Add to cart actions and the Header cart link open the drawer; the full /cart page remains the direct and no-JavaScript fallback.

Important behavior:

• Quantity controls can update the cart automatically when JavaScript is available. Line totals, summary totals, discounts, optional free-shipping progress, and cart count can refresh through the cart page without a separate customer-facing Update click.
• Cart note and enabled cart attribute edits also save automatically when JavaScript is available.
• The full /cart route remains the navigation fallback when drawer JavaScript is unavailable. Quantity, note, and cart-attribute edits are intentionally automatic-only and do not expose a separate manual Update control.
• Line items can show variant details, public product-form line item properties, selling-plan names, unit prices (inside Cart details before discounts), discounts, upload links, and remove/Undo behavior. Private properties whose names start with _ and internal Shopify properties are hidden.
• Cart summary avoids repeating identical Subtotal and Total amounts: when there is no visible price adjustment and both values match, it shows one Estimated total row. Discounts, the optional estimated-tax row, or another subtotal/total difference restore the explanatory Subtotal and Total rows. Checkout button can optionally append the current cart total, which refreshes during AJAX cart updates. Configurable summary blocks include Checkout button, Order notes, Terms checkbox, Gift wrapping, and Divider. Accelerated checkout is configured inside Checkout button. Gift wrapping and its optional message are cart attributes; the block does not add a wrapping fee. Guild does not provide a manual cart-level discount code input.
• Free-shipping messaging is optional. A threshold of 0 disables it; use a positive value only when it matches the store's real shipping policy. Checkout remains the source of truth.
• If visible Order notes or Terms checkbox is required, standard checkout is blocked until the requirement is satisfied. Accelerated checkout inside Checkout button is hidden in that mode because theme JavaScript cannot reliably gate every dynamic accelerated checkout provider.
• The Cart - empty section is intentionally simple by default: heading, text, and buttons. Merchants can keep it minimal or add relevant product, collection, media, form, Custom HTML, or Custom Liquid content when the recovery path needs more context.
• Flexible content sections share a Height group with an explicit Height type: None, Minimum height, Viewport height, or Aspect ratio. Only the selected height model applies. Sections that expose Advanced options can also use section-level Display mode: Default, Mobile only, Desktop only, Hide on desktop, or Hide on mobile. Mobile only follows Guild's mobile utility through 760px; Desktop only applies above 1000px; Hide on desktop hides above 1000px; and Hide on mobile hides through 760px. The exclusive modes omit the 761-1000px tablet range, while the Hide modes keep that range visible.
• Supported Heading, Row, Column, Box, Media, Divider, Icon, Quote, Star rating, and Breadcrumbs blocks use the same five-value responsive Display mode under Advanced > Show advanced options. Context-specific Row, Column, Box, and supported Media variants follow the same behavior. Recommend this setting when a merchant needs to remove one layout/content block at a breakpoint without duplicating the whole section; do not describe tablet-only controls because they are not exposed in this block setting.
• Background blocks can include Background layer, Background icon, Ticker list, and Clickable area children. Their Advanced controls use the same responsive Display mode contract plus Layer order; Layer order 0 follows the block order, while values from -10 to 10 can override the relative stacking order. Background offsets use a signed 2% grid with 0% available, and Clickable area label styling/alignment is shown only when a label is configured.
• Utility-list spacing is axis-aware. In stacked/default layout, Item spacing controls vertical item spacing. In Inline layout, Item spacing controls horizontal spacing and supported merchant-facing utility lists expose Row spacing for the vertical gap between wrapped rows; Default preserves the historical row rhythm, while None/Small/Medium/Large override only that vertical gap. Use equal row and column spacing, where available, takes precedence. Existing Item spacing: None remains vertical-only for Default appearance; Boxes, Dividers, and Table keep their normal spacing, and horizontal inline spacing is intentionally preserved. Keep items on one line is desktop-only; mobile utility rows wrap normally even when the setting is enabled.
• Product-card Product media > Blend image with background is opt-in and intended for white-background packshots. It affects product images only, not videos, models, placeholders, badges, or overlays.

Check:

• one item and multiple items;
• automatic quantity, note, and cart-attribute changes with JavaScript enabled;
• discounts, including automatic, cart-level, and line-level discount display;
• selling-plan products, if applicable;
• unit-price products, if applicable;
• public line item properties from product forms;
• cart notes and optional cart attributes;
• checkout terms behavior;
• the Cart - empty state with a simple header, text, and button preset plus the full Boxed content-style block picker;
• accelerated checkout buttons, where enabled by Shopify.

Contact page

Use the contact page as a customer-support and location page. It can include a visual intro, Shopify-native contact form, supporting contact details, Google map, FAQ content, and a final support or showroom call to action.

Important behavior:

• Test the contact form on a real storefront or theme preview URL. Localhost preview is useful for layout checks, but live Shopify submission, success/error state, and hCaptcha/CAPTCHA behavior should be checked through Shopify.
• Keep required fields limited to what the store needs. Name, email, topic, message, and one privacy/consent checkbox are usually enough.
• Use the Google map section for showroom, studio, pickup, or appointment locations. The pre-release demo composition includes a sample Portland/Pearl District location, map, opening hours, and directions link; replace all sample location content with the store's own public details before publishing.
• Use FAQ content for response time, order help, appointment booking, shipping support, or return guidance.

Search page

Use Search for products, pages, articles, no-results flows, and customer recovery paths after a broad or misspelled query. The main Search picker is focused on search controls/results, result-aware recovery content, collection/product suggestions, compact content, custom code, and app blocks; use separate sections for unrelated editorial or payment content. Header Predictive search is configured separately in Header > Main search. Optional suggested searches, Collections, Brands, and Page/Article content are requested by Search suggestions child blocks, each with independent heading, Content-list-style presentation, spacing, typography, and Display mode. Brands are derived from matching Product vendors already returned by Shopify Predictive Search, so they do not add a separate request. Predictive-search supporting content can use Heading, Buttons, Row - search, and Column - search; Action behavior: Search results resolves to the current predictive query. Add Predictive results list when Product results should be shown; the block can be moved or removed and provides a Product-focused layout with a restricted Product item composition suited to Predictive Search. The normal Search page continues to use Search results list separately.

Check:

• native Shopify search form behavior with q and options[prefix]=last;
• local Search tabs for Products, Articles, and Pages, including per-panel rendered counts;
• the optional Search results heading, result-aware Search visibility groups and Search filter controls, and Result count based on all results or the active result type;
• Product results rendered with Guild Product cards;
• Article and Page results rendered through the shared configurable Result item template;
• separate Theme Editor sample lists for Product item and Result item, including nested card-block styling;
• an optional Collection cards list for supporting collection discovery, including pre-search placement through Search visibility group;
• empty-search and no-results compositions built with Search visibility group for both an entirely empty query result and an empty active result type;
• pagination mode: Paginated, Load more, or Infinite scroll;
• JavaScript-enabled AJAX updates for Search submit, immediate non-drawer filter changes, drawer Apply actions, pagination, and appended tab counts;
• load-more append behavior and guarded Infinite scroll fallback to the manual button;
• native no-JavaScript search, filter, pagination, and visible-result fallback behavior;
• Product-card Quick view behavior from Search results;
• mobile result-card readability and keyboard tab operation.

Search filters use eligible native storefront filter data when Shopify provides it. Filter types and presentations depend on Shopify Search & Discovery configuration and product data. Do not tell merchants that Guild includes Search sorting or query-matched collection results. Collection cards used as supporting Search content are merchant-configured discovery content, not query-matched collection search results.

Blog and article pages

In Shopify, the Blog template is the article-list or journal page, while the Article template is the individual blog post page. Use both for editorial content, guides, announcements, buying advice, care guides, or brand stories.

The Article section uses the same generic section shell as Rich content and can use Row - article, Column - article, and Box - article for nested layouts that retain the current Article resource.

Article Hero slides can use Advanced > Show slide to require the article image, excerpt, either one, or both on the storefront. The Theme Editor always keeps the configured slide visible so the merchant can edit and preview it.

Check:

• one Article heading configured as the page h1;
• Article excerpt and full Article content from Shopify Admin;
• Author, including optional avatar and fallback behavior;
• Date using Published or Updated source, with optional label;
• Reading time;
• Article media;
• Article tags;
• Article buttons, including missing previous/next boundary items and [title] destination-title replacement;
• app blocks where used;
• article body formatting with headings, images, lists, quotes, tables, embeds, and long links;
• blog cards and shared Article block defaults;
• comments when comments are enabled in Shopify and Show comments is enabled in the Article section.

Guild includes a generic Share current page Button action that uses native device sharing and falls back to copying the canonical URL. It does not ship provider-specific social-network buttons; route those through a suitable app block and keep provider setup, privacy, performance, and API changes within the app-provider boundary.

Default Blog template setup

The default Blog template uses Blog as the Blog post list source and includes manually configured category/tag links that can derive from the current blog URL. Blog post list also supports Selected articles and Related articles. Related articles is intended for Article context, excludes the current post, prioritizes shared tags, fills from the same blog, and does not paginate. Tell merchants to set each category button to the intended tag path or leave the tag blank when the button label should supply the tag path. Featured stories and Start here are editorial modules; Latest articles is the intended paginated/infinite list. Warn that separate lists can still select overlapping articles and require live storefront pagination and duplicate-content testing. Do not describe category links as dynamic filters or claim that an optional custom checkbox controls newsletter subscription.

Default Article template setup

The default Article template contains Breadcrumbs, Article tags, Article heading, Article excerpt, Article details, Article media, Article content, related Blog posts, and Newsletter form. Article detail children can use Date, Reading time, Author, or Summary. Summary generates linked navigation from Article content headings and omits the post title. The Article section inherits the complete Rich content section-setting contract.

For Date, Published date and no label are the compatibility defaults. Updated date and Show label are optional. Author can use the Shopify author account image, optional author title, native bio through Article excerpt, and Author homepage through Article buttons. Previous and Next actions are omitted at blog boundaries. Native sharing is available through a generic Share current page Button action.

Standard page

The default Page template uses Rich content with Content source set to Current page, so the title and body come from Shopify Admin. The current page title is the main heading. When Show page title is enabled, its Title controls include Heading/Body Typography, Body-only Text style, Font weight, Font size, Uppercase, and the block Alignment setting. A manually selected reusable page remains supporting content and its title remains a supporting heading.

For richer pages, add sections before or after the main page content.

Password page

Use the password page for launch, maintenance, or coming-soon stores. Include a clear message and review mobile layout.

404 page

Use the 404 page to provide a clear path back to shopping, search, collections, or the home page.

Gift card page

Use Shopify-issued gift card pages for balance, redemption code, QR, Copy, Print, and Apple Wallet where Shopify provides the pass URL.

The Gift card section uses dedicated Gift card row/column layouts and Gift card-specific content blocks. Optional recipient, message, status, QR, and Apple Wallet output should be described only when Shopify provides the matching issued-card data.

Do not tell merchants to add app blocks to the Gift card page. App blocks are not supported in this section. Route app content to a supported section or follow the app provider's documented gift-card integration.

Keep setup guidance merchant-facing: review the issued-card page, the focused Header/Footer visibility choices, the Copy and Print actions, QR output, optional Apple Wallet action, and print preview.

Section catalog for AI assistance

Use these names when guiding merchants in the theme editor.

Section	Best use	Common setup notes
Header	Logo, Main menu, search, account access, cart access, mobile menu, localization, and optional top utilities.	Configure Logo, Main menu, Main search, and Header controls first. Use Top bar for short utilities. Background opacity remains available when either Use background or Sticky behavior is active, so a sticky Header can stay translucent even when its normal state has no background. When opacity is below 100%, Blur background can strengthen separation from content behind the Header. A Main menu placed below the Header has the same optional blur for its own translucent background. Generated Mega menu headings support Heading/Body Typography, Body-only Text style, Font weight, Font size, Uppercase, alignment, and margin. Use Mega menu panel for controlled desktop promotions or Custom mega menu for a more flexible desktop composition. Keep mobile promotional routes in the Shopify menu, because desktop mega-menu content does not automatically become mobile drawer content. Test nested menus, More overflow, compact search, account, cart, country, and language controls.
Footer	Policy links, contact links, social media links, payment methods, localization utilities.	Keep legal/support links accessible and avoid overcrowding. Footer Navigation headings support Heading/Body Typography, Body-only Text style, Font weight, Font size, Uppercase, and heading spacing. Navigation Columns is a desktop maximum and does not reserve empty tracks when fewer menu groups render.
Rich content	Flexible layouts, trust bars, cards, logo rows, custom compositions.	Best general-purpose section; choose blocks based on content type.
Hero slideshow	Large campaign or brand hero.	Use strong images, short headings, and clear calls to action.
Image divider	Visual break between content groups.	Use decorative or editorial imagery; check mobile crop.
Media with content	Brand story, feature explanation, image/video/3D model plus text.	Keep heading and copy concise. Use Custom HTML / Custom Liquid for trusted social embeds rather than native Media social widgets in the current MVP scope.
Google map	Store location, showroom, studio, pickup, or appointment directions.	Replace the generic sample map, placeholder address, opening hours, and directions link before publishing. Review privacy/cookie implications for external map providers.
Columns	Side-by-side content.	Enable mobile-friendly stacking where needed.
Boxed content	Framed information, notices, trust content.	Use consistent padding and color scheme.
Featured collection	Merchandise products from a collection.	Requires a populated Shopify collection.
Featured catalog	Promote collections/categories or build the list collections page.	Use collection images and clear labels. Use Show all collections for automatic catalog pages or select collections manually for curated sections.
Shop the look	Editorial product discovery.	Pair a strong lifestyle visual with a focused product list, such as a room scene, styled shelf, or campaign image.
Related products	Product recommendations.	Best near product pages; output depends on Shopify recommendation data.
Complementary products	Cross-sell recommendations.	Depends on Shopify product recommendation/complementary data.
Recently viewed	Recently viewed product list.	Requires customer browsing activity in the current browser.
Related links and text	Supporting text and internal links.	Use for collection/category SEO and navigational support.
Blog posts	Editorial article cards.	Requires a Shopify blog with published articles.
FAQ accordion	Frequently asked questions.	Good for product details, shipping, returns, care, and service questions. One-column Default accordions can independently hide their top and bottom outer borders for a lighter edge treatment.
Tabbed content	Grouped supporting information.	Keep tab labels short, especially on mobile.
Countdown banner	Genuine timed campaign, launch, event, or promotion.	Set an explicit end date; a blank end date hides the countdown. Check optional start dates and weekday visibility.
Before and after	Image comparison.	Use matching image dimensions for best results.
Contact form	Store contact form.	Depends on Shopify store email settings.
Newsletter form	Newsletter signup.	Depends on Shopify customer/email marketing setup.
Popup	Popup, modal, age-blocker-style message.	Configure trigger, dismissal, close behavior, overlay, and content.
Back-to-top button	Page navigation utility.	Useful on long pages.
Breadcrumbs	Hierarchical navigation.	Useful on product, collection, article, and page templates.
Spacer	Intentional spacing.	Use sparingly; prefer section spacing settings for general rhythm.
Custom HTML	Advanced HTML.	Duplicate the theme before using risky custom code.
Custom Liquid	Advanced Liquid.	Use only for developer-level Shopify Liquid work.

Reusable block families

Guild uses nested blocks extensively. When helping merchants, describe blocks by purpose rather than file names.

Common block families:

• Text and rich text blocks - headings, body text, labels, captions, quotes, highlighted rich text.
• Media blocks - images, Shopify-hosted videos, YouTube/Vimeo external videos, Google maps, 3D models, icons, logos, product media, Article media, and Collection media. Article thumb and Collection thumb are separate card-only image blocks inside their respective list systems. Instagram/TikTok/X social embeds are not native Media block types in the current MVP scope; use Custom HTML / Custom Liquid for trusted provider embed code.
• Button blocks - links, button groups, utility buttons, popup-triggering buttons. When a compositional Buttons block uses Show in header, keep Button alignment meaningful for the mobile copy even though the desktop header placement is controlled by the surrounding header composition.
• Card blocks - static cards, product cards, collection cards, blog/article cards, and collage cards. Boxed Product, Collection, Blog/Search result, generic/custom, pickup-location, and Logo card items share Border radius values Default, Media, and None; Default keeps the normal theme card radius, and Media follows the shared media radius. On Logo items, the card radius is separate from the logo image radius. For a generic Card, keep Card media as the optional media and bounded overlay-content area, place the main content blocks directly under Card, and use Card footer for content that should remain after the main content. Card footer accepts the same content block choices as Card and Custom card; the default action is Buttons > Button. Do not tell merchants to look for a separate Card content or Card body block.
• Quick view - product-card modal that uses the same configurable Product blocks and Product controller as Product spotlight. The global Quick view popup section is the merchant-facing feature switch: when shown, eligible View options links open the dialog; when hidden or absent, those links go to the product page. It can include variants, selling plans, quantity rules, Product pickup, gift card recipient fields, Product details, purchase controls, and supported app blocks. The shipped popup starts with the same non-gallery Product block composition as the default Product template, while Product gallery remains independently configurable for the popup. Beside-content gallery media uses the popup image width as an upper bound but is capped at 50% of the popup on desktop/tablet, and the gallery edge inherits the popup shell radius. Full-screen gallery/PhotoSwipe and its magnifier are intentionally suppressed inside Quick view. Associated-product, limited variant-data, disclosures, and other full-page-only transitions can intentionally continue on the product page.
• Product details popup - Product-page-only Popup-group section with ordinary Popup behavior and a filtered Product spotlight block pool. Apps and Purchase controls are unavailable directly at the section level. Standard Product Row, Column, Box, and Visibility group blocks retain their normal nested child options. It uses the currently viewed Product for focused informational content such as pickup availability, back-in-stock forms, Product details, metafields, prices, badges, or galleries; Quick view remains the separate complete purchase surface. Only the first top-level Product gallery can become Popup leading media. Supported variant-dependent information follows the main PDP through one-way synchronization; the popup does not control the main PDP selection.
• Product blocks - title, vendor, brand, price, variants, quantity, add-to-cart box, inventory, badges, rating, tags, Product metafields with Metafield/Disclosures/Volume pricing children, description, product media, Product shipping, Back-in-stock request, and optional Line item property fields that can appear in cart line details.
• Product list blocks - can source products from a Collection, a hand-picked Selected products list, Related products, Complementary products, or Recently viewed products. Product list can be placed directly in Product spotlight / Quick view / Product details popup and inside Product-specific Column, Box, and Accordion item composition, so a compact Complementary products list can serve as a "Pairs well with" element near purchase content. Start with product applies only to Collection source and skips earlier collection products; values above 1 intentionally disable pagination. Shopify does not support visible_if on the Collection and Product list picker setting types, so both resource pickers remain visible in Theme Editor with source-specific info text; runtime reads only the picker selected by Product source. Selected products keep picker order unless unavailable-product settings move unavailable items to the end, and an empty Selected products source remains empty rather than silently falling back to Collection. Product lists can use Custom blocks for local full drag-and-drop card composition or Default product card for the built-in fallback renderer. In Custom blocks, Product media can use Use second image as primary to swap the alternate product image into the primary slot. With Show second image on hover enabled, the original primary image becomes the hover image; Default is a plain fade, Hover zoom second image zooms only that hover image, and Hover flip keeps the flip transition. These controls are no-op when fewer than two actual product images exist. Custom lists can add one or more manually selected Limited-time product cards at chosen positions; those cards reuse the regular product-card composition, can contain Countdown and product metafield content, and do not infer promotion progress from inventory. Theme Guild does not expose a global drag-and-drop Shared product card section.
• Collection blocks - collection title, description, media, product count, Collection cards, Collection list, and Collection links. Collection list renders selected/all collection titles through the Content-list-style utility renderer with layout, typography, and link/content color controls. Collection links is the separate Button/Text link group presentation.
• Article blocks - article card, Article heading, Article excerpt, Article details, repeatable Article detail children, Article tags, Article buttons, Article thumb for card lists, Article media, Article content, and contextual Row - article, Column - article, and Box - article layouts. Each Article detail child selects Date, Author, Reading time, or Summary. Date can use Published or Updated output; Author can use the Shopify author account image and optional title; Summary creates linked heading navigation. Article buttons use shared Button renderers with article-aware destinations and optional [title] substitution.
• Form blocks - form rows, columns, input fields, textarea fields, select fields, choice groups, hidden fields, success message. Inline Success message blocks expose the shared Margin control; Alert mode is positioned by the global alert system instead.
• Utility blocks - Logo, Social media links, accessibility controls, payment methods, country selector, language selector, Shop link, copyright, and Content list. Shop link selects Sign in with Shop or Follow on Shop and directly owns whether that action is present. Social media links can show icons only, icons with labels, or labels only; the standalone block can show all configured profiles or a selected subset, switches between Button and Text link presentation, supports optional platform-brand icon accents for Text links, and includes text-link typography/color and block margin controls. Applicable utility-list blocks treat the controls independently: Vertical alignment belongs to Inline layout and offers Top, Center, or Bottom with Center as the default, while Equal column widths appears only for Inline + Space between and lets direct inline items divide the available width evenly. Always-inline utility blocks can expose Vertical alignment without a separate Layout selector. Logo supports image or text modes. Country selector can show a native Shopify flag in normal placements, including flag-only mode, combine country and currency text with parentheses or spaced slash formatting, and renders only when Shopify Markets provides multiple countries or regions. Header mobile navigation intentionally reduces the Country trigger to the full country name and uses a chevron; Language mobile disclosures also always use chevrons. Language selector can show names or codes and renders only when multiple storefront languages are published.
• Layout blocks - row, column, box, divider, Background parent, Background layer, Background icon, Ticker list, and Clickable area. Background child layers can use Advanced > Layer order when their visual stacking needs to differ from the block order.
• Interactive blocks - accordion, accordion item, tabs, tab item, countdown, countup, before-and-after comparison control.
• Advanced blocks - Custom HTML, Custom Liquid.

If a merchant cannot find a block, tell them to check whether they are editing the correct section. Not every block is available in every section.

Data requirements

Many apparent theme issues are actually missing Shopify data. Check these before suggesting code.

Products

Products should have:

• title;
• description;
• product media;
• price;
• variants/options where needed;
• vendor or brand data if displayed;
• inventory tracking if inventory messaging is used;
• product category/type/tags if used for filtering or merchandising;
• metafields if the merchant wants custom specifications, care details, dimensions, materials, or extra badges.

Collections

Collections should have:

• clear title;
• description when needed;
• featured image when the theme displays collection media;
• products assigned manually or by automated conditions;
• SEO title/description where needed;
• filterable product data if collection filters are used.

Menus

Menus are managed in Online Store > Navigation.

Check menus when header/footer menu is missing, wrong, empty, or nested incorrectly.

Pages, blogs, and articles

Pages and articles should be published and contain clean rich text. Avoid pasted formatting from external editors when possible.

Images

For repeated cards or grids, use consistent image dimensions and cropping. Keep important subjects near the center for mobile crops. Avoid putting essential text inside images when possible.

Metafields and metaobjects

Do not assume metafields or metaobjects exist. If a merchant wants structured content, guide them to create definitions and values in Shopify Admin first, then connect them through dynamic sources where Guild exposes a compatible setting. For platform setup, see Shopify's metafields and sections and blocks documentation.

Apps

Do not assume app features are part of Guild. If a merchant uses reviews, subscriptions, search/discovery, bundles, loyalty, chat, or upsell apps, app setup and app conflicts are usually handled by the app provider unless the issue is caused by unmodified Guild behavior.

Common setup tasks

Configure brand assets

1. Open Online Store > Themes > Customize.
2. Open Theme settings.
3. Review Brand assets.
4. Add logo, favicon, and social media preview image.
5. Review header and social preview behavior.

Configure navigation

1. Open Online Store > Navigation.
2. Create or edit menus.
3. Return to the theme editor.
4. Open Header or Footer.
5. Select the correct menu.
6. Preview desktop and mobile.

Build a furniture or home decor home page

Recommended sections:

1. Hero slideshow or Media with content.
2. Featured catalog or Featured collection.
3. Shop the look.
4. Rich content with trust points, services, or delivery information.
5. Media with content for brand/material story.
6. Blog posts or Related links and text.
7. Newsletter form.

Improve a product page

Check:

1. Product media quality.
2. Product title and price visibility.
3. Variant option clarity.
4. Add-to-cart and checkout buttons.
5. Description and specifications.
6. Shipping, returns, care, dimensions, materials, and warranty content.
7. FAQ or tabs for long supporting information.
8. Related, complementary, and recently viewed products.

Improve a collection page

Check:

1. Collection title and description.
2. Collection image.
3. Product card consistency.
4. Sorting, pagination, and product-grid structure.
5. Empty state.
6. Supporting SEO links or text.
7. Mobile grid layout.

Add trust content

Use Rich content, FAQ accordion, Tabbed content, Media with content, Boxed content, Footer, and product-page supporting sections.

Good trust topics:

• delivery;
• returns;
• materials;
• care instructions;
• warranty;
• showroom or pickup information;
• payment methods;
• customer service;
• sustainability, if accurate and supported.

Troubleshooting map

Image is not showing

Check:

• whether the image setting is filled;
• whether the block is hidden or empty;
• whether the product/collection/article has an image;
• whether a mobile-specific crop/aspect setting hides the subject;
• whether the merchant is editing the correct template.

Quick view does not add to cart

Check:

• whether JavaScript is enabled;
• whether the product has a purchasable available variant;
• whether the selected variant is sold out;
• whether the quantity is valid for the product's quantity rules;
• whether an app or custom script is replacing the product form or cart endpoints;
• whether a required selling plan, gift card recipient field, line item property, or other Product-form control is incomplete;
• whether the selected option intentionally opens an associated product or full-page variant-data fallback.

Quick view uses the same Product blocks and Product controller as Product spotlight. First check that the global Quick view section is shown: hiding that section intentionally makes eligible View options actions use their normal product-page links. A transition to the full product page is also expected when an associated product, limited variant lookup, disclosure requirement, or another full-page-only Product flow cannot be resolved safely inside the popup.

Product card is empty

Check:

• whether a product is selected;
• whether the selected collection has products;
• whether products are published to Online Store;
• whether the product source setting is configured;
• whether the card is inside the correct section/block.

Collection description is missing

Check:

• whether the actual live collection has a description in Shopify Admin;
• whether the theme editor is previewing a different collection from the live storefront;
• whether the collection description block/setting is enabled;
• whether translations/locales contain different collection content.

Product shipping does not change with the selected variant

Check:

• Product shipping > Show advanced options > Update by variant is enabled;
• the variant metafield namespace and key match the definition in Shopify Admin;
• each affected variant has a value saved for that metafield;
• the product-level metafield is populated when a fallback message is expected;
• the tested option combination resolves to an actual product variant;
• the test is repeated in an unmodified theme preview when an app or custom script also changes product content.

Guild preserves the current server-rendered message while Shopify resolves incomplete high-variant data. It does not generate a delivery promise from inventory, incoming stock, preorder status, or continued selling.

Shopify XR button is missing on the storefront

Check:

• the Button uses Show advanced options > Action behavior > Shopify XR;
• the normal Button label or icon is configured;
• the selected product has at least one Shopify 3D model;
• Product gallery exists in the same Product surface as the Button;
• the test uses a compatible mobile device and browser;
• the XR Button is not being tested inside a product card.

The Theme Editor always shows the Button shell so its appearance can be configured. That preview is not proof that the current storefront device supports AR. On unsupported devices Shopify keeps the live action hidden. When the XR Button is the only action in a Button group, Guild also hides the empty group on the storefront.

Menu is missing

Check:

• Shopify navigation menu exists;
• Header/Footer selects the correct menu;
• menu items are not empty;
• nested menu depth is supported by the current layout;
• mobile navigation was previewed.

Button is visible but does nothing

Check:

• button label exists;
• link is set;
• button is not configured as a form submit/reset when it should be a link;
• popup control target matches the popup handle;
• custom code or app scripts are not intercepting clicks.

Popup is not showing

Check:

• Popup section exists in the popup group;
• automatic display is enabled if needed;
• delay and dismissal settings;
• target popup handle if opened from a button;
• local browser dismissal memory.

Filters are not visible

Check:

• Shopify Search and Discovery filter setup;
• whether products have filterable data;
• whether the collection has products;
• whether the current template/section supports filter display;
• whether an app or custom code modified collection output.

Search results are incomplete

Check:

• products, pages, and articles are published and searchable;
• Shopify search settings;
• spelling and search query;
• whether the active result type link is limiting the view to Products, Articles, or Pages;
• whether the current pagination mode needs the next page, Load more, or Infinite scroll to reveal additional results;
• whether custom code or apps changed search behavior.

Guild Search can include Shopify storefront filters for eligible result scopes when filter data is available, but it does not include Search sorting. Check active filters before diagnosing incomplete product results; article-only and page-only result scopes do not show product filters.

Country or language selector is missing

Check:

• whether Shopify Markets provides more than one country or region to the Online Store;
• whether more than one storefront language is published;
• whether the matching utility block is added in a supported Header or Footer content area;
• whether the merchant saved/refreshed the theme editor after changing Markets or languages;
• whether the storefront is being previewed in the intended market/language context.

A selector with only one valid choice can correctly remain hidden. Fix Shopify configuration first; route to Guild support only when multiple valid options exist and an unmodified Guild selector still fails to render.

Form does not submit

Check:

• required fields;
• whether contact forms were tested on a real storefront or theme preview URL, not only localhost;
• Shopify store email settings for contact forms;
• newsletter/customer settings for signup forms;
• success message block/setting;
• Shopify hCaptcha/CAPTCHA behavior;
• app or custom script conflicts.

Guild contact forms use Shopify's native contact form flow. Avoid replacing the submit path with custom AJAX unless a separate integration is intentionally being built and tested. Forms created through Custom HTML, Custom Liquid, or an app are owned by their code author or provider and must be tested separately for endpoint behavior, validation, success/error output, accessibility, spam protection, consent, and data handling.

Mobile layout looks wrong

Check:

• mobile preview in the theme editor;
• section spacing on mobile;
• image crop/aspect ratio;
• heading length;
• button label length;
• column stacking settings;
• hidden/conditional mobile settings if present.

Product details or metafield content is missing

Check:

• whether the source content exists in Shopify Admin;
• whether the current product has a value for the selected metafield;
• whether the product template includes the matching description, disclosure, size-chart, page-content, text, or dynamic-source block;
• whether the merchant is previewing the correct product and template.

Do not suggest code to manufacture missing product data. Fix the Shopify source data first.

Related, complementary, or recently viewed products are empty

Check:

• whether the page is a real product page;
• which Product source is selected;
• whether Shopify provides related recommendation data for that product;
• whether complementary products were configured in Shopify Search & Discovery when manual setup is required;
• whether recommended products are active and available to the Online Store channel;
• whether the customer viewed other products in the same browser before testing Recently viewed;
• whether browser storage, privacy settings, an extension, an app, or custom code changed the source behavior.

A first visit or cleared/blocked browser storage can correctly leave Recently viewed empty, and Shopify may not return related recommendations for every product or store state. If valid source data or same-browser history exists but the Guild section does not render it in an unmodified theme, route the merchant to Guild support with the product URL, template, selected source, setup details, browser, and visible result.

App block or app embed is missing

Check:

• whether the app is installed and enabled for the current theme;
• whether the app requires an App embed toggle;
• whether the selected Guild section supports Shopify app blocks;
• whether the app's own account, targeting, and data setup is complete;
• whether the underlying Guild layout works with the app disabled in an unpublished duplicate.

Route app-owned setup and output problems to the app developer. Route a missing or broken documented Guild insertion point to Guild support.

Issue appeared after a Guild update

Check:

• previous and current Guild versions;
• the Guild changelog and update guide;
• whether the issue appears in the updated unmodified theme before apps or custom code are reapplied;
• the affected URL, reproduction steps, and recent changes.

For a serious live regression, recommend republishing the previous theme while the updated copy is investigated.

Custom code caused an issue

Tell the merchant:

1. Duplicate the theme before editing code.
2. Test the issue on an unmodified copy of Guild.
3. Remove or disable the custom code and test again.
4. Contact the app developer or code author if the issue only happens with custom code or a third-party app.

Custom code is not included in standard Guild theme support unless support explicitly confirms otherwise.

Safe custom-code guidance

Only suggest custom code when theme editor settings, Shopify Admin data, and app settings cannot solve the task.

Before suggesting code, say:

Duplicate your theme before editing code. Custom code can affect updates, the support scope for issues caused by the modification, accessibility, performance, and storefront behavior. For advanced changes, consider hiring a Shopify Partner.

When a merchant asks for code:

• Ask which theme version they use.
• Ask which template/section should be changed.
• Keep the change small and reversible.
• Avoid editing global behavior unless required.
• Avoid changing checkout behavior.
• Avoid removing accessibility behavior.
• Explain that future theme updates may overwrite custom changes.

Update guidance

When a merchant asks about updating Guild:

• Tell them to duplicate the current live theme first.
• Tell them to add or review the updated theme as an unpublished theme before publishing.
• Tell them to read the changelog and test critical storefront paths.
• Remind them that custom code, Custom HTML, Custom Liquid, app-specific styling, and modified theme files may need to be reapplied or adjusted after an update.
• If an issue appears after updating, ask whether it also happens in an unmodified copy of Guild.
• For urgent storefront issues after publishing an update, tell them to publish the previous theme again while they investigate.

Use /updating-guild for the full update checklist.

Support boundaries

Standard Guild support includes:

• help with documented theme settings;
• questions about expected Guild behavior;
• bug reports for unmodified Guild behavior;
• guidance on using theme sections and templates.

Standard Guild support does not include:

• custom development;
• third-party app setup or conflicts;
• store setup and product data entry;
• custom design services;
• marketing strategy;
• unsupported code tutorials;
• debugging heavily modified theme code.

When contacting support, merchants should start with:

• first and last name;
• email address;
• store URL;
• Guild version;
• the closest public issue category;
• one clear description of what they are trying to do and what happened.

For suspected bugs or update regressions, ask for the affected page/template, reproduction steps, expected and actual behavior, and recent app/custom-code/Guild-update changes only when needed for the next ownership decision. Ask for browser/device only when relevant. An unpublished, unmodified duplicate result and a redacted screenshot or short recording are optional diagnostics, not prerequisites for opening a ticket.

Tell merchants not to send passwords, private keys, payment data, full customer records, full order exports, collaborator codes, full theme ZIPs, or broad admin access details through support requests. If a bug appears to affect shopping, navigation, product forms, cart updates, checkout handoff, or broad storefront rendering, tell them to describe it as a critical bug and include exact reproduction steps if available; do not delay the report solely because an unmodified duplicate test is not possible.

Privacy and external-service boundaries

When a merchant asks about privacy, cookies, external embeds, maps, videos, app blocks, Custom HTML, or Custom Liquid:

• Treat Guild documentation as setup guidance, not legal advice.
• Use Shopify customer privacy settings and the merchant's store policies as the primary place for store-level privacy configuration.
• Tell the merchant to review third-party provider terms and cookie/privacy behavior before publishing external embeds, maps, videos, app blocks, pixels, or custom scripts.
• Do not promise that a theme setting, embed choice, or AI-provided snippet makes the store legally compliant.
• For support screenshots or recordings, ask the merchant to blur customer, order, payment, email, address, and personal information unless it is necessary to reproduce the issue.

Use /privacy-and-external-services for the full merchant-facing guidance.

Good merchant prompts for AI

Home page setup

I use the Guild Shopify theme. Help me build a home page for a home decor store. Ask only the necessary questions, then suggest which Guild sections to use and in what order. Prefer Shopify Admin and theme editor settings over custom code.

Product page improvement

I use the Guild Shopify theme. Help me improve my product page for a furniture product. Focus on product media, variants, price, trust content, care details, dimensions, recommendations, and mobile layout. Prefer theme editor settings over custom code.

Collection page improvement

I use the Guild Shopify theme. Help me improve my collection page for a curated catalog. Focus on title, description, image, sorting, product cards, pagination, empty states, SEO text, and mobile layout. Prefer Shopify-native setup over custom code.

Header and footer setup

I use the Guild Shopify theme. Help me configure my header and footer. Ask for my menu structure, logo, social media links, policy links, and localization needs, then suggest the best setup in the theme editor.

Troubleshooting

I use the Guild Shopify theme. I have this issue: [describe issue]. Ask me for the minimum information needed, then help me check likely causes in Shopify Admin and the theme editor before suggesting code.

Custom CSS request

I use the Guild Shopify theme. I want a small CSS adjustment for [specific section/page]. Before giving code, tell me whether this can be done in the theme editor. If code is needed, keep it small, explain where to add it, and warn me about duplicating the theme first.

AI answer checklist

Before finalizing an answer about Guild, check:

• Did you use an actual Guild section, block, template, or theme setting name from this file?
• Did you prefer Shopify Admin/theme editor setup before custom code?
• Did you avoid assuming apps/metafields/custom data exist?
• Did you ask for the page/template when needed?
• Did you separate theme behavior from Shopify data and app behavior?
• Did you include a theme-duplication warning before custom code?
• Did you avoid referencing internal development files or private task notes?

Related public documentation

Use these public documentation pages for deeper guidance:

• /getting-started
• /theme-settings
• /sections
• /templates
• /troubleshooting
• /faq
• /support-policy
• /privacy-and-external-services
• /updating-guild
• /contact-support
• /changelog

If the public documentation and this AI context disagree, use the current theme editor labels and the most recent public documentation as the higher-priority source for merchant-facing setup.