Components
The full composition catalog across four tiers — Primitives, Components, Modules, and Views. Filter by tier, or browse them all in composition order.
Primitives
The kit building blocks — the small set of low-level layout and theming primitives (Surface, Scrim, Pill, Bubble, Progress, SegmentBar, ThemeProvider) that every higher tier composes from. They carry no funnel intent of their own; they are the shared vocabulary the rest of the library is built on.
content (5)
Token-driven backdrop/overlay primitive — the single source for scrim chrome. Collapses the library's divergent inline rgba scrim patterns onto the dimmer-* token scale. Three dim levels: minor (dimmer-minor, 0.20 alpha), default (dimmer-default, 0.40 alpha), important (dimmer-important, 0.60 alpha). Supports optional backdrop-filter blur and accepts any element or motion.div via the as prop for animated overlays.
Used in 1 recipe: product-showcase
Token-driven presentational container — the single source for card chrome (background, border, radius, shadow, padding). Three sanctioned recipes: card (bordered, raised), inset (sunken base-200, flat), and glass (the one sanctioned translucent recipe). Compose any card-like surface on top of it instead of hand-rolling borders and shadows.
Token-driven inline label primitive — the single source for pill/chip/badge chrome. Resolves background, foreground, and border via resolveTone(tone, variant). Supports six semantic tones (primary, neutral, success, error, warning, info), four variants (fill, soft, outline, ghost), two sizes (sm, md), optional leading icon, and status dot. Always pill-shaped (radius full). Collapses ad-hoc rounded-label spans and named pill presets (Badge, BrandPill, RewardPill) onto one primitive.
Token-driven progress indicator primitive — three variants: ring (SVG arc), bar (linear fill), dots (stepped). Collapses divergent progress implementations onto one component keyed by variant × tone × size. All fill colors resolve through resolveTone; geometry is pure and unit-tested. Replaces ProgressRing (experiences/gamification) and ProgressIndicator bar/dots variants (experiences/survey).
Used in 1 recipe: mission-series
Token-driven speech/comment bubble primitive. Collapses the library's divergent bubble chrome implementations onto one rounded container with an optional triangular tail pointer (left, right, or none). All geometry resolves from tokens; background, radius, and padding are overridable. Replaces hand-rolled bubble chrome in CommentBubble (survey). OnboardingBubble (showcase FREEZE) deferred.
Used in 7 recipes: product-showcase, skincare-quiz, product-browse, mission-series, product-quiz, swipe-to-choose, poll-engage
navigation (1)
Discrete segmented progress bar where segments fill left-to-right as steps advance; the active segment is wider via spring-animated flex. Ideal for multi-step forms and surveys.
theming (1)
React context provider that injects design tokens as CSS variables on the document. Supports built-in and custom themes, localStorage persistence, and runtime token updates via the useTheme hook.
Components
Recipe-consumable UI — the self-contained, brand-themeable pieces (cards, reveals, counters, feeds, engines) that recipes pull in directly. Each composes primitives, owns a focused interaction, and exposes brand hooks. This is the largest tier and the everyday surface for building flows.
content (2)
Themed toast notification for point rewards, coupons, or badges. Displays a prominent animated reward value with variant-specific icon, message line, and optional close button.
Vertical and horizontal product card with image, title, subtitle, pricing (original/current), discount badge, reward label, and optional CTA button. Distinct from the experiences/rewards ProductRevealCard composition.
discovery (3)
A 3D card flip interaction for discovery and reveal moments. Supports both controlled and uncontrolled flip state with a perspective-based rotation animation.
Interactive scratch-off surface revealing hidden content. Uses HTML5 Canvas for real-time scratch drawing with touch/mouse support and auto-reveals at a configurable threshold percentage.
Used in 2 recipes: scratch-discover, coupon-reveal
Tinder-style draggable card deck where cards are swiped left or right via drag gesture or action buttons. Drag position drives button scale and glow feedback; a confirmation pill replaces buttons on commit.
gamification (3)
Interactive 3x3 bingo board with full interaction lifecycle: press feedback, loading spinner, completion stamp with spring animation, particle burst per tile, and SVG line-draw with glow when a row/col/diagonal completes.
Used in 1 recipe: bingo-challenge
Prize wheel with configurable segments and spin physics. SVG-based circular wheel that rotates to land on a random segment with deceleration easing.
Used in 1 recipe: spin-to-win
Animated list of earned rewards. Items spring-animate in as they are added. Emphasis items receive highlighted styling with a primary border and scale-pop on the value — ideal for bingo line completions, milestone bonuses, or any progressive reward accumulation.
Used in 1 recipe: bingo-challenge
loading (1)
Async-event-driven, product-anchored loading state. Renders product thumbnail + name + brand from the ad payload at t=0 (Composer-independent), an optional reward chip slot, a single quiet hint line that swaps to a longWaitHeadline at threshold, and a thin oscillating progress sliver. Sibling of MediatedLoadingScreen — that one runs on preset durationMs with rotating checklist; this one waits for a `ready` signal and is designed for Composer-served recipes where serving latency varies (preset path ~130ms vs real-time LLM ~5s avg / ~9s p95).
Used in 1 recipe: product-showcase
micro (2)
Real-time countdown timer with animated digit transitions. Supports filled/outlined/ghost variants, three sizes, optional days/seconds segments, i18n labels, and an onComplete callback.
Used in 1 recipe: countdown-deal
Animated reward chip with five states (`pending` · `full` · `halved` · `floored` · `paid`) driving a warm → terracotta → green color path. On state transition the chip jolts horizontally and the value swaps via a popLayout AnimatePresence; the pulse halo is active only on `full`. The chip is intended as the hero feedback element for tension-as-mechanic recipes — sets reward expectation at frame zero and signals decay continuously.
Used in 1 recipe: product-showcase
missions (2)
Duolingo-style progress header for multi-question challenge flows. Renders a bar, dots, or counter variant with an inline animated reward pill. Brand name can appear below the bar in small uppercase.
Used in 6 recipes: skincare-quiz, product-browse, mission-series, product-quiz, swipe-to-choose, poll-engage
Toast-style animated feedback notification shown during challenge flows. Supports five types: correct (checkmark), wrong (cross + shake), score (star), milestone (fire), and completion (celebration). Auto-dismisses with personality-driven timing.
Used in 6 recipes: skincare-quiz, product-browse, mission-series, product-quiz, swipe-to-choose, poll-engage
motion (1)
Unified particle engine. One `kind` prop selects the preset: radial (outward reward pop), confetti (full-screen falling celebration), or sparkle (small twinkle ring). Consolidates ParticleBurst, Confetti, RewardBurst, and the AIAvatar pulse sparkle onto a single trig core.
rewards (1)
Animated coupon display with ticket-style layout, prominent discount value, copyable code, and "Use Now" CTA. Designed for conversion-stage reward delivery.
Used in 1 recipe: countdown-deal
showcase (1)
Hyper-personalized 5-step interaction (3 slides → multi-choice quiz → tiered reward → product landing) driven by the Buzzvil Composer. Renders an 8-state machine (S0 entry, S1 mid-slide, S2 last-slide w/ CTA, S3 quiz entry, S4-1/2/3 correct/wrong-first/wrong-final, S5 complete, S6 loading, S7 error). Reward decay (100% → 50% → 25%) is framed as the core UX mechanic — the chip is anchored at frame zero and persists across every state. Loading state is product-anchored and latency-masked, designed for Composer serving latency variance (preset ~130ms vs real-time LLM ~5s avg / ~9s p95). The `layout` field is a content-cluster tag (price-first / design-first / safety-first / performance-first); structural shell is identical across clusters.
Used in 1 recipe: product-showcase
survey (3)
Multi-question survey orchestrator with conditional branching (showIf), correctAnswer evaluation, and optional AI narration path via AIAvatar and CommentBubble. Supports eight input types: single-select, multi-select, image-select, scale, binary, swipe, open-text, and ranking.
Used in 6 recipes: skincare-quiz, product-browse, mission-series, product-quiz, swipe-to-choose, poll-engage
Brand-adaptive animated blob with waveform bars for AI-style narration. State drives animation: idle (slow calm pulse), active (taller faster bars), correct (scale-up + green waveform), incorrect (shake + red waveform). Color adapts to brand primary token.
Used in 8 recipes: product-showcase, review-pick, skincare-quiz, product-browse, mission-series, product-quiz, swipe-to-choose, poll-engage
Explanation speech bubble paired with AIAvatar. Slides up from below with personality-driven timing. Renders an AIAvatar above the bubble, a correct/incorrect badge, and multi-line explanation text in a rounded surface with a triangle pointer.
Used in 6 recipes: skincare-quiz, product-browse, mission-series, product-quiz, swipe-to-choose, poll-engage
Modules
Stateful phase-contract units. A module wires one or more engines and components into a single self-driving interaction with a defined lifecycle — idle, active, resolved — so a recipe can drop it in and let it run. Modules are where composition becomes visible: each one below lists the components and engines it composes.
discovery (3)
Scratch Module — a tactile scratch-off reveal as a self-contained, agent-composable interaction unit (phase contract: config → onComplete). Owns the personality-scaled completion delay and the reveal lifecycle; renders the presentational ScratchReveal engine (canvas touch + threshold) beneath it.
Used in 2 recipes: scratch-discover, coupon-reveal
Product Explore Module — a tap-to-explore product grid as a self-contained, agent-composable interaction unit (phase contract: config → onComplete). Owns the explorable grid, the visited-Set state, the per-item check animation, the progress dots, and the completion lifecycle. Net-new: there is no underlying engine — the Module contains all of the JSX and state itself.
Link List Module — a check-off list of links/content as a self-contained, agent-composable interaction unit (phase contract: config → onComplete). Owns the link rows, the visited/visiting state, the per-row loading spinner and check transition, and the completion lifecycle. Net-new: there is no underlying engine — the Module contains all of the JSX and state itself.
gamification (4)
Memory-pair card matching Module. A self-contained, agent-composable interaction unit (phase contract: config → onComplete). Supports identical-pair mode (config.items) and association mode (config.pairs with cardA/cardB). Cards use FlipCard internally; mismatches flip back after a personality-driven delay. Optional countdown timer reveals all cards on expiry via Scrim. Also serves the deprecated `flip-reveal` recipe type.
Bingo Module — a 3×3 engagement grid as a self-contained, agent-composable interaction unit (phase contract: config → onComplete). Owns tile-completion state, earned-line tracking, the live RewardFeed, and the completion lifecycle; renders the presentational BingoGrid engine and RewardFeed beneath it.
Used in 1 recipe: bingo-challenge
Reaction-timing challenge Module. A self-contained, agent-composable interaction unit (phase contract: config → onComplete) where items cycle on screen and the user taps when the target item appears. Four display variants: hand-flip (emoji circle), emoji-roulette (square grid), product-spotlight (product image), color-pulse (color circle). Owns round/score/phase state and per-round cycling; fires onComplete({ completed: true, payload: { correct, total, perfect } }) when all rounds finish. The target indicator composes Pill.
Spin Wheel Module — a prize-wheel gamification as a self-contained, agent-composable interaction unit (phase contract: config → onComplete). Owns the spinning/result state, the Burst celebration layer, the brand-palette derivation (generateWheelPalette from brand.primary), and the auto-advance lifecycle; renders the presentational SpinWheel engine and Burst beneath it.
Used in 1 recipe: spin-to-win
rewards (2)
Time-limited offer Module. A self-contained, agent-composable interaction unit (phase contract: config → onComplete) for ultra-fast conversion. Renders a prompt header above a Surface card with an integrated countdown timer, urgency escalation (error palette + pulse when time is low), and a single prominent CTA. Fires onComplete({ completed: true, payload.claimed }) on tap, or onComplete({ completed: false, payload.expired }) when the countdown reaches zero.
Used in 1 recipe: flash-offer
Countdown Deal Module — a time-pressure countdown that unlocks a coupon, as a self-contained, agent-composable interaction unit (phase contract: config → onComplete). Owns the two-stage layout, the reveal state flip on countdown completion, the personality-scaled reveal delay, and the completion lifecycle; composes the Countdown primitive and the CouponCard component directly beneath it.
Used in 1 recipe: countdown-deal
shared (1)
Review Pick Module — a two-phase "narrow then reveal" flow as a self-contained, agent-composable interaction unit (phase contract: config → onComplete). Owns the multi-step question sequence (renders its own QuestionStep), the back navigation, and the transition into the mediated loading bridge; renders the MediatedLoadingScreen engine beneath the loading sub-phase, then fires onComplete with the picked option ids.
Used in 1 recipe: review-pick
survey (1)
Survey Module — the keystone Module that subsumes the five quiz/survey challenge families (ox-quiz, multi-quiz, survey, preference-pick, swipe-deck) into one agent-composable interaction unit (phase contract: config → onComplete). Takes a recipe-level SurveyConfig (the five recipe shapes plus a survey-engine passthrough), converts it to the engine SEConfig via in-library adapters, injects the personality, and renders the SurveyEngine beneath it; on completion it maps the SEResult back to each family's legacy payload shape and hands it out on ModuleResult.payload. The optional rewardLabel/brandName/rewardGauge serving-layer extras pass through to the SurveyEngine header.
Views
Full-screen scaffolds — the hook, loading, and offer screens (WelcomeScreen, MediatedLoadingScreen, BrandTransition, ProductRevealCard) that frame a flow end to end. A view owns the whole viewport and the moment around it: first impression, the wait between steps, or the reveal that lands the payoff.
loading (2)
Full-screen brand loading overlay with falling reward icons and centralised brand identity. Designed for context-switch moments (app-to-browser, deep-link landings).
Full-screen narrative loading overlay with rotating progress messages and brand-color spinner. Used for "AI is thinking" beats between user input and a personalized result reveal.
Used in 1 recipe: review-pick
rewards (1)
Offer-phase product display composing a branded header, inline reward context, and a personality-driven staggered two-column product grid. Represents the "Offer" step in a Hook → Challenge → Reward → Offer funnel. Renamed from ProductShowcase in 0.6.0; ProductShowcase now refers to the hyper-personalized recipe experience (PersonalizedProductShowcase).
welcome (1)
Funnel-opening loading screen with brand intro, reward pill, and CTA. Three variants: neutral (brand name + DecorativeRing on themed surface), full-bleed (background photo with GradientOverlay and BrandPill), glass-panel (photo with frosted GlassCard content block). Auto-advances via optional countdown.