@auto-engineer/react-gen 1.134.0

package/skills/design-system/templates/design-tokens-starter.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://design-tokens.org/schema.json",
+  "primitive": {
+    "color": {
+      "gray": {
+        "50": { "$value": "#F9FAFB", "$type": "color" },
+        "100": { "$value": "#F3F4F6", "$type": "color" },
+        "200": { "$value": "#E5E7EB", "$type": "color" },
+        "300": { "$value": "#D1D5DB", "$type": "color" },
+        "400": { "$value": "#9CA3AF", "$type": "color" },
+        "500": { "$value": "#6B7280", "$type": "color" },
+        "600": { "$value": "#4B5563", "$type": "color" },
+        "700": { "$value": "#374151", "$type": "color" },
+        "800": { "$value": "#1F2937", "$type": "color" },
+        "900": { "$value": "#111827", "$type": "color" },
+        "950": { "$value": "#030712", "$type": "color" }
+      },
+      "blue": {
+        "50": { "$value": "#EFF6FF", "$type": "color" },
+        "500": { "$value": "#3B82F6", "$type": "color" },
+        "600": { "$value": "#2563EB", "$type": "color" },
+        "700": { "$value": "#1D4ED8", "$type": "color" },
+        "800": { "$value": "#1E40AF", "$type": "color" }
+      },
+      "red": {
+        "500": { "$value": "#EF4444", "$type": "color" },
+        "600": { "$value": "#DC2626", "$type": "color" },
+        "700": { "$value": "#B91C1C", "$type": "color" }
+      },
+      "green": {
+        "500": { "$value": "#22C55E", "$type": "color" },
+        "600": { "$value": "#16A34A", "$type": "color" }
+      },
+      "yellow": {
+        "500": { "$value": "#EAB308", "$type": "color" }
+      },
+      "white": { "$value": "#FFFFFF", "$type": "color" }
+    },
+    "spacing": {
+      "0": { "$value": "0", "$type": "dimension" },
+      "1": { "$value": "0.25rem", "$type": "dimension" },
+      "2": { "$value": "0.5rem", "$type": "dimension" },
+      "3": { "$value": "0.75rem", "$type": "dimension" },
+      "4": { "$value": "1rem", "$type": "dimension" },
+      "5": { "$value": "1.25rem", "$type": "dimension" },
+      "6": { "$value": "1.5rem", "$type": "dimension" },
+      "8": { "$value": "2rem", "$type": "dimension" },
+      "10": { "$value": "2.5rem", "$type": "dimension" },
+      "12": { "$value": "3rem", "$type": "dimension" },
+      "16": { "$value": "4rem", "$type": "dimension" }
+    },
+    "fontSize": {
+      "xs": { "$value": "0.75rem", "$type": "dimension" },
+      "sm": { "$value": "0.875rem", "$type": "dimension" },
+      "base": { "$value": "1rem", "$type": "dimension" },
+      "lg": { "$value": "1.125rem", "$type": "dimension" },
+      "xl": { "$value": "1.25rem", "$type": "dimension" },
+      "2xl": { "$value": "1.5rem", "$type": "dimension" },
+      "3xl": { "$value": "1.875rem", "$type": "dimension" },
+      "4xl": { "$value": "2.25rem", "$type": "dimension" }
+    },
+    "radius": {
+      "none": { "$value": "0", "$type": "dimension" },
+      "sm": { "$value": "0.125rem", "$type": "dimension" },
+      "default": { "$value": "0.25rem", "$type": "dimension" },
+      "md": { "$value": "0.375rem", "$type": "dimension" },
+      "lg": { "$value": "0.5rem", "$type": "dimension" },
+      "xl": { "$value": "0.75rem", "$type": "dimension" },
+      "full": { "$value": "9999px", "$type": "dimension" }
+    },
+    "shadow": {
+      "none": { "$value": "none", "$type": "shadow" },
+      "sm": { "$value": "0 1px 2px 0 rgb(0 0 0 / 0.05)", "$type": "shadow" },
+      "default": { "$value": "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)", "$type": "shadow" },
+      "md": { "$value": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)", "$type": "shadow" },
+      "lg": { "$value": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)", "$type": "shadow" }
+    },
+    "duration": {
+      "fast": { "$value": "150ms", "$type": "duration" },
+      "normal": { "$value": "200ms", "$type": "duration" },
+      "slow": { "$value": "300ms", "$type": "duration" }
+    }
+  },
+  "semantic": {
+    "color": {
+      "background": { "$value": "{primitive.color.gray.50}", "$type": "color" },
+      "foreground": { "$value": "{primitive.color.gray.900}", "$type": "color" },
+      "primary": { "$value": "{primitive.color.blue.600}", "$type": "color" },
+      "primary-hover": { "$value": "{primitive.color.blue.700}", "$type": "color" },
+      "primary-foreground": { "$value": "{primitive.color.white}", "$type": "color" },
+      "secondary": { "$value": "{primitive.color.gray.100}", "$type": "color" },
+      "secondary-foreground": { "$value": "{primitive.color.gray.900}", "$type": "color" },
+      "muted": { "$value": "{primitive.color.gray.100}", "$type": "color" },
+      "muted-foreground": { "$value": "{primitive.color.gray.500}", "$type": "color" },
+      "destructive": { "$value": "{primitive.color.red.600}", "$type": "color" },
+      "destructive-foreground": { "$value": "{primitive.color.white}", "$type": "color" },
+      "border": { "$value": "{primitive.color.gray.200}", "$type": "color" },
+      "ring": { "$value": "{primitive.color.blue.500}", "$type": "color" }
+    },
+    "spacing": {
+      "component": { "$value": "{primitive.spacing.4}", "$type": "dimension" },
+      "section": { "$value": "{primitive.spacing.12}", "$type": "dimension" }
+    }
+  },
+  "component": {
+    "button": {
+      "bg": { "$value": "{semantic.color.primary}", "$type": "color" },
+      "fg": { "$value": "{semantic.color.primary-foreground}", "$type": "color" },
+      "hover-bg": { "$value": "{semantic.color.primary-hover}", "$type": "color" },
+      "padding-x": { "$value": "{primitive.spacing.4}", "$type": "dimension" },
+      "padding-y": { "$value": "{primitive.spacing.2}", "$type": "dimension" },
+      "radius": { "$value": "{primitive.radius.md}", "$type": "dimension" },
+      "font-size": { "$value": "{primitive.fontSize.sm}", "$type": "dimension" }
+    },
+    "input": {
+      "bg": { "$value": "{semantic.color.background}", "$type": "color" },
+      "border": { "$value": "{semantic.color.border}", "$type": "color" },
+      "focus-ring": { "$value": "{semantic.color.ring}", "$type": "color" },
+      "padding-x": { "$value": "{primitive.spacing.3}", "$type": "dimension" },
+      "padding-y": { "$value": "{primitive.spacing.2}", "$type": "dimension" },
+      "radius": { "$value": "{primitive.radius.md}", "$type": "dimension" }
+    },
+    "card": {
+      "bg": { "$value": "{primitive.color.white}", "$type": "color" },
+      "border": { "$value": "{semantic.color.border}", "$type": "color" },
+      "shadow": { "$value": "{primitive.shadow.default}", "$type": "shadow" },
+      "padding": { "$value": "{primitive.spacing.6}", "$type": "dimension" },
+      "radius": { "$value": "{primitive.radius.lg}", "$type": "dimension" }
+    }
+  },
+  "dark": {
+    "semantic": {
+      "color": {
+        "background": { "$value": "{primitive.color.gray.950}", "$type": "color" },
+        "foreground": { "$value": "{primitive.color.gray.50}", "$type": "color" },
+        "secondary": { "$value": "{primitive.color.gray.800}", "$type": "color" },
+        "muted": { "$value": "{primitive.color.gray.800}", "$type": "color" },
+        "muted-foreground": { "$value": "{primitive.color.gray.400}", "$type": "color" },
+        "border": { "$value": "{primitive.color.gray.800}", "$type": "color" }
+      }
+    }
+  }
+}

