frontend-design

Original source / Raw SKILL.md

---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications, OR when they provide screenshots/images/designs to replicate or draw inspiration from. For screenshot inputs, extracts design guidelines first using ai-multimodal analysis, then implements code following those guidelines. Generates creative, polished code that avoids generic AI aesthetics.
license: Complete terms in LICENSE.txt
---

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.

## Input Types & Workflows

### When User Provides Screenshot/Image/Design Reference

**MANDATORY workflow for screenshot/image/design inputs**:

1. **Extract Design Guidelines** using `./references/design-extraction-overview.md`:
   - Analyze screenshot/image with ai-multimodal skill
   - Extract: colors (hex codes), typography (fonts, sizes, weights), spacing scale, layout patterns, visual hierarchy
   - Document findings in project `docs/design-guidelines/extracted-design.md`
   - See `./references/extraction-prompts.md` for comprehensive analysis prompts

2. **Implement Code** following extracted guidelines:
   - Use exact colors from extraction (hex codes)
   - Match typography specifications (fonts, sizes, weights, line-heights)
   - Replicate layout structure and spacing system
   - Maintain visual hierarchy and component patterns
   - Preserve aesthetic direction and mood

3. **Verify Quality** using `./references/visual-analysis-overview.md`:
   - Compare implementation to original screenshot
   - Check color accuracy, spacing consistency, typography matching
   - Ensure all design elements preserved

**Important**: Do NOT skip to implementation. Extract design guidelines FIRST, then code.

### When Building from Scratch (No Screenshot Provided)

Follow "Design Thinking" process below to create original design.

## Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
- **Constraints**: Technical requirements (framework, performance, accessibility).
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?

**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
- Production-grade and functional
- Visually striking and memorable
- Cohesive with a clear aesthetic point-of-view
- Meticulously refined in every detail

## Frontend Aesthetics Guidelines

Focus on:
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available (Use `anime.js` for animations: `./references/animejs.md`). Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
- **Visual Assets**: Use `ai-multimodal` skills to generate the assets and `media-processing` skill to remove the background of generated assets if needed

## Working with Visual Assets

**Quick Start**: `./references/ai-multimodal-overview.md`

### Generating New Visual Assets
When you need to GENERATE new hero images, backgrounds, textures, or decorative elements that match the design aesthetic, use the `ai-multimodal` skill. This ensures generated assets align with the design thinking and aesthetics guidelines rather than producing generic imagery.

### Analyzing Provided Screenshots/Images/Designs
When user provides screenshots, photos, or design references to analyze or replicate, use `./references/design-extraction-overview.md` to extract design guidelines BEFORE implementation. This is MANDATORY for screenshot inputs (see "Input Types & Workflows" above).

**Workflows**:
- `./references/asset-generation.md` - Generate design-aligned visual assets
- `./references/visual-analysis-overview.md` - Analyze and verify asset quality (modular)
- `./references/design-extraction-overview.md` - Extract guidelines from inspiration (modular)
- `./references/technical-overview.md` - Optimization and best practices (modular)

Each overview references detailed sub-modules for progressive disclosure.

NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.

Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.

**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.

Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/design-extraction-overview.md

```markdown
# Extract Design Guidelines from Existing Assets

Reverse-engineer design principles from existing images or videos to establish design guidelines.

## Purpose

- Analyze competitor designs to understand their approach
- Extract design systems from inspiration screenshots
- Learn from high-quality design examples
- Create documented guidelines based on visual analysis
- Establish consistent aesthetic direction from references

## Use Cases

- Analyzing competitor websites or apps
- Learning from inspiration galleries (Dribbble, Awwwards, Mobbin)
- Extracting design systems from brand materials
- Reverse-engineering successful interfaces
- Creating design documentation from visual references

## Quick Workflows

### Single Image Analysis
```bash
python scripts/gemini_batch_process.py \
  --files docs/inspiration/reference-design.png \
  --task analyze \
  --prompt "[see extraction-prompts.md for detailed prompt]" \
  --output docs/design-guidelines/extracted-design-system.md \
  --model gemini-2.5-flash
```

### Multi-Screen System Extraction
```bash
python scripts/gemini_batch_process.py \
  --files docs/inspiration/home.png docs/inspiration/about.png \
  --task analyze \
  --prompt "[see extraction-prompts.md for multi-screen prompt]" \
  --output docs/design-guidelines/complete-design-system.md \
  --model gemini-2.5-flash
