@funnelsgrove/cli 0.1.10 → 0.1.12

package/template_docs/docs/step-ui-guidelines.md

@@ -0,0 +1,110 @@
+# Step UI Guidelines
+
+Every step must pass these rules before it counts as done. They are distilled from high-performing quiz funnels (BetterMe-class) and apply to new steps, edited steps, and paywalls alike.
+
+## Viewports
+
+Funnels are mobile-first, but QA must cover the desktop-small shell too. Build
+and verify every created or edited step at the default breakpoints in
+`src/config/funnel.manifest.ts`:
+
+| Breakpoint | Size | Role |
+| --- | --- | --- |
+| small | **375 x 667** | iPhone SE and smaller-width stress check. |
+| medium | **393 x 852** | iPhone 15 baseline. |
+| large | **402 x 874** | iPhone 17 Pro baseline. |
+| desktop-small | **1280 x 800** | 13-inch MacBook baseline. |
+
+Pass criteria at every breakpoint: no horizontal scroll, no clipped or overlapping content, the primary CTA visible without scrolling on selection/input steps, and tap targets at least 44px tall.
+
+## Layout Shell Contract
+
+The shell (`src/components/FunnelFlow.tsx`) owns the frame; steps fill the middle:
+
+1. **Fixed top bar** — opaque background, back arrow, brand or section title, optional progress. Thin bottom hairline.
+2. **Scrollable content** — the step body. Must add bottom padding so the last element clears the action bar.
+3. **Fixed bottom action bar** — the Continue button area. **The bar is opaque, never transparent** — content scrolling under a floating button is a defect. Reference implementation:
+
+```css
+position: fixed;
+bottom: 0;
+left: 0;
+right: 0;
+background: var(--color-surface);          /* solid — no alpha */
+border-top: 1px solid rgba(23, 23, 23, 0.08);
+padding: 16px 20px calc(16px + env(safe-area-inset-bottom));
+z-index: 11;
+```
+
+The button itself: full width, ~50px tall, pill radius, theme primary color. Disabled state stays visible (washed-out), it never disappears.
+
+Steps control the shell bar through `FunnelStepMeta.actionBar`:
+
+- omit → default Continue button;
+- `{ buttonText: '...' }` → custom label;
+- `{ hidden: true }` → step owns its CTAs (paywalls);
+- auto-advance steps (single-select) need no bar at all.
+
+## Step Patterns
+
+One decision per screen. Pick the matching pattern; do not invent hybrids.
+
+**Single-select** — tap an option → store answer → `goNext()` immediately. No Continue button. Option cards: icon or image + label + radio indicator, ~16px gap, selected state with tinted background.
+
+**Multi-select** — "Choose all that apply" subtitle, checkbox cards, sticky Continue **disabled until at least one selection**. A "None of the above" option clears and excludes the others.
+
+**Scale question** — statement in quotes as the headline, 1–5 buttons in a row, anchored labels ("Strongly disagree" / "Strongly agree") at the ends. Auto-advance on tap.
+
+**Numeric input** (height, weight, age) — large centered input, unit toggle (kg/lbs, cm/ft) where relevant, visible validation range hint ("enter a value from 90 cm to 243 cm"), Continue disabled until valid. When the value enables personalization, show instant inline feedback below the input (e.g. a BMI callout: amber card, icon, bold key phrase, supportive copy that says how the data will be used). Hard-stop ineligible values with a clear message, not a silent disable.
+
+**Info interstitial** — headline, hero image card, 2–3 short supporting lines, sticky Continue. Insert one every 3–5 questions to re-sell the promise and break monotony; tie it to the answer just given ("Keep your back and knees strong → your plan will include…").
+
+**Personalized summary** — mirror the user's data back (profile card, gauge with the user's position, attribute list, projection chart with goal badge and date). Charts that predict results need a compliance footnote ("illustrative purposes only / results vary").
+
+**Loading / plan-building** — animated percent ring or bar plus rotating social proof (ratings, testimonials) during the wait. Auto-advance on completion.
+
+**Email capture** — single email field, nothing else on screen. Headline names the deliverable ("Enter your email to get your plan"). Padlock icon + one privacy reassurance line + Privacy Policy link. Marketing opt-in is its own subsequent step, never a pre-checked box.
+
+## Paywall Anatomy
+
+The proven block order, top to bottom:
+
+1. **Sticky offer header** — compact bar with countdown timer ("Reserved price for 09:59") and a small CTA, always visible while scrolling.
+2. **Before/after comparison** — "Now" vs "Your Goal" with attribute deltas.
+3. **Applied-discount card** — promo code chip, "applied automatically" copy, countdown.
+4. **Plan cards** — usually three; mark one "MOST POPULAR" and preselect it; show struck-through old total → discounted total and a large per-day price anchor.
+5. **Primary CTA** directly under the cards.
+6. **Auto-renewal disclosure** — full renewal price, interval, cancellation path. Required, directly below the CTA.
+7. **Plan highlights** — icon + bold benefit + one-line explanation.
+8. **Trust blocks** — press logos, testimonials with concrete results, results disclaimer.
+9. **FAQ** ("What happens after payment?") and **money-back guarantee** with conditions.
+10. Repeat plan cards + CTA at the bottom for long pages.
+
+Checkout opens as a modal over the paywall: itemized breakdown (regular price, discount line, promo chip, VAT, total, "you save" line), wallet buttons first (Apple Pay / Google Pay / PayPal as available), card entry collapsed behind a radio. Closing the checkout without paying triggers the second-stage discount dialog ([payment-plans-and-discounts.md](payment-plans-and-discounts.md)) — verify both discount stages whenever you touch the paywall.
+
+## Image Performance
+
+Use the ClaimBee/Blessly image loading pattern:
+
+- Keep raster artwork on the build-time optimization path so publish can shrink
+  PNG/JPEG sources and create AVIF/WebP variants.
+- Put step image metadata in `funnelManifest.assets` and reference those images
+  from each step with `assetIds`.
+- Above-the-fold images on the current step use the framework's priority/preload
+  mechanism.
+- The flow shell may warm likely next-step images at low priority shortly after
+  the active step loads. Do not preload the whole funnel image set on first load.
+- Any image-heavy funnel should keep a contract test that every `assetId`
+  resolves and the shell uses manifest-driven next-step preloads.
+
+## Content-Fit Audit
+
+Run on every created or edited step at small 375x667, medium 393x852, large 402x874, and desktop-small 1280x800:
+
+1. Open the step in local preview (`npm run dev`).
+2. Check: nothing clipped, nothing overlapping, no text truncated mid-word, images loaded with correct aspect, CTA fully visible above the fold on selection/input steps.
+3. Scroll to both ends — last content clears the action bar; nothing hides under the top bar.
+4. Check disabled→enabled CTA transition where applicable.
+5. Fix and re-check before moving to another step.
+
+Report the audit (all four breakpoints, pass/fail per step) in your summary.