package/skills/design-taste-frontend/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: design-taste-frontend
+description: Senior UI/UX Engineer. Architect digital interfaces overriding default LLM biases. Enforces metric-based rules, strict component architecture, CSS hardware acceleration, and balanced design engineering.
+---
+
+# High-Agency Frontend Skill
+
+## 1. ACTIVE BASELINE CONFIGURATION
+* DESIGN_VARIANCE: 8 (1=Perfect Symmetry, 10=Artsy Chaos)
+* VISUAL_DENSITY: 4 (1=Art Gallery/Airy, 10=Pilot Cockpit/Packed Data)
+
+**AI Instruction:** The standard baseline for all generations is strictly set to these values (8, 4). Do not ask the user to edit this file. Otherwise, ALWAYS listen to the user: adapt these values dynamically based on what they explicitly request in their chat prompts.
+
+## 2. DEFAULT ARCHITECTURE & CONVENTIONS
+* **Framework & Interactivity:** React or Next.js.
+* **Styling Policy:** Use Tailwind CSS (v3/v4) for 90% of styling.
+* **ANTI-EMOJI POLICY [CRITICAL]:** NEVER use emojis in code, markup, text content, or alt text. Replace symbols with high-quality icons (lucide-react) or clean SVG primitives. Emojis are BANNED.
+* **Responsiveness & Spacing:**
+  * Contain page layouts using `max-w-7xl mx-auto`.
+  * **Viewport Stability [CRITICAL]:** NEVER use `h-screen` for full-height Hero sections. ALWAYS use `min-h-[100dvh]`.
+  * **Grid over Flex-Math:** NEVER use complex flexbox percentage math. ALWAYS use CSS Grid.
+
+## 3. DESIGN ENGINEERING DIRECTIVES (Bias Correction)
+
+**Rule 1: Deterministic Typography**
+* **Display/Headlines:** Default to `text-4xl md:text-6xl tracking-tighter leading-none`.
+* **ANTI-SLOP:** Discourage `Inter` for "Premium" vibes. Use `Outfit`, `Geist`, or `Satoshi`.
+* **Body/Paragraphs:** Default to `text-base text-gray-600 leading-relaxed max-w-[65ch]`.
+
+**Rule 2: Color Calibration**
+* Max 1 Accent Color. Saturation < 80%.
+* **THE LILA BAN:** No purple button glows, no neon gradients. Use neutral bases (Zinc/Slate) with singular accents.
+
+**Rule 3: Layout Diversification**
+* **ANTI-CENTER BIAS:** Force "Split Screen" (50/50), "Left Aligned/Right Aligned", or "Asymmetric White-space" structures.
+
+**Rule 4: Materiality & Shadows**
+* Use cards ONLY when elevation communicates hierarchy. When a shadow is used, tint it to the background hue.
+
+**Rule 5: Interactive UI States**
+* **Loading:** Skeletal loaders matching layout sizes.
+* **Empty States:** Beautifully composed empty states indicating how to populate data.
+* **Error States:** Clear, inline error reporting.
+* **Tactile Feedback:** On `:active`, use `-translate-y-[1px]` or `scale-[0.98]`.
+
+**Rule 6: Data & Form Patterns**
+* Label MUST sit above input. Use a standard `gap-2` for input blocks.
+
+## 4. PERFORMANCE GUARDRAILS
+* **Z-Index Restraint:** Use z-indexes strictly for systemic layer contexts (Navbars, Modals, Overlays).
+
+## 6. AI TELLS (Forbidden Patterns)
+
+### Visual & CSS
+* **NO Neon/Outer Glows.** Use inner borders or subtle tinted shadows.
+* **NO Pure Black.** Use Off-Black, Zinc-950, or Charcoal.
+* **NO Oversaturated Accents.** Desaturate to blend with neutrals.
+
+### Typography
+* **NO Inter Font.** Use `Outfit`, `Geist`, or `Satoshi`.
+* **NO Oversized H1s.** Control hierarchy with weight and color, not massive scale.
+
+### Layout & Spacing
+* **NO 3-Column Card Layouts.** Use 2-column Zig-Zag, asymmetric grid, or horizontal scroll.
+
+### Content & Data
+* **NO Generic Names.** No "John Doe" or "Jane Smith". Use creative, realistic names.
+* **NO Fake Numbers.** Avoid `99.99%` or `50%`. Use organic data (`47.2%`, `+1 (312) 847-1928`).
+* **NO Filler Words.** No "Elevate", "Seamless", "Unleash", or "Next-Gen".
+
+### External Resources
+* **NO Broken Unsplash Links.** Use `https://picsum.photos/seed/RANDOM_STRING/800/600`.
+* **shadcn/ui Customization:** NEVER use shadcn/ui in its generic default state. Customize radii, colors, shadows.
+
+## 7. PRE-FLIGHT CHECK
+- [ ] Is mobile layout collapse (`w-full`, `px-4`, `max-w-7xl mx-auto`) guaranteed?
+- [ ] Do full-height sections use `min-h-[100dvh]` instead of `h-screen`?
+- [ ] Are empty, loading, and error states provided?
+- [ ] Are cards omitted in favor of spacing where possible?