```

### Video Motion Analysis
```bash
python scripts/gemini_batch_process.py \
  --files docs/inspiration/interaction-demo.mp4 \
  --task analyze \
  --prompt "[see extraction-prompts.md for motion prompt]" \
  --output docs/design-guidelines/motion-system.md \
  --model gemini-2.5-flash
```

### Competitive Analysis
```bash
python scripts/gemini_batch_process.py \
  --files competitor-a.png competitor-b.png competitor-c.png \
  --task analyze \
  --prompt "[see extraction-prompts.md for competitive prompt]" \
  --output docs/design-guidelines/competitive-analysis.md \
  --model gemini-2.5-flash
```

## Detailed References

- `extraction-prompts.md` - All extraction prompt templates
- `extraction-best-practices.md` - Capture quality, analysis tips
- `extraction-output-templates.md` - Documentation formats

## Integration

After extraction, use guidelines with `asset-generation.md` for generating design-aligned visual assets.

```

### references/extraction-prompts.md

```markdown
# Extraction Prompt Templates

Complete prompt templates for design guideline extraction.

## Comprehensive Design Analysis Prompt

```
Extract comprehensive design guidelines from this interface:

## Aesthetic Identification
- Design Style: Identify the aesthetic movement (minimalism, brutalism, maximalism, glassmorphism, neo-brutalism, organic, luxury, editorial, etc.)
- Overall Mood: Professional, playful, serious, energetic, calm, bold, refined
- Differentiation Factor: What makes this design memorable and distinctive?

## Typography System
- Display Font: Predict font family (favor Google Fonts: Playfair Display, Bebas Neue, DM Serif, Archivo Black, etc.). Provide 2-3 alternatives if uncertain.
- Body Font: Identify or suggest similar alternatives
- Font Sizes: Estimate in px for h1, h2, h3, body, small text
- Font Weights: Used weights (300, 400, 500, 600, 700)
- Line Heights: Estimate leading ratios
- Letter Spacing: Tight, normal, or wide tracking

## Color System (CRITICAL)
- Extract 8-12 distinct colors with accurate hex codes
- Classify: Primary (1-2), Secondary (1-2), Accent (2-3), Neutral/Gray (3-5), Background (1-2)
- Note color relationships and usage patterns
- Identify gradients (provide start/end hex codes and direction)

## Spatial Composition
- Layout Type: Grid-based, asymmetric, centered, multi-column, magazine-style
- Grid System: Estimate column count and gutter widths
- Spacing Scale: Identify spacing rhythm (4px, 8px, 16px, 24px, etc.)
- White Space Strategy: Generous, tight, varied
- Section Hierarchy: How content is organized and prioritized

## Visual Elements
- Border Styles: Radius values (sharp, subtle rounded, fully rounded)
- Shadows: Box-shadow characteristics (elevation, spread, blur)
- Backgrounds: Solid, gradients, patterns, textures, images
- Effects: Blur, overlays, transparency, grain, noise
- Decorative Elements: Lines, shapes, illustrations, icons

## Component Patterns
- Button Styles: Shape, size, states, hover effects
- Card Design: Borders, shadows, padding, content structure
- Navigation: Style, position, behavior
- Forms: Input styles, validation, spacing
- Interactive Elements: Hover states, transitions

## Motion & Animation (if video)
- Transition Timing: Fast (100-200ms), medium (200-400ms), slow (400-600ms+)
- Easing Functions: Linear, ease-out, ease-in, cubic-bezier specifics
- Animation Types: Fade, slide, scale, rotate, stagger
- Scroll Interactions: Parallax, reveal-on-scroll, sticky elements

## Accessibility Considerations
- Color Contrast: Evaluate text/background combinations
- Font Sizes: Minimum sizes used
- Interactive Targets: Button/link sizes
- Visual Hierarchy: Clear content prioritization

## Design Highlights
- Top 3 standout design decisions
- What makes this design effective
- Potential improvements or considerations

Output as structured markdown for easy reference.
```

## Multi-Screen System Extraction Prompt

```
Analyze these multiple screens to extract the consistent design system:

For each screen:
1. Identify consistent design tokens (colors, typography, spacing)
2. Note variations and their rationale
3. Extract reusable component patterns

