@minhduydev/mdpi 0.4.0 → 0.5.0

package/dist/template/.pi/skills/frontend-design/SKILL.md

@@ -3,6 +3,8 @@ name: frontend-design
 description: MUST load when building any web UI with React-based frameworks — components, pages, or full applications. Covers Tailwind CSS v4, shadcn/ui, Motion animations. Base UI implementation skill; combine with aesthetic overlays (minimalist-ui, high-end-visual-design) for specific styles.
 ---
 
+**Aesthetic Context:** Your implementation must reflect the project `.pi/DESIGN.md` identity. Before writing any component, internalize the Overview & Mood, Colors, and Typography sections. All code output should feel like it belongs to the same intentional design system.
+
 # Frontend Design
 
 ## When to Use
@@ -18,6 +20,17 @@ description: MUST load when building any web UI with React-based frameworks —
 
 - Backend-only tasks or minimal UI with no visual design requirements.
 
+## Relationship to Other Skills
+
+| Skill | Role |
+|-------|------|
+| `design-taste-frontend` | Upstream — sets aesthetic baseline and anti-AI-slops. Load BEFORE this skill. |
+| `frontend-ui-engineering` | Sibling — handles component implementation, accessibility, and state patterns. |
+| `react-best-practices` | Complement — React/Next.js performance patterns. |
+| `baseline-ui` | Quick deslop pass for automatic fixes (spacing, typography). |
+
+**Pipeline:** `design-taste-frontend` → `frontend-design` → `frontend-ui-engineering`
+
 ## Reference Documentation
 
 ### Tailwind CSS v4.1
@@ -30,7 +43,7 @@ description: MUST load when building any web UI with React-based frameworks —
 
 Search: `@theme`, `@container`, `OKLCH`, `mask-`, `text-shadow`
 
-### shadcn/ui (CLI v3.6)
+### shadcn/ui (CLI v4.11)
 
 - `./references/shadcn/setup.md` - Installation, visual styles, component list
 - `./references/shadcn/core-components.md` - Button, Card, Dialog, Select, Tabs, Toast
@@ -67,7 +80,7 @@ For sophisticated compositions: posters, brand materials, design systems.
 - `./references/design/interaction.md` - State models, focus, dialogs/popovers, loading patterns
 - `./references/design/ux-writing.md` - Button copy, error structure, empty states, i18n
 
-Search: `AI Slop Test`, `tinted neutrals`, `focus-visible`, `verb + object`, `65ch`
+Search: `tinted neutrals`, `focus-visible`, `verb + object`, `65ch`
 
 ## Design Thinking
 
@@ -79,49 +92,56 @@ Before coding, commit to BOLD aesthetic direction:
 
 Bold maximalism and refined minimalism both work. Key is intentionality.
 
-## Anti-Patterns (AI Fingerprints — NEVER)
-
-These patterns immediately signal "AI made this." Avoid them all.
+## Don't
 
 ### Typography
 
-- **Banned fonts**: Inter, Roboto, Arial, Open Sans, Lato, Montserrat, Space Grotesk, system-ui as display font
-- Monospace used as "developer aesthetic" shorthand
-- Big icons centered above every heading
-- Using `px` for body text (use `rem`/`em` to respect user settings)
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Inter, Roboto, Arial as display fonts | Distinctive display fonts (Instrument Sans, Outfit, Fraunces) | Overused fonts signal generic design |
+| Monospace used as "developer aesthetic" shorthand | Purposeful type choice; mono only for code/data | Mono-as-aesthetic reads as placeholder design |
+| Big icons centered above every heading | Integrated icon + heading lockup, or icon inline | Giant centered icons feel template-generated |
+| Using `px` for body text | `rem`/`em` to respect user font-size preferences | `px` ignores accessibility and user settings |
 
 ### Color
 
