Troubleshooting and FAQ

A collection of issues seen during Hyprism development and how to resolve them. Roughly organized by symptom.

19.1 Visual issues

Glass surface looks flat / no blur

Symptoms: A section’s Glass mode shows a slightly transparent color but no actual backdrop-blur.

Causes & fixes:

1. Section animation in flight. When a section’s scroll-in animation runs (translateY(56px) → none), the section temporarily has a transform, which creates a backdrop-root for its descendants. Block-level glass elements sample the empty section box, not the page. The glass “blooms in” after the animation completes.

   Fix in theme: Hyprism’s CSS already excludes glass-containing sections from the scroll-in animation via :has(). If you’ve removed this exclusion (custom code), restore it.

2. Parent element has filter, opacity < 1, will-change: transform, or isolation: isolate. Any of these creates a backdrop-root that traps the descendant glass blur.

   Fix: avoid setting these on glass-element ancestors.

3. Browser doesn’t support backdrop-filter (rare in 2026).

   Fix: nothing — visitors on the rare unsupported browser see a solid translucent surface, which is graceful degradation.

Dark/Light toggle doesn’t switch colors on some sections

Symptoms: Click the dark/light toggle. Most sections swap colors, but one specific section doesn’t.

Causes & fixes:

1. Section uses Use global scheme and the global scheme isn’t in the dark/light pair. The applyMode() JS only swaps schemes that are part of the pair. If your global scheme is scheme-4 and the pair is scheme-1 / scheme-2, scheme-4 stays as scheme-4.

   Fix: in the theme editor, either set the global scheme to one of the pair schemes (e.g., scheme-1), OR add per-section dark/light setting to that specific section.

2. Section has Use global scheme = off but doesn’t have its own dark/light pair. The section uses its picked scheme statically.

   Fix: enable the per-section dark/light pair (Enable dark/light toggle for this section) and pick the dark/light schemes you want.

Cart drawer doesn’t open after adding to cart

Symptoms: Click “Add to cart” on a product card. Cart icon’s count updates but drawer doesn’t open.

Causes & fixes:

1. The add-to-cart action is going to /cart/add.js but not dispatching the ne:cart-updated event. This happens if a custom or third-party “Add to cart” button bypasses Hyprism’s event system.

   Fix: ensure the custom button dispatches document.dispatchEvent(new CustomEvent('ne:cart-updated')) after the AJAX call resolves.

2. Cart drawer is disabled in theme settings. Theme settings → Cart drawer → Enable cart drawer.

3. You’re on /cart page. On the cart page, the cart icon links directly to /cart (reload), not to opening a drawer. This is intentional — drawer doesn’t make sense on the cart page itself.

Sticky Product Bar doesn’t appear

Symptoms: On a product page on mobile, the bar should slide up when you scroll past the ATC. It doesn’t.

Causes & fixes:

1. Enable sticky product bar is off in theme settings.

2. The product page is too short to scroll past the main ATC. The bar only triggers after the ATC scrolls out of view. On a product page with sparse content (no description, no tabs), the visitor never scrolls far enough.

   Fix: nothing — this is correct behavior. The bar is there to help with deep scrolling, not for short pages.

3. A parent element has transform, filter, will-change, or isolation: isolate — these create a containing block for the body-mounted bar, breaking the position: fixed placement.

   Fix: identify the problematic ancestor via DevTools and remove the constraint. Most parent elements in Hyprism are safe, but custom Liquid sections sometimes introduce these.

Mobile slider doesn’t swipe smoothly

Symptoms: On mobile, a carousel/slider feels jittery or doesn’t pick up touch gestures.

Causes & fixes:

1. Mobile touch hint is off, and touch-action isn’t set on the carousel. The default touch-action: auto may not delegate horizontal swipe to the carousel’s scroll handler.

   Fix: enable theme settings → Layout → Mobile → Enable mobile touch hint. This applies touch-action: pan-x to all carousels.

2. A pseudo-element animation is interfering. CSS pseudo-elements with transform animations in a scroll container can be promoted to compositor layers and capture touch hits.

   Fix: hyprism’s touch-hint uses real-DOM <button> chevrons specifically to avoid this. If you’ve added a custom pseudo-element animation, consider real-DOM instead.

