@agentskillkit/agent-skills 1.0.1

package/.agent/skills/frontend-design/rules/visual-effects.md

@@ -0,0 +1,383 @@
+# Visual Effects Reference
+
+> Modern CSS effect principles and techniques - learn the concepts, create variations.
+> **No fixed values to copy - understand the patterns.**
+
+---
+
+## 1. Glassmorphism Principles
+
+### What Makes Glassmorphism Work
+
+```
+Key Properties:
+├── Semi-transparent background (not solid)
+├── Backdrop blur (frosted glass effect)
+├── Subtle border (for definition)
+└── Often: light shadow for depth
+```
+
+### The Pattern (Customize Values)
+
+```css
+.glass {
+  /* Transparency: adjust opacity based on content readability */
+  background: rgba(R, G, B, OPACITY);
+  /* OPACITY: 0.1-0.3 for dark bg, 0.5-0.8 for light bg */
+  
+  /* Blur: higher = more frosted */
+  backdrop-filter: blur(AMOUNT);
+  /* AMOUNT: 8-12px subtle, 16-24px strong */
+  
+  /* Border: defines edges */
+  border: 1px solid rgba(255, 255, 255, OPACITY);
+  /* OPACITY: 0.1-0.3 typically */
+  
+  /* Radius: match your design system */
+  border-radius: YOUR_RADIUS;
+}
+```
+
+### When to Use Glassmorphism
+- ✅ Over colorful/image backgrounds
+- ✅ Modals, overlays, cards
+- ✅ Navigation bars with scrolling content behind
+- ❌ Text-heavy content (readability issues)
+- ❌ Simple solid backgrounds (pointless)
+
+### When NOT to Use
+- Low contrast situations
+- Accessibility-critical content
+- Performance-constrained devices
+
+---
+
+## 2. Neomorphism Principles
+
+### What Makes Neomorphism Work
+
+```
+Key Concept: Soft, extruded elements using DUAL shadows
+├── Light shadow (from light source direction)
+├── Dark shadow (opposite direction)
+└── Background matches surrounding (same color)
+```
+
+### The Pattern
+
+```css
+.neo-raised {
+  /* Background MUST match parent */
+  background: SAME_AS_PARENT;
+  
+  /* Two shadows: light direction + dark direction */
+  box-shadow: 
+    OFFSET OFFSET BLUR rgba(light-color),
+    -OFFSET -OFFSET BLUR rgba(dark-color);
+  
+  /* OFFSET: typically 6-12px */
+  /* BLUR: typically 12-20px */
+}
+
+.neo-pressed {
+  /* Inset creates "pushed in" effect */
+  box-shadow: 
+    inset OFFSET OFFSET BLUR rgba(dark-color),
+    inset -OFFSET -OFFSET BLUR rgba(light-color);
+}
+```
+
+### Accessibility Warning
+⚠️ **Low contrast** - use sparingly, ensure clear boundaries
+
+### When to Use
+- Decorative elements
+- Subtle interactive states
+- Minimalist UI with flat colors
+
+---
+
+## 3. Shadow Hierarchy Principles
+
+### Concept: Shadows Indicate Elevation
+
+```
+Higher elevation = larger shadow
+├── Level 0: No shadow (flat on surface)
+├── Level 1: Subtle shadow (slightly raised)
+├── Level 2: Medium shadow (cards, buttons)
+├── Level 3: Large shadow (modals, dropdowns)
+└── Level 4: Deep shadow (floating elements)
+```
+
+### Shadow Properties to Adjust
+
+```css
+box-shadow: OFFSET-X OFFSET-Y BLUR SPREAD COLOR;
+
+/* Offset: direction of shadow */
+/* Blur: softness (larger = softer) */
+/* Spread: size expansion */
+/* Color: typically black with low opacity */
+```
+
+### Principles for Natural Shadows
+
+1. **Y-offset larger than X** (light comes from above)
+2. **Low opacity** (5-15% for subtle, 15-25% for pronounced)
+3. **Multiple layers** for realism (ambient + direct)
+4. **Blur scales with offset** (larger offset = larger blur)
+
+### Dark Mode Shadows
+- Shadows less visible on dark backgrounds
+- May need to increase opacity
+- Or use glow/highlight instead
+
+---
+
+## 4. Gradient Principles
+
+### Types and When to Use
+
+| Type | Pattern | Use Case |
+|------|---------|----------|
+| **Linear** | Color A → Color B along line | Backgrounds, buttons, headers |
+| **Radial** | Center → outward | Spotlights, focal points |
+| **Conic** | Around center | Pie charts, creative effects |
+
+### Creating Harmonious Gradients
+
+```
+Good Gradient Rules:
+├── Use ADJACENT colors on wheel (analogous)
+├── Or same hue with different lightness
+├── Avoid complementary (can look harsh)
+└── Add middle stops for smoother transitions
+```
+
+### Gradient Syntax Pattern
+
+```css
+.gradient {
+  background: linear-gradient(
+    DIRECTION,           /* angle or to-keyword */
+    COLOR-STOP-1,        /* color + optional position */
+    COLOR-STOP-2,
+    /* ... more stops */
+  );
+}
+
+/* DIRECTION examples: */
+/* 90deg, 135deg, to right, to bottom right */
+```
+
+### Mesh Gradients
+
+```
+Multiple radial gradients overlapped:
+├── Each at different position
+├── Each with transparent falloff
+├── **Mandatory for "Wow" factor in Hero sections**
+└── Creates organic, colorful effect (Search: "Aurora Gradient CSS")
+```
+
+---
+
+## 5. Border Effects Principles
+
+### Gradient Borders
+
+```
+Technique: Pseudo-element with gradient background
+├── Element has padding = border width
+├── Pseudo-element fills with gradient
+└── Mask or clip creates border effect
+```
+
+### Animated Borders
+
+```
+Technique: Rotating gradient or conic sweep
+├── Pseudo-element larger than content
+├── Animation rotates the gradient
+└── Overflow hidden clips to shape
+```
+
+### Glow Borders
+
+```css
+/* Multiple box-shadows create glow */
+box-shadow:
+  0 0 SMALL-BLUR COLOR,
+  0 0 MEDIUM-BLUR COLOR,
+  0 0 LARGE-BLUR COLOR;
+
+/* Each layer adds to the glow */
+```
+
+---
+
+## 6. Glow Effects Principles
+
+### Text Glow
+
+```css
+text-shadow: 
+  0 0 BLUR-1 COLOR,
+  0 0 BLUR-2 COLOR,
+  0 0 BLUR-3 COLOR;
+
+/* Multiple layers = stronger glow */
+/* Larger blur = softer spread */
+```
+
+### Element Glow
+
+```css
+box-shadow:
+  0 0 BLUR-1 COLOR,
+  0 0 BLUR-2 COLOR;
+
+/* Use color matching element for realistic glow */
+/* Lower opacity for subtle, higher for neon */
+```
+
+### Pulsing Glow Animation
+
+```css
+@keyframes glow-pulse {
+  0%, 100% { box-shadow: 0 0 SMALL-BLUR COLOR; }
+  50% { box-shadow: 0 0 LARGE-BLUR COLOR; }
+}
+
+/* Easing and duration affect feel */
+```
+
+---
+
+## 7. Overlay Techniques
+
+### Gradient Overlay on Images
+
+```
+Purpose: Improve text readability over images
+Pattern: Gradient from transparent to opaque
+Position: Where text will appear
+```
+
+```css
+.overlay::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    DIRECTION,
+    transparent PERCENTAGE,
+    rgba(0,0,0,OPACITY) 100%
+  );
+}
+```
+
+### Colored Overlay
+
+```css
+/* Blend mode or layered gradient */
+background: 
+  linear-gradient(YOUR-COLOR-WITH-OPACITY),
+  url('image.jpg');
+```
+
+---
+
+## 8. Modern CSS Techniques
+
+### Container Queries (Concept)
+
+```
+Instead of viewport breakpoints:
+├── Component responds to ITS container
+├── Truly modular, reusable components
+└── Syntax: @container (condition) { }
+```
+
+### :has() Selector (Concept)
+
+```
+Parent styling based on children:
+├── "Parent that has X child"
+├── Enables previously impossible patterns
+└── Progressive enhancement approach
+```
+
+### Scroll-Driven Animations (Concept)
+
+```
+Animation progress tied to scroll:
+├── Entry/exit animations on scroll
+├── Parallax effects
+├── Progress indicators
+└── View-based or scroll-based timeline
+```
+
+---
+
+## 9. Performance Principles
+
+### GPU-Accelerated Properties
+
+```
+CHEAP to animate (GPU):
+├── transform (translate, scale, rotate)
+└── opacity
+
+EXPENSIVE to animate (CPU):
+├── width, height
+├── top, left, right, bottom
+├── margin, padding
+└── box-shadow (recalculates)
+```
+
+### will-change Usage
+
+```css
+/* Use sparingly, only for heavy animations */
+.heavy-animation {
+  will-change: transform;
+}
+
+/* Remove after animation if possible */
+```
+
+### Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Disable or minimize animations */
+  /* Respect user preference */
+}
+```
+
+---
+
+## 10. Effect Selection Checklist
+
+Before applying any effect:
+
+- [ ] **Does it serve a purpose?** (not just decoration)
+- [ ] **Is it appropriate for the context?** (brand, audience)
+- [ ] **Have you varied from previous projects?** (avoid repetition)
+- [ ] **Is it accessible?** (contrast, motion sensitivity)
+- [ ] **Is it performant?** (especially on mobile)
+- [ ] **Did you ask user preference?** (if style open-ended)
+
+### Anti-Patterns
+
+- ❌ Glassmorphism on every element (kitsch)
+- ❌ Dark + neon as default (lazy AI look)
+- ❌ **Static/Flat designs with no depth (FAILED)**
+- ❌ Effects that hurt readability
+- ❌ Animations without purpose
+
+---
+
+> **Remember**: Effects enhance meaning. Choose based on purpose and context, not because it "looks cool."

package/.agent/skills/frontend-design/scripts/accessibility_checker.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+Accessibility Checker - WCAG compliance audit
+Checks HTML files for accessibility issues.
+
+Usage:
+    python accessibility_checker.py <project_path>
+
+Checks:
+    - Form labels
+    - ARIA attributes
+    - Color contrast hints
+    - Keyboard navigation
+    - Semantic HTML
+"""
+
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+
+def find_html_files(project_path: Path) -> list:
+    """Find all HTML/JSX/TSX files."""
+    patterns = ['**/*.html', '**/*.jsx', '**/*.tsx']
+    skip_dirs = {'node_modules', '.next', 'dist', 'build', '.git'}
+    
+    files = []
+    for pattern in patterns:
+        for f in project_path.glob(pattern):
+            if not any(skip in f.parts for skip in skip_dirs):
+                files.append(f)
+    
+    return files[:50]
+
+
+def check_accessibility(file_path: Path) -> list:
+    """Check a single file for accessibility issues."""
+    issues = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8', errors='ignore')
+        
+        # Check for form inputs without labels
+        inputs = re.findall(r'<input[^>]*>', content, re.IGNORECASE)
+        for inp in inputs:
+            if 'type="hidden"' not in inp.lower():
+                if 'aria-label' not in inp.lower() and 'id=' not in inp.lower():
+                    issues.append("Input without label or aria-label")
+                    break
+        
+        # Check for buttons without accessible text
+        buttons = re.findall(r'<button[^>]*>[^<]*</button>', content, re.IGNORECASE)
+        for btn in buttons:
+            # Check if button has text content or aria-label
+            if 'aria-label' not in btn.lower():
+                text = re.sub(r'<[^>]+>', '', btn)
+                if not text.strip():
+                    issues.append("Button without accessible text")
+                    break
+        
+        # Check for missing lang attribute
+        if '<html' in content.lower() and 'lang=' not in content.lower():
+            issues.append("Missing lang attribute on <html>")
+        
+        # Check for missing skip link
+        if '<main' in content.lower() or '<body' in content.lower():
+            if 'skip' not in content.lower() and '#main' not in content.lower():
+                issues.append("Consider adding skip-to-main-content link")
+        
+        # Check for click handlers without keyboard support
+        onclick_count = content.lower().count('onclick=')
+        onkeydown_count = content.lower().count('onkeydown=') + content.lower().count('onkeyup=')
+        if onclick_count > 0 and onkeydown_count == 0:
+            issues.append("onClick without keyboard handler (onKeyDown)")
+        
+        # Check for tabIndex misuse
+        if 'tabindex=' in content.lower():
+            if 'tabindex="-1"' not in content.lower() and 'tabindex="0"' not in content.lower():
+                positive_tabindex = re.findall(r'tabindex="([1-9]\d*)"', content, re.IGNORECASE)
+                if positive_tabindex:
+                    issues.append("Avoid positive tabIndex values")
+        
+        # Check for autoplay media
+        if 'autoplay' in content.lower():
+            if 'muted' not in content.lower():
+                issues.append("Autoplay media should be muted")
+        
+        # Check for role usage
+        if 'role="button"' in content.lower():
+            # Divs with role button should have tabindex
+            div_buttons = re.findall(r'<div[^>]*role="button"[^>]*>', content, re.IGNORECASE)
+            for div in div_buttons:
+                if 'tabindex' not in div.lower():
+                    issues.append("role='button' without tabindex")
+                    break
+        
+    except Exception as e:
+        issues.append(f"Error reading file: {str(e)[:50]}")
+    
+    return issues
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"[ACCESSIBILITY CHECKER] WCAG Compliance Audit")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("-"*60)
+    
+    # Find HTML files
+    files = find_html_files(project_path)
+    print(f"Found {len(files)} HTML/JSX/TSX files")
+    
+    if not files:
+        output = {
+            "script": "accessibility_checker",
+            "project": str(project_path),
+            "files_checked": 0,
+            "issues_found": 0,
+            "passed": True,
+            "message": "No HTML files found"
+        }
+        print(json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    # Check each file
+    all_issues = []
+    
+    for f in files:
+        issues = check_accessibility(f)
+        if issues:
+            all_issues.append({
+                "file": str(f.name),
+                "issues": issues
+            })
+    
+    # Summary
+    print("\n" + "="*60)
+    print("ACCESSIBILITY ISSUES")
+    print("="*60)
+    
+    if all_issues:
+        for item in all_issues[:10]:
+            print(f"\n{item['file']}:")
+            for issue in item["issues"]:
+                print(f"  - {issue}")
+        
+        if len(all_issues) > 10:
+            print(f"\n... and {len(all_issues) - 10} more files with issues")
+    else:
+        print("No accessibility issues found!")
+    
+    total_issues = sum(len(item["issues"]) for item in all_issues)
+    # Accessibility issues are important but not blocking
+    passed = total_issues < 5  # Allow minor issues
+    
+    output = {
+        "script": "accessibility_checker",
+        "project": str(project_path),
+        "files_checked": len(files),
+        "files_with_issues": len(all_issues),
+        "issues_found": total_issues,
+        "passed": passed
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+    main()