Deivisoft Themes

Refill

A subscription-first Shopify theme for replenishment brands.
Version 0.1.0 · Shopify Online Store 2.0 · Liquid, JSON templates, native CSS/JS

1. Purpose

Refill is built for brands that sell consumable products on a recurring basis: skincare, wellness, supplements, pet food, and specialty coffee. It treats the subscription as the primary purchase path, not an option buried below the add-to-cart button.

The theme is aimed at DTC merchants with 20–300 SKUs and at least one Shopify selling plan. It is designed to make the value of subscribing legible in the first screen, to make frequency selection feel safe, and to keep the one-time purchase path available.

2. What is included

  • Complete Online Store 2.0 theme: JSON templates, sections, blocks, section groups.
  • Subscription plan selector driven by native Shopify selling plans.
  • One-time versus subscribe-and-save pricing display.
  • Routine-led homepage with a four-step ritual, ingredient glossary, plan comparison, and subscription explainer.
  • Product page with gallery, variant picker, selling plans, quantity, buy buttons, pickup, ingredients, how-to-use, complementary products, and app/Custom Liquid blocks.
  • Collection page with faceted filtering, sorting, pagination, and an empty state.
  • Predictive search, cart drawer, cart page with discounts and selling plans, account component, gift card, password, 404, blog, article, and contact templates.
  • Responsive image strategy, accessible focus states, reduced-motion support, and semantic landmarks.
  • Theme editor settings for colours, typography, layout, cards, social links, and SEO.
  • Demo content guide, licensed Shopify Burst photography, and vector fallbacks in demo/.

3. Requirements

  • A Shopify store with the Online Store channel.
  • A Shopify plan that supports the features you want to use (selling plans, pickup, markets).
  • Shopify CLI 4.x for local development, or the Shopify admin theme upload workflow.
  • A development store is strongly recommended before publishing.

4. Installation

Option A — Shopify CLI

npx shopify theme dev --store your-store.myshopify.com --path themes/refill

To upload an unpublished theme:

npx shopify theme push --store your-store.myshopify.com --path themes/refill --unpublished

Option B — Admin upload

  1. Create a ZIP of the themes/refill directory (do not zip the parent folder).
  2. In Shopify admin, go to Online Store → Themes → Add theme → Upload ZIP file.
  3. Preview the theme, then publish when ready.

5. Configuration

Theme editor

Open Online Store → Themes → Customize. The main settings are:

  • Colors — background, text, accent, surface, border, and muted colours.
  • Typography — heading and body fonts, base size, heading scale.
  • Layout — page width, section spacing, card radius.
  • Product cards — vendor visibility and image ratio.
  • Cart — cart note.
  • Social media — profile URLs used by the footer.
  • SEO — social share image and favicon.

Subscription setup

  1. Install a subscription app that creates Shopify selling plans, or use Shopify's native selling-plan tooling where available.
  2. Create at least one selling plan group and attach it to the products you want to sell on subscription.
  3. In the theme editor, open a product template and confirm the Subscription introduction block is present.
  4. The theme reads product.selling_plan_groups and variant.selling_plan_allocations. If no plans exist, the selector is hidden automatically.
  5. Subscription management (skip, pause, cancel) is normally owned by the subscription app. Add the app's block to the product template or the customer account area. The theme does not implement subscription management itself.

Recommended content

  • Create collections: bestsellers, cleansers, serums, moisturisers, spf.
  • Create a page for How subscriptions work and link it from the hero secondary button.
  • Create a page for Ingredients and link it from the ingredient glossary.
  • Add menus: main-menu, footer, customer-account-main-menu.

Optional metafields

The theme works without metafields. These are optional enhancements:

Metafield Type Used by
custom.concern Single-line text Product card concern label
custom.ingredients Rich text Product page ingredients block fallback
custom.how_to_use Rich text Product page how-to-use block fallback
custom.complementary_products List of product references Complementary products

6. Customisation

  • Design tokens — edit config/settings_schema.json defaults or use the theme editor. CSS variables are generated in layout/theme.liquid.
  • Theme CSS — assets/theme.css contains the Refill art direction. assets/base.css contains shared components.
  • Sections — add or duplicate sections in sections/. Each section has a {% schema %} block.
  • Product page blocks — reorder or hide blocks in the theme editor. The purchase form is rendered by snippets/product-form.liquid.
  • Selling plans — snippets/selling-plan-selector.liquid renders the plan selector. snippets/variant-picker.liquid provides the variant JSON used by assets/base.js.
  • Translation — edit locales/en.default.json. The theme uses t filters for storefront strings.

7. Validation status

  • shopify theme check: 0 errors, 0 warnings at the time of writing.
  • Structural validator (tools/validate-themes.mjs): required templates, sections, JSON, section references, account component, localization, and Follow on Shop checks pass.
  • Live-store installation, home/product/collection/cart/search, add-to-cart, and Lighthouse home-page audits were executed on the branded demo stores. Checkout, app-dependent flows, and template-level Lighthouse runs remain unmeasured. See docs/05-validation-report.md.

8. Known limitations

  • Subscription management is app-owned. The theme supports native selling plans but does not manage billing, skip/pause, or cancellations.
  • The demo photography is licensed from Shopify Burst. The SVG illustrations remain available as offline fallbacks in demo/<theme>/images/.
  • The theme_info documentation and support URLs point to deivisoft.eu. Publish the documentation and support pages before submission.
  • The theme ships one preset. Additional presets require a /listings folder and separate demo stores for the Shopify Theme Store.
  • Shopify Theme Store acceptance is not guaranteed. Review the requirements and test on a development store before submitting.

9. Support and license

See LICENSE.md for the commercial license terms. See the repository root THIRD_PARTY_NOTICES.md for third-party components. This theme does not bundle third-party JavaScript libraries or font files.

For support, use the contact channel defined by the seller. Theme support covers theme bugs and documented configuration; it does not include custom design or code changes.

FAQ

How do I install the theme?

Install the ZIP from the Theme Store or upload it under Online Store → Themes → Add theme → Upload ZIP file. Then publish or preview the theme.

Does the theme require apps?

No. The core experience uses native Shopify features. App blocks are available for optional integrations such as reviews, subscriptions, or wholesale pricing.

How do I get support?

Use the support form. Include your store URL, theme name, and a description of the issue. We reply within two business days.

How do updates work?

Theme Store purchases include updates. Download the latest version from the Theme Store or your Shopify admin and apply it to a duplicate of your theme before publishing.