@runwell/shopify-toolkit 0.1.0 → 0.2.0

package/modules/_shared/css-tokens/assets/runwell-tokens.css

@@ -0,0 +1,14 @@
+/* Runwell Shopify Toolkit: brand tokens.
+   Generated from runwell.config.json brand vars. Every other module
+   references these via var(--runwell-X). Do not hand-edit in client
+   themes; re-run runwell-shopify sync to update.
+*/
+:root {
+  --runwell-primary: {{brand.primary}};
+  --runwell-accent: {{brand.accent}};
+  --runwell-cream: {{brand.cream}};
+  --runwell-oat: {{brand.oat}};
+  --runwell-celadon: {{brand.celadon}};
+  --runwell-blue: {{brand.blue}};
+  --runwell-rain-forrest: {{brand.rain-forrest}};
+}

package/modules/_shared/css-tokens/module.json

@@ -0,0 +1,13 @@
+{
+  "name": "_shared/css-tokens",
+  "version": "0.1.0",
+  "category": "foundation",
+  "description": "CSS custom properties published as :root vars so every Runwell module pulls brand colors from one source. Always synced.",
+  "always_enabled": true,
+  "files": {
+    "assets": ["assets/runwell-tokens.css"]
+  },
+  "config": {
+    "schema": {}
+  }
+}

package/modules/cart-cross-sell/README.md

@@ -0,0 +1,32 @@
+# cart-cross-sell
+
+Cart drawer cross-sell suggestion. Picks the first available product not already in cart and renders a one-click Add card.
+
+## Files
+
+- `snippets/runwell-cart-xsell.liquid`
+
+## How to use
+
+In `snippets/cart-drawer.liquid` body:
+
+```liquid
+{% render 'runwell-cart-xsell' %}
+```
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `eyebrow` | `Pairs well with` | Tag above the suggestion |
+| `cta_label` | `Add` | Button label |
+
+## Replaces
+
+Rebuy, One Click Upsell (OCU) pre-purchase display layer.
+
+## Future variants
+
+- `tag-based`: filter to products tagged complementary to cart contents
+- `metafield-curated`: per-product complementary set in `lushi.complements` metafield
+- `recommendations-api`: Shopify `recommendations.json?intent=complementary`

package/modules/cart-cross-sell/module.json

@@ -0,0 +1,15 @@
+{
+  "name": "cart-cross-sell",
+  "version": "0.1.0",
+  "category": "conversion",
+  "description": "Cart drawer cross-sell card. Suggests one related product not yet in cart with one-click Add. Replaces Rebuy / OneClickUpsell pre-purchase upsell.",
+  "files": {
+    "snippets": ["snippets/runwell-cart-xsell.liquid"]
+  },
+  "config": {
+    "schema": {
+      "eyebrow": { "type": "string", "default": "Pairs well with" },
+      "cta_label": { "type": "string", "default": "Add" }
+    }
+  }
+}

package/modules/cart-cross-sell/snippets/runwell-cart-xsell.liquid

@@ -0,0 +1,40 @@
+{%- comment -%}
+  Runwell cart cross-sell. Surfaces the first available product not
+  already in cart. Replaces Rebuy/OneClickUpsell pre-purchase upsell
+  display. Render inside cart-drawer.liquid via:
+  {% render 'runwell-cart-xsell' %}
+{%- endcomment -%}
+
+{%- if cart.item_count > 0 -%}
+  {%- assign cart_handles = cart.items | map: 'handle' -%}
+  {%- assign suggestion = blank -%}
+  {%- for p in collections.all.products -%}
+    {%- unless cart_handles contains p.handle -%}
+      {%- if p.available -%}
+        {%- assign suggestion = p -%}
+        {%- break -%}
+      {%- endif -%}
+    {%- endunless -%}
+  {%- endfor -%}
+  {%- if suggestion != blank -%}
+    <div class="runwell-cart-xsell" data-runwell-xsell>
+      <p class="runwell-cart-xsell__eyebrow">{{config.eyebrow}}</p>
+      <div class="runwell-cart-xsell__row">
+        {%- if suggestion.featured_image -%}
+          <a href="{{ suggestion.url }}" class="runwell-cart-xsell__media" aria-hidden="true" tabindex="-1">
+            <img src="{{ suggestion.featured_image | image_url: width: 120 }}" alt="" width="60" height="60" loading="lazy">
+          </a>
+        {%- endif -%}
+        <div class="runwell-cart-xsell__body">
+          <a href="{{ suggestion.url }}" class="runwell-cart-xsell__title">{{ suggestion.title }}</a>
+          <span class="runwell-cart-xsell__price">{{ suggestion.price | money }}</span>
+        </div>
+        <form action="{{ routes.cart_add_url }}" method="post" enctype="multipart/form-data" class="runwell-cart-xsell__form">
+          <input type="hidden" name="id" value="{{ suggestion.selected_or_first_available_variant.id }}">
+          <input type="hidden" name="quantity" value="1">
+          <button type="submit" class="runwell-cart-xsell__cta">{{config.cta_label}}</button>
+        </form>
+      </div>
+    </div>
+  {%- endif -%}
+{%- endif -%}