Then synthesize:
- Core design system: Consistent colors, fonts, spacing scales
- Component library: Buttons, cards, navigation, forms
- Layout patterns: Grid systems, responsive behavior
- Visual language: Shared aesthetic principles
- Design tokens: Create CSS variable recommendations

Provide as a unified design system specification.
```

## Motion Design Extraction Prompt

```
Analyze this video to extract motion design guidelines:

1. Transition Timing: Measure duration of key animations (in ms)
2. Easing Curves: Describe acceleration/deceleration (ease-in, ease-out, spring)
3. Animation Types: List all animation styles used
4. Micro-interactions: Button hovers, form focus states, feedback
5. Page Transitions: How screens change
6. Scroll Interactions: Parallax, sticky headers, reveal animations
7. Loading States: Skeleton screens, spinners, progressive reveals
8. Stagger Effects: Sequential animation delays and patterns

Provide implementable specifications with timing values.
```

## Competitive Analysis Prompt

```
Comparative design analysis of 3 competitors:

For each competitor:
1. Design style and aesthetic approach
2. Color strategy and brand perception
3. Typography choices and hierarchy
4. Layout and information architecture
5. Unique design elements
6. Strengths and weaknesses

Synthesis:
- Common industry patterns (what everyone does)
- Differentiation opportunities (gaps to exploit)
- Best practices observed (proven approaches)
- Design recommendations (how to stand out)

Provide strategic design direction based on analysis.
```

```

### references/visual-analysis-overview.md

```markdown
# Visual Analysis Overview

Use AI multimodal vision to analyze generated assets and verify design standards.

## Purpose

- Verify generated assets align with aesthetic direction
- Ensure professional quality before integration
- Identify specific improvements needed for iteration
- Make objective design decisions based on analysis
- Extract actionable data (hex codes, composition insights)

## Quick Start

### Comprehensive Analysis
```bash
python scripts/gemini_batch_process.py \
  --files docs/assets/generated-hero.png \
  --task analyze \
  --prompt "[see analysis-prompts.md for detailed prompt]" \
  --output docs/assets/analysis-report.md \
  --model gemini-2.5-flash
```

### Compare Multiple Variations
```bash
python scripts/gemini_batch_process.py \
  --files docs/assets/option-1.png docs/assets/option-2.png docs/assets/option-3.png \
  --task analyze \
  --prompt "[see analysis-prompts.md for comparison prompt]" \
  --output docs/assets/comparison-analysis.md \
  --model gemini-2.5-flash
```

### Extract Color Palette
```bash
python scripts/gemini_batch_process.py \
  --files docs/assets/final-asset.png \
  --task analyze \
  --prompt "Extract 5-8 dominant colors with hex codes. Classify as primary/accent/neutral. Suggest CSS variable names." \
  --output docs/assets/color-palette.md \
  --model gemini-2.5-flash
```

## Decision Framework

### Score ≥ 8/10: Proceed to Integration
**Actions**:
- Optimize for web delivery
- Create responsive variants
- Document implementation guidelines
- Extract color palette for CSS variables

### Score 6-7/10: Minor Refinements Needed
**Actions**:
- Use `media-processing` skill for adjustments (brightness/contrast/saturation)
- Consider selective regeneration of problem areas
- May proceed with caution if time-constrained

### Score < 6/10: Major Iteration Required
**Actions**:
- Analyze specific failure points from report
- Refine generation prompt substantially
- Regenerate with corrected parameters
- Consider alternative aesthetic approach

## Detailed References

- `analysis-prompts.md` - All analysis prompt templates
- `analysis-techniques.md` - Advanced analysis strategies
- `analysis-best-practices.md` - Quality guidelines and pitfalls

## Example Color Extraction Output

```css
/* Extracted Color Palette */
:root {
  /* Primary Colors */
  --color-primary-600: #2C5F7D;  /* Dark teal - headers, CTAs */
  --color-primary-400: #4A90B8;  /* Medium teal - links, accents */

  /* Accent Colors */
  --color-accent-500: #E8B44F;   /* Warm gold - highlights */

  /* Neutral Colors */
  --color-neutral-900: #1A1A1A;  /* Near black - body text */
  --color-neutral-100: #F5F5F5;  /* Light gray - backgrounds */

  /* Semantic Usage */
  --color-text-primary: var(--color-neutral-900);
  --color-text-on-primary: #FFFFFF;
  --color-background: var(--color-neutral-100);
  --color-cta: var(--color-primary-600);
}
```

```

