@minhduydev/mdpi 0.4.1 → 0.6.0

package/dist/template/.pi/skills/frontend-design/references/animation/motion-core.md

@@ -1,6 +1,9 @@
 # Motion Core (motion/react)
 
-**Import**: `import { motion, AnimatePresence } from 'motion/react'`
+**Package**: `motion` (v12.40.0). Formerly "framer-motion".
+**Import**: `import { motion, AnimatePresence, useScroll, useTransform } from 'motion/react'`
+
+Framer Motion rebranded to **Motion** in November 2024. Both `motion` and `framer-motion` packages published in lockstep. New projects use `motion`. No breaking changes in v12 for React.
 
 ## Motion Principles
 
@@ -8,6 +11,8 @@
 - Use motion to explain state change and hierarchy
 - Prefer subtle distance (`8-16px`) and opacity shifts
 - Use consistent timing/easing system across the app
+- Let Tailwind handle static styles; Motion handles behavior
+- **Remove `transition-*` Tailwind classes from motion elements** — they conflict
 
 ## Timing System
 
@@ -19,6 +24,7 @@
 | Large entrances               | 500-800ms  |
 
 **Rule**: exit duration = ~75% of enter duration.
+**Never exceed 600ms for UI responsiveness.**
 
 ## Easing System
 
@@ -29,20 +35,20 @@ const EASING_ENTER = [0.16, 1, 0.3, 1];
 const EASING_EXIT = [0.4, 0, 1, 1];
 ```
 
-Avoid bounce/elastic easings for product UI.
+Avoid bounce/elastic easings for product UI. Motion's hybrid engine runs animations natively via Web Animations API (WAAPI) and ScrollTimeline for 120fps GPU performance, falling back to JS only for spring physics and gestures.
 
 ## Performance Rules
 
 Animate only compositor-friendly properties:
 
-- `transform`
+- `transform` (x, y, scale, rotate, skew)
 - `opacity`
 
 Avoid animating:
 
-- `width`, `height`
-- `top`, `left`
-- `margin`, `padding`
+- `width`, `height` — triggers layout recalculation
+- `top`, `left` — use `x`/`y` instead
+- `margin`, `padding`, `border`
 
 ## Basic Pattern
 
@@ -54,6 +60,101 @@ Avoid animating:
 />
 ```
 
+## React 19 + Next.js 15/16
+
+### Page Transitions (App Router)
+
+**Critical**: Use `template.tsx`, NOT `layout.tsx`. Layout persists across routes and never remounts.
+
+```tsx
+// app/template.tsx
+'use client'
+
+import { AnimatePresence, motion } from 'motion/react'
+import { usePathname } from 'next/navigation'
+
+export default function Template({ children }: { children: React.ReactNode }) {
+  const pathname = usePathname()
+  return (
+    <AnimatePresence mode="wait" initial={false}>
+      <motion.div
+        key={pathname}
+        initial={{ opacity: 0, y: 8 }}
+        animate={{ opacity: 1, y: 0 }}
+        exit={{ opacity: 0, y: -8 }}
+        transition={{ duration: 0.18, ease: 'easeInOut' }}
+        style={{ minHeight: 'var(--page-min-height, 100dvh)' }}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  )
+}
+```
+
+### Dynamic Import (Performance)
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const AnimatedWrapper = dynamic(() => import('@/components/animated-wrapper'), {
+  ssr: false,
+  loading: ({ children }) => <>{children}</>,
+})
+```
+
+### React 19.2 View Transitions
+
+Next.js 16 + React 19.2 support native View Transitions via `experimental.viewTransition: true`. Motion's `AnimateView` (premium) builds on this.
+
+## Integration with shadcn/ui
+
+**Architecture**: shadcn/ui = structure + accessibility. Motion = behavior + animation. Wrap/extend shadcn components — don't replace.
+
+```
+src/
+├── components/
+│   ├── ui/              # shadcn generated (untouched)
+│   └── animated/        # Motion-wrapped shadcn components
+│       ├── AnimatedButton.tsx
+│       ├── AnimatedDialog.tsx
+│       └── ...
+└── lib/
+    └── animations.ts    # Shared variants & transition configs
+```
+
+### Shared Variants Pattern
+
+```ts
+// lib/animations.ts
+import type { Variants, Transition } from 'motion/react'
+
+export const fadeIn: Variants = {
+  initial: { opacity: 0 },
+  animate: { opacity: 1 },
+  exit: { opacity: 0 },
+}
+
+export const slideUp: Variants = {
+  initial: { opacity: 0, y: 20 },
+  animate: { opacity: 1, y: 0 },
+  exit: { opacity: 0, y: 20 },
+}
+
+export const spring: Transition = {
+  type: 'spring',
+  stiffness: 300,
+  damping: 25,
+}
+```
+
+### Installation Order
+
+1. `npx shadcn init` + add components
+2. `npm install motion`
+3. Create `lib/animations.ts` for shared variants
+4. Create `components/animated/` directory for wrapped components
+
 ## Variants Pattern (Recommended)
 
 ```tsx
