Terrazza documentation

This guide describes the theme as shipped. Shopify admin labels may vary slightly by plan, market, or the current Shopify editor.

1. Install and preview

1. In Shopify admin, open Online Store > Themes.
2. Add the Terrazza ZIP, or add the theme from the source workflow used by your team.
3. Create a duplicate before making substantial changes.
4. Select Customize to open the theme editor. Start from the Terrazza preset, adjust it, then save.
5. Assign menus, collections, products, pages, articles, and images to the section settings.
6. Preview on a representative product, collection, article, cart, and gift card before publishing.

A development preview can also be run with Shopify CLI using shopify theme dev. The CLI, the theme editor, and Shopify's admin are Shopify services; Terrazza does not replace them. Publishing, domains, checkout settings, shipping, taxes, payments, markets, and inventory remain Shopify admin responsibilities.

2. Start in the theme editor

Use the left-hand section tree to reorder sections, select a section to edit its settings, and use Add block to add or reorder blocks. Each section exposes its own color scheme, spacing, alignment, and visibility options where relevant. Use the mobile preview before saving.

Global settings are under Theme settings:

• Colors: four coordinated color schemes and page / gift-card schemes.
• Typography: heading and body font_picker settings, with the Terrazza display and body defaults.
• Layout: page width, spacing, image behavior, card treatment, and controls.
• Brand: logo, inverse logo for transparent headers, logo width, and logo arch.
• Cart and search: drawer behavior, quick add, recommendations, predictive-search types and limits.
• Motion: the global motion switch. A visitor's prefers-reduced-motion preference still takes precedence.
• Style defaults: the Terrazza preset.
• Social links and market / language controls where enabled by the store.

The editor saves settings as theme data. Product prices, inventory, selling plans, pickup availability, taxes, delivery rates, markets, and customer accounts are not theme settings.

3. Home page sections and presets

The Terrazza home template is intentionally rich. The shipped home configuration uses 19 section positions, including the announcement bar, header, hero, reassurance, category tiles, tabbed products, hamper builder, promotional banners, featured product, image-and-text story, season dial, producer rail, pairing picker, process content, FAQ, journal, newsletter, and rich footer. Remove or reorder sections for a smaller store, but keep every visible section supplied with its image, copy, and action.

Core sections available in the theme include:

• announcement-bar: rotating merchant messages and links.
• hero: a single slide or three-slide slideshow, with desktop and mobile media, overlay, two calls to action, and optional featured product content.
• reassurance: commitments and the word-scroll variant.
• category-bubbles and category-tiles: collection-led discovery with image, title, and product count from Shopify.
• tabbed-products: up to three collection tabs, with pills or arch layouts.
• featured-products, featured-product, and collection-rail: product grids, a detailed product presentation, and a horizontal collection rail.
• promo-banners, image-text, lookbook, and video-poster: editorial merchandising, hotspots, and a poster-led video section.
• hamper-builder: three product slots for an assembled hamper; the total uses native product prices unless a merchant configures another value.
• season-dial: month selection backed by the configured product / collection data.
• pairing-picker: step-by-step or quick recommendations based on the answers and products configured by the merchant.
• producers-rail, faq, journal, and newsletter: provenance, questions, articles, and email capture.
• custom-section and custom-liquid: flexible content and app blocks. Custom Liquid should be used only with code you trust.

Terrazza ships with a single style preset: the cream, terracotta, olive, and saffron treatment, with arched media and four-column product grids on desktop. More presets will follow in later versions.

Section presets are starting points, not locked layouts. A preset does not create products, collections, pages, or images.

4. Navigation and footer

Create menus in Shopify admin under Content > Menus. Terrazza supports nested navigation: a top-level item can contain child links, and the desktop mega menu can show link groups and optional visual cards. The mobile drawer exposes the same hierarchy, supports keyboard focus, and closes with its close control or Escape.

The header can show a logo, transparent-hero treatment, search, customer account, and cart count. The footer supports menus, a newsletter form, social links, payment icons, country / language controls, and an optional pickup information block. Payment icons are informational; Shopify checkout decides which payment methods are actually available.

5. Catalog and merchandising

The collection template provides a banner, breadcrumb, product count, sorting, faceted filters, a desktop sidebar or mobile drawer, product grid, optional promotional tile, and progressive loading / pagination behavior supplied by Shopify. Product cards can show a second image, badges, swatches, compare-at price, savings calculated from Shopify, and quick add when the product needs no additional choice.

The product template is block based. It supports a gallery, variant media, price and unit price, quantity rules and quantity price breaks when Shopify provides them, selling-plan choices, accelerated checkout, Shop Pay Installments information when available, local pickup availability, delivery copy, product facts, accordions, complementaries, bundle contents from a product metafield, Custom Liquid, and app blocks. A gift card product receives gift-recipient fields from Shopify.

Use real Shopify data in all merchandising content. Terrazza deliberately does not create reviews, ratings, urgency, fake availability, countdowns, or invented statistics. If a store needs reviews, subscriptions, recommendations, or another service, configure the relevant Shopify feature or app and use the provided app block where supported.