package/modules/cart-freeship-progress/README.md

@@ -0,0 +1,29 @@
+# cart-freeship-progress
+
+Cart drawer free-shipping progress bar. Renders dynamic remaining-to-free-ship message + a CSS progress fill that updates with cart total.
+
+## Files
+
+- `snippets/runwell-cart-freeship.liquid`
+
+## How to use
+
+In `snippets/cart-drawer.liquid` (or wherever your cart drawer body is):
+
+```liquid
+{% render 'runwell-cart-freeship' %}
+```
+
+CSS is part of `_shared/css-tokens` + the styles already present in the merchant theme stylesheet (look for `.runwell-freeship` rules in your CSS).
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `threshold_cents` | `7500` | Threshold in cents (USD `$75 = 7500`). Adjust for currency. |
+| `away_text` | `away from free shipping.` | Text appended after the dynamic remaining amount |
+| `unlocked_message` | `You unlocked free shipping. <strong>Glow on.</strong>` | HTML shown when cart total clears the threshold |
+
+## Replaces
+
+Bold Free Shipping Manager, similar app features.

package/modules/cart-freeship-progress/module.json

@@ -0,0 +1,16 @@
+{
+  "name": "cart-freeship-progress",
+  "version": "0.1.0",
+  "category": "conversion",
+  "description": "Cart drawer free-shipping progress bar. Shows remaining $$ to free ship + visual progress fill. Replaces Bold Free Shipping Manager and similar app features.",
+  "files": {
+    "snippets": ["snippets/runwell-cart-freeship.liquid"]
+  },
+  "config": {
+    "schema": {
+      "threshold_cents": { "type": "number", "default": 7500, "label": "Free shipping threshold (cents)" },
+      "away_text": { "type": "string", "default": "away from free shipping.", "label": "Text after remaining amount" },
+      "unlocked_message": { "type": "string", "default": "You unlocked free shipping. <strong>Glow on.</strong>", "label": "HTML shown when threshold met" }
+    }
+  }
+}

package/modules/cart-freeship-progress/snippets/runwell-cart-freeship.liquid

@@ -0,0 +1,27 @@
+{%- comment -%}
+  Runwell cart free-shipping progress bar.
+  Renders inside cart-drawer.liquid via {% render 'runwell-cart-freeship' %}.
+  Replaces inline implementations and the freeship-bar feature in apps
+  like Vitals / Bold Free Shipping Manager.
+{%- endcomment -%}
+
+{%- assign runwell_freeship_threshold_cents = {{config.threshold_cents}} -%}
+{%- assign runwell_remaining = runwell_freeship_threshold_cents | minus: cart.total_price -%}
+<div class="runwell-freeship">
+  {%- if cart.item_count > 0 -%}
+    {%- if runwell_remaining > 0 -%}
+      <p class="runwell-freeship__msg">
+        You're <strong>{{ runwell_remaining | money }}</strong> {{config.away_text}}
+      </p>
+    {%- else -%}
+      <p class="runwell-freeship__msg runwell-freeship__msg--unlocked">
+        {{config.unlocked_message}}
+      </p>
+    {%- endif -%}
+    <div class="runwell-freeship__track" aria-hidden="true">
+      {%- assign pct = cart.total_price | times: 100.0 | divided_by: runwell_freeship_threshold_cents -%}
+      {%- if pct > 100 -%}{%- assign pct = 100 -%}{%- endif -%}
+      <div class="runwell-freeship__fill" style="width: {{ pct }}%"></div>
+    </div>
+  {%- endif -%}
+</div>

