Deivisoft Themes

Topnote

A scent-discovery Shopify theme for home fragrance.
Version 0.1.0 · Shopify Online Store 2.0 · Liquid, JSON templates, native CSS and JavaScript

1. Purpose

Topnote is built for home fragrance stores that sell by note, room, mood, and intensity: candles, reed diffusers, room sprays, incense, refills, and sample sets. The buying anxiety is not “what is this?” It is “will this smell right in my room, and will it be too strong or too weak?”

The signature interaction is the Scent Finder. Four questions — room, mood, intensity, and format — narrow a collection to three products using product tags. A sample-first CTA sits beside the questions so a customer can try before committing to a full bottle. Everything is native Liquid and vanilla JavaScript: no app, no remote API, no dead button.

2. What is included

  • Complete Online Store 2.0 theme: JSON templates, sections, blocks, header and footer section groups.
  • Scent-led home page: full-bleed scent hero, five-family scent index, four-question scent finder, sample set, note pyramid, layering story, FAQ, and newsletter.
  • Product page with top/heart/base notes, intensity meter, burn time or longevity, room size, wax and wick, clean-burn and refill notes, layering pairs, and a sample-first CTA.
  • Note-card product cards with scent family, top/heart/base notes, intensity meter, format, price, and quick add.
  • Dark editorial collection page with native filters for family, intensity, room, format, wax, and season.
  • Cart drawer, predictive search, account component, gift card, password, 404, blog, article, and contact 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.
  • Licensed Shopify Burst photography (six product squares, two landscapes) and an importable six-product CSV in demo/topnote/.

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

To upload an unpublished theme:

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

Option B — Admin upload

  1. Create a ZIP of the themes/topnote 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 — near-black, cream, amber, surface, rule, and smoke.
  • Typography — Fraunces headings, Work Sans body, base size, heading scale.
  • Layout — page width, section spacing, corner radius, amber ambient glow.
  • Product cards — scent family, note ladder, intensity meter, arch or rectangle portraits.
  • Social media — profile URLs used by the footer.
  • SEO — social share image and favicon.

If the store's font library does not offer Fraunces, choose Playfair Display in the heading font picker. The theme reads the picker, so no code change is required.

Home page sections

The default index.json composes:

  1. Scent hero
  2. Scent families
  3. Scent finder
  4. Sample set
  5. Note pyramid
  6. Layering
  7. FAQ
  8. Newsletter

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

Scent Finder

The finder is a section setting plus a fixed four-question form:

Question Tags used
Room room-living, room-bedroom, room-kitchen, room-bathroom
Mood mood-calm, mood-bright, mood-warm, mood-grounding
Intensity intensity-light, intensity-medium, intensity-strong
Format format-candle, format-diffuser, format-spray, format-incense, format-refill, format-sample

Choose a collection in the Scent finder section. Every product in that collection is rendered into a hidden pool with its tags and availability. On submit, vanilla JavaScript scores each product by exact tag matches, prefers available products, lowers the score of the sample set unless the customer asked for a sample, and clones the top three note cards into the results grid. The sample product setting adds a quick-add sample CTA below the questions.

The form posts to the selected collection URL, so without JavaScript the button still works as a clear path to the full collection. The results panel is hidden until JavaScript fills it.

Limitations: the finder depends on consistent product tags. Products without matching tags still appear as fallback results, but they will not be ranked. The finder searches the chosen collection only; it is not a global search. A no-JS customer sees the collection, not a personalized result.

Product signature

snippets/product-signature.liquid reads these product metafields, with section block fallbacks:

Metafield Type Used by
custom.scent_family Single-line text Product card, product eyebrow
custom.format Single-line text Product card, burn-time label
custom.top_notes Single-line text Note pyramid
custom.heart_notes Single-line text Note pyramid
custom.base_notes Single-line text Note pyramid
custom.intensity Single-line text Intensity meter; use Light, Medium, or Strong
custom.burn_time Single-line text Burn time, longevity, or uses depending on format
custom.room_size Single-line text Room size
custom.wax Single-line text Wax
custom.wick Single-line text Wick
custom.clean_burn Multi-line text Clean-burn note
custom.refill Multi-line text Refill note
custom.layering_pairs Single-line text Comma-separated product handles for layering

Missing rows are hidden. If no note, spec, prose, layering, or sample data exists, the signature section is not rendered at all.

The Sample product setting on the product section adds a sample-first CTA to every product page. It is hidden when blank and hidden on the sample product's own page. The CTA uses the sample product's first available variant and the shared quick-add behavior.

The burn-time label changes by format: diffusers show Longevity, room sprays show Uses, sample sets show Try, and candles, refills, and incense show Burn time. The value still comes from custom.burn_time, so a diffuser can hold “3–4 months” and a spray can hold “60+ uses”.

Demo catalog and tags

demo/topnote/products.csv contains six products: a candle, a diffuser, a room spray, a sample set, a refill, and incense. Tags cover all five families, four rooms, three intensities, six formats, wax, season, and mood. The demo README documents the exact tag vocabulary and collections.

Collections and filters

Create these collections:

  • scent-finder — all six products; used by the finder.
  • samples — the sample trio.
  • candles, diffusers, room-sprays, incense — format shelves.
  • woody, citrus, floral, smoky, fresh — family shelves.
  • layering — a curated pairing shelf.

In the Search & Discovery app, add tag filters for Family, Intensity, Room, Format, Wax, and Season. The collection page renders Shopify's native filters, active pills, sorting, and pagination.

Recommended content

  • Pages: About, Scent guide, Contact (use the page.contact template), Samples, Shipping.
  • Menus: main-menu, footer, customer-account-main-menu.
  • Two articles so the blog and article templates are testable.
  • Shipping, refund, terms of service, and privacy policies.

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 sensory editorial 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 scent finder.
  • Sections — add or duplicate sections in sections/. Each section has a {% schema %} block.
  • Product page blocks — reorder or hide blocks in the editor. The purchase form is a block, so it can sit after the scent dossier.
  • Translation — edit locales/en.default.json. The theme uses t filters for storefront strings.
  • Icons — snippets/icon.liquid contains original SVG paths.

7. Validation status

  • shopify theme check --path themes/topnote --fail-level error: 0 offenses in the final run.
  • node tools/validate-themes.mjs: required files, JSON, section references, render references, account component, localization, and Follow on Shop checks pass for Topnote.
  • Live-store installation, scent-finder 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/topnote --fail-level error
node tools/validate-themes.mjs
npx shopify theme dev --store your-store.myshopify.com --path themes/topnote

Then verify on the development store:

  • Scent Finder: all four questions, three results, sample CTA, reset, and no-JS collection fallback.
  • Product page: note pyramid, intensity meter, burn-time label by format, layering links, and sample CTA.
  • 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.
  • Collection filters for family, intensity, room, format, wax, and season; query preservation on search.
  • 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 finder depends on consistent tags and the chosen collection. It is not a global search.
  • Without JavaScript, the finder submits to the collection rather than rendering personalized results. The sample CTA and quick-add forms still post normally.
  • The sample-first CTA is a section setting, not a per-product metafield. Use the same sample product across the catalog, or create alternate product templates with a different sample product.
  • The demo catalog uses licensed Shopify Burst photography. Original SVGs remain in demo/topnote/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.