@stella-studio/ck 1.0.0

package/.claude/skills/frontend-design/references/extraction-prompts.md

@@ -0,0 +1,127 @@
+# 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.
+```

package/.claude/skills/frontend-design/references/technical-accessibility.md

@@ -0,0 +1,119 @@
+# Accessibility Checks
+
+WCAG compliance and accessibility guidelines for generated assets.
+
+## Text Overlay Readability
+
+### Color Contrast Ratios
+- **WCAG AA**: 4.5:1 for normal text, 3:1 for large text
+- **WCAG AAA**: 7:1 for normal text, 4.5:1 for large text
+
+### Testing Requirements
+- Test across image variations
+- Consider adding gradient overlays in code
+- Add text shadows for increased legibility
+
+### Alt Text Guidelines
+- Describe the asset's purpose and mood
+- Don't repeat visible text
+- Keep concise (150 characters max)
+
+## CSS Techniques for Accessibility
+
+### Gradient Overlay for Text Readability
+```css
+.hero {
+  position: relative;
+  background-image: url('hero.webp');
+}
+.hero::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    to bottom,
+    rgba(0,0,0,0.3) 0%,
+    rgba(0,0,0,0.6) 100%
+  );
+}
+```
+
+### Text Shadow for Contrast
+```css
+.hero-text {
+  text-shadow: 0 2px 4px rgba(0,0,0,0.5);
+}
+```
+
+### Ensure Minimum Contrast
+```css
+.hero-cta {
+  background: var(--color-primary-600);
+  color: white; /* Ensure 4.5:1 contrast */
+}
+```
+
+## Integration Testing Analysis
+
+Analyze how asset works with UI elements:
+
+```bash
+python scripts/gemini_batch_process.py \
+  --files docs/assets/hero-with-text-overlay.png \
+  --task analyze \
+  --prompt "Analyze this design asset with UI elements overlaid:
+
+1. Text Readability: Can all text be read clearly?
+2. Contrast Issues: Identify any WCAG violations
+3. Visual Hierarchy: Do buttons and CTAs stand out?
+4. Spacing Problems: Any crowding or poor breathing room?
+5. Responsive Concerns: Will this work on mobile at 9:16?
+
+Provide specific recommendations for adjustments." \
+  --output docs/assets/integration-analysis.md \
+  --model gemini-2.5-flash
+```
+
+## Next.js Integration Example
+
+```tsx
+// app/components/Hero.tsx
+import Image from 'next/image'
+
+export function Hero() {
+  return (
+    <section className="relative h-screen">
+      {/* Background image with optimization */}
+      <Image
+        src="/assets/hero-desktop.webp"
+        alt="Minimalist desert landscape"
+        fill
+        priority
+        quality={85}
+        className="object-cover"
+        sizes="100vw"
+      />
+
+      {/* Gradient overlay for text readability */}
+      <div className="absolute inset-0 bg-gradient-to-b from-black/30 to-black/60" />
+
+      {/* Content */}
+      <div className="relative z-10 flex h-full items-center justify-center">
+        <h1 className="text-6xl font-bold text-white drop-shadow-lg">
+          Your Headline
+        </h1>
+      </div>
+    </section>
+  )
+}
+```
+
+## Common Issues
+
+### Issue: Poor Text Overlay Readability
+**Symptoms**: Text hard to read over generated background
+**Solutions**:
+- Add CSS gradient overlay (see above)
+- Regenerate with "clean composition for text overlay" in prompt
+- Use darker/lighter areas strategically
+- Add text shadows or backdrop-blur

package/.claude/skills/frontend-design/references/technical-best-practices.md

@@ -0,0 +1,97 @@
+# Best Practices Checklists
+
+Quality gates and checklists for asset generation workflows.
+
+## Asset Generation Workflow
+
+### Before Generating Assets
+- [ ] Defined clear aesthetic direction from design brief
+- [ ] Extracted color palette and typography character
+- [ ] Identified asset purpose and integration context
+- [ ] Considered accessibility and text overlay needs
+
+### During Generation
+- [ ] Crafted design-driven, contextual prompt
+- [ ] Selected appropriate model and quality level
+- [ ] Specified correct aspect ratio for use case
+- [ ] Generated multiple variations if exploring
+
+### After Generation
+- [ ] Ran comprehensive visual analysis (score ≥ 7/10)
+- [ ] Extracted exact color palette with hex codes
+- [ ] Compared multiple variations and selected best
+- [ ] Tested with overlaid text/UI elements
+- [ ] Optimized file size for web performance
+- [ ] Created responsive variants if needed
+- [ ] Documented asset usage and guidelines
+
+## Design Guideline Extraction Workflow
+
+### When Analyzing Existing Designs
+- [ ] Captured high-quality reference screenshots
+- [ ] Ran comprehensive design analysis with structured prompts
+- [ ] Extracted specific values (hex codes, px sizes, ms timings)
+- [ ] Analyzed multiple screens for pattern consistency
+- [ ] Validated font predictions against Google Fonts
+- [ ] Documented findings in actionable format
+- [ ] Created CSS variable specifications
+- [ ] Saved extracted guidelines in project docs/
+
+## Quality Gates
+
+### Never Proceed to Integration Without
+- [ ] Visual analysis score ≥ 7/10
+- [ ] Extracted color palette documented
+- [ ] Accessibility contrast checks passed
+- [ ] Responsive variants generated
+- [ ] File optimization completed
+- [ ] Asset usage guidelines documented
+
+## Final Checklist
+
+Before considering any asset "done":
+- [ ] Generated with design-driven prompt (not generic)
+- [ ] Analyzed and scored ≥ 7/10
+- [ ] Extracted color palette for CSS implementation
+- [ ] Tested with UI overlays for readability
+- [ ] Optimized for web (WebP/JPEG)
+- [ ] Created responsive variants
+- [ ] Documented usage guidelines
+- [ ] Accessibility checks passed (contrast, alt text)
+- [ ] Integrated into frontend with proper optimization
+
+## Common Issues & Solutions
+
+### Issue 1: Generated Asset Too Generic
+**Symptoms**: Asset looks like stock photography, lacks design character
+**Solution**:
+- Refine prompt with specific aesthetic movements
+- Reference artists/designers/styles explicitly
+- Use more distinctive color directions
+- Add contextual details that make it unique
+
+### Issue 2: Inconsistent Design Language
+**Symptoms**: Each generated asset feels unrelated
+**Solution**:
+- Extract and document design system from first successful generation
+- Reuse color palette keywords in all subsequent prompts
+- Maintain consistent aesthetic direction across generations
+- Reference previous successful assets in new prompts
+
+### Issue 3: Low Analysis Scores
+**Symptoms**: Consistently getting scores < 7/10
+**Solutions**:
+- Review evaluation criteria—are they realistic?
+- Study high-scoring designs for patterns
+- Use design extraction on inspiration to learn what works
+- Iterate prompt with specific improvements from analysis
+
+### Issue 4: Slow Generation Times
+**Symptoms**: Waiting too long for results
+**Solutions**:
+- Use fast model for exploration phase
+- Generate in batches rather than sequentially
+- Reserve ultra model only for final production assets
+- Run analysis while next generation processes
+
+**Remember**: Design first, generate second. Context is king. Iterate ruthlessly. Analysis is mandatory. Demand specifics, not generalities.

package/.claude/skills/frontend-design/references/technical-optimization.md

@@ -0,0 +1,44 @@
+# Cost & Performance Optimization
+
+Model selection strategies and budget guidelines.
+
+## Model Selection Strategy
+
+### 1. Exploration Phase
+Use fast model (3-5 variations):
+- **Cost**: ~$0.02 per image
+- **Speed**: ~5-10 seconds per generation
+- **Use for**: Rapid iteration, aesthetic exploration
+
+### 2. Refinement Phase
+Use standard model (1-2 variations):
+- **Cost**: ~$0.04 per image
+- **Speed**: ~10-20 seconds per generation
+- **Use for**: Production-ready assets
+
+### 3. Final Polish
+Use ultra model (1 generation):
+- **Cost**: ~$0.08 per image
+- **Speed**: ~20-30 seconds per generation
+- **Use for**: Hero images, marketing materials, critical assets
+
+## Analysis Model Strategy
+
+- Use gemini-2.5-flash for all analysis (vision understanding)
+- **Cost**: ~$0.001 per analysis
+- **Speed**: ~2-5 seconds per analysis
+- **Token-efficient**: Images count as ~258-1548 tokens
+
+## Budget Guidelines
+
+- **Small project**: 10-20 images, ~$2-5 total
+- **Medium project**: 50-100 images, ~$10-20 total
+- **Large project**: 200+ images, ~$50+ total
+
+## Optimization Tips
+
+1. **Use fast model first**: Explore variations cheaply before committing to production quality
+2. **Batch analyze**: Analyze multiple variations simultaneously to save time
+3. **Reuse successful prompts**: Once you find a working prompt, reuse it with variations
+4. **Generate responsive variants separately**: Only create mobile versions for assets that need them
+5. **Skip ultra model unless critical**: Standard quality often sufficient for most assets

package/.claude/skills/frontend-design/references/technical-overview.md

@@ -0,0 +1,90 @@
+# 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"
+/>
+```