package/modules/cart-usps/README.md

@@ -0,0 +1,22 @@
+# cart-usps
+
+Three brand promises listed at the bottom of the cart drawer. Reinforces trust at the moment of decision.
+
+## Files
+
+- `snippets/runwell-cart-usps.liquid`
+
+## How to use
+
+```liquid
+{% render 'runwell-cart-usps' %}
+```
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `icon` | `✓` | Bullet icon (HTML entity or emoji) |
+| `usp_1` | `30-day satisfaction promise` | First USP |
+| `usp_2` | `Editorially curated, not bulk-stocked` | Second USP |
+| `usp_3` | `Every product paired with a journal post` | Third USP |

package/modules/cart-usps/module.json

@@ -0,0 +1,17 @@
+{
+  "name": "cart-usps",
+  "version": "0.1.0",
+  "category": "conversion",
+  "description": "Three brand promises listed at the bottom of the cart drawer. Native, no app.",
+  "files": {
+    "snippets": ["snippets/runwell-cart-usps.liquid"]
+  },
+  "config": {
+    "schema": {
+      "icon": { "type": "string", "default": "✓", "label": "Bullet icon (HTML entity or emoji)" },
+      "usp_1": { "type": "string", "default": "30-day satisfaction promise" },
+      "usp_2": { "type": "string", "default": "Editorially curated, not bulk-stocked" },
+      "usp_3": { "type": "string", "default": "Every product paired with a journal post" }
+    }
+  }
+}

package/modules/cart-usps/snippets/runwell-cart-usps.liquid

@@ -0,0 +1,11 @@
+{%- comment -%}
+  Runwell cart USPs. Three short bullets at the bottom of the cart
+  drawer reinforcing brand promises. Render via:
+  {% render 'runwell-cart-usps' %}
+{%- endcomment -%}
+
+<ul class="runwell-cart-usps" aria-label="Brand promises">
+  <li><span aria-hidden="true">{{config.icon}}</span> {{config.usp_1}}</li>
+  <li><span aria-hidden="true">{{config.icon}}</span> {{config.usp_2}}</li>
+  <li><span aria-hidden="true">{{config.icon}}</span> {{config.usp_3}}</li>
+</ul>

package/modules/editorial-hero/sections/runwell-video-hero.liquid

@@ -28,11 +28,11 @@
       height="1080"
       loading="eager"
     >
-  {%- else -%}
-    {%- comment -%} Fallback to bundled v1 imagery so the hero is never blank pre-launch {%- endcomment -%}
+  {%- elsif section.settings.fallback_asset != blank -%}
+    {%- comment -%} Fallback to bundled brand image so the hero is never blank pre-launch {%- endcomment -%}
     <img
       class="runwell-video-hero__video"
-      src="{{ 'runwell-hero-bg.jpg' | asset_url }}"
+      src="{{ section.settings.fallback_asset | asset_url }}"
       alt="{{ section.settings.heading | escape }}"
       width="1920"
       height="1080"
@@ -109,6 +109,12 @@
       "id": "poster_image",
       "label": "Poster image (and fallback)"
     },
