cokit-cli 1.2.6 → 1.3.0

package/templates/repo/.github/skills/frontend-design/references/asset-generation.md

@@ -1,161 +1,337 @@
-# Asset Processing Workflow
+# Asset Generation Workflow
 
-Complete workflow for processing design assets using CLI tools (ImageMagick, FFmpeg, RMBG).
+Complete workflow for generating design-aligned visual assets using `ai-multimodal` (if available) skill.
 
-## Processing Workflow
+## Generation Workflow
 
 ### Step 1: Define Design Context
 
-Before processing, extract from the design brief:
+Before generating, extract from the design brief:
 - **Aesthetic direction**: Minimalist? Maximalist? Brutalist? Organic?
 - **Color palette**: Primary colors, accent colors, mood
+- **Typography character**: Modern sans-serif? Elegant serif? Bold display?
 - **Visual tone**: Professional? Playful? Luxury? Raw?
-- **Output requirements**: Formats, sizes, optimization targets
+- **User context**: Who sees this? What problem does it solve?
 
-### Step 2: Source Assets
+### Step 2: Craft Contextual Prompts
 
-Get assets from:
-- Client-provided images/videos
-- Stock photo services (Unsplash, Pexels)
-- Design tools exports (Figma, Sketch)
-- Screenshots or captured frames
+Translate design thinking into generation prompts.
 
-### Step 3: Process Assets with CLI Tools
+**Generic (❌ Avoid)**:
+```
+"Modern website hero image"
+```
+
+**Design-Driven (✓ Use)**:
+```
+"Brutalist architectural photograph, stark concrete textures,
+dramatic shadows, high contrast black and white, raw unpolished
+surfaces, geometric shapes, monumental scale, inspired by
+1960s Bauhaus, 16:9 aspect ratio"
+```
+
+**Prompt Components**:
+1. **Style/Movement**: "Neo-brutalism", "Art Deco", "Organic modernism"
+2. **Visual Elements**: Textures, shapes, composition style
+3. **Color Direction**: "Muted earth tones", "Vibrant neon accents", "Monochromatic"
+4. **Mood/Atmosphere**: "Serene", "Energetic", "Mysterious"
+5. **Technical Specs**: Aspect ratio, composition focus
+6. **References**: "Inspired by [artist/movement]"
+
+### Step 3: Generate with Appropriate Model
 
-Use these CLI tools:
+Use `ai-multimodal` (if available) skill's image generation capabilities:
 
-**Image Processing (ImageMagick)**:
 ```bash
-# Resize for web
-convert input.png -resize 1920x1080 output.png
+# Standard quality (most cases)
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[your design-driven prompt]" \
+  --output docs/assets/hero-image \
+  --model imagen-4.0-generate-001 \
+  --aspect-ratio 16:9
+
+# Ultra quality (production hero images, marketing)
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[your design-driven prompt]" \
+  --output docs/assets/hero-ultra \
+  --model imagen-4.0-ultra-generate-001 \
+  --size 2K
+
+# Fast iteration (exploring concepts)
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[your design-driven prompt]" \
+  --output docs/assets/concept \
+  --model imagen-4.0-fast-generate-001
+```
 
-# Convert format
-convert input.png output.webp
+**Model Selection**:
+- **imagen-4.0-generate-001**: Default choice, balanced quality/speed
+- **imagen-4.0-ultra-generate-001**: Final production assets, marketing materials
+- **imagen-4.0-fast-generate-001**: Rapid prototyping, multiple variations
 
-# Apply color adjustments
-convert input.png -modulate 100,110,100 output.png
+**Aspect Ratios**:
+- **16:9**: Hero sections, wide banners
+- **9:16**: Mobile-first, vertical content
+- **1:1**: Square cards, social media
+- **4:3**: Classic layouts, presentations
+- **3:4**: Portrait orientations, mobile screens
 
-# Add border/padding
-convert input.png -bordercolor white -border 20 output.png
+### Step 4: Evaluate Against Design Standards
 
-# Create thumbnail
-convert input.png -thumbnail 300x200 thumbnail.png
-```
+Use `ai-multimodal` (if available) to analyze the generated asset (see `visual-analysis.md` for complete workflow):
 
-**Background Removal (RMBG CLI)**:
 ```bash
