🎨 DESIGNER — Starting UI/UX design for "{feature}"
🔍 Phase 1: Researching references...
   🌐 Searching web for inspiration...
   📸 Screenshotting reference sites...
   🎯 Analyzing project's existing UI...
🧠 Phase 2: Making design decisions...
🛠️ Phase 3: Writing production components...
   ⚡ Adding motion & interactions...
✔️ Phase 4: Self-review checklist...
📄 Writing → 02-references.md, 02-design.md
✅ DESIGNER — Complete ({N} components created)

Search queries (adapt to the feature):
- "[feature type] UI design 2025 2026"
- "[feature type] best UX patterns"
- "best [industry] dashboard design"
- "[competitor] UI screenshot"
- "dribbble [feature type]"
- "awwwards [feature category]"

## Design Decisions
 
### Layout
- Pattern: [e.g., "Bento grid like Linear's dashboard" or "Single column like Stripe's checkout"]
- Why: [reasoning from research]
- Reference: [URL or screenshot]
 
### Visual Hierarchy
- Primary action: [what draws the eye first]
- Secondary: [supporting information]
- Tertiary: [metadata, less important]
 
### Color Strategy
- Primary: [from project tokens or new proposal]
- Accent: [for CTAs, highlights]
- Semantic: [success, error, warning, info]
- Approach: [e.g., "dark mode with gold accents" or "clean white with blue CTAs"]
 
### Typography
- Headings: [size, weight]
- Body: [size, weight]
- Captions: [size, weight]
- Hierarchy levels: [how many, what size jumps]
 
### Spacing System
- Base unit: [4px, 8px grid?]
- Component padding: [internal spacing]
- Section gaps: [between major sections]
 
### Motion & Interaction Strategy
- Animation library: [Framer Motion / GSAP / CSS / Lottie — match project]
- Entrance animations: [fade, slide, scale, blur — with stagger timing]
- Scroll animations: [parallax, reveal, pin, progress-driven]
- Hover/press interactions: [scale, glow, tilt, magnetic cursor]
- Drag & gesture: [draggable cards, swipe, pinch-zoom]
- Loading states: [skeleton shimmer, spinner, progress bar, content placeholder]
- Page transitions: [shared layout, crossfade, slide, morph]
- Micro-interactions: [button feedback, toggle spring, counter tick, tooltip float]
- Performance budget: [GPU-only props (transform/opacity), will-change, reduced-motion fallback]
 
### Mobile Strategy
- Approach: [stack, collapse, hide, tab-switch]
- Touch targets: [minimum 44px]
- Navigation: [bottom nav, hamburger, tab bar]

# UI/UX References: {Feature Name}
 
## Reference 1: [Site Name]
- **URL**: [url]
- **What's good**: [specific observations]
- **Pattern to adopt**: [what we're taking]
- **Screenshot**: [description of what was captured]
 
## Reference 2: ...
 
## Design Trends Applied
- [Trend 1]: [how we're using it]
- [Trend 2]: [how we're using it]
 
## Anti-Patterns Avoided
- [Pattern]: [why we're not doing this]

# Design: {Feature Name}
 
## References
[Links to 02-references.md]
 
## Design Decisions
[From Phase 2 above]
 
## Component Structure
[Component tree]
 
## States & Interactions
| State | Visual | Trigger |
 
## Responsive Behavior
- Mobile / Tablet / Desktop
 
## Accessibility
## Handoff Notes for Developer
[What needs API wiring, state management, business logic]

src/components/
├── {FeatureName}/
│   ├── {FeatureName}.tsx      ← Main component
│   ├── {SubComponent}.tsx     ← Sub-components
│   └── index.ts               ← Barrel export (if project uses them)

// Designer produces this:
export function PaymentCard({ status, amount, onPay }: PaymentCardProps) {
  if (status === "loading") return <PaymentCardSkeleton />;
  if (status === "error") return <PaymentCardError />;
  // ... full visual implementation with all states
}
 
// Developer wires up:
// - actual payment API call
// - error retry logic
// - status state management
// - onPay handler implementation

// Staggered entrance — children animate in sequence
const container = {
  hidden: {},
  show: { transition: { staggerChildren: 0.06 } }
};
 
const item = {
  hidden: { opacity: 0, y: 20, filter: "blur(4px)" },
  show: { opacity: 1, y: 0, filter: "blur(0px)", transition: { duration: 0.4, ease: [0.25, 0.46, 0.45, 0.94] } }
};

// Framer Motion scroll-linked
const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] });
const y = useTransform(scrollYProgress, [0, 1], [100, -100]);
const opacity = useTransform(scrollYProgress, [0, 0.3, 0.7, 1], [0, 1, 1, 0]);

// Spring-based hover
<motion.button
  whileHover={{ scale: 1.02, boxShadow: "0 8px 30px rgba(0,0,0,0.12)" }}
  whileTap={{ scale: 0.98 }}
  transition={{ type: "spring", stiffness: 400, damping: 17 }}
/>

// Draggable with constraints and snap
<motion.div
  drag="x"
  dragConstraints={{ left: -200, right: 200 }}
  dragElastic={0.1}
  onDragEnd={(_, info) => {
    if (Math.abs(info.offset.x) > 100) handleSwipe(info.offset.x > 0 ? "right" : "left");
  }}
/>

// Shared layout animation between states
<AnimatePresence mode="popLayout">
  {items.map(item => (
    <motion.div key={item.id} layout layoutId={item.id}
      initial={{ opacity: 0, scale: 0.8 }}
      animate={{ opacity: 1, scale: 1 }}
      exit={{ opacity: 0, scale: 0.8 }}
    />
  ))}
</AnimatePresence>

// Split text and stagger characters/words
const words = text.split(" ");
{words.map((word, i) => (
  <motion.span key={i}
    initial={{ opacity: 0, y: 20 }}
    animate={{ opacity: 1, y: 0 }}
    transition={{ delay: i * 0.05, duration: 0.3 }}
  />
))}

// Element that follows or reacts to cursor position
const x = useMotionValue(0);
const y = useMotionValue(0);
 
function handleMouse(e: React.MouseEvent) {
  const rect = e.currentTarget.getBoundingClientRect();
  x.set((e.clientX - rect.left - rect.width / 2) * 0.1);
  y.set((e.clientY - rect.top - rect.height / 2) * 0.1);
}

// Required: reduced motion fallback
const prefersReducedMotion = useReducedMotion();
const animation = prefersReducedMotion
  ? { opacity: 1 }
  : { opacity: 1, y: 0, filter: "blur(0px)" };

## Motion Design
 
### Animation Library
- [Library]: [version, why chosen]
 
### Motion Tokens
- Duration fast: 150ms (hover, toggle)
- Duration normal: 300ms (enter/exit)
- Duration slow: 500ms (page transitions, hero)
- Easing default: cubic-bezier(0.25, 0.46, 0.45, 0.94)
- Easing bounce: spring(stiffness: 400, damping: 17)
- Easing smooth: cubic-bezier(0.22, 1, 0.36, 1)
- Stagger interval: 50-80ms
 
### Scroll Animations
- [Section]: [animation type, trigger point]
 
### Interactive Elements
- [Element]: [hover, press, drag behavior]
 
### Reduced Motion
- All animations collapse to instant opacity transitions