Deivisoft Themes

Selvedge

A project-first Shopify theme for craft supply stores.
Version 0.1.0 · Shopify Online Store 2.0 · Liquid, JSON templates, native CSS and JavaScript

1. Purpose

Selvedge is built for stores that sell materials for a specific making project: fabric shops, yarn stores, quilting suppliers, pattern makers, and notions shelves. The buying model is project-based. The customer chooses a project, size, and materials, and the theme turns that into a complete cart.

The signature interaction is the Project Builder. A second native calculator on the product page answers “How much do I need?” from product metafields or block settings. Neither feature uses an app, a remote API, or a third-party script.

2. What is included

  • Complete Online Store 2.0 theme: JSON templates, sections, blocks, header and footer section groups.
  • Project-led home page: split project hero, four project tiles, stash staples, project builder, method, studio story, FAQ, and newsletter.
  • Project Builder with project blocks, size multipliers, material lists, and one-step cart add through /cart/add.js.
  • Product page with a native fiber card, dye-lot and care notes, substitution guidance, quantity calculator, and “Add all materials” path.
  • Swatch-forward product cards with fiber, weight, and project-use labels.
  • Collection page with a swatch grid, native sorting and filtering, active filter pills, pagination, and an empty state.
  • Predictive search, cart drawer, cart page, account component, gift card, password, 404, blog, article, and contact templates.
  • Responsive image strategy, keyboard access, visible focus, reduced-motion support, and semantic landmarks.
  • Theme editor settings for colors, typography, layout, product cards, social links, and SEO.
  • Licensed Shopify Burst photography (six product squares, two landscapes) and an importable six-product CSV in demo/selvedge/.

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

To upload an unpublished theme:

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

Option B — Admin upload

  1. Create a ZIP of the themes/selvedge 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 — paper, ink, rust, surface, rule, and muted text.
  • Typography — Archivo headings, Work Sans body, base size, heading scale.
  • Layout — page width, section spacing, corner radius, worktable grid lines.
  • Product cards — vendor visibility, fiber and weight, project label, swatch shape.
  • Social media — profile URLs used by the footer.
  • SEO — social share image and favicon.

Home page sections

The default index.json composes:

  1. Project hero
  2. Project tiles
  3. Stash staples
  4. Project builder
  5. How it works
  6. Studio story
  7. FAQ
  8. Newsletter

Every section can be reordered, hidden, or duplicated in the editor. The project hero and project builder are the two pieces that define the buying model.

Project Builder

The builder is a section made of Project blocks. Each block accepts:

Setting Purpose
Project name The label shown on the selector and in the cart property.
Pattern or product The primary product added with the project.
Size label The size shown to the customer, for example Size M or Throw · 12 fat quarters.
Base quantity The primary product quantity at the base size.
Size multiplier Multiplies the base quantity for the selected size. Use 1 for one size.
Material quantity The quantity of each listed material, before the size multiplier.
Material handles Comma-separated product handles, for example sashiko-thread,mend-patch-kit.

The primary quantity is ceil(base quantity × size multiplier). Each material quantity is ceil(material quantity × size multiplier). The builder renders every project server-side, then uses vanilla JavaScript to switch panels, update the hidden variant and quantity inputs, and post the complete item list to /cart/add.js. Each line item receives Project and Size properties, which the cart renders automatically.

Limitation: every listed material in a block uses the same material quantity. A merchant who needs different quantities per material should use separate blocks, or add a note in the product description. This keeps the block schema small and the demo data importable. With JavaScript disabled, the form posts the primary product only; it is a working no-JS fallback, not the full builder.

Quantity calculator

The calculator is rendered by snippets/product-signature.liquid inside the Fiber card and calculator block on the product template.

It reads:

  • custom.yield_per_unit — how many units one package, skein, spool, or metre yields.
  • custom.yield_unit — the unit label, for example metres.
  • custom.package_label — the plural label for the result, for example skeins.
  • custom.package_label_singular — the singular label for a result of one, for example skein.
  • custom.size_yardage — size and units in Label=units pairs separated by semicolons, for example Small=2.5;Medium=3.5;Large=4.5.

