cokit-cli 1.2.7 → 1.4.0

package/skills/ck-frontend-design/references/anti-slop-rules.md

@@ -0,0 +1,103 @@
+# Anti-Slop Rules: Avoiding AI Design Fingerprints
+
+These are patterns LLMs gravitate toward by default. Treat them as "overused AI defaults" — not absolute bans. Context matters. A SaaS dashboard and a personal blog have different rules.
+
+## Typography
+
+**Strongly prefer alternatives to:**
+- `Inter` — ubiquitous to the point of being invisible. Prefer `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`, `Plus Jakarta Sans`
+- `Roboto` / `Arial` / `Open Sans` — browser defaults with no character
+- `Space Grotesk` — overused in "tech startup" contexts
+
+**Alternatives:** Variable fonts, display serifs (editorial), tight grotesks (minimal SaaS), humanist sans (consumer apps)
+
+**Avoid:**
+- Serif fonts on dashboards/data UIs — reserve for creative/editorial work
+- Only Regular (400) + Bold (700) — use 500/600 for subtler hierarchy
+- Orphaned words — use `text-wrap: balance` or `text-wrap: pretty`
+- All-caps subheaders everywhere — try lowercase italic, sentence case, small-caps
+
+## Color
+
+**Strongly prefer alternatives to:**
+- AI purple/blue gradient aesthetic — the single most common LLM design fingerprint
+- Pure `#000000` — use off-black: `#0a0a0a`, `#111`, Zinc-950, or tinted dark
+- Oversaturated accents (saturation > 80%) — desaturate to blend elegantly
+- Gradient text on large headers — use sparingly, never on body copy
+
+**Principles:**
+- Max 1 accent color per project. Remove the rest.
+- Stick to one gray family — never mix warm and cool grays
+- Tint shadows to match background hue (dark navy shadow on navy bg), not pure black
+- Flat design with zero texture feels sterile — add subtle noise/grain
+
+## Layout
+
+**Strongly prefer alternatives to:**
+- 3-column equal card layouts as feature rows — the most generic AI layout. Use 2-col zig-zag, asymmetric grid, horizontal scroll, or masonry
+- Centered hero with centered H1 at high variance — try split-screen, left-aligned, or asymmetric whitespace
+- `h-screen` for full-height sections — always use `min-h-[100dvh]` (iOS Safari viewport bug)
+- Complex flexbox `calc()` math for grids — use CSS Grid instead
+
+**Avoid:**
+- Everything centered and symmetrical — break with offset margins or mixed aspect ratios
+- Equal card heights forced by flexbox — allow variable heights or use masonry
+- Uniform border-radius everywhere — vary: tighter on inner elements, softer on containers
+- Missing max-width — always constrain to ~1200-1440px with auto margins
+
+## Content (The "Jane Doe" Effect)
+
+**Avoid:**
+- Generic names: "John Doe", "Jane Smith", "Sarah Chan" — use realistic, diverse names
+- Round fake numbers: `99.99%`, `50%`, `$100.00` — use organic data: `47.2%`, `$99.00`
+- Startup slop names: "Acme", "Nexus", "SmartFlow" — invent contextual brand names
+- AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve", "Tapestry" — write plain, specific language
+- Lorem Ipsum — write real draft copy, even if rough
+- Exclamation marks in success messages — be confident, not loud
+- "Oops!" error messages — be direct: "Connection failed. Try again."
+- Title Case On Every Single Header — use sentence case
+
+## Visual Effects
+
+**Strongly prefer alternatives to:**
+- Neon/outer glows (`box-shadow` glows) — use inner borders or subtle tinted shadows instead
+- Custom mouse cursors — outdated, hurt performance and accessibility
+- Standard `ease-in-out` / `linear` transitions — use spring physics or custom cubic-beziers
+
+**Allowed with care:**
+- Gradient text — sparingly on accent elements, never on body or large headers
+- Glassmorphism — only when it goes beyond `backdrop-blur` (add inner border + refraction shadow)
+
+## Components
+
+**Strongly prefer alternatives to:**
+- Unstyled/default shadcn components — always customize radii, colors, and shadows
+- Generic card (border + shadow + white bg) at high visual density — use spacing/dividers instead
+- Standard Lucide/Feather icons as the only icon set — try Phosphor, Heroicons, or custom SVG for differentiation
+- Rocketship for "Launch", shield for "Security" — avoid cliché icon metaphors
+- 3-card carousel testimonials with dots — masonry wall, embedded posts, or single rotating quote
+- Pill-shaped "New"/"Beta" badges everywhere — try square badges or plain text labels
+- Avatar circles exclusively — try squircles or rounded squares
+
+## External Resources
+
+**Avoid:**
+- Unsplash direct links — use `https://picsum.photos/seed/{name}/800/600` or SVG UI Avatars
+- Same avatar image for multiple users — use unique assets
+- Stock "diverse team" photos — use real photos, candid shots, or consistent illustration style
+
+## AI Tells: Quick Self-Check
+
+Before shipping, scan for these instant giveaways:
+- [ ] Inter font anywhere in the project?
+- [ ] Purple or blue gradient as the main aesthetic?
+- [ ] Three equal-width cards in a row?
+- [ ] Centered hero text over a dark gradient image?
+- [ ] "John Doe" or "Acme Corp" in any content?
+- [ ] Round placeholder numbers (50%, $100)?
+- [ ] "Elevate your workflow" or similar AI copy?
+- [ ] Pure `#000000` as background?
+- [ ] Generic spinner (no skeleton loader)?
+- [ ] No hover/active states on buttons?
+
+If any box is checked, the design reads as AI-generated. Address before delivery.

package/skills/ck-frontend-design/references/asset-generation.md

@@ -0,0 +1,337 @@
+# Asset Generation Workflow
+
+Complete workflow for generating design-aligned visual assets using `ai-multimodal` (if available) skill.
+
+## Generation Workflow
+
+### Step 1: Define Design Context
+
+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?
+- **User context**: Who sees this? What problem does it solve?
+
+### Step 2: Craft Contextual Prompts
+
+Translate design thinking into generation prompts.
+
+**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 `ai-multimodal` (if available) skill's image generation capabilities:
+
+```bash
+# 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
+```
+
+**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
+
+**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
+
+### Step 4: Evaluate Against Design Standards
+
+Use `ai-multimodal` (if available) to analyze the generated asset (see `visual-analysis.md` for complete workflow):
+
+```bash
+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
+```
+
+### 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
+
+### Pattern 1: Minimalist Background Texture
+
+**Design Context**: Clean, refined interface with generous white space
+
+**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"
+```
+
+**Use Case**: Background for minimalist product pages, portfolio sites
+
+### Pattern 2: Maximalist Hero Section
+
+**Design Context**: Bold, energetic landing page with vibrant colors
+
+**Prompt Strategy**:
+```
+"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"
+```
+
+**Use Case**: Hero section for creative agencies, entertainment platforms
+
+### Pattern 3: Brutalist Geometric Pattern
+
+**Design Context**: Raw, bold interface with strong typography
+
+**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"
+```
+
+**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"
+```
+
+**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"
+```
+
+**Use Case**: SaaS landing pages, tech conferences, gaming platforms
+
+### 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"
+```
+
+**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
+# 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
+```
+
+## Model Cost Optimization
+
+**Imagen 4 Pricing** (as of 2024):
+- Standard: ~$0.04 per image
+- Ultra: ~$0.08 per image
+- Fast: ~$0.02 per image
+
+**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
+
+## 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 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/skills/ck-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