Verso Documentation
Everything is controlled from the Shopify Theme Editor. You never need to edit code to run the theme.
Overview
- Version: 1.0.0
- Compatibility: Shopify Online Store 2.0 — JSON templates, section groups, app blocks
- Tech: Liquid • vanilla JS Web Components • one design-token-driven CSS file
- No build step — upload the folder as-is.
Best suited to fashion, electronics, home & lifestyle and luxury stores, but the four preset styles and the token system make it work for most catalogues.
Installing the theme
Option A — Shopify admin (recommended)
- Zip the contents of the theme folder so
layout/,sections/, … sit at the root of the zip — not inside a parent folder. (The suppliedVerso-1.0.0.zipis already correct.) - Shopify admin → Online Store → Themes → Add theme → Upload zip file.
- Click Customize to open the Theme Editor.
- When you’re happy, Actions → Publish.
Option B — Shopify CLI (for developers)
shopify theme dev # live preview against your store
shopify theme push # upload to a new unpublished themeFirst-run checklist
| Step | Where |
|---|---|
| Pick a preset (Luxury / Fashion / Tech / Home) | Theme settings → gear icon → presets |
| Upload your logo + favicon | Theme settings → Logo |
| Set brand colours | Theme settings → Colors |
| Choose fonts | Theme settings → Typography |
| Build your menu | Shopify admin → Navigation → main-menu, footer |
| Assign templates | Product / Page admin → Theme template dropdown |
| Configure cart, header, badges | Theme settings groups of the same name |
| Connect review / email / loyalty apps | Theme settings → App integrations & Reviews & ratings |
What’s included
Templates
index · product · collection · list-collections · cart · search · blog · article · page · page.about · page.contact · page.wishlist · 404 · password · gift_card · full customers/* set.
Homepage / content sections
Hero banner · Slideshow · Featured collection (grid or carousel) · Collection list · Rich text · Image with text · Multicolumn · Testimonials · FAQ · Call to action · Newsletter · Tabs · Gallery / lookbook · Shop the look (image hotspots) · Shop-the-look video (3D coverflow) · Announcement bar · Custom Liquid / HTML · Related products.
Every content section has: colour scheme, top/bottom padding, a heading with *emphasis* support, and reveal-on-scroll animation.
Layout options
| Area | Options |
|---|---|
| Header | Minimal (centered logo) · Standard (logo left) · Full-width with mega menu |
| Product page | Standard · Wide gallery · Stacked; gallery as thumbnails or grid |
| Collection page | Sidebar filters · Filter drawer · No filters; grid / list toggle |
| Homepage | Fully modular — drag sections in the editor |
Colours & schemes
snippets/css-variables.liquid turns your Theme settings into CSS custom properties (--color-primary, --color-surface, …). Sections never hard-code a colour, so your settings always win.
Every content section exposes a Colour scheme picker — default / surface / inverse — mapped to the .color-* helper classes. The helpers keep foreground and background paired so text contrast holds.
Typography
- Headings — default Playfair Display
- Body — default Assistant
- Accent — eyebrows, buttons, small labels
- Display — an italic serif for emphasised words
In any heading field, wrap words in *asterisks* (or use <em> in rich text) to render them in the display font — e.g. Real *routines.* All four faces are font_picker settings: merchants pick from Shopify’s font library with zero code.
Spacing & shape
Global: page width, section spacing, grid gaps, corner radius, button radius, shadow strength. Per-section: top / bottom padding in px.
Animations
Theme settings → Animations: enable / disable, reveal style (fade / slide-up / scale), hover lift, and product-image hover effect (none / zoom / show 2nd image).
All motion auto-disables for visitors with prefers-reduced-motion — CSS and JS both respect it.
Product page
sections/main-product.liquid is built from re-orderable blocks — drag them in the editor, no code:
- Vendor, title, rating, price (with tax note)
- Variant picker — pills / swatches or dropdowns; sold-out combos marked
- Quantity with min / max / step validation
- Subscriptions — selling-plan groups render automatically (“one-time” vs “subscribe & save”)
- Pre-orders — auto-detected (continue-selling + 0 stock) or
preordertag; button + badge text switch - Digital products — dynamic checkout + no-shipping messaging just work
- Inventory status — in stock / low stock (configurable threshold) / backorder / out of stock, updates live on variant change
- Collapsible rows (shipping, care…), trust badges, share button
- App blocks (
@app) — drop any app’s product-page block anywhere in the column - Sticky add-to-cart bar, sticky gallery on desktop, quick view from cards
- Media gallery: images, video, external video, 3D models, click-to-zoom
Sections reference
Shared conventions: Colour scheme (default/surface/inverse), top / bottom padding, and headings that support *emphasis*.
Store sections
| Section | Notes |
|---|---|
| Header | 3 layouts (minimal / standard / full-width-mega); sticky, transparent-on-home, search & account visibility in Theme settings → Header. Section settings: menu, mega-menu blocks, wishlist icon + page. |
| Footer | Blocks: Brand, Menu (×N), Text, Newsletter, Social icons. Copyright suffix, policy links, payment icons, country / language selectors. |
| Announcement bar | Rotating message blocks; background / text colour + rotation speed. |
| Cart drawer | No own settings — driven by Theme settings → Cart: drawer / page / notification, quick add, upsell products, order notes, free-shipping bar + threshold. |
Homepage / content sections
| Section | Key options |
|---|---|
| Hero banner | Image or video background, height, overlay, content alignment (L/C/R), eyebrow, heading, text, 2 buttons. Works with the transparent header. |
| Slideshow | Up to 6 slides, autoplay + speed, height; per slide image / overlay / text colour / alignment / eyebrow / heading / text / button. Keyboard + touch, pauses on hover / focus / tab-hidden and for reduced motion. |
| Featured collection | Collection, grid or carousel, columns (2–5), product count, “View all” label, per-section card style. Reuses the product card. |
| Collection list | Collection cards from blocks; columns, image ratio, product count. |
| Rich text | Re-orderable blocks: eyebrow, heading (3 sizes), text, button. Left / center. |
| Image with text | Image / Shopify video / external video; ratio; image left / right; vertical align; eyebrow / heading / text / button; feature-line blocks (icon + text). |
| Multicolumn | 2–4 columns, icon or image, heading, text, optional link. Value props / how-it-works / perks. |
| Testimonials | Grid or carousel. Per block: quote, 0–5 stars, author, role, avatar. |
| FAQ | Split or centered layout, single-open toggle. Emits FAQPage structured data. |
| Call to action | 1–3 CTA cards, each with optional background image, colour scheme, 2 buttons. |
| Newsletter | Heading / text / disclaimer + provider-aware form (see App integrations). |
| Tabs | Up to 6 tabs; each is a collection grid or a rich-text panel. Accessible arrow-key navigation. |
| Gallery | Grid / masonry / slider layouts, optional lightbox. Per image: caption + link. |
| Shop the look | Lifestyle image with positioned hotspot blocks (x/y %), each linking a product. Hotspot popover has quick-add. |
| Shop-the-look video | 3D coverflow of vertical video cards → full-screen player with a featured-product rail. Per block: Shopify-hosted video, title, caption, duration, product. Self-contained CSS/JS; empty blocks show a static poster. |
| Custom Liquid / HTML | Paste app embeds / HTML / Liquid. Full / narrow / default width. |
| Related products | Lazy-loaded via the Product Recommendations API. Intent: related / complementary. Columns + count. |
Template sections
| Section | Template | Key options |
|---|---|---|
main-product | product | layout (standard / wide-gallery / stacked), gallery style, sticky gallery / ATC, re-orderable info blocks |
main-collection | collection | filter layout (sidebar / drawer / none), grid / list toggle, columns, per-page |
main-cart | cart | free-shipping bar, notes, recommendations |
main-blog | blog | feature latest post, excerpts, tag filter, columns |
main-article | article | hero image, share, reading time, comments |
main-page | page | title, alignment, width, breadcrumbs |
main-list-collections | list-collections | sort, hide frontpage, counts, ratio, columns |
main-search | search | columns, results per page |
main-404 | 404 | message + suggested collection |
main-password | password | background, heading / text, newsletter |
wishlist | page.wishlist | heading, source collection, columns |
App integrations — no code changes
Merchants switch apps from the Theme Editor. Each integration degrades gracefully if the app is missing or misconfigured.
Reviews & ratings
Theme settings → Reviews & ratings → Review platform · snippet snippets/app-reviews.liquid.
| Provider | Badge container | Full widget |
|---|---|---|
shopify | .shopify-product-reviews-badge[data-id] | #shopify-product-reviews |
judgeme | .jdgm-widget.jdgm-preview-badge | .jdgm-widget.jdgm-review-widget |
loox | #looxReviews[data-product-id] | #looxReviews |
yotpo | .yotpo.bottomLine | .yotpo.yotpo-main-widget |
okendo | [data-oke-star-rating] | [data-oke-widget] |
stamped | .stamped-product-reviews-badge | #stamped-main-widget |
The theme prints the provider’s expected markup; the app’s own script hydrates it. Fallback: when the provider is none, cards and the product page fall back to the reviews.rating / reviews.rating_count product metafields.
Loyalty & rewards
Theme settings → App integrations → Loyalty & rewards · snippet snippets/loyalty-widget.liquid. Providers: Smile.io, LoyaltyLion, Yotpo Loyalty, or paste custom code.
| Placement | Where |
|---|---|
product | Below the add-to-cart button |
launcher | Footer (floating widget host) |
inline | Customer account page panel |
Fallback: if loyalty features are off, nothing renders — zero performance cost.
Email marketing / newsletter
Theme settings → App integrations → Email marketing · snippet snippets/newsletter-form.liquid (Newsletter section, footer block, password page).
| Provider | Behaviour |
|---|---|
shopify | Native customer form — synced to any connected ESP |
klaviyo | Native form + hidden contact[list_id] from the Klaviyo list ID setting |
mailchimp / omnisend | Native form; their apps sync customers automatically |
custom | Renders the raw embed from “Custom newsletter embed” verbatim |
Fallback: every mode degrades to the native Shopify customer form, so email capture keeps working even if a script fails to load.
Anything else
- Custom Liquid / HTML section — add anywhere, paste the app’s embed.
- Product page → Custom Liquid block — product-specific widgets.
- App blocks (
@app) — OS 2.0 block apps drop into the product info column. - App embed blocks — site-wide apps work automatically via
content_for_header.
Mega menu
- Theme settings → Header → Header layout = “Full width with mega menu”.
- Open the Header section and add a Mega menu block per top-level item you want a panel for.
- Top-level menu item title — must match the menu item exactly.
- Column menu — each top-level link becomes a column heading; its children become the links.
- Optional featured products strip (from a collection) and up to 2 promo banners (image + heading + link).
New / Sale / Hot pills are set on the Header section as comma-separated menu-item titles (label_new, label_sale, label_hot) and apply to the desktop nav and the mobile drawer.
Wishlist
Built-in localStorage wishlist — heart icon on cards, count in the header, page.wishlist template. It emits a wishlist:change DOM event and exposes window.Verso.Wishlist, so a wishlist app can hook in or replace it. To use an app’s page, point Theme settings → Header → Wishlist page at it.
Performance & accessibility
Loading
- One CSS file, CDN-served with far-future cache; section rules use scoped
{% style %}. - JS deferred — nothing blocks first paint. Zero dependencies, all vanilla Web Components.
- No render-blocking fonts (
font-display: swap, preconnect). Design tokens inlined in<head>to avoid FOUC.
Images
snippets/image.liquidemitssrcset(8 widths),sizes, intrinsicwidth/height(no CLS),loading="lazy"+decoding="async".- Above-the-fold images (hero, first slide, first gallery media, logo) load
eager+fetchpriority="high".
Accessibility (WCAG 2.1 AA)
- Landmark roles, skip-to-content link,
:focus-visibleoutline on every interactive element. - Drawers:
role="dialog",aria-modal, focus trap, Esc to close, focus returned to the trigger. - Tabs & sliders: proper roles, arrow-key navigation, real
<button>controls. - Live regions for cart / filter updates and confirmations. Every input has a
<label>; errors usearia-invalid+role="alert". prefers-reduced-motion: animations, smooth scroll and autoplay all disabled.
Lighthouse depends on merchant content. Advise buyers to: upload images ≤ ~2000px; compress hero images (< 250 KB, WebP); keep the homepage to ~8–12 sections; audit apps (third-party scripts are the #1 cause of score drops); use Shopify-hosted video above the fold.
Error handling & fallbacks
A missing image, an empty collection, a failed request or a disabled app never breaks a page.
| Scenario | Handling |
|---|---|
| Section with no collection / product chosen | Onboarding placeholders in the editor; muted “choose a…” message on the live store |
| Product has no images | Placeholder rendered; card / gallery keep their aspect ratio |
| Product / variant unavailable | Buy button disabled with “Sold out” / “Unavailable”; price gets price--sold-out |
| Collection has 0 products after filtering | Friendly empty state + “Clear all” link |
| Add-to-cart / cart update fails | Error surfaced in the form region + aria-live; button re-enabled; cart never left broken |
| Section Rendering API fails | Falls back to a full page navigation rather than stale UI |
localStorage unavailable (private mode) | Wishlist reads / writes are try/catch-wrapped and no-op safely |
| Web Components unsupported (old browsers) | Progressive enhancement — forms, links and native <details> accordions still work; <noscript> variant selector |
FAQ
Do I need to know how to code?
No. Every colour, font, layout, section and integration is set from the Theme Editor.
Will the demo images stay on my store?
No — the bundled ph-*.jpg photos only show where an image is missing. They disappear automatically as you add real products and images.
How do I connect my reviews / loyalty / email app?
Theme settings → Reviews & ratings or App integrations, pick the provider, and install that app from the Shopify App Store. No theme edits. See App integrations.
Can I move the theme to another store?
Yes. Download it (Actions → Download theme file) or use the supplied zip and upload it to the other store.
How do I get help?
See the support page or email [email protected].
Changelog
1.0.0 — Initial release. Online Store 2.0 architecture; 3 header layouts; full homepage / content section set; advanced product page (variants, subscriptions, pre-orders, inventory, sticky ATC, quick view); collection filtering + grid/list; cart drawer with upsell & free-shipping bar; app integration layer for reviews / loyalty / email; built-in wishlist; 4 preset styles; full customers/*, gift_card, password, 404, search templates.
Full history ships with the theme in docs/CHANGELOG.md.