+    {
+      "type": "text",
+      "id": "fallback_asset",
+      "label": "Fallback asset filename",
+      "info": "Bundled theme asset filename (e.g. lushi-hero-bg.jpg). Used when video_url and poster_image are blank."
+    },
     {
       "type": "range",
       "id": "min_height",

package/modules/gift-with-purchase/README.md

@@ -0,0 +1,36 @@
+# gift-with-purchase
+
+Auto-add a gift product to the cart when total clears a threshold. Shows progress message before unlock and confirmation after. Combine with a Shopify 100%-off automatic discount on the gift SKU so the line lands free at checkout.
+
+## Files
+
+- `snippets/runwell-gwp.liquid`. Cart-drawer snippet rendering progress + unlock state.
+- `assets/runwell-gwp.js`. Auto-adder. Posts to `/cart/add.js` once when threshold is met and gift is not yet in cart.
+
+## How to use
+
+1. Run admin steps in `module.json`: create the gift product, create the 100% off automatic discount targeting it
+2. Render the snippet in `snippets/cart-drawer.liquid`:
+   ```liquid
+   {% render 'runwell-gwp' %}
+   ```
+3. Sync: `runwell-shopify sync`
+
+## Behaviour
+
+- Cart total below threshold: shows "Spend $X more for [unlocked_message]"
+- Cart total above threshold AND gift not yet in cart: auto-adds gift, shows "[unlocked_message]"
+- Cart total above threshold AND gift in cart: shows "[unlocked_message]" only
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `threshold_cents` | `10000` | $100 default. Adjust per AOV. |
+| `gift_handle` | `free-gift` | Product handle for the auto-added gift |
+| `unlocked_message` | `You earned a free gift.` | Shown when threshold met |
+| `locked_message_suffix` | `a free gift.` | Appended to "Spend $X more for..." |
+
+## Replaces
+
+Free Gifts BOGO Plus, Bold Free Gifts, Tada free gift apps.

package/modules/gift-with-purchase/assets/runwell-gwp.js

@@ -0,0 +1,42 @@
+/* Runwell gift-with-purchase auto-adder. When the cart drawer renders
+   a [data-runwell-gwp] element AND the configured gift product is not
+   already in cart, this script POSTs to /cart/add.js to add it.
+   Quantity is locked to 1. The merchant should also create a
+   "Gift" discount in Shopify that makes the gift product 100% off when
+   cart total >= threshold (so the auto-added line is free). */
+(function () {
+  if (typeof window === 'undefined') return;
+
+  function autoAddGift() {
+    var unlocked = document.querySelector('.runwell-gwp--unlocked');
+    if (!unlocked) return;
+    var giftHandle = unlocked.getAttribute('data-gift-handle');
+    if (!giftHandle) return;
+    if (window._runwellGwpAdded) return;
+    window._runwellGwpAdded = true;
+
+    fetch('/products/' + giftHandle + '.js')
+      .then(function (r) { return r.ok ? r.json() : null; })
+      .then(function (product) {
+        if (!product) return;
+        var variantId = product.variants && product.variants[0] && product.variants[0].id;
+        if (!variantId) return;
+        return fetch('/cart/add.js', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
+          body: JSON.stringify({ id: variantId, quantity: 1, properties: { _runwell_gift: '1' } })
+        });
+      })
+      .then(function () {
+        if (typeof window.fetchCart === 'function') window.fetchCart();
+        document.dispatchEvent(new CustomEvent('runwell:cart:refresh'));
+      })
+      .catch(function () { window._runwellGwpAdded = false; });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', autoAddGift);
+  } else {
+    autoAddGift();
+  }
+})();

package/modules/gift-with-purchase/module.json

@@ -0,0 +1,32 @@
+{
+  "name": "gift-with-purchase",
+  "version": "0.1.0",
+  "category": "conversion",
+  "description": "Auto-add a gift product to the cart when total clears a threshold. Shows progress message before unlock and confirmation after. Combine with a 100%-off discount on the gift SKU so it lands free.",
+  "files": {
+    "snippets": ["snippets/runwell-gwp.liquid"],
+    "assets": ["assets/runwell-gwp.js"]
+  },
+  "config": {
+    "schema": {
+      "threshold_cents": { "type": "number", "default": 10000, "label": "Spend threshold in cents (e.g. 10000 = $100)" },
+      "gift_handle": { "type": "string", "default": "free-gift", "label": "Product handle for the gift" },
+      "unlocked_message": { "type": "string", "default": "You earned a free gift." },
+      "locked_message_suffix": { "type": "string", "default": "a free gift." }
+    }
+  },
+  "admin_steps": [
+    {
+      "id": "create-gift-product",
+      "label": "Create the gift product",
+      "url": "https://admin.shopify.com/store/{store_handle}/products/new",
+      "summary": "Create a product matching the gift_handle config (default: free-gift). Set a baseline price (e.g. $10) so it shows value. Inventory: enough for forecast monthly volume."
+    },
+    {
+      "id": "create-gift-discount",
+      "label": "Create the 100% off discount on the gift product",
+      "url": "https://admin.shopify.com/store/{store_handle}/discounts/new",
+      "summary": "Discount type: Amount off products. Code or Automatic: Automatic preferred. Value: 100%. Applies to: Specific products > select the gift product. Minimum requirement: Subtotal >= $100 (matching threshold_cents). Customer eligibility: All customers. So the auto-added gift line lands free at checkout."
+    }
+  ]
+}