### references/animejs.md

```markdown
# Anime.js v4 Reference Guide for AI Assistants

## 🚨 CRITICAL: ALWAYS USE ANIME.JS V4 SYNTAX 🚨

**This project uses Anime.js v4.x.x - DO NOT use v3 syntax under any circumstances**

**If you're about to write `import anime from 'animejs'` - STOP!**
**That's v3. This project uses v4. Use the correct import below.**

## 🚀 Quick Start - Essential Setup

### 1. Correct v4 Import (REQUIRED)
```javascript
// ✅ CORRECT v4 imports
import { animate, createTimeline, stagger, utils, svg, eases, engine } from 'animejs';

// ❌ WRONG v3 import - NEVER USE THIS
// import anime from 'animejs';
```

### 2. Configure Time Units to Seconds (SET ONCE IN APP ENTRY POINT)
```javascript
// ⚠️ IMPORTANT: Set this ONLY ONCE in your app's main entry point
// For React: App.js/App.tsx or index.js/index.tsx
// For Vue: main.js/main.ts
// For vanilla JS: The main script file that loads first

import { engine } from 'animejs';

// Set ONLY in the app's entry point, NOT in components
engine.timeUnit = 's';

// Now ALL durations use seconds everywhere: 1 = 1 second, 0.5 = 500ms
// DO NOT set this in individual components - it's a global setting!
```

### 3. Single-Line Format for Simple Animations (REQUIRED)
```javascript
// ✅ GOOD - Clean, readable, one line for simple tweens
animate('.element', { x: 250, duration: 1, ease: 'outQuad' });

// ❌ BAD - Unnecessary multi-line for simple tweens
animate('.element', {
  x: 250,
  duration: 1,
  ease: 'outQuad'
});
```

## ✅ Quick Validation Checklist

Before generating anime.js code, verify:
- [ ] Using `import { animate, ... } from 'animejs'` NOT `import anime`
- [ ] Set `engine.timeUnit = 's'` ONLY ONCE in app entry point (NOT in components)
- [ ] Using seconds for all durations (1 = 1 second)
- [ ] Simple animations on ONE LINE
- [ ] Using `animate()` NOT `anime()`
- [ ] Using `createTimeline()` NOT `anime.timeline()`
- [ ] Using `ease:` NOT `easing:`
- [ ] Using `to:` for values, NOT `value:`
- [ ] Using `on` prefix for callbacks (onUpdate, onComplete)
- [ ] Using `loop` and `alternate` NOT `direction`
- [ ] Using correct v4 stagger syntax with `stagger()`
- [ ] Using shorthand properties (x, y, z) when possible

## 🎯 Core API - Most Common Patterns

### Basic Animation (single line for simple tweens)
```javascript
// Simple tween - ALWAYS one line
animate('.element', { x: 250, rotate: 180, duration: 0.8, ease: 'inOutQuad' });

// Fade in - one line
animate('.element', { opacity: [0, 1], y: [20, 0], duration: 0.6, ease: 'outQuad' });

// Scale bounce - one line
animate('.element', { scale: [0, 1], duration: 0.8, ease: 'outElastic(1, 0.5)' });

// Infinite loop - one line
animate('.element', { rotate: 360, duration: 2, loop: true, ease: 'linear' });
```

### Timeline Creation
```javascript
const tl = createTimeline({ defaults: { duration: 1, ease: 'outQuad' } });

tl.add('.element1', { x: 250 })
  .add('.element2', { y: 100 }, '+=0.2')  // 0.2s after previous
  .add('.element3', { rotate: 180 }, '<'); // at start of previous
```

### Stagger Animations (single line)
```javascript
animate('.elements', { x: 250, delay: stagger(0.1) });  // 0.1s between each
animate('.elements', { x: 250, delay: stagger(0.1, { from: 'center' }) });
```

## ❌ Common AI Mistakes to Avoid

### MISTAKE #1: Using v3 Import Pattern
```javascript
// ❌ WRONG - This is v3
import anime from 'animejs';
anime({ targets: '.element', translateX: 250 });

// ✅ CORRECT - Always use v4
import { animate } from 'animejs';
animate('.element', { x: 250 });
```

### MISTAKE #2: Using 'targets' Property
```javascript
// ❌ WRONG - 'targets' is v3
animate({ targets: '.element', translateX: 250 });

