Deivisoft Themes

Meeple

A set-completion and preorder Shopify theme for tabletop games, TCGs, board games, and RPGs.
Version 0.1.0 · Shopify Online Store 2.0 · Liquid, JSON templates, native CSS and JavaScript

1. Purpose

Meeple is built for the collector who is almost done. The buying anxiety is not “is this game good?” It is “is this the right edition and language, how many pieces am I missing, and when does the preorder arrive?”

The signature interaction is the Set Tracker. Product metafields define the set name, card number, and set total. Guests mark the pieces they own; the count persists in localStorage; Complete the set adds the unmarked items through AJAX, or offers the set collection as a clear fallback. The product page repeats the progress and missing-item action in a collector set card, while the collection page carries the progress bars and release-status tabs.

The visual language is a collector binder on a felt table: card frames, cream stock, foil marks, dealer-row data, and a deep green surface. It is adult collector, not a toy aisle.

2. What is included

  • Complete Online Store 2.0 theme: JSON templates, sections, blocks, header and footer section groups.
  • Meeple home page: hero-set with a binder of cards, set tracker, preorder calendar, featured collection, game-night events, staff picks, FAQ, and newsletter.
  • Set Tracker: native Liquid + vanilla JS, localStorage owned state, progress bars, complete-the-set AJAX, fallback link, and no-JS path.
  • Product page with gallery, set card, edition/language/rarity, player count and time, preorder date, compatibility, set progress, missing-item add, and recommendations.
  • Card-frame product cards with set name, rarity, card number, mini set progress, price, and quick add where the variant model allows it.
  • Collection page with collection image, set progress, all/in-stock/preorder tabs, native filters for game system, set, faction, rarity, edition, language, and release status.
  • Cart drawer, predictive search, account component, gift card, password, 404, blog, article, page, contact, and search templates.
  • Responsive images, keyboard access, visible focus, reduced-motion support, and semantic landmarks.
  • Theme editor settings for colors, typography, layout, product cards, social links, and SEO.
  • Six licensed Shopify Burst product photos, two landscape photos, and a 15-variant, 6-product demo CSV in demo/meeple/.

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 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/meeple

To upload an unpublished theme:

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

Option B — Admin upload

  1. Create a ZIP of the themes/meeple 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 — card cream #F5EFE0, felt green #1F3A2E, foil #D4A24C, ink #161A17, surface #FFFDF7, card line, and muted text.
  • Typography — Libre Baskerville headings, Work Sans body, base size, and heading scale.
  • Layout — page width, section spacing, card radius, and the felt/card texture.
  • Product cards — set name, rarity, card number, and mini set progress.
  • Social media — profile URLs used by the footer.
  • SEO — social share image and favicon.

Foil on cream is decorative only. Small foil text uses the darker #7C5A24 tone, and white/cream text on felt uses the 10.75:1 contrast pair.

Header and footer

The header is a dark felt bar with a cream wordmark, a card-frame logo mark, announcement bar, main menu, search, account, and binder count. The footer is felt with a foil top rule, shop menus, visit note, social links, localization, payments, and Follow on Shop.

The default section groups expect:

  • main-menu
  • header-utility
  • footer-shop
  • footer-info
  • customer-account-main-menu

Home page sections

The default index.json composes:

  1. Hero — set
  2. Set tracker
  3. Preorder calendar
  4. Featured collection
  5. Game night
  6. Staff picks
  7. FAQ — Meeple
  8. Newsletter — Meeple

Every section can be reordered, hidden, or duplicated in the editor.

Set tracker

The Set Tracker section takes a set collection and reads these product metafields:

Metafield Type Used by
custom.set_name Single-line text Set key, card label, progress
custom.card_number Single-line text Card number on the slot
custom.set_total Number (integer) Progress denominator
custom.set_collection Single-line text Set collection handle for product signatures

The section marks each collection product as owned in localStorage under meeple-owned-<set-handle>. The progress displays the owned count divided by set_total, with a minimum of zero and a maximum of the set total.

Complete the set adds every available, unmarked product variant through /cart/add.js at quantity 1. It does not mark items as owned; owning and buying are deliberately separate. The cart drawer refreshes through the shared cart:updated event.

If the collection is empty or JavaScript is off, the section hides the toggles and complete button and shows the set collection link. The product cards also carry a small set-progress bar that reads the same local state.

The set tracker tolerates missing storage: if localStorage is unavailable, the current page still works, but the state will not persist after a reload.

Product signature

snippets/product-signature.liquid reads:

Metafield Type Used by
custom.set_name Single-line text Set card heading and set key
custom.card_number Single-line text Card number
custom.set_total Number (integer) Card total and progress
custom.set_collection Single-line text Set collection for missing items
custom.edition Single-line text Edition row
custom.language Single-line text Language row
custom.rarity Single-line text Rarity label and row
custom.player_count Single-line text Players row
custom.play_time Single-line text Play time row
custom.preorder_date Date Preorder date and release row
custom.release_status Single-line text preorder or in-stock
custom.game_system Single-line text Compatibility row

The block's Set collection setting is a fallback when the metafield is blank. If neither is set, the theme looks for a product collection whose title contains the set name. The signature hides the set block cleanly when no set metafields exist.