-# Remove background from image
-rmbg input.png output.png
-
-# Batch process directory
-rmbg -i ./input/ -o ./output/
+python scripts/gemini_batch_process.py \
+  --files docs/assets/hero-image.png \
+  --task analyze \
+  --prompt "Evaluate this image for:
+1. Visual coherence with [aesthetic direction]
+2. Color harmony and contrast
+3. Composition and balance
+4. Suitability for overlaying text
+5. Professional quality (rate 1-10)
+6. Specific weaknesses or improvements needed" \
+  --output docs/assets/hero-evaluation.md \
+  --model gemini-2.5-flash
 ```
 
-**Video Processing (FFmpeg)**:
-```bash
-# Extract frame from video
-ffmpeg -i video.mp4 -ss 00:00:05 -frames:v 1 frame.png
+### Step 5: Iterate or Integrate
+
+**If evaluation score < 7/10 or doesn't meet standards**:
+1. Identify specific issues (color, composition, mood, technical)
+2. Refine prompt with improvements
+3. Regenerate with adjusted parameters
+4. Consider using `media-processing` skill for post-generation adjustments
+
+**If meets standards**:
+1. Optimize for web (compress, format conversion)
+2. Create responsive variants if needed
+3. Document asset usage guidelines
+4. Integrate into frontend implementation
+
+## Design Pattern Examples
 
-# Create thumbnail grid
-ffmpeg -i video.mp4 -frames 1 -vf "select=not(mod(n\,100)),scale=200:120,tile=5x3" grid.png
+### Pattern 1: Minimalist Background Texture
 
-# Convert to web format
-ffmpeg -i input.mp4 -c:v libx264 -crf 23 output.mp4
+**Design Context**: Clean, refined interface with generous white space
 
-# Create animated GIF
-ffmpeg -i video.mp4 -vf "fps=10,scale=480:-1" output.gif
+**Prompt Strategy**:
+```
+"Subtle paper texture, off-white color (#F8F8F8), barely visible
+grain pattern, high-end stationery feel, minimal contrast,
+professional and clean, 1:1 aspect ratio for tiling"
 ```
 
-### Step 4: Optimize for Web
+**Use Case**: Background for minimalist product pages, portfolio sites
 
-**Image Optimization**:
-```bash
-# PNG optimization
-pngquant --quality=65-80 input.png -o output.png
+### Pattern 2: Maximalist Hero Section
 
-# JPEG optimization
-convert input.jpg -quality 85 output.jpg
+**Design Context**: Bold, energetic landing page with vibrant colors
 
-# WebP conversion (smaller file size)
-convert input.png -quality 80 output.webp
+**Prompt Strategy**:
 ```
-
-**Responsive Variants**:
-```bash
-# Create multiple sizes
-convert hero.png -resize 1920x output/hero-lg.png
-convert hero.png -resize 1280x output/hero-md.png
-convert hero.png -resize 768x output/hero-sm.png
-convert hero.png -resize 480x output/hero-xs.png
+"Explosive color gradients, neon pink to electric blue,
+holographic reflections, dynamic diagonal composition,
+retrofuturistic aesthetic, vaporwave influence, high energy,
+layered transparency effects, 16:9 cinematic"
 ```
 
-### Step 5: Verify Quality
+**Use Case**: Hero section for creative agencies, entertainment platforms
 
-After processing, verify:
-- File sizes are optimized (target < 200KB for images)
-- Colors match design palette
-- Resolution appropriate for use case
-- No compression artifacts visible
-- Transparent backgrounds work correctly
+### Pattern 3: Brutalist Geometric Pattern
 
-## Common Asset Tasks
+**Design Context**: Raw, bold interface with strong typography
 
-### Background Removal for Product Images
-```bash
-# Single image
-rmbg product.jpg product-nobg.png
+**Prompt Strategy**:
+```
+"Monochromatic geometric pattern, overlapping rectangles,
+stark black and white, high contrast, Swiss design influence,
+grid-based composition, architectural precision, repeatable
+pattern for backgrounds"
+```
 
-# Batch process
-for f in products/*.jpg; do rmbg "$f" "output/$(basename "$f" .jpg).png"; done
+**Use Case**: Background pattern for design studios, architecture firms
+
+### Pattern 4: Organic Natural Elements
+
+**Design Context**: Wellness brand, calming user experience
+
+**Prompt Strategy**:
+```
+"Soft botanical watercolor, sage green and cream tones,
+gentle leaf shadows, natural light quality, serene atmosphere,
+minimal detail for text overlay, 3:4 portrait orientation"
 ```
 
-### Hero Image Optimization
-```bash
-# Full workflow
-convert original.png -resize 1920x1080^ -gravity center -extent 1920x1080 hero-lg.png
-convert hero-lg.png -quality 85 hero-lg.webp
-convert original.png -resize 768x -quality 85 hero-sm.webp
+**Use Case**: Hero section for wellness brands, eco-friendly products
+
+### Pattern 5: Retro-Futuristic
+
+**Design Context**: Tech product with nostalgic twist
+
+**Prompt Strategy**:
+```
+"80s computer graphics aesthetic, wireframe grids, cyan and magenta
+gradients, digital sunrise, Tron-inspired, geometric precision,
+nostalgic future vision, 16:9 widescreen"
 ```
 
