Numu AOV Themes

NUMU AOV Themes

Playbook for adding revenue/AOV features to a NUMU V3 theme. Each feature is small, independent, and follows the same conventions — implement them one phase at a time, verifying in the browser after each.

Ground rules (apply to every feature)

• Everything is merchant-controllable from the theme editor. Each feature ships with a show_* checkbox in the section schema (default ON, read as s.show_x !== false) and a text setting for any visible title. Titles render through the theme's inline-edit wrapper so merchants can edit them in the preview.
• Bilingual always — every string has EN + AR forms via the theme's localized(locale, en, ar) helper; icons that imply direction get rtl:rotate-180.
• Hooks before early returns — cart/PDP sections typically have loading/empty/no-product early returns; call every new hook above them (rules of hooks).
• Gate after every change: npx tsc --noEmit && npx vite build in the theme directory.
• Version-bump the theme manifest, package.json, and the bundle handle together so merchants see the update.
• Money units: cart totals reach the theme in major currency units, while promotion/discount rule fields are stored in cents — convert at the boundary, and verify with a real order before trusting any discount math.

Feature catalog

1. Free-shipping progress bar (cart) — smallest, highest ROI

A filling bar at the top of the cart driven by the theme's free-shipping-threshold setting: "Add {amount} more to get free shipping" → "You've earned free shipping!" at 100%. Use role="progressbar" with proper aria values. Remove any older text-only nudge so the same promise never reads twice.

2. Promotions display (cart + PDP)

NUMU exposes the store's active promotions to the storefront; the host renders announcement bars/popups itself but auto-discount offers render nowhere unless the theme shows them — a merchant can configure "spend X save Y%" and customers never learn about it.

• Cart nudge: a strip with the best applicable offer + its own progress meter. Rank actionable rules first (tiered > spend-threshold > free-shipping > BOGO) — the nudge exists to change the order, not just inform. Skip free-shipping-kind rules when the theme's own bar (feature 1) is configured.
• PDP offer pill near the price ("Spend X, save Y%" / "Buy 2, get 1 free"). On the PDP rank BOGO first — "buy one more of this" is the strongest per-product nudge.
• Quantity hint at the stepper (BOGO only): "Add 1 more to get 1 free" → "✓ You qualify — 1 free at checkout". Quantity-sensitive, recomputed as the shopper steps.

3. Cart recommendations rail with quick-add

"You may also like" under the cart items: up to 4 mini cards, horizontal snap-scroll on mobile / grid on desktop. Pool = related products of the first cart item, falling back to the store catalog; always exclude products already in the cart (the rail re-filters live after an add — satisfying to watch). Quick-add rule (use everywhere): one-tap add only for single-variant, in-stock products; multi-variant products get a "Choose options" link to the PDP — blind-adding a default size/colour is how wrong items end up in orders.

4. "Added to bag" drawer (PDP)

The moment after add-to-cart is the highest-attention point in the session. Hook the add-to-cart button's success callback (both the main button and any mobile sticky bar) and open a bottom sheet (mobile) / end panel (desktop) containing: confirmation + the added item, live bag subtotal, the offer meter (recomputed with the fresh subtotal), two quick suggestions, then Checkout / View bag / Keep shopping. role="dialog" + aria-modal, Esc + backdrop close, body scroll-lock while open.

5. Grid quick-add

A circular "+" button over product-card images on home/collection grids — always visible on mobile, hover-reveal on desktop. Cards are links, so the button must preventDefault + stopPropagation. Same single-variant rule as the rail. States: idle → spinner → ✓ for 2s.

6. Recently-viewed rail (PDP)

Zero-backend: record each PDP visit into one localStorage key (slim entries: id/slug/name/image/price/currency, newest first, deduped, capped ~8; wrap all storage access in try/catch for private modes). Render the trail minus the current product below the related rail.

7. Low-stock urgency

If the theme already shows "Only X left" for low stock, render it in the sale accent color — muted gray reads as metadata, not urgency.

8. Brand payment badges (footer)

Replace text payment-method names with small brand-colored badges (card networks, local gateways, COD chip); unknown entries fall back to a neutral text chip so custom values never break. Two-layer source: the merchant's explicit comma-separated setting wins; when empty, derive the list from the gateways the checkout actually offers so the trust row never advertises a method the store doesn't accept. Add a show/hide toggle. Accept Arabic method names in the matcher. Related checkout principle: customers pick "Card", not an acquirer — if the checkout lists gateway-branded entries ("Card (GatewayA)", "Card (GatewayB)", duplicate wallet buttons), collapse them into one customer-facing choice per method and let the first-priority gateway process it.

9. Editor-preview sample cart

In the theme customizer the preview session usually has an empty cart, so the merchant can never style the populated cart before publishing. When the theme detects it's inside the editor preview AND the cart is empty, render sample items built from the store's real products (real names/images/prices so the bar/nudge math works), with cart actions disabled and a dashed "sample items" notice. Real cart items always win; the detection signal never exists on the live storefront. Note: on cart/checkout routes the catalog hook may be empty — fetch a few products directly as a fallback.

Data-shape defenses (learned the hard way)

• Product images arrive in TWO shapes depending on the endpoint: [{url}] objects (catalog) vs ["url"] plain strings (related products). Never read images[0].url raw — use a tolerant productImage(p) helper and apply it to every surface that renders products, including pre-existing rails (grep the whole theme for the raw pattern; don't fix only the surfaces you built).
• Same for currency: currency vs price_currency.

QA approach

• Verify each phase in a real browser at a mobile viewport, not just by reading code; measure (element positions, aria values, computed styles) rather than eyeballing.
• For empty-cart scenarios use a fresh/isolated browser context — cart mutations are CSRF-protected, so scripted cart-clearing is more trouble than a clean cookie jar.
• Test offers end-to-end: register a buyer → login → add → apply a discount code → place a test order → verify the stored order totals match what the checkout displayed (display-vs-charge mismatches are the worst class of offer bug).
• QA from the theme editor too, not just the storefront: check every new setting toggles its feature and titles are inline-editable.
• Keep a phase-by-phase log file ("session memory") recording what changed, what was verified, and every footgun — it compounds across sessions.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Yahiasherif002
• Source: Yahiasherif002/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.