thachvd-kit 1.0.28 → 1.0.30

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

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

package/.agent/skills/frontend-design/color-system.md

@@ -1,311 +0,0 @@
-# Color System Reference
-
-> Color theory principles, selection process, and decision-making guidelines.
-> **No memorized hex codes - learn to THINK about color.**
-
----
-
-## 1. Color Theory Fundamentals
-
-### The Color Wheel
-
-```
-                    YELLOW
-                      │
-           Yellow-    │    Yellow-
-           Green      │    Orange
-              ╲       │       ╱
-               ╲      │      ╱
-    GREEN ─────────── ● ─────────── ORANGE
-               ╱      │      ╲
-              ╱       │       ╲
-           Blue-      │    Red-
-           Green      │    Orange
-                      │
-                     RED
-                      │
-                   PURPLE
-                  ╱       ╲
-             Blue-         Red-
-             Purple        Purple
-                  ╲       ╱
-                    BLUE
-```
-
-### Color Relationships
-
-| Scheme | How to Create | When to Use |
-|--------|---------------|-------------|
-| **Monochromatic** | Pick ONE hue, vary only lightness/saturation | Minimal, professional, cohesive |
-| **Analogous** | Pick 2-3 ADJACENT hues on wheel | Harmonious, calm, nature-inspired |
-| **Complementary** | Pick OPPOSITE hues on wheel | High contrast, vibrant, attention |
-| **Split-Complementary** | Base + 2 colors adjacent to complement | Dynamic but balanced |
-| **Triadic** | 3 hues EQUIDISTANT on wheel | Vibrant, playful, creative |
-
-### How to Choose a Scheme:
-1. **What's the project mood?** Calm → Analogous. Bold → Complementary.
-2. **How many colors needed?** Minimal → Monochromatic. Complex → Triadic.
-3. **Who's the audience?** Conservative → Monochromatic. Young → Triadic.
-
----
-
-## 2. The 60-30-10 Rule
-
-### Distribution Principle
-```
-┌─────────────────────────────────────────────────┐
-│                                                 │
-│     60% PRIMARY (Background, large areas)       │
-│     → Should be neutral or calming              │
-│     → Carries the overall tone                  │
-│                                                 │
-├────────────────────────────────────┬────────────┤
-│                                    │            │
-│   30% SECONDARY                    │ 10% ACCENT │
-│   (Cards, sections, headers)       │ (CTAs,     │
-│   → Supports without dominating    │ highlights)│
-│                                    │ → Draws    │
-│                                    │   attention│
-└────────────────────────────────────┴────────────┘
-```
-
-### Implementation Pattern
-```css
-:root {
-  /* 60% - Pick based on light/dark mode and mood */
-  --color-bg: /* neutral: white, off-white, or dark gray */
-  --color-surface: /* slightly different from bg */
-  
-  /* 30% - Pick based on brand or context */
-  --color-secondary: /* muted version of primary or neutral */
-  
-  /* 10% - Pick based on desired action/emotion */
-  --color-accent: /* vibrant, attention-grabbing */
-}
-```
-
----
-
-## 3. Color Psychology - Meaning & Selection
-
-### How to Choose Based on Context
-
-| If Project Is... | Consider These Hues | Why |
-|------------------|---------------------|-----|
-| **Finance, Tech, Healthcare** | Blues, Teals | Trust, stability, calm |
-| **Eco, Wellness, Nature** | Greens, Earth tones | Growth, health, organic |
-| **Food, Energy, Youth** | Orange, Yellow, Warm | Appetite, excitement, warmth |
-| **Luxury, Beauty, Creative** | Deep Teal, Gold, Black | Sophistication, premium |
-| **Urgency, Sales, Alerts** | Red, Orange | Action, attention, passion |
-
-### Emotional Associations (For Decision Making)
-
-| Hue Family | Positive Associations | Cautions |
-|------------|----------------------|----------|
-| **Blue** | Trust, calm, professional | Can feel cold, corporate |
-| **Green** | Growth, nature, success | Can feel boring if overused |
-| **Red** | Passion, urgency, energy | High arousal, use sparingly |
-| **Orange** | Warmth, friendly, creative | Can feel cheap if saturated |
-| **Purple** | ⚠️ **BANNED** - AI overuses this! | Use Deep Teal/Maroon/Emerald instead |
-| **Yellow** | Optimism, attention, happy | Hard to read, use as accent |
-| **Black** | Elegance, power, modern | Can feel heavy |
-| **White** | Clean, minimal, open | Can feel sterile |
-
-### Selection Process:
-1. **What industry?** → Narrow to 2-3 hue families
-2. **What emotion?** → Pick primary hue
-3. **What contrast?** → Decide light vs dark mode
-4. **ASK USER** → Confirm before proceeding
-
----
-
-## 4. Palette Generation Principles
-
-### From a Single Color (HSL Method)
-
-Instead of memorizing hex codes, learn to **manipulate HSL**:
-
-```
-HSL = Hue, Saturation, Lightness
-
-Hue (0-360): The color family
-  0/360 = Red
-  60 = Yellow
-  120 = Green
-  180 = Cyan
-  240 = Blue
-  300 = Purple
-
-Saturation (0-100%): Color intensity
-  Low = Muted, sophisticated
-  High = Vibrant, energetic
-
-Lightness (0-100%): Brightness
-  0% = Black
-  50% = Pure color
-  100% = White
-```
-
-### Generating a Full Palette
-
-Given ANY base color, create a scale:
-
-```
-Lightness Scale:
-  50  (lightest) → L: 97%
-  100            → L: 94%
-  200            → L: 86%
-  300            → L: 74%
-  400            → L: 66%
-  500 (base)     → L: 50-60%
-  600            → L: 48%
-  700            → L: 38%
-  800            → L: 30%
-  900 (darkest)  → L: 20%
-```
-
-### Saturation Adjustments
-
-| Context | Saturation Level |
-|---------|-----------------|
-| **Professional/Corporate** | Lower (40-60%) |
-| **Playful/Youth** | Higher (70-90%) |
-| **Dark Mode** | Reduce by 10-20% |
-| **Accessibility** | Ensure contrast, may need adjustment |
-
----
-
-## 5. Context-Based Selection Guide
-
-### Instead of Copying Palettes, Follow This Process:
-
-**Step 1: Identify the Context**
-```
-What type of project?
-├── E-commerce → Need trust + urgency balance
-├── SaaS/Dashboard → Need low-fatigue, data focus
-├── Health/Wellness → Need calming, natural feel
-├── Luxury/Premium → Need understated elegance
-├── Creative/Portfolio → Need personality, memorable
-└── Other → ASK the user
-```
-
-**Step 2: Select Primary Hue Family**
-```
-Based on context, pick ONE:
-- Blue family (trust)
-- Green family (growth)
-- Warm family (energy)
-- Neutral family (elegant)
-- OR ask user preference
-```
-
-**Step 3: Decide Light/Dark Mode**
-```
-Consider:
-- User preference?
-- Industry standard?
-- Content type? (text-heavy = light preferred)
-- Time of use? (evening app = dark option)
-```
-
-**Step 4: Generate Palette Using Principles**
-- Use HSL manipulation
-- Follow 60-30-10 rule
-- Check contrast (WCAG)
-- Test with actual content
-
----
-
-## 6. Dark Mode Principles
-
-### Key Rules (No Fixed Codes)
-
-1. **Never pure black** → Use very dark gray with slight hue
-2. **Never pure white text** → Use 87-92% lightness
-3. **Reduce saturation** → Vibrant colors strain eyes in dark mode
-4. **Elevation = brightness** → Higher elements slightly lighter
-
-### Contrast in Dark Mode
-
-```
-Background layers (darker → lighter as elevation increases):
-Layer 0 (base)    → Darkest
-Layer 1 (cards)   → Slightly lighter
-Layer 2 (modals)  → Even lighter
-Layer 3 (popups)  → Lightest dark
-```
-
-### Adapting Colors for Dark Mode
-
-| Light Mode | Dark Mode Adjustment |
-|------------|---------------------|
-| High saturation accent | Reduce saturation 10-20% |
-| Pure white background | Dark gray with brand hue tint |
-| Black text | Light gray (not pure white) |
-| Colorful backgrounds | Desaturated, darker versions |
-
----
-
-## 7. Accessibility Guidelines
-
-### Contrast Requirements (WCAG)
-
-| Level | Normal Text | Large Text |
-|-------|-------------|------------|
-| AA (minimum) | 4.5:1 | 3:1 |
-| AAA (enhanced) | 7:1 | 4.5:1 |
-
-### How to Check Contrast
-
-1. **Convert colors to luminance**
-2. **Calculate ratio**: (lighter + 0.05) / (darker + 0.05)
-3. **Adjust until ratio meets requirement**
-
-### Safe Patterns
-
-| Use Case | Guideline |
-|----------|-----------|
-| **Text on light bg** | Use lightness 35% or less |
-| **Text on dark bg** | Use lightness 85% or more |
-| **Primary on white** | Ensure dark enough variant |
-| **Buttons** | High contrast between bg and text |
-
----
-
-## 8. Color Selection Checklist
-
-Before finalizing any color choice, verify:
-
-- [ ] **Asked user preference?** (if not specified)
-- [ ] **Matches project context?** (industry, audience)
-- [ ] **Follows 60-30-10?** (proper distribution)
-- [ ] **WCAG compliant?** (contrast checked)
-- [ ] **Works in both modes?** (if dark mode needed)
-- [ ] **NOT your default/favorite?** (variety check)
-- [ ] **Different from last project?** (avoid repetition)
-
----
-
-## 9. Anti-Patterns to Avoid
-
-### ❌ DON'T:
-- Copy the same hex codes every project
-- Default to purple/violet (AI tendency)
-- Default to dark mode + neon (AI tendency)
-- Use pure black (#000000) backgrounds
-- Use pure white (#FFFFFF) text on dark
-- Ignore user's industry context
-- Skip asking user preference
-
-### ✅ DO:
-- Generate fresh palette per project
-- Ask user about color preferences
-- Consider industry and audience
-- Use HSL for flexible manipulation
-- Test contrast and accessibility
-- Offer light AND dark options
-
----
-
-> **Remember**: Colors are decisions, not defaults. Every project deserves thoughtful selection based on its unique context.