-### Sprite Sheet Creation
-```bash
-# Combine multiple images into sprite
-convert icon-*.png +append sprite.png
+**Use Case**: SaaS landing pages, tech conferences, gaming platforms
 
-# With grid layout
-montage icon-*.png -tile 4x -geometry +0+0 sprite.png
+### Pattern 6: Editorial Magazine Style
+
+**Design Context**: Content-heavy site with strong visual hierarchy
+
+**Prompt Strategy**:
+```
+"High-contrast editorial photography, dramatic side lighting,
+stark shadows, black and white, fashion magazine quality,
+strong vertical composition, 3:4 portrait for text layout"
 ```
 
-### Video Thumbnail
+**Use Case**: Blog headers, news sites, content platforms
+
+## Prompt Engineering Best Practices
+
+### 1. Be Specific About Style
+❌ "Modern design"
+✓ "Bauhaus-inspired geometric abstraction with primary colors"
+
+### 2. Define Color Precisely
+❌ "Colorful"
+✓ "Vibrant sunset palette: coral (#FF6B6B), amber (#FFB84D), violet (#A66FF0)"
+
+### 3. Specify Composition
+❌ "Nice layout"
+✓ "Rule of thirds composition, subject left-aligned, negative space right for text overlay"
+
+### 4. Reference Movements/Artists
+❌ "Artistic"
+✓ "Inspired by Bauhaus geometric abstraction and Swiss International Style"
+
+### 5. Technical Requirements First
+Always include: aspect ratio, resolution needs, intended use case
+
+### 6. Iterate Strategically
+- First generation: Broad aesthetic exploration
+- Second generation: Refine color and composition
+- Third generation: Fine-tune details and mood
+
+## Common Pitfalls to Avoid
+
+### ❌ Generic Stock Photo Aesthetics
+Don't prompt: "Professional business team working together"
+Instead: Design-specific, contextual imagery that serves the interface
+
+### ❌ Overcomplex Generated Images
+Generated assets that compete with UI elements create visual chaos
+Keep backgrounds subtle enough for text/button overlay
+
+### ❌ Inconsistent Visual Language
+Each generated asset should feel part of the same design system
+Maintain color palette, visual style, mood consistency
+
+### ❌ Ignoring Integration Context
+Assets aren't standalone—consider how they work with:
+- Typography overlays
+- Interactive elements (buttons, forms)
+- Navigation and UI chrome
+- Responsive behavior across devices
+
+## Responsive Asset Strategy
+
+### Desktop-First Approach
+1. Generate primary asset at 16:9 (desktop hero)
+2. Generate mobile variant at 9:16 with same prompt
+3. Ensure focal point works in both orientations
+
+### Mobile-First Approach
+1. Generate primary asset at 9:16 (mobile hero)
+2. Generate desktop variant at 16:9 with same prompt
+3. Test that composition scales effectively
+
+### Variant Generation
 ```bash
