Scaffold Complex Interactions with AI — and Own the Last 30%

Tier: Core · Workflow area: Component development · Tools: Cursor, dnd-kit / TanStack Virtual, Framer Motion

Interaction code has a unique property: it can look perfect in a demo and be unshippable in production. The scroll jumps on data refresh, drag fights text selection on touch, the exit animation leaks a subscription. Models reliably produce the 70% scaffold; the remaining 30% is judgment about how interactions feel and fail — and it stays yours.

When to use

• Library-backed interaction workdnd-kit sortable lists, TanStack Virtual tables, Framer Motion sequences — where boilerplate dominates.
• You know the target feelyou can name the acceptance criteria ("drop preview snaps, list stays put on refresh, 60fps on mid-tier Android").
• Porting a known patternkanban board, reorderable settings list, infinite feed — into your codebase and design system.

When NOT to use

• You can't yet describe the desired physicsprototype by hand first; you cannot review timing you haven't felt.
• A design-system primitive already existsif @acme/ui ships SortableList, use it (pb-03); don't scaffold a rival.
• Novel gesture systemsmulti-touch canvas editors and custom physics are research, not scaffolding; AI assists per-function, not per-feature.

The recipe

1. 1.

   Write the interaction contract before prompting. Ten minutes that anchor everything — behavior, constraints, and failure modes in plain language:

   Copy

   INTERACTION CONTRACT — Kanban card drag
   - Pointer + keyboard reorder (space to lift, arrows to move, esc cancels)
   - Drop preview shows insertion gap; source card at 40% opacity
   - Auto-scroll when dragging within 48px of a column edge
   - Live data: if a card moves server-side mid-drag, my drag wins; refetch
     reconciles after drop
   - Mobile: drag starts after 150ms long-press; scroll wins otherwise
   - Failure: failed persist reverts with a toast, no silent reorder
   Perf gate: no dropped frames with 200 cards on a 4x CPU throttle.
   

2. 2.

   Scaffold against the contract with the library named explicitly. In Cursor (or Claude Code), pin the library and version so the model doesn't free-associate APIs across major versions:

   Copy

   Using dnd-kit (@dnd-kit/core@6, @dnd-kit/sortable@8) implement the
   attached interaction contract for our KanbanBoard in
   src/features/board/. Use PointerSensor + KeyboardSensor with our
   sortableKeyboardCoordinates. Columns and cards come from
   useBoardQuery(); persist via reorderCard mutation with optimistic
   update and rollback. Use @acme/ui Card. Ask before adding deps.
   

   Copy

   npm i @dnd-kit/core@6 @dnd-kit/sortable@8 @dnd-kit/modifiers
   

   Good scaffold output: DndContext with both sensors configured, SortableContext per column, an onDragEnd that calls the mutation with optimistic update and rollback, and a DragOverlay for the preview — not a hand-rolled mousemove listener.

3. 3.

   Take manual ownership of the last-30% checklist. Walk each item personally; these are precisely the things scaffolds get subtly wrong:

   • •
     Timing and easing — tune durations/curves by feel in the browser, not by accepting duration: 0.3 defaults.
   • •
     Gesture conflicts — drag vs. scroll vs. text-selection vs. click; test on a real touch device, set touch-action deliberately.
   • •
     Interruption — what happens on esc mid-drag, refetch mid-drag, unmount mid-animation, rapid re-triggers.
   • •
     Cleanup — every listener, observer, timeout, and animation subscription removed on unmount; check with React StrictMode double-invoke.
   • •
     Reduced motion — prefers-reduced-motion collapses animations to opacity/instant.
4. 4.

   Profile before declaring done. Feel is measurable:

   Copy

   npx playwright test board.perf.spec.ts --project=chromium
   

   Or manually: DevTools Performance panel, 4x CPU throttle, record a full drag across columns with 200 cards. A good trace shows no long tasks over 50ms during drag and no layout thrash (purple spikes) on dragover. For virtualized lists, scroll a 10k-row list and confirm stable frame times and correct scroll restoration after data refresh.

5. 5.

   Ask the model to critique its own scaffold against the contract. Cheap and surprisingly effective at surfacing what it skipped:

   Copy

   Re-read the interaction contract. List every requirement my current
   implementation does NOT fully satisfy, with file:line evidence. Pay
   special attention to keyboard reorder, mid-drag refetch, and cleanup.
   

   Treat the answer as a lead list, not a verdict — verify each claim yourself.

Make it yours

• React (as written)dnd-kit for drag, TanStack Virtual for lists, Framer Motion for orchestration; for tables, TanStack Virtual + your Table primitives beats a virtualized-table library the model invents.
• Vue / Angularswap libraries, keep the contract: Vue uses vuedraggable/@formkit/drag-and-drop + @tanstack/vue-virtual + Motion for Vue; Angular uses CDK DragDrop + CDK Virtual Scroll + Angular animations. The last-30% checklist is framework-agnostic.
• React Nativereact-native-gesture-handler + Reanimated 3 + FlashList; the last 30% grows: worklet thread correctness (no JS-thread reads in gesture callbacks), Android back-gesture conflicts, and 60fps verified on a low-end physical device, not the simulator.
• FlutterReorderableListView/custom Draggable + ListView.builder; profile with DevTools' frame chart in profile mode on real hardware.

Quality check

• Every contract line demonstrably holdswalk the contract top to bottom in the running app, including keyboard-only reorder.
• Perf gate met on throttled hardwaretrace recorded at 4x CPU (or low-end device for mobile) with no >50ms tasks during interaction.
• Interruption matrix testedesc, unmount, refetch, and rapid re-trigger during drag/animation, no console errors or stuck state.
• Cleanup verifiedStrictMode dev pass plus a heap/listener check after mounting and unmounting the surface five times.
• Reduced-motion path exists and was viewed with the OS setting enabled.