npm - @mrtrinhvn/ag-kit - Versions diffs - 1.0.11 → 1.1.1 - Mend

@mrtrinhvn/ag-kit 1.0.11 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (218) hide show

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

@@ -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 DELETED Viewed

@@ -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.