-# Extract best frame (usually around 25% in)
-ffmpeg -i video.mp4 -ss 00:00:03 -frames:v 1 thumbnail.jpg
+# Desktop (16:9)
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[prompt]" \
+  --output docs/assets/hero-desktop \
+  --model imagen-4.0-generate-001 \
+  --aspect-ratio 16:9
+
+# Mobile (9:16)
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[same prompt]" \
+  --output docs/assets/hero-mobile \
+  --model imagen-4.0-generate-001 \
+  --aspect-ratio 9:16
+
+# Square (1:1)
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[same prompt]" \
+  --output docs/assets/hero-square \
+  --model imagen-4.0-generate-001 \
+  --aspect-ratio 1:1
 ```
 
-## File Format Guidelines
+## Model Cost Optimization
 
-| Format | Use Case | Notes |
-|--------|----------|-------|
-| WebP | Web images (default) | Best compression, wide support |
-| PNG | Images with transparency | Use for icons, logos |
-| JPEG | Photos without transparency | Good for large images |
-| SVG | Icons, simple graphics | Scalable, smallest for simple shapes |
-| MP4 (H.264) | Web video | Universal support |
-| WebM | Modern browsers | Better compression than MP4 |
-| GIF | Simple animations | Limited colors, larger files |
+**Imagen 4 Pricing** (as of 2024):
+- Standard: ~$0.04 per image
+- Ultra: ~$0.08 per image
+- Fast: ~$0.02 per image
 
-## Quality vs Size Targets
+**Optimization Strategy**:
+1. Use Fast model for exploration (3-5 variations)
+2. Select best direction, generate with Standard model
+3. Use Ultra only for final production assets
+4. Batch generate variations in single session
 
-| Asset Type | Target Size | Quality Setting |
-|------------|-------------|-----------------|
-| Hero image | < 200KB | 80-85% |
-| Thumbnails | < 50KB | 75-80% |
-| Icons | < 10KB | PNG or SVG |
-| Product images | < 150KB | 80-85% |
-| Background patterns | < 100KB | 70-80% |
+## Complete Example Workflow
+
+```bash
+# 1. Fast exploration (3 variations)
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "Minimalist mountain landscape, muted blue-gray tones,
+  fog layers, serene morning atmosphere, clean for text overlay, 16:9" \
+  --output docs/assets/concept-1 \
+  --model imagen-4.0-fast-generate-001 \
+  --aspect-ratio 16:9
+
+# 2. Analyze best variation
+python scripts/gemini_batch_process.py \
+  --files docs/assets/concept-1.png \
+  --task analyze \
+  --prompt "Rate 1-10 for aesthetic quality, color harmony, text overlay suitability" \
+  --output docs/assets/analysis-1.md \
+  --model gemini-2.5-flash
+
+# 3. If score ≥ 7/10, generate production version
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[refined prompt based on analysis]" \
+  --output docs/assets/hero-final \
+  --model imagen-4.0-generate-001 \
+  --aspect-ratio 16:9
+
+# 4. Generate mobile variant
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[same refined prompt]" \
+  --output docs/assets/hero-mobile \
+  --model imagen-4.0-generate-001 \
+  --aspect-ratio 9:16
+```
 
 ## Next Steps
 
-- **Verify visual quality**: Compare processed assets to originals
-- **Test across devices**: Ensure responsive variants work
-- **Document assets**: Keep track of source files and processing steps
+- **Verify quality**: See `visual-analysis.md` for comprehensive analysis workflow
+- **Optimize assets**: See `technical-guide.md` for file optimization and integration
+- **Extract inspiration**: See `design-extraction.md` to learn from existing designs

package/templates/repo/.github/skills/frontend-design/references/bento-motion-engine.md

@@ -0,0 +1,142 @@
+# Bento 2.0 Motion Engine
+
+Architecture for modern SaaS dashboards and feature sections. Goes beyond static cards — enforces a "Vercel-core meets Dribbble-clean" aesthetic with perpetual physics.
+
+Use when generating: SaaS dashboards, feature showcase grids, marketing bento sections, product landing pages with interactive demos.
+
+---
+
+## Core Design Philosophy
+
+**Aesthetic:** High-end, minimal, functional. Every card feels alive.
+
+**Palette:**
+- Background: `#f9fafb` (light) or `#050505` (dark)
+- Cards: pure white `#ffffff` (light) / vantablack with `bg-white/5` (dark)
+- Card borders: `border border-slate-200/50` (light) / `border border-white/10` (dark)
+
+**Surfaces:**
+- All major containers use `rounded-[2.5rem]`
+- Diffusion shadow: `shadow-[0_20px_40px_-15px_rgba(0,0,0,0.05)]` — depth without clutter
+- Card titles and descriptions sit **outside and below** the card (gallery-style presentation)
+- Card interior: generous `p-8` or `p-10` padding
+
+**Typography:**
+- Font stack: `Geist`, `Satoshi`, or `Cabinet Grotesk` only
+- Header tracking: `tracking-tight`
+- Never Inter in a Bento context
+
+**Double-Bezel structure for premium cards:**
+- Outer shell: `bg-black/5 ring-1 ring-black/5 p-1.5 rounded-[2rem]`
+- Inner core: own background + `shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)]` + `rounded-[calc(2rem-0.375rem)]`
+
+---
+
+## Animation Engine Specs
+
+All cards MUST contain **Perpetual Micro-Interactions**. The dashboard must always feel alive.
+
+**Spring Physics (no linear easing):**
+```js
+// Use for all interactive elements
+{ type: "spring", stiffness: 100, damping: 20 }
+```
+
+**Layout Transitions:**
+- Use Framer Motion `layout` and `layoutId` props for smooth reordering, resizing, and shared element transitions
+
+**Infinite Loops:**
+- Every card has an active state that loops infinitely: Pulse, Typewriter, Float, or Carousel
+
+**Performance isolation (critical):**
+- Every perpetual animation MUST be wrapped in `React.memo`
+- Extract each animated card as its own isolated leaf `'use client'` component
+- Never trigger re-renders in the parent layout
+
+**AnimatePresence:**
+- Wrap all dynamic lists — enables proper enter/exit animations
+
+---
+
+## Grid Structure
+
+Typical layout: Row 1 = 3 columns | Row 2 = 2 columns (70/30 split)
+
+```jsx
+<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+  {/* Row 1: 3 equal cards */}
+  <IntelligentListCard />
+  <CommandInputCard />
+  <LiveStatusCard />
+</div>
+<div className="grid grid-cols-1 md:grid-cols-[70%_30%] gap-6 mt-6">
+  {/* Row 2: wide data stream + contextual UI */}
+  <WideDataStreamCard />
+  <ContextualUICard />
+</div>
+```
+
+Mobile: all cards collapse to `grid-cols-1` with `gap-6`. No horizontal overflow.
+
+---
+
+## The 5 Card Archetypes
+
+### 1. Intelligent List
+A vertical stack of items with an infinite auto-sorting loop.
+
+- Items swap positions using `layoutId` — simulates AI prioritizing tasks in real-time
+- Smooth position swaps on a ~3s interval
+- Spring-based position transitions for a weighted, physical feel
+- Use case: task lists, priority queues, leaderboards
+
+### 2. Command Input
+A search/AI bar with a multi-step Typewriter Effect.
+
+- Cycles through 3-5 complex prompts
+- Blinking cursor between prompts
+- "Processing" state: shimmering loading gradient on the input
+- On "completion": brief checkmark animation before next cycle
+- Use case: AI search demos, command palette teasers
+
+### 3. Live Status
+A scheduling or status interface with breathing indicators.
+
+- Status dots with infinite `scale` pulse animation (`1.0 → 1.2 → 1.0`, 2s loop)
+- Pop-up notification badge with overshoot spring: appears, stays 3s, vanishes
+- Badge entrance: `scale: [0, 1.2, 1]` with overshoot spring physics
+- Use case: scheduling UIs, monitoring dashboards, live feed indicators
+
+### 4. Wide Data Stream
+A horizontal infinite carousel of data cards or metrics.
+
+- Seamless loop using `x: ["0%", "-50%"]` with duplicate items for continuity
+- Speed feels effortless — not urgent, not slow (~20-30s per full cycle)
+- Cards show metrics, user avatars, status chips, mini sparklines
+- Use case: social proof logos, metric streams, activity feeds
+
+### 5. Contextual UI (Focus Mode)
+A document or content view that highlights and reveals tools.
+
+- Staggered text block highlight animation (sequential word/line highlights, 300ms stagger)
+- After highlight completes: float-in of a floating action toolbar
+- Toolbar entrance: `y: [20, 0]` + `opacity: [0, 1]` with spring, staggered micro-icons
+- Toolbar holds 3-5 action icons with individual hover states
+- Use case: editor demos, AI annotation tools, document review flows
+
+---
+
+## Pre-Flight Checklist
+
+Before shipping a Bento section:
+
+- [ ] Global state used only to avoid deep prop-drilling, not arbitrarily
+- [ ] Mobile layout collapses to single column with `w-full px-4`
+- [ ] Full-height sections use `min-h-[100dvh]` not `h-screen`
+- [ ] All `useEffect` animations have cleanup functions
+- [ ] Empty, loading, and error states provided for each card
+- [ ] Generic card borders replaced with spacing/dividers where appropriate
+- [ ] Every perpetual animation isolated in its own memoized Client Component
+- [ ] No `window.addEventListener('scroll')` — use `whileInView` or `IntersectionObserver`
+- [ ] No arbitrary z-index values
+- [ ] `backdrop-blur` only on fixed/sticky elements, never scrolling cards