# Numu AOV Themes > Add AOV (Average Order Value) features to a NUMU V3 (BYOT) storefront theme — free-shipping progress bar, promotions display, cart recommendations with quick-add, added-to-bag drawer, grid quick-add, recently-viewed rail, brand payment badges, and an editor-preview sample cart. Includes the design rules, editor-settings conventions, and QA approach. Use when asked to raise AOV / conversion on a N… - **Type:** Skill - **Install:** `agentstack add skill-yahiasherif002-claude-skills-numu-aov-themes` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Yahiasherif002](https://agentstack.voostack.com/s/yahiasherif002) - **Installs:** 0 - **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Yahiasherif002](https://github.com/Yahiasherif002) - **Source:** https://github.com/Yahiasherif002/claude-skills/tree/master/numu-AOV-themes ## Install ```sh agentstack add skill-yahiasherif002-claude-skills-numu-aov-themes ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://github.com/Yahiasherif002) - **Source:** [Yahiasherif002/claude-skills](https://github.com/Yahiasherif002/claude-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-yahiasherif002-claude-skills-numu-aov-themes - Seller: https://agentstack.voostack.com/s/yahiasherif002 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.