A section’s corner-radius isn’t applied on mobile

Symptoms: Section has a configured radius on desktop, but on mobile the corners are square.

Causes & fixes:

1. The section is full_width_mobile = on. Full-width sections force radius=0 (rounded corners + edge-to-edge looks broken). This is intentional.

   Fix: if you want rounded corners on mobile too, turn off full_width_mobile. The section then has page-margin, which lets the radius show.

Variant-selector swatches show empty / wrong color

Symptoms: Color swatches in the product variant picker (or on product cards) render as transparent, white, or the wrong color.

How swatch colors are resolved (first hit wins):

1. option.values[i].swatch.color — Shopify’s native color picker. Set in Admin → Products → Options → “Edit values” when the option type is Color. Language-independent and supports brand-custom hex values.
2. Built-in name dictionary (~60 entries) — covers common DE + EN color names (Schwarz / Black, Marineblau / Navy, Bronze, Cognac, Mauve, Türkis, …). Used when the option is plain text and the value name matches.
3. handleize fallback — works only for English values that coincide with CSS keywords (red, green, blue, …).

Recommended fix for any locale / brand-color:

1. Shopify Admin → Products → select your product → scroll to Variants.
2. Click “Edit options” on the Color option.
3. Change option type from “Custom (text)” to “Color”.
4. A color picker (and image-upload slot) appears for each value. Pick the exact hex for each variant.
5. Save. The theme reads swatch.color (or swatch.image) and renders the picked color or pattern — works for any language and any custom brand color.

This is the only setup that scales beyond DE / EN. Stores using non-English color names (Spanish “Rojo”, French “Rouge”, Italian “Rosso”, …) must use this path or the swatches stay empty.

Variant-selector shows pattern image instead of solid color

Symptoms: One of your color swatches renders as an image instead of a flat color, e.g. wood-grain or fabric texture.

This is by design. When the merchant uploads an image in the Color option’s “Edit values” swatch slot, the theme renders it as a swatch instead of a solid color. Use this for:

• Wood, leather, fabric, or marble patterns
• Brand-graphic swatches (e.g. tie-dye, gradient prints)
• Two-tone color-blocks that don’t reduce to one hex

The image is loaded at 80 px (cards) or 120 px (PDP variant picker) — keep source images small and square for a tidy result.

19.2 SEO / structured data issues

Schema validation shows duplicate Organization schema

Symptoms: Google Rich Results Test shows “2 Organization schemas detected on this page”.

Causes & fixes:

1. An SEO app (e.g., StoreSEO) emits its own Organization schema, and Hyprism also emits one.

   Fix: turn off Hyprism’s schema emission for whichever schemas the app handles. Theme settings → SEO & GEO → Enable schema emission → off. OR set per-schema-type toggles.

llms.txt page returns 404

Symptoms: Visiting /pages/llms returns Shopify’s 404 page.

Causes & fixes:

1. You haven’t created the page yet. Shopify Admin → Pages → Add page. Title: “llms.txt”. Handle: llms. Theme template: llms-txt.

2. The Theme template is set incorrectly. Verify “llms-txt” is the selected Theme Template (Shopify Admin → Pages → Edit Page → Theme template dropdown).

Meta description missing on category pages

Symptoms: Google Search Console reports “Page is missing meta description” for collection pages.

Causes & fixes:

1. The collection has no description in Shopify Admin.

   Fix: edit each collection in Shopify Admin → Products → Collections → set a description. Hyprism falls back to the description for the meta tag.

2. Theme-wide Home meta description and Organization description are also empty.

   Fix: set the Organization description in Theme settings → SEO and GEO (160 chars max recommended).

19.3 Performance issues

Lighthouse Performance dropped on mobile after a change

Symptoms: Lighthouse Mobile was 90+, now it’s 60–70.

Causes & fixes:

1. You added a large hero image without compression. Heavy images (>500KB JPEG, >2MB video) tank LCP.

   Fix: optimize images before upload. Shopify CDN auto-compresses, but extreme files still hurt.