// ✅ CORRECT - First parameter is the target
animate('.element', { x: 250 });
```

### MISTAKE #3: Using 'easing' Instead of 'ease'
```javascript
// ❌ WRONG
animate('.element', { x: 250, easing: 'easeInOutQuad' });

// ✅ CORRECT
animate('.element', { x: 250, ease: 'inOutQuad' });
```

### MISTAKE #4: Using 'value' for Animation Values
```javascript
// ❌ WRONG - 'value' is v3
animate('.element', { x: { value: 250 } });

// ✅ CORRECT - Use 'to' for values
animate('.element', { x: { to: 250 } });
```

### MISTAKE #5: Wrong Timeline Syntax
```javascript
// ❌ WRONG - anime.timeline() is v3
const tl = anime.timeline();

// ✅ CORRECT - Use createTimeline
import { createTimeline } from 'animejs';
const tl = createTimeline();
```

## 📋 Property Syntax Reference (v3 → v4)

### Animation Values
```javascript
// ✅ v4: Use 'to' for target values
{ opacity: { to: 0.5 } }
{ x: { to: [0, 100] } }

// ❌ v3: DON'T use 'value'
// { opacity: { value: 0.5 } }
```

### Easing Functions
```javascript
// ✅ v4: Use 'ease' (no 'ease' prefix)
{ ease: 'inOutQuad' }
{ ease: 'outElastic(1, 0.5)' }
{ ease: 'cubicBezier(0.4, 0, 0.2, 1)' }

// ❌ v3: DON'T use 'easing' or 'ease' prefix
// { easing: 'easeInOutQuad' }
```

### Direction & Looping
```javascript
// ✅ v4
{
  loop: true,        // infinite loop
  loop: 3,          // loop 3 times
  alternate: true,   // alternate direction
  reversed: true     // play in reverse
}

// ❌ v3: DON'T use 'direction'
// { direction: 'alternate' }
```

### Transform Properties (Shorthand Preferred)
```javascript
// ✅ Both syntaxes work in v4:
animate('.element', { x: 100, y: 50, z: 25 });           // shorthand (preferred)
animate('.element', { translateX: 100, translateY: 50, translateZ: 25 }); // explicit
```

### Callbacks (ALL prefixed with 'on')
```javascript
// ✅ v4: Simple callback - keep on one line
animate('.element', { x: 250, duration: 1, onComplete: () => console.log('Done!') });

// ✅ v4: Multiple callbacks - use multi-line
animate('.element', {
  x: 250,
  duration: 1,
  onBegin: (anim) => console.log('Started'),
  onUpdate: (anim) => console.log('Progress:', anim.progress),
  onComplete: (anim) => console.log('Finished')
});

// ❌ v3: DON'T use unprefixed callbacks
// { update: () => {}, complete: () => {} }
```

## 📝 Code Formatting Guidelines

### ALWAYS Use Single-Line Format for Simple Animations
**This is mandatory for readability** - Use for animations with ≤4 properties:
```javascript
// ✅ GOOD - Clean, readable, one line
animate('.element', { x: 250, duration: 1, ease: 'outQuad' });
animate('.box', { opacity: 0.5, scale: 0.8, duration: 0.3 });

// ❌ BAD - Unnecessary multi-line for simple tweens
animate('.element', {
  x: 250,
  duration: 1,
  ease: 'outQuad'
});
```

### Multi-Line Format (Only for Complex Animations)
Use for animations with >4 properties or callbacks:
```javascript
// Complex animation with callbacks - multi-line is appropriate
animate('.element', {
  x: { to: [0, 100, 50], duration: 2 },
  y: { to: [0, -50, 0], duration: 2 },
  scale: [0, 1.2, 1],
  ease: 'outElastic(1, 0.5)',
  onComplete: () => console.log('Done!')
});
```

## 🎨 Common Animation Patterns

### Hover Animation (single line per animation)
```javascript
element.addEventListener('mouseenter', () => animate(element, { scale: 1.1, duration: 0.3, ease: 'outQuad' }));
element.addEventListener('mouseleave', () => animate(element, { scale: 1, duration: 0.3, ease: 'outQuad' }));
```

### Sequential Timeline
```javascript
const tl = createTimeline({ defaults: { duration: 0.5 } });
tl.add('.step1', { x: 100 })
  .add('.step2', { y: 100 })
  .add('.step3', { scale: 2 });
