@maestro-ai/cli 1.0.0

package/content/skills/frontend-design/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: frontend-design
+description: Design thinking and decision-making for web UI. Use when designing components, layouts, color schemes, typography, or creating aesthetic interfaces. Teaches principles, not fixed values.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Frontend Design System
+
+> **Philosophy:** Every pixel has purpose. Restraint is luxury. User psychology drives decisions.
+> **Core Principle:** THINK, don't memorize. ASK, don't assume.
+
+---
+
+## 🎯 Selective Reading Rule (MANDATORY)
+
+**Read REQUIRED files always, OPTIONAL only when needed:**
+
+| File | Status | When to Read |
+|------|--------|--------------|
+| [ux-psychology.md](ux-psychology.md) | 🔴 **REQUIRED** | Always read first! |
+| [color-system.md](color-system.md) | ⚪ Optional | Color/palette decisions |
+| [typography-system.md](typography-system.md) | ⚪ Optional | Font selection/pairing |
+| [visual-effects.md](visual-effects.md) | ⚪ Optional | Glassmorphism, shadows, gradients |
+| [animation-guide.md](animation-guide.md) | ⚪ Optional | Animation needed |
+| [motion-graphics.md](motion-graphics.md) | ⚪ Optional | Lottie, GSAP, 3D |
+| [decision-trees.md](decision-trees.md) | ⚪ Optional | Context templates |
+
+> 🔴 **ux-psychology.md = ALWAYS READ. Others = only if relevant.**
+
+---
+
+## 🔧 Runtime Scripts
+
+**Execute these for audits (don't read, just run):**
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/ux_audit.py` | UX Psychology & Accessibility Audit | `python scripts/ux_audit.py <project_path>` |
+
+---
+
+## ⚠️ CRITICAL: ASK BEFORE ASSUMING (MANDATORY)
+
+> **STOP! If the user's request is open-ended, DO NOT default to your favorites.**
+
+### When User Prompt is Vague, ASK:
+
+**Color not specified?** Ask:
+> "What color palette do you prefer? (blue/green/orange/neutral/other?)"
+
+**Style not specified?** Ask: 
+> "What style are you going for? (minimal/bold/retro/futuristic/organic?)"
+
+**Layout not specified?** Ask:
+> "Do you have a layout preference? (single column/grid/asymmetric/full-width?)"
+
+### ⛔ DEFAULT TENDENCIES TO AVOID (ANTI-SAFE HARBOR):
+
+| AI Default Tendency | Why It's Bad | Think Instead |
+|---------------------|--------------|---------------|
+| **Bento Grids (Modern Cliché)** | Used in every AI design | Why does this content NEED a grid? |
+| **Hero Split (Left/Right)** | Predictable & Boring | How about Massive Typography or Vertical Narrative? |
+| **Mesh/Aurora Gradients** | The "new" lazy background | What's a radical color pairing? |
+| **Glassmorphism** | AI's idea of "premium" | How about solid, high-contrast flat? |
+| **Deep Cyan / Fintech Blue** | Safe harbor from purple ban | Why not Red, Black, or Neon Green? |
+| **"Orchestrate / Empower"** | AI-generated copywriting | How would a human say this? |
+| Dark background + neon glow | Overused, "AI look" | What does the BRAND actually need? |
+| **Rounded everything** | Generic/Safe | Where can I use sharp, brutalist edges? |
+
+> 🔴 **"Every 'safe' structure you choose brings you one step closer to a generic template. TAKE RISKS."**
+
+---
+
+## 1. Constraint Analysis (ALWAYS FIRST)
+
+Before any design work, ANSWER THESE or ASK USER:
+
+| Constraint | Question | Why It Matters |
+|------------|----------|----------------|
+| **Timeline** | How much time? | Determines complexity |
+| **Content** | Ready or placeholder? | Affects layout flexibility |
+| **Brand** | Existing guidelines? | May dictate colors/fonts |
+| **Tech** | What stack? | Affects capabilities |
+| **Audience** | Who exactly? | Drives all visual decisions |
+
+### Audience → Design Approach
+
+| Audience | Think About |
+|----------|-------------|
+| **Gen Z** | Bold, fast, mobile-first, authentic |
+| **Millennials** | Clean, minimal, value-driven |
+| **Gen X** | Familiar, trustworthy, clear |
+| **Boomers** | Readable, high contrast, simple |
+| **B2B** | Professional, data-focused, trust |
+| **Luxury** | Restrained elegance, whitespace |
+
+---
+
+## 2. UX Psychology Principles
+
+### Core Laws (Internalize These)
+
+| Law | Principle | Application |
+|-----|-----------|-------------|
+| **Hick's Law** | More choices = slower decisions | Limit options, use progressive disclosure |
+| **Fitts' Law** | Bigger + closer = easier to click | Size CTAs appropriately |
+| **Miller's Law** | ~7 items in working memory | Chunk content into groups |
+| **Von Restorff** | Different = memorable | Make CTAs visually distinct |
+| **Serial Position** | First/last remembered most | Key info at start/end |
+
+### Emotional Design Levels
+
+```
+VISCERAL (instant)  → First impression: colors, imagery, overall feel
+BEHAVIORAL (use)    → Using it: speed, feedback, efficiency
+REFLECTIVE (memory) → After: "I like what this says about me"
+```
+
+### Trust Building
+
+- Security indicators on sensitive actions
+- Social proof where relevant
+- Clear contact/support access
+- Consistent, professional design
+- Transparent policies
+
+---
+
+## 3. Layout Principles
+
+### Golden Ratio (φ = 1.618)
+
+```
+Use for proportional harmony:
+├── Content : Sidebar = roughly 62% : 38%
+├── Each heading size = previous × 1.618 (for dramatic scale)
+├── Spacing can follow: sm → md → lg (each × 1.618)
+```
+
+### 8-Point Grid Concept
+
+```
+All spacing and sizing in multiples of 8:
+├── Tight: 4px (half-step for micro)
+├── Small: 8px
+├── Medium: 16px
+├── Large: 24px, 32px
+├── XL: 48px, 64px, 80px
+└── Adjust based on content density
+```
+
+### Key Sizing Principles
+
+| Element | Consideration |
+|---------|---------------|
+| **Touch targets** | Minimum comfortable tap size |
+| **Buttons** | Height based on importance hierarchy |
+| **Inputs** | Match button height for alignment |
+| **Cards** | Consistent padding, breathable |
+| **Reading width** | 45-75 characters optimal |
+
+---
+
+## 4. Color Principles
+
+### 60-30-10 Rule
+
+```
+60% → Primary/Background (calm, neutral base)
+30% → Secondary (supporting areas)
+10% → Accent (CTAs, highlights, attention)
+```
+
+### Color Psychology (For Decision Making)
+
+| If You Need... | Consider Hues | Avoid |
+|----------------|---------------|-------|
+| Trust, calm | Blue family | Aggressive reds |
+| Growth, nature | Green family | Industrial grays |
+| Energy, urgency | Orange, red | Passive blues |
+| Luxury, creativity | Deep Teal, Gold, Emerald | Cheap-feeling brights |
+| Clean, minimal | Neutrals | Overwhelming color |
+
+### Selection Process
+
+1. **What's the industry?** (narrows options)
+2. **What's the emotion?** (picks primary)
+3. **Light or dark mode?** (sets foundation)
+4. **ASK USER** if not specified
+
+For detailed color theory: [color-system.md](color-system.md)
+
+---
+
+## 5. Typography Principles
+
+### Scale Selection
+
+| Content Type | Scale Ratio | Feel |
+|--------------|-------------|------|
+| Dense UI | 1.125-1.2 | Compact, efficient |
+| General web | 1.25 | Balanced (most common) |
+| Editorial | 1.333 | Readable, spacious |
+| Hero/display | 1.5-1.618 | Dramatic impact |
+
+### Pairing Concept
+
+```
+Contrast + Harmony:
+├── DIFFERENT enough for hierarchy
+├── SIMILAR enough for cohesion
+└── Usually: display + neutral, or serif + sans
+```
+
+### Readability Rules
+
+- **Line length**: 45-75 characters optimal
+- **Line height**: 1.4-1.6 for body text
+- **Contrast**: Check WCAG requirements
+- **Size**: 16px+ for body on web
+
+For detailed typography: [typography-system.md](typography-system.md)
+
+---
+
+## 6. Visual Effects Principles
+
+### Glassmorphism (When Appropriate)
+
+```
+Key properties:
+├── Semi-transparent background
+├── Backdrop blur
+├── Subtle border for definition
+└── ⚠️ **WARNING:** Standard blue/white glassmorphism is a modern cliché. Use it radically or not at all.
+```
+
+### Shadow Hierarchy
+
+```
+Elevation concept:
+├── Higher elements = larger shadows
+├── Y-offset > X-offset (light from above)
+├── Multiple layers = more realistic
+└── Dark mode: may need glow instead
+```
+
+### Gradient Usage
+
+```
+Harmonious gradients:
+├── Adjacent colors on wheel (analogous)
+├── OR same hue, different lightness
+├── Avoid harsh complementary pairs
+├── 🚫 **NO Mesh/Aurora Gradients** (floating blobs)
+└── VARY from project to project radically
+```
+
+For complete effects guide: [visual-effects.md](visual-effects.md)
+
+---
+
+## 7. Animation Principles
+
+### Timing Concept
+
+```
+Duration based on:
+├── Distance (further = longer)
+├── Size (larger = slower)
+├── Importance (critical = clear)
+└── Context (urgent = fast, luxury = slow)
+```
+
+### Easing Selection
+
+| Action | Easing | Why |
+|--------|--------|-----|
+| Entering | Ease-out | Decelerate, settle in |
+| Leaving | Ease-in | Accelerate, exit |
+| Emphasis | Ease-in-out | Smooth, deliberate |
+| Playful | Bounce | Fun, energetic |
+
+### Performance
+
+- Animate only transform and opacity
+- Respect reduced-motion preference
+- Test on low-end devices
+
+For animation patterns: [animation-guide.md](animation-guide.md), for advanced: [motion-graphics.md](motion-graphics.md)
+
+---
+
+## 8. "Wow Factor" Checklist
+
+### Premium Indicators
+
+- [ ] Generous whitespace (luxury = breathing room)
+- [ ] Subtle depth and dimension
+- [ ] Smooth, purposeful animations
+- [ ] Attention to detail (alignment, consistency)
+- [ ] Cohesive visual rhythm
+- [ ] Custom elements (not all defaults)
+
+### Trust Builders
+
+- [ ] Security cues where appropriate
+- [ ] Social proof / testimonials
+- [ ] Clear value proposition
+- [ ] Professional imagery
+- [ ] Consistent design language
+
+### Emotional Triggers
+
+- [ ] Hero that evokes intended emotion
+- [ ] Human elements (faces, stories)
+- [ ] Progress/achievement indicators
+- [ ] Moments of delight
+
+---
+
+## 9. Anti-Patterns (What NOT to Do)
+
+### ❌ Lazy Design Indicators
+
+- Default system fonts without consideration
+- Stock imagery that doesn't match
+- Inconsistent spacing
+- Too many competing colors
+- Walls of text without hierarchy
+- Inaccessible contrast
+
+### ❌ AI Tendency Patterns (AVOID!)
+
+- **Same colors every project**
+- **Dark + neon as default**
+- **Purple/violet everything (PURPLE BAN ✅)**
+- **Bento grids for simple landing pages**
+- **Mesh Gradients & Glow Effects**
+- **Same layout structure / Vercel clone**
+- **Not asking user preferences**
+
+### ❌ Dark Patterns (Unethical)
+
+- Hidden costs
+- Fake urgency
+- Forced actions
+- Deceptive UI
+- Confirmshaming
+
+---
+
+## 10. Decision Process Summary
+
+```
+For EVERY design task:
+
+1. CONSTRAINTS
+   └── What's the timeline, brand, tech, audience?
+   └── If unclear → ASK
+
+2. CONTENT
+   └── What content exists?
+   └── What's the hierarchy?
+
+3. STYLE DIRECTION
+   └── What's appropriate for context?
+   └── If unclear → ASK (don't default!)
+
+4. EXECUTION
+   └── Apply principles above
+   └── Check against anti-patterns
+
+5. REVIEW
+   └── "Does this serve the user?"
+   └── "Is this different from my defaults?"
+   └── "Would I be proud of this?"
+```
+
+---
+
+## Reference Files
+
+For deeper guidance on specific areas:
+
+- [color-system.md](color-system.md) - Color theory and selection process
+- [typography-system.md](typography-system.md) - Font pairing and scale decisions
+- [visual-effects.md](visual-effects.md) - Effects principles and techniques
+- [animation-guide.md](animation-guide.md) - Motion design principles
+- [motion-graphics.md](motion-graphics.md) - Advanced: Lottie, GSAP, SVG, 3D, Particles
+- [decision-trees.md](decision-trees.md) - Context-specific templates
+- [ux-psychology.md](ux-psychology.md) - User psychology deep dive
+
+---
+
+> **Remember:** Design is THINKING, not copying. Every project deserves fresh consideration based on its unique context and users. **Avoid the Modern SaaS Safe Harbor!**

package/content/skills/frontend-design/animation-guide.md

@@ -0,0 +1,331 @@
+# Animation Guidelines Reference
+
+> Animation principles and timing psychology - learn to decide, not copy.
+> **No fixed durations to memorize - understand what affects timing.**
+
+---
+
+## 1. Duration Principles
+
+### What Affects Timing
+
+```
+Factors that determine animation speed:
+├── DISTANCE: Further travel = longer duration
+├── SIZE: Larger elements = slower animations
+├── COMPLEXITY: Complex = slower to process
+├── IMPORTANCE: Critical actions = clear feedback
+└── CONTEXT: Urgent = fast, luxurious = slow
+```
+
+### Duration Ranges by Purpose
+
+| Purpose | Range | Why |
+|---------|-------|-----|
+| Instant feedback | 50-100ms | Below perception threshold |
+| Micro-interactions | 100-200ms | Quick but noticeable |
+| Standard transitions | 200-300ms | Comfortable pace |
+| Complex animations | 300-500ms | Time to follow |
+| Page transitions | 400-600ms | Smooth handoff |
+| **Wow/Premium Effects** | 800ms+ | Dramatic, organic spring-based, layered |
+
+### Choosing Duration
+
+Ask yourself:
+1. How far is the element moving?
+2. How important is it to notice this change?
+3. Is the user waiting, or is this background?
+
+---
+
+## 2. Easing Principles
+
+### What Easing Does
+
+```
+Easing = how speed changes over time
+├── Linear: constant speed (mechanical, robotic)
+├── Ease-out: fast start, slow end (natural entry)
+├── Ease-in: slow start, fast end (natural exit)
+└── Ease-in-out: slow both ends (smooth, deliberate)
+```
+
+### When to Use Each
+
+| Easing | Best For | Feels Like |
+|--------|----------|------------|
+| **Ease-out** | Elements entering | Arriving, settling |
+| **Ease-in** | Elements leaving | Departing, exiting |
+| **Ease-in-out** | Emphasis, loops | Deliberate, smooth |
+| **Linear** | Continuous motion | Mechanical, constant |
+| **Bounce/Elastic** | Playful UI | Fun, energetic |
+
+### The Pattern
+
+```css
+/* Entering view = ease-out (decelerate) */
+.enter {
+  animation-timing-function: ease-out;
+}
+
+/* Leaving view = ease-in (accelerate) */
+.exit {
+  animation-timing-function: ease-in;
+}
+
+/* Continuous = ease-in-out */
+.continuous {
+  animation-timing-function: ease-in-out;
+}
+```
+
+---
+
+## 3. Micro-Interaction Principles
+
+### What Makes Good Micro-Interactions
+
+```
+Purpose of micro-interactions:
+├── FEEDBACK: Confirm the action happened
+├── GUIDANCE: Show what's possible
+├── STATUS: Indicate current state
+└── DELIGHT: Small moments of joy
+```
+
+### Button States
+
+```
+Hover → slight visual change (lift, color, scale)
+Active → pressed feeling (scale down, shadow change)
+Focus → clear indicator (outline, ring)
+Loading → progress indicator (spinner, skeleton)
+Success → confirmation (check, color)
+```
+
+### Principles
+
+1. **Respond immediately** (under 100ms perception)
+2. **Match the action** (press = `scale(0.95)`, hover = `translateY(-4px) + glow`)
+3. **Be bold but smooth** (Usta işi hissettir)
+4. **Be consistent** (same actions = same feedback)
+
+---
+
+## 4. Loading States Principles
+
+### Types by Context
+
+| Situation | Approach |
+|-----------|----------|
+| Quick load (<1s) | No indicator needed |
+| Medium (1-3s) | Spinner or simple animation |
+| Long (3s+) | Progress bar or skeleton |
+| Unknown duration | Indeterminate indicator |
+
+### Skeleton Screens
+
+```
+Purpose: Reduce perceived wait time
+├── Show layout shape immediately
+├── Animate subtly (shimmer, pulse)
+├── Replace with content when ready
+└── Feels faster than spinner
+```
+
+### Progress Indicators
+
+```
+When to show progress:
+├── User-initiated action
+├── File uploads/downloads
+├── Multi-step processes
+└── Long operations
+
+When NOT needed:
+├── Very quick operations
+├── Background tasks
+└── Initial page loads (skeleton better)
+```
+
+---
+
+## 5. Page Transitions Principles
+
+### Transition Strategy
+
+```
+Simple rule: exit fast, enter slower
+├── Outgoing content fades quickly
+├── Incoming content animates in
+└── Avoids "everything moving at once"
+```
+
+### Common Patterns
+
+| Pattern | When to Use |
+|---------|-------------|
+| **Fade** | Safe default, works everywhere |
+| **Slide** | Sequential navigation (prev/next) |
+| **Scale** | Opening/closing modals |
+| **Shared element** | Maintaining visual continuity |
+
+### Direction Matching
+
+```
+Navigation direction = animation direction
+├── Forward → slide from right
+├── Backward → slide from left
+├── Deeper → scale up from center
+├── Back up → scale down
+```
+
+---
+
+## 6. Scroll Animation Principles
+
+### Progressive Reveal
+
+```
+Content appears as user scrolls:
+├── Reduces initial cognitive load
+├── Rewards exploration
+├── Must not feel sluggish
+└── Option to disable (accessibility)
+```
+
+### Trigger Points
+
+| When to Trigger | Effect |
+|-----------------|--------|
+| Just entering viewport | Standard reveal |
+| Centered in viewport | For emphasis |
+| Partially visible | Earlier reveal |
+| Fully visible | Late trigger |
+
+### Animation Properties
+
+- Fade in (opacity)
+- Slide up (transform)
+- Scale (transform)
+- Combination of above
+
+### Performance
+
+- Use Intersection Observer
+- Animate only transform/opacity
+- Reduce on mobile if needed
+
+---
+
+## 7. Hover Effects Principles
+
+### Matching Effect to Action
+
+| Element | Effect | Intent |
+|---------|--------|--------|
+| **Clickable card** | Lift + shadow | "This is interactive" |
+| **Button** | Color/brightness change | "Press me" |
+| **Image** | Zoom/scale | "View closer" |
+| **Link** | Underline/color | "Navigate here" |
+
+### Principles
+
+1. **Signal interactivity** - hover shows it's clickable
+2. **Don't overdo it** - subtle changes work
+3. **Match importance** - bigger change = more important
+4. **Touch alternatives** - hover doesn't work on mobile
+
+---
+
+## 8. Feedback Animation Principles
+
+### Success States
+
+```
+Celebrate appropriately:
+├── Minor action → subtle check/color
+├── Major action → more pronounced animation
+├── Completion → satisfying animation
+└── Match brand personality
+```
+
+### Error States
+
+```
+Draw attention without panic:
+├── Color change (semantic red)
+├── Shake animation (brief!)
+├── Focus on error field
+└── Clear messaging
+```
+
+### Timing
+
+- Success: slightly longer (enjoy the moment)
+- Error: quick (don't delay action)
+- Loading: continuous until complete
+
+---
+
+## 9. Performance Principles
+
+### What's Cheap to Animate
+
+```
+GPU-accelerated (FAST):
+├── transform: translate, scale, rotate
+└── opacity: 0 to 1
+
+CPU-intensive (SLOW):
+├── width, height
+├── top, left, right, bottom
+├── margin, padding
+├── border-radius changes
+└── box-shadow changes
+```
+
+### Optimization Strategies
+
+1. **Animate transform/opacity** whenever possible
+2. **Avoid layout triggers** (size/position changes)
+3. **Use will-change sparingly** (hints to browser)
+4. **Test on low-end devices** (not just dev machine)
+
+### Respecting User Preferences
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Honor this preference */
+  /* Essential animations only */
+  /* Reduce or remove decorative motion */
+}
+```
+
+---
+
+## 10. Animation Decision Checklist
+
+Before adding animation:
+
+- [ ] **Is there a purpose?** (feedback/guidance/delight)
+- [ ] **Is timing appropriate?** (not too fast/slow)
+- [ ] **Did you pick correct easing?** (enter/exit/emphasis)
+- [ ] **Is it performant?** (transform/opacity only)
+- [ ] **Tested reduced motion?** (accessibility)
+- [ ] **Consistent with other animations?** (same timing feel)
+- [ ] **Not your default settings?** (variety check)
+- [ ] **Asked user about style if unclear?**
+
+### Anti-Patterns
+
+- ❌ Same timing values every project
+- ❌ Animation for animation's sake
+- ❌ Ignoring reduced-motion preference
+- ❌ Animating expensive properties
+- ❌ Too many things animating at once
+- ❌ Delays that frustrate users
+
+---
+
+> **Remember**: Animation is communication. Every motion should have meaning and serve the user experience.