2. You installed a heavy app. App scripts add to TBT (Total Blocking Time). Common offenders: live chat with heavy JS, page-builder apps, marketing automation apps.

   Fix: review apps via Shopify Admin → Apps → Performance tab. Disable or replace heavy apps.

3. You added a Custom Liquid section with synchronous JavaScript. Inline scripts block parsing.

   Fix: move JS to a deferred <script> tag or remove if unneeded.

4. Variance. Lighthouse Mobile has natural ±10 variance per run. Run 5 times and take the median before assuming a regression.

CLS (Cumulative Layout Shift) > 0.1

Symptoms: Lighthouse reports CLS = 0.15 (or higher).

Causes & fixes:

1. Images without width/height attributes. The browser doesn’t reserve space, so the page shifts when the image loads.

   Fix: in custom Liquid or HTML, always specify width + height on <img>. Hyprism’s image_url filter does this automatically.

2. Web fonts swap-loading without size-adjust. The fallback font has a different cap height; when the web font loads, text shifts.

   Fix: Hyprism uses font-display: swap + matching system-font fallback. If you’re loading a custom font via custom code (a Custom Liquid <style> block or theme files), configure a similar setup.

3. A Custom Liquid section inserts content above existing content after page load. Async JS that adds DOM content shifts everything below.

   Fix: reserve space with a placeholder of the same size.

19.4 Localization issues

German theme-editor shows English labels for some settings

Symptoms: You’re a German-speaking merchant, your Shopify Admin is set to German, but some Hyprism settings still show English labels.

Causes & fixes:

1. A specific section/block was added in a recent update and the German schema-locale hasn’t been updated. (Unlikely in the maintained version; but if you’re on an old version, possible.)

   Fix: update your theme to the latest version. Theme settings → Theme info → Latest version.

2. A new app block has English-only labels. App blocks define their own settings strings; if the app doesn’t ship German translations, you see English.

   Fix: contact the app developer to add German support.

Footer language switcher doesn’t show options

Symptoms: Footer-localization block shows the language switcher but it’s empty.

Causes & fixes:

1. Only one language is published on the store. Switchers only render when there’s more than one published locale.

   Fix: Shopify Admin → Settings → Languages → publish a second language.

19.5 Custom code conflicts

Custom CSS doesn’t override theme styles

Symptoms: You added custom CSS (via a Custom Liquid section’s <style> block or by editing theme files), but it has no effect.

Causes & fixes:

1. Specificity issue. Theme CSS has higher specificity than your override.

   Fix: increase your selector specificity. E.g., .ne-section .ne-section__title { font-size: ... } instead of .ne-section__title { font-size: ... }. Or add !important (less ideal but works).

2. There is no “Custom CSS” theme-settings field in Hyprism. Add CSS via a Custom Liquid section (<style>…</style>) or by editing theme files, and make sure it loads after the theme’s stylesheet.

3. Browser cache. After saving, do a hard refresh (Ctrl+Shift+R / Cmd+Shift+R).

Custom Liquid section renders broken

Symptoms: Custom Liquid section shows raw {% %} syntax or doesn’t render.

Causes & fixes:

1. Liquid syntax error. Run shopify theme check to see the specific error.

2. An {% if %} is unclosed — common when copy-pasting.

3. A {% form %} tag has filter args — known Shopify quirk. Use plain {% form 'product', _product %} (no class:, no data-X:). Add wrapper div around if you need data attributes.

19.6 When to ask for help

Issue type	First-line help	If still stuck
Theme setting question	Read the relevant chapter of this manual	Contact theme support (link on theme’s listing page)
Custom code	Read CLAUDE.md for the engineering patterns	Hire a Shopify Partner
App conflict	Contact the app’s support first (they’ve seen this before)	Theme support
Shopify-platform issue (checkout, customer accounts, payments)	Shopify Help Center	Shopify Support chat
Lighthouse / SEO	Run schema validators, lighthouse, manual checks	Theme support if Hyprism-specific

Next

Chapter 20 — Advanced (theme update workflow, backups, partners) — the final chapter.