```

### Scroll-triggered Animation
```javascript
import { createScrollObserver } from 'animejs';

createScrollObserver({
  target: '.scroll-element',
  root: document.querySelector('.scroll-container'),
  play: () => animate('.element', { x: 250, duration: 1 }),
  visibility: 0.5
});
```

## 🔧 Advanced Features

### SVG Animations
```javascript
import { animate, svg } from 'animejs';

// Morph path (single line)
animate('#path1', { d: svg.morphTo('#path2'), duration: 1 });

// Draw SVG line
const drawable = svg.createDrawable('.svg-path');
animate(drawable, { draw: '0% 100%', duration: 2 });

// Motion path (single line for simple usage)
const motionPath = svg.createMotionPath('#motion-path');
animate('.element', { x: motionPath.translateX, y: motionPath.translateY, rotate: motionPath.rotate });
```

### Utility Functions
```javascript
import { utils } from 'animejs';

// DOM selection
const elements = utils.$('.elements');

// Get current value
const currentX = utils.get('.element', 'translateX');

// Set values immediately
utils.set('.element', { x: 100, opacity: 0.5 });

// Remove animations
utils.remove('.element');

// Math utilities
utils.random(0, 100);
utils.shuffle([1, 2, 3, 4]);
utils.lerp(0, 100, 0.5); // 50
utils.clamp(150, 0, 100); // 100
```

### TypeScript Support
```typescript
import { animate, createTimeline, JSAnimation, Timeline, AnimationParams, TimelineParams } from 'animejs';

// Single line for simple animations
const animation: JSAnimation = animate('.element', { x: 250, duration: 1 } as AnimationParams);

const timeline: Timeline = createTimeline({ defaults: { duration: 0.8 } } as TimelineParams);
```

## ⚡ Performance Tips

1. **Use transforms over position properties**
   ```javascript
   // ✅ Good - uses transform
   animate('.element', { x: 100 });
   
   // ❌ Avoid - triggers layout
   animate('.element', { left: 100 });
   ```

2. **Batch animations in timelines**
   ```javascript
   // ✅ Good - single timeline
   const tl = createTimeline();
   elements.forEach(el => tl.add(el, { x: 100 }));
   
   // ❌ Avoid - multiple animations
   elements.forEach(el => animate(el, { x: 100 }));
   ```

3. **Use will-change CSS property for complex animations**
   ```css
   .animated-element {
     will-change: transform, opacity;
   }
   ```

## 🚫 How to Identify V3 Code (DON'T USE)

If you see ANY of these patterns, it's v3 and MUST be updated:

```javascript
// All of these are V3 - NEVER USE:
anime({ ... })
anime.timeline()
anime.stagger()
anime.random()
anime.remove()
anime.get()
anime.set()
anime.running
{ targets: '...' }
{ easing: '...' }
{ value: ... }
{ direction: 'alternate' }
```

## 💡 AI Code Generation Rules

When asked to create animations with anime.js:

1. **ONLY** set `engine.timeUnit = 's'` ONCE in the app's main entry point (App.js, main.js, index.js) - NEVER in components
2. **ALWAYS** use seconds for all durations (1 = 1 second)
3. **ALWAYS** format simple animations on ONE LINE
4. **ALWAYS** start with v4 imports
5. **NEVER** use `anime()` function
6. **ALWAYS** use `animate()` for animations
7. **NEVER** include `targets` property
8. **ALWAYS** use `ease` not `easing`
9. **NEVER** use `value`, use `to` instead
10. **ALWAYS** prefix callbacks with `on`
11. **NEVER** use `direction`, use `alternate` and `reversed`
12. **ALWAYS** use `createTimeline()` for timelines
13. **PREFER** shorthand (`x`) over explicit (`translateX`)
14. **FORMAT** short animations on single line (≤4 properties)
15. **NEVER** generate v3 syntax under any circumstances

## NPM Installation
```bash
npm install animejs
```

## Version Check
```javascript
// Current version: 4.x.x
// If you see any code using anime({ targets: ... }), it's v3 and needs updating!
```
```

### references/ai-multimodal-overview.md

