numu-AOV-themes
Skill1 starsChanged 5 months agoMITView on GitHub
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 NUMU theme or port these features to another theme.
In this repository11 other files it gives its agents.
- ask-terminalSkill
- build-themeSkill
- command-paletteSkill
- deploy-doctorSkill
- github-activitySkill
- llm-endpointSkill
- numu-store-founderSkill
- og-imageSkill
- scroll-reveal-kitSkill
- seo-kitSkill
- theme-toggleSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 44
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.
- Distinctive: line 58
Verify each phase in a real browser at a mobile viewport, not just by reading code.
- Distinctive: line 60
Test offers end-to-end: register a buyer → login → add → apply a discount code → place a test order → verify the stored order totals match …
- Distinctive: line 62
Keep a phase-by-phase log file ("session memory") recording what changed, what was verified, and every footgun — it compounds across …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 ass.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 getrtl: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 buildin 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 readimages[0].urlraw — use a tolerantproductImage(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:
currencyvsprice_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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