The formula is ceil(units needed ÷ yield per unit). The result updates the product form quantity input, and the Use this quantity button scrolls to the add-to-cart button.

Block settings provide fallbacks for yield, yield unit, quantity label, and size data. If no yield is available from either the metafield or the block, the calculator is hidden. If no size data exists, the units input still works on its own.

Add all materials

The Project materials block reads custom.materials as a comma-separated list of product handles. It renders the available variants, then adds the selected product quantity and one of each available material through /cart/add.js. Unavailable materials are skipped and marked. The block hides itself when the metafield is empty.

Optional metafields

The theme works without metafields. These are optional enhancements:

Metafield Type Used by
custom.fiber Single-line text Product card, fiber card
custom.weight Single-line text Product card, fiber card
custom.yardage Single-line text Fiber card
custom.dye_lot Single-line text Fiber card
custom.care Multi-line text Fiber card care note
custom.substitution Multi-line text Fiber card substitution note
custom.yield_per_unit Number (decimal) Quantity calculator
custom.yield_unit Single-line text Quantity calculator
custom.package_label Single-line text Quantity calculator result
custom.package_label_singular Single-line text Quantity calculator result for one
custom.size_yardage Single-line text Quantity calculator sizes
custom.materials Single-line text “Add all materials” block
custom.project_use Single-line text Product card project label
custom.complementary_products List of product references Complementary products block

Metafield definitions are not required. Create them in Settings → Custom data if you want to use the related features.

Recommended content

  • Collections: stash-staples, garment-projects, quilt-projects, bag-projects, mend-projects.
  • Pages: About, Project guide, Contact (use the page.contact template), Shipping.
  • Menus: main-menu, footer, customer-account-main-menu.
  • Native filters: configure Project, Fiber, Weight, and Skill level in the Search & Discovery app. The demo CSV uses tags such as project-garment, fiber-linen, weight-midweight, and skill-beginner.
  • Two articles so the blog and article templates are testable.

6. Customisation

  • Design tokens — edit config/settings_schema.json defaults or use the theme editor. CSS variables are generated in snippets/css-variables.liquid and rendered in the theme, password, and gift card layouts.
  • Theme CSS — assets/theme.css contains the Selvedge art direction. assets/base.css contains shared commerce mechanics and content utilities.
  • Theme JavaScript — assets/base.js contains shared cart, search, header, and motion behavior. assets/theme.js contains the project builder, materials add, and quantity calculator.
  • 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 a block, so it can be positioned directly after the fiber card.
  • Translation — edit locales/en.default.json. The theme uses t filters for storefront strings.
  • Icons — snippets/icon.liquid contains original SVG paths. Add a new when branch for new icons.

7. Validation status

  • shopify theme check --path themes/selvedge --fail-level error: 0 offenses (see the final validation run).
  • node tools/validate-themes.mjs: required files, JSON, section references, render references, account component, localization, and Follow on Shop checks pass for Selvedge.
  • Live-store installation, checkout, project-builder cart behavior, pickup, selling plans, 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/selvedge --fail-level error
node tools/validate-themes.mjs
npx shopify theme dev --store your-store.myshopify.com --path themes/selvedge

Then verify on the development store:

  • Project builder: select each project, confirm the materials list and total, add to cart, confirm project and size properties in the drawer.
  • Calculator: open a product with yield data, change size and units, confirm the quantity input updates.
  • Add all materials: confirm the selected product and listed materials appear in the bag, and unavailable materials are skipped.
  • Variant selection, price, compare-at price, unit price, media, and add-to-cart state.
  • Cart page and drawer quantities, remove, note, discounts, selling plans, and accelerated checkout.
  • Search results, no results, predictive search, sorting, filtering, and 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, and plural labels.

9. Known limitations

  • Live demo store: selvedge-cdzsjn40.myshopify.com (password demo2026). Screenshots and listing copy live in theme-store/.
  • The demo catalog uses licensed Shopify Burst photography. Original SVGs remain in demo/selvedge/images/ as offline fallbacks.
  • The project builder uses a uniform material quantity per block. Use separate blocks for different quantities.
  • The calculator depends on merchant data. Without custom.yield_per_unit, it hides rather than guessing.
  • 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.