```markdown
# AI Multimodal Integration for Frontend Design

Entry point for using the `ai-multimodal` skill to generate and analyze visual assets that align with frontend design thinking and aesthetic guidelines.

## When to Use

Use `ai-multimodal` in frontend design when you need to:

**Asset Generation**:
- Generate hero images, background assets, decorative elements
- Create placeholder images with specific aesthetic qualities
- Produce marketing visuals that match UI design language
- Generate icon sets, illustrations, or graphic elements
- Create texture overlays, gradient meshes, or background patterns
- Prototype visual concepts before implementing in code

**Visual Analysis**:
- Analyze generated assets to verify they meet design standards
- Compare multiple variations objectively with ratings
- Extract exact color palettes with hex codes for implementation
- Test assets with UI overlays for readability and contrast

**Design Extraction**:
- Extract design guidelines from existing images or videos
- Analyze competitor designs to understand their approach
- Reverse-engineer design systems from inspiration screenshots
- Create documented guidelines based on visual analysis
- Establish consistent aesthetic direction from references

## Core Principles

### 1. Design-Driven Generation
**NEVER** generate generic AI imagery. Every asset must align with:
- The chosen aesthetic direction (brutalism, maximalism, retro-futurism, etc.)
- Typography system and visual hierarchy
- Color palette and theme consistency
- Overall design story and purpose

### 2. Contextual Asset Creation
Assets aren't standalone—they're part of a cohesive interface. Consider:
- **Purpose**: Hero image vs. background texture vs. decorative element
- **Integration**: How it interacts with overlaid text, buttons, forms
- **Technical constraints**: File size, aspect ratio, responsive behavior
- **Accessibility**: Color contrast, text readability, decorative vs. informative

### 3. Analysis is Mandatory
Never integrate assets without comprehensive analysis:
- Score quality objectively (1-10 scale, minimum 7/10)
- Extract specific values: hex codes, not "blue"; px sizes, not "large"
- Compare multiple variations before deciding
- Test with UI overlays, not in isolation

### 4. Learn from Excellence
Extract design systems systematically from high-quality references:
- Analyze 3-5 screens to identify patterns
- Document actionably with CSS variables and exact values
- Validate predictions (fonts, colors) manually
- Adapt principles contextually, don't copy blindly

## Workflow Quick Reference

### For Asset Generation
**See**: `asset-generation.md`

1. Define design context (aesthetic, colors, typography, tone)
2. Craft design-driven prompts (not generic)
3. Generate with appropriate Imagen 4 model
4. Analyze and verify quality (score ≥ 7/10)
5. Iterate or integrate based on results

**Models**: imagen-4.0-generate-001 (standard), imagen-4.0-ultra-generate-001 (production), imagen-4.0-fast-generate-001 (iteration)

### For Visual Analysis
**See**: `visual-analysis.md`

1. Define evaluation criteria (context-specific)
2. Run comprehensive analysis with structured prompts
3. Compare multiple variations objectively
4. Extract color palettes with hex codes
5. Test integration with UI elements

**Model**: gemini-2.5-flash (vision understanding)

### For Design Extraction
**See**: `design-extraction.md`

1. Capture high-quality reference screenshots
2. Extract comprehensive design elements systematically
3. Analyze multiple screens for consistent patterns
4. Extract motion guidelines from videos (if applicable)
5. Document actionably with CSS-ready specifications

**Model**: gemini-2.5-flash (vision understanding)

## Integration with Other Skills

### With `aesthetic` Skill
Use `aesthetic` for overall design system guidance and quality evaluation framework. Then use `frontend-design` with `ai-multimodal` for asset generation and analysis that follows those guidelines.

### With `chrome-devtools` Skill
Use `chrome-devtools` to capture full-screen screenshots from inspiration websites for design extraction. Capture at actual viewport size, not full-page scrolls.

### With `ui-styling` Skill
Generate and analyze assets first, then implement using shadcn/ui + Tailwind with colors/styles that complement the generated imagery.

### With `web-frameworks` Skill
Optimize generated assets for Next.js App Router: image optimization, responsive images, lazy loading.

### With `media-processing` Skill
Post-process generated assets: resize, compress, add filters, create compositions using FFmpeg/ImageMagick.

## Navigation

**Detailed Workflows**:
- `asset-generation.md` - Complete generation workflow with prompt strategies
- `visual-analysis.md` - Analysis and verification workflow
- `design-extraction.md` - Extract guidelines from existing designs

**Additional Resources**:
- `technical-guide.md` - File optimization, examples, checklists, common pitfalls
- `animejs.md` - Animation implementation for frontend

## Quick Commands

**Generate asset**:
```bash
python scripts/gemini_batch_process.py \
  --task generate \
  --prompt "[design-driven prompt]" \
  --output docs/assets/[name] \
  --model imagen-4.0-generate-001 \
  --aspect-ratio 16:9