package/modules/gift-with-purchase/snippets/runwell-gwp.liquid

@@ -0,0 +1,30 @@
+{%- comment -%}
+  Runwell gift-with-purchase. Shows a "free gift unlocked" message in
+  the cart drawer when cart total clears the threshold. The actual gift
+  product gets auto-added via runwell-gwp.js (cart.js write).
+  Render inside cart-drawer.liquid:
+
+  {% render 'runwell-gwp' %}
+{%- endcomment -%}
+
+{%- assign threshold_cents = {{config.threshold_cents}} -%}
+{%- assign gift_handle = '{{config.gift_handle}}' -%}
+{%- assign cart_handles = cart.items | map: 'handle' -%}
+
+{%- if cart.total_price >= threshold_cents -%}
+  <div class="runwell-gwp runwell-gwp--unlocked" data-runwell-gwp data-gift-handle="{{ gift_handle }}">
+    <p class="runwell-gwp__msg">{{config.unlocked_message}}</p>
+    {%- unless cart_handles contains gift_handle -%}
+      <p class="runwell-gwp__detail">Adding to your bag now.</p>
+    {%- endunless -%}
+  </div>
+{%- elsif cart.item_count > 0 -%}
+  {%- assign remaining = threshold_cents | minus: cart.total_price -%}
+  <div class="runwell-gwp runwell-gwp--locked">
+    <p class="runwell-gwp__msg">
+      Spend <strong>{{ remaining | money }}</strong> more for {{config.locked_message_suffix}}
+    </p>
+  </div>
+{%- endif -%}
+
+<script src="{{ 'runwell-gwp.js' | asset_url }}" defer="defer"></script>

package/modules/loyalty-tiers/README.md

@@ -0,0 +1,45 @@
+# loyalty-tiers
+
+Lifetime-spend tier card on the customer account page. Combined with Shopify Flow auto-tagging and tag-targeted discounts, replaces Smile.io / Yotpo Loyalty / LoyaltyLion. App-free.
+
+## Why tiers, not points
+
+Points-based loyalty needs:
+- Real-time balance updates (Shopify Flow runs are async, lagging 1 to 5 minutes)
+- A custom redemption endpoint that issues unique discount codes
+- Customer education that's expensive at low scale
+
+Tiers deliver the same psychological lever (status + reward) using only Shopify primitives: `customer.total_spent`, customer tags, Shopify Flow, tag-targeted discounts.
+
+## Files
+
+- `sections/runwell-tier-card.liquid`. Tier card section that renders on the customer account template.
+
+## How to use
+
+1. Run the merchant admin steps in `module.json`:
+   - Create Shopify Flow workflows that auto-tag customers as their lifetime spend crosses the thresholds
+   - Create tier-targeted discount codes (TIER_INSIDER 10%, TIER_FOUNDER 15%)
+   - Add the tier card section to `templates/customers/account.json`
+2. Sync: `runwell-shopify sync`
+3. The tier card renders for any logged-in customer; tier auto-derives from `customer.total_spent`
+
+## Default tiers
+
+| Tier | Threshold | Perk |
+|---|---|---|
+| Curator | $0 (everyone) | Free ship over $75, 30-day returns |
+| Insider | $250 | 10% off code (auto-applied via tag), first-look on new arrivals |
+| Founder | $750 | 15% off code, free shipping always, free sample |
+
+## Config
+
+All tier names, thresholds, and perk percentages are configurable per client. See `module.json` config schema.
+
+## Replaces
+
+Smile.io, Yotpo Loyalty, Stamped Loyalty, LoyaltyLion (display layer; rewards still issued via Shopify Discounts).
+
+## Plan requirement
+
+Works on **Shopify Basic and up**. Shopify Flow is included free on all plans (with a daily action limit).

package/modules/loyalty-tiers/module.json

