english/.opencode/skills/frontend-design/references/bento-motion-engine.md

Bento 2.0 Motion Engine

Architecture for modern SaaS dashboards and feature sections. Goes beyond static cards — enforces a "Vercel-core meets Dribbble-clean" aesthetic with perpetual physics.

Use when generating: SaaS dashboards, feature showcase grids, marketing bento sections, product landing pages with interactive demos.

---

Core Design Philosophy

Aesthetic: High-end, minimal, functional. Every card feels alive.

Palette:

• Background: #f9fafb (light) or #050505 (dark)
• Cards: pure white #ffffff (light) / vantablack with bg-white/5 (dark)
• Card borders: border border-slate-200/50 (light) / border border-white/10 (dark)

Surfaces:

• All major containers use rounded-[2.5rem]
• Diffusion shadow: shadow-[0_20px_40px_-15px_rgba(0,0,0,0.05)] — depth without clutter
• Card titles and descriptions sit outside and below the card (gallery-style presentation)
• Card interior: generous p-8 or p-10 padding

Typography:

• Font stack: Geist, Satoshi, or Cabinet Grotesk only
• Header tracking: tracking-tight
• Never Inter in a Bento context

Double-Bezel structure for premium cards:

• Outer shell: bg-black/5 ring-1 ring-black/5 p-1.5 rounded-[2rem]
• Inner core: own background + shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)] + rounded-[calc(2rem-0.375rem)]

---

Animation Engine Specs

All cards MUST contain Perpetual Micro-Interactions. The dashboard must always feel alive.

Spring Physics (no linear easing):

// Use for all interactive elements
{ type: "spring", stiffness: 100, damping: 20 }

Layout Transitions:

• Use Framer Motion layout and layoutId props for smooth reordering, resizing, and shared element transitions

Infinite Loops:

• Every card has an active state that loops infinitely: Pulse, Typewriter, Float, or Carousel

Performance isolation (critical):

• Every perpetual animation MUST be wrapped in React.memo
• Extract each animated card as its own isolated leaf 'use client' component
• Never trigger re-renders in the parent layout

AnimatePresence:

• Wrap all dynamic lists — enables proper enter/exit animations

---

Grid Structure

Typical layout: Row 1 = 3 columns | Row 2 = 2 columns (70/30 split)

<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
  {/* Row 1: 3 equal cards */}
  <IntelligentListCard />
  <CommandInputCard />
  <LiveStatusCard />
</div>
<div className="grid grid-cols-1 md:grid-cols-[70%_30%] gap-6 mt-6">
  {/* Row 2: wide data stream + contextual UI */}
  <WideDataStreamCard />
  <ContextualUICard />
</div>

Mobile: all cards collapse to grid-cols-1 with gap-6. No horizontal overflow.

---

The 5 Card Archetypes

1. Intelligent List

A vertical stack of items with an infinite auto-sorting loop.

• Items swap positions using layoutId — simulates AI prioritizing tasks in real-time
• Smooth position swaps on a ~3s interval
• Spring-based position transitions for a weighted, physical feel
• Use case: task lists, priority queues, leaderboards

2. Command Input

A search/AI bar with a multi-step Typewriter Effect.

• Cycles through 3-5 complex prompts
• Blinking cursor between prompts
• "Processing" state: shimmering loading gradient on the input
• On "completion": brief checkmark animation before next cycle
• Use case: AI search demos, command palette teasers

3. Live Status

A scheduling or status interface with breathing indicators.

• Status dots with infinite scale pulse animation (1.0 → 1.2 → 1.0, 2s loop)
• Pop-up notification badge with overshoot spring: appears, stays 3s, vanishes
• Badge entrance: scale: [0, 1.2, 1] with overshoot spring physics
• Use case: scheduling UIs, monitoring dashboards, live feed indicators

4. Wide Data Stream

A horizontal infinite carousel of data cards or metrics.

• Seamless loop using x: ["0%", "-50%"] with duplicate items for continuity
• Speed feels effortless — not urgent, not slow (~20-30s per full cycle)
• Cards show metrics, user avatars, status chips, mini sparklines
• Use case: social proof logos, metric streams, activity feeds

5. Contextual UI (Focus Mode)

A document or content view that highlights and reveals tools.

• Staggered text block highlight animation (sequential word/line highlights, 300ms stagger)
• After highlight completes: float-in of a floating action toolbar
• Toolbar entrance: y: [20, 0] + opacity: [0, 1] with spring, staggered micro-icons
• Toolbar holds 3-5 action icons with individual hover states
• Use case: editor demos, AI annotation tools, document review flows

---

Pre-Flight Checklist

Before shipping a Bento section:

• Global state used only to avoid deep prop-drilling, not arbitrarily
• Mobile layout collapses to single column with w-full px-4
• Full-height sections use min-h-[100dvh] not h-screen
• All useEffect animations have cleanup functions
• Empty, loading, and error states provided for each card
• Generic card borders replaced with spacing/dividers where appropriate
• Every perpetual animation isolated in its own memoized Client Component
• No window.addEventListener('scroll') — use whileInView or IntersectionObserver
• No arbitrary z-index values
• backdrop-blur only on fixed/sticky elements, never scrolling cards