@@ -69,8 +170,6 @@ const card = {
 <motion.div variants={card} initial="hidden" animate="visible" />
 ```
 
-Use variants for shared timing and maintainability.
-
 ## Exit Animations (AnimatePresence)
 
 ```tsx
@@ -87,7 +186,7 @@ Use variants for shared timing and maintainability.
 </AnimatePresence>
 ```
 
-Always provide stable `key` values for exiting elements.
+Always provide stable `key` values. Use `mode="wait"` to prevent overlapping DOM elements.
 
 ## Stagger Patterns
 
@@ -123,6 +222,9 @@ Use `layout` for reordering and size changes. Add spring only when needed:
 <motion.div layout transition={{ type: 'spring', stiffness: 320, damping: 28 }} />
 ```
 
+**New (v12.35+)**: Axis-locked layout: `layout="x"` or `layout="y"`.
+**New (v12.38+)**: Custom anchor: `layoutAnchor={{ x: 0.5, y: 0.5 }}`.
+
 ## Gestures
 
 ```tsx
@@ -133,7 +235,7 @@ Use `layout` for reordering and size changes. Add spring only when needed:
 />
 ```
 
-Keep gesture amplitudes subtle (`0.98-1.03`).
+Keep gesture amplitudes subtle (`0.98-1.03`). Available: `whileHover`, `whileTap`, `whileFocus`, `whileDrag`, `whileInView`.
 
 ## Height Expand/Collapse (No height animation)
 
@@ -168,14 +270,47 @@ Use CSS grid technique:
 }
 ```
 
-For motion/react, switch spatial movement to opacity-only when reduced motion is enabled.
+For motion/react, use `useReducedMotion()`:
+
+```tsx
+import { useReducedMotion } from 'motion/react'
+
+const prefersReduced = useReducedMotion()
+
+<motion.div
+  animate={prefersReduced ? {} : { scale: 1.1 }}
+/>
+```
+
+## Motion AI Kit
+
+Official Motion AI tools (premium, Motion+ required):
+```bash
+npx motion-ai     # Install MCP server + skills for Claude Code, Cursor, Windsurf, etc.
+```
+
+Provides: 400+ premium examples, MotionScore runtime profiling, CSS spring generation, transition editing.
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| `layout.tsx` for AnimatePresence (CLS) | Use `template.tsx` with `mode="wait"` |
+| `transition-*` classes on motion elements | Remove Tailwind transition classes |
+| Animating `width`/`height` | Use `scaleX`/`scaleY` or grid technique |
+| Missing `use client` in Next.js | Extract animation to client component |
+| `mode="sync"` with page transitions | Use `mode="wait"` to prevent overlap |
+| Duration > 600ms for UI | Cap at 600ms; reserve long durations for storytelling |
 
 ## Quick Checklist
 
-- [ ] Uses `motion/react` import
+- [ ] Uses `motion/react` import (not `framer-motion`)
 - [ ] Timing follows 100/300/500ms system
 - [ ] Exponential easing, no bounce/elastic
 - [ ] Animates only `transform` and `opacity`
 - [ ] Uses `AnimatePresence` for exit states
-- [ ] Includes reduced motion support
+- [ ] Includes reduced motion support (CSS + `useReducedMotion()`)
 - [ ] Stagger windows stay under 500ms
+- [ ] Next.js: uses `template.tsx` not `layout.tsx`
+- [ ] No `transition-*` classes on motion elements
+- [ ] shadcn/ui: animated components in `components/animated/`

package/dist/template/.pi/skills/frontend-design/references/shadcn/setup.md

@@ -1,56 +1,161 @@
 # shadcn/ui Setup
 
-CLI v3.6.x (current: v3.6.3) - Copy-paste components, Radix UI + Tailwind v4.
+CLI v4.x (current: shadcn@4.11.0) — Copy-paste components, Radix UI / Base UI + Tailwind v4.
 
-## New Project
+## Create a New Project
 
 ```bash
 npx shadcn create
 ```
 
 Interactive setup:
-- Visual style: Vega, Nova, Maia, Lyra, Mira
-- Component library: Radix UI or Base UI
-- Icon library (including Phosphor)
-- Next.js 16 support
+- **Visual style**: Vega, Nova, Maia, Lyra, Mira
+- **Component library**: Radix UI or Base UI
+- **Icon library** (Lucide, Phosphor, etc.)
+- **Next.js 16**, Vite, Laravel, React Router, Astro, TanStack Start support
+- **Template scaffolding** via `npx shadcn init --template`
 
 ## Existing Project
 
 ```bash
-npx shadcn@latest init
+npx shadcn@latest init --preset <code>
 npx shadcn@latest add button card dialog
 npx shadcn@latest add --all