@@ -0,0 +1,40 @@
+{
+  "name": "loyalty-tiers",
+  "version": "0.1.0",
+  "category": "customer",
+  "description": "Lifetime-spend tier card on the customer account page. Combined with Shopify Flow auto-tagging and tag-targeted discounts, replaces Smile.io / Yotpo Loyalty / LoyaltyLion. App-free.",
+  "files": {
+    "sections": ["sections/runwell-tier-card.liquid"]
+  },
+  "config": {
+    "schema": {
+      "tier_0_name": { "type": "string", "default": "Curator" },
+      "tier_1_name": { "type": "string", "default": "Insider" },
+      "tier_1_threshold": { "type": "number", "default": 250 },
+      "tier_1_perk_pct": { "type": "number", "default": 10 },
+      "tier_2_name": { "type": "string", "default": "Founder" },
+      "tier_2_threshold": { "type": "number", "default": 750 },
+      "tier_2_perk_pct": { "type": "number", "default": 15 }
+    }
+  },
+  "admin_steps": [
+    {
+      "id": "create-tier-tags-and-flows",
+      "label": "Create Shopify Flow workflows for tier auto-tagging",
+      "url": "https://admin.shopify.com/store/{store_handle}/apps",
+      "summary": "Apps > Shopify Flow > Create workflow. Trigger: Order paid. Filter: customer.amount_spent.amount >= 250. Action: Add customer tag runwell-tier-insider + send email. Repeat for >= 750 with runwell-tier-founder."
+    },
+    {
+      "id": "create-tier-discounts",
+      "label": "Create tier-targeted discount codes",
+      "url": "https://admin.shopify.com/store/{store_handle}/discounts/new",
+      "summary": "Two discount codes: TIER_INSIDER (10%) targeting customers tagged runwell-tier-insider, TIER_FOUNDER (15%) targeting customers tagged runwell-tier-founder. Both: amount off order, sitewide, no min, unlimited uses, automatic per customer."
+    },
+    {
+      "id": "add-tier-card-to-account",
+      "label": "Add the tier card to customer account",
+      "url": "https://admin.shopify.com/store/{store_handle}/themes",
+      "summary": "Edit the customer/account.json template (or via theme editor on the Customer account template). Add the Runwell tier card section before the order list."
+    }
+  ]
+}

package/modules/loyalty-tiers/sections/runwell-tier-card.liquid