Set progress reads the same localStorage key as the home tracker. Add missing items adds the unmarked, available set products at quantity 1, including the current product if it is unmarked. The normal product form remains available for a single-item purchase. Without JavaScript, the action is hidden and the set link remains.

The signature block is below the product buy box, so the set card reads as a full collector sheet rather than a narrow sidebar.

Collection page

The collection masthead shows the collection image, title, description, count, and — when every product shares one set — a set progress block with the same complete action. The tabs link to:

  • All products
  • ?filter.p.tag=release-in-stock
  • ?filter.p.tag=release-preorder

Those tabs require the release-status tag filter in Search & Discovery. The sidebar renders Shopify's native filters for game system, set, faction, rarity, edition, language, and release status.

Set progress is hidden on mixed collections such as new-releases and preorders, where standalone board games and RPG books would make a single set bar misleading.

Preorder calendar

The calendar section uses curated blocks with a text date (YYYY-MM-DD), product, status, and copy. It is a ledger, not a countdown. The product page reads the separate custom.preorder_date and custom.release_status metafields.

Product card

The card frame shows set name, rarity, card number, and a mini set-progress bar. Quick add appears for single-variant products; multi-variant products link to the product page.

Demo catalog and filters

demo/meeple/products.csv contains six products and fifteen variant rows. The four Gilded Fen items share a set name, card numbers GF-01 to GF-04, and set total 4. Mothwake and The Ember Ledger are standalone.

Demo tags use these prefixes:

  • system-*, set-*, faction-*, rarity-*, edition-*, language-*, release-*
  • Collection helpers: new-release, preorder, staff-pick, gilded-fen, preorders, new-releases, board-games, rpg-books

Create smart collections gilded-fen, new-releases, preorders, staff-picks, board-games, and rpg-books. Then add tag filters in Search & Discovery. The full demo README in demo/meeple/README.md documents the exact tags, import order, and test script.

6. Customisation

  • Design tokens — edit config/settings_schema.json defaults or use the theme editor. CSS variables are generated in snippets/css-variables.liquid.
  • Theme CSS — assets/theme.css contains the collector-binder art direction. assets/base.css contains shared commerce mechanics and content utilities.
  • Theme JavaScript — assets/base.js contains shared cart, search, header, media, and motion behavior. assets/theme.js contains the set tracker, product signature, collection progress, and gift-card recipient toggle.
  • Sections — add or duplicate sections in sections/. Each section has a {% schema %} block.
  • Product page blocks — reorder or hide description, form, complementary products, custom liquid, app blocks, and the set signature.
  • Translation — edit locales/en.default.json.
  • Icons — snippets/icon.liquid contains original SVG paths.

7. Validation status

  • npx shopify theme check --path themes/meeple --fail-level error: 0 offenses in the final run.
  • node tools/validate-themes.mjs: all structural checks passed with Meeple in the portfolio scan.
  • Live-store installation, set-tracker cart behavior, checkout, filters, selling plans, pickup, and Lighthouse were not executed in this environment. Run the commands in section 8 on a development store before submission.

8. Pre-launch checklist

npx shopify theme check --path themes/meeple --fail-level error
node tools/validate-themes.mjs
npx shopify theme dev --store your-store.myshopify.com --path themes/meeple

Then verify on the development store:

  • Set tracker: mark 0, 1, 2, and all items; reload to confirm localStorage; complete the set; confirm unavailable items are skipped.
  • Product signature: set progress matches the home tracker; add missing items adds the unmarked set products, including the current product when unmarked; the fallback link works.
  • Collection page: set bar appears on gilded-fen, hides on mixed collections; all/in-stock/preorder tabs return the right products.
  • Variant selection, price, compare-at price, unit price, media, and add-to-cart state.
  • Cart page and drawer quantities, remove, note, discounts, selling plans, accelerated checkout, and drawer refresh.
  • Preorder dates and release status on products and in the calendar.
  • Search results, no results, predictive search, sort, filter, query preservation.
  • Gift card recipient toggle and hidden fields.
  • Mobile header, menu, search, cart, and horizontal overflow at 390×844.
  • Heading order, keyboard access, focus states, plural labels, and reduced motion.

9. Known limitations

  • The set tracker treats each product handle as one item. It does not count the cards inside a sealed booster box.
  • set_total is the merchant's total for the tracked set. The demo uses the four sealed collector pieces, not the 180 cards inside the fictional TCG set.
  • Owned state is per device and per set. There is no account sync or server-side collection.
  • The complete action adds quantity 1 of each available missing variant; it does not choose a language or edition for the customer.
  • The release-status tabs require the matching tag filter in Search & Discovery.
  • The preorder calendar is curated in the theme editor; it is not an automatic feed from the preorder metafields.
  • The demo images use licensed Shopify Burst photography. Original SVG card art remains in demo/meeple/images/ as offline fallbacks.
  • The theme_info documentation and support URLs point to deivisoft.eu. Publish those pages before submission.
  • The theme ships one preset. Additional presets require a /listings folder and separate demo stores.
  • Shopify Theme Store acceptance is not guaranteed. Review the current requirements and test on a development store before submitting.

10. 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.