@champpaba/claude-agent-kit 1.4.0 → 1.4.1

package/.claude/agents/02-uxui-frontend.md

@@ -94,16 +94,19 @@ Read: .changes/{change-id}/page-plan.md
 - Suggest: User should run `/designsetup` to generate style guide
 
 **If page-plan.md exists:**
-- ✅ Read and load page-plan.md (contains component reuse plan, content draft, assets)
+- ✅ Read and load page-plan.md (contains component reuse plan, content draft, assets, **animation blueprint**)
 - Extract:
+  - **Section 2.6 - Animation Blueprint** (🆕 animation strategy for all components)
   - Component reuse list (which components already exist)
   - Component new list (which to create)
   - Content draft (headlines, descriptions, copy)
   - Asset paths (images, icons locations)
 - **OPTIMIZATION:** Skip STEP 3 (component search) - page-plan already did this!
+- **CRITICAL:** If Section 2.6 exists, animations are **pre-designed** - follow blueprint exactly
 
 **If page-plan.md does NOT exist:**
 - ℹ️ No page plan - will search for components manually in STEP 3
+- ⚠️ No animation blueprint - fallback to `.claude/contexts/patterns/animation-patterns.md`
 
 **Report when complete:**
 ```
@@ -122,8 +125,10 @@ Read: .changes/{change-id}/page-plan.md
 
 📋 Page Plan: ✅ page-plan.md loaded (3 reuse, 2 new, 4 assets)
    → Will skip component search (STEP 3)
+   🎬 Animation Blueprint: ✅ Section 2.6 loaded (buttons, cards, inputs pre-designed)
    OR
 📋 Page Plan: ℹ️ Not found - will search components in STEP 3
+   🎬 Animation Blueprint: ⚠️ Not found - using animation-patterns.md (fallback)
 
 🎯 Ready to create UI components!
 ```