package/.claude/skills/frontend-design/references/technical-workflows.md

@@ -0,0 +1,150 @@
+# Complete Workflow Examples
+
+End-to-end pipeline examples for asset generation and analysis.
+
+## Example 1: Hero Section (Complete Pipeline)
+
+```bash
+# 1. Generate hero image with design context
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "Minimalist desert landscape, warm beige sand dunes,
+  soft morning light, serene and spacious, muted earth tones
+  (tan, cream, soft ochre), clean composition for text overlay,
+  sophisticated travel aesthetic, 16:9 cinematic" \
+  --output docs/assets/hero-desert \
+  --model imagen-4.0-generate-001 \
+  --aspect-ratio 16:9
+
+# 2. Evaluate aesthetic quality
+python scripts/gemini_batch_process.py \
+  --files docs/assets/hero-desert.png \
+  --task analyze \
+  --prompt "Rate this image 1-10 for: visual appeal, color harmony,
+  suitability for overlaying white text, professional quality.
+  List any improvements needed." \
+  --output docs/assets/hero-evaluation.md \
+  --model gemini-2.5-flash
+
+# 3. If score ≥ 7/10, optimize for web
+python scripts/media_optimizer.py \
+  --input docs/assets/hero-desert.png \
+  --output docs/assets/hero-desktop.webp \
+  --quality 85
+
+# 4. Generate mobile variant (9:16)
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "Minimalist desert landscape, warm beige sand dunes,
+  soft morning light, serene and spacious, muted earth tones
+  (tan, cream, soft ochre), clean composition for text overlay,
+  sophisticated travel aesthetic, 9:16 portrait" \
+  --output docs/assets/hero-mobile \
+  --model imagen-4.0-generate-001 \
+  --aspect-ratio 9:16
+
+# 5. Optimize mobile variant
+python scripts/media_optimizer.py \
+  --input docs/assets/hero-mobile.png \
+  --output docs/assets/hero-mobile.webp \
+  --quality 85
+```
+
+## Example 2: Extract, Generate, Analyze Loop
+
+```bash
+# 1. Extract design guidelines from inspiration
+python scripts/gemini_batch_process.py \
+  --files docs/inspiration/competitor-hero.png \
+  --task analyze \
+  --prompt "[use extraction prompt from extraction-prompts.md]" \
+  --output docs/design-guidelines/competitor-analysis.md \
+  --model gemini-2.5-flash
+
+# 2. Generate asset based on extracted guidelines
+# (Review competitor-analysis.md for color palette, aesthetic)
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[craft prompt using extracted aesthetic and colors]" \
+  --output docs/assets/our-hero \
+  --model imagen-4.0-generate-001 \
+  --aspect-ratio 16:9
+
+# 3. Analyze our generated asset
+python scripts/gemini_batch_process.py \
+  --files docs/assets/our-hero.png \
+  --task analyze \
+  --prompt "Compare to competitor design. Rate differentiation (1-10).
+  Are we too similar or successfully distinct?" \
+  --output docs/assets/differentiation-analysis.md \
+  --model gemini-2.5-flash
+
+# 4. Extract colors from our final asset for CSS
+python scripts/gemini_batch_process.py \
+  --files docs/assets/our-hero.png \
+  --task analyze \
+  --prompt "[use color extraction prompt from visual-analysis-overview.md]" \
+  --output docs/assets/color-palette.md \
+  --model gemini-2.5-flash
+```
+
+## Example 3: A/B Test Assets
+
+```bash
+# Generate 2 design directions
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "Minimalist approach: [prompt]" \
+  --output docs/assets/variant-a \
+  --model imagen-4.0-fast-generate-001 \
+  --aspect-ratio 16:9
+
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "Bold approach: [prompt]" \
+  --output docs/assets/variant-b \
+  --model imagen-4.0-fast-generate-001 \
+  --aspect-ratio 16:9
+
+# Compare variants
+python scripts/gemini_batch_process.py \
+  --files docs/assets/variant-a.png docs/assets/variant-b.png \
+  --task analyze \
+  --prompt "A/B comparison for [target audience]:
+  1. Attention capture
+  2. Brand alignment
+  3. Conversion potential
+  Recommend which to test." \
+  --output docs/assets/ab-comparison.md \
+  --model gemini-2.5-flash
+
+# Generate production version of winner
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[winning approach prompt]" \
+  --output docs/assets/final-hero \
+  --model imagen-4.0-generate-001 \
+  --aspect-ratio 16:9
+```
+
+## Batch Analysis for Rapid Iteration
+
+```bash
+# Generate 3 variations with fast model
+for i in {1..3}; do
+  python scripts/gemini_batch_process.py \
+    --task generate \
+    --prompt "[prompt with variation-$i twist]" \
+    --output docs/assets/var-$i \
+    --model imagen-4.0-fast-generate-001 \
+    --aspect-ratio 16:9
+done
+
+# Batch analyze all variations
+python scripts/gemini_batch_process.py \
+  --files docs/assets/var-*.png \
+  --task analyze \
+  --prompt "Rank these variations 1-3 with scores. Identify winner." \
+  --output docs/assets/batch-analysis.md \
+  --model gemini-2.5-flash
+```