agent-skill-kit 3.9.135

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

@@ -0,0 +1,407 @@
+---
+name: visual-effects
+description: Glassmorphism, neumorphism, shadow hierarchy, gradients, glow, overlays, modern CSS techniques
+title: "Visual Effects Reference"
+impact: LOW
+impactDescription: "Minor optimization or best practice"
+tags: visual, effects
+---
+
+# 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."
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [animation-guide.md](animation-guide.md) | Animation timing for effects |
+| [motion-graphics.md](motion-graphics.md) | Advanced Lottie, GSAP, 3D effects |
+| [color-system.md](color-system.md) | Color for gradients and glows |
+| [../SKILL.md](../SKILL.md) | Anti-pattern bans |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/design-system/scripts/accessibility_checker.ts

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+// @ts-nocheck
+/**
+ * Accessibility Checker v2.0.0
+ * Skill: design-system
+ *
+ * WCAG compliance audit for HTML/JSX/TSX files.
+ *
+ * Usage:
+ *   node accessibility_checker.js <project_path>
+ *   node accessibility_checker.js <project_path> --json
+ *
+ * Checks:
+ *   - Inputs without label or aria-label
+ *   - Buttons without accessible text
+ *   - Missing lang attribute on <html>
+ *   - Missing skip-to-main-content link
+ *   - onClick without keyboard handler
+ *   - Positive tabIndex values
+ *   - Autoplay media without muted
+ *   - role="button" without tabindex
+ *   - Images without alt attribute
+ *
+ * Flags:
+ *   --json     Output as JSON only
+ *   --help     Show help
+ *   --version  Show version
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { resolve, extname } from 'node:path';
+
+const VERSION = '2.0.0';
+const SKIP_DIRS = new Set(['node_modules', '.next', 'dist', 'build', '.git', '__pycache__']);
+const VALID_EXTS = new Set(['.html', '.jsx', '.tsx', '.vue']);
+const MAX_FILES = 50;
+
+const args = process.argv.slice(2);
+const jsonMode = args.includes('--json');
+const filteredArgs = args.filter(a => !a.startsWith('--'));
+
+function showHelp() {
+    console.log(`Accessibility Checker v${VERSION}
+
+Usage: node accessibility_checker.js <project_path> [options]
+
+Options:
+  --json       Output as JSON only
+  --help       Show this help
+  --version    Show version
+
+Checks: inputs, buttons, lang, skip-link, keyboard, tabindex, autoplay, role, img alt`);
+}
+
+// --- File Discovery ---
+
+async function walkFiles(dir, files = [], depth = 0) {
+    if (depth > 8 || files.length >= MAX_FILES) return files;
+
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+        if (!jsonMode) console.warn(`[WARN] Cannot read: ${dir} (${err.code})`);
+        return files;
+    }
+
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name) || files.length >= MAX_FILES) continue;
+        const fullPath = resolve(dir, entry.name);
+
+        if (entry.isDirectory()) {
+            await walkFiles(fullPath, files, depth + 1);
+        } else if (VALID_EXTS.has(extname(entry.name).toLowerCase())) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+
+// --- Checks ---
+
+async function checkAccessibility(filePath) {
+    const issues = [];
+    let content;
+
+    try {
+        content = await readFile(filePath, 'utf-8');
+    } catch (err) {
+        issues.push({ rule: 'FILE_READ', severity: 'error', message: `Cannot read: ${err.message}` });
+        return issues;
+    }
+
+    // 1. Inputs without labels
+    const inputs = content.match(/<input[^>]*>/gi) || [];
+    for (const inp of inputs) {
+        const lower = inp.toLowerCase();
+        if (lower.includes('type="hidden"') || lower.includes("type='hidden'")) continue;
+        if (!lower.includes('aria-label') && !lower.includes('aria-labelledby')) {
+            issues.push({
+                rule: 'A11Y_INPUT_NO_LABEL',
+                severity: 'error',
+                message: 'Input without aria-label or aria-labelledby',
+            });
+            break; // report once per file
+        }
+    }
+
+    // 2. Buttons without accessible text
+    const buttons = content.match(/<button[^>]*>[\s\S]*?<\/button>/gi) || [];
+    for (const btn of buttons) {
+        const lower = btn.toLowerCase();
+        if (lower.includes('aria-label') || lower.includes('aria-labelledby')) continue;
+        const text = btn.replace(/<[^>]+>/g, '').trim();
+        if (!text) {
+            issues.push({
+                rule: 'A11Y_BUTTON_NO_TEXT',
+                severity: 'error',
+                message: 'Button without accessible text or aria-label',
+            });
+            break;
+        }
+    }
+
+    // 3. Missing lang attribute
+    if (content.toLowerCase().includes('<html') && !content.toLowerCase().includes('lang=')) {
+        issues.push({
+            rule: 'A11Y_MISSING_LANG',
+            severity: 'error',
+            message: 'Missing lang attribute on <html>',
+        });
+    }
+
+    // 4. Missing skip link
+    if (content.toLowerCase().includes('<main') || content.toLowerCase().includes('<body')) {
+        if (!content.toLowerCase().includes('skip') && !content.includes('#main')) {
+            issues.push({
+                rule: 'A11Y_NO_SKIP_LINK',
+                severity: 'warning',
+                message: 'Consider adding skip-to-main-content link',
+            });
+        }
+    }
+
+    // 5. onClick without keyboard support
+    const onclickCount = (content.toLowerCase().match(/onclick=/g) || []).length;
+    const keyboardCount = (content.toLowerCase().match(/onkeydown=|onkeyup=|onkeypress=/g) || []).length;
+    if (onclickCount > 0 && keyboardCount === 0) {
+        issues.push({
+            rule: 'A11Y_NO_KEYBOARD',
+            severity: 'warning',
+            message: 'onClick without keyboard handler (onKeyDown)',
+        });
+    }
+
+    // 6. Positive tabIndex
+    if (/tabindex=["']([1-9]\d*)["']/i.test(content)) {
+        issues.push({
+            rule: 'A11Y_POSITIVE_TABINDEX',
+            severity: 'warning',
+            message: 'Avoid positive tabIndex values (use 0 or -1)',
+        });
+    }
+
+    // 7. Autoplay without muted
+    if (content.toLowerCase().includes('autoplay') && !content.toLowerCase().includes('muted')) {
+        issues.push({
+            rule: 'A11Y_AUTOPLAY_UNMUTED',
+            severity: 'error',
+            message: 'Autoplay media should be muted',
+        });
+    }
+
+    // 8. role="button" without tabindex
+    const divButtons = content.match(/<div[^>]*role=["']button["'][^>]*>/gi) || [];
+    for (const div of divButtons) {
+        if (!div.toLowerCase().includes('tabindex')) {
+            issues.push({
+                rule: 'A11Y_ROLE_NO_TABINDEX',
+                severity: 'error',
+                message: 'role="button" without tabindex',
+            });
+            break;
+        }
+    }
+
+    // 9. Images without alt
+    const images = content.match(/<img[^>]*>/gi) || [];
+    for (const img of images) {
+        if (!img.toLowerCase().includes('alt=')) {
+            issues.push({
+                rule: 'A11Y_IMG_NO_ALT',
+                severity: 'error',
+                message: 'Image without alt attribute',
+            });
+            break;
+        }
+    }
+
+    return issues;
+}
+
+// --- Main ---
+
+async function main() {
+    if (args.includes('--version')) { console.log(VERSION); return; }
+    if (args.includes('--help') || filteredArgs.length === 0) { showHelp(); return; }
+
+    const projectPath = resolve(filteredArgs[0]);
+
+    if (!jsonMode) {
+        console.log(`\n${'='.repeat(60)}`);
+        console.log(`[ACCESSIBILITY CHECKER] WCAG Compliance v${VERSION}`);
+        console.log('='.repeat(60));
+        console.log(`Project: ${projectPath}`);
+        console.log(`Time: ${new Date().toISOString()}`);
+        console.log('-'.repeat(60));
+    }
+
+    const files = await walkFiles(projectPath);
+
+    if (files.length === 0) {
+        const output = {
+            script: 'accessibility_checker', version: VERSION,
+            project: projectPath, files_checked: 0,
+            errors: 0, warnings: 0, passed: true,
+            message: 'No HTML/JSX/TSX files found',
+        };
+        console.log(jsonMode ? JSON.stringify(output, null, 2) : 'No files found.\n' + JSON.stringify(output, null, 2));
+        return;
+    }
+
+    if (!jsonMode) console.log(`Found ${files.length} file(s)`);
+
+    const allResults = [];
+
+    for (const f of files) {
+        const issues = await checkAccessibility(f);
+        if (issues.length > 0) {
+            allResults.push({ file: f.split(/[/\\]/).pop(), issues });
+        }
+    }
+
+    const totalErrors = allResults.reduce(
+        (sum, r) => sum + r.issues.filter(i => i.severity === 'error').length, 0,
+    );
+    const totalWarnings = allResults.reduce(
+        (sum, r) => sum + r.issues.filter(i => i.severity === 'warning').length, 0,
+    );
+
+    if (!jsonMode) {
+        console.log('\n' + '='.repeat(60));
+        if (allResults.length > 0) {
+            console.log('ACCESSIBILITY ISSUES');
+            console.log('='.repeat(60));
+            for (const item of allResults.slice(0, 10)) {
+                console.log(`\n${item.file}:`);
+                for (const issue of item.issues) {
+                    const icon = issue.severity === 'error' ? '[ERROR]' : '[WARN]';
+                    console.log(`  ${icon} ${issue.rule}: ${issue.message}`);
+                }
+            }
+            if (allResults.length > 10) {
+                console.log(`\n... and ${allResults.length - 10} more files`);
+            }
+        } else {
+            console.log('No accessibility issues found!');
+        }
+        console.log(`\nRESULT: ${totalErrors === 0 ? 'PASSED' : 'FAILED'} | ${totalErrors} errors, ${totalWarnings} warnings`);
+        console.log('='.repeat(60));
+    }
+
+    const output = {
+        script: 'accessibility_checker',
+        version: VERSION,
+        project: projectPath,
+        files_checked: files.length,
+        files_with_issues: allResults.length,
+        errors: totalErrors,
+        warnings: totalWarnings,
+        passed: totalErrors === 0,
+        results: allResults,
+    };
+
+    console.log('\n' + JSON.stringify(output, null, 2));
+    process.exit(totalErrors === 0 ? 0 : 1);
+}
+
+main().catch(err => {
+    console.error(jsonMode ? JSON.stringify({ status: 'error', message: err.message }) : `[FATAL] ${err.message}`);
+    process.exit(1);
+});