/interaction-patterns

name: interaction-patterns
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "UI interaction patterns: skeleton loading, infinite scroll, progressive disclosure, modal/drawer/inline selection, drag-and-drop, tab overflow, toasts. Use when implementing loading states, pagination, overlays, reorderable lists, or notifications."
user-invocable: false
metadata:
  owner-agent: "frontend-ui-developer"
  category: document-asset-creation
  version: "1.0.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "interaction-design, skeleton-loading, infinite-scroll, progressive-disclosure, modal, drawer, drag-drop, tabs, toast, ux-patterns"
allowed-tools: "Read Glob Grep WebFetch WebSearch"

Interaction Patterns

Codifiable UI interaction patterns that prevent common UX failures. Covers loading states, content pagination, disclosure patterns, overlays, drag-and-drop, tab overflow, and notification systems — all with accessibility baked in.

Quick Reference

| Rule | File | Impact | When to Use | |------|------|--------|-------------| | Skeleton Loading | `rules/interaction-skeleton-loading.md` | HIGH | Content-shaped placeholders for async data | | Infinite Scroll | `rules/interaction-infinite-scroll.md` | CRITICAL | Paginated content with a11y and keyboard support | | Progressive Disclosure | `rules/interaction-progressive-disclosure.md` | HIGH | Revealing complexity based on user need | | Modal / Drawer / Inline | `rules/interaction-modal-drawer-inline.md` | HIGH | Choosing overlay vs inline display patterns | | Drag & Drop | `rules/interaction-drag-drop.md` | CRITICAL | Reorderable lists with keyboard alternatives | | Tabs Overflow | `rules/interaction-tabs-overflow.md` | MEDIUM | Tab bars with 7+ items or dynamic tabs | | Toast Notifications | `rules/interaction-toast-notifications.md` | HIGH | Success/error feedback and notification stacking | | Cognitive Load Thresholds | `rules/interaction-cognitive-load-thresholds.md` | HIGH | Enforcing Miller's Law, Hick's Law, and Doherty Threshold with numeric limits | | Form UX | `rules/interaction-form-ux.md` | HIGH | Target sizing, label placement, error prevention, and smart defaults | | Persuasion Ethics | `rules/interaction-persuasion-ethics.md` | HIGH | Detecting dark patterns and applying ethical engagement principles |

**Total: 10 rules across 6 categories**

Decision Table — Loading States

| Scenario | Pattern | Why | |----------|---------|-----| | List/card content loading | Skeleton | Matches content shape, reduces perceived latency | | Form submission | Spinner | Indeterminate, short-lived action | | File upload | Progress bar | Measurable operation with known total | | Image loading | Blur placeholder | Prevents layout shift, progressive reveal | | Route transition | Skeleton | Preserves layout while data loads | | Background sync | None / subtle indicator | Non-blocking, low priority |

Quick Start

Skeleton Loading

function CardSkeleton() {
  return (
    <div className="animate-pulse space-y-3">
      <div className="h-48 w-full rounded-lg bg-muted" />
      <div className="h-4 w-3/4 rounded bg-muted" />
      <div className="h-4 w-1/2 rounded bg-muted" />
    </div>
  )
}

function CardList({ items, isLoading }: { items: Item[]; isLoading: boolean }) {
  if (isLoading) {
    return (
      <div className="grid grid-cols-3 gap-4">
        {Array.from({ length: 6 }).map((_, i) => (
          <CardSkeleton key={i} />
        ))}
      </div>
    )
  }
  return (
    <div className="grid grid-cols-3 gap-4">
      {items.map((item) => <Card key={item.id} item={item} />)}
    </div>
  )
}

Infinite Scroll with Accessibility

function InfiniteList({ fetchNextPage, hasNextPage, items }: Props) {
  const sentinelRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => { if (entry.isIntersecting && hasNextPage) fetchNextPage() },
      { rootMargin: "200px" }
    )
    if (sentinelRef.current) observer.observe(sentinelRef.current)
    return () => observer.disconnect()
  }, [fetchNextPage, hasNextPage])

  return (
    <div role="feed" aria-busy={isFetching}>
      {items.map((item) => (
        <article key={item.id} aria-posinset={item.index} aria-setsize={-1}>
          <ItemCard item={item} />
        </article>
      ))}
      <div ref={sentinelRef} />
      {hasNextPage && (
        <button onClick={() => fetchNextPage()}>Load more items</button>
      )}
      <div aria-live="polite" className="sr-only">
        {`Showing ${items.length} items`}
      </div>
    </div>
  )
}

Rule Details

Skeleton Loading

Content-shaped placeholders that match the final layout. Use skeleton for lists, cards, and text blocks.

> **Load**: `rules/interaction-skeleton-loading.md`

Infinite Scroll

Accessible infinite scroll with IntersectionObserver, screen reader announcements, and "Load more" fallback.

> **Load**: `rules/interaction-infinite-scroll.md`

Progressive Disclosure

Reveal complexity progressively: tooltip, accordion, wizard, contextual panel.

> **Load**: `rules/interaction-progressive-disclosure.md`

Modal / Drawer / Inline

Choose the right overlay pattern: modal for confirmations, drawer for detail views, inline for simple toggles.

> **Load**: `rules/interaction-modal-drawer-inline.md`

Drag & Drop

Drag-and-drop with mandatory keyboard alternatives using `@dnd-kit/core`.

> **Load**: `rules/interaction-drag-drop.md`

Tabs Overflow

Scrollable tab bars with overflow menus for dynamic or numerous tabs.

> **Load**: `rules/interaction-tabs-overflow.md`

Toast Notifications

Positioned, auto-dismissing notifications with ARIA roles and stacking.

> **Load**: `rules/interaction-toast-notifications.md`

Cognitive Load Thresholds

Miller's Law (max 7 items per group), Hick's Law (max 1 primary CTA), and Doherty Threshold (400ms feedback) with specific, countable limits.

> **Loa