package/skills/emil-design-engineering/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: emil-design-engineering
+description: "Design engineering principles and patterns for building polished, accessible web interfaces. Use this skill when building UI components, reviewing frontend code, implementing forms, handling touch interactions, optimizing performance, or creating marketing pages. Triggers on: design engineering, UI polish, input fields, form validation, button states, touch devices, mobile UX, accessibility, a11y, keyboard navigation, aria labels, font rendering, typography, layout shift, z-index, animations, transitions, easing, hover effects, tap targets, iOS Safari, prefers-reduced-motion, marketing pages, landing pages, dark mode, theme switching, scrollbars, gradients, shadows, virtualization, preloading."
+---
+
+# Emil's Design Engineering Principles
+
+A comprehensive guide for building polished, accessible web interfaces based on Emil Kowalski's design engineering practices.
+
+## Quick Reference
+
+| Category                                        | When to Use                                          |
+| ----------------------------------------------- | ---------------------------------------------------- |
+| [Animations](animations.md)                     | Enter/exit transitions, easing, springs, performance |
+| [UI Polish](ui-polish.md)                       | Typography, visual design, layout, colors            |
+| [Forms & Controls](forms-controls.md)           | Inputs, buttons, form submission                     |
+| [Touch & Accessibility](touch-accessibility.md) | Mobile, touch devices, keyboard nav, a11y            |
+| [Component Design](component-design.md)         | Compound components, composition, props API          |
+| [Marketing](marketing.md)                       | Landing pages, blogs, docs sites                     |
+| [Performance](performance.md)                   | Virtualization, preloading, optimization             |
+
+## Core Principles
+
+### 1. No Layout Shift
+
+Dynamic elements should cause no layout shift. Use hardcoded dimensions, `font-variant-numeric: tabular-nums` for changing numbers, and avoid font weight changes on hover/selected states.
+
+### 2. Touch-First, Hover-Enhanced
+
+Design for touch first, then add hover enhancements. Disable hover effects on touch devices. Ensure 44px minimum tap targets. Never rely on hover for core functionality.
+
+### 3. Keyboard Navigation
+
+Tabbing should work consistently. Only allow tabbing through visible elements. Ensure keyboard navigation scrolls elements into view with `scrollIntoView()`.
+
+### 4. Accessibility by Default
+
+Every animation needs `prefers-reduced-motion` support. Every icon button needs an aria label. Every interactive element needs proper focus states.
+
+### 5. Speed Over Delight
+
+Product UI should be fast and purposeful. Skip animations for frequently-used interactions. Marketing pages can be more elaborate.
+
+## Decision Flowcharts
+
+### Should I Animate This?
+
+```
+Will users see this 100+ times daily?
+├── Yes → Don't animate
+└── No
+    ├── Is this user-initiated?
+    │   └── Yes → Animate with ease-out (150-250ms)
+    └── Is this a page transition?
+        └── Yes → Animate (300-400ms max)
+```
+
+### What Easing Should I Use?
+
+```
+Is the element entering or exiting?
+├── Yes → ease-out
+└── No
+    ├── Is it moving on screen?
+    │   └── Yes → ease-in-out
+    └── Is it a hover/color change?
+        ├── Yes → ease
+        └── Default → ease-out
+```
+
+## Common Mistakes
+
+| Mistake                     | Fix                                         |
+| --------------------------- | ------------------------------------------- |
+| `transition: all`           | Specify exact properties                    |
+| Hover effects on touch      | Use `@media (hover: hover)`                 |
+| Font weight change on hover | Use consistent weights                      |
+| Animating `height`/`width`  | Use `transform` and `opacity` only          |
+| No reduced motion support   | Add `prefers-reduced-motion` query          |
+| z-index: 9999               | Use fixed scale or `isolation: isolate`     |
+| Custom page scrollbars      | Only customize scrollbars in small elements |
+
+## Review Checklist
+
+When reviewing UI code, check:
+
+- [ ] No layout shift on dynamic content
+- [ ] Animations have reduced motion support
+- [ ] Touch targets are 44px minimum
+- [ ] Hover effects disabled on touch devices
+- [ ] Keyboard navigation works properly
+- [ ] Icon buttons have aria labels
+- [ ] Forms submit with Enter/Cmd+Enter
+- [ ] Inputs are 16px+ to prevent iOS zoom
+- [ ] No `transition: all`
+- [ ] z-index uses fixed scale
+
+## Reference Files
+
+For detailed guidance on specific topics:
+
+- [animations.md](animations.md) - Easing, timing, springs, performance
+- [ui-polish.md](ui-polish.md) - Typography, shadows, gradients, scrollbars
+- [forms-controls.md](forms-controls.md) - Inputs, buttons, form patterns
+- [touch-accessibility.md](touch-accessibility.md) - Touch devices, keyboard nav, a11y
+- [component-design.md](component-design.md) - Compound components, composition, props API
+- [marketing.md](marketing.md) - Landing pages, blogs, docs
+- [performance.md](performance.md) - Virtualization, preloading, optimization