```

**Analyze asset**:
```bash
python scripts/gemini_batch_process.py \
  --files docs/assets/[image].png \
  --task analyze \
  --prompt "[evaluation criteria]" \
  --output docs/assets/analysis.md \
  --model gemini-2.5-flash
```

**Extract design guidelines**:
```bash
python scripts/gemini_batch_process.py \
  --files docs/inspiration/[reference].png \
  --task analyze \
  --prompt "[extraction criteria from design-extraction.md]" \
  --output docs/design-guidelines/extracted.md \
  --model gemini-2.5-flash
```

## Remember

1. **Design First, Generate Second**: Start with design thinking, not generation capabilities
2. **Context is King**: Every asset serves the interface, not itself
3. **Iterate Ruthlessly**: First generation is rarely final—evaluate and refine
4. **Analysis is Mandatory**: Never integrate without comprehensive verification (≥7/10)
5. **Demand Specifics**: Hex codes not "blue", px not "large", ms not "fast"
6. **Learn from Excellence**: Extract design systems from high-quality references systematically
7. **Adapt, Don't Copy**: Understand principles, apply contextually to your unique design

Generate assets that elevate frontend design, maintain aesthetic consistency, and serve user experience—never generic, always contextual.

```

### references/asset-generation.md

```markdown
# Asset Generation Workflow

Complete workflow for generating design-aligned visual assets using `ai-multimodal` 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` 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` 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

```

### references/technical-overview.md

```markdown
# Technical Guide Overview

Technical considerations and best practices for AI multimodal integration in frontend design.

## Quick Reference

### File Optimization
```bash
python scripts/media_optimizer.py \
  --input docs/assets/hero-image.png \
  --output docs/assets/hero-optimized.webp \
  --quality 85
```

### Format Selection
- **WebP**: Best for web, 25-35% smaller than PNG, wide browser support
- **AVIF**: Cutting edge, 50% smaller than WebP, limited support
- **PNG**: Lossless, large file size, use for transparency
- **JPEG**: Lossy, smaller than PNG, photos without transparency

### Responsive Variants
```bash
# Desktop hero (16:9)
--aspect-ratio 16:9

# Mobile hero (9:16 or 3:4)
--aspect-ratio 9:16

# Square cards (1:1)
--aspect-ratio 1:1
```

## Detailed References

- `technical-accessibility.md` - WCAG compliance, contrast checks, alt text
- `technical-workflows.md` - Complete pipeline examples
- `technical-best-practices.md` - Checklists, quality gates
- `technical-optimization.md` - Cost strategies, model selection

## Quick Commands

```bash
# Generate (standard quality)
python scripts/gemini_batch_process.py --task generate \
  --prompt "[design-driven prompt]" \
  --output docs/assets/[name] \
  --model imagen-4.0-generate-001 \
  --aspect-ratio 16:9

# Analyze
python scripts/gemini_batch_process.py --files docs/assets/[image].png \
  --task analyze \
  --prompt "[evaluation criteria]" \
  --output docs/assets/analysis.md \
  --model gemini-2.5-flash

# Optimize
python scripts/media_optimizer.py \
  --input docs/assets/[image].png \
  --output docs/assets/[image].webp \
  --quality 85

# Extract colors
python scripts/gemini_batch_process.py --files docs/assets/[image].png \
  --task analyze \
  --prompt "Extract 5-8 dominant colors with hex codes. Classify as primary/accent/neutral." \
  --output docs/assets/color-palette.md \
  --model gemini-2.5-flash
```

## Responsive Image Strategies

**Art Direction (different crops)**:
```html
<picture>
  <source media="(min-width: 768px)" srcset="hero-desktop.webp">
  <source media="(max-width: 767px)" srcset="hero-mobile.webp">
  <img src="hero-desktop.jpg" alt="Hero image">
</picture>
```

**Resolution Switching (same crop, different sizes)**:
```html
<img
  srcset="hero-400w.webp 400w, hero-800w.webp 800w, hero-1200w.webp 1200w"
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
  src="hero-800w.jpg"
  alt="Hero image"
/>
```

```