+npx shadcn@latest add <username>/<repo>/<item>  # GitHub Registry
 ```
 
 Components install to `components/ui/`.
 
+## Key CLI v4 Commands
+
+```bash
+# Inspection
+npx shadcn info                     # Full project config (for agent context)
+npx shadcn info --json              # JSON output for programmatic use
+npx shadcn docs <component>         # Docs, code, examples from CLI
+
+# Preview changes before writing
+npx shadcn add button --dry-run     # Show what will be installed
+npx shadcn add button --diff        # Show diff against current
+npx shadcn add button --view        # Open component in browser
+
+# Project setup flags
+npx shadcn init --preset a1Dg5eFl    # Pack entire design system into short code
+npx shadcn init --template           # Scaffold project templates
+npx shadcn init --monorepo           # Monorepo setup
+npx shadcn init --base radix         # Choose primitives (radix | base)
+
+# Skills (AI Agent)
+npx skills add shadcn/ui             # Install agent prompt file
+npx shadcn skills generate           # Regenerate after adding components
+npx shadcn skills update             # Update monthly
+```
+
 ## Visual Styles
 
-| Style | Description |
-|-------|-------------|
-| **Vega** | Classic shadcn look |
-| **Nova** | Reduced padding, compact |
-| **Maia** | Soft, rounded, generous |
-| **Lyra** | Boxy, sharp, mono fonts |
-| **Mira** | Compact, dense interfaces |
+| Style | Characteristics |
+|-------|----------------|
+| **Vega** | Classic shadcn look — balanced, versatile |
+| **Nova** | Reduced padding, compact, space-efficient |
+| **Maia** | Soft, rounded corners, generous spacing |
+| **Lyra** | Boxy, sharp corners, monospace fonts |
+| **Mira** | Compact, dense, data-heavy interfaces |
+
+Styles rewrite component code, not just CSS — fonts, spacing, structure, primitives all adapt.
+
+## Presets
+
+Presets pack the entire design system into a reproducible short code:
+
+```bash
+# Export your preset
+npx shadcn preset export
+
+# Init a project with a preset
+npx shadcn init --preset a1Dg5eFl
+```
+
+A preset includes: colors, theme, icons, fonts, radius, spacing — everything in one code.
 
 ## Component Libraries
 
-- **Radix UI** (default): Full accessibility, React-only
-- **Base UI**: MUI unstyled components
+- **Radix UI** (default): Full accessibility, React-only, battle-tested
+- **Base UI**: MUI unstyled components, headless
+
+Select during `npx shadcn create` or with `--base` flag. CLI auto-detects your library when pulling components.
+
+## GitHub Registries (June 2026)
+
+Any public GitHub repo with a `registry.json` can be a component registry:
 
-Select during `npx shadcn create` or in `components.json`.
+```bash
+npx shadcn@latest add <username>/<repo>/<item>
+```
+
+Distribute: components, hooks, utilities, design tokens, feature kits, project conventions, CI workflows, templates. No build step — CLI reads `registry.json` directly.
+
+```json
+// registry.json (in any GitHub repo)
+{
+  "name": "my-components",
+  "items": [
+    {
+      "name": "data-table",
+      "type": "registry:component",
+      "files": [{ "path": "components/data-table.tsx" }]
+    }
+  ]
+}
+```
+
+## shadcn/skills — AI Agent Bridge
+
+```bash
+npx skills add shadcn/ui
+```
+
+Creates `.shadcn/skills.md` — a machine-readable file that gives AI coding agents project-aware context:
+
+- **Project context** — framework, aliases, installed components, icon library, base library (via `shadcn info --json`)
+- **CLI command reference** — all flags, smart merge, presets, templates
+- **Theming guidance** — CSS vars, OKLCH, dark mode, Tailwind v3/v4
+- **Registry authoring** — `registry.json` format
+- **Pattern enforcement** — FieldGroup for forms, ToggleGroup for options, semantic colors
+
+**Measured impact**: API errors 34% → 3%, correct variants 61% → 98%, first-try success 45% → 89%.
+
+**Critical workflows**:
+- Re-generate after adding components: `npx shadcn skills generate`
+- Update monthly: `npx shadcn skills update`
+- Reference file path (don't paste into context — 4K cutoff)
 
 ## MCP Server Support
 
-- OpenCode MCP (v3.6.3)
-- Codex MCP (v3.4.0)
+Connect AI editors to your registry:
+
+```json
+{
+  "mcpServers": {
+    "shadcn": {
+      "command": "npx",
+      "args": ["-y", "shadcn@canary", "registry:mcp"],
+      "env": {
+        "REGISTRY_URL": "https://your-registry.vercel.app/r/registry.json"
+      }
+    }
+  }
+}
+```
+
+Also: OpenCode MCP (v3.6.3), Codex MCP (v3.4.0).
 
 ## Registry System
 
 - Registry Directory: https://ui.shadcn.com/docs/directory
 - Custom registries via `components.json`
 - Namespaced components
+- `registry:base` — distribute entire design systems
+- `registry:font` — distribute font packages
 
 ## Component List
 
@@ -66,4 +171,6 @@ Select during `npx shadcn create` or in `components.json`.
 
 **Overlay**: Dropdown Menu, Context Menu, Popover, Collapsible
 
-**Other**: Toggle, Toggle Group, Kbd, Button Group, Item, Empty, Input OTP
+**2026 New**: Spinner, Kbd, KbdGroup, Button Group, Input Group, Field, Item, Empty, Input OTP
+
+**Other**: Toggle, Toggle Group