-- **AI palette**: Cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds
-- Gray text on colored backgrounds (use darker shade of background color instead)
-- Pure `#000` or `#fff` (always tint — pure black/white don't exist in nature)
-- Gradient text on headings or metrics
-- `rgba()` / heavy alpha transparency as primary palette (design smell — define explicit colors)
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Gray text on colored backgrounds | Darker shade of the background color | Gray-on-color fails contrast and looks muddy |
+| Pure `#000` or `#fff` | Tinted near-black or near-white | Pure black/white don't exist in natural light |
+| Gradient text on headings or metrics | Solid, well-chosen heading color | Gradient text is a design crutch |
+| `rgba()` / heavy alpha transparency as primary palette | Explicit, named color values | Heavy alpha stacking creates unpredictable colors |
 
 ### Layout
 
-- Cards nested inside cards (use typography, spacing, dividers for hierarchy within a card)
-- Identical card grids (icon + heading + text repeated 3-6 times)
-- Hero metric template (big number + small label + gradient accent)
-- Center-aligning everything
-- Same spacing everywhere (no visual rhythm)
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Cards nested inside cards | Typography, spacing, dividers for hierarchy | Nested cards create visual noise without purpose |
+| Identical card grids (icon + heading + text ×3-6) | Varied layout with purposeful asymmetry | Repeated identical cards is the #1 AI tell |
+| Hero metric template (big number + small label + gradient accent) | Contextual data display — number embedded in prose or card | Generic hero metrics are the startup-template cliché |
+| Center-aligning everything | Left-align content blocks; reserve center for short hero headlines | Center-aligned body text is hard to scan |
+| Same spacing everywhere (no visual rhythm) | Use proximity to group related items; vary spacing to create sections | Uniform spacing flattens hierarchy |
 
 ### Visual
 
-- Glassmorphism used decoratively (blur cards, glow borders)
-- Thick colored border on one side of rounded rectangles
-- Sparklines as decoration (not connected to real data)
-- Generic drop shadows on everything
-- Rounded rectangles as the only shape language
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Glassmorphism used decoratively | Flat surfaces or layered shadows | Glassmorphism needs a functional reason for depth |
+| Thick colored border on one side of rounded rectangles | Subtle border or shadow on entire element | One-sided colored borders are a dated pattern |
+| Sparklines as decoration (not connected to real data) | Real sparklines from actual data, or omit entirely | Decorative sparklines are fake data theater |
+| Generic drop shadows on everything | Intentional shadow hierarchy — only where depth communicates meaning | Shadow-everywhere flattens the depth language |
+| Rounded rectangles as the only shape language | Mix shapes: sharp corners, soft corners, circles, organic shapes | Single-shape designs feel templated |
 
 ### Motion
 
-- Bounce or elastic easing (real objects decelerate smoothly)
-- Animating `height`, `width`, `padding`, `margin` (causes layout recalculation)
-- Default `ease` (compromise that's rarely optimal — use exponential easing)
-- Missing `prefers-reduced-motion` handling
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Bounce or elastic easing on UI | Exponential easing `cubic-bezier(0.16, 1, 0.3, 1)` | Real objects decelerate smoothly, not bounce |
+| Animating `height`, `width`, `padding`, `margin` | Animate only `transform` and `opacity` | Layout animations cause expensive repaints |
+| Default `ease` | Exponential easing curves tuned to animation purpose | Default `ease` is a compromise rarely optimal |
+| Missing `prefers-reduced-motion` handling | Always respect reduced motion preferences | ~35% of adults over 40 prefer reduced motion |
 
-> **The AI Slop Test**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
+> **The Slop Test:** If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
 
 ## Best Practices
 
@@ -235,28 +255,21 @@ Create atmosphere: gradient meshes, noise textures, geometric patterns, layered
 
 | Rationalization | Reality |
 |---|---|
-| "The AI aesthetic is fine for now" | AI default styles (purple gradients, oversized cards) signal low quality. Use the design system. |
+| "The default look is fine for now" | Default styles signal low quality. Use the design system from the start. |
 | "I'll make it responsive later" | Retrofitting responsive design is 3x harder than building it mobile-first. |
 | "Accessibility is a nice-to-have" | It's a legal requirement in many jurisdictions and an engineering quality standard. |
 | "This is just a prototype" | Prototypes become production code. Build the foundation right from the start. |
-
-## Red Flags
-
-- Components exceeding 200 lines (split them)
-- Inline styles or arbitrary pixel values
-- Missing error states, loading states, or empty states
-- No keyboard navigation testing
-- Color as the sole indicator of state (red/green without text or icons)
-- Generic "AI look" (purple gradients, oversized cards, stock layouts)
+| "Typography doesn't matter for functionality" | Typography is 95% of web design. Bad type ruins even good layouts. |
+| "Users won't notice the details" | Users may not articulate it, but they feel quality. Details accumulate into perception. |
 
 ## Verification
 
-After building UI:
-
-- [ ] Component renders without console errors
-- [ ] All interactive elements are keyboard accessible (Tab through the page)
-- [ ] Screen reader can convey the page's content and structure
+- [ ] Design tokens defined: primitives + semantic layer, with dark mode variants
+- [ ] Typography: distinctive font pairing, fluid sizing with `clamp()`, `max-width: 65ch` on body text
+- [ ] Color: OKLCH tokens, tinted neutrals (chroma 0.01-0.02), sufficient contrast (4.5:1 min)
+- [ ] Motion: exponential easing only, `prefers-reduced-motion` handled, only `transform` + `opacity` animated
+- [ ] Spacing: consistent 4pt scale, `gap` over margins, self-adjusting grids
 - [ ] Responsive: works at 320px, 768px, 1024px, 1440px
-- [ ] Loading, error, and empty states all handled
-- [ ] Follows the project's design system (spacing, colors, typography)
-- [ ] No accessibility warnings in dev tools or axe-core
+- [ ] Interaction: all 8 states designed, `:focus-visible` used, skeletons over spinners
+- [ ] UX Writing: verb + object buttons, error = what + why + fix, empty states are onboarding
+- [ ] No banned fonts, no gray-on-color text, no pure black/white

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

@@ -1,13 +1,13 @@
 # Motion Advanced
 
-Scroll, orchestration, TypeScript, performance.
+Scroll, orchestration, TypeScript, AnimateView, performance.
 
 ## Scroll Animations
 
 ```tsx
 import { motion, useScroll, useTransform } from 'motion/react';
 
-// Scroll progress
+// Scroll progress (GPU-accelerated via ScrollTimeline API since v12.32)
 const { scrollYProgress } = useScroll();
 const opacity = useTransform(scrollYProgress, [0, 1], [1, 0]);
 
@@ -36,7 +36,7 @@ const scale = useTransform(scrollYProgress, [0, 0.5, 1], [0.8, 1, 0.8]);
 ## AnimatePresence Modes
 
 ```tsx
-// Wait for exit before enter
+// Wait for exit before enter (recommended for page transitions)
 <AnimatePresence mode="wait">
   <motion.div key={currentPage} />
 </AnimatePresence>
@@ -50,6 +50,37 @@ const scale = useTransform(scrollYProgress, [0, 0.5, 1], [0.8, 1, 0.8]);
 <AnimatePresence mode="sync" />
 ```
 
+## AnimateView (New — Motion+ Early Access)
+
+View Transitions wrapper for React. Enter/exit/update/share animations for page transitions:
+
+```tsx
+import { AnimateView } from 'motion/react'
+
+<AnimateView>
+  <motion.div
+    animate={{ opacity: 1, scale: 1 }}
+    initial={{ opacity: 0, scale: 0.95 }}
+  />
+</AnimateView>
+```
+
+Built on React 19.2 `ViewTransition` component. Works alongside Next.js 16 `experimental.viewTransition`.
+
+## arc() — Curved Motion Paths (v12.40+)
+
+```tsx
+import { arc } from 'motion/react'
+
+<motion.div
+  animate={{
+    x: 200,
+    y: -120,
+    transition: { path: arc() }
+  }}
+/>
+```
+
 ## Orchestration
 
 ```tsx
@@ -157,6 +188,24 @@ const prefersReduced = useReducedMotion();
 
 // Use layoutRoot to isolate layout calculations
 <motion.div layoutRoot />
+
+// Axis-locked layout (v12.35+) — cheaper than full layout
+<motion.div layout="x" />
+
+// Custom anchor point (v12.38+)
+<motion.div layoutAnchor={{ x: 0.5, y: 0.5 }} />
+```
+
+## CSS Color Support (v12.35+)
+
+Motion now supports modern CSS color formats:
+- `oklch()`, `oklab()`, `lab()`, `lch()`
+- `color-mix()`, `light-dark()`
+
+```tsx
+<motion.div
+  animate={{ backgroundColor: 'oklch(0.65 0.22 250)' }}
+/>
 ```
 
 ## Common Patterns
@@ -171,18 +220,28 @@ const prefersReduced = useReducedMotion();
 />
 ```
 
-### Page transitions
+### Page transitions (Next.js App Router)
 ```tsx
-<AnimatePresence mode="wait">
-  <motion.main
-    key={pathname}
-    initial={{ opacity: 0, x: 20 }}
-    animate={{ opacity: 1, x: 0 }}
-    exit={{ opacity: 0, x: -20 }}
-  >
-    {children}
-  </motion.main>
-</AnimatePresence>
+// app/template.tsx
+'use client'
+import { AnimatePresence, motion } from 'motion/react'
+import { usePathname } from 'next/navigation'
+
+export default function Template({ children }) {
+  const pathname = usePathname()
+  return (
+    <AnimatePresence mode="wait" initial={false}>
+      <motion.main
+        key={pathname}
+        initial={{ opacity: 0, x: 20 }}
+        animate={{ opacity: 1, x: 0 }}
+        exit={{ opacity: 0, x: -20 }}
+      >
+        {children}
+      </motion.main>
+    </AnimatePresence>
+  )
+}
 ```
 
 ### Expandable card
@@ -212,13 +271,27 @@ anime.js v4 still appropriate for:
 - Non-React projects
 
 ```javascript
-// anime.js for SVG morphing
 import { animate, svg } from 'animejs';
 animate('#path1', { d: svg.morphTo('#path2'), duration: 1 });
 ```
 
+## Library Comparison (2026)
+
+| Library | Bundle | React DX | Scroll | Gestures | Layout Anim |
+|---------|--------|----------|--------|----------|-------------|
+| **Motion** | ~85KB | 🏆 Best | Built-in | Built-in | Built-in |
+| GSAP | ~78KB | Imperative | ScrollTrigger | Draggable | Flip plugin |
+| React Spring | ~45KB | Good | External | ❌ | ❌ |
+| Anime.js | ~52KB | Imperative | External | ❌ | ❌ |
+| TailwindCSS Motion | ~5KB | Good | Built-in | ❌ | ❌ |
+
+**Verdict**: Motion for React-first projects with complex interactions. GSAP for marketing sites with complex timelines. React Spring for physics-driven natural motion. Anime.js for SVG path animations.
+
 ## Installation
 
 ```bash
 npm install motion
+# or migrate from framer-motion:
+npm uninstall framer-motion && npm install motion
+# swap imports: "framer-motion" → "motion/react"
 ```

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/`