package/skills/emil-design-engineering/animations.md

@@ -0,0 +1,266 @@
+# Animations
+
+Based on Emil Kowalski's "Animations on the Web" course.
+
+## Quick Decision
+
+1. **Is this element entering or exiting?** → Use `ease-out`
+2. **Is an on-screen element moving?** → Use `ease-in-out`
+3. **Is this a hover/color transition?** → Use `ease`
+4. **Will users see this 100+ times daily?** → Don't animate it
+
+## The Easing Blueprint
+
+### ease-out (Most Common)
+
+Use for **user-initiated interactions**: dropdowns, modals, tooltips, any element entering or exiting the screen.
+
+```css
+/* Sorted weak to strong */
+--ease-out-quad: cubic-bezier(0.25, 0.46, 0.45, 0.94);
+--ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
+--ease-out-quart: cubic-bezier(0.165, 0.84, 0.44, 1);
+--ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);
+--ease-out-expo: cubic-bezier(0.19, 1, 0.22, 1);
+--ease-out-circ: cubic-bezier(0.075, 0.82, 0.165, 1);
+```
+
+Why it works: Acceleration at the start creates an instant, responsive feeling. The element "jumps" toward its destination then settles in.
+
+### ease-in-out (For Movement)
+
+Use when **elements already on screen need to move or morph**. Mimics natural motion like a car accelerating then braking.
+
+```css
+/* Sorted weak to strong */
+--ease-in-out-quad: cubic-bezier(0.455, 0.03, 0.515, 0.955);
+--ease-in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1);
+--ease-in-out-quart: cubic-bezier(0.77, 0, 0.175, 1);
+--ease-in-out-quint: cubic-bezier(0.86, 0, 0.07, 1);
+--ease-in-out-expo: cubic-bezier(1, 0, 0, 1);
+--ease-in-out-circ: cubic-bezier(0.785, 0.135, 0.15, 0.86);
+```
+
+### ease (For Hover Effects)
+
+Use for **hover states and color transitions**. The asymmetrical curve (faster start, slower end) feels elegant for gentle animations.
+
+```css
+transition: background-color 150ms ease;
+```
+
+### linear (Avoid in UI)
+
+Only use for:
+- Constant-speed animations (marquees, tickers)
+- Time visualization (hold-to-delete progress indicators)
+
+Linear feels robotic and unnatural for interactive elements.
+
+### ease-in (Almost Never)
+
+**Avoid for UI animations.** Makes interfaces feel sluggish because the slow start delays visual feedback.
+
+## Paired Elements Rule
+
+Elements that animate together must use the same easing and duration. Modal + overlay, tooltip + arrow, drawer + backdrop—if they move as a unit, they should feel like a unit.
+
+```css
+/* Both use the same timing */
+.modal { transition: transform 200ms ease-out; }
+.overlay { transition: opacity 200ms ease-out; }
+```
+
+## Duration Guidelines
+
+| Element Type | Duration |
+| --- | --- |
+| Micro-interactions | 100-150ms |
+| Standard UI (tooltips, dropdowns) | 150-250ms |
+| Modals, drawers | 200-300ms |
+| Page transitions | 300-400ms |
+
+**Rules:**
+- UI animations should stay under 300ms
+- Larger elements animate slower than smaller ones
+- Exit animations can be faster than entrances
+- Longer travel distance = longer duration
+
+## The Frequency Principle
+
+Determine how often users will see the animation:
+
+- **100+ times/day** → No animation (or drastically reduced)
+- **Occasional use** → Standard animation
+- **Rare/first-time** → Can be special
+
+**Example:** Raycast never animates its menu toggle because users open it hundreds of times daily.
+
+## When to Animate
+
+**Do animate:**
+- Enter/exit transitions for spatial consistency
+- State changes that benefit from visual continuity
+- Responses to user actions (feedback)
+- Rarely-used interactions where delight adds value
+
+**Don't animate:**
+- Keyboard-initiated actions
+- Hover effects on frequently-used elements
+- Anything users interact with 100+ times daily
+- When speed matters more than smoothness
+
+**Marketing vs. Product:**
+- Marketing: More elaborate, longer durations allowed
+- Product: Fast, purposeful, never frivolous
+
+## Spring Animations
+
+Springs feel more natural because they don't have fixed durations—they simulate real physics.
+
+### When to Use Springs
+
+- Drag interactions with momentum
+- Elements that should feel "alive" (Dynamic Island)
+- Gestures that can be interrupted mid-animation
+- Organic, playful interfaces
+
+### Configuration
+
+**Apple's approach (recommended):**
+
+```js
+// Duration + bounce (easier to understand)
+{ type: "spring", duration: 0.5, bounce: 0.2 }
+```
+
+**Traditional physics:**
+
+```js
+// Mass, stiffness, damping (more complex)
+{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
+```
+
+### Bounce Guidelines
+
+- **Avoid bounce** in most UI contexts
+- **Use bounce** for drag-to-dismiss, playful interactions
+- Keep bounce subtle (0.1-0.3) when used
+
+### Interruptibility
+
+Springs maintain velocity when interrupted—CSS animations restart from zero. This makes springs ideal for gestures users might change mid-motion.
+
+## Performance
+
+### The Golden Rule
+
+Only animate `transform` and `opacity`. These skip layout and paint stages, running entirely on the GPU.
+
+**Avoid animating:**
+- `padding`, `margin`, `height`, `width` (trigger layout)
+- `blur` filters above 20px (expensive, especially Safari)
+- CSS variables in deep component trees
+
+### Optimization Techniques
+
+```css
+/* Force GPU acceleration */
+.animated-element {
+  will-change: transform;
+}
+```
+
+**React-specific:**
+- Animate outside React's render cycle when possible
+- Use refs to update styles directly instead of state
+- Re-renders on every frame = dropped frames
+
+**Framer Motion:**
+
+```jsx
+// Hardware accelerated (transform as string)
+<motion.div animate={{ transform: "translateX(100px)" }} />
+
+// NOT hardware accelerated (more readable)
+<motion.div animate={{ x: 100 }} />
+```
+
+### CSS vs. JavaScript
+
+- CSS animations run off main thread (smoother under load)
+- JS animations (Framer Motion, React Spring) use `requestAnimationFrame`
+- CSS better for simple, predetermined animations
+- JS better for dynamic, interruptible animations
+
+## Accessibility
+
+### prefers-reduced-motion
+
+Whenever you add an animation, also add a media query to disable it:
+
+```css
+.modal {
+  animation: fadeIn 200ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .modal {
+    animation: none;
+  }
+}
+```
+
+### Reduced Motion Guidelines
+
+- Every animated element needs its own `prefers-reduced-motion` media query
+- Set `animation: none` or `transition: none` (no `!important`)
+- No exceptions for opacity or color—disable all animations
+- Show play buttons instead of autoplay videos
+
+### Framer Motion Implementation
+
+```jsx
+import { useReducedMotion } from "framer-motion";
+
+function Component() {
+  const shouldReduceMotion = useReducedMotion();
+
+  return (
+    <motion.div
+      initial={shouldReduceMotion ? false : { opacity: 0, y: 20 }}
+      animate={{ opacity: 1, y: 0 }}
+    />
+  );
+}
+```
+
+## Practical Tips
+
+| Scenario | Solution |
+| --- | --- |
+| Make buttons feel responsive | Add `transform: scale(0.97)` on `:active` |
+| Element appears from nowhere | Start from `scale(0.95)`, not `scale(0)` |
+| Shaky/jittery animations | Add `will-change: transform` |
+| Hover causes flicker | Animate child element, not parent |
+| Popover scales from wrong point | Set `transform-origin` to trigger location |
+| Sequential tooltips feel slow | Skip delay/animation after first tooltip |
+| Small buttons hard to tap | Use 44px minimum hit area (pseudo-element) |
+| Something still feels off | Add subtle blur (under 20px) to mask it |
+| Hover triggers on mobile | Use `@media (hover: hover) and (pointer: fine)` |
+
+## Theme Transitions
+
+**Important:** Switching themes should not trigger transitions and animations on elements. Disable transitions during theme changes to prevent flash of animated content.
+
+## AnimatePresence
+
+Use `popLayout` mode on AnimatePresence when an element has an exit animation and is in a group of elements.
+
+## Drag Gestures
+
+When implementing drag-to-dismiss or similar gestures, ensure velocity-based swiping works. Usually velocity (`swipeAmount / timeTaken`) higher than `0.10` should be sufficient to trigger the action.
+
+## Looping Animations
+
+Pause looping animations when off-screen to save resources.