@@ -198,10 +203,112 @@ const TOKENS = {
   spacing: { padding: '[value]', gap: '[value]' },
   colors: { bg: '[token]', text: '[token]' },
   shadows: '[value]',
-  radius: '[value]'
+  radius: '[value]',
+  // 🆕 Animation tokens (MANDATORY - v1.4.0)
+  animation: {
+    hover: '[classes]',          // e.g., hover:scale-105 hover:shadow-lg
+    focus: '[classes]',          // e.g., focus:ring-2 focus:ring-primary
+    active: '[classes]',         // e.g., active:scale-95
+    transition: '[value]',       // e.g., transition-all duration-150
+    duration: '[token]',         // e.g., 150ms, 300ms, 500ms (from STYLE_TOKENS.json)
+    easing: '[token]',           // e.g., ease-in-out
+    description: '[rationale]'   // Why this animation pattern?
+  }
 }
 ```
 
+**Animation Token Extraction Rules:**
+1. ✅ Extract from reference component (STEP 3 search results)
+2. ✅ Fallback to page-plan.md Section 2.6 (if exists)
+3. ✅ Fallback to animation-patterns.md (component patterns)
+4. ✅ Use durations from STYLE_TOKENS.json (150ms, 300ms, 500ms)
+5. ❌ NO random durations (200ms, 250ms, 400ms)
+6. ❌ NO random patterns (button A scales, button B changes color)
+
+### 📋 Step 4.5: Performance Optimization Checklist (MANDATORY)
+
+**→ See:** `.claude/contexts/patterns/performance-optimization.md` for complete guide
+
+**Before implementing ANY component, apply these optimizations:**
+
+#### **Images (Primary Focus)**
+
+- [ ] **Format:** Use WebP with fallback (NOT JPEG/PNG only)
+  ```tsx
+  // ✅ CORRECT
+  <picture>
+    <source srcset="hero.webp" type="image/webp">
+    <img src="hero.jpg" alt="Hero" loading="lazy" />
+  </picture>
+
+  // ❌ WRONG
+  <img src="hero.jpg" alt="Hero" />
+  ```
+
+- [ ] **Lazy Loading:** `loading="lazy"` for below-fold images
+  ```tsx
+  // ✅ Below fold (most images)
+  <img src="product.webp" alt="Product" loading="lazy" width={400} height={300} />
+
+  // ✅ Above fold (hero only)
+  <img src="hero.webp" alt="Hero" loading="eager" width={1920} height={1080} />
+  ```
+
+- [ ] **Dimensions:** ALWAYS specify width/height (prevent layout shift)
+  ```tsx
+  // ✅ CORRECT (prevents CLS)
+  <img src="product.webp" alt="Product" width={400} height={300} />
+
+  // ❌ WRONG (causes layout shift)
+  <img src="product.webp" alt="Product" />
+  ```
+
+- [ ] **Responsive Images:** Generate 3 sizes for images > 400px width
+  ```tsx
+  // ✅ CORRECT (mobile saves bandwidth)
+  <img
+    src="hero-1920.webp"
+    srcset="hero-768.webp 768w, hero-1024.webp 1024w, hero-1920.webp 1920w"
+    sizes="(max-width: 768px) 100vw, 1920px"
+    alt="Hero"
+    width={1920}
+    height={1080}
+  />
+  ```
+
+#### **Code (Secondary Focus)**
+
+- [ ] **Lazy Load Heavy Components:** Use dynamic imports for charts, modals, editors
+  ```tsx
+  // ✅ CORRECT (only load when needed)
+  const HeavyChart = dynamic(() => import('./HeavyChart'), {
+    loading: () => <div>Loading...</div>,
+    ssr: false
+  })
+  ```
+
+- [ ] **Use React.memo() for expensive components:** Prevent unnecessary re-renders
+  ```tsx
+  // ✅ CORRECT (memoize expensive list)
+  export const ProductList = memo(function ProductList({ products }) {
+    return products.map(product => <ProductCard key={product.id} {...product} />)
+  })
+  ```
+
+#### **Quick Validation**
+
+**Before committing code, verify:**
+1. All images have `width` and `height` attributes ✓
+2. Below-fold images have `loading="lazy"` ✓
+3. Hero images use `loading="eager"` ✓
+4. Using WebP format (with fallback) ✓
+5. No arbitrary spacing values (use spacing scale) ✓
+
+**Performance Impact:**
+- LCP: -50-60% (faster hero image load)
+- Bundle size: -30-40% (code splitting)
+- Image size: -80% (WebP + compression)
+
 ### 📋 Step 5: Pre-Implementation Report (REQUIRED)
 
 Provide complete analysis covering steps 1-4 BEFORE writing code.
@@ -230,6 +337,8 @@ Provide complete analysis covering steps 1-4 BEFORE writing code.
 - @.claude/contexts/design/accessibility.md
 - @.claude/contexts/patterns/ui-component-consistency.md (CRITICAL!)
 - @.claude/contexts/patterns/frontend-component-strategy.md
+- @.claude/contexts/patterns/animation-patterns.md (Animations & micro-interactions)
+- @.claude/contexts/patterns/performance-optimization.md (Image optimization, lazy loading)
 
 ### Project-Specific (If Exists)
 - `design-system/STYLE_GUIDE.md` (Priority #1 - loaded in STEP 0.5)

package/.claude/commands/pageplan.md

@@ -163,20 +163,380 @@ Based on context + found components, generate:
 </Layout>
 \`\`\`
 
-## 3. 📦 Assets to Prepare (คุณต้องเตรียม)
+## 2.5. 📐 Layout Wireframe (Visual Blueprint)
 
-### Images
-- [ ] \`filename.jpg\` (widthxheight, format)
-      → Place at: \`/public/images/filename.jpg\`
-      → Purpose: [description]
+> **Purpose:** Visual representation of page layout for user review BEFORE implementation
+
+### Desktop View (>1024px)
+\`\`\`
+┌────────────────────────────────────────────────────┐
+│ [Logo]        [Nav Menu]           [CTA Button]   │  ← Navbar (h-16, sticky)
+├────────────────────────────────────────────────────┤
+│                                                    │
+│                  Hero Section                      │  ← Full viewport (h-screen)
+│              [Large Headline]                      │     Background image
+│            [Subheadline text]                      │     Centered content
+│              [Primary CTA]                         │
+│                                                    │
+├────────────────────────────────────────────────────┤
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
+│  │  Card 1  │  │  Card 2  │  │  Card 3  │        │  ← Feature Grid
+│  │  [Icon]  │  │  [Icon]  │  │  [Icon]  │        │     (grid-cols-3, gap-6)
+│  │  Title   │  │  Title   │  │  Title   │        │     Container: max-w-7xl
+│  │  Desc    │  │  Desc    │  │  Desc    │        │     Padding: py-24
+│  └──────────┘  └──────────┘  └──────────┘        │
+├────────────────────────────────────────────────────┤
+│ [Footer Links]              [Social Icons]        │  ← Footer (h-20)
+└────────────────────────────────────────────────────┘
+\`\`\`
+
+### Tablet View (768-1023px)
+\`\`\`
+┌──────────────────────────────┐
+│ [Logo]   [Nav]      [☰]     │  ← Navbar (collapsed nav)
+├──────────────────────────────┤
+│         Hero Section         │  ← h-[600px]
+│       [Headline]             │     Same layout, smaller
+│       [CTA]                  │
+├──────────────────────────────┤
+│  ┌──────────┐ ┌──────────┐  │
+│  │  Card 1  │ │  Card 2  │  │  ← Feature Grid
+│  └──────────┘ └──────────┘  │     (grid-cols-2, gap-4)
+│  ┌──────────┐               │
+│  │  Card 3  │               │
+│  └──────────┘               │
+├──────────────────────────────┤
+│ Footer (stacked)             │
+└──────────────────────────────┘
+\`\`\`
+
+### Mobile View (<768px)
+\`\`\`
+┌────────────────┐
+│ [Logo]    [☰] │  ← Navbar (hamburger)
+├────────────────┤
+│   Hero         │  ← h-[500px]
+│  [Headline]    │     Smaller text
+│  [CTA]         │     Full-width button
+├────────────────┤
+│ ┌────────────┐ │
+│ │   Card 1   │ │  ← Feature Grid
+│ │   [Icon]   │ │     (grid-cols-1, gap-4)
+│ │   Title    │ │     Full-width cards
+│ └────────────┘ │
+│ ┌────────────┐ │
+│ │   Card 2   │ │
+│ └────────────┘ │
+│ ┌────────────┐ │
+│ │   Card 3   │ │
+│ └────────────┘ │
+├────────────────┤
+│ Footer         │
+│ (stacked)      │
+└────────────────┘
+\`\`\`
+
+### Spacing & Sizing Details
+
+**Containers:**
+- Hero: Full viewport height (h-screen desktop, h-[600px] tablet, h-[500px] mobile)
+- Features: max-w-7xl, px-6, py-24 (desktop) → py-16 (tablet) → py-12 (mobile)
+- Cards: Equal height, p-6 (desktop) → p-4 (mobile)
+
+**Grid Breakpoints:**
+- Desktop (>1024px): 3 columns (grid-cols-3)
+- Tablet (768-1023px): 2 columns (grid-cols-2)
+- Mobile (<768px): 1 column (grid-cols-1)
+
+**Gaps:**
+- Section gaps: gap-24 (desktop) → gap-16 (tablet) → gap-12 (mobile)
+- Card gaps: gap-6 (desktop) → gap-4 (mobile)
+
+### Responsive Behavior
+
+| Element | Desktop | Tablet | Mobile |
+|---------|---------|--------|--------|
+| **Navbar** | Full menu | Collapsed | Hamburger |
+| **Hero** | h-screen | h-[600px] | h-[500px] |
+| **Feature Grid** | 3 cols | 2 cols | 1 col (stack) |
+| **Cards** | Side-by-side | Wrap to 2 cols | Full-width stack |
+| **Footer** | Horizontal | Stacked | Stacked |
+
+---
+
+## 2.6. 🎬 Animation Blueprint (Micro-interactions)
+
+> **Purpose:** Define animation strategy BEFORE implementation to ensure consistency and polish
+> **Source:** `design-system/STYLE_TOKENS.json` (animation tokens)
+> **Philosophy:** Match Flow Engineer Step 3 - Design animations systematically, not randomly
+
+### Animation Principles
+
+**From STYLE_TOKENS.json:**
+- **Durations:** 150ms (quick), 300ms (normal), 500ms (slow)
+- **Easing:** ease-in-out (default), cubic-bezier for custom
+- **Properties:** GPU-accelerated ONLY (transform, opacity) - NOT width, height, top, left
+- **Consistency:** Same component type = same animation pattern
+
+---
+
+### Button Animations
+
+#### Primary CTA Button
+**Hover State:**
+- Properties: `transform` (scale 1.05) + `box-shadow` (md → lg)
+- Duration: 150ms (fast, responsive feel)
+- Easing: ease-in-out
+- Code: `transition-all duration-150 hover:scale-105 hover:shadow-lg`
+
+**Active State:**
+- Properties: `transform` (scale 0.95)
+- Duration: 100ms (immediate feedback)
+- Code: `active:scale-95`
+
+**Loading State:**
+- Properties: `opacity` (text → 70%), spinner fade-in
+- Duration: 300ms
+- Code: `disabled:opacity-70` + spinner component
+
+**Full Example:**
+```tsx
+<button className="px-6 py-3 bg-primary text-primary-foreground rounded-md
+  transition-all duration-150
+  hover:scale-105 hover:shadow-lg
+  active:scale-95
+  disabled:opacity-70">
+  Get Started
+</button>
+```
+
+#### Secondary Button
+**Hover State:**
+- Properties: `background-color` shift, `border-color` shift
+- Duration: 150ms
+- Code: `transition-colors duration-150 hover:bg-secondary/80`
+
+---
+
+### Card Animations
+
+#### Feature Card / Product Card
+**Hover State:**
+- Properties: `box-shadow` elevation (sm → xl)
+- Duration: 300ms (smooth, elegant)
+- Easing: ease-in-out
+- Code: `transition-shadow duration-300 hover:shadow-xl`
+
+**Border Glow (Optional):**
+- Properties: `border-color` subtle shift
+- Duration: 300ms
+- Code: `hover:border-primary/50`
+
+**Full Example:**
+```tsx
+<div className="p-6 bg-card border border-border rounded-lg
+  transition-shadow duration-300
+  hover:shadow-xl hover:border-primary/50">
+  {/* Card content */}
+</div>
+```
+
+#### Interactive Card (Clickable)
+**Hover State:**
+- Same as feature card + cursor pointer
+- Code: `cursor-pointer transition-shadow duration-300 hover:shadow-xl`
+
+**Active State:**
+- Properties: `transform` (scale 0.98) - subtle press feedback
+- Duration: 100ms
+- Code: `active:scale-98`
+
+---
+
+### Input & Form Animations
+
+#### Text Input / Select / Combobox
+**Focus State:**
+- Properties: `box-shadow` (ring-2 appears), `border-color` shift
+- Duration: 200ms (balanced - not too fast, not slow)
+- Easing: ease-in-out
+- Code: `transition-all duration-200 focus:ring-2 focus:ring-primary focus:border-primary`
+
+**Error State:**
+- Properties: `border-color` (→ destructive), optional shake
+- Duration: 300ms
+- Code: `border-destructive` (static) or `animate-shake` (if shake defined)
+
+**Full Example:**
+```tsx
+<input className="w-full px-3 py-2 border border-input rounded-md
+  transition-all duration-200
+  focus:ring-2 focus:ring-primary focus:border-primary
+  placeholder:text-muted-foreground" />
+```
+
+---
+
+### Navigation Animations
+
+#### Desktop Menu Hover
+**Menu Item Hover:**
+- Properties: `background-color` subtle shift
+- Duration: 150ms
+- Code: `transition-colors duration-150 hover:bg-accent`
+
+#### Mobile Menu (Slide-in)
+**Hamburger → Sidebar:**
+- Properties: `transform` (translateX -100% → 0)
+- Duration: 300ms
+- Easing: cubic-bezier(0.4, 0, 0.2, 1)
+- Library: Framer Motion or Tailwind transition
+
+**Example (Framer Motion):**
+```tsx
+<motion.div
+  initial={{ x: "-100%" }}
+  animate={{ x: 0 }}
+  exit={{ x: "-100%" }}
+  transition={{ duration: 0.3, ease: [0.4, 0, 0.2, 1] }}>
+  {/* Sidebar content */}
+</motion.div>
+```
+
+---
+
+### Icon Animations
+
+#### Chevron / Arrow (Dropdown)
+**Expand/Collapse:**
+- Properties: `transform` (rotate 0deg → 180deg)
+- Duration: 200ms
+- Code: `transition-transform duration-200 [data-state=open]:rotate-180`
+
+#### Loading Spinner
+**Continuous Rotation:**
+- Properties: `transform` (rotate 360deg)
+- Duration: 1000ms (1s per rotation)
+- Easing: linear (consistent speed)
+- Code: `animate-spin` (Tailwind utility)
+
+---
+
+### Modal / Dialog Animations
+
+#### Modal Entrance
+**Background Overlay:**
+- Properties: `opacity` (0 → 100%)
+- Duration: 200ms
+- Code: `transition-opacity duration-200`
+
+**Dialog Content:**
+- Properties: `opacity` + `transform` (scale 0.95 → 1)
+- Duration: 300ms
+- Easing: ease-in-out
+- Library: Framer Motion or Radix UI (built-in)
+
+---
+
+### Performance Rules (CRITICAL!)
+
+**✅ DO USE (GPU-accelerated):**
+- `transform` (translate, scale, rotate)
+- `opacity`
+- `filter` (blur, brightness)
+
+**❌ DON'T USE (CPU-intensive, causes reflow):**
+- `width`, `height` (causes layout recalculation)
+- `top`, `left`, `margin` (use `transform` instead)
+- `font-size` (causes text reflow)
+
+**Example:**
+```tsx
+// ❌ WRONG (causes reflow)
+className="hover:w-full hover:h-auto"
+
+// ✅ CORRECT (GPU-accelerated)
+className="hover:scale-105 transform"
+```
+
+---
+
+### Animation Consistency Checklist
+
+**Before implementing components:**
+- [ ] All buttons use scale + shadow pattern (150ms)
+- [ ] All cards use shadow elevation pattern (300ms)
+- [ ] All inputs use ring pattern (200ms)
+- [ ] All durations from STYLE_TOKENS.json (150/300/500ms)
+- [ ] All properties GPU-accelerated (transform, opacity)
+- [ ] No random durations (e.g., 200ms, 400ms) unless intentional
+- [ ] Tested on mobile (animations not janky)
+
+---
+
+### Design Rationale
+
+**Why these patterns?**
+1. **Scale + Shadow (Buttons):** Creates depth, signals interactivity
+2. **Shadow Elevation (Cards):** Subtle, elegant, matches Material Design
+3. **Ring (Inputs):** Clear focus indicator, accessibility compliant
+4. **Short Durations (150-300ms):** Feels responsive, not sluggish
+5. **GPU Properties:** 60fps smooth animations, no jank
+
+**Inspiration:** Based on extracted animations from reference sites + STYLE_TOKENS.json
+
+---
+
+## 3. 📦 Assets to Prepare (Performance-Optimized)
+
+> **Performance Note:** Follow image optimization best practices for faster load times and better SEO.
+> See: `.claude/contexts/patterns/performance-optimization.md`
+
+### Images (Apply Performance Checklist)
+
+**For each image, provide:**
+
+- [ ] **filename.webp** (1920x1080)
+      → **Source:** filename.jpg (compress to WebP, quality 85%)
+      → **Responsive sizes:** 768w, 1024w, 1920w (generate 3 sizes for responsive)
+      → **Loading strategy:**
+         - `loading="lazy"` (if below fold - most images)
+         - `loading="eager"` (if hero/above fold - rare)
+      → **Alt text:** Descriptive alt text for accessibility
+      → **Place at:** `/public/images/`
+      → **Purpose:** [description - where used on page]
+      → **Estimated size:** ~80KB WebP (was ~450KB JPEG) = **-82% reduction**
+      → **LCP impact:** Hero images affect LCP score - optimize first!
+
+**Example:**
+```
+- [ ] **hero-background.webp** (1920x1080)
+      → Source: hero-background.jpg (compress via TinyPNG/Squoosh)
+      → Sizes: hero-768.webp, hero-1024.webp, hero-1920.webp
+      → Loading: eager (hero image, above fold)
+      → Alt: "Students taking TOEIC exam in modern classroom"
+      → Place: /public/images/
+      → Purpose: Hero section background
+      → Size: 85KB WebP (was 520KB JPEG) = -84%
+```
 
 ### Icons
-- [ ] [description] (size, format)
-      → Place at: \`/public/icons/\`
-      → Style: [match STYLE_GUIDE]
+
+**Preferred format:** SVG (scalable, tiny file size)
+
+- [ ] **[icon-name].svg** (24x24 viewBox)
+      → **Format:** SVG (preferred) or PNG sprite (if 10+ icons)
+      → **Optimization:** Remove unnecessary metadata (use SVGO)
+      → **Place at:** `/public/icons/` or inline in component
+      → **Style:** Match STYLE_GUIDE colors
+      → **Estimated size:** 1-3KB per icon
+
+**If using 10+ icons:** Consider SVG sprite sheet (combine → 1 HTTP request)
 
 ### Other Assets
-[Fonts, videos, etc.]
+- [ ] **Fonts:** Use `font-display: swap` to prevent FOIT (Flash of Invisible Text)
+- [ ] **Videos:** Use lazy loading, provide poster image
+- [ ] **Third-party scripts:** Load async/defer when possible
 
 ---