@@ -0,0 +1,86 @@
+{%- comment -%}
+  Runwell loyalty tier card. Renders on the customer account page
+  showing current tier + progress to next tier. Drives spend tiers via
+  Shopify Flow workflows that auto-tag customers (see admin_steps).
+  Replaces Smile.io / Yotpo Loyalty / LoyaltyLion display layer.
+{%- endcomment -%}
+
+{%- if customer != blank -%}
+  {%- assign spend = customer.total_spent | divided_by: 100.0 -%}
+  {%- assign current_tier = section.settings.tier_0_name -%}
+  {%- assign current_perk_pct = section.settings.tier_0_perk -%}
+  {%- assign next_threshold = section.settings.tier_1_threshold -%}
+  {%- assign next_tier = section.settings.tier_1_name -%}
+
+  {%- if spend >= section.settings.tier_2_threshold -%}
+    {%- assign current_tier = section.settings.tier_2_name -%}
+    {%- assign current_perk_pct = section.settings.tier_2_perk -%}
+    {%- assign next_threshold = 0 -%}
+    {%- assign next_tier = blank -%}
+  {%- elsif spend >= section.settings.tier_1_threshold -%}
+    {%- assign current_tier = section.settings.tier_1_name -%}
+    {%- assign current_perk_pct = section.settings.tier_1_perk -%}
+    {%- assign next_threshold = section.settings.tier_2_threshold -%}
+    {%- assign next_tier = section.settings.tier_2_name -%}
+  {%- endif -%}
+
+  <section class="runwell-tier" aria-labelledby="runwell-tier-heading">
+    <div class="runwell-tier__inner">
+      <header class="runwell-tier__header">
+        <p class="runwell-tier__eyebrow">{{ section.settings.eyebrow }}</p>
+        <h2 id="runwell-tier-heading" class="runwell-tier__name">{{ current_tier }}</h2>
+        {%- if current_perk_pct > 0 -%}
+          <p class="runwell-tier__perk">{{ current_perk_pct }}% off every order, applied automatically at checkout.</p>
+        {%- endif -%}
+      </header>
+
+      {%- if next_tier != blank -%}
+        {%- assign remaining = next_threshold | minus: spend -%}
+        {%- assign pct = spend | times: 100.0 | divided_by: next_threshold -%}
+        {%- if pct > 100 -%}{%- assign pct = 100 -%}{%- endif -%}
+        <div class="runwell-tier__progress">
+          <p class="runwell-tier__progress-label">${{ remaining | round }} to <strong>{{ next_tier }}</strong></p>
+          <div class="runwell-tier__progress-track" aria-hidden="true">
+            <div class="runwell-tier__progress-fill" style="width: {{ pct }}%"></div>
+          </div>
+        </div>
+      {%- else -%}
+        <p class="runwell-tier__topped">You're at the top tier. Welcome to the inside.</p>
+      {%- endif -%}
+
+      <ul class="runwell-tier__perks-list">
+        <li>Free shipping over $75</li>
+        <li>30-day satisfaction promise</li>
+        {%- if customer.tags contains 'runwell-tier-insider' or customer.tags contains 'runwell-tier-founder' -%}
+          <li>First-look access on new arrivals</li>
+        {%- endif -%}
+        {%- if customer.tags contains 'runwell-tier-founder' -%}
+          <li>Free shipping always</li>
+          <li>Free sample with every order</li>
+        {%- endif -%}
+      </ul>
+    </div>
+  </section>
+{%- endif -%}
+
+{% schema %}
+{
+  "name": "Runwell tier card",
+  "tag": "section",
+  "class": "section-runwell-tier",
+  "settings": [
+    { "type": "text", "id": "eyebrow", "label": "Eyebrow", "default": "Your tier" },
+    { "type": "text", "id": "tier_0_name", "label": "Tier 0 name", "default": "Curator" },
+    { "type": "number", "id": "tier_0_perk", "label": "Tier 0 perk %", "default": 0 },
+    { "type": "text", "id": "tier_1_name", "label": "Tier 1 name", "default": "Insider" },
+    { "type": "number", "id": "tier_1_threshold", "label": "Tier 1 spend threshold ($)", "default": 250 },
+    { "type": "number", "id": "tier_1_perk", "label": "Tier 1 perk %", "default": 10 },
+    { "type": "text", "id": "tier_2_name", "label": "Tier 2 name", "default": "Founder" },
+    { "type": "number", "id": "tier_2_threshold", "label": "Tier 2 spend threshold ($)", "default": 750 },
+    { "type": "number", "id": "tier_2_perk", "label": "Tier 2 perk %", "default": 15 }
+  ],
+  "presets": [
+    { "name": "Runwell tier card" }
+  ]
+}
+{% endschema %}

package/modules/product-badges/README.md

@@ -0,0 +1,35 @@
+# product-badges
+
+Tag-driven product card badges (Best seller / New / Editor's pick). Renders inside the card-product snippet.
+
+## Files
+
+- `snippets/runwell-product-badges.liquid`
+
+## How to use
+
+In `snippets/card-product.liquid` near the existing `card__badge` block:
+
+```liquid
+{% render 'runwell-product-badges', product: card_product %}
+```
+
+## Tags
+
+- Tag a product with `best-seller` to render the Best seller badge
+- Tag with `new` for the New badge
+- Tag with `editor-pick` for the Editor's pick badge
+
+Tags are added in Shopify admin: Products > {product} > Tags.
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `label_best_seller` | `Best seller` | Localise per locale |
+| `label_new` | `New` | Localise per locale |
+| `label_editor_pick` | `Editor's pick` | Localise per locale |
+
+## Replaces
+
+Badge widgets in Vitals, BSS, and similar.

package/modules/product-badges/module.json

@@ -0,0 +1,16 @@
+{
+  "name": "product-badges",
+  "version": "0.1.0",
+  "category": "social-proof",
+  "description": "Tag-driven badges on product cards (Best seller, New, Editor's pick). Native, no app.",
+  "files": {
+    "snippets": ["snippets/runwell-product-badges.liquid"]
+  },
+  "config": {
+    "schema": {
+      "label_best_seller": { "type": "string", "default": "Best seller" },
+      "label_new": { "type": "string", "default": "New" },
+      "label_editor_pick": { "type": "string", "default": "Editor's pick" }
+    }
+  }
+}