6. Conversion-native features and limits

Terrazza is designed to reduce routine app work with theme-native presentation of Shopify data: quick add, product recommendations, complementary products, cart recommendations, quantity rules, selling plans, unit prices, Shop Pay messaging, local pickup data, gift messages, cart notes, and accelerated checkout. These features still depend on the store, product, market, fulfillment locations, and Shopify plan configuration.

Selling plans are not invented by the theme. A product must have a Shopify selling-plan group. The product form sends the selected plan, and the cart displays the plan allocation when Shopify returns it. A subscription app may be required to create or manage the plan; Terrazza only renders the native data.

The hamper builder is a guided multi-product selection, not an automatic bundle discount. A merchant must configure the collection and any bundle price behavior. The pairing picker is a configured recommendation experience, not personalization or an AI service. The season dial uses the products and collections selected in its settings.

The theme does not include wish lists, theme-generated reviews, coupon-code fields in the cart, back-in-stock alerts, automatic gifts, buy-X-get-Y promotions, A/B testing, Instagram feeds, appointment booking, or fake urgency. Use a compatible app or Shopify service only when the merchant genuinely needs one.

7. Accessibility

Terrazza includes a skip link, semantic headings, associated form labels, visible :focus-visible states, keyboard-operable menus and accordions, live announcements for relevant cart and selection updates, text alternatives for images, and touch targets designed for at least 44 by 44 pixels. Do not use color as the only signal for selected, error, or availability states.

Check every image's alt text in the editor. Keep heading levels in a meaningful order, write link labels that make sense out of context, and test custom Liquid and app blocks separately. The theme's color schemes are designed for WCAG AA contrast, but a merchant's image overlay, custom text, or app content can change the result.

8. Motion and reduced motion

Terrazza uses restrained transform and opacity transitions for arch lift, image hover, drawers, product selection, and the season dial. Turn off Theme settings > Motion to disable the theme's optional motion. The CSS also honors prefers-reduced-motion: reduce, shortening transitions and stopping looping motion. Video remains a separate media choice and should have a clear poster and controls.

9. Localization, markets, and SEO

Theme strings live in the locale files and can be translated with Shopify's language tools. Store language availability, translated resources, market catalogs, currency conversion, rounding, taxes, and checkout language are controlled by Shopify Markets and the store configuration. Translate merchant-entered headings, descriptions, alt text, menus, metafields, and Custom Liquid separately.

Terrazza includes canonical and page metadata handling, structured product / organization / breadcrumb data, product and article templates, a social sharing image setting, and predictive search. Search indexing, rich-result eligibility, URL redirects, merchant content quality, and search-engine changes are outside theme control. Do not place essential information only inside an image.

10. Page-by-page map

• Home: templates/index.json; the full editorial and merchandising sequence.
• Oil and vinegar collection: templates/collection.json with the oils-vinegars collection assigned in Shopify.
• Early Harvest Olive Oil: templates/product.json; the product handle is early-harvest-olive-oil in the demonstration catalog.
• Cart: templates/cart.json plus the cart drawer group; includes notes, gift message, complementaries, discounts, selling plans, and accelerated checkout when Shopify exposes them.
• Search: templates/search.json; predictive search is in the header and the page supports filters, suggested collections, suggested products, and useful empty states.
• Journal and article: templates/blog.json and templates/article.json; the demonstration article handle is how-to-build-a-cheese-board-with-pantry-staples.
• Pages: page.about.json, page.contact.json, page.faq.json, page.landing.json, and the generic page template.
• Customer account: login, registration, activation, reset, dashboard, addresses, and order templates.
• Gift card: gift_card.liquid; Shopify supplies the gift-card balance, code, and recipient data.
• 404: templates/404.json; configured collection and product links help visitors continue shopping.

11. Images and content

Use clear, well-lit images with a deliberate focal point. Square product media works well for product cards; portrait imagery supports the arch treatment; the hero accepts separate desktop and mobile media. Add alt text that describes the useful subject, not a keyword list. Shopify image resizing and responsive delivery are used by the theme, but source quality and file size still affect performance.

Do not put prices, claims, guarantees, or critical instructions only in an image. Videos need a poster, meaningful controls, and captions where speech conveys information.

12. Support and troubleshooting

Before contacting support, record the theme version, store URL, template name, browser and viewport, exact steps, and a screenshot with customer data removed. Check whether the behavior reproduces in a duplicate theme and with app embeds temporarily disabled.

Terrazza support covers theme settings, section behavior, documented blocks, and defects in the shipped theme. Shopify support owns checkout, payments, taxes, shipping rates, Markets, customer accounts, inventory, pickup configuration, translations infrastructure, and platform outages. App developers own their app blocks, scripts, data, and compatibility. Custom Liquid is merchant code and is outside normal theme support.

Do not edit theme code to fix a product price, inventory level, delivery rate, selling plan, or market setting: change the relevant Shopify admin resource instead.